前言

Claude Code 是 Anthropic 推出的 AI 编程工具。在用户授权后，它可以读取项目文件、修改代码、执行命令和运行测试。

在企业统一出口、开发测试或模型服务集中管理等场景中，开发者可能需要将 Claude Code 连接到兼容 Anthropic Messages 协议的自定义 API 地址。本文集中说明以下技术问题：

• Claude Code CLI 如何读取用户级配置；
• 如何正确合并 settings.json，避免覆盖原有设置；
• Claude App 桌面端如何填写 Gateway 参数；
• VS Code 扩展如何传递环境变量；
• 401、404、模型不存在和配置未生效如何排查；
• 如何降低 API Key 和源码泄露风险。

本文使用三个通用占位符：

<ANTHROPIC_COMPATIBLE_BASE_URL>
<API_KEY>
<MODEL_ID>

请根据自己有权使用的服务填写实际值。第三方网关会参与请求转发，使用前应确认服务条款、数据处理方式和所在组织的安全要求。

---

一、理解请求链路

配置自定义 API 地址后的请求链路如下：

本地项目
   ↓
Claude Code CLI / Claude App / VS Code 扩展
   ↓  Anthropic Messages 兼容协议
自定义 API 网关
   ↓
网关提供的模型

Claude Code 客户端仍运行在本机，本地文件读取、代码修改和命令执行由客户端发起。但发送给模型的提示词、上下文以及必要的代码片段会经过所配置的网关，因此不能把“客户端在本地运行”理解为“所有数据都只保留在本地”。

接入前至少需要确认：

参数	含义	常见错误
Base URL	Anthropic 兼容接口的基础地址	错加 /v1、多写路径、末尾空格
API Key	网关签发的访问密钥	Key 失效、复制不完整、包含多余引号
Model ID	网关实际支持的模型标识	使用展示名称代替真实 ID

---

二、安装 Claude Code CLI

建议优先参考 Anthropic 官方安装文档选择适合当前系统的安装方式。

macOS、Linux 或 WSL：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

Windows 也可以使用 WinGet：

winget install Anthropic.ClaudeCode

如果已经安装 Node.js 18 或更高版本，也可以使用 npm：

npm install -g @anthropic-ai/claude-code@latest

安装后检查版本和运行环境：

claude --version
claude doctor

图 1：Claude Code CLI 完成安装并通过版本检查。

如果出现 command not found，先关闭并重新打开终端，再检查安装目录是否已经加入 PATH。不要在同一台机器上同时保留多套来源不同的 Claude Code，以免版本和配置文件不一致。

---

三、使用 settings.json 配置 CLI

1. 配置文件位置

Claude Code 用户级配置文件位于：

操作系统	配置文件路径
macOS / Linux / WSL	~/.claude/settings.json
Windows	%USERPROFILE%\.claude\settings.json

macOS、Linux 或 WSL：

mkdir -p ~/.claude
nano ~/.claude/settings.json

如果已安装 VS Code：

code ~/.claude/settings.json

Windows PowerShell：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude"
notepad "$env:USERPROFILE\.claude\settings.json"

用户级配置会影响当前用户启动的多个项目。项目目录中的 .claude/settings.json 属于项目级配置，不建议把真实 API Key 写进去，因为它可能被提交到 Git。

2. 空文件的完整配置

如果 settings.json 是空文件，可以写入：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "<API_KEY>",
    "ANTHROPIC_BASE_URL": "<ANTHROPIC_COMPATIBLE_BASE_URL>",
    "ANTHROPIC_MODEL": "<MODEL_ID>"
  }
}

三个字段分别表示：

• ANTHROPIC_AUTH_TOKEN：网关访问密钥；
• ANTHROPIC_BASE_URL：Anthropic Messages 兼容地址；
• ANTHROPIC_MODEL：当前 Key 可以访问的真实模型 ID。

3. 合并已有配置

如果文件中已经有权限、Hook 或其他配置，不要覆盖整个文件。只需要把 env 合并到最外层 JSON 对象：

{
  "permissions": {
    "defaultMode": "default"
  },
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "<API_KEY>",
    "ANTHROPIC_BASE_URL": "<ANTHROPIC_COMPATIBLE_BASE_URL>",
    "ANTHROPIC_MODEL": "<MODEL_ID>"
  }
}

常见 JSON 格式问题包括：

• 使用中文引号或中文逗号；
• 两个顶层字段之间漏写逗号；
• 最后一个字段后多写逗号；
• 在标准 JSON 中加入 // 注释；
• 把两个完整的 { ... } 对象直接拼接在一起。

4. 保存前检查 JSON

macOS、Linux 或 WSL 可以运行：

python3 -m json.tool ~/.claude/settings.json

格式正确时，命令会输出格式化后的 JSON；格式错误时会提示大致行列位置。

Windows PowerShell 可以运行：

Get-Content "$env:USERPROFILE\.claude\settings.json" -Raw | ConvertFrom-Json

5. 启动并进行只读验证

保存配置后，退出原有 Claude Code 会话，进入测试项目：

cd /path/to/your-project
claude

第一次建议使用只读请求：

请介绍一下自己

能够正常返回，说明客户端、Base URL、API Key 和 Model ID 已经生效。

6. 恢复默认连接

不再使用自定义 API 地址时，可以删除：

ANTHROPIC_AUTH_TOKEN
ANTHROPIC_BASE_URL
ANTHROPIC_MODEL

如果 env 中没有其他配置，可以删除整个 env 对象。修改后退出并重新启动 Claude Code。

---

四、Claude App 桌面端配置

Claude App 的功能和菜单会随版本、操作系统和组织策略变化。只有客户端公开提供 Third-party inference 入口时，才使用下面的方法；如果没有相关菜单，应以当前官方客户端功能为准。

1. 查看开发者模式入口

在支持该功能的版本中，菜单路径通常为：

Help → Troubleshooting → Enable Developer Mode

启用后按照应用提示重启。菜单名称和位置可能随版本变化，不建议通过修改应用内部文件强制开启未公开的功能。

图 2：支持第三方推理配置的客户端版本中的开发者模式入口。

2. 填写 Gateway 参数

应用重启后，进入：

Developer → Configure third-party inference

Connection 选择 Gateway，填写：

配置项	内容
Gateway base URL	<ANTHROPIC_COMPATIBLE_BASE_URL>
Gateway API key	<API_KEY>
Gateway auth scheme	bearer

填写完成后点击：

Apply locally → Relaunch now

重启后新建 Local Code 会话，先使用简单的只读请求验证连接。

3. 桌面端为什么可能读取不到 Shell 变量

从 macOS Dock 或 Finder 启动的图形应用不一定继承终端中的完整环境。即使变量已经写入 ~/.zshrc，桌面端也可能无法读取。

因此桌面端应优先使用：

• 应用提供的 Gateway 配置界面；或
• Local 环境编辑器。

不要仅凭终端中 echo $ANTHROPIC_BASE_URL 有输出，就认定桌面端已经获得同一个变量。

---

五、Claude Code for VS Code 配置

1. 打开用户设置

在 VS Code 中安装并核对 Claude Code 扩展的发布者，然后按 Ctrl/Cmd + Shift + P，运行：

Preferences: Open User Settings (JSON)

2. 合并扩展环境变量

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "<API_KEY>"
    },
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "<ANTHROPIC_COMPATIBLE_BASE_URL>"
    },
    {
      "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY",
      "value": "1"
    },
    {
      "name": "ANTHROPIC_MODEL",
      "value": "<MODEL_ID>"
    }
  ]
}

如果用户设置中已经存在其他字段，应合并而不是覆盖。修改后运行：

Developer: Reload Window

然后使用只读问题验证连接。若扩展提示某个字段不受支持，应查看当前版本文档，不要继续添加来源不明的设置。

---

六、一次实际参数替换示例

为了说明占位符如何替换，本文测试时使用过 AgentRouter，其 Anthropic 兼容 Base URL 为 https://agentrouter.org；配置时将 <ANTHROPIC_COMPATIBLE_BASE_URL> 替换为该地址，把 <API_KEY> 与 <MODEL_ID> 分别替换为控制台实际值即可。该段只记录参数替换方法，不构成服务推荐；接口和模型可能调整，使用者应自行验证服务状态、条款与数据边界。

---

七、常见问题排查

1. 返回 401 或 Unauthorized

可能原因：

• API Key 复制不完整；
• Key 已过期或被撤销；
• 值中包含多余空格或引号；
• Key 不属于当前 Base URL；
• 服务端要求的认证方式与客户端配置不一致。

不要在排错截图中展示真实 Key。

2. 返回 404

404 通常表示 URL 路径不正确。重点检查：

• Base URL 是否误加 /v1；
• 是否把 OpenAI 兼容地址填入 Anthropic 客户端；
• 是否重复拼接 /v1/messages；
• 域名末尾是否带有不可见空格；
• 服务商是否已经调整接口地址。

3. 提示 model not found

展示名称不一定等于 Model ID。应从当前服务的模型列表复制完整 ID，并确认当前 Key 确实拥有访问权限。

4. CLI 修改后没有生效

依次检查：

1. 编辑的是否是当前用户的 ~/.claude/settings.json；
2. JSON 是否通过格式检查；
3. Claude Code 是否已经完全退出并重启；
4. 是否存在其他作用域的同名配置；
5. 当前终端运行的是不是另一套 Claude Code 安装。

macOS 和 Linux 可以检查实际执行文件：

which -a claude

Windows 可以运行：

where.exe claude

5. 请求超时

先用短文本问题验证基础连接，再逐步增加项目上下文。一次性扫描大型仓库、读取二进制文件或运行长时间命令，都可能显著增加响应时间。

6. API Key 出现在公开截图中

仅删除截图并不充分。应立即在对应控制台撤销旧 Key、创建新 Key，然后更新本机配置。

---

八、安全建议

1. 初次进入项目先执行只读分析，再授权修改。
2. AI 修改代码后检查 Git Diff 并运行测试。
3. 重要任务在独立分支或隔离工作区中操作。
4. 不向模型或第三方网关发送生产密钥、证书和数据库连接串。
5. 删除文件、安装依赖和部署等操作保留人工确认。
6. 定期查看调用记录，并撤销不再使用的 Key。
7. 企业项目只使用组织批准的模型服务和密钥管理方案。

---

九、总结

Claude Code 配置自定义 Anthropic 兼容 API 的核心流程是：

确认协议和数据边界
  → 获取 Base URL、API Key 和 Model ID
  → 合并用户级 settings.json
  → 检查 JSON 格式
  → 重启客户端
  → 使用只读任务验证
  → 排查状态码与配置作用域

CLI、Claude App 和 VS Code 扩展的配置入口不同，但最终都需要正确传递 Base URL、API Key 和 Model ID。相比记住某个平台的固定参数，理解协议、配置作用域和排错方法更有长期价值。

---

参考资料

1. Anthropic：Claude Code 安装文档
   https://code.claude.com/docs/en/installation
2. Anthropic：Claude Code Desktop 文档
   https://code.claude.com/docs/zh-CN/desktop

本文是客户端配置与排错记录。相关字段、菜单和功能可能随版本变化，请以当前客户端的官方文档为准。