Claude Code 的配置系统通过 settings.json 文件实现，支持四级作用域继承，覆盖从个人偏好到企业级安全策略的所有场景。
四级配置作用域
| 作用域 | 位置 | 影响范围 | 团队共享 |
|---|---|---|---|
| Managed | 服务器下发 / plist / 注册表 / managed-settings.json | 机器上所有用户 | 是（IT 部署） |
| User | ~/.claude/ 目录 | 你的所有项目 | 否 |
| Project | 仓库 .claude/ 目录 | 所有协作者 | 是（提交到 git） |
| Local | .claude/*.local.* 文件 | 仅你在此仓库 | 否（gitignore） |
优先级规则
Managed（最高，不可覆盖）
> 命令行参数（临时覆盖）
> Local（覆盖 Project 和 User）
> Project（覆盖 User）
> User（最低）
不同功能的配置文件位置
| 功能 | User | Project | Local |
|---|---|---|---|
| Settings | ~/.claude/settings.json | .claude/settings.json | .claude/settings.local.json |
| Subagents | ~/.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 |
settings.json 结构示例
json
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
"deny": ["Bash(curl *)", "Read(./.env)"]
},
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1"
},
"companyAnnouncements": ["欢迎使用公司 Claude Code！请遵守代码规范。"]
}添加
$schema后，VS Code / Cursor 等编辑器会提供自动补全和内联验证。
完整配置项速查表（40+ 项）
基础配置
| 配置项 | 说明 | 示例值 |
|---|---|---|
model | 覆盖默认模型 | "claude-sonnet-4-6" |
availableModels | 限制用户可选的模型范围 | ["sonnet", "haiku"] |
language | Claude 回复语言 | "japanese" |
cleanupPeriodDays | 非活跃会话保留天数（0 = 立即删除，默认 30） | 20 |
autoUpdatesChannel | 更新频道（latest/stable） | "stable" |
认证
| 配置项 | 说明 | 示例值 |
|---|---|---|
apiKeyHelper | 动态生成 API Key 的脚本 | "/bin/get-key.sh" |
forceLoginMethod | 强制登录方式（claudeai/console） | "claudeai" |
forceLoginOrgUUID | 自动选择组织（需配合 forceLoginMethod） | "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" |
界面与体验
| 配置项 | 说明 | 示例值 |
|---|---|---|
companyAnnouncements | 启动时展示的公司公告（随机轮换） | ["欢迎！"] |
showTurnDuration | 显示响应耗时（如 "Cooked for 1m 6s"） | false |
spinnerVerbs | 自定义加载动词 | {"mode": "append", "verbs": ["思考中"]} |
spinnerTipsEnabled | 显示加载提示 | false |
spinnerTipsOverride | 自定义加载提示内容 | {"excludeDefault": true, "tips": ["Use tool X"]} |
terminalProgressBarEnabled | 终端进度条（iTerm2/Windows Terminal） | false |
prefersReducedMotion | 减少动画（无障碍） | true |
outputStyle | 输出风格（如 "Explanatory"） | "Explanatory" |
statusLine | 自定义状态栏 | {"type": "command", "command": "~/.claude/statusline.sh"} |
fileSuggestion | @ 文件自动补全脚本 | {"type": "command", "command": "~/.claude/file-suggestion.sh"} |
respectGitignore | @ 文件选择器是否遵守 .gitignore（默认 true） | false |
工作流
| 配置项 | 说明 | 示例值 |
|---|---|---|
plansDirectory | 计划文件存储路径（相对项目根目录） | "./plans" |
includeGitInstructions | 系统提示中包含内置 Git 工作流指令 | false |
attribution | Git commit/PR 的归因标注 | {"commit": "🤖 Generated with Claude Code"} |
alwaysThinkingEnabled | 默认启用扩展思考模式 | true |
fastModePerSessionOptIn | 快速模式需每次会话手动开启（不跨会话持久） | true |
teammateMode | Agent 团队显示方式（auto/in-process/tmux） | "in-process" |
权限配置
json
{
"permissions": {
"allow": ["Bash(git diff *)", "Read(~/.zshrc)"],
"ask": ["Bash(git push *)"],
"deny": ["WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"]
}
}权限规则格式：Tool 或 Tool(specifier)，先匹配 deny → ask → allow，第一个匹配规则生效。
安全与企业（仅 Managed 作用域有效）
| 配置项 | 说明 |
|---|---|
disableBypassPermissionsMode | 禁止 --dangerously-skip-permissions 标志 |
allowManagedPermissionRulesOnly | 仅允许 Managed 设置中的权限规则 |
allowManagedHooksOnly | 仅允许 Managed 和 SDK Hooks |
allowedHttpHookUrls | HTTP Hooks 目标 URL 白名单（支持 * 通配符） |
httpHookAllowedEnvVars | HTTP Hooks 可使用的环境变量白名单 |
allowManagedMcpServersOnly | 仅允许 Managed 白名单中的 MCP 服务器 |
strictKnownMarketplaces | 限制用户可添加的插件市场来源 |
blockedMarketplaces | 屏蔽指定插件市场（下载前即拦截） |
pluginTrustMessage | 安装插件信任警告中的自定义组织提示 |
MCP 服务器配置
json
{
"enableAllProjectMcpServers": true,
"enabledMcpjsonServers": ["memory", "github"],
"disabledMcpjsonServers": ["filesystem"]
}插件配置
json
{
"enabledPlugins": [
{"pluginName": "pyright-lsp", "marketplaceName": "claude-plugins-official", "scope": "project"}
],
"extraKnownMarketplaces": [
{"name": "company-plugins", "source": "github", "repo": "acme/claude-plugins"}
],
"strictKnownMarketplaces": [
{"source": "official"}
]
}使用 /config 命令
在 Claude Code 交互界面中运行：
/config
打开带标签页的设置界面，可查看状态信息并修改配置，无需手动编辑 JSON 文件。
验证当前生效配置
bash
claude config list # 列出所有配置
claude config get permissions # 查看特定配置项原文：Claude Code settings - Claude Code Docs | 来源：Anthropic 官方文档