---
title: "配置 Claude Code 与 Claude Desktop"
description: "选择正确的鉴权变量、模型映射与应用专属设置，并验证 Claude 请求。"
version: "zh"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ochub.org/zh/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置 Claude Code 与 Claude Desktop

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

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

如果主要在终端中编程，先配置 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 的“用量”或目标供应商后台核对请求。

> **先判断鉴权头，再排查密钥**
>
> 同一个密钥放进错误的变量时，常见结果是 `401` 或供应商提示缺少 Authorization / x-api-key。
> 遇到鉴权失败，先核对“鉴权变量”，不要立即生成新密钥。

## 配置角色模型

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 插件集成

Claude Code 的**应用设置**提供“Claude 插件集成”。开启后，OcHub 可以让技能和 MCP 功能
写入 Claude Code 插件相关配置。关闭它适合需要完全手工维护 Claude 插件配置的环境，但会
限制 OcHub 对相关功能的同步。

“跳过 Claude 引导”会标记 MCP 引导已经完成。如果要重新查看官方引导，可在**高级工具**中
选择“恢复 Claude 引导”。

## 配置 Claude Desktop

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

1. 打开 **Claude Desktop** 应用页。
2. 新增第三方连接，填写 Base URL 与 API Key；或选择官方登录。
3. 展开写入预览，确认目标位于 Claude Desktop 配置目录。
4. 保存并切换。
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 与技能只分发到预期应用。
- 自定义目录与写入预览中的路径一致。

继续阅读[管理连接](/zh/guides/providers)了解复制和配置漂移，或阅读
[管理 MCP 与技能](/zh/guides/mcp-skills)完成共享能力配置。配置优先级、网关兼容、指令加载与
MCP 作用域见 [Claude Code 进阶与易踩坑](/zh/claude/advanced)。

Source: https://docs.ochub.org/zh/claude/configure/index.mdx