Claude Code 设置

Claude Code 提供多种设置以配置其行为。在交互式 REPL 中运行 /config 可打开设置界面。

配置作用域

作用域	位置	影响对象	与团队共享？
托管	服务端设置、plist/注册表或 `managed-settings.json`	机器上所有用户	是（IT 部署）
用户	`~/.claude/` 目录	您，跨所有项目	否
项目	仓库中的 `.claude/`	所有协作者	是（提交到 git）
本地	`.claude/settings.local.json`	仅您，仅本仓库	否（gitignore）

优先级（高者优先）：托管 → 命令行参数 → 本地 → 项目 → 用户。

权限规则跨层合并；deny 始终优先于 allow。

何时使用各作用域

托管 — 安全策略、合规、IT 标准化配置
用户 — 个人偏好、API 密钥、跨项目工具
项目 — 团队权限、hooks、MCP 服务器、共享插件
本地 — 个人覆盖、与团队分享前的试验

设置文件

用户： ~/.claude/settings.json
项目： .claude/settings.json（共享）、.claude/settings.local.json（个人，gitignore）
托管： macOS /Library/Application Support/ClaudeCode/、Linux /etc/claude-code/、Windows C:\Program Files\ClaudeCode\

其他配置在 ~/.claude.json（OAuth、用户/本地 MCP、每项目状态）。项目 MCP 使用 .mcp.json。

示例：

{
  "$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"
  },
  "companyAnnouncements": [
    "欢迎！请参阅 docs.example.com 上的代码规范"
  ]
}

添加 "$schema" 可在 VS Code、Cursor 等编辑器中获得自动完成。

编辑何时生效

Claude Code 监视设置文件，多数键变更时热重载（permissions、hooks、apiKeyHelper 等）。

在会话开始时读取一次（改文件需重启或 /clear）：

model — 会话中可用 /model
outputStyle — 属于系统提示，在 /clear 或重启时重建

CLAUDE.md 在会话中编辑要到 /clear、/compact 或重启才生效。

使用作用域的功能

功能	用户	项目	本地
设置	`~/.claude/settings.json`	`.claude/settings.json`	`.claude/settings.local.json`
子代理	`~/.claude/agents/`	`.claude/agents/`	—
MCP 服务器	`~/.claude.json`	`.mcp.json`	`~/.claude.json`（按项目）
插件	`~/.claude/settings.json`	`.claude/settings.json`	`.claude/settings.local.json`
CLAUDE.md	`~/.claude/CLAUDE.md`	`CLAUDE.md` 或 `.claude/CLAUDE.md`	`CLAUDE.local.md`

Windows 上 ~/.claude 解析为 %USERPROFILE%\.claude。

常用设置

键	说明
`permissions`	`defaultMode`、`allow`、`ask`、`deny` — 见权限配置
`model`	默认模型；由 `--model` 或 `ANTHROPIC_MODEL` 覆盖
`env`	每个会话及子进程的环境变量
`hooks`	生命周期事件上的命令
`autoMemoryEnabled`	自动记忆开关；也可 `/memory`
`claudeMdExcludes`	monorepo 中跳过 CLAUDE.md 的 glob
`additionalDirectories`	Claude 可访问的额外目录
`disableAutoMode`	`"disable"` 从 Shift+Tab 循环中移除 auto
`disableBypassPermissionsMode`	`"disable"` 阻止 bypass 模式
`forceLoginMethod`	`claudeai` 或 `console`（托管）
`minimumVersion`	自动更新与 `claude update` 的最低版本

官方设置页有完整键参考表。

托管设置

组织可部署 managed-settings.json、MDM 策略或服务端托管设置，用户与项目设置无法覆盖。

托管专用示例：allowManagedPermissionRulesOnly、allowManagedHooksOnly、strictKnownMarketplaces、组织级 claudeMd。

技术强制用托管设置（permissions.deny、sandbox.enabled、env）。行为指导用托管 CLAUDE.md；与 deny 规则不同，后者由客户端硬执行。