Claude Code 设置完全指南

Claude Code 提供多种设置来配置其行为以满足您的需求。您可以在使用交互式 REPL 时运行 /config 命令来配置 Claude Code，这会打开一个选项卡式设置界面，您可以在其中查看状态信息并修改配置选项。

配置作用域

Claude Code 使用作用域系统来确定配置应用的位置以及与谁共享。了解作用域可以帮助您决定如何为个人使用、团队协作或企业部署配置 Claude Code。

可用作用域

作用域	位置	影响范围	与团队共享？
Managed	系统级 `managed-settings.json`	机器上的所有用户	是（由 IT 部署）
User	`~/.claude/` 目录	您，跨所有项目	否
Project	存储库中的 `.claude/`	此存储库上的所有协作者	是（提交到 git）
Local	`.claude/.local.` 文件	您，仅在此存储库中	否（gitignored）

何时使用每个作用域

Managed 作用域用于：

必须在整个组织范围内强制执行的安全策略
无法被覆盖的合规要求
由 IT/DevOps 部署的标准化配置

User 作用域最适合：

您想在任何地方使用的个人偏好（主题、编辑器设置）
您在所有项目中使用的工具和插件
API 密钥和身份验证（安全存储）

Project 作用域最适合：

团队共享的设置（权限、hooks、MCP servers）
整个团队应该拥有的插件
跨协作者标准化工具

Local 作用域最适合：

特定项目的个人覆盖
在与团队共享之前测试配置
对其他人不适用的特定于机器的设置

作用域如何相互作用

当在多个作用域中配置相同的设置时，更具体的作用域优先：

Managed（最高）- 无法被任何内容覆盖
命令行参数 - 临时会话覆盖
Local - 覆盖项目和用户设置
Project - 覆盖用户设置
User（最低）- 当没有其他内容指定设置时应用

例如，如果在用户设置中允许某个权限，但在项目设置中拒绝，则项目设置优先，权限被阻止。

哪些功能使用作用域

作用域适用于许多 Claude Code 功能：

功能	用户位置	项目位置	本地位置
Settings	`~/.claude/settings.json`	`.claude/settings.json`	`.claude/settings.local.json`
Subagents	`~/.claude/agents/`	`.claude/agents/`	—
MCP servers	`~/.claude.json`	`.mcp.json`	`~/.claude.json`（每个项目）
Plugins	`~/.claude/settings.json`	`.claude/settings.json`	`.claude/settings.local.json`
CLAUDE.md	`~/.claude/CLAUDE.md`	`CLAUDE.md` 或 `.claude/CLAUDE.md`	`CLAUDE.local.md`

设置文件

settings.json 文件是我们用于通过分层设置配置 Claude Code 的官方机制：

用户设置在 ~/.claude/settings.json 中定义，适用于所有项目。
项目设置保存在您的项目目录中：
- .claude/settings.json 用于检入源代码管理并与您的团队共享的设置
- .claude/settings.local.json 用于未检入的设置，适用于个人偏好和实验
Managed 设置：对于需要集中控制的组织，Claude Code 支持可以部署到系统目录的 managed-settings.json 和 managed-mcp.json 文件

Claude Code 自动创建配置文件的时间戳备份，并保留最近五个备份以防止数据丢失。

可用设置

settings.json 支持多个选项，包括：

permissions - 权限规则（allow/ask/deny）
env - 环境变量
hooks - 生命周期事件钩子
model - 覆盖默认模型
sandbox - 沙箱配置
attribution - 自定义 git 提交归属
statusLine - 自定义状态行
fileSuggestion - 自定义文件建议
outputStyle - 输出样式
language - 响应语言
autoUpdatesChannel - 更新渠道（stable/latest）

权限设置

键	描述
`allow`	允许工具使用的权限规则数组
`ask`	在工具使用时要求确认的权限规则数组
`deny`	拒绝工具使用的权限规则数组
`additionalDirectories`	Claude 有权访问的其他工作目录
`defaultMode`	打开 Claude Code 时的默认权限模式

Sandbox 设置

配置高级沙箱行为：

enabled - 启用 bash 沙箱
autoAllowBashIfSandboxed - 沙箱化时自动批准 bash 命令
excludedCommands - 应在沙箱外运行的命令
network.allowedDomains - 允许出站网络流量的域数组
network.allowUnixSockets - 沙箱中可访问的 Unix 套接字路径

环境变量

Claude Code 支持以下环境变量来控制其行为：

变量	目的
`ANTHROPIC_API_KEY`	API 密钥
`ANTHROPIC_MODEL`	要使用的模型设置的名称
`CLAUDE_CODE_SHELL`	覆盖自动 shell 检测
`CLAUDE_CODE_MAX_OUTPUT_TOKENS`	最大输出令牌数
`DISABLE_TELEMETRY`	禁用遥测
`HTTP_PROXY` / `HTTPS_PROXY`	代理设置
`CLAUDE_CODE_ENABLE_TELEMETRY`	启用 OpenTelemetry 数据收集
`CLAUDE_CONFIG_DIR`	自定义配置和数据文件位置

Subagent 配置

Claude Code 支持可在用户和项目级别配置的自定义 AI subagents：

用户 subagents：~/.claude/agents/ - 在所有项目中可用
项目 subagents：.claude/agents/ - 特定于您的项目，可与您的团队共享

插件配置

Claude Code 支持插件系统，可通过 settings.json 配置：

enabledPlugins - 控制启用哪些插件
extraKnownMarketplaces - 定义其他插件市场
strictKnownMarketplaces - 控制用户可以添加哪些市场（仅 Managed 设置）

使用 /plugin 命令以交互方式管理插件。