常见问题 FAQ

Claude Code 问题汇总

Codex 问题汇总

Claude Code

API 密钥无效（InvalidAPIKey 错误）

Mac/Linux — 检查以下文件：

  • ~/.claude/settings.json
  • ~/.claude.json

Windows — 按 Win + R 输入 %USERPROFILE%，检查以下文件：

  • %USERPROFILE%\.claude\settings.json
  • %USERPROFILE%\.claude.json

确认以下配置项正确：

json 
"ANTHROPIC_API_KEY": "您的API密钥"
"ANTHROPIC_BASE_URL": "https://yyken.com"

如有错误，请参考对应教程的"配置 API 密钥"章节重新配置。

启动报错：command not found

重新安装 Claude Code：

bash 
npm install -g @anthropic-ai/claude-code --ignore-scripts

如何重新安装 Claude Code

卸载：

bash 
npm uninstall -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

重新安装：

bash 
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

重新安装后，请参考教程的"配置认证绕过"章节完成认证配置。

Windows 完全清理（可选）：

powershell 
if (Test-Path "$HOME\.claude.json") { Remove-Item "$HOME\.claude.json" -Force }
if (Test-Path "$HOME\.claude")      { Remove-Item "$HOME\.claude" -Recurse -Force }

配置完依旧显示 Not logged in · Please run /login

请确认是否在配置步骤中选择了 recommended。

⚠️ 注意：如果出现推荐配置页面，需要选 yes 来应用密钥。

如果选错了，请删除 .claude 目录和 .claude.json 后重新配置即可。

提示 Claude's response exceeded the 32000 output token maximum

Claude Code 默认限制单次响应最多输出 32000 个 token。当处理较大文件或生成较长内容时会触发此限制。

解决方法： 设置环境变量 CLAUDE_CODE_MAX_OUTPUT_TOKENS 来提高上限。

Mac/Linux：

bash 
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

永久生效，添加到 ~/.zshrc 或 ~/.bashrc：

bash 
echo 'export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000' >> ~/.zshrc
source ~/.zshrc

Windows（PowerShell）：

powershell 
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_MAX_OUTPUT_TOKENS", "64000", "User")

设置后重启 Claude Code 生效。

VS Code 插件配置了 key 和 url 后仍跳转官网登录页

原因： Claude Code for VS Code 插件默认会弹出登录提示，即使已配置 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL 也会触发。

解决方法： 在 ~/.claude/settings.json 中添加以下配置：

json 
"claudeCode.disableLoginPrompt": true

添加后重启 VS Code 即可正常使用。

出现网络相关错误怎么办？

  • 检查是否启用了代理，可尝试关闭代理或者切换节点后重试
  • 按 Esc 退出终端，重新打开后再试
  • 尝试切换密钥分组

出现 401 错误或提示令牌过期、余额不足怎么办？

  • 登录后台检查密钥状态，确认余额充足、密钥未过期
  • 确认 ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL 配置正确
  • 如配置有误，参考对应教程的"配置 API 密钥"章节重新配置

出现 400 错误怎么办？

400 错误一般为官方临时 Bug，新开终端重试即可。

Claude Code 新版本缓存命中问题导致消耗变大怎么办？

Claude Code 官方新版本存在缓存命中问题，会导致 token 消耗异常增大。建议降级到稳定版本 2.1.77。

卸载当前版本：

bash 
npm uninstall -g @anthropic-ai/claude-code

安装指定版本：

bash 
npm install -g @anthropic-ai/claude-code@2.1.77

Claude Code 突然输出韩语/日语怎么办？

Claude Code 有时会无故切换输出语言（如韩语、日语），这是模型的偶发行为，可能是因为上下文太大出现的幻觉。

解决方法： 在 ~/.claude/CLAUDE.md 中添加语言规范配置，强制模型使用中文回复。

bash 
mkdir -p ~/.claude && cat >> ~/.claude/CLAUDE.md << 'EOF'

# 语言规范

| 场景 | 语言 |
|------|------|
| 对话、解释、计划 | 中文 |
| Commit Message | 英文 (`feat:`, `fix:`, `docs:` 等) |
| 代码注释、README | 英文（除非有特殊说明） |
EOF

添加后重启 Claude Code 即可生效。

使用 TokenPan 中转服务时无法开启 Auto Mode 怎么办？

Auto Mode 是 Claude Code 的自动权限模式，Anthropic 官方限制了只有通过官方 API 才能使用，通过 TokenPan 等第三方中转服务接入时默认被锁定。

请参考 Claude Code Auto Mode 解锁教程 通过补丁工具解除此限制。

Codex

401 报错

原因： 配置文件格式有问题或密钥错误。

解决方法：

  1. 检查 config.toml 和 auth.json 文件格式是否正确
  2. 确认密钥已正确复制（无多余空格或特殊字符）

config.toml 标准配置：

toml 
model_provider = "tokenpan"
model = "gpt-5.2-codex"
model_reasoning_effort = "xhigh"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.tokenpan]
name = "tokenpan"
base_url = "https://yyken.com/v1"
wire_api = "responses"
requires_openai_auth = true

auth.json 标准配置：

json 
{
  "OPENAI_API_KEY": "你的密钥"
}

如何验证 Codex 配置是否成功

bash 
codex --version

显示版本号即表示安装成功。

Model metadata for 'gpt-5.5' not found 报错

出现如下提示：

bash 
Model metadata for 'gpt-5.5' not found. Defaulting to fallback metadata; this can degrade performance and cause issues

原因： codex 124.0 的模型列表没有更新，需要手动补充模型元数据文件。

解决方法：

第一步： 下载模型元数据文件并解压，得到 model-catalog.gpt-5.5.json。

第二步： 将文件放到 .codex 配置目录：

  • Mac/Linux： 放到 ~/.codex/ 目录下
  • Windows： 放到 %USERPROFILE%\.codex\ 目录下

第三步： 在 config.toml 中添加以下参数：

toml 
model_catalog_json = './model-catalog.gpt-5.5.json'

第四步： 重启 Codex，输入 /model，即可看到 gpt-5.5 出现在模型列表中。