Skip to content

troubleshooting.md

Latest commit

 

History

History
109 lines (78 loc) · 4.26 KB

troubleshooting.md

File metadata and controls

109 lines (78 loc) · 4.26 KB
Raw

Claude Code 本地模型配置 - 故障排查指南

常见问题与解决方案

1. Unable to connect to Anthropic services

现象: 启动 claude code 后显示红色错误：

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

根因: CC 交互模式启动时有一个前置引导流程（onboarding），会硬连 api.anthropic.com。此流程由 ~/.claude.json 中的 hasCompletedOnboarding 字段控制。

解决:

$f = "$env:USERPROFILE\.claude.json"
$j = Get-Content $f | ConvertFrom-Json
$j | Add-Member -NotePropertyName 'hasCompletedOnboarding' -NotePropertyValue $true -Force
$j | ConvertTo-Json | Set-Content $f

2. 环境变量设了但没生效

现象: $env:ANTHROPIC_BASE_URL 已设置，但 CC 仍然连接错误地址或报认证失败。

原因: ~/.claude/settings.json 中的 env 字段只注入子进程（Bash 工具执行命令时），不影响 CC 主进程的 API 连接。

解决方案优先级:

  1. --settings 文件覆盖（推荐）— 最可靠
  2. setx 写入注册表 — 需重启终端生效
  3. PowerShell Profile — 每次新终端自动加载
  4. 手动设置环境变量 — 仅当前会话有效

3. "The model xxx does not exist" (404)

现象: CC 报 404 错误，说模型不存在。

原因: --settings 文件指向了错误的端点地址。CC 实际连的是 settings 文件中指定的 URL，而不是你期望的那个服务器。

解决:

  • 确认 settings-xxx.json 中的 ANTHROPIC_BASE_URL 与该模型实际运行的服务器一致
  • 用 scripts/test-endpoint.py --url <URL> --model <MODEL> 验证

4. cc-122b / cc-multimodal 命令找不到

现象: 输入 cc-122b 报错：无法将 "cc-122b" 识别为 cmdlet/函数...

原因: Profile 脚本未被加载。

检查步骤:

  1. 确认 Profile 文件路径正确（注意 PowerShell 5 vs 7 的差异）
  2. WinPS 5.x: ~/Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1
  3. PS 7+: ~/Documents/PowerShell/Microsoft.PowerShell_profile.ps1
  4. 确认 Profile 中有 . "$env:USERPROFILE\Documents\PowerShell\claude-models.ps1" 这行
  5. 确认 claude-models.ps1 文件存在于 Documents\PowerShell\ 目录下

临时修复: 手动加载 . $env:USERPROFILE\Documents\PowerShell\claude-models.ps1

5. 交互模式 vs -p 模式行为不同

模式 行为
-p/--print (非交互) 直接发请求，读取环境变量和 --settings
交互模式 (claude code) 先跑 onboarding → 加载 settings → 进入 REPL

通常 -p 更容易成功，因为跳过了 onboarding 步骤。如果交互模式失败但 -p 成功，优先检查 onboarding 配置。

6. 多模态请求返回 400/500

现象: 发送图片给多模态模型时报错。

可能原因:

  1. vLLM 的多模态支持需要特定格式
  2. 图片 base64 编码过大
  3. 模型本身不支持图片输入

调试建议:

  • 先用纯文本确认端点可用
  • 尝试不同的 API 格式（Anthropic vs OpenAI）
  • 缩小图片尺寸（detail=low）

Debug 方法

开启详细日志

claude code --model "MODEL_NAME" --debug-file "$env:TEMP\cc_debug.log"

日志中关注:

  • [API REQUEST] /v1/messages source=sdk — 确认请求发送到了正确的 URL
  • ANTHROPIC_BASE_URL=http://... — 确认环境变量被正确读取
  • 404 {"type":"NotFoundError","message":"The model ... does not exist."} — 模型名或端点不匹配

快速连通性测试

python scripts/test-endpoint.py --url http://10.101.106.100:8000 --model "Intel/Qwen3.5-122B-A10B-int4-AutoRound"

关键文件清单

文件 作用 修改频率
~/.claude.json Onboarding 状态 仅一次
~/.claude/settings-122b.json 122B 端点配置 改端点时
~/.claude/settings-mm.json 多模态端点配置 改端点时
~/.claude/settings.json 默认配置（可选保留） 极少
~/Documents/PowerShell/claude-models.ps1 切换函数定义 添加新模型时
.../Microsoft.PowerShell_profile.ps1 自动加载函数 仅一次