Claude Code 配置完全指南（二）：settings.json 逐行拆解

系列第 2 篇 | 2026-07-22
配套仓库：C:\Users\zhang\.claude

---

前言

上篇我们鸟瞰了 .claude 的整体结构，本篇聚焦最核心的两个文件：settings.json（云端同步）和 settings.local.json（本机独享）。我们逐行拆解真实配置，把每个字段的含义、最佳实践和常见坑都说清楚。

---

一、settings.json 逐行解读

以下是我的完整 settings.json（19行）：

{
  "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-design@claude-plugins-official": true,
    "superpowers@claude-plugins-official": true
  }
}

1.1 ANTHROPIC_AUTH_TOKEN

"ANTHROPIC_AUTH_TOKEN": "PROXY_MANAGED"

PROXY_MANAGED 是一个特殊值，告诉 Claude Code：「认证由代理层管理，不要自己去读 key」。这在你使用第三方 API 代理（如 OpenRouter、OneAPI、或者自建代理）时使用。背后的逻辑是：

• API 请求发到 ANTHROPIC_BASE_URL 指定的地址
• 代理在请求头中注入真实的 API Key
• Claude Code 不感知、不存储、不泄露你的真实 Key

常见误区：如果你用的是 Anthropic 官方 API，这里应该填你的真实 sk-ant-xxx key，而不是 PROXY_MANAGED。

1.2 ANTHROPIC_BASE_URL

"ANTHROPIC_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:15721
OpenRouter	https://openrouter.ai/api/v1
OneAPI	http://your-server:3000/v1

1.3 模型映射：三对 _MODEL / _MODEL_NAME

"ANTHROPIC_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 默认用途
Haiku	claude-haiku-4-5	轻量任务：文件列表、简单替换
Sonnet	claude-sonnet-4-6	主力：代码生成、分析、对话
Opus	claude-opus-4-8	复杂推理：架构设计、大段重构

1.4 EDITOR / VISUAL

"EDITOR": "code",
"VISUAL": "code"

指定 Claude Code 使用的默认编辑器。当 Claude Code 需要你手动编辑文件时，会调用这个编辑器打开文件。

• EDITOR → 命令行编辑器（如 vim、nano）
• VISUAL → GUI 编辑器（如 code、subl）

都设为 code 表示统一使用 VS Code。如果你更习惯用 Cursor，设为 cursor 即可。

1.5 enabledPlugins

"enabledPlugins": {
    "frontend-design@claude-plugins-official": true,
    "superpowers@claude-plugins-official": true
}

插件命名规范：<插件名>@<发布者>。

我启用了两个官方插件：

• frontend-design：前端设计辅助（生成 UI 代码、组件布局）
• superpowers：增强能力合集（可能是子代理、技能扩展等）

要禁用某个插件，把 true 改为 false 或直接删除该行。

---

二、settings.local.json 逐行解读

settings.local.json 不同步到云端，适合存放敏感配置和机器特有的设置。我的文件 49 行，核心分两块。

2.1 env：本地环境变量

"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.2 permissions.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":*)	允许该路径下的所有子命令
WebSearch	WebSearch	允许网络搜索
WebFetch(domain:xxx)	WebFetch(domain:python.langchain.com)	只允许抓取指定域名
mcp__服务名__工具名	mcp__obsidian-local-rest-api__vault_list	允许调用特定 MCP 工具

我的白名单分析：

1. Python 权限比较宽松：Bash(python:*) 和 Bash("D:\\LEO\\bin\\anaconda3\\python.exe":*) 同时存在，说明我信任 Claude Code 执行 Python 脚本
2. pip install 带路径限制：只允许特定 conda 环境下的 pip，防止误装到系统 Python
3. WebFetch 限定域名：只允许抓 python.langchain.com 等少数几个域名
4. MCP 工具精确授权：逐工具授权 Obsidian MCP 的 vault_list、search_query、vault_read

---

三、两者如何协同：覆盖规则

settings.local.json  >  settings.json

如果同一字段在两个文件中都存在，settings.local.json 的值胜出。具体到 env 和 permissions：

• env：合并，local 中的同名字段覆盖 global
• permissions：Claude 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 白名单里加了哪些规则？有没有踩过路径格式的坑？评论区聊聊。