先确认请求走的是哪条链路
接到“Claude Code 连不上局域网网关”这类问题,我一般不会先改配置,而是先确认当前请求发到了哪里。很多配置看起来改了,实际还在走默认接口,现象是启动正常,一问就报连接超时或 401。
当 Claude Code 需要连接局域网内的 AI 网关时,优先检查环境变量 ANTHROPIC_BASE_URL。默认情况下,Claude Code 会请求 Anthropic 官方接口,而通过将 ANTHROPIC_BASE_URL 指定为局域网网关的地址,例如 http://192.168.1.10:8080,即可将请求转发到内部网关。注意,网关必须实现 Anthropic 兼容的 /v1/messages 端点,否则会出现 404 错误。设置后,可运行 claude 命令,观察启动日志中是否显示正在使用自定义 base URL,以此判断配置是否生效。
容易被代理变量带偏
如果设了 ANTHROPIC_BASE_URL 还连不上,我会先查 http_proxy、https_proxy。这个坑很容易误判成网关地址写错。
常见坑是系统设置了 HTTP_PROXY 环境变量,导致请求被转发到代理服务器而不是直连局域网网关。Claude Code 基于 Node.js,会遵循 http_proxy 和 https_proxy 设置。如果网关在局域网内,代理可能无法访问该内网地址,导致连接超时。解决办法是启动时临时清除代理变量:env -u http_proxy -u https_proxy claude。另外,若网关只接受 HTTP 而 Claude Code 请求为 HTTPS,可设置 ANTHROPIC_BASE_URL 为 http:// 前缀,但要注意混合内容可能被安全策略拦截。
排查时先执行 env | grep -i proxy 看是否有残留代理变量,再决定要不要清空。临时清空比反复改配置更快。
验证网关可访问后再谈认证
配置网关前,先用 curl 验证目标地址是否可访问。例如执行 curl http://192.168.1.10:8080/v1/messages -H "x-api-key: test",如果返回 JSON 错误或超时,说明网关服务未就绪或防火墙阻止了端口。另一种常见坑是网关只绑定了 127.0.0.1,仅本机可访问,需要将监听地址改为 0.0.0.0 才能在局域网内暴露。同时要确认防火墙规则,避免 8080 端口被默认拦截。
连通性确认没问题,再看认证方式。局域网网关若需要 API 密钥认证,Claude Code 通过 ANTHROPIC_API_KEY 环境变量传递密钥。如果网关使用自定义的认证机制(如 Bearer Token),可将令牌直接设为 API Key,但要注意令牌不应带有换行或引号。若网关需要额外的 header,Claude Code 本身不支持自定义 header,需要通过反向代理或修改代码实现,因此最简单的方案是网关兼容 Anthropic 的认证方式,即读取 x-api-key 请求头。
配置文件持久化要分清优先级
环境变量测试通过后,再考虑写配置文件。这个顺序能避免改错路径后还要回滚。
除了环境变量,Claude Code 通常支持在用户配置目录下的 settings.json 中设置 apiBaseUrl 字段。不过不同版本的配置优先级可能不同,环境变量不一定总是覆盖配置文件。我的习惯是先用 export 方式跑通,再写入配置文件。写完启动 claude,如果日志仍然显示官方接口,优先怀疑配置文件没被加载,而不是网关又出问题。
安全边界和后续维护
网关能连通、认证也能通过之后,还要看监听范围。将 AI 网关部署在局域网时,务必限制监听范围,不要使用 0.0.0.0 绑定在公网可达接口。建议在网关上设置 IP 白名单或防火墙规则,仅允许公司内部网段访问。同时,由于局域网内传输可能被嗅探,如网关支持 HTTPS,应启用 TLS 证书;若使用 HTTP 明文传输,则需确保网络环境可信,避免敏感对话内容泄露。在配置 Claude Code 时,不要将含密钥的启动命令写入 shell 历史,可用环境变量文件并设置权限。
回滚时,把 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY 从当前终端 unset,或者删除 settings.json 里新增的 apiBaseUrl 字段,再启动 claude 就能回到默认接口。后续维护主要看两处:一是局域网网关升级后 /v1/messages 的响应格式是否变化,二是 Claude Code 更新后配置优先级是否调整。出现异常时,先看启动日志里的 base URL 和实际请求地址,这一步能过滤掉一大半环境问题。