--- title: "将 Claude Code 接入 XiuRouter" description: "为 Claude Desktop Code、Claude Code CLI 或 VS Code 扩展配置 XiuRouter Messages 网关。" image: "https://docs.xiu.ai/og.png" --- > XiuAI 文档索引 > 完整文档索引:https://docs.xiu.ai/llms.txt > 阅读前先通过索引确认当前可用页面。 # 将 Claude Code 接入 XiuRouter Claude Desktop Code、Claude Code CLI 和 VS Code 扩展都能使用 XiuRouter Messages 网关,但配置入口不同。已经安装 Claude Code 时,不需要重新登录或重装。 ## 先选使用端 | 使用端 | 配置入口 | 模型 | | --- | --- | --- | | Claude Desktop Code | Developer → Configure Third-Party Inference | 从网关 `/v1/models` 选择 | | Claude Code CLI | 启动进程的终端环境 | 用 `/model` 选择带 `From gateway` 的模型 | | VS Code 扩展 | 用户级 `claudeCode.environmentVariables` | 重新加载窗口后在 `/model` 中选择 | ## 选择配置方式 - 首次配置:按使用端添加 Gateway 连接。 - 替换已有:先记录原 provider、地址和凭据来源,再修改对应入口。 - 对话协助:不提供。当前对话不能修改启动它的父进程环境变量,API Key 也不应进入模型上下文。 > **先跑真实小任务** > > `count_tokens` 缺失本身不是阻断项,但 Claude Code 还依赖流式响应,并会随版本发送新的 > `anthropic-beta` 和请求字段。先在非关键项目完成真实小任务,不要把 Messages > 请求成功当作完整兼容证明。 ## 前置条件 - 使用 CLI 时,`claude --version` 可以正常输出版本。 - 已创建一把只给 Claude Code 使用的 XiuRouter API Key。 - XiuRouter 当前能返回至少一个 Claude 模型。 ## Claude Desktop Code 1. 打开 Help → Troubleshooting → Enable Developer Mode,等待应用重启。 2. 打开 Developer → Configure Third-Party Inference。 3. 填写: ```text Inference provider: Gateway Gateway base URL: https://router-api.xiu.ai Gateway API key: YOUR_XIUROUTER_API_KEY Credential kind: Static API key Gateway auth scheme: Bearer ``` 4. 完全退出 Claude Desktop 后重开。 5. 在 Code 中选择 XiuRouter 返回的 Claude 模型,再完成一个短任务。 替换已有连接时,先记下原 provider、地址和认证方式。Gateway 模式不提供 Cloud、SSH 或 Remote Control。 ## Claude Code CLI 在启动 Claude Code 的同一终端中设置: ```bash export ANTHROPIC_BASE_URL="https://router-api.xiu.ai" export ANTHROPIC_AUTH_TOKEN="YOUR_XIUROUTER_API_KEY" export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1" ``` Base URL 不要加 `/v1`。Claude Code 会自己追加 `/v1/messages`。这里使用 `ANTHROPIC_AUTH_TOKEN`,由客户端发送 Bearer Token;XiuRouter Messages 路由接受该方式。 Windows PowerShell: ```powershell $env:ANTHROPIC_BASE_URL = "https://router-api.xiu.ai" $env:ANTHROPIC_AUTH_TOKEN = "YOUR_XIUROUTER_API_KEY" $env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY = "1" ``` 运行 `claude`,再执行 `/model`。选择带 `From gateway` 的模型,然后运行 `/status`,确认 Base URL 和凭据来源。 替换已有连接时,先在原会话运行 `/status`,再到独立终端设置上面的变量。原终端和用户级设置保持不变。 ## VS Code 扩展 运行 Preferences: Open User Settings (JSON),把下面配置合并到用户设置。不要写到工作区设置。 ```json { "claudeCode.environmentVariables": [ { "name": "ANTHROPIC_BASE_URL", "value": "https://router-api.xiu.ai" }, { "name": "ANTHROPIC_AUTH_TOKEN", "value": "YOUR_XIUROUTER_API_KEY" }, { "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" } ] } ``` 运行 Developer: Reload Window。在 Claude Code 中执行 `/status`,再完成一个短任务。 替换已有连接时,先备份原 `claudeCode.environmentVariables`。真实 Key 只写入本机用户设置。 ## 验证 完成一个短任务,再到 XiuRouter 控制台“检查实际请求”核对同一 Key、`/v1/messages` 和成功状态。 日志中出现 `count_tokens` 的 `404` 时,不要轮换 Key 或反复充值。Claude Code 应回退到 Messages;继续确认任务是否完成。 ## 常见失败 | 现象 | 处理 | | --- | --- | | 请求发到 Anthropic 官方地址 | 检查当前使用端的 Gateway 配置是否生效 | | `/status` 没有 XiuRouter 地址 | 完全退出客户端,按对应使用端重新加载或重启 | | 路径变成 `/v1/v1/messages` | 把 `ANTHROPIC_BASE_URL` 改为不含 `/v1` 的地址 | | `401` | 确认 `ANTHROPIC_AUTH_TOKEN` 是 XiuRouter API Key | | `404` 且路径含 `count_tokens` | 这是可选端点;确认 Claude Code 是否继续通过 Messages 完成任务 | | `count_tokens` 回退后任务仍停止 | 记录随后发送的 Messages 请求、响应和客户端版本,再定位真正失败字段 | | 普通回复成功,工具任务失败 | 记录请求路径、模型和 `anthropic-beta`;不要扩大到生产任务 | ## 回滚 - Claude Desktop:在 Third-Party Inference 中恢复原连接,或关闭第三方推理。 - CLI:取消三个网关环境变量,再重新启动 Claude Code。 - VS Code:恢复原 `claudeCode.environmentVariables`,再重新加载窗口。 回滚后运行 `/status`,确认已恢复原连接。 ## 来源与核对日期 内容核对于 2026-08-31。`/v1/messages/count_tokens` 当前没有专用路由,但 Claude Code 允许回退;请用真实小任务和“检查实际请求”确认最终兼容性。 源文件:https://docs.xiu.ai/router/integrations/claude-code/index.mdx