Codex 和 Claude Code 接入 API 时，Key、Base URL 和模型权限怎么排查

在 Codex、Claude Code、Cursor 或其他 AI 编程工具里接入模型 API 时，最常见的问题并不是命令本身，而是 Key、Base URL、模型名、Provider 和权限没有对应起来。本文只讨论通用配置和排错思路，不涉及具体账号购买、充值或平台选择。

文章目录

1. AI 编程工具接入 API 时需要哪些信息？
2. 接入前应该先检查什么？
3. Codex 常见配置写法
4. Claude Code 常见配置检查
5. 常见报错和排查顺序

1、AI 编程工具接入 API 时需要哪些信息？

AI 编程工具通常需要通过 API 调用模型。不同工具的字段名称可能不一样，但核心信息大体相同。

信息1：API Key

API Key 是调用模型的凭证，通常以 sk- 开头。它应该保存在本机环境变量或安全配置文件里，不要写进公开仓库，也不要放在截图和文章里。

信息2：Base URL

Base URL 是工具请求模型服务的入口地址。OpenAI-compatible 工具一般使用类似下面的形式：

https://api.example.com/v1

Claude Code 或其他 Anthropic 风格工具可能不使用同一个路径。不要把两种接口格式混用。

信息3：模型名

模型名必须来自当前账号或当前 Key 有权限调用的模型列表。旧教程里的模型名不一定仍然可用，直接照抄很容易出现模型不存在。

信息4：Provider 或接口类型

Codex 这类工具通常可以配置自定义 provider；部分工具还会区分 Responses API、Chat Completions API 或 Anthropic 风格接口。接口类型不匹配时，Key 正确也可能无法调用。

2、接入前应该先检查什么？

正式写配置前，可以先按下面顺序做一次自检。

检查1：Key 是否处于可用状态

进入 API Key 管理页面，确认密钥没有禁用、没有过期、没有被删除，并且当前状态是可用。

图1：API Key 管理页面示例。先确认 Key 状态、分组、用量和操作入口。

检查2：Key 分组是否对应目标工具

不同模型或工具可能对应不同分组。OpenAI-compatible 工具、Claude Code、Gemini CLI 等工具不要混用同一个不匹配的分组。分组不匹配时，常见表现是 403 或模型不可用。

检查3：Base URL 是否和接口风格一致

OpenAI-compatible 工具通常带 /v1，Claude Code 则需要看当前工具要求。不要只复制域名，也不要自己随意补路径。

检查4：本地环境是否能读到配置

终端环境变量只在当前窗口生效。Windows 设置后如果重新打开 PowerShell 才能生效，macOS / Linux 写入 shell 配置文件后也需要重新加载终端。

3、Codex 常见配置写法

Codex 的用户级配置文件通常放在 ~/.codex/config.toml。如果使用自定义兼容接口，可以通过 model_provider 指向一个自定义 provider。

macOS / Linux 创建配置

mkdir -p ~/.codex
nano ~/.codex/config.toml

Windows 创建配置

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\config.toml"

config.toml 示例

model = "your-model-name"
model_provider = "custom-api"

[model_providers.custom-api]
name = "custom-api"
base_url = "https://api.example.com/v1"
env_key = "OPENAI_API_KEY"

图2：一键接入配置示例。重点确认 Base URL、API Key、模型名是否由同一套配置生成。

设置环境变量

macOS / Linux：

export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

Windows PowerShell：

$env:OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

如果希望长期生效，可以写入用户环境变量；如果只是临时测试，当前终端窗口设置即可。

4、Claude Code 常见配置检查

Claude Code 的配置不要直接照搬 Codex。它可能要求不同的环境变量、Base URL 或模型字段。最稳妥的方式是先看当前工具页签或配置说明。

检查 Base URL

Claude Code 使用的 Base URL 应以对应工具说明为准。如果文档明确给出专用地址，就不要套用 OpenAI-compatible 的 /v1 地址。

检查模型权限

Claude Code 要使用支持 Claude 模型的 Key 或分组。拿 OpenAI/Codex 分组去跑 Claude Code，常见结果是 403 或模型不存在。

检查脚本写入位置

有些一键接入脚本会写入用户目录，有些会写入当前项目目录。建议优先使用用户级配置，避免每个项目都重复配置。

图3：Claude Code 配置示例。不要把 Codex 的 OpenAI-compatible 配置直接照搬到 Claude Code。

5、常见报错和排查顺序

401：Key 无效

检查 Key 是否复制完整，是否多了空格，环境变量名是否写对，当前终端是否真的读到了变量。

403：权限不足

优先检查模型权限和分组。Key 本身可用，不代表它能调用所有模型。

404：接口路径错误

检查 Base URL 是否多写或少写了路径。OpenAI-compatible 和 Anthropic 风格接口不要混用。

模型不存在

回到当前模型列表，确认模型名仍然可用。尤其是第三方教程里的模型名，可能已经被替换或下线。

命令能启动但没有响应

检查终端网络、代理、流式输出、超时设置，以及工具是否使用了正确的配置文件。

图片或文档里的 Key 泄露

写教程、截图或发问题时，必须把 Key 打码成 sk-xxxxxxxx。如果真实 Key 已经发出，应立即禁用并重新创建。

最后总结

AI 编程工具接入 API 时，最重要的是确认五件事：Key 可用、Base URL 正确、模型名可用、Provider 匹配、当前终端能读取配置。遇到问题时不要反复重装工具，先按 401、403、404、模型名、环境变量这个顺序排查，通常能更快定位问题。