settings-management

设置管理

管理编码 Agent 的配置。

重要提示：修改设置后，务必告知用户需要重启 Agent才能使更改生效。大多数设置仅在启动时加载。

设置文件位置

范围	位置	是否与团队共享？
用户	~/.claude/settings.json	否
项目	.claude/settings.json	是（已提交）
本地	.claude/settings.local.json	否（已加入 gitignore）
托管	系统级 managed-settings.json	由 IT 部署

优先级（从高到低）：托管 → 命令行 → 本地 → 项目 → 用户

快捷操作

查看当前设置

cat ~/.claude/settings.json 2>/dev/null || echo "No user settings"
cat .claude/settings.json 2>/dev/null || echo "No project settings"
cat .claude/settings.local.json 2>/dev/null || echo "No local settings"

创建/编辑设置

使用 Edit 或 Write 工具修改设置文件。请务必先读取现有内容，再合并更改。

常见配置任务

设置默认模型

{
  "model": "claude-opus-4-7",
  "effort": "high"
}

工作量级别：low、medium、high、xhigh（仅限 Opus 4.7）、max。截至 2026 年，对于使用 API 密钥、Bedrock/Vertex/Foundry、Team 和 Enterprise 的用户，默认工作量级别为 high。

配置权限

{
  "permissions": {
    "allow": ["Bash(npm run:*)", "Bash(git:*)"],
    "deny": ["Read(.env)", "Read(.env.*)", "WebFetch"],
    "defaultMode": "acceptEdits"
  }
}

defaultMode 可接受：default、acceptEdits、plan、auto、dontAsk、bypassPermissions。新的 auto 模式（2026 年 3 月）使用基于 LLM 的分类器，遭拒时会触发 PermissionDenied 钩子。

添加环境变量

{
  "env": {
    "MY_VAR": "value",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

启用扩展思考

{
  "alwaysThinkingEnabled": true
}

配置归属信息

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <[email protected]>",
    "pr": ""
  }
}

配置沙盒

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"]
  }
}

配置钩子

{
  "hooks": {
    "PreToolUse": {
      "Bash": "echo 'Running command...'"
    }
  }
}

范围选择指南

• 用户设置（~/.claude/settings.json）：适用于所有项目的个人偏好
• 项目设置（.claude/settings.json）：团队共享的设置，提交到 git
• 本地设置（.claude/settings.local.json）：个人项目覆盖项，不提交

工作流

1. 确定范围：如果未指定，询问用户选择哪个范围（用户/项目/本地）
2. 读取现有设置：修改前务必读取当前文件
3. 合并更改：保留现有设置，仅修改所请求的键
4. 验证 JSON：写入前确保 JSON 有效
5. 确认更改：向用户展示最终设置
6. 提醒重启：告知用户重启 Claude Code 以使更改生效

Codex CLI 设置

Codex 在 ~/.codex/config.toml（用户级）和 .codex/config.toml（项目级，仅限受信任的项目）中使用 TOML 格式。

model = "gpt-5.5"                  # As of April 2026; gpt-5.4 is a valid fallback
approval_policy = "on-request"     # untrusted | on-request | never (or { granular = { ... } })
                                    # NOTE: "on-failure" is DEPRECATED — migrate to on-request or never
sandbox_mode = "workspace-write"   # read-only | workspace-write | danger-full-access

[features]
codex_hooks = true                 # Lifecycle hooks (stable in v0.124, April 2026)
multi_agent = true                 # Subagent orchestration (GA March 2026)

与 Claude Code 的主要区别：

• 使用 TOML 格式而非 JSON；项目配置需要明确的信任设置
• 在 .codex/rules/ 中使用 Starlark 规则配置命令策略
• 使用命名配置文件（[profiles.NAME]）适配不同工作流
• 功能标志系统（codex features list、codex --enable feature）
• 生命周期钩子以内联 [[hooks.PreToolUse]]（等）区块的形式存放在 config.toml 中
• 使用 [agents] 区块进行子 Agent 编排（max_threads、max_depth）
• 使用 [[skills.config]] 覆盖各项技能的启用/禁用设置
• 通过 [model_providers.NAME] 配置自定义模型提供方，包括 v0.123 起支持的 amazon-bedrock

完整的 Codex 配置参考（涵盖审批/沙盒/配置文件/功能/Agent/技能/钩子/规则/提供方/管理员强制策略），请参阅 references/codex-settings.md。

OpenCode 设置

OpenCode（anomalyco/opencode v1.14.x）在 ~/.config/opencode/opencode.json（用户级）和 opencode.json（项目根目录，或 .opencode/ 下）中使用 JSON/JSONC。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "permission": {
    "edit": "ask",
    "bash": { "*": "ask", "git status *": "allow" }
  },
  "instructions": ["AGENTS.md", "docs/style.md"]
}

与 Claude Code 的主要区别：

• 使用经过架构验证的 JSON/JSONC，而非纯 JSON
• 配置采用深度合并（后面的配置优先；instructions 等数组会拼接，而非替换）
• 权限是针对每个工具、使用 glob 模式的 allow/ask/deny 对象，而非单独的 allow/deny/ask 数组
• 主题/键绑定存放在单独的 tui.json 文件中
• 通过 model: "<provider>/<model-id>" 和顶层 provider 区块支持多个提供商
• 变量替换：{env:VAR} 和 {file:path}

完整的 OpenCode 配置参考请参阅 references/opencode-settings.md。

Devin CLI / 桌面设置

Devin 使用 JSON，配置文件位于 ~/.config/devin/config.json（用户级；Windows 上为 %APPDATA%\devin\config.json）、.devin/config.json（项目级）和 .devin/config.local.json（项目本地，已加入 gitignore）。MCP 服务存放在相同层级下专用的 mcp_config.json 文件中。

{
  "agent": { "model": "swe-2-high" },
  "permissions": {
    "allow": ["Read(**)", "Exec(git)"],
    "ask": ["Write(**/.env*)"]
  },
  "read_config_from": { "claude": true, "cursor": true, "windsurf": true }
}

主要区别：

• 项目配置仅接受 permissions、read_config_from 和 hooks
• read_config_from 默认从 .claude/、.cursor/、.windsurf/ 导入规则/钩子/子 Agent
• 技能：.devin/skills/（项目级）、~/.config/devin/skills/（用户级）
• 插件：.devin-plugin/plugin.json 清单；devin plugins CLI

完整的 Devin 配置参考请参阅 references/devin-settings.md。

参考

• Claude Code 设置：references/claude-settings.md
• Codex CLI 设置：references/codex-settings.md
• OpenCode 设置：references/opencode-settings.md
• Devin CLI/桌面设置：references/devin-settings.md