古法编程

Free Claude Code 使用中的常见报错集中在代理连接配置、上游模型兼容性、流式传输中断及工具调用格式。本文按错误现象分类，提供详细的排查步骤和解决方案，帮助你快速定位并修复问题，确保 Claude Code 稳定运行。

Free Claude Code 常见问题排查：代理连接、模型兼容性、流式传输错误

在部署和使用 Free Claude Code 的过程中，你可能会遇到各种报错。本指南将常见问题分为四大类：代理连接、上游 Provider、流式传输、安全与日志，并提供对应的排查方法。

代理连接问题

这类问题通常与本地代理服务或客户端环境变量配置有关。

Claude Code 报 undefined ... input_tokens 或 $.speed

错误现象：Claude Code CLI 或 IDE 扩展在收到代理响应后报错，提示无法解析 input_tokens 或 speed 字段。

可能原因：代理返回的流式响应（Server-Sent Events）中缺少 Claude Code 预期的 usage 元数据，导致其解析失败。

排查步骤：

  1. 更新代理：确保你使用的是最新版本的 Free Claude Code。
  2. 检查 ANTHROPIC_BASE_URL 配置：这是最常见的错误。该环境变量必须设为 http://localhost:8082，末尾不能有 /v1 后缀。
  3. 确认端点正常：代理的 /v1/messages 端点需要正确返回 SSE 流。
  4. 查看上游错误：检查代理的控制台日志，看上游 Provider 是否返回了 400 或 500 错误，这可能导致代理无法生成完整的 usage 数据。

VS Code 扩展仍然显示登录页面

错误现象：在 VS Code 中配置了环境变量后，打开 Claude Code 扩展依然要求登录 Anthropic 账号。

可能原因：VS Code 环境变量未正确生效，或扩展内部状态缓存了登录请求。

排查步骤：

  1. 核对配置位置：确认环境变量（如 ANTHROPIC_BASE_URL）是在 VS Code 的 settings.json 文件中的 claudeCode.environmentVariables 字段里设置的，而不是在系统环境变量中。更多 IDE 配置细节可参考连接 IDE 配置指南。
  2. 重载窗口：执行 Ctrl+Shift+P，输入并选择 Developer: Reload Window，以使新的配置生效。
  3. 完成一次登录：如果重载后仍显示登录页面，尝试完成一次 Anthropic Console 的登录流程。这会清空内部的认证缓存。之后，只要环境变量正确，所有后续请求都会转发到本地代理。

Claude Code 报连接超时

错误现象：Claude Code 发起请求后，长时间无响应，最终提示连接超时。

可能原因：Free Claude Code 代理服务未启动，或客户端配置的端口与代理实际监听的端口不一致。

排查步骤：

# 使用 curl 测试代理的健康检查端点
curl http://localhost:8082/health
  • 如果返回 Connection refused，说明代理服务没有运行，或运行在了其他端口。请按照安装部署教程检查启动步骤。
  • 如果返回 {"status":"healthy"}，则说明代理运行正常。问题很可能出在客户端的 ANTHROPIC_BASE_URL 配置错误（例如写成了 https 或端口不对），请回到上一节排查。

上游 Provider 问题

当 Free Claude Code 成功接收请求，但在转发给上游模型（如 Ollama, NVIDIA NIM, OpenRouter）时出错，通常会归于此类。

llama.cpp 或 LM Studio 返回 HTTP 400

错误现象：代理日志显示从本地模型服务（如 llama.cpp, LM Studio）收到了 400 Bad Request 错误。

可能原因：本地模型服务器不兼容 Anthropic 的 Messages API 格式，或模型的上下文窗口太小。

排查步骤：

  1. 确认 API 端点：确保你的本地模型服务器暴露的是 OpenAI 兼容的 API 端点（即支持 POST /v1/messages）。
  2. 检查上下文长度：模型加载时设置的上下文大小（context size）必须足够容纳 Claude Code 发送的长 prompt 和工具定义。对于 llama.cpp 用户，需要增加 --ctx-size 参数，建议至少设置为 8192。
  3. 检查 Base URL 后缀：对于 LM Studio 或 llama.cpp，在 .env 文件中配置的 *_BASE_URL（如 OLLAMA_BASE_URL）必须包含 /v1 后缀。例如，http://localhost:1234/v1。

Provider 断开连接（incomplete chunked read / server disconnected）

错误现象：请求过程中，上游 Provider 突然断开连接，代理日志出现 chunked read 不完整或服务器断开的错误。

可能原因：上游 Provider 或中间网关因超时、请求过大或并发限制而主动断开连接。

排查步骤：

  1. 降低并发：在 .env 中调低 PROVIDER_MAX_CONCURRENCY 的值，减少同时发送给同一个 Provider 的请求数。
  2. 增大超时：提高 HTTP_READ_TIMEOUT 的值（默认为 120 秒），给予上游 Provider 更多的响应时间。
  3. 重试或更换：等待一段时间后重试，这可能是临时限流。如果问题持续，考虑切换到另一个 Provider。

工具调用在一个模型上能用，另一个不行

错误现象：同一个代码库，使用某个模型时工具调用（如文件读写）正常，换另一个模型就报错或返回乱码。

可能原因：不同模型和 Provider 对工具调用的支持程度和实现方式不同。有些模型可能会：发送格式错误的工具调用 delta；在工具调用响应中省略工具名称；或者干脆把工具调用当作纯文本返回。

排查步骤：

  1. 更换模型：优先尝试参数更大的模型，它们通常对工具调用的支持更完善。
  2. 更换 Provider：同一个模型通过不同 Provider（如直接用 NVIDIA NIM 和通过 OpenRouter）路由，行为可能不同。
  3. 启用原始日志：在 .env 中设置 LOG_RAW_SSE_EVENTS=true，然后重现问题。查看代理日志中打印的原始 SSE 事件，确认上游返回的工具调用数据格式是否正确。

NVIDIA NIM 报 429 Too Many Requests

错误现象：使用 NVIDIA NIM 作为后端时，频繁收到 429 速率限制错误。

可能原因：NVIDIA NIM 的免费套餐有严格的请求频率限制。

解决方法：在 .env 文件中配置速率限制，主动降低请求频率。

PROVIDER_RATE_LIMIT=1
PROVIDER_RATE_WINDOW=5    # 将窗口从默认的 1 秒增大到 5 秒

或者，暂时停止请求，等待一段时间配额重置后再试。

流式传输问题

响应中途截断

错误现象：模型的输出在显示过程中突然中断，不再继续。

可能原因：上游 Provider 在流式传输过程中异常断开，或本地网络不稳定。

排查步骤：

  1. 检查代理日志：查看日志中是否有来自上游的错误信息。
  2. 增大读取超时：提高 HTTP_READ_TIMEOUT 的值。
  3. 检查网络配置：如果你的网络环境需要通过代理访问上游 Provider（如使用 NVIDIA_NIM_PROXY），请确保该配置正确。

响应速度很慢

可能原因：

  • 启用 Thinking 模式：该模式会生成更多思考过程的 Token，导致整体响应变慢。
  • 上游延迟：Provider 本身处理请求的速度慢。
  • 本地性能：如果使用本地模型，机器的 CPU/GPU 性能不足。

排查步骤：

  1. 关闭 Thinking：在 .env 中设置 ENABLE_MODEL_THINKING=false，测试速度是否改善。
  2. 更换 Provider/模型：尝试其他更快的上游服务。
  3. 查看耗时日志：检查代理日志，关注每个请求从发起到完成的总耗时。

安全和日志

如何查看详细日志

当遇到难以诊断的问题时，可以开启详细的调试日志。在 .env 文件中添加以下配置：

LOG_RAW_API_PAYLOADS=true    # 打印发送给上游的完整请求 JSON（包含 prompt 和工具参数）
LOG_RAW_SSE_EVENTS=true      # 打印从上游收到的原始 SSE 事件流
LOG_API_ERROR_TRACEBACKS=true # 打印完整的 Python 错误栈信息

警告：这些选项会将用户 prompt、工具调用参数、模型输出等敏感信息打印到日志中。仅在本地调试时临时开启，生产环境务必关闭。

ANTHROPIC_AUTH_TOKEN 不起作用

Free Claude Code 代理默认会忽略客户端发送的 ANTHROPIC_AUTH_TOKEN，仅将其作为日志记录或透传，不进行真正的鉴权校验。这样设计是为了兼容 Claude Code 客户端的认证流程。如果你需要为代理添加真正的访问控制，需要自行修改代理代码，添加鉴权中间件。

FAQ

Q: 代理日志在哪里看？ A: 代理启动后，所有日志会直接输出到启动它的控制台（stdout）。如果你是通过 fcc-init 和 free-claude-code 命令运行的，日志就在运行该命令的终端窗口里。

Q: 更新 Free Claude Code 后需要重新配置吗？ A: 不需要。你的配置（.env 文件）是独立于代码仓库的。更新代码后，原有的 .env 文件会保留。但是，如果新版本引入了新的环境变量（例如增加了新的 Provider 支持），你可能需要对照 .env.example 文件，将新增的配置项补充到你的 .env 中。

Q: 怎么确认请求真的通过了代理？ A: 有两个方法：1) 在浏览器中访问 http://localhost:8082/，它会返回当前代理配置的 provider 和 model 信息。2) 在 Claude Code 中发起一个请求，观察代理的控制台日志。如果请求被正确转发，日志中会出现类似 MODEL MAPPING 的条目，显示请求被路由到了哪个后端模型。