跳到正文
OcHub

配置 Claude Code 与 Claude Desktop

选择正确的鉴权变量、模型映射与应用专属设置,并验证 Claude 请求。

更新于 查看 Markdown
For humans

Claude Code 与 Claude Desktop 都采用“当前连接切换”模式:切换后,工具的实时配置只指向 当前连接。两者共享 Claude 生态,但 OcHub 能管理的范围不同。

能力 Claude Code Claude Desktop
直接连接与官方登录 支持 支持
模型供应商 支持 支持
MCP 管理 支持 不支持
技能分发 支持 不支持
会话读取 支持 不作为主要会话来源

如果主要在终端中编程,先配置 Claude Code;如果只需要桌面客户端使用第三方接口,再单独配置 Claude Desktop。两个应用的连接不会自动互相复制。

配置 Claude Code 直接连接

  1. 打开 Claude Code。 在左侧应用列表中选择 Claude Code,点击“新增连接”。

  2. 填写端点。 Base URL 填写供应商给出的 Anthropic 兼容地址。Claude Code 会在地址后请求 /v1/messages,不要把完整的消息接口重复拼到普通 Base URL 中。

  3. 选择鉴权变量。 第三方模型供应商通常选择 ANTHROPIC_AUTH_TOKEN(Bearer);Anthropic 官方密钥通常选择 ANTHROPIC_API_KEY(x-api-key)。以供应商文档要求的请求头为准。

  4. 填写 API Key。 OcHub 只会把密钥写入上一步选中的变量,并移除另一种互斥鉴权变量,避免同一请求携带两套凭据。

  5. 先配置一个模型。 “默认模型”是各角色没有单独映射时的回退模型。第一次连接只填一个确认可用的模型即可。

  6. 查看写入预览。 打开“配置文件”,确认目标是 Claude 配置目录中的 settings.json,且未意外覆盖 hooks、permissions、statusline 等原有字段。

  7. 保存草稿或应用。 “保存到 OcHub”仅保留编辑草稿;准备完成后点击“应用到 Claude Code”写入目标配置。

  8. 重开终端验证。 退出正在运行的 Claude Code 会话,新开终端发起一条短请求,再到 OcHub 的“用量”或目标供应商后台核对请求。

逐步界面示意点击画面放大,左右方向键切换步骤;蓝色描边是当前要对照的位置。
1
STEP 01打开 Claude Code 并添加连接
2
STEP 02填写 Anthropic 兼容地址
3
STEP 03选择鉴权变量
4
STEP 04填写 API Key
5
STEP 05先使用一个模型
6
STEP 06检查 settings.json
7
STEP 07保存草稿或应用
8
STEP 08在新终端验证

配置角色模型

Claude Code 可以为不同角色指定模型。OcHub 会把它们写入对应的 ANTHROPIC_DEFAULT_*_MODEL 字段。

角色 典型用途 未填写时
sonnet 日常编程与综合任务 回退到“默认模型”
opus 高复杂度推理 回退到“默认模型”
haiku 快速、低成本任务 回退到“默认模型”
fable 工具支持时的额外角色 回退到“默认模型”

每行可以填写模型 ID、显示名和 1M 上下文开关。1M 开关会给模型 ID 追加 [1M] 标记; haiku 不支持这一标记。只有上游明确支持相应模型和上下文窗口时才开启,否则会得到 “模型不存在”或参数不受支持的错误。

一个稳妥的配置顺序是:

  1. 只设置默认模型并完成真实请求。
  2. 为 sonnet 添加同一个已验证模型。
  3. 再逐个添加 opus、haiku 或 fable。
  4. 每次只改一行,避免模型名与鉴权问题同时出现。

使用官方登录

Claude Code 已经完成官方账号登录时,可以新增“官方登录”连接。它不会写入第三方 Base URL 或 API Key,而是沿用 Claude Code 自己的登录状态。

适合在以下情况使用:

  • 在订阅账号与第三方 API 之间来回切换。
  • 暂时排除第三方地址、密钥或额度问题。
  • 希望保留 Claude Code 原生登录能力。

从第三方切回官方登录后,重开 Claude Code 会话。如果仍然请求旧地址,检查终端环境变量是否 覆盖了 settings.json;可到高级工具 → 环境变量冲突扫描。

管理 MCP 与技能

Claude Code 支持 OcHub 的 MCP 和技能分发。

MCP

  1. 在MCP 服务器中从 Claude 导入已有配置,或新增服务器。
  2. 打开该服务器卡片上的 Claude Code 开关。
  3. 点击“同步到应用”。
  4. 重启 Claude Code,再检查服务器是否可见。

MCP 配置通常从 Claude 配置目录推导到相邻的 ~/.claude.json。如果使用自定义目录,OcHub 会按目录名推导相邻 JSON;同步前应查看实际目标路径。

技能

在技能中安装技能时选择 Claude Code,或在已安装卡片上打开 Claude Code 开关。技能 分发依赖本机 skills CLI;安装或更新失败时先到高级工具 → CLI 工具维护检查版本和 PATH。

配置 Claude Desktop

Claude Desktop 的连接与 Claude Code 分开管理:

  1. 打开 Claude Desktop 应用页。
  2. 新增第三方连接,填写 Base URL 与 API Key;或选择官方登录。
  3. 展开写入预览,确认目标位于 Claude Desktop 配置目录。
  4. 检查后点击“应用到 Claude Desktop”;仅保存草稿不会改变客户端。
  5. 完全退出 Claude Desktop 后重新打开,发起一条短请求。

Claude Desktop 不参与 OcHub 的 MCP 和技能管理。需要配置 Claude Desktop 自己的扩展能力 时,请使用客户端原生设置,不要把 Claude Code 的同步结果当作 Desktop 配置。

自定义配置目录

Claude Code 默认使用 ~/.claude。在应用页右上角进入应用设置可以改成其他目录。适合:

  • 同一台电脑维护工作与个人两套配置。
  • 配置目录通过挂载盘或受管目录提供。
  • 测试一套配置但不想覆盖默认目录。

保存目录后重启 OcHub 和 Claude Code,并重新打开写入预览。目录设置会影响配置、MCP 和 会话读取位置,不会自动把旧目录内容搬到新目录。

常见问题

现象 优先检查 处理
返回 401 / 未授权 鉴权变量、API Key 核对 Bearer 与 x-api-key 要求
返回 404 Base URL 是否包含完整 /v1/messages 改回供应商要求的基础地址
提示模型不存在 默认模型、角色映射 使用供应商模型列表中的真实 ID
切换后仍请求旧地址 旧终端、环境变量 重开终端并扫描环境变量冲突
MCP 没出现 Claude 开关、配置目录、JSON 重新同步并重启 Claude Code
原生设置丢失风险 写入预览、配置漂移提示 取消写入,先备份并比较差异

最后可用以下清单验收:

  • Claude Code 能完成一条真实对话。
  • 用量或供应商后台能看到正确模型。
  • 切换到官方登录后不再写入第三方密钥。
  • 需要的 MCP 与技能只分发到预期应用。
  • 自定义目录与写入预览中的路径一致。

继续阅读管理连接了解复制和配置漂移,或阅读 管理 MCP 与技能完成共享能力配置。配置优先级、网关兼容、指令加载与 MCP 作用域见 Claude Code 进阶与易踩坑。

Navigation

Type to search…

↑↓ navigate↵ selectEsc close