这篇把配置优先级、四类 settings.json 的区别、高频环境变量分组、常见踩坑、开发模式与调试技巧讲透最后给一个设置并验证一条环境变量生效的完整实操。一、先讲个坑配了半天不生效原来是配错了文件说个我自己踩过的坑。刚用 Claude Code 那阵我想给项目配一个环境变量让它走第三方 API 而不是官方订阅。我在项目根目录的.claude/settings.json里写了{ env: { ANTHROPIC_API_KEY: sk-xxx, ANTHROPIC_BASE_URL: https://api.third-party.com }}然后重启 Claude Code结果发现它还是走官方订阅根本没走第三方 API。我折腾了半天——检查 JSON 格式、重启终端、重新登录都没用。后来才发现我配错了文件。项目级的.claude/settings.json是团队共享的配置会提交到 git而包含 API Key 这种敏感信息的配置应该放在.claude/settings.local.json——这个文件是项目本地私有的不会提交 git而且优先级更高。更坑的是我后来发现我之前在用户全局的~/.claude/settings.json里也配过一个ANTHROPIC_API_KEY那个是旧的、已经过期的 key。因为用户全局配置的优先级比项目共享配置高所以我在项目里配的新 key 被全局的旧 key 覆盖了——而旧 key 过期了所以它就 fallback 到了官方订阅。一套下来三个配置文件打架我配了半天全白搭。这一篇就把配置体系从里到外讲透——有哪几类配置文件、优先级是怎样的、高频环境变量有哪些、常见踩坑怎么避、开发模式怎么配、以及怎么验证配置真的生效了。二、配置优先级谁覆盖谁在讲具体配置之前先把最重要的优先级搞清楚。Claude Code 的配置来源有很多它们按优先级从高到低排列高优先级的覆盖低优先级的。配置优先级金字塔图优先级配置来源说明1最高CLI 命令行标志--model、--permission-mode、--max-turns等当次启动生效2项目本地私有.claude/settings.local.json不提交 git优先级最高的配置文件3项目共享.claude/settings.json提交 git团队共享4用户全局~/.claude/settings.json所有项目生效5托管设置企业管理员部署的 managed-settings.json组织级6系统环境变量shell 里 export 的环境变量7最低程序默认值内置默认配置两个关键规则规则一环境变量 vs settings.json 的 env 字段如果同一个变量既在系统环境变量里设了又在 settings.json 的env字段里设了settings.json 的 env 字段优先级更高因为 settings.json 排在环境变量前面。但有个例外如果 settings.json 里有对应的专用设置键比如customApiUrl而环境变量里也设了比如ANTHROPIC_BASE_URL环境变量优先级更高。官方文档明确说如果两者都设置了环境变量具有更高的优先级。简单记settings.json 的 env 字段 系统环境变量但专用设置键 vs 环境变量环境变量赢。搞不清的时候用/config命令看当前生效的配置。规则二合并而非覆盖不同层级的配置不是简单的覆盖而是合并——更具体的配置添加到或覆盖更宽泛的配置。比如用户全局配了 3 个 MCP 服务器项目共享配了 2 个项目专用的 MCP最终生效的是 5 个全局 3 个 项目 2 个而不是只有项目的 2 个。但如果同一个键在两个层级都设了高优先级的覆盖低优先级的。比如全局设了model: sonnet项目设了model: opus最终生效的是opus。三、四类 settings.json哪个是哪个这是最多人搞混的地方。Claude Code 有四类 settings.json各管各的作用域、是否提交 git、优先级都不同。四类配置文件对比图类型路径作用域提交 git优先级适合放什么用户全局~/.claude/settings.json所有项目❌ 不提交4个人通用配置默认模型、全局 MCP、通用 Hooks、个人偏好项目共享.claude/settings.json当前项目✅ 提交3团队共享配置项目 MCP、团队 Hooks、权限规则、CLAUDE.md 引用项目本地私有.claude/settings.local.json当前项目本机❌ 不提交2敏感信息API Key、个人 token、本机路径、临时调试配置托管设置企业管理员部署整个组织管理员管理5企业策略安全规则、强制 MCP、权限限制、遥测配置怎么选1. 个人通用的配置 → 用户全局比如你所有项目都用同一个模型、都装了同样的几个 MCP、都有同样的 Hooks——这些放在~/.claude/settings.json里一次配置所有项目生效。2. 团队共享的配置 → 项目共享比如项目专用的 MCP 服务器、团队约定的 Hooks、权限规则——这些放在.claude/settings.json里提交 git团队成员 clone 项目后自动生效。3. 敏感信息和本机私有 → 项目本地私有比如 API Key、个人 token、本机绝对路径、临时调试用的配置——这些放在.claude/settings.local.json里绝对不要提交 git。这个文件应该加到.gitignore里。4. 企业策略 → 托管设置这个是企业管理员配置的普通用户不用管。它用于强制整个组织遵守安全策略比如禁用某些权限、强制安装安全 MCP、配置遥测。最常见的错误错误一把 API Key 写进项目共享配置.claude/settings.json会提交 git把 API Key 写进去等于把密钥公开给整个团队甚至公开给全世界如果是开源项目。API Key 必须写在.claude/settings.local.json里。错误二在项目共享配置里配了却被用户全局覆盖了比如你在项目里设了model: opus但你全局设了model: sonnet——因为项目共享优先级3比用户全局4高所以项目的 opus 会生效。等等不对优先级数字越小越高3 比 4 高所以项目共享覆盖用户全局。那为什么我之前说被覆盖了哦我之前的坑是我在项目共享3里配了新 key但用户全局4里配了旧 key——按优先级项目共享应该覆盖用户全局啊为什么没生效因为我配的是env字段里的环境变量而环境变量的合并规则可能不同——或者更可能的是我当时配错了文件根本没配在正确的位置。这就是为什么搞清楚四类文件的区别这么重要。简单记优先级数字越小越高。CLI标志(1) 项目本地(2) 项目共享(3) 用户全局(4) 托管(5) 环境变量(6) 默认(7)。四、高频环境变量分组速查Claude Code 支持的环境变量很多我把它们按用途分组方便你快速查找。高频环境变量分组速查表第一组连接认证变量作用示例ANTHROPIC_API_KEY官方 API Keysk-ant-xxxANTHROPIC_AUTH_TOKEN第三方平台的 API Key接入国产模型时用sk-xxxANTHROPIC_BASE_URL第三方 API 端点接入国产模型时用https://api.deepseek.comANTHROPIC_MODEL默认模型claude-sonnet-4-20250514ANTHROPIC_SMALL_FAST_MODEL轻量任务用的模型分类、提取等claude-haiku-4-20250414接入国产模型的三个变量缺一不可ANTHROPIC_AUTH_TOKENANTHROPIC_BASE_URLANTHROPIC_MODEL全部放在settings.local.json的env字段里。第 5 篇详细讲过。第二组模型与推理变量作用示例ANTHROPIC_MODEL默认模型claude-opus-4-20250514ANTHROPIC_SMALL_FAST_MODEL轻量任务模型claude-haiku-4-20250414ANTHROPIC_MAX_TOKENS最大输出 token 数8192ANTHROPIC_TEMPERATURE采样温度0确定性1随机性0.0追求输出稳定性时设ANTHROPIC_TEMPERATURE0.0——这对算法工程师做确定性推理很重要。第三组超时与限流变量作用示例ANTHROPIC_TIMEOUTAPI 请求超时时间秒600ANTHROPIC_MAX_RETRIESAPI 请求失败最大重试次数3CLAUDE_CODE_MAX_TURNS单次会话最大轮次100第四组隐私与遥测变量作用示例DISABLE_AUTO_COMPACT禁用自动上下文压缩1DISABLE_AUTOUPDATE禁用自动更新1CLAUDE_CODE_DISABLE_TELEMETRY禁用遥测数据收集1CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING禁用文件检查点第17篇讲过1第五组调试与开发变量作用示例CLAUDE_CODE_DEBUG开启调试模式输出详细日志1CLAUDE_CODE_LOG_LEVEL日志级别debug/info/warn/errordebugCLAUDE_CODE_DISABLE_SAFE_MODE禁用安全模式慎用1CLAUDE_CHROME_PERMISSION_MODEChrome 操作权限模式第19篇讲过skip_all_permission_checks调试配置出问题时设CLAUDE_CODE_DEBUG1启动会输出详细的加载日志帮你定位配置哪里出了问题。五、三种设置环境变量的方式环境变量有三种设置方式各有适用场景。方式一Shell 临时设置当前会话有效# 临时设置只在当前终端会话有效export ANTHROPIC_API_KEYsk-xxxexport ANTHROPIC_BASE_URLhttps://api.third-party.com # 然后启动 Claude Codeclaude适用场景临时测试、一次性使用、不想持久化的配置。关掉终端就失效了。方式二Shell 配置文件持久化所有终端有效把环境变量写进 shell 配置文件~/.bashrc、~/.zshrc、~/.bash_profile# ~/.zshrcexport ANTHROPIC_API_KEYsk-xxxexport ANTHROPIC_BASE_URLhttps://api.third-party.comexport ANTHROPIC_MODELclaude-sonnet-4-20250514然后source ~/.zshrc使其生效或者重启终端。适用场景全局通用的环境变量所有项目、所有终端都生效。注意把 API Key 写进 shell 配置文件有安全风险——任何能读取你 shell 配置的程序都能拿到你的 Key。更安全的方式是放在 settings.local.json 里或者用密码管理器管理。方式三settings.json 的 env 字段推荐在 settings.json 里用env字段设置环境变量{ env: { ANTHROPIC_API_KEY: sk-xxx, ANTHROPIC_BASE_URL: https://api.third-party.com, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }}这是最推荐的方式因为 1. 可以按项目隔离项目级 vs 用户全局 2. 敏感信息放在settings.local.json不会提交 git 3. 不需要改 shell 配置不影响其他程序 4. Claude Code 启动时自动加载不需要source六、常见踩坑这一节是血泪教训总结把最常见的配置坑列出来。坑一API Key 残留导致走 API 计费而非订阅这是最常见、最烧钱的坑。你之前为了测试接入了第三方 API在~/.claude/settings.json或 shell 配置里设了ANTHROPIC_API_KEY。后来你想切回官方订阅但忘了删掉那个环境变量。结果Claude Code 检测到有ANTHROPIC_API_KEY就走 API 计费而不是你的订阅。你以为在用订阅其实在按 token 烧钱——月底账单出来才发现。解决方法 1. 想切回订阅时检查所有配置文件里有没有ANTHROPIC_API_KEYbash grep -r ANTHROPIC_API_KEY ~/.claude/ .claude/ ~/.zshrc ~/.bashrc2. 找到后删掉或者注释掉 3. 重启 Claude Code 4. 用/status或/cost确认当前是订阅模式还是 API 模式经验法则如果你有订阅就不要在任何地方设 ANTHROPIC_API_KEY。设了就会走 API 计费。坑二改了配置不生效因为配错了文件就像我开场讲的坑——你在.claude/settings.json里配了但应该配在.claude/settings.local.json里或者你在项目里配了但被用户全局的配置覆盖了。解决方法 1. 先搞清楚四类配置文件的区别第三节 2. 敏感信息放settings.local.json团队共享放settings.json个人通用放~/.claude/settings.json3. 改完配置后重启 Claude Code很多配置需要重启才生效 4. 用/config命令查看当前生效的配置确认你的配置真的生效了坑三改了环境变量需要重启会话才生效环境变量是在 Claude Code 启动时加载的。如果你在会话进行中改了环境变量比如在另一个终端 export 了新的变量当前会话不会自动加载——你需要退出当前会话重新启动 Claude Code。解决方法改完环境变量后/exit退出当前会话重新启动claude。不要在会话进行中改环境变量然后期望它生效。坑四JSON 格式错误整个配置文件失效settings.json 是 JSON 格式一个逗号、一个引号错了整个文件就解析失败Claude Code 会忽略这个文件的所有配置。解决方法 1. 改完配置后用 JSON 校验工具检查格式bash python3 -m json.tool .claude/settings.local.json /dev/null echo JSON 格式正确 || echo JSON 格式错误2. 或者用jq检查bash jq . .claude/settings.local.json /dev/null3. 用--debug模式启动看有没有配置解析错误坑五把敏感配置提交到了 git你不小心把settings.local.json或者包含 API Key 的配置提交到了 git推到了远程仓库——密钥就泄露了。解决方法 1. 确保.gitignore里包含.claude/settings.local.json .claude/*.local.json .env2. 如果已经提交了立刻 - 轮换泄露的 API Key旧的作废生成新的 - 从 git 历史中移除敏感信息git filter-branch或 BFG Repo-Cleaner - 通知团队成员经验法则任何包含密钥、token、密码的文件绝对不能提交 git。提交前git status看一眼确认没有敏感文件。七、开发模式与调试技巧如果你在开发 Claude Code 的插件、Skills、或者调试配置问题这些技巧会帮到你。调试模式启动# 开启调试模式输出详细日志claude --debug # 或者用环境变量CLAUDE_CODE_DEBUG1 claude调试模式会输出 - 配置文件加载详情加载了哪些文件、哪些被覆盖了 - 插件加载详情哪些插件加载成功、哪些失败 - MCP 服务器连接详情 - API 请求和响应详情 - 错误堆栈配置出问题时第一时间用--debug启动看日志就能定位问题。查看当前生效的配置在 Claude Code 会话里输入/config会显示当前生效的所有配置包括 - 当前使用的模型 - 权限模式 - 已加载的 MCP 服务器 - 已启用的插件 - 环境变量部分 - 配置文件路径这是验证配置是否生效的最快方式。查看当前状态和认证/status显示当前认证状态、账号信息、是订阅模式还是 API 模式、当前模型等。插件开发调试开发插件时第18篇讲过# 重载插件不需要重启/reload-plugins # 验证插件配置claude plugin validate /path/to/plugin日志文件位置Claude Code 的日志文件存在~/.claude/logs/配置出问题、插件加载失败、MCP 连不上时去这里看日志。八、动手实验设置并验证一条环境变量光看不练没用。下面用一个最小流程让你亲手设置一条环境变量并验证它生效。第一步创建项目本地私有配置文件在项目根目录创建.claude/settings.local.json如果不存在{ env: { ANTHROPIC_MODEL: claude-haiku-4-20250414 }}这里我们把默认模型设为 haiku轻量模型省钱。第二步确保这个文件不会被提交 git检查.gitignore里有没有.claude/settings.local.json如果没有加上。然后确认 git 不会追踪这个文件git status你应该看不到.claude/settings.local.json如果看到了说明.gitignore没配好。第三步重启 Claude Code退出当前会话/exit重新启动claude。第四步验证配置生效在 Claude Code 里输入/config看看当前模型是不是claude-haiku-4-20250414。如果是说明配置生效了。也可以用/status查看当前模型。第五步测试切换模型在会话里用/model切换到 sonnet然后再/config看——当前会话的模型变成了 sonnet但配置文件里的默认模型还是 haiku下次启动会回到 haiku。这说明配置文件里的模型是启动时的默认值会话中用/model切换只影响当前会话不影响配置文件。第六步清理实验完了把settings.local.json里的模型改回你常用的或者删掉这行用默认值重启 Claude Code。走完这六步你就对环境变量的设置、优先级、验证方式有了真实体感以后配置出问题也知道怎么排查了。本篇小结维度一句话记住优先级CLI标志(1) 项目本地(2) 项目共享(3) 用户全局(4) 托管(5) 环境变量(6) 默认(7)数字越小越高四类配置文件用户全局(~/.claude/settings.json)、项目共享(.claude/settings.json提交git)、项目本地私有(.claude/settings.local.json不提交git)、托管设置(企业管理员)敏感信息放哪必须放 settings.local.json绝对不能提交 git接入国产模型三变量ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL ANTHROPIC_MODEL缺一不可三种设置方式shell临时(当前会话)、shell配置文件(全局持久)、settings.json的env字段(推荐按项目隔离)坑一API Key残留有订阅就不要设 ANTHROPIC_API_KEY设了就走API计费月底烧钱坑二配错文件敏感信息放local团队共享放settings.json个人通用放全局坑三需要重启改完环境变量/配置文件必须重启Claude Code才生效坑四JSON格式错一个逗号错了整个文件失效改完用jq校验坑五敏感配置提交git.gitignore必须包含settings.local.json提交了立刻轮换密钥调试技巧--debug启动看日志、/config看当前生效配置、/status看认证状态、~/.claude/logs/看日志文件你现在应该能理解配置优先级谁覆盖谁、搞清楚四类settings.json的区别、知道高频环境变量的分组和作用、会用三种方式设置环境变量、能避开5个常见踩坑、会用调试模式和/config验证配置、能亲手设置并验证一条环境变量。说到底配置的本质只有一句话搞清楚哪个文件管什么、谁覆盖谁、敏感信息别提交 git——改完重启用 /config 验证别瞎折腾。资料展示下面是我整理的AI大模型 学习资料和工具包预览适合收藏后按主题逐步学习。如果你想看完整资料目录可以在评论区留言「资料」也欢迎告诉我你更关注AI大模型里的哪类内容。
Claude Code - 环境变量与开发配置：把 Claude Code 调成你想要的样子
这篇把配置优先级、四类 settings.json 的区别、高频环境变量分组、常见踩坑、开发模式与调试技巧讲透最后给一个设置并验证一条环境变量生效的完整实操。一、先讲个坑配了半天不生效原来是配错了文件说个我自己踩过的坑。刚用 Claude Code 那阵我想给项目配一个环境变量让它走第三方 API 而不是官方订阅。我在项目根目录的.claude/settings.json里写了{ env: { ANTHROPIC_API_KEY: sk-xxx, ANTHROPIC_BASE_URL: https://api.third-party.com }}然后重启 Claude Code结果发现它还是走官方订阅根本没走第三方 API。我折腾了半天——检查 JSON 格式、重启终端、重新登录都没用。后来才发现我配错了文件。项目级的.claude/settings.json是团队共享的配置会提交到 git而包含 API Key 这种敏感信息的配置应该放在.claude/settings.local.json——这个文件是项目本地私有的不会提交 git而且优先级更高。更坑的是我后来发现我之前在用户全局的~/.claude/settings.json里也配过一个ANTHROPIC_API_KEY那个是旧的、已经过期的 key。因为用户全局配置的优先级比项目共享配置高所以我在项目里配的新 key 被全局的旧 key 覆盖了——而旧 key 过期了所以它就 fallback 到了官方订阅。一套下来三个配置文件打架我配了半天全白搭。这一篇就把配置体系从里到外讲透——有哪几类配置文件、优先级是怎样的、高频环境变量有哪些、常见踩坑怎么避、开发模式怎么配、以及怎么验证配置真的生效了。二、配置优先级谁覆盖谁在讲具体配置之前先把最重要的优先级搞清楚。Claude Code 的配置来源有很多它们按优先级从高到低排列高优先级的覆盖低优先级的。配置优先级金字塔图优先级配置来源说明1最高CLI 命令行标志--model、--permission-mode、--max-turns等当次启动生效2项目本地私有.claude/settings.local.json不提交 git优先级最高的配置文件3项目共享.claude/settings.json提交 git团队共享4用户全局~/.claude/settings.json所有项目生效5托管设置企业管理员部署的 managed-settings.json组织级6系统环境变量shell 里 export 的环境变量7最低程序默认值内置默认配置两个关键规则规则一环境变量 vs settings.json 的 env 字段如果同一个变量既在系统环境变量里设了又在 settings.json 的env字段里设了settings.json 的 env 字段优先级更高因为 settings.json 排在环境变量前面。但有个例外如果 settings.json 里有对应的专用设置键比如customApiUrl而环境变量里也设了比如ANTHROPIC_BASE_URL环境变量优先级更高。官方文档明确说如果两者都设置了环境变量具有更高的优先级。简单记settings.json 的 env 字段 系统环境变量但专用设置键 vs 环境变量环境变量赢。搞不清的时候用/config命令看当前生效的配置。规则二合并而非覆盖不同层级的配置不是简单的覆盖而是合并——更具体的配置添加到或覆盖更宽泛的配置。比如用户全局配了 3 个 MCP 服务器项目共享配了 2 个项目专用的 MCP最终生效的是 5 个全局 3 个 项目 2 个而不是只有项目的 2 个。但如果同一个键在两个层级都设了高优先级的覆盖低优先级的。比如全局设了model: sonnet项目设了model: opus最终生效的是opus。三、四类 settings.json哪个是哪个这是最多人搞混的地方。Claude Code 有四类 settings.json各管各的作用域、是否提交 git、优先级都不同。四类配置文件对比图类型路径作用域提交 git优先级适合放什么用户全局~/.claude/settings.json所有项目❌ 不提交4个人通用配置默认模型、全局 MCP、通用 Hooks、个人偏好项目共享.claude/settings.json当前项目✅ 提交3团队共享配置项目 MCP、团队 Hooks、权限规则、CLAUDE.md 引用项目本地私有.claude/settings.local.json当前项目本机❌ 不提交2敏感信息API Key、个人 token、本机路径、临时调试配置托管设置企业管理员部署整个组织管理员管理5企业策略安全规则、强制 MCP、权限限制、遥测配置怎么选1. 个人通用的配置 → 用户全局比如你所有项目都用同一个模型、都装了同样的几个 MCP、都有同样的 Hooks——这些放在~/.claude/settings.json里一次配置所有项目生效。2. 团队共享的配置 → 项目共享比如项目专用的 MCP 服务器、团队约定的 Hooks、权限规则——这些放在.claude/settings.json里提交 git团队成员 clone 项目后自动生效。3. 敏感信息和本机私有 → 项目本地私有比如 API Key、个人 token、本机绝对路径、临时调试用的配置——这些放在.claude/settings.local.json里绝对不要提交 git。这个文件应该加到.gitignore里。4. 企业策略 → 托管设置这个是企业管理员配置的普通用户不用管。它用于强制整个组织遵守安全策略比如禁用某些权限、强制安装安全 MCP、配置遥测。最常见的错误错误一把 API Key 写进项目共享配置.claude/settings.json会提交 git把 API Key 写进去等于把密钥公开给整个团队甚至公开给全世界如果是开源项目。API Key 必须写在.claude/settings.local.json里。错误二在项目共享配置里配了却被用户全局覆盖了比如你在项目里设了model: opus但你全局设了model: sonnet——因为项目共享优先级3比用户全局4高所以项目的 opus 会生效。等等不对优先级数字越小越高3 比 4 高所以项目共享覆盖用户全局。那为什么我之前说被覆盖了哦我之前的坑是我在项目共享3里配了新 key但用户全局4里配了旧 key——按优先级项目共享应该覆盖用户全局啊为什么没生效因为我配的是env字段里的环境变量而环境变量的合并规则可能不同——或者更可能的是我当时配错了文件根本没配在正确的位置。这就是为什么搞清楚四类文件的区别这么重要。简单记优先级数字越小越高。CLI标志(1) 项目本地(2) 项目共享(3) 用户全局(4) 托管(5) 环境变量(6) 默认(7)。四、高频环境变量分组速查Claude Code 支持的环境变量很多我把它们按用途分组方便你快速查找。高频环境变量分组速查表第一组连接认证变量作用示例ANTHROPIC_API_KEY官方 API Keysk-ant-xxxANTHROPIC_AUTH_TOKEN第三方平台的 API Key接入国产模型时用sk-xxxANTHROPIC_BASE_URL第三方 API 端点接入国产模型时用https://api.deepseek.comANTHROPIC_MODEL默认模型claude-sonnet-4-20250514ANTHROPIC_SMALL_FAST_MODEL轻量任务用的模型分类、提取等claude-haiku-4-20250414接入国产模型的三个变量缺一不可ANTHROPIC_AUTH_TOKENANTHROPIC_BASE_URLANTHROPIC_MODEL全部放在settings.local.json的env字段里。第 5 篇详细讲过。第二组模型与推理变量作用示例ANTHROPIC_MODEL默认模型claude-opus-4-20250514ANTHROPIC_SMALL_FAST_MODEL轻量任务模型claude-haiku-4-20250414ANTHROPIC_MAX_TOKENS最大输出 token 数8192ANTHROPIC_TEMPERATURE采样温度0确定性1随机性0.0追求输出稳定性时设ANTHROPIC_TEMPERATURE0.0——这对算法工程师做确定性推理很重要。第三组超时与限流变量作用示例ANTHROPIC_TIMEOUTAPI 请求超时时间秒600ANTHROPIC_MAX_RETRIESAPI 请求失败最大重试次数3CLAUDE_CODE_MAX_TURNS单次会话最大轮次100第四组隐私与遥测变量作用示例DISABLE_AUTO_COMPACT禁用自动上下文压缩1DISABLE_AUTOUPDATE禁用自动更新1CLAUDE_CODE_DISABLE_TELEMETRY禁用遥测数据收集1CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING禁用文件检查点第17篇讲过1第五组调试与开发变量作用示例CLAUDE_CODE_DEBUG开启调试模式输出详细日志1CLAUDE_CODE_LOG_LEVEL日志级别debug/info/warn/errordebugCLAUDE_CODE_DISABLE_SAFE_MODE禁用安全模式慎用1CLAUDE_CHROME_PERMISSION_MODEChrome 操作权限模式第19篇讲过skip_all_permission_checks调试配置出问题时设CLAUDE_CODE_DEBUG1启动会输出详细的加载日志帮你定位配置哪里出了问题。五、三种设置环境变量的方式环境变量有三种设置方式各有适用场景。方式一Shell 临时设置当前会话有效# 临时设置只在当前终端会话有效export ANTHROPIC_API_KEYsk-xxxexport ANTHROPIC_BASE_URLhttps://api.third-party.com # 然后启动 Claude Codeclaude适用场景临时测试、一次性使用、不想持久化的配置。关掉终端就失效了。方式二Shell 配置文件持久化所有终端有效把环境变量写进 shell 配置文件~/.bashrc、~/.zshrc、~/.bash_profile# ~/.zshrcexport ANTHROPIC_API_KEYsk-xxxexport ANTHROPIC_BASE_URLhttps://api.third-party.comexport ANTHROPIC_MODELclaude-sonnet-4-20250514然后source ~/.zshrc使其生效或者重启终端。适用场景全局通用的环境变量所有项目、所有终端都生效。注意把 API Key 写进 shell 配置文件有安全风险——任何能读取你 shell 配置的程序都能拿到你的 Key。更安全的方式是放在 settings.local.json 里或者用密码管理器管理。方式三settings.json 的 env 字段推荐在 settings.json 里用env字段设置环境变量{ env: { ANTHROPIC_API_KEY: sk-xxx, ANTHROPIC_BASE_URL: https://api.third-party.com, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }}这是最推荐的方式因为 1. 可以按项目隔离项目级 vs 用户全局 2. 敏感信息放在settings.local.json不会提交 git 3. 不需要改 shell 配置不影响其他程序 4. Claude Code 启动时自动加载不需要source六、常见踩坑这一节是血泪教训总结把最常见的配置坑列出来。坑一API Key 残留导致走 API 计费而非订阅这是最常见、最烧钱的坑。你之前为了测试接入了第三方 API在~/.claude/settings.json或 shell 配置里设了ANTHROPIC_API_KEY。后来你想切回官方订阅但忘了删掉那个环境变量。结果Claude Code 检测到有ANTHROPIC_API_KEY就走 API 计费而不是你的订阅。你以为在用订阅其实在按 token 烧钱——月底账单出来才发现。解决方法 1. 想切回订阅时检查所有配置文件里有没有ANTHROPIC_API_KEYbash grep -r ANTHROPIC_API_KEY ~/.claude/ .claude/ ~/.zshrc ~/.bashrc2. 找到后删掉或者注释掉 3. 重启 Claude Code 4. 用/status或/cost确认当前是订阅模式还是 API 模式经验法则如果你有订阅就不要在任何地方设 ANTHROPIC_API_KEY。设了就会走 API 计费。坑二改了配置不生效因为配错了文件就像我开场讲的坑——你在.claude/settings.json里配了但应该配在.claude/settings.local.json里或者你在项目里配了但被用户全局的配置覆盖了。解决方法 1. 先搞清楚四类配置文件的区别第三节 2. 敏感信息放settings.local.json团队共享放settings.json个人通用放~/.claude/settings.json3. 改完配置后重启 Claude Code很多配置需要重启才生效 4. 用/config命令查看当前生效的配置确认你的配置真的生效了坑三改了环境变量需要重启会话才生效环境变量是在 Claude Code 启动时加载的。如果你在会话进行中改了环境变量比如在另一个终端 export 了新的变量当前会话不会自动加载——你需要退出当前会话重新启动 Claude Code。解决方法改完环境变量后/exit退出当前会话重新启动claude。不要在会话进行中改环境变量然后期望它生效。坑四JSON 格式错误整个配置文件失效settings.json 是 JSON 格式一个逗号、一个引号错了整个文件就解析失败Claude Code 会忽略这个文件的所有配置。解决方法 1. 改完配置后用 JSON 校验工具检查格式bash python3 -m json.tool .claude/settings.local.json /dev/null echo JSON 格式正确 || echo JSON 格式错误2. 或者用jq检查bash jq . .claude/settings.local.json /dev/null3. 用--debug模式启动看有没有配置解析错误坑五把敏感配置提交到了 git你不小心把settings.local.json或者包含 API Key 的配置提交到了 git推到了远程仓库——密钥就泄露了。解决方法 1. 确保.gitignore里包含.claude/settings.local.json .claude/*.local.json .env2. 如果已经提交了立刻 - 轮换泄露的 API Key旧的作废生成新的 - 从 git 历史中移除敏感信息git filter-branch或 BFG Repo-Cleaner - 通知团队成员经验法则任何包含密钥、token、密码的文件绝对不能提交 git。提交前git status看一眼确认没有敏感文件。七、开发模式与调试技巧如果你在开发 Claude Code 的插件、Skills、或者调试配置问题这些技巧会帮到你。调试模式启动# 开启调试模式输出详细日志claude --debug # 或者用环境变量CLAUDE_CODE_DEBUG1 claude调试模式会输出 - 配置文件加载详情加载了哪些文件、哪些被覆盖了 - 插件加载详情哪些插件加载成功、哪些失败 - MCP 服务器连接详情 - API 请求和响应详情 - 错误堆栈配置出问题时第一时间用--debug启动看日志就能定位问题。查看当前生效的配置在 Claude Code 会话里输入/config会显示当前生效的所有配置包括 - 当前使用的模型 - 权限模式 - 已加载的 MCP 服务器 - 已启用的插件 - 环境变量部分 - 配置文件路径这是验证配置是否生效的最快方式。查看当前状态和认证/status显示当前认证状态、账号信息、是订阅模式还是 API 模式、当前模型等。插件开发调试开发插件时第18篇讲过# 重载插件不需要重启/reload-plugins # 验证插件配置claude plugin validate /path/to/plugin日志文件位置Claude Code 的日志文件存在~/.claude/logs/配置出问题、插件加载失败、MCP 连不上时去这里看日志。八、动手实验设置并验证一条环境变量光看不练没用。下面用一个最小流程让你亲手设置一条环境变量并验证它生效。第一步创建项目本地私有配置文件在项目根目录创建.claude/settings.local.json如果不存在{ env: { ANTHROPIC_MODEL: claude-haiku-4-20250414 }}这里我们把默认模型设为 haiku轻量模型省钱。第二步确保这个文件不会被提交 git检查.gitignore里有没有.claude/settings.local.json如果没有加上。然后确认 git 不会追踪这个文件git status你应该看不到.claude/settings.local.json如果看到了说明.gitignore没配好。第三步重启 Claude Code退出当前会话/exit重新启动claude。第四步验证配置生效在 Claude Code 里输入/config看看当前模型是不是claude-haiku-4-20250414。如果是说明配置生效了。也可以用/status查看当前模型。第五步测试切换模型在会话里用/model切换到 sonnet然后再/config看——当前会话的模型变成了 sonnet但配置文件里的默认模型还是 haiku下次启动会回到 haiku。这说明配置文件里的模型是启动时的默认值会话中用/model切换只影响当前会话不影响配置文件。第六步清理实验完了把settings.local.json里的模型改回你常用的或者删掉这行用默认值重启 Claude Code。走完这六步你就对环境变量的设置、优先级、验证方式有了真实体感以后配置出问题也知道怎么排查了。本篇小结维度一句话记住优先级CLI标志(1) 项目本地(2) 项目共享(3) 用户全局(4) 托管(5) 环境变量(6) 默认(7)数字越小越高四类配置文件用户全局(~/.claude/settings.json)、项目共享(.claude/settings.json提交git)、项目本地私有(.claude/settings.local.json不提交git)、托管设置(企业管理员)敏感信息放哪必须放 settings.local.json绝对不能提交 git接入国产模型三变量ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL ANTHROPIC_MODEL缺一不可三种设置方式shell临时(当前会话)、shell配置文件(全局持久)、settings.json的env字段(推荐按项目隔离)坑一API Key残留有订阅就不要设 ANTHROPIC_API_KEY设了就走API计费月底烧钱坑二配错文件敏感信息放local团队共享放settings.json个人通用放全局坑三需要重启改完环境变量/配置文件必须重启Claude Code才生效坑四JSON格式错一个逗号错了整个文件失效改完用jq校验坑五敏感配置提交git.gitignore必须包含settings.local.json提交了立刻轮换密钥调试技巧--debug启动看日志、/config看当前生效配置、/status看认证状态、~/.claude/logs/看日志文件你现在应该能理解配置优先级谁覆盖谁、搞清楚四类settings.json的区别、知道高频环境变量的分组和作用、会用三种方式设置环境变量、能避开5个常见踩坑、会用调试模式和/config验证配置、能亲手设置并验证一条环境变量。说到底配置的本质只有一句话搞清楚哪个文件管什么、谁覆盖谁、敏感信息别提交 git——改完重启用 /config 验证别瞎折腾。资料展示下面是我整理的AI大模型 学习资料和工具包预览适合收藏后按主题逐步学习。如果你想看完整资料目录可以在评论区留言「资料」也欢迎告诉我你更关注AI大模型里的哪类内容。
