가이드

모든 AI 코딩 에이전트의 설정 파일 위치: Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Qwen Code, Amp, Factory Droid (2026)

각 AI 코딩 에이전트의 설정 파일은 어디에 있으며, 같은 키가 두 번 설정되면 어느 파일이 우선합니까?

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 같은 에이전트 파일을 ~/.cursor와 .cursor에 둡니다. 모든 도구에서 프로젝트 파일이 사용자 파일보다 우선합니다.

이 페이지는 영어 가이드를 번역한 것입니다. 명령어, 설정 키, 코드는 원문 그대로이며 내용이 다를 경우 영어판을 기준으로 합니다. 영어 원문 보기 → · 다른 언어: 简体中文 · 日本語 · Español · Português (Brasil)

설정 변경 소식을 가장 먼저 받아 보세요

이 도구들의 설정, 플래그, 권한 규칙이 바뀌면 주 1회 이메일(영어)로 알려 드립니다. 모든 내용은 공식 문서로 확인합니다.

빠른 답변: 사용자 및 프로젝트 설정 파일

  • 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, 에이전트 파일은 ~/.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(우선순위 높은 순): managed settings, 명령줄 인수, .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입니다. 주석이나 trailing comma는 문법 오류입니다.
  • 프로젝트 .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)은 커밋하고, 개인 파일(.claude/settings.local.json, Droid의 settings.local.json)은 git에서 제외하십시오.

에이전트별 전체 설정 가이드

출처

이 가이드에서 확인한 공식 문서(영어)입니다. 영어판 확인일: 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

다른 한국어 가이드