← 返回博客
Claude CodeCodeGateway

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

(Unofficial)

本指南由社区独立维护，与被介绍的第三方工具厂商无官方隶属、背书或赞助关系，不代表其官方文档。文中第三方商标归其各自所有者所有。

2026年5月20日
没有官方 Key，也不想绑定海外信用卡 —— 直接在这里拿一个。
Claude 桌面端开发者模式配置自定义 API 端点:完整指南

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

`claude_desktop_config.json` 里的鉴权 key 放在哪？ 放在它所服务的那个 MCP server 条目自己的 `env` 对象里，不是文件的顶层。这个文件有文档记载的顶层字段只有一个 mcpServers：既没有文件级的 API key 字段，也没有任何字段能改变 Claude Desktop 把推理请求发往哪台主机。

json
{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

每个 server 各自带一个 env，位置在 command、args 旁边、该 server 自己的对象里面。两个需要不同凭据的 server 不会共用同一个 env，给某个 server 的 key 也不会被其他 server 读到。上面这个结构来自官方 MCP 文档里连接本地 server 的示例。

要改整个应用的 API 主机，这个文件不是入口。 官方给的路径是第三方推理模式：Help → Troubleshooting → Enable Developer Mode，再进 Developer → Configure Third-Party Inference…。那个窗口写入的是托管配置（inferenceProvider、inferenceGatewayBaseUrl、inferenceGatewayApiKey），不是 claude_desktop_config.json。

下面把这两件事展开：完整的点击路径、涉及的键、你的网关必须实现什么，以及如果你照更早的教程配过、现在该怎么收拾。

目录

这页改了什么

TL;DR: 改 Claude Desktop 的 API 端点在开发者模式里做（Help → Troubleshooting → 第三方推理），不是改 claude_desktop_config.json——那个文件只配置 MCP 服务器。

这页的早期版本、以及抄它的不少文章，教的做法是：在 claude_desktop_config.json 顶层加一个 env 对象，里面写上网关主机和一个 API key。

这个做法不成立。关于 claude_desktop_config.json 的官方文档里，既没有文件级 env 对象，也没有 API 主机相关的键——这个文件的定位是 MCP server 注册表。让读者加一个应用从不读取的键，结果是：配置文件看起来是对的，JSON 语法也合法，但什么都不会发生。这类问题最难查，因为它不报错。

正确的流程就是下面这些。如果你正是因为照旧教程配置后没效果才找到这里，原因就在这里，清理办法见照旧教程配过怎么办。

TL;DRTL;DR：claude_desktop_config.json 只配置 MCP server，文件里没有 authentication key 字段。API 密钥在开发者模式里填一次，不写进 JSON。

两个配置容器，别混

Claude Desktop 会读两套互不相干的配置。网上大部分把人绕晕的教程，都是把这两套混在一起讲。

`claude_desktop_config.json`——只管 MCP。 这个文件列出 Claude 可以启动哪些本地工具 server。路径是 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 的 %APPDATA%\Claude\claude_desktop_config.json。Developer 选项卡里那个 Edit Config 按钮打开的就是它。key 写在每个 server 条目内部，形状见本文开头。

托管偏好与 `Claude-3p/configLibrary/`——管推理与应用策略。 第三方推理设置存在操作系统级的托管偏好里，或者存在应用内窗口写入的本地配置库里：

  • macOS 托管：/Library/Managed Preferences/<user>/com.anthropic.claudefordesktop.plist

  • Windows 托管：HKLM\SOFTWARE\Policies\Claude（机器级）或 HKCU\SOFTWARE\Policies\Claude（用户级）

  • Linux 托管：/etc/claude-desktop/managed-settings.json

  • macOS 本地：~/Library/Application Support/Claude-3p/configLibrary/

  • Windows 本地：%LOCALAPPDATA%\Claude-3p\configLibrary\

  • Linux 本地：~/.config/Claude-3p/configLibrary/

这张表带来两条规则。第一，托管来源的优先级高于本地写入的值，两者同时存在时托管生效。第二，Windows 上两个策略 hive 不会合并：HKLM 下存在机器级策略时，应用会完全忽略 HKCU。另外配置是启动时读取的，改完要完全退出应用再打开，只关窗口不算。

不要把第三方推理的键写进 `claude_desktop_config.json`。 把 inferenceProvider、inferenceGatewayBaseUrl 塞进那个文件，等于换了拼写重犯同一个错：它仍然是文件 schema 里没有定义的键，客户端仍然不会读。

官方三步：开启开发者模式并打开第三方推理窗口

按应用期望的顺序，三步。

第一步，开启开发者模式。 打开应用菜单（macOS 是顶部菜单栏，Windows 是登录页左上角的 ☰），进入 Help → Troubleshooting → Enable Developer Mode。

第二步，打开推理配置窗口。 选择 Developer → Configure Third-Party Inference…。

第三步，填好 Connection 并应用。 把推理提供方设为 Gateway，填上网关地址与凭据，然后点 Apply Changes——它会把这套配置写到本机并以该配置重启应用。如果你不是配一台机器而是要发给整个团队，同一个窗口的 Export 菜单可以直接产出 macOS MDM 用的 .mobileconfig、Windows 用的 .reg、ADMX 模板、纯 JSON 配置，以及给网络团队用的出站白名单。

官方推荐用应用内窗口而不是手工改文件：它会边输入边校验、按你选的提供方显示必填项、对你的端点做一次连接测试，还会根据你的设置推导出需要放行的出站域名。那个连接测试，是客户端真正开工之前最接近预检的东西。

如果机器上已经部署了托管配置，窗口会以只读方式打开并显示已下发的值。要写新配置，请在没装托管配置的机器上做。

TL;DRTL;DR：网关 base URL 和 API 密钥都填在开发者模式的推理窗口里，密钥不会存进 claude_desktop_config.json。

Connection 里每一项是什么

以下键名来自官方的配置参考，也就是那个窗口背后的设置：

  • `inferenceProvider`：填 gateway。它表示用自建/第三方网关（LiteLLM、Portkey、你自己的代理等）作为推理提供方。

  • `inferenceGatewayBaseUrl`：网关端点的完整 URL。Claude Desktop 1.2581.0 起提供。

  • `inferenceGatewayApiKey`：该网关的 API key。同样是 1.2581.0 起提供。

  • `inferenceGatewayAuthScheme`：凭据怎么放在请求头上，bearer（默认）或 x-api-key。1.3036.0 起提供。只有你的网关只认其中一种时才需要设它。

  • `inferenceModels`：显式模型列表。网关没有实现 GET /v1/models 时用它；想自己控制选择器的顺序和标签时也用它。列表第一项会成为默认项。

  • `inferenceStreamIdleTimeoutSec`：流式响应当前只在发 keep-alive ping 时，额外等待模型输出多少秒。默认 300，范围 300–1800，仅网关提供方可用。上游很慢、要 ping 好几分钟才出第一个 token 的话，把它调大。

手工写策略而不是从窗口导出时注意：在操作系统的偏好存储里，每个值都写成字符串，布尔值和数组也一样。Linux 的托管文件是真 JSON，用原生类型；macOS 与 Windows 上，inferenceModels 这种数组是一个键，值是编码成字符串的 JSON 文档。

网关必须实现什么

这一节决定某个服务到底能不能用，没有商量余地：

  • 必须：实现 Anthropic Messages API 的 POST /v1/messages，其中流式与tool use 是硬要求。

  • 可选：GET /v1/models。实现了，Claude Desktop 会自动发现可用模型；没实现，就在 inferenceModels 里显式列出。

提示缓存（prompt caching）是强烈建议而不是硬要求：Cowork 与 Code 会话每轮都会带 cache_control 断点，网关把这些字段透传下去，缓存命中就能保住。反过来，如果网关把 cache_control 剥掉，或者每轮都改动 system prompt 或工具列表，上游每轮都要把整段对话按全价输入 token 重算一遍，成本更高、延迟更大。检查方法在你的用量数据里：一个会话的第一次请求之后，多数请求的 cache_read_input_tokens 应该明显大于 0。如果每次都是 0，去看这条路由的请求改写逻辑。

这套契约也是筛掉服务商最快的办法。只支持 OpenAI chat-completions 格式的服务，不是 Claude Desktop 能直接用的网关，不管它列了多少模型。

base URL 要不要带 /v1

官方文档自己给了两种写法，所以这件事得说仔细。

gateway 指南里那张应用内配置表写的是纯主机：https://llm-gateway.example.corp。配置参考里 Linux 托管文件的示例写的是带路径：https://gateway.example.com/v1。

两种都在官方材料里出现过，而我们没有在真实的 Claude Desktop 里验证过握手，所以本文不会断言必须带、也不会断言绝不能带。能确定的是请求最终要落到哪里：客户端必须把 POST /v1/messages 发到你的网关。

据此有个可操作的判断办法：按你网关文档给的形态填，然后确认客户端最终拼出来的路径落在 /v1/messages。在我们自己的端点上这个差别可以直接观察：POST https://api.codegateway.dev/messages 返回 404 Not found，POST https://api.codegateway.dev/v1/messages 返回 200。CodeGateway 自己的接入页推荐的是纯主机形态 https://api.codegateway.dev，不带 /v1。如果你的网关文档写的是另一种，以你的网关为准；拿不准就先点窗口里的连接测试，它会先告诉你结果，再让你决定要不要应用。

TL;DRTL;DR：发一条测试消息，确认网关日志里出现 Authorization 头；没有就重新打开「帮助 → 排查疑难 → 开发者模式」再填一次密钥。

验证一次往返

TL;DR: 在 Claude Desktop 发一条测试消息，看网关日志有没有收到请求。没收到就检查端点 URL 并重启应用。

在 Claude Desktop 里发一条消息，然后确认网关的用量日志里出现了这次请求。这一步就能把「客户端在跟网关说话」和「客户端还在跟 Anthropic 说话」分开。

你也可以绕开桌面客户端，直接测网关这一侧。下面这条请求是在文中这个端点上真跑过的，返回体是真实响应，只保留了与判断相关的字段：

bash
curl -s https://api.codegateway.dev/v1/messages \
  -H "x-api-key: $CODEGATEWAY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,"messages":[{"role":"user","content":"Reply with exactly: ok"}]}'
json
{"type":"message","model":"claude-haiku-4-5-20251001","stop_reason":"end_turn","content":[{"type":"text","text":"ok"}],"usage":{"input_tokens":12,"output_tokens":4}}

返回 "type":"message" 说明这条路是通的。返回 401，说明 key 不对，或者鉴权方式与网关期望的不一致。返回 404，说明 base URL 和客户端追加的路径没对上，回上一节看。

还有一个时间上的坑，值得在判定「配置坏了」之前先知道：重启后的第一个请求可能比后面慢很多。在我们自己的端点上，用 claude-haiku-4-5，第一次冷调用用了 22.2 秒，紧接着的流式调用 5.7 秒，强制 tool call 5.9 秒。第一条消息看起来卡住的网关，往往只是冷启动，先发第二条再动手改配置。

一个可用实现：CodeGateway

CodeGateway 是满足上面这套契约的网关之一。它不是唯一一个，而且任何实现了 Anthropic Messages API 的网关，配法都一样——本文这些步骤不随服务商变化。

我们在 2026-09-29 对着线上端点逐项测过四项要求，模型用 claude-haiku-4-5，max_tokens 分别取 16、16、64：

  • `POST /v1/messages`：HTTP 200，type=message，stop_reason=end_turn，usage 为输入 12 / 输出 4 token。

  • 流式：HTTP 200，SSE 事件序列完整——message_start、content_block_start、五个 content_block_delta、content_block_stop、message_delta、message_stop，另有一个 ping。

  • tool use：强制 tool_choice 后 HTTP 200，返回 stop_reason=tool_use，并带有 tool_use 块，其输入为 {"city":"Tokyo"}。

  • 鉴权：x-api-key 与 Authorization: Bearer 都接受，所以默认的 bearer 可用，x-api-key 也可用。

GET /v1/models 也已实现，因此模型自动发现可用，inferenceModels 不是必须的。在自动发现模式下，Claude Desktop 只保留看起来像 Claude 模型的那批 id，目录里的 claude-* 条目会出现在选择器里；想换成显式清单、调整顺序、或正确声明 1M 上下文的模型，看 Claude Desktop 接入文档。

下面是同样这组设置在托管文件里的形态，示例给的是只认 x-api-key 头的网关：

json
{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://api.codegateway.dev",
  "inferenceGatewayApiKey": "sk-cg-...",
  "inferenceGatewayAuthScheme": "x-api-key"
}

除非你在用 MDM 批量下发，否则请从应用内窗口写这份配置。Linux 上文件是 /etc/claude-desktop/managed-settings.json，必须是普通文件、属主为 root、且组和其他用户不可写；任何一条不满足，整份文件都会被拒绝，应用会认为设备处于「托管但读不出来」的状态，本地设置也会一起失效，直到你修好它。

CodeGateway 是独立产品，不是 Anthropic 官方产品，与 Anthropic 无隶属或背书关系。 网关侧的价格见价格页，统一倍率怎么算说明了用量的计费方式。

如果你还没有官方 Anthropic key，或不想为它绑定外卡，CodeGateway 可以直接签发一个满足上文契约的 key。在开发者模式的「第三方推理」窗口里把它填进 inferenceGatewayApiKey，再把 inferenceGatewayBaseUrl 指向你的网关主机即可——不需要另装客户端，也没有起步订阅。按 token 计费，评估只需几分钱，而不是先付一个月。在 CodeGateway 注册后，key 就在控制台首页。

claude_desktop_config.json 的鉴权 key 到底写在哪里？

claude_desktop_config.json 没有顶层的 authentication key 字段。鉴权 key 写在它所服务的那个 mcpServers 条目的 env 对象里；应用本身只在 开发者模式 → Configure Third-Party Inference 里接收 key。

json
{
  "mcpServers": {
    "your-server": {
      "command": "npx",
      "args": ["-y", "your-mcp-server"],
      "env": { "API_KEY": "sk-..." }
    }
  }
}

官方 key 路径：在 Anthropic Console（console.anthropic.com → API keys）创建。Claude Desktop 不会从 claude_desktop_config.json 读取它。要让整个应用改走别的 API 主机，用第三方推理设置：inferenceGatewayBaseUrl 与 inferenceGatewayApiKey。

ANTHROPIC_BASE_URL 同样不是 Claude Desktop 的配置项 —— 它是 Claude Code CLI 的环境变量。Claude Desktop 改主机走第三方推理模式，步骤见上文的配置教程。

没有官方 Anthropic key，或不想绑定海外信用卡？在 CodeGateway 创建一个 key，粘贴到第三方推理窗口即可 —— 具体步骤就在本页。

MCP 与网关并存

TL;DR: Windows 配置文件在 %APPDATA%\Claude\claude_desktop_config.json，启动 Claude Desktop 前编辑。它只配置 MCP 服务器——改 API 端点走开发者模式。

两套容器互相独立，这正是不该把它们合并的实际理由。MCP 工具调用走的是 Claude Desktop 与它启动的那个 server 之间的本地进程通信；推理请求走网络到你的网关。把推理指向网关，不会改变 MCP server 的鉴权方式；MCP server 的凭据，也不会影响推理发往哪里。

一个两者都配、且都配对的文件长这样：

json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

注意这个文件里没有什么：顶层没有 env，没有 API 主机，没有网关 key。网关设置在上面说的第三方推理配置里。

Claude Code 是另一套机制

TL;DR: 环境变量法在进程层注入 API 端点（高级用法）。多数场景建议用开发者模式的「第三方推理」界面。

ANTHROPIC_BASE_URL 是一个真实、且被官方文档记载的环境变量——但它属于 Claude Code，也就是 Anthropic 的命令行工具，跟 Claude Desktop 是两个产品。在 shell 里设置它，是把 CLI 指向网关的受支持方式：

bash
export ANTHROPIC_BASE_URL="https://api.codegateway.dev"
export ANTHROPIC_API_KEY="sk-cg-..."
claude --print "hello"

这个变量和 Claude Desktop 的配置文件没有任何关系。如果你见过把两者写在一起的教程，那正是这个话题上大部分混乱的来源：CLI 读环境变量，桌面客户端读托管偏好。CLI 这条路我们单独写了一篇：Claude Code 一行命令配置。

TL;DRTL;DR：旧教程让你往 claude_desktop_config.json 加 apiKey / authentication key 是错的，该字段无效；请改用开发者模式。

如果你的编码 agent 没有读到项目规则，先查指令链：AGENTS.md 不生效？加载顺序与 32 KiB 上限 解释了 AGENTS.md 为什么会按错误顺序加载、或静默丢文件。

照旧教程配过怎么办

如果你之前给 claude_desktop_config.json 加过顶层的 env 对象，里面指向某个网关主机、旁边放着 API key：

json
{
  "mcpServers": {},
  "env": {
    "YOUR_GATEWAY_HOST_VARIABLE": "https://some-gateway.example.com/v1",
    "YOUR_GATEWAY_KEY_VARIABLE": "your-key"
  }
}

那么没有任何东西在读它。把顶层那个 env 块删掉，保留写在各个 mcpServers 条目内部（如果确实配过）的 env 对象，然后改从第三方推理窗口配置推理。清理时有两个细节容易出错：顶层 env 和 server 内部的 env 乍看一模一样，行为却完全不同；另外旧块留着除了让人困惑并不会造成别的损害，所以不必在一台你在用的机器上赶着改。

还有一点：文件级 env 块从来不是设置 MCP 凭据的另一种方式。如果哪篇教程让你把 API key 放在那里、指望所有 MCP server 都能读到，那些 server 其实并没有收到它。

排错

窗口提示已应用，但行为没变。 配置是启动时读的。彻底退出应用再打开——macOS 从菜单栏退，Windows 从系统托盘退。两个平台上只关窗口都不够。

机器上有托管配置，窗口是只读的。 这是预期行为：托管值优先。改托管配置（走你的 MDM），或者换一台没有托管配置的机器做实验。

Linux 上连接测试失败。 先查文件属主和权限。/etc/claude-desktop/managed-settings.json 必须属主为 root、组和其他用户不可写，/etc/claude-desktop 必须是真目录而不是符号链接。被拒绝的文件不会应用任何设置，原因会写进应用日志目录下的 main.log，schema 校验失败的键名也写在同一处。从这里查，比反复重填快得多。

第一条消息要等很久。 见前面的时间说明，冷启动是真实存在的。如果每次流式响应都这样、而不是每次启动只出现一次，去看 inferenceStreamIdleTimeoutSec，以及你的网关在上游模型沉默期间是否发出 keep-alive ping。

流式正常但 tool call 失败。 说明你的网关没有实现完整契约。tool use 是硬要求，不是加分项：一个永远收不到 tool_use 块的 agent 循环，就不再是 agent 了。

常见问题

Q：能不能接第三方 API、不订阅官方？

能，网关提供方模式就是为这个场景设计的。官方文档把它写给自建网关（LiteLLM、Portkey、公司内部代理等），客户端这一侧只需要一个 base URL 和一个凭据。不能省掉的是接口本身：网关必须实现 Anthropic Messages API，包括 POST /v1/messages、流式与 tool use。只会 OpenAI 格式的网关，需要在前面加一层转换。推理的账号与计费关系随之转到网关运营方；桌面客户端本身仍然是 Anthropic 的客户端。

Q：配置放哪——`claude_desktop_config.json` 还是别的地方？

不同的设置，不同的容器。claude_desktop_config.json 放 MCP server 列表，每个 server 的鉴权 key 放在它自己的 env 对象里。第三方推理设置——inferenceProvider、inferenceGatewayBaseUrl、inferenceGatewayApiKey——放在操作系统托管偏好里（macOS 的 .mobileconfig、Windows 的注册表策略、Linux 的 /etc/claude-desktop/managed-settings.json），或者放在应用内窗口写入的本地 Claude-3p/configLibrary/ 目录里。这个文件既没有文件级 API key 字段，也不该出现任何推理相关的键。托管来源存在时，托管优先。

Q：这跟 MCP 是什么关系？

两套系统，只是恰好装在同一个应用里。MCP 负责 Claude Desktop 怎么启动、怎么跟本地工具 server 通信；推理网关决定模型请求发往哪里。改一个不影响另一个。真正的交集在文件层面：两者都配在同一台机器上，而 MCP 那个文件的名字听起来像是该放 API 设置的地方——这也是大量教程把网关 key 放错位置的原因。把 MCP 的 key 留在 server 条目里，把推理设置留在第三方推理配置里，两者就永远不会打架。

Q：claude_desktop_config.json 支持 authentication key 或 apiKey 字段吗？ 不支持。claude_desktop_config.json 只列 MCP server。第三方端点的鉴权在开发者模式（帮助 → 排查疑难 → 开发者模式）里填写，存于应用本地设置，不在 JSON 文件里。

相关资料

参考来源

claude_desktop_config.json 里的 API Key 到底填在哪？

TL;DR: anthropic_base_url 不是 Claude Desktop 的配置键。支持方式是开发者模式第三方推理（inferenceGatewayBaseUrl + inferenceGatewayApiKey）。配置教程见下。

该文件没有「文件级」API Key 字段。MCP 服务器的鉴权 key 写在对应 mcpServer 条目的 env 或 args 里；第三方推理（自定义 API 主机）的 Key 在开发者模式的推理窗口填写，不写进 config 文件。

Claude Desktop 想换自定义 API 地址（base URL）怎么设置？

开启开发者模式后，在第三方推理窗口填网关地址与 Key 即可切换 API 主机，不需要改 claude_desktop_config.json（那只是 MCP 配置）。前提是网关兼容 Anthropic Messages API。

没有官方 Key、不想绑外卡，能接第三方推理网关吗？

可以。选一个兼容 Anthropic Messages API 的网关，在网关侧创建 API Key，回到开发者模式窗口填入网关地址与 Key 即可；同一套 Key 也能给 Claude Code 用，连接不稳参见连接超时排查指南。文末「Solve API Key & Billing limits」卡片可直接创建 Key。

作者：CodeGateway 团队最后审稿：2026-05-20

用 CodeGateway 解决 API 密钥与限流难题

缺少官方 API Key 或面临海外信用卡支付受限？注册立得 sk-cg- 密钥，支持 Claude、GPT、Gemini、DeepSeek。注意：Claude 与 Gemini 的文本模型走 Anthropic Messages 协议（/v1/messages），OpenAI 兼容的文本端点不接收这两系。内置智能路由、用量分析与免费体验额度。

免费注册
← 返回博客