设置参考

Claude Code 提供丰富的配置项，可以通过 settings.json 文件或 /config 命令调整。本文是所有配置选项的完整参考。

配置作用域

Claude Code 使用分层配置系统，不同位置的配置影响不同范围：

作用域	位置	影响范围	是否共享
托管	MDM/注册表/managed-settings.json	机器上所有用户	是（IT 部署）
用户	~/.claude/settings.json	你的所有项目	否
项目	.claude/settings.json	仓库所有协作者	是（提交到 git）
本地	.claude/settings.local.json	仅你在此仓库	否（gitignore）

使用场景

• 托管：全组织强制执行的安全策略、合规要求
• 用户：个人偏好（主题、编辑器）、跨项目工具
• 项目：团队共享的权限、Hooks、MCP 服务器
• 本地：个人对特定项目的覆盖、测试配置

优先级（从高到低）

1. 托管设置（不可覆盖）
2. 命令行参数（临时覆盖）
3. 本地项目设置（.claude/settings.local.json）
4. 共享项目设置（.claude/settings.json）
5. 用户设置（~/.claude/settings.json）

数组合并：数组类型的设置（如 permissions.allow、sandbox.filesystem.allowWrite）跨作用域会合并（拼接去重），不是覆盖。低优先级可以追加，高优先级也可以追加。

配置文件示例

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

加上 $schema 行后，VS Code 和 Cursor 会提供自动补全和验证。

核心设置项

键	说明	示例值
model	覆盖默认模型	"claude-sonnet-4-6"
effortLevel	思考深度：low/medium/high	"medium"
alwaysThinkingEnabled	默认开启扩展思考	true
language	Claude 的响应语言	"japanese"
env	每次会话都注入的环境变量	{"FOO": "bar"}
autoUpdatesChannel	更新频道：latest 或 stable	"stable"
cleanupPeriodDays	会话历史保留天数（0=不保留）	30
plansDirectory	计划文件存储目录	"./plans"
statusLine	自定义状态栏显示	见下方
outputStyle	调整系统提示的输出风格	"Explanatory"
agent	以指定子代理的身份运行主线程	"code-reviewer"
includeGitInstructions	是否注入内置 git 工作流指令（默认 true）	false
companyAnnouncements	启动时循环显示的公告	["Welcome to Acme!"]

权限设置

详细语法见权限配置文档。

键	说明	示例值
permissions.allow	允许的工具规则数组	["Bash(git diff *)"]
permissions.ask	需要确认的工具规则数组	["Bash(git push *)"]
permissions.deny	拒绝的工具规则数组	["WebFetch", "Read(./.env)"]
permissions.additionalDirectories	额外可访问的目录	["../docs/"]
permissions.defaultMode	默认权限模式	"acceptEdits"
permissions.disableBypassPermissionsMode	禁止 bypassPermissions 模式	"disable"

沙箱设置

沙箱隔离 Bash 命令的文件系统和网络访问，与权限系统互补。

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  }
}

沙箱选项详解

键	说明	默认值
sandbox.enabled	启用沙箱（macOS、Linux、WSL2）	false
sandbox.autoAllowBashIfSandboxed	沙箱内自动批准 Bash 命令	true
sandbox.excludedCommands	在沙箱外运行的命令	[]
sandbox.allowUnsandboxedCommands	允许通过 dangerouslyDisableSandbox 参数逃出沙箱	true

文件系统沙箱

键	说明
sandbox.filesystem.allowWrite	沙箱内可写的额外路径（数组跨作用域合并）
sandbox.filesystem.denyWrite	沙箱内禁止写入的路径
sandbox.filesystem.denyRead	沙箱内禁止读取的路径
sandbox.filesystem.allowRead	在 denyRead 区域内重新允许读取（优先级更高）

网络沙箱

键	说明	默认值
sandbox.network.allowedDomains	允许的出站域名（支持 *.example.com 通配符）
sandbox.network.allowUnixSockets	允许访问的 Unix Socket 路径
sandbox.network.allowAllUnixSockets	允许所有 Unix Socket 连接	false
sandbox.network.allowLocalBinding	允许绑定 localhost 端口（仅 macOS）	false
sandbox.network.httpProxyPort	自定义 HTTP 代理端口
sandbox.network.socksProxyPort	自定义 SOCKS5 代理端口

沙箱路径前缀

前缀	含义
/	从文件系统根的绝对路径
~/	相对于家目录
./ 或无前缀	相对于项目根（项目设置）或 ~/.claude（用户设置）

模型设置

{
  "model": "claude-sonnet-4-6",
  "availableModels": ["sonnet", "haiku"],
  "modelOverrides": {
    "claude-opus-4-6": "arn:aws:bedrock:us-east-1:123456789:inference-profile/..."
  }
}

键	说明
model	覆盖默认模型
availableModels	限制用户可以通过 /model 选择的模型列表
modelOverrides	将 Anthropic 模型 ID 映射到 Bedrock ARN 等提供商 ID

归因设置

Claude Code 默认在 git commit 和 PR 中添加归因信息：

{
  "attribution": {
    "commit": "🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>",
    "pr": ""
  }
}

设为空字符串可隐藏归因。

Worktree 设置

优化大型单仓库（monorepo）中 --worktree 的性能：

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"],
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}

键	说明
worktree.symlinkDirectories	从主仓库软链接到 worktree 的目录，避免磁盘重复占用
worktree.sparsePaths	使用 git sparse-checkout 只检出指定路径，加速大型仓库

文件建议设置

自定义 @ 文件路径补全命令：

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

命令通过 stdin 接收 JSON：

{"query": "src/comp"}

在 stdout 输出换行分隔的文件路径（最多 15 条）。

状态栏设置

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

插件设置

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": "github",
      "repo": "acme-corp/claude-plugins"
    }
  }
}

用 /plugin 命令交互式管理插件（浏览、安装、启用/禁用）。

MCP 相关设置

键	说明
enableAllProjectMcpServers	自动批准项目 .mcp.json 中的所有 MCP 服务器
enabledMcpjsonServers	只批准列出的 MCP 服务器
disabledMcpjsonServers	拒绝列出的 MCP 服务器

全局配置项（~/.claude.json）

这些项存储在 ~/.claude.json，不在 settings.json 中（否则会报 schema 错误）：

键	说明	默认值
autoConnectIde	从外部终端启动时自动连接 IDE	false
autoInstallIdeExtension	从 VS Code 终端启动时自动安装扩展	true
editorMode	输入框键绑定模式：normal 或 vim	"normal"
showTurnDuration	响应后显示用时信息	true
terminalProgressBarEnabled	显示终端进度条	true

企业托管设置（仅 managed-settings.json）

键	说明
disableBypassPermissionsMode	设为 "disable" 全局禁止跳过权限模式
allowManagedPermissionRulesOnly	仅允许托管权限规则，用户/项目规则无效
allowManagedHooksOnly	仅允许托管 Hooks
allowManagedMcpServersOnly	仅允许托管 MCP 服务器白名单
channelsEnabled	Team/Enterprise 用户启用 Channels 功能
allowedMcpServers	MCP 服务器白名单
deniedMcpServers	MCP 服务器黑名单
strictKnownMarketplaces	允许的插件市场
blockedMarketplaces	屏蔽的插件市场
pluginTrustMessage	自定义插件信任警告附加信息
forceLoginMethod	限定登录方式：claudeai 或 console
forceLoginOrgUUID	自动选择指定组织（需配合 forceLoginMethod）

托管设置文件位置

系统	路径
macOS	/Library/Application Support/ClaudeCode/managed-settings.json
Linux/WSL	/etc/claude-code/managed-settings.json
Windows	C:\Program Files\ClaudeCode\managed-settings.json

验证当前设置

在 Claude Code 中运行 /status 可以查看所有激活的配置来源，包括托管设置来自哪里（远程、plist、注册表还是文件）。如果 settings.json 有语法错误，/status 会报告具体问题。

排除敏感文件

推荐在 .claude/settings.json 中添加：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)"
    ]
  }
}

相关资源

• 权限配置：权限规则语法和工具特定示例
• Hooks：生命周期自动化
• MCP：外部工具集成
• 子代理：自定义子代理配置