常见问题

基本问题

CodePilot 是什么？

CodePilot 是 Claude Code 的桌面工作区。它在 Claude Code CLI 的基础上提供图形界面，整合了多服务商管理、MCP 插件、技能、消息桥接和助理工作区等功能。基于 Electron + Next.js 构建。

CodePilot 和 Claude Code CLI 是什么关系？

CodePilot 是 Claude Code CLI 的图形前端。它通过 Claude Agent SDK 调用 Claude Code CLI 的能力，同时在上层添加了 GUI 专属的功能（多服务商切换、桥接、素材库等）。使用 CodePilot 需要先安装 Claude Code CLI。

CodePilot 免费吗？

CodePilot 本身开源且免费。你需要自备 API 密钥（来自 Anthropic、OpenRouter 或其他支持的服务商）。API 调用费用由服务商收取。

支持哪些操作系统？

• macOS 12+（Apple Silicon 和 Intel）
• Windows 10+（64 位）

安装与配置

首次启动提示找不到 Node.js

CodePilot 需要 Node.js 18+。首次启动的设置向导会检测并提供自动安装。你也可以从 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
• OpenRouter — openrouter.ai
• 智谱 GLM — open.bigmodel.cn
• Kimi — platform.moonshot.cn
• 火山引擎 — console.volcengine.com
• 阿里云百炼 — dashscope.console.aliyun.com

可以使用本地大模型吗？

可以。任何提供 OpenAI 兼容 API 的本地服务（Ollama、LM Studio、vLLM 等）都可以作为自定义 API 服务商接入。在服务商设置中选择自定义 API，填写本地服务的 URL。

macOS 提示"无法验证开发者"

前往 系统设置 > 隐私与安全性，找到 CodePilot 相关提示，点击"仍要打开"。

使用问题

代码 / 计划 / 问答三种模式有什么区别？

• 代码 — Claude 可以读写文件、执行命令，适合日常开发
• 计划 — Claude 只分析方案不执行操作，适合规划阶段
• 问答 — Claude 只回答问题不使用工具，适合纯问答

如何在手机上与 Claude 对话？

使用 消息桥接 功能，将 CodePilot 连接到 Telegram、Discord、飞书或 QQ。桌面端保持运行即可从手机上与 Claude 对话。

Claude 没有响应怎么办？

1. 检查 API 密钥是否有效且有余额
2. 检查网络连接
3. 尝试切换到其他服务商
4. 查看 MCP 页面是否有服务器报错
5. 重启 CodePilot

如何导入 CLI 的对话历史？

在对话页面使用导入功能，可以搜索并导入 Claude Code CLI 中的历史会话。

反馈与支持

如何报告 Bug？

在 GitHub Issues 提交，请包含：

• 操作系统和 CodePilot 版本
• 复现步骤
• 相关错误日志