Claude Code 配置完全指南（二）：settings.json 逐行拆解 Claude Code 配置完全指南二settings.json 逐行拆解系列第 2 篇 | 2026-07-22配套仓库C:\Users\zhang\.claude前言上篇我们鸟瞰了.claude的整体结构本篇聚焦最核心的两个文件settings.json云端同步和settings.local.json本机独享。我们逐行拆解真实配置把每个字段的含义、最佳实践和常见坑都说清楚。一、settings.json 逐行解读以下是我的完整settings.json19行{env:{ANTHROPIC_AUTH_TOKEN:PROXY_MANAGED,ANTHROPIC_BASE_URL:http://127.0.0.1:15721,ANTHROPIC_DEFAULT_HAIKU_MODEL:claude-haiku-4-5,ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME:agnes-2.0-flash,ANTHROPIC_DEFAULT_OPUS_MODEL:claude-opus-4-8,ANTHROPIC_DEFAULT_OPUS_MODEL_NAME:agnes-2.0-flash,ANTHROPIC_DEFAULT_SONNET_MODEL:claude-sonnet-4-6,ANTHROPIC_DEFAULT_SONNET_MODEL_NAME:agnes-2.0-flash,EDITOR:code,VISUAL:code},enabledPlugins:{frontend-designclaude-plugins-official:true,superpowersclaude-plugins-official:true}}1.1ANTHROPIC_AUTH_TOKENANTHROPIC_AUTH_TOKEN:PROXY_MANAGEDPROXY_MANAGED是一个特殊值告诉 Claude Code「认证由代理层管理不要自己去读 key」。这在你使用第三方 API 代理如 OpenRouter、OneAPI、或者自建代理时使用。背后的逻辑是API 请求发到ANTHROPIC_BASE_URL指定的地址代理在请求头中注入真实的 API KeyClaude Code 不感知、不存储、不泄露你的真实 Key常见误区如果你用的是 Anthropic 官方 API这里应该填你的真实sk-ant-xxxkey而不是PROXY_MANAGED。1.2ANTHROPIC_BASE_URLANTHROPIC_BASE_URL:http://127.0.0.1:15721将所有 API 请求指向本地代理127.0.0.1:15721。我的环境中运行了一个本地代理服务可能是 litellm 或者自建转发负责将请求转换为 Anthropic API 格式并注入认证信息。配置场景对照表场景BASE_URL 示例官方 API不填使用默认https://api.anthropic.com本地代理http://127.0.0.1:15721OpenRouterhttps://openrouter.ai/api/v1OneAPIhttp://your-server:3000/v11.3 模型映射三对_MODEL/_MODEL_NAMEANTHROPIC_DEFAULT_HAIKU_MODEL:claude-haiku-4-5,ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME:agnes-2.0-flash,这是 Claude Code 最容易被误解的配置。这里有两层映射字段含义示例值_MODEL你告诉 Claude Code 要调用的模型名claude-haiku-4-5_MODEL_NAME实际发送给 API 的模型名agnes-2.0-flash为什么需要两层因为代理可能使用不同的模型命名。比如我的本地代理把 Anthropic 的三个模型都映射到了同一个内部模型agnes-2.0-flash但 Claude Code 仍然认为自己在使用 Haiku/Sonnet/Opus 三个不同能力的模型不同的 system prompt 和上下文窗口限制。三档模型的默认分工档位模型Claude Code 默认用途Haikuclaude-haiku-4-5轻量任务文件列表、简单替换Sonnetclaude-sonnet-4-6主力代码生成、分析、对话Opusclaude-opus-4-8复杂推理架构设计、大段重构1.4EDITOR/VISUALEDITOR:code,VISUAL:code指定 Claude Code 使用的默认编辑器。当 Claude Code 需要你手动编辑文件时会调用这个编辑器打开文件。EDITOR→ 命令行编辑器如vim、nanoVISUAL→ GUI 编辑器如code、subl都设为code表示统一使用 VS Code。如果你更习惯用 Cursor设为cursor即可。1.5enabledPluginsenabledPlugins:{frontend-designclaude-plugins-official:true,superpowersclaude-plugins-official:true}插件命名规范插件名发布者。我启用了两个官方插件frontend-design前端设计辅助生成 UI 代码、组件布局superpowers增强能力合集可能是子代理、技能扩展等要禁用某个插件把true改为false或直接删除该行。二、settings.local.json 逐行解读settings.local.json不同步到云端适合存放敏感配置和机器特有的设置。我的文件 49 行核心分两块。2.1env本地环境变量env:{PIP_INDEX_URL:https://pypi.tuna.tsinghua.edu.cn/simple}我在这里设置了清华 PyPI 镜像。这很实用——你在公司电脑可能需要内网镜像在家用阿里云镜像但 Agent 定义可以统一。建议放到 local 的环境变量PIP_INDEX_URL、NPM_REGISTRY等镜像地址http_proxy、https_proxy等代理设置API_KEY_xxx等密钥配合PROXY_MANAGED时不需要操作系统特定的路径变量2.2permissions.allow权限白名单permissions:{allow:[Bash(curl:*),Bash(chmod:*),Bash(dir:*),Bash(mkdir:*),Bash(python:*),Bash(findstr:*),WebSearch,WebFetch(domain:python.langchain.com),Bash(claude mcp *),mcp__obsidian-local-rest-api__vault_list,...]}这是 Claude Code 安全模型的核心——默认拒绝一切危险操作只有白名单中的命令才能自动执行。权限格式规则格式示例含义Bash(命令名)Bash(python:*)允许执行python开头的所有命令Bash(完整路径)Bash(D:\\LEO\\bin\\anaconda3\\python.exe --version)只允许精确匹配的这一条命令Bash(路径:*)Bash(D:\\LEO\\bin\\anaconda3\\python.exe:*)允许该路径下的所有子命令WebSearchWebSearch允许网络搜索WebFetch(domain:xxx)WebFetch(domain:python.langchain.com)只允许抓取指定域名mcp__服务名__工具名mcp__obsidian-local-rest-api__vault_list允许调用特定 MCP 工具我的白名单分析Python 权限比较宽松Bash(python:*)和Bash(D:\\LEO\\bin\\anaconda3\\python.exe:*)同时存在说明我信任 Claude Code 执行 Python 脚本pip install 带路径限制只允许特定 conda 环境下的 pip防止误装到系统 PythonWebFetch 限定域名只允许抓python.langchain.com等少数几个域名MCP 工具精确授权逐工具授权 Obsidian MCP 的vault_list、search_query、vault_read三、两者如何协同覆盖规则settings.local.json settings.json如果同一字段在两个文件中都存在settings.local.json的值胜出。具体到env和permissionsenv合并local 中的同名字段覆盖 globalpermissionsClaude Code 会合并两份白名单而不是替换所以你在 global 中设置的权限依然生效enabledPlugins合并任一文件中设为true的插件都会启用四、常见配置错误4.1 模型名写错导致全部请求失败// ❌ 错误Anthropic 没有这个模型ANTHROPIC_DEFAULT_SONNET_MODEL:claude-3.5-sonnet// ✅ 正确ANTHROPIC_DEFAULT_SONNET_MODEL:claude-sonnet-4-6症状Claude Code 启动后所有请求超时或返回 404。4.2 权限白名单路径用了正斜杠Windows// ❌ Windows 下错误Bash(\D:/LEO/bin/anaconda3/python.exe\:*)// ✅ 双反斜杠Bash(\D:\\LEO\\bin\\anaconda3\\python.exe\:*)症状白名单不生效每次python命令都要手动确认。4.3 把密钥写到 settings.json// ❌ 危险settings.json 会同步到云端env:{ANTHROPIC_AUTH_TOKEN:sk-ant-actual-key-here}// ✅ 应该放到 settings.local.json五、我的推荐配置模板// settings.local.json不同步、本机独享{env:{PIP_INDEX_URL:https://pypi.tuna.tsinghua.edu.cn/simple,NPM_REGISTRY:https://registry.npmmirror.com},permissions:{allow:[Bash(python:*),Bash(pip:*),Bash(git:*),Bash(npm:*),Bash(dir:*),Bash(mkdir:*),Bash(findstr:*),WebSearch,WebFetch(domain:*)]}}这个模板适合大多数开发者允许 Python/pip/git/npm 自动执行允许网络搜索和任意网页抓取但更敏感的命令如rm、del、curl仍需手动确认。下一篇预告下一篇我们深入agents/目录以我的fullstack-developer.md为例逐段拆解一个生产级 Agent 的定义角色设定、工具权限、工作流编排、编码规范——以及如何让你的 Agent 真正听话。你的permissions.allow白名单里加了哪些规则有没有踩过路径格式的坑评论区聊聊。