---
title: "Claude Code 自定义 API 与 Codex、OpenCode 接口地址配置"
description: "讲清 Claude Code、Codex、OpenCode 三个工具从哪里读取接口地址和密钥，给出可照抄的环境变量与配置文件写法，并附 401、404、超时的排错表和网络自查步骤。"
url: https://cdnping.org/blog/configure-custom-api-endpoint-claude-code-codex
language: zh-CN
published: 2026-10-17
category: "开发工具"
tags: ["Claude Code","Codex","OpenCode","API 配置","排错"]
source: cdnping.org
license: Free to quote and summarize with a link to the url above.
---
# Claude Code 自定义 API 与 Codex、OpenCode 接口地址配置

Claude Code 自定义 API 地址靠两个环境变量：`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`。Codex 和 OpenCode 则是在各自的配置文件里声明一个“供应商”，写上 base url 和密钥来源。改完如果报错，多半是地址路径写错、密钥类型不对或者网络不通，后文的排错表可以逐项对照。

下面只写官方文档里有记载的配置项。这几个工具更新快，字段名可能变化，标了“以官方文档为准”的地方，动手前先核对当前版本的文档。

## 填进去的接口地址要满足什么条件？

先确认你要接的服务和工具用的是同一种接口格式。

| 工具 | 默认使用的接口格式 | 你填的地址需要兼容 |
| --- | --- | --- |
| Claude Code | Anthropic Messages 接口 | Anthropic 格式 |
| Codex | OpenAI 接口 | OpenAI 格式（具体走 Chat Completions 还是 Responses，以 Codex 官方文档为准） |
| OpenCode | 按供应商配置决定 | 你在配置里声明的那种格式 |

只兼容 OpenAI 格式的地址填进 Claude Code 跑不通，反过来也一样，这是 404 的常见来源。

另外两点：

- base url 一般只写到根路径或 `/v1`，工具会自己拼后面的 `/messages`、`/chat/completions`。要不要带 `/v1`，看服务方的接入说明。
- 密钥不要写进项目仓库，放在 shell 配置、用户目录下的配置文件或系统的密钥管理里。

## Claude Code 怎么设置自定义 API 地址？

Claude Code 官方文档里与此相关的环境变量有三个：

| 变量 | 作用 |
| --- | --- |
| `ANTHROPIC_BASE_URL` | 覆盖默认的 API 地址 |
| `ANTHROPIC_AUTH_TOKEN` | 作为 `Authorization: Bearer` 头发送的令牌，常用于网关或代理 |
| `ANTHROPIC_API_KEY` | 作为 `X-Api-Key` 头发送的密钥 |

`ANTHROPIC_AUTH_TOKEN` 和 `ANTHROPIC_API_KEY` 走的是不同的请求头。服务方要哪一种就设哪一种，不要两个都填。

### 方式一：在终端里临时设置

```bash
export ANTHROPIC_BASE_URL="https://your-endpoint.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxx"
claude
```

适合先试通不通，关掉终端就失效。

### 方式二：写进 settings.json

`settings.json` 支持 `env` 字段，里面的变量在每次会话启动时生效。用户级配置在 `~/.claude/settings.json`：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-endpoint.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxx"
  }
}
```

项目目录下也可以放 `.claude/settings.json`，但这个文件通常会提交到仓库，密钥别写在里面。项目级的私有配置用 `.claude/settings.local.json`，并确认它在 `.gitignore` 里。

### 怎么确认生效了

启动后在 Claude Code 里执行 `/status`，查看当前的 API 地址和认证来源。如果显示的还是默认地址，检查 shell 里是不是另有同名变量。

## Codex 怎么配置自定义 base url？

Codex 的配置文件是 `~/.codex/config.toml`。官方文档的做法是用 `model_providers` 声明一个自定义供应商，再用 `model_provider` 指向它。示例：

```toml
model_provider = "mygateway"

[model_providers.mygateway]
name = "My Gateway"
base_url = "https://your-endpoint.example.com/v1"
env_key = "MYGATEWAY_API_KEY"
```

密钥放在环境变量里：

```bash
export MYGATEWAY_API_KEY="sk-xxxxxxxx"
codex
```

几点说明：

- `env_key` 填的是环境变量的名字，不是密钥本身，Codex 启动时去读这个变量。
- 供应商段落里还有 `wire_api` 等字段，用来指定走哪种 OpenAI 接口。可选值和默认值在不同版本里调整过，以 Codex 官方文档为准。
- 模型名用 `model = "..."` 指定，填服务方支持的名称。

## OpenCode 怎么添加自定义 provider？

OpenCode 的全局配置一般在 `~/.config/opencode/opencode.json`，项目根目录也可以放一份。接入兼容 OpenAI 格式的服务用 `provider` 字段，官方文档的写法大致如下：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "mygateway": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Gateway",
      "options": {
        "baseURL": "https://your-endpoint.example.com/v1"
      },
      "models": {
        "your-model-id": {}
      }
    }
  }
}
```

密钥可以用 `opencode auth login` 交互录入，也可以在 `options` 里引用环境变量。具体字段名，以及 Anthropic 格式供应商的写法，以 OpenCode 官方文档为准。

## 接聚合网关时有什么不同？以 AGI Plan 为例

用聚合网关的流程和上面一样，只是地址和密钥换成网关给的。以 AGI Plan 为例（AGI Plan 是 cdnping 的商业合作方）：它同时兼容 OpenAI 和 Anthropic 两种接口格式，Claude Code、Codex、OpenCode 都能接。接入分三步：邮箱验证码注册、选套餐并建密钥、改一处配置。各工具的地址和分步教程见 [agiplan.dev](https://agiplan.dev)。AGI Plan 站方说明自己不是官方授权渠道，部分模型标注为“仅境外”，具体以 [模型页](https://agiplan.dev/models) 为准。使用前看清说明，并遵守各服务的条款和当地法规。

## 报 401、404、超时怎么查？

改完配置报错，按下表从上往下查。

| 现象 | 常见原因 | 怎么查 |
| --- | --- | --- |
| 401 / 403 | 密钥错误、过期或额度用完；请求头类型不对（Claude Code 里 `AUTH_TOKEN` 和 `API_KEY` 用反） | 用 curl 带同一个密钥直接请求一次；在 Claude Code 里用 `/status` 看认证来源 |
| 404 | base url 多写或少写了 `/v1`；接口格式不匹配（OpenAI 格式地址填进了 Claude Code）；模型名服务方不支持 | 对照服务方文档核对完整路径和模型名 |
| 连接超时 / 一直转圈 | 本机到接口地址的网络不通；代理没覆盖到终端；DNS 解析异常 | 先看对方是否故障，再查本机网络，见下一节 |
| 偶发 5xx、429 | 服务端故障或限流 | 看 [/status](/status) 和 [/down](/down) 上同一时段有没有异常 |
| 改了配置不生效 | shell 里有同名环境变量覆盖；改的是项目级而不是用户级配置 | `env \| grep -i anthropic` 或 `env \| grep -i base_url` |

通用的 curl 自检命令（Anthropic 格式，按服务方要求换成对应的请求头）：

```bash
curl -sS -o /dev/null -w "HTTP %{http_code}  连接 %{time_connect}s  总计 %{time_total}s\n" \
  "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"your-model-id","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
```

返回 200 说明地址和密钥都对，问题在工具配置；返回 401 或 404 对照上表；命令卡住不返回，就是网络问题。

## 超时是服务端的问题还是本机网络的问题？

超时有两种可能：对方服务故障，或者你这边到对方的路不通。分开查会快很多。

第一步，看服务方是否正常。打开 [API 状态页](/status)，它从 Cloudflare 边缘每 5 分钟探测一次各家官方 API 入口，并同步部分官方状态页。用 AGI Plan 的可以直接看 [/status/agiplan](/status/agiplan)；用 Claude Code 也可以看 [/down/claude-code](/down/claude-code)，那里汇总了官方状态页、API 探测和用户报告。

作为参照：cdnping 在 2026 年 10 月 17 日从 Cloudflare 丹佛节点（DEN）做的边缘探测中（统计窗口约 85 分钟，共 242 次探测，来源 cdnping /status），`api.anthropic.com` 的 p50 为 73 ms，`api.openai.com` 为 96 ms，窗口内都没有失败。cdnping 从这一天才开始采集，这只是一小段窗口的机房到机房数据，不代表你本机的体验，只能说明当时服务端在正常响应。如果状态页正常而你这边超时，问题多半在本地网络。

第二步，查本机网络。打开 [IP 与环境检测](/ip)，重点看三项：

1. 出口 IP 与类型：确认终端实际走的出口在哪里，是机房、家宽还是移动网络。
2. 大陆分流检测：判断当前是“大陆分流 / 全局代理 / 国内直连”。浏览器走了代理而终端没走，是常见情况。
3. 多出口检测与 DNS 泄漏：看访问不同服务时出口是否一致，DNS 是否走了预期的解析器。

检测完可以生成带水印的结果图，并可选择隐藏 IP 地址。发给同事或在群里求助时，把这张图附上，不会把自己的出口 IP 暴露出去。指纹在本地计算，不上传。

第三步，测延迟。首页的[在线测速](/)在浏览器里测到 15 个 AI 模型 API 的“首次连接”（含 DNS 和 TLS 握手）和“往返”时间。首次连接明显偏高而往返正常，通常是 DNS 或握手阶段的问题；两者都高，就是链路本身慢。延迟的成因可以参考 [AI API 延迟为什么高](/learn/ai-api-latency-china)。

浏览器和终端不一定走同一条网络路径。浏览器里测得通、终端里不通，先检查终端有没有设置 `HTTPS_PROXY` 等变量，以及分流规则是否覆盖了接口域名，原理见[分流原理](/learn/split-tunneling)。

## 照着做：从配置到自检

1. 选一个工具，先用环境变量临时配好，跑一次上面的 curl 自检。
2. 通了再写进配置文件，确认密钥文件不在仓库里。
3. 下次报错，先看 [/status](/status) 确认服务端，再打开 [/ip](/ip) 查本机；求助时附上隐藏了 IP 的结果图。