故障排查

命令不存在

先关闭并重新打开终端，再执行版本检查：

Shell复制

claude --version
codex --version

• Windows 安装器通常将命令放在用户目录下。Claude Code 的默认位置是 %USERPROFILE%\.local\bin。
• macOS 安装器通常使用 ~/.local/bin。确认该目录位于 PATH 中。
• Windows 中运行 irm 报错时，请确认当前窗口是 PowerShell，而不是 CMD。

返回 401

401 表示 API Key 缺失、错误、已撤销或所属用户已被禁用。

1. 确认请求头格式是 Authorization: Bearer <YOURAN_API_KEY>。
2. 前往访问密钥确认 Key 仍然有效。
3. 不要使用上游服务的 Key，也不要把控制台登录密码当作 API Key。
4. 如果怀疑泄露，立即撤销并创建新 Key。

模型无效

重新查询实时模型列表，并完整复制 data[].id：

Shell复制

curl -sS https://youran-ai.du-fu.com/api/models \
  -H "Authorization: Bearer <YOURAN_API_KEY>"

Claude Code 需要同步更新 ANTHROPIC_MODEL、三个 ANTHROPIC_DEFAULT_*_MODEL 和 CLAUDE_CODE_SUBAGENT_MODEL。Codex 需要更新 config.toml 顶部的 model。

Base URL 错误

两个客户端都应使用以下地址，不要额外追加 /v1：

Base URL复制

https://youran-ai.du-fu.com/api

• Claude Code 会自行追加 /v1/messages。
• Codex 的 wire_api = "responses" 会自行调用 /responses。
• 如果写成 /api/v1，最终路径会重复并返回 404。

环境变量没有生效

• Windows：执行 $env:YOURAN_API_KEY 或 $env:ANTHROPIC_BASE_URL 检查当前 PowerShell 会话。
• macOS：执行 echo "$YOURAN_API_KEY" 或 echo "$ANTHROPIC_BASE_URL" 检查当前终端。
• 用户级变量写入后，重新打开终端最稳妥。不要把完整 Key 粘贴到故障截图中。

Codex 没有使用悠然 AI

确认 ~/.codex/config.toml 中同时存在：

TOML复制

model_provider = "youran"

[model_providers.youran]
base_url = "https://youran-ai.du-fu.com/api"
env_key = "YOURAN_API_KEY"
wire_api = "responses"

Provider 和凭据来源必须配置在用户级文件中。Codex 会忽略项目级 .codex/config.toml 中用于改写 Provider 或鉴权的设置。

流式响应中断

1. 先使用非流式请求验证鉴权和模型。
2. 检查终端、公司代理或安全软件是否会缓冲 SSE。
3. 确认客户端没有删除 anthropic-version 或 anthropic-beta 请求头。
4. 前往控制台的请求记录查看 HTTP 状态和请求 ID，再联系管理员定位上游错误。