AI 编程工具连接失败排查教程

按 API Key、Base URL、余额、模型和环境变量排查 Claude Code、Codex CLI、Cursor 的连接失败。

排查问题

连接失败时不要同时改多项设置。按 API Key、Base URL、余额、模型可用状态、工具环境变量的顺序检查，大多数问题都能定位到密钥、endpoint 或权限配置。

检查 API Key 是否多复制空格、是否少复制字符、是否使用了过期或已删除的密钥。

进入控制台查看余额。CoderPlan 按真实模型调用扣费，余额不足时工具会直接请求失败。

检查服务地址是否填写正确，并确认工具没有仍在使用之前保存的旧配置。

查看价格页确认模型是否可用。任务不复杂时，可以先切换到基础模型验证链路。

现象: Claude Code 启动或发起任务时提示无法连接 Anthropic 服务，任务还没进入模型调用阶段。
原因: 工具可能仍在请求默认 Anthropic 服务地址，或 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、网络配置没有被当前终端会话读取。
检查步骤: 确认当前终端里的 ANTHROPIC_BASE_URL 指向 CoderPlan endpoint。
确认 ANTHROPIC_AUTH_TOKEN 使用 CoderPlan 控制台生成的完整 `sk-` 密钥。
重开终端后打印环境变量，排除旧 shell、IDE 或配置文件覆盖。

现象: 错误信息里仍然出现 `api.anthropic.com`，并带有 `err_bad_request` 或请求格式错误。
原因: Base URL 没有切到 CoderPlan，或者工具把 Anthropic 原生地址和 CoderPlan API Key 混用，导致服务端拒绝请求。
检查步骤: 检查工具配置文件中是否还有 `api.anthropic.com`。
确认 Base URL 字段没有漏填、拼错或被项目级配置覆盖。
把请求缩小到单个短提示词，先验证 endpoint 和认证，再恢复复杂任务。

现象: Codex CLI 返回 401 unauthorized，通常还没有进入模型执行阶段。
原因: 常见原因是 OPENAI_API_KEY 不完整、环境变量没有生效、账户余额不可用，或当前模型不在账户权限范围内。
检查步骤: 打印 OPENAI_BASE_URL 和 OPENAI_API_KEY 的前缀，确认当前 shell 读取的是新配置。
到 CoderPlan 控制台确认 API Key 未删除、余额可用、模型状态正常。
确认 Codex CLI 没有读取项目里的旧 `.env`、全局配置或系统 keychain。

先不要同时改多项。按 API Key、Base URL、余额、模型可用状态、工具环境变量的顺序检查，每改一项就重新跑一次小请求。

这通常说明工具仍在读取旧 endpoint 或默认配置。检查全局配置、项目 `.env`、IDE 环境变量和当前 shell，确认它们没有互相覆盖。