指南

各 AI 编程 agent 的设置文件位置：Claude Code、Cursor、Codex、Gemini CLI、OpenCode、Qwen Code、Amp 和 Factory Droid（2026）

每个 AI 编程 agent 的设置文件在哪里？同一个键设置两次时哪个文件生效？

Claude Code 使用 ~/.claude/settings.json，以及项目中的 .claude/settings.json 和 .claude/settings.local.json。Codex 使用 ~/.codex/config.toml，以及受信任项目中的 .codex/config.toml。Gemini CLI 和 Qwen Code 使用 ~/.gemini/settings.json 和 ~/.qwen/settings.json，每个项目各有一个 .gemini 或 .qwen 文件夹。OpenCode 使用 ~/.config/opencode/opencode.json 和 opencode.json，Amp 使用 ~/.config/amp/settings.json 和 .amp/settings.json，Factory Droid 使用 ~/.factory/settings.json。Cursor 把 AI 设置放在 Cursor Settings 面板中，permissions.json 等 agent 文件放在 ~/.cursor 和 .cursor。在所有工具中，项目文件都会覆盖用户文件。

本文译自英文版指南。命令、配置键与代码均保持原样；如有出入，以英文版为准。 阅读英文原版 → · 其他语言: 日本語 · 한국어 · Español · Português (Brasil)

设置一变，第一时间知道

当这些工具的设置、参数或权限规则发生变化时，每周一封邮件通知你（英文），内容均对照官方文档核实。

快速答案：用户与项目设置文件

  • Claude Code：~/.claude/settings.json（用户）、.claude/settings.json（共享项目）、.claude/settings.local.json（仅自己，单个项目）。常用选项可用 /config 修改。
  • Cursor：AI 功能用 Cursor Settings 面板（Ctrl/Cmd + Shift + J），编辑器键用 VS Code 风格的 settings.json，agent 文件位于 ~/.cursor 和 .cursor：mcp.json、permissions.json、hooks.json、sandbox.json。Cursor CLI 使用 ~/.cursor/cli-config.json。
  • OpenAI Codex：~/.codex/config.toml（用户）和仓库中的 .codex/config.toml，后者仅在你信任该项目时加载。
  • Gemini CLI：~/.gemini/settings.json（用户）和项目根目录的 .gemini/settings.json。
  • Qwen Code：~/.qwen/settings.json（用户）和项目根目录的 .qwen/settings.json。
  • OpenCode：~/.config/opencode/opencode.json（全局）和项目根目录的 opencode.json。也支持 JSONC。
  • Amp：~/.config/amp/settings.json（用户）和最近的 .amp/settings.json（工作区）。所有键都以 amp. 开头。
  • Factory Droid：~/.factory/settings.json，用 /settings 命令编辑。同目录下的 settings.local.json 会叠加合并在其之上。

哪个文件生效

  • Claude Code，优先级从高到低：托管设置、命令行参数、.claude/settings.local.json、.claude/settings.json、~/.claude/settings.json。permissions.allow 等列表键会跨文件合并。
  • Codex，优先级从高到低：CLI 参数和 -c 覆盖、项目 .codex/config.toml 文件（离当前目录最近的生效）、--profile 文件、~/.codex/config.toml，然后是系统和内置默认值。
  • Gemini CLI 和 Qwen Code：项目文件覆盖用户文件，系统设置文件覆盖两者。环境变量和命令行参数覆盖所有文件。
  • OpenCode：文件是合并而非替换。后加载的来源只在键冲突时覆盖先前的来源，项目配置在全局配置之后加载。
  • Amp：工作区设置覆盖用户设置。
  • Cursor permissions.json：用户文件和项目文件会合并，其中的数组会拼接。
  • Factory Droid：settings.local.json 在同一层级叠加合并在 settings.json 之上。

思路相同，语法不同

Claude Code：.claude/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run test *)"],
    "deny": ["Read(./.env)"]
  }
}

Codex：~/.codex/config.toml

model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

Gemini CLI：.gemini/settings.json

{
  "general": {
    "defaultApprovalMode": "auto_edit"
  },
  "tools": {
    "sandbox": "docker"
  }
}

OpenCode：opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": { "*": "ask", "git *": "allow" }
  }
}

Cursor：.cursor/permissions.json

{
  "terminalAllowlist": ["git", "npm", "pnpm"],
  "mcpAllowlist": ["github:*"]
}

常见陷阱

  • Claude Code 设置文件是严格 JSON。注释或尾随逗号都会导致语法错误。
  • 项目 .codex/config.toml 不能设置 provider、auth、notification、profile 或 telemetry 键。这些请放在 ~/.codex/config.toml。
  • Gemini CLI 设置必须放在对应的类别对象中，例如 general、ui、model 或 tools。YOLO mode 不能在文件中设置，只能用 --yolo 或 --approval-mode=yolo。
  • 提交共享文件（.claude/settings.json、.cursor/permissions.json、opencode.json），个人文件不要纳入 git（.claude/settings.local.json、Droid 的 settings.local.json）。

各 agent 的完整设置指南

来源

以下为本指南核对过的官方文档（英文）。 英文版核对日期: 2026-10-18

Claude Code: Settings files and precedenceCursor Docs: Permissions referenceCursor Docs: CLI configurationOpenAI: Codex config basicsGemini CLI: ConfigurationQwen Code: SettingsOpenCode: ConfigAmp: CLI settingsFactory: Droid CLI settings

更多中文指南