新拿到的开发机装了最新版Claude Code之后第一次跑claude命令会直接进入官方OAuth登录流程。这个流程对个人日常用没问题可一旦你所在团队用的是自建API网关、或者你自己有一个兼容端点、又或者你想在本地LM Studio上跑一个开源模型来试验继续走官方登录就是南辕北辙了。这时候你要改的说白了就是两个东西接口地址URL和认证密钥Key而且大概率希望让它们永久生效而不是每次启动终端都手动敲一遍环境变量。很多教程会告诉你启动时加上两个环境变量再运行比如export ANTHROPIC_BASE_URLxxx。这种办法当场能用但关掉终端就失效换个目录也是白搭。所谓“永久设置”本质上是找一个合适的持久化位置让Claude Code每次启动都能自动读到你的URL和Key并且不被版本升级、终端切换影响。这篇文章就按这个思路从原理到实操逐步讲清楚。1. Claude Code的模型接入逻辑URL、Key和模型名分别管什么1.1 三个环境变量各自负责一件事Claude Code虽然交互界面很简单但底层用的是Anthropic的TypeScript SDK启动时按固定顺序去读环境变量。你真正需要掌握的有三个环境变量作用默认值什么时候需要改ANTHROPIC_API_KEY官方API密钥用于官方端点鉴权无使用官方API时填写ANTHROPIC_AUTH_TOKEN自定义端点的Bearer Token无接入自家网关或第三方兼容端点时填写ANTHROPIC_BASE_URLAPI接口根地址https://api.anthropic.com需要把请求发往自建或第三方端点时必改这里有一个新用户最容易绕晕的地方为什么既要有ANTHROPIC_API_KEY又要有ANTHROPIC_AUTH_TOKEN我的理解是SDK对两套鉴权做了分离——API_KEY走的是官方校验逻辑它会在请求里带x-api-key头而AUTH_TOKEN是直接作为Authorization: Bearer传给你的端点网关类服务通常认这个。所以当你把BASE_URL改成自己的地址之后最稳妥的做法是设置ANTHROPIC_AUTH_TOKEN而不是继续依赖ANTHROPIC_API_KEY。有些人在改完BASE_URL后还留着官方Key结果跑出一堆401多半就是这里没想明白。1.2 模型名也是配置的一部分标题里问的是URL和Key但真正跑起来后你可能还要再关心一个变量ANTHROPIC_MODEL。BASE_URL只决定请求发往哪里Key只决定对方认不认你而模型名决定你的请求被路由到哪个模型上。比如你家网关后面同时挂了Claude、DeepSeek、Qwen等多个模型网关会根据请求体里的模型参数去做分发。这时候你可以在环境变量里加一行export ANTHROPIC_MODELclaude-sonnet-4-20250514如果网关那边对模型名有自定义映射比如它内部把某个别名映射到了DeepSeek的某个型号那你就得按网关文档来填模型名。这里没有银弹原则就是请求体里出现的模型名必须以你的端点服务方支持的为准而不是以Claude Code默认的为准。1.3 配置加载顺序与优先级Claude Code确认配置时大致遵循这样的优先级命令行启动参数当前shell环境变量项目级/用户级settings.json中的env块系统默认配置实际经验里shell环境变量往往会压过settings.json里的同名配置。所以我不建议两处都设否则排查问题时你会搞不清到底是谁在生效。提示Claude Code没有图形设置面板它的“模型地址”“密钥”完全由启动时的环境变量和配置文件决定。理解了这一点你就明白了所谓“永久设置”就是把这几个值写进稳定的持久化文件。2. 永久设置的三条路线环境变量、配置文件、切换工具2.1 路线一写进Shell配置文件最直接、最通用的方式就是把export语句写进shell启动文件。这样每次打开新终端系统都会先去执行这个文件效果等于永久生效。在macOS/Linux下先确认你用的是哪种shellzsh修改~/.zshrcbashmacOS一般是~/.bash_profileLinux通常是~/.bashrcfish修改~/.config/fish/config.fish然后追加配置export ANTHROPIC_BASE_URLhttps://your-endpoint.example.com export ANTHROPIC_AUTH_TOKENsk-ant-xxxxx export ANTHROPIC_MODELclaude-3-5-sonnet-20241022保存后执行source ~/.zshrc或者直接新开一个终端窗口再运行claude。你会发现它已经不再走官方登录流程而是直接使用你配置的端点。Windows下的操作略有差异。如果你在PowerShell里运行用setx命令写入用户环境变量setx ANTHROPIC_BASE_URL https://your-endpoint.example.com setx ANTHROPIC_AUTH_TOKEN sk-ant-xxxxx注意setx不会立即作用于当前会话必须新开一个终端窗口才会生效。如果用的是cmd规则一样。2.2 路线二写到Claude Code的配置文件如果你不喜欢在shell启动文件里堆变量更希望“配置跟着Claude Code走”那配置文件是更好的选择。Claude Code会读取两个层级的配置用户级~/.claude/settings.json作用于本机所有项目项目级.claude/settings.json只作用于当前项目可提交进Git两个文件都支持env字段。例如{ env: { ANTHROPIC_BASE_URL: https://your-endpoint.example.com, ANTHROPIC_AUTH_TOKEN: sk-ant-xxxxx } }这里面有个细节值得注意~/.claude/settings.json是你的个人全局配置放API Key这类私密信息没问题但如果放在项目级settings.json并提交到Git仓库就意味着所有看到代码的人都能拿到你的Key。所以项目级配置更适合放BASE_URL这种不敏感信息Key放用户级或者干脆用项目本地配置文件.claude/settings.local.json来存放个人密钥这个文件一般会被Git忽略不会提交。2.3 路线三用社区工具cc switch管理多套配置如果你的需求不只是永久设置一套而是要反复切换——比如白天连公司网关、晚上连本地模型、偶尔回官方端点——手写配置就容易改乱。社区里常用一个叫cc switch的小工具npm包名cc-switch它本质上是一个TUI界面提供增删改查配置的能力。安装后在终端里执行cc switch它会列出当前已有的配置。你可以新建一个Provider配置比如命名为my-gateway填上API地址、Key、模型名然后一键切换。切换动作的底层其实就是帮你重写~/.claude/settings.json。我个人的建议是初次用可以安装cc switch省点事但不要完全依赖它因为你有必要理解它帮你改的是什么文件。一旦你明白了配置结构完全可以自己维护一个配置文件模板在不同项目、不同机器上复制使用。3. 完整实操从零配置自己的URL和Key并永久生效3.1 动手之前的前置确认在改配置之前先确认三件事Claude Code已经安装好并且能正常启动。安装命令通常是npm install -g anthropic-ai/claude-code装完跑claude --version看版本号。手上有一个可用的端点地址并且有对应的有效Key。如果端点还没就绪后面所有步骤都会报connection refused或401。想清楚配置的持久化范围只给当前项目用还是全机所有目录都用。不同范围直接影响你要改的文件。全机使用首选shell profile或用户级settings.json只给当前项目用就在项目根目录建.claude/settings.json或.claude/settings.local.json。3.2 实操示例macOS/Linux 用户级settings.json我以“全机所有项目都使用自定义端点和Key”为例给出一个比较干净的做法。第一步创建用户级配置文件目录并写入配置mkdir -p ~/.claude cat ~/.claude/settings.json EOF { env: { ANTHROPIC_BASE_URL: https://your-endpoint.example.com, ANTHROPIC_AUTH_TOKEN: sk-ant-xxxxx } } EOF第二步验证配置是否被读取。打开任意目录运行claude在对话里输入/status查看显示的API端点和认证状态。如果显示的是你配置的地址说明读取成功如果显示的还是官方地址说明当前shell的环境变量里可能存在更高优先级的同名变量。这个验证动作很多人会跳过但它其实是最快定位问题的手段。/status面板里会直接显示Claude Code当前正在使用的模型、端点、登录方式比你猜来猜去强得多。3.3 实操示例只有一个项目需要自定义如果你只是某个项目要用自己的端点不想到处污染全局配置那就在项目根目录下操作mkdir -p .claude cat .claude/settings.local.json EOF { env: { ANTHROPIC_BASE_URL: https://your-endpoint.example.com, ANTHROPIC_AUTH_TOKEN: sk-ant-local-xxxxx } } EOF这样Key只存在这个项目里其他项目仍然使用默认配置。.claude/settings.local.json这个文件名本身就暗示了它不该被提交到Git。如果你希望团队共享同一个网关地址但每个人用自己的Key可以这样拆.claude/settings.json只写ANTHROPIC_BASE_URL.claude/settings.local.json写每个人自己的ANTHROPIC_AUTH_TOKEN这种方式既实现了“永久”又兼顾了多人协作的安全边界。3.4 验证和回退改完之后我推荐用一个最小命令验证claude --print hi --model claude-3-5-sonnet-20241022如果端点和Key没问题会正常返回一句问候如果报错参考后面第5部分的排错方向。想撤销自定义配置时反向操作就行如果走shell profile把export那几行删掉或注释重新source如果走settings.json把env字段清空或直接删除对应文件后重启claude。这里有个小技巧删除前先备份一条命令mv ~/.claude/settings.json ~/.claude/settings.json.bak确认没问题再删备份免得改完发现还不如原来。4. 本地模型与多模型网关的接入URL改对了协议还要对4.1 为什么不能把OpenAI格式的地址直接填进去热门搜索词里反复出现的LM Studio、DeepSeek、Qwen、GLM其实都指向同一个问题很多人想用Claude Code的交互外壳去驱动非Anthropic家的模型。Claude Code和Anthropic官方API之间用的是Messages API协议POST /v1/messages。而LM Studio、Ollama、以及很多开源模型服务默认提供的是OpenAI兼容协议POST /v1/chat/completions。你把BASE_URL改成http://127.0.0.1:1234后Claude Code确实会把请求发过去但发出去的请求体是Anthropic的格式对面服务如果没做格式转换会直接报错。所以正确的思路是先确认你的目标服务是否提供Anthropic兼容端点然后再去配置URL和Key。4.2 LM Studio怎么接新版LM Studio的本地Server已经自带Anthropic兼容端点所以接入比想象中简单。流程大致是在LM Studio里加载一个模型比如Qwen或Llama系列启动Local Server默认地址是http://127.0.0.1:1234确认Server面板里Anthropic兼容API是开启状态在Claude Code侧配置export ANTHROPIC_BASE_URLhttp://127.0.0.1:1234 export ANTHROPIC_AUTH_TOKENlm-studio export ANTHROPIC_MODELqwen2.5-7b-instruct这里有个关键细节本地服务通常不校验Key但字段必须非空所以随便填一个非空字符串即可。模型名要以LM Studio加载后显示的模型ID为准不能随便填。完成后把这三行写进~/.zshrc或其他持久化文件就完成了永久设置。用这套配置启动claude请求就会打到本地模型上。4.3 DeepSeek、Qwen、GLM通过通用网关接入时的常见误配如果你们团队是用通用模型网关把各家模型统一成一个对外接口那么配置URL和Key反而简单网关一般会暴露一个统一端点你在网关后台分配一个Token然后把BASE_URL指向网关的Anthropic兼容地址即可。这时候最常见的坑反而不在Claude Code而在网关内部。以DeepSeek为例如果你在网关里创建了“DeepSeek官方渠道”但渠道配置里的模型映射带上了奇怪的修饰名Claude Code请求里的模型名就很容易对不上最后报出类似no api key for provider route deepseek-official的提示。看到这种报错第一反应应该是查网关后台而不是反复改Claude Code配置。你需要确认网关里是否存在名为deepseek-official的渠道分组以及Claude Code请求里指定的模型名是否在对应渠道的分发列表里。5. 永久配置后最常见的几个报错症状与解法我按实战中出现频率从高到低排了一张表报错内容问题本质建议处理token exchange failed: error sending request for url登录态下SDK尝试到BASE_URL下的/auth端点做OAuth令牌交换你的端点不支持这个流程弃用OAuth登录方式改用ANTHROPIC_AUTH_TOKEN方式no api key for provider route deepseek-official网关侧路由/渠道配置缺少对应密钥或渠道名称不符去网关后台检查渠道配置不要反复折腾Claude Code401 / Invalid API Key端点返回认证失败检查ANTHROPIC_AUTH_TOKEN是否被正确读取值是否正确404 model not found / model not exist模型名不被端点识别在/status里查当前模型名再对照端点支持的模型列表Connection refusedBASE_URL指向的端口没有服务在监听先用浏览器或curl访问该地址确认服务进程活着claude native binary not installed安装不完整postinstall未执行重装或手动执行postinstall这个和URL/Key无关5.1token exchange failed的完整排查思路很多人在设置完BASE_URL后启动Claude Code看到的第一条报错就是这个因为本机之前已经保存了官方OAuth登录信息SDK会优先尝试拿已有的token去换新token。我的处理顺序是先确认环境变量里ANTHROPIC_AUTH_TOKEN已设置且非空再检查是否还存在旧的会话信息。可以执行claude /logout或者查看~/.claude下的临时会话文件如果仍然报错检查BASE_URL是否拼写正确尤其是端口号后不要带多余斜杠比如https://your-endpoint.example.com/v1写成https://your-endpoint.example.com/v1/都可能导致路径拼接异常。正常情况下只要AUTH_TOKEN被正确读取SDK就不会走到OAuth分支这个报错自然消失。5.2 为什么改完配置后/status里还是官方地址这个坑太常见了。明明settings.json和profile都写对了打开/status依然显示官方端点。最可能的原因有两个一是你还在那个旧终端里运行claude而这个终端是在修改配置文件之前就启动的shell没有重新加载最新的配置。关掉重开一个终端问题往往就没了。二是你之前手动设置过临时的export当前shell里残留了一个优先级更高的ANTHROPIC_BASE_URL。排查方法很简单env | grep ANTHROPIC看输出结果就知道当前进程从哪读到了值。如果发现有残留先unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN再启动。从经验看90%的“配置没生效”都不是文件写错而是当前shell的加载顺序问题。6. 我的配置习惯如何让“永久”真的可持续配置一旦设置成功还要面对几个现实问题Claude Code升级会不会覆盖配置、多台开发机怎么同步、Key意外泄露怎么办。先说升级。Claude Code的版本更新通常只更新安装目录下的程序文件不会碰~/.claude下的内容所以用户级settings.json是安全的。但如果你把配置写在项目根目录的.claude/settings.json里一旦项目被重建或清理配置会丢。这种情况下我建议在项目README里放一段配置模板或者干脆在仓库保留一个.claude/settings.example.json方便随时恢复。再说多设备同步。我自己的习惯是全局共享的、不敏感的配置比如BASE_URL、模型名放进用户级settings.json或项目级settings.json每个设备不一样的Key放进settings.local.json不纳入Git迁移到新机器时只拷贝settings.json加上导出Key几分钟就能恢复。最后一个是安全层面。自定义端点意味着你的Key在每次请求时都会发往目标服务器所以目标服务器必须是你可信的环境。不要把公司内部Key配置到个人电脑上也不要把个人Key放到公用终端上。一旦怀疑Key泄露第一时间去端点服务商后台轮换Key然后同步更新本地配置。我在实际项目中见过很多团队在“永久设置”这件事上翻车大多数都不是技术不会而是Key管理太随意。另外补充一个小习惯每次修改完配置我会顺手用env | grep ANTHROPIC检查一遍当前环境再启动claude并看一眼/status。这套组合动作不超过十秒但能避免绝大多数“改了却没生效”的困惑。总的来说把Claude Code的URL和Key永久设置成自己的核心就是三句话先搞清楚三个环境变量的职责再选一个合适的持久化位置最后用/status和最小请求做验证。按这个流程走不管是官方网关、自建端点还是本地模型都能稳定跑起来。