配置详解

Mr.xiaou2026/4/26大约 7 分钟快速入门

配置详解

通过 /config 命令或编辑 JSON 文件来配置 Claude Code。支持 JSON Schema 自动补全，在文件头部加上：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

配置体系

四个作用域

作用域	文件位置	影响范围	团队共享
托管	服务器/MDM/注册表/`managed-settings.json`	全机器所有用户	是（IT 部署）
用户	`~/.claude/settings.json`	你所有项目	否
项目	`.claude/settings.json`	仓库所有协作者	是（提交 Git）
本地	`.claude/settings.local.json`	仅你在此仓库	否（自动 gitignore）

优先级（从高到低）

托管设置 > CLI 标志 > 本地项目 > 共享项目 > 用户级

提示

团队项目：共享配置放 .claude/settings.json（提交 Git），个人偏好放 .claude/settings.local.json（自动 gitignore）。

作用域适用范围

功能	用户位置	项目位置
Settings	`~/.claude/settings.json`	`.claude/settings.json`
子代理	`~/.claude/agents/`	`.claude/agents/`
MCP 服务器	`~/.claude.json`	`.mcp.json`
CLAUDE.md	`~/.claude/CLAUDE.md`	`CLAUDE.md` 或 `.claude/CLAUDE.md`

托管设置部署

企业 IT 可通过以下方式部署不可覆盖的配置：

平台	部署方式
macOS	`com.anthropic.claudecode` MDM 偏好域（Jamf/Kandji 等）
Windows	`HKLM\SOFTWARE\Policies\ClaudeCode` 注册表（Group Policy/Intune）
文件	`managed-settings.json` + `managed-settings.d/*.json` drop-in 目录

文件路径：macOS /Library/Application Support/ClaudeCode/，Linux/WSL /etc/claude-code/，Windows C:\Program Files\ClaudeCode\。

常用配置

日常使用中最常调整的设置项。

模型与推理

{
  "model": "claude-sonnet-4-6",
  "alwaysThinkingEnabled": true,
  "effortLevel": "medium",
  "availableModels": ["sonnet", "haiku", "opus"]
}

设置项	说明	默认值
`model`	默认模型	sonnet
`alwaysThinkingEnabled`	始终启用扩展思考	true
`effortLevel`	推理深度：`low` / `medium` / `high` / `xhigh`	medium
`availableModels`	限制用户可选模型列表	不限制

effortLevel 在运行 /effort 时自动写入并跨会话保持。

语言与界面

{
  "language": "chinese",
  "outputStyle": "Explanatory",
  "viewMode": "default",
  "tui": "fullscreen"
}

设置项	说明	默认值
`language`	响应语言（如 `"chinese"`、`"japanese"`、`"spanish"`）	en
`outputStyle`	输出风格，调整系统提示	-
`viewMode`	启动时默认视图：`default` / `verbose` / `focus`	default
`tui`	终端渲染器：`fullscreen`（无闪烁） / `default`	fullscreen
`defaultShell`	`!` 命令的 shell：`"bash"` / `"powershell"`	bash

权限配置

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(git *)",
      "Bash(npm run *)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

设置项	说明
`allow`	自动允许的工具规则
`ask`	需确认的工具规则
`deny`	拒绝的工具规则（优先级最高）
`defaultMode`	默认权限模式：`default` / `acceptEdits` / `plan` / `auto` / `dontAsk`
`additionalDirectories`	额外的工作目录

规则语法：Tool 或 Tool(specifier)，支持通配符。

规则	效果
`Bash`	匹配所有 Bash 命令
`Bash(npm run *)`	匹配以 `npm run` 开头的命令
`Read(./.env)`	匹配读取 `.env` 文件
`WebFetch(domain:example.com)`	匹配请求 example.com

评估顺序：deny → ask → allow，第一个匹配的规则生效。

环境变量

{
  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

每个会话都会应用这些环境变量。也可以通过系统环境变量控制，env 设置中的值会覆盖。

沙箱配置

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["src/", "tests/"],
      "denyWrite": [".env", "config/production/"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "allowLocalBinding": true
    }
  }
}

设置项	说明	默认值
`enabled`	启用 bash 沙箱	false
`autoAllowBashIfSandboxed`	沙箱内自动批准 bash 命令	true
`excludedCommands`	不在沙箱内运行的命令	[]
`allowUnsandboxedCommands`	允许逃逸沙箱	true
`filesystem.allowWrite`	允许写入的路径	[]
`filesystem.denyWrite`	禁止写入的路径	[]
`filesystem.denyRead`	禁止读取的路径	[]
`network.allowedDomains`	允许的网络域名（支持通配符）	[]
`network.allowLocalBinding`	允许绑定 localhost 端口	false

路径前缀：/ 绝对路径，~/ 相对 home 目录，./ 或无前缀相对项目根目录。

Hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "ruff check --fix $FILE_PATH" }]
      }
    ]
  }
}

详见权限与安全。

会话管理

设置项	说明	默认值
`cleanupPeriodDays`	会话文件保留天数	30
`plansDirectory`	计划文件存储路径	`~/.claude/plans`
`autoUpdatesChannel`	更新通道：`stable` / `latest`	latest
`awaySummaryEnabled`	离开后显示会话摘要	true

其他配置

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

这些设置存储在 ~/.claude.json 中，不能放在 settings.json 里：

设置项	说明	默认值
`autoConnectIde`	从外部终端启动时自动连接 IDE	false
`autoInstallIdeExtension`	自动安装 IDE 扩展	true
`autoScrollEnabled`	全屏模式自动滚动到底部	true
`editorMode`	输入框键绑定：`normal` / `vim`	normal
`externalEditorContext`	外部编辑器中显示上次响应作为上下文	false
`showTurnDuration`	显示每轮响应耗时	true
`terminalProgressBarEnabled`	终端进度条（iTerm2/Ghostty 等）	true
`teammateMode`	Agent 团队显示方式：`auto` / `in-process` / `tmux`	auto

Worktree 配置

大型 monorepo 中减少磁盘占用和启动时间：

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

设置项	说明
`symlinkDirectories`	从主仓库符号链接到 worktree 的目录
`sparsePaths`	git sparse-checkout 只检出这些路径

用 .worktreeinclude 文件复制 gitignored 文件（如 .env）到新 worktree。

界面与交互

设置项	说明	默认值
`showThinkingSummaries`	显示扩展思考摘要	false（交互模式）
`spinnerTipsEnabled`	显示加载提示	true
`spinnerTipsOverride`	自定义加载提示内容	-
`spinnerVerbs`	自定义加载动词（`"replace"` / `"append"` 模式）	-
`prefersReducedMotion`	减少动画效果（无障碍）	false
`voiceEnabled`	启用语音输入	false
`feedbackSurveyRate`	质量调查出现概率（0-1）	默认采样率
`respectGitignore`	`@` 文件选择器遵守 `.gitignore`	true
`statusLine`	自定义状态栏脚本	-
`showClearContextOnPlanAccept`	计划确认时显示"清除上下文"选项	false

认证与安全

设置项	说明
`apiKeyHelper`	自定义脚本生成 API Key
`forceLoginMethod`	限制登录方式：`claudeai` / `console`
`forceLoginOrgUUID`	限制登录到特定组织（UUID 或 UUID 数组）
`awsAuthRefresh`	AWS SSO 刷新脚本
`awsCredentialExport`	AWS 凭证导出脚本
`disableBypassPermissionsMode`	禁用 `--dangerously-skip-permissions`
`skipDangerousModePermissionPrompt`	跳过危险模式确认提示

子代理与模型

设置项	说明
`agent`	以指定子代理身份运行主线程
`modelOverrides`	将模型 ID 映射到提供商特定 ID（如 Bedrock ARN）
`autoMode`	自定义 Auto Mode 分类器的允许/拒绝规则
`useAutoModeDuringPlan`	计划模式中使用 Auto Mode 语义

Git 与项目

设置项	说明	默认值
`attribution`	自定义 commit 和 PR 署名	默认含 Claude Code 署名
`includeGitInstructions`	系统提示中包含 Git 操作指令	true
`plansDirectory`	计划文件存储路径	`~/.claude/plans`
`fileSuggestion`	自定义 `@` 文件补全脚本	内置文件遍历

Attribution 示例：

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  }
}

空字符串隐藏对应署名。

插件配置

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

设置项	说明
`enabledPlugins`	启用/禁用插件，格式 `插件名@市场名: true/false`
`extraKnownMarketplaces`	额外的插件市场源
`strictKnownMarketplaces`	（仅托管）限制可添加的市场白名单
`blockedMarketplaces`	（仅托管）阻止的市场黑名单

extraKnownMarketplaces 支持多种源类型：github、git、url、npm、file、directory、hostPattern、settings（内联声明）。

企业管控（仅托管设置）

设置项	说明
`channelsEnabled`	启用 Channels（Team/Enterprise 默认关闭）
`disableAutoMode`	禁用 Auto Mode
`disableAllHooks`	禁用所有 Hooks 和自定义状态栏
`allowManagedHooksOnly`	只加载托管 Hooks
`allowManagedMcpServersOnly`	只允许托管 MCP 白名单中的服务器
`allowManagedPermissionRulesOnly`	只允许托管权限规则
`allowedMcpServers`	MCP 服务器白名单
`deniedMcpServers`	MCP 服务器黑名单
`disableDeepLinkRegistration`	禁止注册 `claude-cli://` 协议
`disableSkillShellExecution`	禁用技能中的 shell 执行
`forceRemoteSettingsRefresh`	启动时强制刷新远程设置
`companyAnnouncements`	启动时显示的企业公告
`pluginTrustMessage`	插件信任警告的附加信息
`minimumVersion`	最低版本限制

沙箱高级设置

设置项	说明	默认值
`failIfUnavailable`	沙箱不可用时启动失败	false
`enableWeakerNestedSandbox`	Docker 环境中使用弱沙箱（降低安全性）	false
`enableWeakerNetworkIsolation`	允许访问 TLS 信任服务（Go 工具需要）	false
`network.allowUnixSockets`	允许的 Unix socket 路径（macOS）	[]
`network.allowAllUnixSockets`	允许所有 Unix socket（Linux/WSL2）	false
`network.allowMachLookup`	XPC/Mach 服务名（macOS，支持前缀通配符）	[]
`network.httpProxyPort`	自定义 HTTP 代理端口	自动
`network.socksProxyPort`	自定义 SOCKS5 代理端口	自动
`network.allowManagedDomainsOnly`	仅托管域名白名单生效	false
`filesystem.allowManagedReadPathsOnly`	仅托管读取路径白名单生效	false

Hook 安全配置

设置项	说明
`allowedHttpHookUrls`	HTTP Hook 允许的 URL 模式（支持 `*` 通配符）
`httpHookAllowedEnvVars`	HTTP Hook 允许插值的环境变量名

排查配置问题

运行 /status 查看当前生效的配置来源（managed / user / project），以及配置文件是否有错误。

实践建议

日常配置放用户级 ~/.claude/settings.json
权限和 Hooks 放项目级 .claude/settings.json 让团队共享
敏感文件通过 permissions.deny 排除（替代已废弃的 ignorePatterns）
大型 monorepo 用 worktree.symlinkDirectories 和 sparsePaths 优化