小白也能看懂：Claude Code 和 Codex CLI 自定义 API 配

Claude Code 和 Codex CLI 都是运行在终端里的 AI 编程工具，可以读取项目文件、修改代码、执行命令和分析报错。

不过两者使用的接口协议并不相同：

所以，即使同一个 API Key 同时支持两款工具，Base URL 和配置文件通常也需要分别设置。只有 /v1/chat/completions 接口，不代表一定能用于 Claude Code 或 Codex CLI。

下面分别介绍安装和配置方法。

一、开始前需要准备什么

你需要提前准备：

• 一个可以使用的 API Key
• 对应工具的 Base URL
• 准确的模型 ID
• 一个用于测试的普通项目目录

本文统一使用以下占位符：

YOUR_API_KEY
YOUR_MODEL_ID
YOUR_ANTHROPIC_BASE_URL
YOUR_RESPONSES_BASE_URL

使用时需要把它们替换成 API 服务控制台提供的真实内容。

注意：不要直接猜模型名称。控制台显示的产品名称和接口实际使用的模型 ID，可能并不完全相同。

---

二、安装 Claude Code

macOS、Linux 和 WSL

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

macOS 也可以通过 Homebrew 安装：

brew install --cask claude-code

Windows PowerShell

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

或者使用 WinGet：

winget install Anthropic.ClaudeCode

安装完成后检查版本：

claude --version

也可以运行诊断：

claude doctor

如果提示找不到 claude 命令，通常需要重新打开终端，让环境变量重新加载。

通过网络脚本安装软件比较方便，但在安全要求较高的环境中，建议先下载并检查脚本内容。

---

三、临时配置 Claude Code

第一次使用建议先配置临时环境变量。关闭终端后配置会自动失效，方便排查问题。

macOS、Linux 和 WSL

export ANTHROPIC_BASE_URL="YOUR_ANTHROPIC_BASE_URL"
export ANTHROPIC_API_KEY="YOUR_API_KEY"
export ANTHROPIC_MODEL="YOUR_MODEL_ID"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="YOUR_MODEL_ID"

Windows PowerShell

$env:ANTHROPIC_BASE_URL="YOUR_ANTHROPIC_BASE_URL"
$env:ANTHROPIC_API_KEY="YOUR_API_KEY"
$env:ANTHROPIC_MODEL="YOUR_MODEL_ID"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="YOUR_MODEL_ID"

Windows CMD

set ANTHROPIC_BASE_URL=YOUR_ANTHROPIC_BASE_URL
set ANTHROPIC_API_KEY=YOUR_API_KEY
set ANTHROPIC_MODEL=YOUR_MODEL_ID
set ANTHROPIC_DEFAULT_HAIKU_MODEL=YOUR_MODEL_ID

这里有三个容易出错的地方：

1. ANTHROPIC_API_KEY 一般通过 X-Api-Key 请求头发送。除非接口文档明确要求，否则不要擅自改成 ANTHROPIC_AUTH_TOKEN。
2. Base URL 应使用服务控制台提供的 Claude Code 或 Anthropic 兼容地址。
3. 通常不要手动在 Base URL 后面添加 /v1/messages，客户端会自行拼接请求路径。

如果只有 OpenAI 格式的 /chat/completions 地址，一般不能直接用于 Claude Code。

---

四、运行并检查 Claude Code

先进入一个用于测试的项目：

cd 你的项目目录
claude

第一次不要直接让它修改整个项目，可以先输入只读任务：

请先不要修改文件。阅读当前项目目录，告诉我它使用了什么技术栈，并列出主要目录的作用。

进入 Claude Code 后，可以使用：

/status

检查当前模型和连接状态。

其他常用命令：

/model
/permissions
/clear

分别用于查看或切换模型、管理权限，以及清理当前对话上下文。

---

五、永久保存 Claude Code 配置

确认临时配置可以正常使用后，再写入配置文件。

配置文件位置：

macOS/Linux：~/.claude/settings.json
Windows：%USERPROFILE%\.claude\settings.json

配置内容：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "YOUR_ANTHROPIC_BASE_URL",
    "ANTHROPIC_API_KEY": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "YOUR_MODEL_ID",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "YOUR_MODEL_ID"
  }
}

如果电脑会与他人共用，不建议把 API Key 直接保存在配置文件中。更稳妥的方法是只保存 Base URL 和模型名称，API Key 通过系统环境变量注入。

macOS 和 Linux 可以限制文件权限：

chmod 600 ~/.claude/settings.json

---

六、安装 Codex CLI

macOS 和 Linux

使用官方安装脚本：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

也可以通过 npm 安装：

npm install -g @openai/codex

macOS 还可以使用 Homebrew：

brew install --cask codex

Windows

Windows 更推荐在 WSL 2 中使用，相关命令和 Linux 相同。

如果已经安装 Node.js，也可以在 PowerShell 中尝试：

npm install -g @openai/codex

安装完成后检查：

codex --version
codex --help

---

七、配置 Codex CLI 的 API Key

这里使用自定义环境变量 CUSTOM_API_KEY。

macOS、Linux 和 WSL

export CUSTOM_API_KEY="YOUR_API_KEY"

Windows PowerShell

$env:CUSTOM_API_KEY="YOUR_API_KEY"

Windows CMD

set CUSTOM_API_KEY=YOUR_API_KEY

环境变量名称可以自行修改，但必须与后面配置文件中的 env_key 完全一致，包括大小写。

---

八、配置 Codex CLI

配置文件位置：

macOS/Linux/WSL：~/.codex/config.toml
Windows：%USERPROFILE%\.codex\config.toml

写入以下内容：

model = "YOUR_MODEL_ID"
model_provider = "custom"
model_reasoning_effort = "medium"

[model_providers.custom]
name = "Custom API"
base_url = "YOUR_RESPONSES_BASE_URL"
env_key = "CUSTOM_API_KEY"
wire_api = "responses"

配置时需要重点检查：

• model 必须填写接口支持的真实模型 ID。
• model_provider 必须和 [model_providers.custom] 中的名称对应。
• env_key 必须和此前设置的环境变量一致。
• wire_api 应设置为 responses。
• Base URL 应使用 OpenAI Responses 兼容地址。
• 通常不要在 Base URL 后手动添加 /responses。
• 不要把真实 API Key 直接写进 TOML 文件。

如果接口只支持 /v1/chat/completions，不一定能正常运行 Codex CLI。它需要的是 Responses API，而不只是普通的 OpenAI Chat Completions 格式。

---

九、运行并检查 Codex CLI

进入测试项目：

cd 你的项目目录
codex

建议第一次先执行只读任务：

请不要修改任何文件。检查当前项目结构，告诉我启动方式、主要依赖和可能需要的环境变量。

然后输入：

/status

检查当前模型、权限和运行状态。

常见命令包括：

/status
/model
/permissions
/review
/init

如果需要让 Codex 修改文件，建议先使用比较保守的权限：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

可以把这两行放在 config.toml 顶层。这样遇到需要额外权限的操作时，工具会先请求确认。

---

十、如何安全测试文件修改

不要一开始就在重要项目中测试。可以建立一个临时 Git 仓库：

mkdir ai-cli-test
cd ai-cli-test
git init

创建一个简单的 README.md 后，再让工具执行：

请在 README.md 中补充项目说明，完成后展示修改内容，但不要提交 Git commit。

修改完成后，在另一个终端检查：

git diff

确认内容没有问题，再决定是否保留。正式项目最好也提前提交现有改动，避免 AI 修改与未提交代码混在一起。

---

十一、常见错误怎么处理

401 Unauthorized

通常表示身份验证失败，检查：

• API Key 是否完整
• Key 是否已经失效
• 环境变量名称是否写错
• 当前终端是否已经加载环境变量
• 接口要求的是 X-Api-Key 还是 Bearer Token

可以先检查变量是否存在，但不要公开完整 Key：

echo ${CUSTOM_API_KEY:+API_KEY 已设置}

403 Forbidden

一般表示 Key 没有对应模型或接口的使用权限。检查模型权限、账户状态和服务端访问策略。

404 Not Found

常见原因：

• Base URL 填错
• 重复添加了 /v1
• 手动添加了 /messages 或 /responses
• 使用了错误的协议地址
• 服务端没有实现对应接口

Claude Code 需要 Anthropic Messages API，Codex CLI 需要 OpenAI Responses API，不能只看域名相同就混用地址。

400 Bad Request

通常说明接口能连接，但请求格式不兼容，例如：

• 模型 ID 不存在
• 服务端不支持某些参数
• Messages API 兼容不完整
• Responses API 的事件格式不完整
• 流式响应格式不符合客户端要求

这种情况不一定是本地配置错误，也可能是接口只兼容了部分协议。

429 Too Many Requests

表示触发了并发或频率限制。可以降低请求频率、减少并行任务，稍后再试。

命令找不到

如果安装成功但提示 command not found，先关闭并重新打开终端，再检查：

which claude
which codex

Windows PowerShell 可以使用：

Get-Command claude
Get-Command codex

---

十二、使用时需要注意的安全问题

API Key 和项目代码都属于敏感信息，建议注意以下几点：

• 不要把 API Key 提交到 Git 仓库。
• 不要把 Key 写进 README、截图或公开日志。
• 测试时不要直接打开包含生产密钥的项目。
• 首次运行先使用只读任务。
• 修改完成后一定检查 git diff。
• 涉及删除文件、安装依赖、执行脚本时仔细确认。
• .env、私钥、证书和生产配置应加入工具的拒绝访问规则。
• 不确定命令用途时，不要直接批准执行。

如果项目中包含敏感文件，可以在 Claude Code 的项目权限配置中禁止读取，例如：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./certs/**)"
    ]
  }
}

这类项目级配置可以放在：

项目目录/.claude/settings.json

总结

配置这两款工具时，最重要的不是复制命令，而是先确认接口协议：

Claude Code → Anthropic Messages API
Codex CLI   → OpenAI Responses API

如果出现问题，建议按照下面的顺序排查：

API Key
→ 环境变量名称
→ Base URL
→ 模型 ID
→ 接口协议
→ 权限和频率限制

先用临时环境变量验证连接，再保存长期配置；先执行只读任务，再允许修改文件。按照这个顺序配置，出现问题时会更容易定位。