AI帮助文档 main troubleshooting/common-problems.md

title: 常见问题排查 description: 汇总 AI Agent、ARAI 中转站、Codex、Claude Code 和 CC Switch 的常见入门问题和排查顺序。 keywords:

  • AI Agent 排错
  • Codex 排错
  • Claude Code 排错
  • ARAI 排错

常见问题排查

遇到问题时，不要一上来就重装。先按账号、订阅、API Key、工具配置、网络和平台状态的顺序排查，通常能更快找到原因。

推荐排查顺序

  1. 账号是否能登录。
  2. 订阅或额度是否有效。
  3. API Key 是否正确、启用、没有泄露。
  4. 客户端配置是否使用了正确地址和模型。
  5. 当前网络是否能访问平台。
  6. 平台公开状态是否正常。
  7. 工具本身是否安装成功。

常见问题排查顺序

ARAI 调用失败

先检查：

  • 是否能登录 https://ai.feinian.net。
  • 订阅是否有效。
  • 额度是否足够。
  • API Key 是否还存在且启用。
  • 公开状态页是否有异常提示。
  • 最近调用记录是否显示错误原因。

如果错误发生在登录后控制台，保留错误信息和订单或调用时间，再联系平台支持。

ARAI 错误示例

Codex 不能正常工作

先检查：

  • 是否已经登录 Codex。
  • 当前工作目录是否正确。
  • 项目是否被信任。
  • 权限策略是否允许读取或修改文件。
  • 配置文件 ~/.codex/config.toml 是否最近改过。
  • 如果使用中转站或第三方 Key，API 地址和 Key 是否正确。

Codex 国内网络排查

Codex 的问题要先分成两类：安装问题 和 模型调用问题。codex --version 能输出版本号，只能说明 CLI 安装成功，不代表 ChatGPT、OpenAI API、ARAI 或其他模型服务已经能调用。

安装阶段

先检查：

  • npm 国内镜像是否可访问：https://registry.npmmirror.com
  • 是否已经设置 npm 镜像：
npm config get registry

如果输出不是 https://registry.npmmirror.com/，可以重新设置：

npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex
codex --version

如果你使用官方脚本，注意它可能跳转到 GitHub Release：

  • macOS / Linux：https://chatgpt.com/codex/install.sh
  • Windows：https://chatgpt.com/codex/install.ps1
  • GitHub Release：https://github.com/openai/codex/releases/latest

这些地址在国内网络下可能不稳定。打不开时优先回到 npm 镜像安装，不要一开始就反复重装系统或终端。

调用阶段

安装成功后，再检查：

  • 如果使用 ChatGPT 登录，当前网络是否能稳定访问 ChatGPT。
  • 如果使用 OpenAI API Key，当前网络是否能访问 OpenAI API。
  • 如果使用 ARAI/API 中转站，是否能打开 https://ai.feinian.net。
  • ARAI 订阅、额度和 API Key 是否有效。
  • CC Switch 是否已经把正确供应商应用到 Codex。
  • Codex 是否在重新打开后读取了最新配置。
  • ARAI 控制台调用记录是否出现对应请求。

如果 npm 能安装、codex --version 正常，但请求模型时报错，重点排查 API Key、API 地址、模型名、订阅额度和当前网络，不要把它当成安装失败。

App、IDE 和 Cloud

Codex App、IDE 扩展和 Cloud 入口都可能受网络影响：

  • macOS Apple Silicon App：https://persistent.oaistatic.com/codex-app-prod/Codex.dmg
  • macOS Intel App：https://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg
  • Windows App：https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi
  • VS Code 扩展：vscode:extension/openai.chatgpt
  • Cursor 扩展：cursor:extension/openai.chatgpt
  • Windsurf 扩展：windsurf:extension/openai.chatgpt
  • Marketplace：https://marketplace.visualstudio.com/items?itemName=openai.chatgpt
  • Codex Cloud：https://chatgpt.com/codex
  • Cloud 环境设置：https://chatgpt.com/codex/settings/environments

这些入口打不开时，国内用户优先按本地 Codex CLI + ARAI/API 中转站 + CC Switch 路线排查。

Claude Code 不能正常工作

先检查：

  • 命令是否能启动。
  • 是否已经登录。
  • 当前目录是否是你要处理的项目。
  • 网络是否能访问服务。
  • 账户权限和额度是否可用。
  • 如果通过中转站接入，地址、Key 和模型配置是否匹配。

CC Switch 切换后没生效

先检查：

  • 供应商配置是否保存。
  • 是否已经应用到目标工具。
  • 目标工具是否需要重新启动。
  • 是否切到了正确供应商。
  • 配置里的 API 地址和 Key 是否来自同一个平台。
  • 是否多个配置名称太像，导致选错。

CC Switch 切换未生效检查位置

API Key 相关问题

错误表现 可能原因
未授权 Key 错误、被禁用或复制不完整。
额度不足 订阅过期或额度用完。
模型不存在 模型名写错或当前平台不支持。
请求超时 网络、上游或平台状态异常。
调用记录异常 Key 可能被多个工具共用或泄露。

什么时候联系支持

这些情况适合联系平台或工具支持：

  • 支付成功但订阅没有生效。
  • 控制台显示的订单状态异常。
  • 公开状态正常，但调用记录持续报平台侧错误。
  • 按文档检查后仍无法确认原因。

联系支持时提供：

  • 发生时间。
  • 使用的平台或工具。
  • 错误截图，注意遮住 API Key。
  • 套餐或订单信息。
  • 你已经尝试过的排查步骤。

相关页面