Skip to content

问题解决(排障) ​

按出现频率从高到低排列,从上往下对照。

排查前先做一件事

先打开 服务运行状态。服务端在维护或故障时,本地怎么改配置都没用,等恢复即可。

1) 报错:401 无效的令牌 ​

完整报错类似:401 {"error":{"code":"","message":"无效的令牌 (request id: xxxxxxxxxx)","type":"..."}}

这是 CcodeZH 官方教程点名的高频问题,通常原因是:

  • 配置缺少 apiKeyHelper 或多了 apiKeyHelper

解决:

  1. 打开 ~/.claude/settings.json
  2. 确认是否存在 apiKeyHelper:存在则删除,不存在则添加
  3. 调整 apiKeyHelper 后仍然报 401,在 Claude Code 控制台输入 /logout 退出,然后重新进入。部分情况下是本地缓存仍在使用之前的 key,退出后重新进入可让它重新读取配置。

参考写法(把密钥替换掉):

json
{
  "apiKeyHelper": "echo 'sk-替换为你的 API Key'",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.ccodezh.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-替换为你的 API Key"
  }
}

2) 报错:Unable to connect to Anthropic services ​

优先检查:

  1. API Key 是否复制完整(是否多了空格/换行)
  2. ANTHROPIC_BASE_URL 是否写错(是否漏了 https://)
  3. 是否编辑错了文件位置(Windows 的 ~ 要换成 %USERPROFILE%)
  4. 修改配置后是否重启了终端/VSCode

3) 找不到 ~/.claude 目录 / 配置文件不生效 ​

Claude Code 往往在首次运行后才会创建配置目录。先执行一次:

bash
claude

然后再去 ~/.claude/ 里创建/编辑 settings.json、config.json。

4) npm install -g 提示 permission denied / 权限不足 ​

常见解法:

  • Windows:用管理员运行 PowerShell 再执行安装命令
  • macOS / Linux:建议使用 nvm 安装 Node.js,避免系统级权限问题
  • 或者把 npm 全局目录改到用户目录(适合不想折腾 nvm 的人)

5) Windows 执行脚本被拦截(PowerShell ExecutionPolicy) ​

如果你使用控制台「一键配置脚本」时遇到执行策略限制,可以尝试(仅当前用户):

powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

执行策略属于系统安全设置,请确保脚本来源可信后再执行。

6) 首次启动卡在引导/反复提示未完成 onboarding(可选) ​

有些环境下(尤其是改过网络或配置后)可能出现引导状态异常。可以尝试:

  1. 打开 ~/.claude.json(Windows 为 %USERPROFILE%\.claude.json)
  2. 在 JSON 顶层增加或修改:
json
{
  "hasCompletedOnboarding": true
}

不熟悉 JSON,建议用 VSCode 打开该文件修改,避免漏逗号导致格式错误。

7) VSCode 插件不生效 ​

按这个顺序排查:

  1. 先确保 CLI 可用:claude 能正常对话
  2. 再检查 ~/.claude/settings.json 是否包含 apiKeyHelper
  3. 最后重启 VSCode

8) 报错:400 Invalid signature in thinking block ​

使用扩展思考(Extended Thinking)功能时可能出现此错误,具体表现为:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.7.content.0: Invalid `signature` in `thinking` block"},"request_id":"req_xxxxxxx"}

原因:会话历史文件中保存了损坏的 thinking 块签名,重新发送时服务端校验失败。

解决步骤:

  1. 退出 Claude Code

  2. 找到对话历史文件

bash
# macOS / Linux
ls -la ~/.claude/projects/

# Windows
dir %USERPROFILE%\.claude\projects\

在对应项目目录下找到最新/最大的 .jsonl 文件。

  1. 备份并修复文件(将路径替换为实际文件路径)
python
import json

filepath = "/path/to/your/session.jsonl"

with open(filepath, 'r') as f:
    lines = f.readlines()

with open(filepath, 'w') as f:
    for line in lines:
        if not line.strip():
            continue
        data = json.loads(line)
        if 'message' in data and 'content' in data['message']:
            if isinstance(data['message']['content'], list):
                data['message']['content'] = [
                    c for c in data['message']['content']
                    if c.get('type') not in ('thinking', 'redacted_thinking')
                ]
        f.write(json.dumps(data) + '\n')
  1. 重启 Claude Code,执行 /resume 恢复之前的对话记录即可继续。

参考来源:GitHub Issue #10199

9) Claude Code 没有 ToolSearch 工具 ​

现象:问 Claude Code「你可以使用 toolsearch 吗」,回答「我没有一个叫 toolsearch 的工具」。

背景:Claude Code v2.0.76 新增了 Tool Search 功能——工具按需延迟加载,大幅降低初始 token 占用(启用了大量 MCP 的用户体感最明显)。但早期版本加了一个地址校验,只有请求地址是 api.anthropic.com(即官方订阅)时才允许开启,使用第三方 API 服务的用户无法享受此功能。该限制已在 v2.0.76 中作为 bug 修复,现在任何 API 地址都可以手动开启。

解决:在 ~/.claude/settings.json 的 env 中加入 ENABLE_TOOL_SEARCH:

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.ccodezh.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-替换为你的 API Key",
    "ENABLE_TOOL_SEARCH": "true"
  }
}

保存后重启 Claude Code 生效。

验证是否开启:启动后直接问 Claude「你可以使用 toolsearch 吗」,如果回答「可以,我有一个 ToolSearch 工具……」则说明已成功开启。