Reglas

Usa reglas para controlar qué comandos puede ejecutar Codex fuera del entorno aislado.

Crear un archivo de reglas

1. Crea un archivo .rules dentro de una carpeta rules/ junto a una capa de configuración activa (por ejemplo, ~/.codex/rules/default.rules).
2. Añade una regla. Este ejemplo solicita confirmación antes de permitir que gh pr view se ejecute fuera del entorno aislado.

   # Prompt before running commands with the prefix `gh pr view` outside the sandbox.
   prefix_rule(
       # The prefix to match.
       pattern = ["gh", "pr", "view"],

       # The action to take when Codex requests to run a matching command.
       decision = "prompt",

       # Optional rationale for why this rule exists.
       justification = "Viewing PRs is allowed with approval",

       # `match` and `not_match` are optional "inline unit tests" where you can
       # provide examples of commands that should (or should not) match this rule.
       match = [
           "gh pr view 7888",
           "gh pr view --repo openai/codex",
           "gh pr view 7888 --json title,body,comments",
       ],
       not_match = [
           # Does not match because the `pattern` must be an exact prefix.
           "gh pr --repo openai/codex view 7888",
       ],
   )

3. Reinicia Codex.

Al iniciarse, Codex examina los archivos rules/ de cada capa de configuración activa, incluidas las ubicaciones de Configuración del equipo y la capa del usuario en ~/.codex/rules/. Las reglas locales del proyecto en <repo>/.codex/rules/ solo se cargan cuando la capa .codex/ del proyecto es de confianza.

Cuando añades un comando a la lista de permitidos en la TUI, Codex lo escribe en la capa del usuario en ~/.codex/rules/default.rules para que las ejecuciones futuras puedan omitir la solicitud de confirmación.

Cuando las aprobaciones inteligentes están habilitadas (la opción predeterminada), Codex puede proponerte un prefix_rule durante las solicitudes de escalamiento. Revisa cuidadosamente el prefijo sugerido antes de aceptarlo.

Los administradores también pueden imponer entradas prefix_rule restrictivas desde requirements.toml.

Comprender los campos de las reglas

prefix_rule() admite estos campos:

• pattern (obligatorio): Una lista no vacía que define el prefijo de comando que debe coincidir. Cada elemento puede ser:
  • Una cadena literal (por ejemplo, "pr").
  • Una unión de literales (por ejemplo, ["view", "list"]) para hacer coincidir alternativas en esa posición del argumento.
• decision (el valor predeterminado es "allow"): La acción que se debe realizar cuando la regla coincide. Codex aplica la decisión más restrictiva cuando coincide más de una regla (forbidden > prompt > allow).
  • allow: Ejecuta el comando fuera del entorno aislado sin solicitar confirmación.
  • prompt: Solicita confirmación antes de cada invocación coincidente.
  • forbidden: Bloquea la solicitud sin pedir confirmación.
• justification (opcional): Un motivo no vacío y legible para la regla. Codex puede mostrarlo en solicitudes de aprobación o mensajes de rechazo. Cuando uses forbidden, incluye una alternativa recomendada en la justificación cuando corresponda (por ejemplo, "Use \rg` instead of `grep`."`).
• match y not_match (el valor predeterminado es []): Ejemplos que Codex valida cuando carga tus reglas. Úsalos para detectar errores antes de que una regla entre en vigor.

Cuando Codex considera ejecutar un comando, compara la lista de argumentos del comando con pattern. Internamente, Codex trata el comando como una lista de argumentos (como la que recibe execvp(3)).

Contenedores de shell y comandos compuestos

Algunas herramientas agrupan varios comandos de shell en una sola invocación, por ejemplo:

["bash", "-lc", "git add . && rm -rf /"]

Como este tipo de comando puede ocultar varias acciones dentro de una sola cadena, Codex trata bash -lc, bash -c y sus equivalentes zsh / sh de manera especial.

Cuando Codex puede dividir el script de forma segura

Si el script de shell es una cadena lineal de comandos compuesta únicamente por:

• palabras simples (sin expansión de variables, ni VAR=..., $FOO, *, etc.)
• unidas mediante operadores seguros (&&, ||, ; o |)

entonces Codex lo analiza (mediante tree-sitter) y lo divide en comandos individuales antes de aplicar tus reglas.

El script anterior se trata como dos comandos independientes:

• ["git", "add", "."]
• ["rm", "-rf", "/"]

A continuación, Codex evalúa cada comando según tus reglas y prevalece el resultado más restrictivo.

Aunque permitas pattern=["git", "add"], Codex no permitirá automáticamente git add . && rm -rf /, porque la parte rm -rf / se evalúa por separado e impide que toda la invocación se permita automáticamente.

Esto evita que se introduzcan comandos peligrosos junto con otros seguros.

Cuando Codex no divide el script

Si el script usa funciones de shell más avanzadas, como:

• redirección (>, >>, <)
• sustituciones ($(...), ...)
• variables de entorno (FOO=bar)
• patrones comodín (*, ?)
• flujo de control (if, for, && con asignaciones, etc.)

entonces Codex no intenta interpretarlo ni dividirlo.

En esos casos, toda la invocación se trata como:

["bash", "-lc", "<full script>"]

y tus reglas se aplican a esa única invocación.

Con este tratamiento, obtienes la seguridad de la evaluación por comando cuando es seguro hacerlo y un comportamiento conservador cuando no lo es.

Probar un archivo de reglas

Usa codex execpolicy check para probar cómo se aplican tus reglas a un comando:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments

El comando emite JSON que muestra la decisión más estricta y todas las reglas coincidentes, incluidos los valores justification de las reglas coincidentes. Usa más de una opción --rules para combinar archivos y añade --pretty para dar formato a la salida.

Comprender el lenguaje de reglas

El formato de archivo .rules usa Starlark (consulta la especificación del lenguaje). Su sintaxis es similar a la de Python, pero está diseñada para ejecutarse de forma segura: el motor de reglas puede ejecutarla sin efectos secundarios (por ejemplo, sin modificar el sistema de archivos).