Appearance
Free Claude Code 的常见问题主要集中在：代理 URL 配置错误、上游 Provider 400/500 错误、流式传输中断、工具调用不兼容。本文按错误现象分类，提供排查步骤和解决方案。
Free Claude Code 常见问题排查：代理连接、模型兼容性、流式传输错误
代理连接问题
Claude Code 报 undefined ... input_tokens 或 $.speed
原因：代理返回的流式响应中缺少 usage 元数据，Claude Code 解析失败。
排查步骤：
- 更新到最新版本的 Free Claude Code
- 确认
ANTHROPIC_BASE_URL是http://localhost:8082，没有/v1后缀 - 确认代理在返回 Server-Sent Events（
/v1/messages端点） - 查看代理日志中是否有上游 400/500 错误
VS Code 扩展仍然显示登录页面
原因：扩展环境变量未生效。
排查步骤：
- 确认在 VS Code
settings.json中正确配置了claudeCode.environmentVariables - 重新加载窗口（
Ctrl+Shift+P→Developer: Reload Window） - 如果仍然显示登录页面，走一次 Anthropic Console 登录流程——环境变量生效后，后续请求都会走本地代理
Claude Code 报连接超时
原因：代理未启动或端口不匹配。
排查步骤：
bash
# 确认代理在运行
curl http://localhost:8082/health
# 如果返回 Connection refused，代理没启动或端口不对
# 如果返回 {"status":"healthy"}，检查环境变量配置上游 Provider 问题
llama.cpp 或 LM Studio 返回 HTTP 400
原因：本地服务器不支持 Anthropic Messages 请求格式，或上下文大小不足。
排查步骤：
- 确认本地服务器支持
POST /v1/messages端点 - 确认模型和运行时支持请求的上下文长度和工具
- llama.cpp 用户：增加
--ctx-size参数（至少 8192） - LM Studio / llama.cpp 用户：确认
*_BASE_URL包含/v1后缀
Provider 断开连接（incomplete chunked read / server disconnected）
原因：上游 Provider 或网关超时断开。
排查步骤：
- 减少并发：降低
PROVIDER_MAX_CONCURRENCY - 增大超时：提高
HTTP_READ_TIMEOUT（默认 120 秒） - 等一段时间重试——可能是上游临时限流
- 如果持续断开，换一个 Provider
工具调用在一个模型上能用，另一个不行
原因：工具调用支持是模型和 Provider 相关的。某些模型可能：
- 发送格式错误的工具调用 delta
- 省略工具名称
- 把工具调用当纯文本返回
排查步骤：
- 换一个更大的模型试试
- 换一个 Provider 试试
- 查看代理日志中的原始 SSE 事件（
LOG_RAW_SSE_EVENTS=true）确认上游返回格式
NVIDIA NIM 报 429 Too Many Requests
原因：免费额度的速率限制。
解决：
dotenv
PROVIDER_RATE_LIMIT=1
PROVIDER_RATE_WINDOW=5 # 增大窗口，降低请求频率或等待一段时间后重试。
流式传输问题
响应中途截断
原因：上游 Provider 断开或网络不稳定。
排查步骤：
- 检查代理日志中的错误信息
- 增大
HTTP_READ_TIMEOUT - 检查网络代理配置（
NVIDIA_NIM_PROXY等）
响应速度很慢
可能原因：
- 使用了 thinking 模式（消耗更多 Token，响应更慢）
- 上游 Provider 本身延迟高
- 本地模型机器性能不足
排查：
- 关闭 thinking 模式测试：
ENABLE_MODEL_THINKING=false - 换一个更快的 Provider 或模型
- 检查代理日志中的请求耗时
安全和日志
如何查看详细日志
dotenv
LOG_RAW_API_PAYLOADS=true # 打印原始请求（含 prompt）
LOG_RAW_SSE_EVENTS=true # 打印原始 SSE 响应
LOG_API_ERROR_TRACEBACKS=true # 打印完整错误栈警告：这些选项会暴露 prompt、工具参数、模型输出等敏感信息。仅在本地调试时开启，生产环境务必关闭。
ANTHROPIC_AUTH_TOKEN 不起作用
代理默认不校验 ANTHROPIC_AUTH_TOKEN（用于兼容 Claude Code 的认证流程）。如果你需要真正的鉴权，需要自行修改代理代码添加中间件。
FAQ
Q: 代理日志在哪里看？ A: 代理启动后的控制台输出就是日志。如果用 fcc-init + free-claude-code 方式运行，日志输出到 stdout。
Q: 更新 Free Claude Code 后需要重新配置吗？ A: 不需要。.env 配置文件独立于代码。但如果有新的环境变量（新 Provider 或功能），需要参考 .env.example 补充配置。
Q: 怎么确认请求真的通过了代理？ A: 访问 http://localhost:8082/ 看返回的 provider 和 model 信息。或者在 Claude Code 中发起一个请求，观察代理控制台是否有 MODEL MAPPING 日志。