Claude Code永久配置自定义API地址与密钥技巧-北京尧图网络

一说到把 Claude Code 的模型地址和密钥“永久”换成自己的很多人第一反应是去改某个配置文件。但真正动手之后才发现官方文档里讲得比较分散加上不同操作系统、不同网关服务的写法还不一样很容易绕晕。我前前后后给团队配置过好几轮踩了不少坑这篇就把整个过程按“概念 → 配置方式 → 实战场景 → 排错”理一遍照着做基本一次就能生效。整个配置的核心是搞清楚两个词**API Base URL接口基地址**和API Key密钥。只要这两个地方配对了Claude Code 就能把请求发到你自己的服务上而不是默认的 Anthropic 官方接口。至于“永久”靠的是把配置写进环境变量或 Claude Code 自己的配置文件里而不是每次开会话前临时手动 export。1. 先弄懂 Claude Code 的 API 配置原理1.1 三个关键变量Claude Code 本身只是一个命令行编码工具它的模型调用逻辑是通过读取三个环境变量来决定的ANTHROPIC_BASE_URL模型接口的基地址默认指向 Anthropic 官方 API。ANTHROPIC_AUTH_TOKEN自定义网关或第三方服务时用的认证令牌。ANTHROPIC_API_KEYAnthropic 官方 API Key。正常联网使用官方服务时只需要配置好ANTHROPIC_API_KEY就能跑。但如果想把请求转到自己的网关、内部服务或本地模型你就要动ANTHROPIC_BASE_URL这个变量。这里有一个容易混淆的点ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY并不是二选一的关系。Claude Code 的处理逻辑大致是设置了ANTHROPIC_AUTH_TOKEN它就按“自定义网关的 Bearer Token”去认证。设置了ANTHROPIC_API_KEY它就按“Anthropic 官方 x-api-key 头”去认证。接官方 API 时用后者接自建网关或第三方兼容服务时用前者大多数情况是二选一。如果你不确定自己的服务走哪种认证就看后台生成密钥时给的是“API Key”还是“Token”两者的请求头格式不一样。1.2 为什么只能改这两个东西从底层看Claude Code 本质上就是一个对话式编程助手它把输入内容封装成 HTTP 请求发送给指定接口。你改 Base URL 就等于是告诉它“去哪个门牌号找人”改密钥就等于是“进门时出示什么证件”。这两项是启动时读取的一旦配置好了整个会话过程都会生效。很多人在这一步卡住是因为只改了 URL 没改认证方式接口直接返回 401 或 403。后面排错部分我会专门讲这个。1.3 配置文件优先级Claude Code 加载配置的顺序大致是系统环境变量。用户级配置文件~/.claude/settings.json。项目级配置文件.claude/settings.json。如果同一变量在多个地方都有值系统环境变量通常优先。这也是很多人改了项目的.claude/settings.json却没生效的原因——你终端里正好已经导出了更早的旧变量。下面这张表可以帮助你快速判断自己该改哪一层配置位置作用范围适用场景系统环境变量整个机器所有会话全局统一切换适合单机单人~/.claude/settings.json的 env 块该用户下所有 Claude Code 会话最推荐隔离干净.claude/settings.json的 env 块进入该项目的会话多人共享按项目隔离适合团队注意官方文档里的settings.json是支持env块的它会在 Claude Code 启动时自动把里面的键值注入到会话环境。这比你去改系统环境变量要干净很多不会污染其他命令行工具。2. 永久配置的三种方式按需选择2.1 方式一写进 ~/.claude/settings.json 的 env 块这是我个人最推荐的方式。它的好处是只在 Claude Code 自己的配置范围内生效不会影响系统全局环境变量换终端、换 SSH 登录都不会丢。先找到用户级配置文件。macOS / Linux 路径一般是~/.claude/settings.jsonWindows 一般是C:\Users\你的用户名\.claude\settings.json。如果文件不存在直接新建即可。打开后把内容写成这样{ env: { ANTHROPIC_BASE_URL: https://api.your-gateway.example.com, ANTHROPIC_AUTH_TOKEN: sk-your-token-here, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意几个细节env块里每一项都是一个环境变量键值对。如果你接的是官方 API就把ANTHROPIC_AUTH_TOKEN换成ANTHROPIC_API_KEY。ANTHROPIC_MODEL不是必填项但接第三方网关时建议显式指定否则部分网关无法正确识别默认模型名。这里我没有写ANTHROPIC_SMALL_FAST_MODEL。实际使用中如果需要启用后台快速模型也可以一并加上。保存后重新打开 Claude Code 会话配置就会自动生效。提示settings.json是明文存储密钥的。如果是个人电脑还好如果是公司共用的服务器记得把文件权限收窄。Linux/macOS 上可以执行chmod 600 ~/.claude/settings.json避免同机器其他用户读到密钥。2.2 方式二写进 Shell 配置文件如果你习惯纯终端环境或者你的 Claude Code 是通过claude命令在任意目录下启动的把变量写进 Shell 配置文件也很方便。macOS / Linux 下结合自己用的 Shell 选择对应文件echo export ANTHROPIC_BASE_URLhttps://api.your-gateway.example.com ~/.zshrc echo export ANTHROPIC_AUTH_TOKENsk-your-token-here ~/.zshrc source ~/.zshrc如果用的是 Bash就把~/.zshrc换成~/.bashrc或~/.bash_profile。设置完以后任何新开的终端窗口都会自动带上这两个变量。这种方式适合“希望 Claude Code 之外的其他工具也能读到这些变量”的场景。缺点也明显变量是全局的一旦你在项目里需要用另外一套配置就得手动调整。团队共用一台服务器时这种方式容易互相干扰。2.3 方式三Windows 系统环境变量Windows 下配置 Claude Code 时很多人习惯直接在命令提示符里先 export 一次但那是临时的。真正“永久”的做法有两种。PowerShell 里设置当前用户的环境变量[Environment]::SetEnvironmentVariable(ANTHROPIC_BASE_URL, https://api.your-gateway.example.com, User) [Environment]::SetEnvironmentVariable(ANTHROPIC_AUTH_TOKEN, sk-your-token-here, User)设置之后需要重开一个终端窗口才能读到。也可以走图形界面右键“此电脑” → 属性 → 高级系统设置 → 环境变量 → 在用户变量里新建ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。Windows 上还有一个常见坑如果 Claude Code 是在 WSL 里面安装的它读的是 WSL 内部的环境变量而不是 Windows 的系统环境变量。这种情况下要么在 WSL 的~/.bashrc里写要么用settings.json方式两者都可以绕过这个坑。3. 结合实战场景配置自建模型服务光讲理论不够我拿三个最常见的场景演示一下。这三个场景分别对应三类需求用统一网关管理多个模型、接入第三方模型服务、接入本地离线模型。配置方法完全一样区别只在ANTHROPIC_BASE_URL指向哪里。3.1 场景一把自己部署的模型网关设为基地址很多团队会自己部署一套 API 网关服务来统一管理各家模型的密钥、用量和渠道。网关暴露出来的地址通常是内网的http://192.168.x.x:8080或者一个固定域名。配置如下{ env: { ANTHROPIC_BASE_URL: http://192.168.1.100:8080, ANTHROPIC_AUTH_TOKEN: sk-team-gateway-token } }这里的关键点在于网关的对外协议必须和 Anthropic API 的协议兼容。也就是说Claude Code 发出的请求必须能被你的网关正确解析。大多数网关都内置了 Anthropic 兼容接口如果没有就需要在网关侧开启相关兼容选项而不是在 Claude Code 这边硬改参数。我实际配置时还遇到过一个情况网关服务有“渠道”的概念每个渠道对应一家上游模型服务而每个渠道都要单独配置密钥。如果你在网关后台发现某个渠道一直报错先不要怀疑 Claude Code 配置错了去查一下网关渠道里是否漏填了上游密钥。3.2 场景二接入 DeepSeek 这类第三方模型服务DeepSeek 这类第三方服务通常提供的是 OpenAI 兼容接口也就是https://api.deepseek.com/v1这种格式。但 Claude Code 默认用的是 Anthropic 的/v1/messages接口格式两者不能直接互通。所以直接改ANTHROPIC_BASE_URL指向https://api.deepseek.com/v1是不可行的。正确做法有两种第一种是不改 Claude Code 本身在网关层做协议转换。你把 DeepSeek 作为网关里的一个渠道然后在 Claude Code 里把 Base URL 指向网关的 Anthropic 兼容接口这样请求链就是Claude Code → 网关Anthropic 协议→ 转换为 OpenAI 协议 → DeepSeek第二种是使用专门做协议转换的工具或服务。这类工具把 Anthropic 格式的请求包装成 OpenAI 格式再转发给 DeepSeek相当于在中间加了一个翻译层。这个过程中最容易出现的报错是模型名不匹配。比如 Claude Code 默认发的是claude-sonnet-4-20250514而 DeepSeek 那边的模型名是deepseek-chat网关无法映射就会直接 404。解决办法是去网关后台配置模型映射规则或者像我一样在ANTHROPIC_MODEL里直接指定能用名字。3.3 场景三接入 LM Studio 本地模型本地使用 LM Studio 时它启动的本地服务地址一般是http://localhost:1234/v1。这个地址同样是 OpenAI 兼容协议不能直接作为 Claude Code 的 Base URL。我的建议是把 LM Studio 的本地服务挂到一个转换网关后面转换网关接收 Anthropic 协议的请求再转成本地模型能明白的格式。配置依然是两步在转换网关里设置一个本地模型渠道指向http://localhost:1234/v1。在 Claude Code 的settings.json里把 Base URL 指向转换网关的地址。启动顺序也很重要先启动 LM Studio 服务再启动转换网关最后打开 Claude Code。如果顺序反了Claude Code 启动时网关还在等上游服务会话会一直转圈或者直接报连接拒绝。本地模型还有个上下文窗口限制。Claude Code 默认会发很长的 system prompt 和工具定义小参数本地模型经常收到超过最长文本的报错。遇到这种要么选用上下文更长的模型要么在网关侧做输入裁剪或者把ANTHROPIC_MODEL指定为适合本地推理的模型名称。我把三种场景整理成一个对比表方便你挑选场景Base URL 典型值需要认证方式额外注意官方 Anthropichttps://api.anthropic.comANTHROPIC_API_KEY默认情况无需改动自建/第三方网关http://网关地址:端口或网关域名一般为ANTHROPIC_AUTH_TOKEN网关需兼容 Anthropic 协议DeepSeek 或 OpenAI 兼容服务不能直接填需经转换层取决于转换层配置注意模型名映射LM Studio 本地不能直接填需经转换层取决于转换层配置注意启动顺序和上下文长度4. 验证配置是否生效以及常见错误排查配置改完之后别急着马上开始写代码先用几个简单办法确认环境真的生效了。4.1 确认变量被正确读取在 Claude Code 的会话里直接输入一个简单的提问比如“你好请回复测试成功”。如果应答正常说明 Base URL 和密钥都通。如果请求报错先检查变量是否真的设置进去了。终端里执行echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN也可以用claude启动后的调试信息来看。确认变量值确实是你写入的再继续往下排查。4.2 常见报错对照我整理了一张排查表覆盖了我自己踩过的和跟同事一起踩过的典型问题报错现象可能原因排查方向401 Unauthorized密钥错误、过期或认证类型不匹配检查 key 是否少前缀确认该用ANTHROPIC_API_KEY还是ANTHROPIC_AUTH_TOKEN403 Forbidden网关渠道被禁用或模型未对当前账号开放登录网关后台查看渠道状态404 model not found模型名不匹配网关没有对应模型在网关做模型映射或改ANTHROPIC_MODELConnection refusedBase URL 端口不对服务未启动先 curl 一下地址确认服务存活请求超时网关等待上游响应时间过长查看网关日志确认上游是否稳定网关日志提示 no api key for provider网关渠道漏填了上游服务密钥到网关渠道管理里补上密钥4.3 回滚到官方 API改坏了也不要慌。把配置里的ANTHROPIC_BASE_URL删掉或者改回https://api.anthropic.com再把认证方式换成官方ANTHROPIC_API_KEY然后重启会话即可。如果用的是settings.json直接恢复成{ env: { ANTHROPIC_API_KEY: sk-ant-官方key } }如果之前不记得原来的值也可以先删除整个settings.json里的 env 块让 Claude Code 走最原始的配置路径。注意删除前最好备份一份。5. 我踩过的几个坑写出来给你避雷配置本身不难真正让人花时间的是各种“看起来没错但就是不生效”的情况。下面这些是我在实际操作中遇到过的比较典型的坑。第一个坑是环境变量优先级。我第一次配置的时候在项目里的.claude/settings.json里写了新地址但终端还是报连不上官方接口。排查半天发现是系统里早就导出了ANTHROPIC_BASE_URL指向官方域名的旧变量。系统环境变量优先级高于项目配置文件所以旧值一直压在头顶。解决方法是把终端的旧变量清理干净再重开会话。第二个坑是认证方式选错。接自建网关时我一开始填的是ANTHROPIC_API_KEY接口一直返回 401。后来发现网关走的是 Bearer Token 认证必须用ANTHROPIC_AUTH_TOKEN。这个问题的迷惑性在于两个变量都是“密钥”的含义很多人根本不会怀疑这里。第三个坑是本地模型接进去之后疯狂报超时。LM Studio 服务明明启动着但 Claude Code 就是请求超时。后来发现是 LM Studio 加载的模型上下文长度太小Claude Code 发过去的请求头里已经带着非常长的工具定义模型还没开始推理就直接撑爆了。换了个大上下文模型之后立刻顺畅。第四个坑是 Windows 下改完环境变量不重开终端以为没生效。Windows 的 PowerShell 读的是进程启动时的环境变量每次设置完都必须完全重开终端。这个坑不大但很容易让人白折腾十几分钟。最后再补一个安全上的经验settings.json里的密钥是明文的尽量不要把包含真实密钥的这个文件提交到 Git 仓库。项目配置和密钥分开管理项目里只写网关地址密钥放到用户级配置文件里这样既能共享配置又不把敏感信息传到仓库。按照我给的流程先确定自己的模型服务是哪一类再选择对应的配置方式最后用验证步骤测一遍整个过程用不了十分钟。如果你以后换了新的网关或者新的模型服务只需要改改动ANTHROPIC_BASE_URL和认证变量这两项Claude Code 这边不需要重装也不需要重新设置什么底层环境。

Claude Code永久配置自定义API地址与密钥技巧

相关推荐

Shell脚本遍历日期范围：原理、常见坑与高效实现

WMS物流仓储智能调度新解法：DeepSeek多目标优化与九个关键参数调参实战

谢希仁《计算机网络》课后答案：从题库到协议分析实战指南

更多资讯

ARM64 CentOS 7手工安装MySQL 5.7实战：从二进制包到systemd全流程

OpenHarmony上适配dcli_common：构建鸿蒙CLI工具链实践

插件加载失败排查指南：从IAR到Harness与MusicFree的实战解析

Win11 安装配置 Node.js 完全指南：从 LTS 到环境变量与 npm 提速

Supabase RLS实战：公开读、投稿写、待审核可见的权限策略

408计算机网络复习：三层协议栈考点梳理与CRC/CIDR手算通关

今日更新

插件加载失败深度解析：从did not activate到生命周期排查指南

SpringBoot+Vue+MyBatis企业级房屋租赁管理系统源码解析

企业核心数据灾备自动化：用 OpenClaw 备份到本地 + 云端 + 离线存储的 TaoToken 统一通道实践

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？