使用文档问题排查

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

按 Key、Base URL、额度、模型和环境变量排查连接失败。

排查问题

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

认证失败

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

额度不足

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

请求无响应

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

模型不可用

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

常见错误

unable to connect to anthropic services

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

相关教程：Claude Code 工具接入教程

failed to connect to api.anthropic.com: err_bad_request

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

相关教程：Anthropic err_bad_request 排查教程

codex unexpected status 401 unauthorized

现象: Codex CLI 返回 401 unauthorized，通常还没有进入模型执行阶段。
原因: 常见原因是 auth.json 里的密钥不完整或不是 CoderPlan 的 `sk-` 密钥、config.toml 语法错误导致配置静默失效、账户 API 使用额度不可用，或当前模型不在账户权限范围内。
检查步骤: 确认 `~/.codex/auth.json` 是合法 JSON，OPENAI_API_KEY 为完整的 CoderPlan 密钥。
确认 `~/.codex/config.toml` 语法正确、base_url 以 `/v1` 结尾，并清理旧教程残留的 OPENAI_BASE_URL 环境变量。
到 CoderPlan 控制台确认 API Key 未删除、API 使用额度可用、模型状态正常。

常见问题

连接失败时应该先改哪一项配置？

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

为什么错误里还会出现官方 API 域名？

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

联系技术支持