Guías

Ubicación de los archivos de configuración en todos los agentes de programación con IA: Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Qwen Code, Amp y Factory Droid (2026)

¿Dónde está el archivo de configuración de cada agente de programación con IA, y qué archivo gana cuando la misma clave se define dos veces?

Claude Code usa ~/.claude/settings.json además de .claude/settings.json y .claude/settings.local.json en el proyecto. Codex usa ~/.codex/config.toml además de .codex/config.toml en proyectos de confianza. Gemini CLI y Qwen Code usan ~/.gemini/settings.json y ~/.qwen/settings.json con una carpeta .gemini o .qwen por proyecto. OpenCode usa ~/.config/opencode/opencode.json y opencode.json, Amp usa ~/.config/amp/settings.json y .amp/settings.json, y Factory Droid usa ~/.factory/settings.json. Cursor guarda la configuración de IA en el panel Cursor Settings y los archivos del agente, como permissions.json, en ~/.cursor y .cursor. En todas las herramientas, el archivo del proyecto sobrescribe el del usuario.

Esta página es una traducción de la guía en inglés. Los comandos, claves de configuración y el código no se modifican; si hay diferencias, prevalece la versión en inglés. Leer en inglés → · Otros idiomas: 简体中文 · 日本語 · 한국어 · Português (Brasil)

Entérate cuando cambie la configuración

Cuando cambie un ajuste, flag o regla de permisos de estas herramientas, te avisamos en un correo semanal (en inglés), verificado con la documentación oficial.

Respuesta rápida: archivos de configuración de usuario y de proyecto

  • Claude Code: ~/.claude/settings.json (usuario), .claude/settings.json (proyecto compartido), .claude/settings.local.json (solo tú, un proyecto). Cambia las opciones comunes con /config.
  • Cursor: el panel Cursor Settings (Ctrl/Cmd + Shift + J) para las funciones de IA, el settings.json estilo VS Code para las claves del editor, y los archivos del agente en ~/.cursor y .cursor: mcp.json, permissions.json, hooks.json, sandbox.json. La Cursor CLI usa ~/.cursor/cli-config.json.
  • OpenAI Codex: ~/.codex/config.toml (usuario) y .codex/config.toml en el repo, que solo se carga cuando confías en el proyecto.
  • Gemini CLI: ~/.gemini/settings.json (usuario) y .gemini/settings.json en la raíz del proyecto.
  • Qwen Code: ~/.qwen/settings.json (usuario) y .qwen/settings.json en la raíz del proyecto.
  • OpenCode: ~/.config/opencode/opencode.json (global) y opencode.json en la raíz del proyecto. También funciona JSONC.
  • Amp: ~/.config/amp/settings.json (usuario) y el .amp/settings.json más cercano (workspace). Todas las claves empiezan por amp.
  • Factory Droid: ~/.factory/settings.json, que se edita con el comando /settings. Un settings.local.json junto a él se fusiona por encima.

Qué archivo gana

  • Claude Code, de mayor a menor prioridad: managed settings, argumentos de línea de comandos, .claude/settings.local.json, .claude/settings.json, ~/.claude/settings.json. Las claves de tipo lista, como permissions.allow, se fusionan entre archivos.
  • Codex, de mayor a menor prioridad: flags de la CLI y sobrescrituras con -c, los archivos .codex/config.toml del proyecto (gana el más cercano a tu directorio), un archivo de --profile, ~/.codex/config.toml, y luego los valores predeterminados del sistema e integrados.
  • Gemini CLI y Qwen Code: el archivo del proyecto sobrescribe el del usuario, y un archivo de configuración del sistema sobrescribe ambos. Las variables de entorno y los argumentos de línea de comandos sobrescriben todos los archivos.
  • OpenCode: los archivos se fusionan, no se reemplazan. Las fuentes posteriores sobrescriben a las anteriores solo en las claves en conflicto, y la configuración del proyecto se carga después de la global.
  • Amp: la configuración del workspace sobrescribe la del usuario.
  • permissions.json de Cursor: los archivos de usuario y de proyecto se combinan, y sus arrays se concatenan.
  • Factory Droid: settings.local.json se fusiona por encima de settings.json en el mismo nivel.

La misma idea, distinta sintaxis

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:*"]
}

Errores comunes

  • Los archivos de configuración de Claude Code son JSON estricto. Un comentario o una coma final es un error de sintaxis.
  • Un .codex/config.toml de proyecto no puede definir claves de provider, auth, notificaciones, profile ni telemetría. Ponlas en ~/.codex/config.toml.
  • La configuración de Gemini CLI debe estar dentro de su objeto de categoría, como general, ui, model o tools. YOLO mode no se puede definir en el archivo, solo con --yolo o --approval-mode=yolo.
  • Haz commit de los archivos compartidos (.claude/settings.json, .cursor/permissions.json, opencode.json) y deja los personales fuera de git (.claude/settings.local.json, el settings.local.json de Droid).

Guía completa de configuración para cada agente

Fuentes

Documentación oficial (en inglés) con la que se verificó esta guía. Versión en inglés revisada el: 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

Más guías en español