okooooooo/CodePilot
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update website docs with Setup Center and Claude Code conflict guide

Browse Source 
- installation.mdx: expand "First Launch" into detailed Setup Center walkthrough
  covering CLI detection, provider configuration, and project directory setup
- installation.mdx: add "Claude Code Conflicts" section with detection logic,
  uninstall commands per install type, and recommended installation method
- faq.mdx: add troubleshooting entries for CLI not detected, multi-version
  conflicts, and Setup Center auto-open behavior
- providers.mdx: mention ANTHROPIC_AUTH_TOKEN alongside API_KEY for env detection

All changes in both English and Chinese versions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
7418andClaude Opus 4.6 committed 2026-03-13 15:24:31 +08:00
1 parent 8154130035
commit 8372a3f548
6 files changed
+196 -12
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

apps/site/content/docs/en/faq.mdx
+31
View File
@@ -30,6 +30,37 @@ CodePilot is open source and free to use. You need your own API key from a suppo
CodePilot requires Node.js 18+. The first-launch setup wizard will detect this and offer automatic installation. You can also install manually from [nodejs.org](https://nodejs.org).
### Claude Code CLI not detected
If the Setup Center shows "Claude Code not found":
1. Open a terminal and run `claude --version` to confirm it's installed
2. If installed but not detected, the binary may not be in CodePilot's PATH. Try launching CodePilot from the terminal (`open /Applications/CodePilot.app` on macOS) so it inherits your shell environment
3. If not installed, follow the Setup Center's instructions or run `curl -fsSL https://claude.ai/install.sh | bash`
### Multiple Claude Code installations (conflicts)
If you see a "Multiple installations detected" warning in the Setup Center, your system has more than one Claude Code binary. This commonly happens when:
- You installed via npm **and** the native installer
- An old npm installation was left behind after switching to native
**To resolve:**
1. Open the Setup Center (Settings > General > Initial Setup Guide)
2. Click **View Cleanup** on the Claude Code card
3. Run the provided uninstall commands for each extra installation:
- npm: `npm uninstall -g @anthropic-ai/claude-code`
- Bun: `bun remove -g @anthropic-ai/claude-code`
- Homebrew: `brew uninstall --cask claude-code`
4. Click **Re-detect** to verify
The native installer is recommended — it's independent of Node.js/npm and receives the fastest updates.
### Setup Center keeps appearing on launch
The Setup Center opens automatically until all three steps (CLI, provider, project directory) are completed or skipped. To dismiss it permanently, click **Skip and Enter** in the top-right corner. You can reopen it later from Settings > General > Initial Setup Guide.
### How do I get an API key?
- **Anthropic** — [console.anthropic.com](https://console.anthropic.com)
apps/site/content/docs/en/installation.mdx
+66 -5
View File
@@ -36,13 +36,74 @@ Download the latest release for your platform from [GitHub Releases](https://git
2. Run the installer and follow the prompts
3. CodePilot will be available in your Start menu
## First Launch
## First Launch & Setup Center
On first launch, CodePilot will:
On first launch, CodePilot automatically opens the **Setup Center** — a guided setup overlay that walks you through three prerequisites:
1. **Check for Node.js** — if not found, it will offer to install it automatically
2. **Check for Claude Code CLI** — if not found, it will install it via npm
3. **Open the Setup Wizard** — configure your API provider and preferences
### 1. Claude Code CLI Detection
The Setup Center checks whether the Claude Code CLI is installed and accessible.
- **Detected** — Shows version, installation type (native/npm/bun/homebrew), and binary path. You're good to go.
- **Not found** — Provides the install command for your platform:
- macOS/Linux: `curl -fsSL https://claude.ai/install.sh | bash`
- Windows: `irm https://claude.ai/install.ps1 | iex`
- After installing, click **Re-detect** to verify.
- **Multiple installations detected** — If CodePilot finds more than one Claude Code binary (e.g., one installed via npm and another natively), it shows a warning with cleanup instructions. See [Claude Code Conflicts](#claude-code-conflicts) below.
- **Git not found (Windows)** — Claude Code requires Git. The Setup Center provides step-by-step instructions for installing Git for Windows.
You can **skip** any step and continue — the app will still work if the CLI is available in your PATH.
### 2. API Provider Configuration
The Setup Center checks for available API credentials in three locations:
1. **Database providers** — Any providers you've manually configured in Settings
2. **Environment variables** — `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` set in your shell
3. **App settings** — Legacy `anthropic_auth_token` stored from previous versions
If credentials are found, the card is automatically marked as complete. Otherwise, you can click **Add Provider** to go to Settings, or **Skip** to configure later.
> **Note:** Skipping the provider step doesn't mean you have a working provider. If you try to send a message without any configured provider, CodePilot will prompt you to set one up.
### 3. Default Project Directory
Select a default working directory for new conversations. The Setup Center shows your recent projects (if any) as quick-select chips, or you can browse for a folder.
This directory is used as the fallback when creating new conversations. You can always change it per-conversation.
### Reopening the Setup Center
You can reopen the Setup Center anytime from **Settings > General > Initial Setup Guide**.
## Claude Code Conflicts
If multiple Claude Code installations exist on your system, they can cause version conflicts, unexpected behavior, or permission errors. Common scenarios:
- Installed via `npm install -g` **and** the native installer
- Old npm installation left behind after switching to the native installer
- Multiple package managers (npm + homebrew, npm + bun)
### How CodePilot detects conflicts
When the Setup Center (or the connection status indicator) detects Claude Code, it also scans for other installations. If multiple are found, it shows:
1. **Which binary is currently in use** — path, version, and installation type
2. **Other installations found** — each with its path and type
3. **Uninstall commands** — specific to each installation type:
| Installation Type | Uninstall Command |
|---|---|
| npm | `npm uninstall -g @anthropic-ai/claude-code` |
| Bun | `bun remove -g @anthropic-ai/claude-code` |
| Homebrew | `brew uninstall --cask claude-code` |
| Native | Remove the binary at the displayed path |
After removing the conflicting installations, click **Re-detect** to verify only one remains.
### Recommended installation method
The **native installer** (`curl -fsSL https://claude.ai/install.sh | bash`) is recommended. It doesn't depend on Node.js/npm being in your PATH, avoids version conflicts with other npm packages, and receives the fastest updates.
## Configuring an API Provider
apps/site/content/docs/en/providers.mdx
+1 -1
View File
@@ -13,7 +13,7 @@ CodePilot has two ways to obtain API credentials:
### 1. CLI Environment Authentication (Auto-Detected)
If you have the `ANTHROPIC_API_KEY` environment variable set in your shell, CodePilot **automatically detects** it on startup and uses it as a built-in provider.
If you have the `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` environment variable set in your shell, CodePilot **automatically detects** it on startup and uses it as a built-in provider. The Setup Center also checks for these credentials and marks the provider step as complete if found.
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
apps/site/content/docs/zh/faq.mdx
+31
View File
@@ -30,6 +30,37 @@ CodePilot 本身开源且免费。你需要自备 API 密钥（来自 Anthropic
CodePilot 需要 Node.js 18+。首次启动的设置向导会检测并提供自动安装。你也可以从 [nodejs.org](https://nodejs.org) 手动安装。
### Claude Code CLI 未被检测到
如果设置中心显示"未找到 Claude Code"：
1. 打开终端运行 `claude --version` 确认是否已安装
2. 如果已安装但未被检测到，可能是二进制不在 CodePilot 的 PATH 中。尝试从终端启动 CodePilot（macOS 上运行 `open /Applications/CodePilot.app`），这样可以继承 shell 环境变量
3. 如果未安装，按照设置中心的指引操作，或运行 `curl -fsSL https://claude.ai/install.sh | bash`
### Claude Code 多版本冲突
如果设置中心显示"检测到多个安装版本"的警告，说明系统中存在多个 Claude Code 二进制文件。常见原因：
- 通过 npm **和**原生安装器分别安装了
- 切换到原生安装后遗留了旧的 npm 安装
**解决方法：**
1. 打开设置中心（设置 > 通用 > 首次设置引导）
2. 在 Claude Code 卡片上点击**查看清理方式**
3. 按照提供的命令卸载多余的安装：
- npm：`npm uninstall -g @anthropic-ai/claude-code`
- Bun：`bun remove -g @anthropic-ai/claude-code`
- Homebrew：`brew uninstall --cask claude-code`
4. 点击**重新检测**验证
推荐使用原生安装器 — 不依赖 Node.js/npm，更新最快。
### 设置中心每次启动都弹出
设置中心会在三个步骤（CLI、服务商、项目目录）全部完成或跳过前自动弹出。要永久关闭，点击右上角的**跳过并进入**。之后可以在设置 > 通用 > 首次设置引导中重新打开。
### 如何获取 API 密钥？
- **Anthropic** — [console.anthropic.com](https://console.anthropic.com)
apps/site/content/docs/zh/installation.mdx
+66 -5
View File
@@ -36,13 +36,74 @@ description: 如何在你的系统上安装和配置 CodePilot。
2. 运行安装程序并按提示操作
3. CodePilot 将出现在开始菜单中
## 首次启动
## 首次启动与设置中心
首次启动时，CodePilot 会：
首次启动时，CodePilot 会自动打开**设置中心** — 一个引导式设置面板，帮你完成三项前置配置：
1. **检查 Node.js** — 如未找到，会提供自动安装
2. **检查 Claude Code CLI** — 如未找到，会通过 npm 安装
3. **打开引导设置** — 配置 API 服务商和偏好设置
### 1. Claude Code CLI 检测
设置中心会检查 Claude Code CLI 是否已安装并可访问。
- **已检测到** — 显示版本号、安装类型（native/npm/bun/homebrew）和二进制路径，可以直接使用。
- **未找到** — 提供对应平台的安装命令：
- macOS/Linux：`curl -fsSL https://claude.ai/install.sh | bash`
- Windows：`irm https://claude.ai/install.ps1 | iex`
- 安装完成后点击**重新检测**验证。
- **检测到多个安装版本** — 如果系统中存在多个 Claude Code 二进制文件（如 npm 安装和原生安装并存），会显示警告及清理指引。详见下方 [Claude Code 冲突处理](#claude-code-冲突处理)。
- **未找到 Git（Windows）** — Claude Code 依赖 Git。设置中心会提供 Git for Windows 的安装步骤。
每一步都可以**跳过** — 只要 CLI 在 PATH 中可用，应用就能正常工作。
### 2. API 服务商配置
设置中心会从三个位置检查可用的 API 凭据：
1. **数据库服务商** — 在设置中手动配置的服务商
2. **环境变量** — shell 中设置的 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`
3. **应用设置** — 旧版本遗留的 `anthropic_auth_token`
如果检测到凭据，卡片会自动标记为已完成。否则你可以点击**添加服务商**跳转到设置页，或点击**跳过**稍后配置。
> **注意：** 跳过服务商配置不代表你已经有可用的服务商。如果在没有配置服务商的情况下尝试发送消息，CodePilot 会提示你先完成配置。
### 3. 默认项目目录
选择新会话的默认工作目录。设置中心会显示你的最近项目（如果有）作为快速选择，也可以浏览文件夹手动选择。
该目录在创建新会话时作为默认值。你随时可以在对话中切换。
### 重新打开设置中心
可以随时从 **设置 > 通用 > 首次设置引导** 重新打开设置中心。
## Claude Code 冲突处理
如果系统中存在多个 Claude Code 安装，可能会导致版本冲突、异常行为或权限错误。常见场景：
- 通过 `npm install -g` 和原生安装器分别安装过
- 切换到原生安装后遗留了旧的 npm 安装
- 使用了多个包管理器（npm + homebrew、npm + bun）
### CodePilot 如何检测冲突
设置中心（或连接状态指示器）检测到 Claude Code 时，也会扫描是否存在其他安装。如果发现多个，会显示：
1. **当前使用的二进制** — 路径、版本号和安装类型
2. **其他发现的安装** — 各自的路径和类型
3. **卸载命令** — 根据安装类型给出：
| 安装类型 | 卸载命令 |
|----------|----------|
| npm | `npm uninstall -g @anthropic-ai/claude-code` |
| Bun | `bun remove -g @anthropic-ai/claude-code` |
| Homebrew | `brew uninstall --cask claude-code` |
| 原生安装 | 删除显示路径下的二进制文件 |
清理完成后点击**重新检测**，确认只剩一个安装。
### 推荐安装方式
推荐使用**原生安装器**（`curl -fsSL https://claude.ai/install.sh | bash`）。它不依赖 PATH 中的 Node.js/npm，避免与其他 npm 包的版本冲突，且更新速度最快。
## 配置 API 服务商
apps/site/content/docs/zh/providers.mdx
+1 -1
View File
@@ -13,7 +13,7 @@ CodePilot 有两种获取 API 凭据的途径：
### 1. CLI 环境认证（自动检测）
如果你在 shell 环境中设置了 `ANTHROPIC_API_KEY` 环境变量，CodePilot 启动时会**自动检测**并作为内置服务商使用。
如果你在 shell 环境中设置了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 环境变量，CodePilot 启动时会**自动检测**并作为内置服务商使用。设置中心也会检查这些凭据，如果检测到会自动将服务商步骤标记为已完成。
```bash
export ANTHROPIC_API_KEY="sk-ant-..."