← 返回博客
Claude CodeCodeGateway

Claude 桌面端开发者模式配置自定义 API 端点:完整指南

2026年5月20日
Claude 桌面端开发者模式配置自定义 API 端点:完整指南

Claude 桌面端开发者模式配置自定义 API 端点：完整指南

TL;DR：Claude Desktop 默认连官方 API。遇到超时或连接问题时，通过开发者模式编辑 claude_desktop_config.json，设置 ANTHROPIC_BASE_URL 指向 CodeGateway，5 分钟解决，MCP 工具不受影响。

目录

为什么要修改 Claude Desktop 的 API 端点

Claude Desktop 默认把所有请求发到 Anthropic 的官方端点。对于部分开发者，这个连接会出现：

  • 请求超时或响应极慢
  • 错误码 unsupported_region（地区限制）
  • API Key 无法在桌面端使用（订阅用户无 API key，API 用户才有）

解决方式是把 Claude Desktop 的底层 API 请求路由到第三方聚合网关。具体做法是通过开发者模式修改配置文件，指定自定义 baseURL。

整个配置过程约 5 分钟，不需要修改系统代理，不影响 Claude Desktop 的其他功能（MCP、Projects、Artifacts 均正常使用）。

Claude Desktop 开发者模式是什么

Claude Desktop 提供两个入口开启开发者模式，选其中一个即可：

入口

路径

顶部菜单栏

Help → Enable Developer Mode

应用内设置

Settings → Developer → Edit Config

开启后可以编辑底层配置文件 claude_desktop_config.json，该文件控制：

  • MCP 服务器列表：定义哪些本地 MCP 工具可以被 Claude 调用
  • API 端点设置：通过环境变量或配置项指定自定义 baseURL
  • 日志级别：用于调试 MCP 工具调用

注意：开发者模式本质上是配置文件编辑器入口，并不是独立的模式切换开关。你需要手动编辑 JSON 文件，Claude Desktop 下次启动时读取新配置。

前置条件

  • Claude Desktop 已安装（下载地址），版本建议 ≥ 0.10
  • 第三方 API 网关的 endpoint URL 和 API Key（本文以 CodeGateway 为例：https://api.codegateway.dev/v1）
  • 文本编辑器（VS Code、Notepad++ 均可）

macOS 配置步骤

Step 1：开启开发者模式并打开配置文件

有两种方式，任选一个：

  • 方式 A：屏幕顶部菜单栏 → Help → Enable Developer Mode，勾选后 Settings 会出现 Developer 选项卡
  • 方式 B：直接点击 Claude → Settings → Developer → Edit Config

开启后点击 Edit Config，这会打开 claude_desktop_config.json 文件，默认路径：

~/Library/Application Support/Claude/claude_desktop_config.json

也可以直接在终端里打开：

bash
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 2：添加自定义 API 端点配置

在配置文件中加入 env 字段，指定自定义端点和 Key：

json
{
  "mcpServers": {},
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "你的-codegateway-api-key"
  }
}

如果你已有 MCP 服务器配置，只需在现有 JSON 里补充 "env" 字段，不要覆盖整个文件：

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    }
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "你的-codegateway-api-key"
  }
}

Step 3：保存并重启

保存文件，完全退出 Claude Desktop（菜单栏 Claude → Quit Claude），再重新启动。

只关闭窗口不够——Claude Desktop 在系统托盘常驻，必须从菜单栏彻底退出。

Windows 配置步骤

Step 1：开启开发者模式并打开配置文件

两种方式，任选一个：

  • 方式 A：应用菜单栏 → Help → Enable Developer Mode，勾选后 Settings 会出现 Developer 选项卡，再点击 Edit Config
  • 方式 B：直接进入 Settings → Developer → Edit Config

也可以手动导航配置文件路径：

%APPDATA%\Claude\claude_desktop_config.json

在文件资源管理器地址栏直接粘贴此路径并按 Enter 可直接跳转。

Step 2：添加自定义 API 端点配置

同 macOS，在配置文件中加入 env 字段：

json
{
  "mcpServers": {},
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "你的-codegateway-api-key"
  }
}

注意 Windows 路径在 JSON 中用双反斜杠：

json
"args": ["C:\\Users\\yourname\\Documents"]

Step 3：保存并重启

保存文件，在系统托盘右键 Claude → Exit，再重新启动。

通过环境变量配置（高级）

如果你管理多台设备，或者不想把 API Key 写进配置文件（有安全顾虑），可以通过系统环境变量来配置。

macOS / Linux（.zshrc 或 .bashrc）

bash
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"
export ANTHROPIC_API_KEY="你的-codegateway-api-key"

然后在从终端启动 Claude Desktop 时，它会继承这两个环境变量。

注意：双击图标启动的 Claude Desktop 不读取 shell 环境变量。需要从终端运行： ``bash open -a "Claude" ``

Windows（系统设置 → 高级 → 环境变量）

在系统环境变量里新增：

  • ANTHROPIC_BASE_URL = https://api.codegateway.dev/v1
  • ANTHROPIC_API_KEY = 你的 Key

重启 Claude Desktop 后生效。Windows 环境变量会被所有进程继承，不需要从终端启动。

优先级：claude_desktop_config.json 中的 env > 系统环境变量。两者同时存在时，配置文件优先。

验证配置是否生效

配置完成后，在 Claude Desktop 里发一条消息，然后在 CodeGateway Dashboard 查看请求日志：

  • 有新请求：配置生效，流量走 CodeGateway
  • 无请求：检查 Key 是否正确、重启是否彻底

也可以用下面的命令快速验证网关端点可达性：

bash
curl -s https://api.codegateway.dev/v1/models \
  -H "Authorization: Bearer 你的-codegateway-api-key" \
  | python3 -m json.tool | head -20

返回模型列表说明连接正常。

MCP 工具同时使用

配置了自定义 API 端点后，MCP 工具仍然正常工作。MCP 协议和 API 请求是两条独立链路：

  • MCP 工具调用（文件系统、数据库、外部服务等）：走本地进程通信，不经过 API 端点
  • Claude 模型推理：走 ANTHROPIC_BASE_URL 指定的端点

两者互不干扰。你可以同时：

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "你的-codegateway-api-key"
  }
}

在我们的测试中，同时挂 4 个 MCP 服务器 + 路由到 CodeGateway，工具调用延迟无明显变化（P50 < 200ms），模型推理走 Cloudflare 边缘节点，首字节时间比官方直连低约 30%（测试条件：上海 → 香港节点，3 次均值）。

常见问题

Q：配置后 Claude Desktop 显示"无法连接"，怎么办？

先确认 API Key 是否有效。在终端运行上面的 curl 验证命令。如果返回 401 Unauthorized，Key 填错了；如果 curl 通但 Claude Desktop 不通，检查 JSON 格式是否有语法错误（常见：末尾多了逗号）。

Q：ANTHROPIC_BASE_URL 要不要加 /v1 后缀？

要。Claude Desktop 内部会把请求追加在 baseURL 后面，比如 {ANTHROPIC_BASE_URL}/messages。如果 baseURL 末尾没有 /v1，路径会拼错成 api.codegateway.dev/messages，返回 404。

Q：配置文件里写了 Key，安全吗？

配置文件存在本机，只有当前用户可读。如果是个人设备，风险可接受。如果是共享设备，建议用系统环境变量方案（见上文），Key 不进配置文件。

Q：可以同时用多个不同的 API 端点吗？

不行。ANTHROPIC_BASE_URL 是全局设置，Claude Desktop 所有请求指向同一个端点。如果需要按对话切换不同模型/端点，目前只能改配置文件重启。

Q：Claude Desktop 更新后配置会丢失吗？

不会。claude_desktop_config.json 是用户数据，更新 Claude Desktop 不覆盖这个文件。

Q：CodeGateway 支持 Claude Desktop 的哪些模型？

CodeGateway 支持 Anthropic 所有 Claude 模型（Haiku 4.5、Sonnet 4.6、Opus 4.7），以及 OpenAI GPT 系列。Claude Desktop 发起请求时使用哪个模型，由应用内的模型选择器决定，CodeGateway 按请求的 model 参数路由，不强制限定模型。

Q：Claude Desktop 的 Projects 和 Artifacts 功能会受影响吗？

Projects 和 Artifacts 的数据存在 Anthropic 账号侧，不经过 API。这两个功能不受 ANTHROPIC_BASE_URL 配置影响，配置后正常使用。

相关资料

参考资料

  • Anthropic Claude Desktop 官方文档（2026）
  • Model Context Protocol 快速开始指南（modelcontextprotocol.io）
  • Anthropic API SDK Python README（github.com/anthropics/anthropic-sdk-python）

**权威参考**：Anthropic API 入门文档 · Claude Code 官方文档

作者：CodeGateway 团队最后审稿：2026-05-20
← 返回博客