附录B：配置参考 - Claude Code 智能体开发权威指南

Settings.json 键名按作用域分类

Settings 的 JSON Schema

在任何 settings.json 中添加 $schema 行，即可在支持 JSON schema 的编辑器中获得自动补全和行内验证：

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

权限规则

键名	类型	描述
permissions.allow	string[]	自动批准而无需提示的工具
permissions.ask	string[]	需要用户确认的工具
permissions.deny	string[]	始终阻止的工具

规则语法：Tool 或 Tool(specifier)，支持 glob 模式。评估顺序：Deny > Ask > Allow，在所有作用域中首次匹配即生效。

示例：

Bash(npm test) — 特定的 bash 命令
Write(*.env) — 文件模式
mcp__server__tool — MCP 工具
Bash(git *) — 通配符命令

环境变量（Settings）

键名	类型	描述
env	object	注入到 Claude 环境中的键值对

Hook 配置

键名	类型	描述
hooks	object	事件到处理程序的映射（参见下方 Hook Schema）

模型设置

键名	类型	描述
model	string	默认模型标识符
availableModels	string[]	可供选择的模型列表

认证与凭据

键名	类型	描述
apiKeyHelper	string	自定义脚本（通过 `/bin/sh` 执行）用于生成认证值。该值作为 `X-Api-Key` 和 `Authorization: Bearer` 请求头发送用于模型请求
awsAuthRefresh	string	自定义脚本，用于修改 .aws 目录以刷新凭据
awsCredentialExport	string	自定义脚本，输出包含 AWS 凭据的 JSON
forceLoginMethod	string	限制登录方式为 claudeai（Claude.ai 账户）或 console（API 计费账户）
forceLoginOrgUUID	string	登录时自动选择的组织 UUID（需要 forceLoginMethod）

会话与行为

键名	类型	描述
cleanupPeriodDays	number	不活跃时间超过此值的天数的会话将在启动时被删除。默认值：30。设为 0 则立即清理
language	string	首选响应语言（例如 "japanese"、"spanish"、"french"）
outputStyle	string	配置输出样式以调整系统提示
plansDirectory	string	自定义计划文件的存储位置。相对于项目根目录的路径。默认值：`~/.claude/plans`
showTurnDuration	boolean	显示回合持续时间消息（例如 "Cooked for 1m 6s"）。默认值：true
teammateMode	string	代理团队队友的显示方式：auto（在 tmux/iTerm2 中选择分屏）、in-process 或 tmux

UI 与显示

键名	类型	描述
autoUpdatesChannel	string	发布通道："stable"（约一周前的版本，跳过回归问题）或 "latest"（最新版本）。默认值："latest"
spinnerTipsEnabled	boolean	工作时在加载动画中显示提示。默认值：true
spinnerVerbs	object	自定义加载动画动词。mode: "replace"（仅使用你的动词）或 "append"（与默认值混合）。verbs: string[]
terminalProgressBarEnabled	boolean	在 Windows Terminal 和 iTerm2 中启用终端进度条。默认值：true
prefersReducedMotion	boolean	减少或禁用 UI 动画（加载动画、微光效果、闪烁效果）以提升无障碍体验

文件建议

键名	类型	描述
fileSuggestion	object	用于大型 monorepo 中 @ 文件路径自动补全的自定义脚本
respectGitignore	boolean	@ 文件选择器是否遵循 .gitignore 模式。默认值：true

fileSuggestion 脚本通过 stdin 接收包含 query 字段的 JSON，并通过 stdout 输出以换行分隔的文件路径。

沙盒设置

键名	类型	描述
sandbox.enabled	boolean	启用 bash 沙盒（macOS、Linux、WSL2）。默认值：false
sandbox.autoAllowBashIfSandboxed	boolean	在沙盒环境中自动批准 bash 命令。默认值：true
sandbox.excludedCommands	string[]	在沙盒外运行的命令（例如 ["git", "docker"]）
sandbox.allowUnsandboxedCommands	boolean	允许命令通过 dangerouslyDisableSandbox 绕过沙盒。设为 false 以强制严格沙盒。默认值：true
sandbox.network.allowUnixSockets	string[]	沙盒中可访问的 Unix socket 路径（例如 SSH agent socket）
sandbox.network.allowAllUnixSockets	boolean	允许所有 Unix socket 连接。默认值：false
sandbox.network.allowLocalBinding	boolean	允许绑定到 localhost 端口（仅 macOS）。默认值：false
sandbox.network.allowedDomains	string[]	沙盒中可访问的域名。默认值：常见包注册表
sandbox.network.httpProxyPort	number	用于沙盒网络过滤的自定义 HTTP 代理端口
sandbox.network.socksProxyPort	number	用于沙盒网络过滤的自定义 SOCKS 代理端口
sandbox.enableWeakerNestedSandbox	boolean	在无特权 Docker 环境中启用较弱的沙盒（仅 Linux/WSL2）。会降低安全性。默认值：false

完整沙盒示例：

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowedDomains": ["registry.npmjs.org", "api.github.com"],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)",
      "Write(.env)",
      "Write(.env.*)",
      "Write(secrets/**)"
    ]
  }
}

归属设置

键名	类型	描述
attribution.commit	string	自定义 git 提交归属文本。支持 `\n` 用于多行尾部信息
attribution.pr	string	自定义 PR 描述归属文本。设为 "" 可禁用 PR 归属

默认提交归属：

Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>

自定义示例：

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

插件设置

键名	类型	描述
enabledPlugins	string[]	活跃的插件标识符，格式为 plugin-name@marketplace-name
extraKnownMarketplaces	object[]	额外的插件市场源，具有明确的信任边界

插件 hook 定义在插件根目录的 hooks/hooks.json 中。Hook 包含一个可选的顶层 description 字段。插件脚本通过 ${CLAUDE_PLUGIN_ROOT} 变量引用自己的目录。

MCP 服务器审批

键名	类型	描述
enableAllProjectMcpServers	boolean	自动批准项目 .mcp.json 文件中定义的所有 MCP 服务器
enabledMcpjsonServers	string[]	批准来自 .mcp.json 的特定 MCP 服务器（例如 ["memory", "github"]）
disabledMcpjsonServers	string[]	拒绝来自 .mcp.json 的特定 MCP 服务器

仅限托管管理的设置

键名	类型	描述
strictKnownMarketplaces	boolean	限制插件仅来自已批准的市场
allowManagedHooksOnly	boolean	阻止用户、项目和插件 hook；仅运行托管和 SDK hook
allowManagedPermissionRulesOnly	boolean	阻止用户/项目设置定义 allow、ask 或 deny 权限规则
disableAllHooks	boolean	禁用所有 hook 和任何自定义状态行
allowedMcpServers	object[]	用户可配置的 MCP 服务器允许列表。未定义 = 无限制。空数组 = 完全锁定。拒绝列表优先
deniedMcpServers	object[]	在所有作用域中被明确阻止的 MCP 服务器拒绝列表

Settings 作用域层级

优先级	作用域	位置	是否共享	是否可覆盖
1（最高）	Managed	系统目录或服务器托管（IT 部署）	组织范围	否
2	CLI	命令行标志	否	仅会话内
3	Local	`.claude/settings.local.json`	否（gitignored）	可被 managed/CLI 覆盖
4	Project	`.claude/settings.json`	是（VCS）	可被 managed/CLI/local 覆盖
5（最低）	User	`~/.claude/settings.json`	否	可被以上所有覆盖

何时使用各作用域

作用域	用途
Managed	组织范围的安全策略、API key 辅助脚本、强制登录方式、MCP 允许/拒绝列表、沙盒要求
User	个人偏好（模型、语言、加载动画动词、减少动画）、个人 API key、用户级权限
Project	共享的团队标准（权限、hook、MCP 服务器）、编码约定、归属设置
Local	特定项目的个人覆盖、实验性设置、不想提交的凭据

作用域如何交互

设置在各作用域之间合并。对于大多数键，高优先级作用域覆盖低优先级。权限规则遵循特定的评估顺序：先 deny 规则，然后 ask，最后 allow — 首个匹配的规则生效，在所有作用域中评估。

服务器托管设置

没有设备管理基础设施的组织可以使用服务器托管设置，该设置通过 Anthropic 的服务器为 Claude for Enterprise 客户交付配置。其功能与基于文件的托管设置完全相同，且不能被用户或项目设置覆盖。

环境变量

Claude Code 支持超过 70 个环境变量。以下按功能分组列出最常用的变量。

API 与认证

变量	描述
`ANTHROPIC_API_KEY`	用于直接 Anthropic 访问的 API key
`CLAUDE_CODE_USE_BEDROCK`	启用云提供商 Bedrock 集成 (1)
`CLAUDE_CODE_USE_VERTEX`	启用云提供商 Vertex AI 集成 (1)
`ANTHROPIC_BASE_URL`	自定义 API 基础 URL
`CLAUDE_CODE_AUTH_TOKEN`	覆盖认证令牌

模型配置

变量	描述
`ANTHROPIC_MODEL`	覆盖默认模型
`ANTHROPIC_SMALL_FAST_MODEL`	用于轻量操作的模型（Haiku 任务）
`CLAUDE_CODE_MAX_TOKENS`	每次响应的最大 token 数
`CLAUDE_CODE_MAX_THINKING_TOKENS`	用于思考/推理的最大 token 数

代理与网络

变量	描述
`HTTP_PROXY / HTTPS_PROXY`	HTTP(S) 代理 URL
`NO_PROXY`	逗号分隔的绕过域名
`ANTHROPIC_PROXY_URL`	Anthropic 专用代理 URL

上下文与压缩

变量	描述
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	自动压缩阈值百分比（默认值：95）
`CLAUDE_CODE_CONTEXT_LIMIT`	最大上下文窗口大小

功能标志

变量	描述
`ENABLE_TOOL_SEARCH`	启用/禁用 MCP 工具搜索和延迟加载
`CLAUDE_CODE_ENABLE_AGENT_TEAMS`	启用实验性代理团队
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	禁用遥测和非必要的网络调用

无头/CI

变量	描述
`CLAUDE_CODE_ENTRYPOINT`	在无头环境中设为 cli
`CLAUDE_CODE_BUDGET_TOKENS`	无头会话的 token 预算
`CLAUDE_CODE_MAX_TURNS`	无头模式下的最大对话轮次

输出与格式

变量	描述
`CLAUDE_CODE_OUTPUT_FORMAT`	无头模式的输出格式（text、json、stream-json）
`CLAUDE_CODE_HIDE_TOOL_OUTPUT`	在终端中抑制工具输出显示

调试与诊断

变量	描述
`CLAUDE_CODE_DEBUG`	启用调试日志 (1)
`CLAUDE_CODE_LOG_LEVEL`	设置日志详细级别
`CLAUDE_CODE_VERBOSE`	启用详细输出

会话与行为

变量	描述
`CLAUDE_CODE_SKIP_CLAUDE_MD`	跳过加载 CLAUDE.md 文件 (1)
`CLAUDE_CODE_THINKING_MODE`	思考模式（enabled、disabled、budget）
`CLAUDE_CODE_THINKING_BUDGET`	扩展思考的 token 预算

遥测

变量	描述
`CLAUDE_CODE_DISABLE_TELEMETRY`	禁用使用遥测 (1)
`CLAUDE_CODE_TELEMETRY_ENDPOINT`	自定义遥测收集端点

工具清单

工具	描述
`Bash`	执行 shell 命令。工作目录持久保持；环境变量不会。
`Read`	读取文件内容。支持图片、PDF、notebook 文件。
`Write`	创建或覆盖文件。
`Edit`	文件中的精确字符串替换。需要唯一匹配。
`Glob`	文件模式匹配。返回按修改时间排序的路径。
`Grep`	内容搜索，支持正则表达式。支持文件类型过滤、上下文行。
`WebFetch`	获取并处理 URL 内容。自动将 HTTP 升级为 HTTPS。
`WebSearch`	网页搜索，支持域名过滤。返回格式化结果。
`Task`	生成具有隔离上下文的子代理。支持前台/后台。
`Skill`	在对话中调用基于技能的工作流。
`NotebookEdit`	编辑 notebook 单元格（.ipynb）。替换、插入或删除。
`LSP`	语言服务器协议操作。诊断、跳转定义、引用。
`TeamCreate`	创建代理团队（实验性）。
`TaskCreate`	在代理团队任务列表中创建任务。
`TaskUpdate`	在代理团队中更新任务状态。
`TaskList`	列出代理团队的任务。
`SendMessage`	在代理团队成员之间发送消息。
`TeamDelete`	删除代理团队。
`TodoRead`	读取当前任务/待办列表。
`TodoWrite`	写入/更新任务/待办项。

Hook 配置 Schema

通用输入字段

每个 hook 事件通过 stdin 以 JSON 格式接收以下字段：

字段	描述
session_id	当前会话标识符
transcript_path	对话 JSON 文件的路径
cwd	调用 hook 时的工作目录
permission_mode	活跃的权限模式："default"、"plan"、"acceptEdits"、"dontAsk" 或 "bypassPermissions"
hook_event_name	触发的事件名称

每个事件会添加自己的字段（例如 PreToolUse 的 tool_name、tool_input）。

事件类型

事件	触发时机	能否阻止？	事件特有字段
PreToolUse	任何工具执行之前	是	tool_name, tool_input
PostToolUse	任何工具执行之后	是（通过 decision）	tool_name, tool_input, tool_output
PostToolUseFailure	工具执行失败时	是（通过 decision）	tool_name, error, is_interrupt
UserPromptSubmit	处理用户提示之前	是	prompt
Notification	状态通知时（permission_prompt、idle_prompt、auth_success、elicitation_dialog）	否	message, type
Stop	Claude 停止生成时	是（通过 decision）	stop_hook_active
SessionStart	会话初始化时	否	source（startup、resume、clear、compact）、model，可选 agent_type
SessionEnd	会话终止时	否	reason（clear、logout、prompt_input_exit、bypass_permissions_disabled、other）
PermissionRequest	显示权限对话框之前	是	tool_name、权限详情；支持 updatedInput、updatedPermissions
PreCompact	上下文压缩之前	否	trigger（manual 或 auto）、custom_instructions
PostCompact	上下文压缩之后	否	压缩后的上下文
SubagentStart	子代理生成时	否	agent_id, agent_type
SubagentStop	子代理完成时	是（通过 decision）	agent_id, agent_type, agent_transcript_path, stop_hook_active
TeammateIdle	代理团队队友即将进入空闲时	是（退出码 2）	teammate_name
TaskCompleted	任务被标记为完成时	是（退出码 2）	task_id, task_subject

处理程序类型（3 种）

Command 处理程序

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "handler": {
          "type": "command",
          "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate.sh"
        }
      }
    ]
  }
}

执行 shell 命令。通过 stdin 接收事件 JSON。通过退出码和 stdout JSON 传递结果。

Prompt 处理程序

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write(*.sql)",
        "handler": {
          "type": "prompt",
          "prompt": "Review this SQL file write for safety. Allow or deny."
        }
      }
    ]
  }
}

将上下文和提示发送给 Claude 模型（默认为 Haiku）进行单轮评估。返回结构化的 {"ok": true/false, "reason": "..."} 决策。使用 $ARGUMENTS 占位符表示事件数据。

Agent 处理程序

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "handler": {
          "type": "agent",
          "agent": "security-reviewer",
          "tools": ["Read", "Grep"]
        }
      }
    ]
  }
}

生成具有多轮工具访问权限的子代理，用于复杂验证。最多 50 轮。

处理程序通用字段

字段	必填	描述
timeout	否	超时时间（秒）。默认值：10（command）、30（prompt）、60（agent）
statusMessage	否	hook 运行时显示的自定义加载动画消息
once	否	如果为 true，每个会话仅运行一次然后被移除。仅适用于 Skills
async	否	如果为 true，在后台运行而不阻塞。输出通过 systemMessage 或 additionalContext 在下一轮传递。不能阻止操作

退出码行为

退出码	含义	效果
0	成功	操作继续执行。Stdout 被解析以获取 JSON 输出字段。Stdout 在详细模式（Ctrl+O）中显示，UserPromptSubmit 和 SessionStart 除外，其输出会变为上下文
2	阻止性错误	操作被阻止。Stdout/JSON 被忽略。Stderr 文本作为错误消息反馈给 Claude
其他	非阻止性错误	Stderr 在详细模式中显示。执行继续

JSON 输出字段（退出码为 0 时）

字段	类型	效果
continue	boolean	如果为 false，停止此事件的后续 hook 处理
stopReason	string	停止时显示的消息
suppressOutput	boolean	如果为 true，抑制默认 hook 输出
systemMessage	string	作为系统上下文注入到对话中的消息
additionalContext	string	添加到事件的额外上下文
updatedInput	object	执行前修改的工具输入（PreToolUse、PermissionRequest）
updatedPermissions	object	修改的权限设置（PermissionRequest；等同于"始终允许"）
permissionDecision	string	PreToolUse hook 的 "allow"、"deny" 或 "ask"（在 hookSpecificOutput 内）
decision	string	"block" 以停止操作（UserPromptSubmit、PostToolUse、PostToolUseFailure、Stop、SubagentStop）

Hook 中的环境变量

变量	描述
`$CLAUDE_PROJECT_DIR`	项目根目录。对于含空格的路径请用引号包裹
`${CLAUDE_PLUGIN_ROOT}`	插件根目录，用于插件打包的脚本
`$CLAUDE_ENV_FILE`	（仅 SessionStart）用于持久化环境变量的文件路径。将 export 语句写入此文件可使变量在所有后续 Bash 命令中可用

CLAUDE_ENV_FILE 示例：

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export DEBUG_LOG=true' >> "$CLAUDE_ENV_FILE"
fi
exit 0

匹配器语法

精确工具名：Bash、Write、Edit
带说明符的工具：Bash(npm *)、Write(*.env)
MCP 工具：mcp__servername__toolname
说明符中支持正则表达式模式
* 匹配任何工具

Hook 决策控制（PreToolUse）

PreToolUse 使用 hookSpecificOutput.permissionDecision：

决策	效果
"allow"	无需用户提示即可继续
"deny"	阻止执行；原因显示给 Claude
"ask"	显示权限提示（可与 updatedInput 结合以显示修改后的输入）
省略 / 无输出	转入正常权限评估

Hook 决策控制（PermissionRequest）

决策	效果
"approve"	无需用户提示自动批准
"deny"	无需用户提示自动拒绝
省略 / 无输出	显示正常权限提示

支持 updatedInput 和 updatedPermissions（等同于"始终允许"选项）。

Hook 决策控制（TeammateIdle / TaskCompleted）

这些事件仅使用退出码，而非 JSON 决策控制：

退出码	效果
0	允许操作（队友进入空闲，任务标记为完成）
2	阻止操作；stderr 作为反馈返回以继续工作

Hook 安全模型

Hook 在会话启动时进行快照。如果 hook 在会话期间被外部修改，Claude Code 会发出警告并要求在 /hooks 菜单中审核后才能应用更改。这可以防止恶意的会话中修改。

MCP 配置格式

.mcp.json（项目根目录）

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "API_KEY": "${ENV_VAR_NAME}"
      },
      "cwd": "./optional-working-directory"
    },
    "remote-server": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${TOKEN}"
      }
    }
  }
}

服务器配置字段

字段	类型	必填	描述
command	string	是（本地）	要启动的可执行文件
args	string[]	否	命令参数
env	object	否	环境变量（支持 `${VAR}` 插值）
cwd	string	否	服务器进程的工作目录
url	string	是（远程）	远程服务器的 SSE 端点
headers	object	否	远程连接的 HTTP 请求头

托管 MCP 设置

键名	类型	描述
mcpServers.allowlist	string[]	仅允许配置这些服务器
mcpServers.denylist	string[]	这些服务器被阻止

插件市场源

源类型	格式
Git 托管平台	githost:org/repo
Git URL	git:https://example.com/repo.git
npm	npm:package-name
URL	url:https://example.com/plugin.tar.gz
文件	file:/path/to/plugin
目录	directory:/path/to/plugin-dir
主机模式	host:*.internal.company.com

完整 Settings.json 示例

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git *)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Write(.env)",
      "Write(.env.*)",
      "Read(secrets/**)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "info"
  },
  "model": "claude-opus-4-6",
  "language": "english",
  "autoUpdatesChannel": "stable",
  "showTurnDuration": true,
  "spinnerVerbs": {
    "mode": "append",
    "verbs": ["Pondering", "Crafting"]
  },
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"],
    "network": {
      "allowedDomains": ["registry.npmjs.org", "api.github.com"]
    }
  },
  "attribution": {
    "commit": "Generated with Claude Code\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
    "pr": "Generated with Claude Code"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "handler": {
          "type": "command",
          "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate-bash.sh"
        }
      }
    ]
  }
}