settings.json 完整字段参考

沉淀沉淀再沉淀
5 阅读4分钟

settings.json 完整字段参考

settings.json 是 Claude Code 的运行时配置文件，控制模型、权限、MCP 服务器、Hooks 等所有运行行为。

文件位置

~/.claude/settings.json           全局配置（对所有项目生效）
./.claude/settings.json           项目级配置（仅当前项目，会合并到全局配置）

合并规则：项目级配置合并（不是覆盖）全局配置。相同字段以项目级为准，独有字段各自保留。

完整字段结构

{
  "model": "claude-opus-4-6",
  "env": {},
  "permissions": {
    "allow": [],
    "deny": []
  },
  "mcpServers": {},
  "hooks": {},
  "includeCoAuthoredBy": true,
  "theme": "dark"
}

字段详解

model — 默认模型

{
  "model": "claude-opus-4-6"
}
值说明
"claude-opus-4-6"最强推理，适合复杂任务
"claude-sonnet-4-6"均衡，日常开发首选
"claude-haiku-4-5-20251001"最快最省，简单任务

可在会话中用 /model <ID> 临时覆盖。

env — 环境变量

在 Claude 执行 Bash 命令时注入的环境变量：

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost/mydb",
    "MY_CUSTOM_VAR": "value"
  }
}

优先级：settings.json 中的 env > 系统环境变量。

安全注意：不要把 settings.json 提交到 git！密钥放这里只适合个人机器。

permissions — 工具权限控制

{
  "permissions": {
    "allow": ["规则1", "规则2"],
    "deny": ["规则3", "规则4"]
  }
}

规则优先级：deny > allow。同一操作同时在 allow 和 deny 中，以 deny 为准。

权限规则语法

格式："工具名" 或 "工具名(参数模式)"

// 允许/禁止所有该工具的调用
"Read"
"Write"
"Edit"
"Bash"
"Glob"
"Grep"
"Agent"
"WebFetch"

// 允许/禁止特定命令（仅对 Bash 有效）
"Bash(git *)"              // 所有 git 命令
"Bash(npm test)"           // 精确匹配 npm test
"Bash(npm run *)"          // 所有 npm run 子命令
"Bash(git status)"         // 精确匹配

通配符规则：

  • * 匹配任意字符（包括空格和子命令）
  • 不支持正则表达式
  • 括号内是命令内容的精确或通配匹配
完整推荐配置示例
{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep",
      "Bash(ls *)",
      "Bash(cat *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git checkout *)",
      "Bash(git branch *)",
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(yarn *)",
      "Bash(node *)",
      "Bash(npx *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(git clean -f *)",
      "Bash(chmod 777 *)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)"
    ]
  }
}

mcpServers — MCP 服务器配置

{
  "mcpServers": {
    "服务器名称": {
      // SSE 类型（通过 HTTP 连接）
      "type": "sse",
      "url": "http://localhost:端口/path",

      // 或 stdio 类型（通过标准输入输出连接）
      "type": "stdio",
      "command": "执行命令",
      "args": ["参数1", "参数2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}
SSE vs stdio 选择指南
类型适用场景特点
sse服务已独立运行（IDE 插件、Chrome 调试端口）连接到已有服务
stdio需要 Claude Code 启动服务Claude Code 管理进程生命周期
完整 MCP 配置示例
{
  "mcpServers": {
    "chrome-devtools": {
      "type": "sse",
      "url": "http://localhost:9222/json/mcp/sse"
    },
    "webstorm-index": {
      "type": "sse",
      "url": "http://IDE_MCP_HOST:PORT/sse"
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost/mydb"]
    }
  }
}

hooks — 生命周期钩子

{
  "hooks": {
    "事件名": [
      {
        "type": "command",
        "command": "bash 命令"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "工具名",
        "hooks": [
          {
            "type": "command",
            "command": "检查命令"
          }
        ]
      }
    ]
  }
}
支持的事件类型
事件触发时机典型用途
SessionStart会话开始时同步知识库、打印环境信息
PreToolUse工具调用前安全检查、拦截危险操作
PostToolUse工具调用后自动 lint、运行测试
NotificationClaude 需要通知时发送消息到 Slack/钉钉
StopClaude 完成任务/会话结束时提示经验回写
PreToolUse 的 matcher 匹配
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",           // 精确匹配工具名
        "hooks": [{ "type": "command", "command": "检查命令" }]
      },
      {
        "matcher": "Write|Edit",     // 多工具匹配（OR）
        "hooks": [{ "type": "command", "command": "自动 lint" }]
      }
    ]
  }
}
Hook 脚本的退出码
退出码效果
0成功，继续执行工具
非 0失败，阻止工具执行（仅对 PreToolUse 有效）

Hook 的 stdout 显示给用户，stderr 记录到日志。

includeCoAuthoredBy — Commit 署名

{
  "includeCoAuthoredBy": true
}

为 true 时，/commit 生成的 commit 会自动包含：

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

theme — 界面主题

{
  "theme": "dark"
}

可选值："dark" | "light" | "auto"

完整配置示例（生产推荐）

{
  "model": "claude-opus-4-6",
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx"
  },
  "permissions": {
    "allow": [
      "Read", "Write", "Edit", "Glob", "Grep",
      "Bash(git *)",
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(ls *)",
      "Bash(cat *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)"
    ]
  },
  "mcpServers": {
    "chrome-devtools": {
      "type": "sse",
      "url": "http://localhost:9222/json/mcp/sse"
    },
    "webstorm-index": {
      "type": "sse",
      "url": "http://IDE_MCP_HOST:PORT/sse"
    }
  },
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "cd ~/Documents/git/team-knowledge && git pull --quiet 2>&1 | tail -1"
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": "echo '[EVOLUTION_CHECK] 会话结束 - 有新发现请执行 /team-learn'"
      }
    ]
  },
  "includeCoAuthoredBy": true,
  "theme": "dark"
}

验证配置文件是否有效

# 验证 JSON 格式
python3 -m json.tool ~/.claude/settings.json

# 验证 Claude Code 能读取配置
claude --debug 2>&1 | grep "settings"

常见格式错误：

  • 尾逗号（JSON 不允许）："key": "value",（最后一项后有逗号）
  • 注释（JSON 不支持 // 注释）
  • 单引号（JSON 要求双引号）
avatar
文章
阅读
粉丝