Reglas

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

Crear un archivo de reglas

Para acceder a la computadora local con la nube de Work, usa el campo rules de TOML en la configuración de seguridad del agente para definir las reglas administradas de comandos que se admiten. Estas reglas se aplican a los ejecutores locales. Los contenedores en la nube de Work usan las políticas vigentes de esa nube.

Estas instrucciones sobre archivos .rules locales se aplican a Codex. No des por hecho que la función de acceso a la computadora local con la nube de Work lee archivos de reglas locales. Consulta la configuración administrada y la referencia de configuración para conocer los requisitos administrados de Work.

1. Crea un archivo .rules en una carpeta rules/ junto a una capa de configuración activa (por ejemplo, ~/.codex/rules/default.rules).

2. Agrega una regla. En este ejemplo, Codex solicita aprobación antes de permitir que gh pr view se ejecute fuera del sandbox.

   # 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 busca reglas en la carpeta rules/ de cada capa de configuración activa, incluidas las ubicaciones de configuración del equipo y la capa de usuario en ~/.codex/rules/. Las reglas locales del proyecto que se encuentran en <repo>/.codex/rules/ solo se cargan si la capa .codex/ del proyecto es de confianza.

Cuando agregas un comando a la lista de comandos permitidos en la interfaz de texto (TUI), Codex guarda la regla en la capa de usuario, en ~/.codex/rules/default.rules, para que pueda omitir la solicitud de aprobación en futuras ejecuciones.

Cuando las aprobaciones inteligentes están habilitadas (la opción predeterminada), Codex puede proponerte una regla prefix_rule al solicitar permisos adicionales. Revisa con atención el prefijo sugerido antes de aceptarlo.

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

Campos de una regla

prefix_rule() admite los siguientes campos:

• pattern (obligatorio): lista no vacía que define el prefijo con el que debe coincidir el comando. Cada elemento puede ser:
  • una cadena literal (por ejemplo, "pr").
  • una unión de literales (por ejemplo, ["view", "list"]) que admite distintos valores para el argumento en esa posición.
• decision (valor predeterminado: "allow"): acción que se realiza cuando un comando coincide con la regla. Si coincide con varias reglas, Codex aplica la decisión más restrictiva (forbidden > prompt > allow).
  • allow: ejecuta el comando fuera del sandbox sin solicitar aprobación.
  • prompt: solicita aprobación antes de cada invocación que coincida con la regla.
  • forbidden: bloquea la solicitud sin pedir aprobación.
• justification (opcional): texto no vacío que explica el motivo de la regla. Codex puede mostrarlo en las solicitudes de aprobación o en los mensajes de rechazo. Cuando uses forbidden, incluye en la justificación una alternativa recomendada si corresponde (por ejemplo, "Use \rg` instead of `grep`.“`).
• match y not_match (valor predeterminado: []): ejemplos que Codex valida al cargar tus reglas. Úsalos para detectar errores antes de que una regla entre en vigor.

Al evaluar si puede ejecutar un comando, Codex compara su lista de argumentos con pattern. Internamente, Codex trata el comando como una lista de argumentos, similar a la que recibe execvp(3).

Envoltorios 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 en una sola cadena, Codex trata de manera especial bash -lc, bash -c y sus equivalentes en zsh y sh.

Cuándo puede Codex dividir el script de forma segura

Codex puede dividir un script de shell si consiste en una secuencia lineal de comandos que cumple estas dos condiciones:

• Los comandos solo contienen palabras simples (sin expansión de variables, sin VAR=..., $FOO, *, etc.).
• Los comandos están unidos por operadores seguros (&&, ||, ; o |).

En ese caso, Codex analiza el script con tree-sitter y lo divide en comandos individuales antes de aplicar tus reglas.

Codex trata el script anterior como dos comandos separados:

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

Luego, Codex evalúa cada comando según tus reglas y aplica el resultado más restrictivo.

Aunque permitas pattern=["git", "add"], Codex no permitirá automáticamente git add . && rm -rf /, ya que evalúa rm -rf / por separado.

Así se evita que alguien introduzca comandos peligrosos de forma encubierta junto con otros seguros.

Cuándo deja Codex el script sin dividir

Un script puede usar funciones más avanzadas del shell, como las siguientes:

• redirecciones (>, >>, <)
• sustituciones ($(...), ...)
• variables de entorno (FOO=bar)
• patrones con comodines (*, ?)
• control de flujo (if, for, && con asignaciones, etc.)

Si el script usa alguna de estas funciones, Codex no intenta interpretarlo ni dividirlo.

En esos casos, Codex trata la invocación completa de la siguiente manera:

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

y aplica tus reglas a esa única invocación.

Así, Codex evalúa cada comando por separado cuando puede hacerlo de forma segura y actúa con cautela en los demás casos.

Probar un archivo de reglas

Usa codex execpolicy check para comprobar 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 devuelve un resultado en JSON que muestra la decisión más restrictiva, las reglas coincidentes y cualquier valor de justification que contengan esas reglas. Usa la opción --rules más de una vez para combinar archivos y agrega --pretty para dar formato a la salida.

El lenguaje de las reglas

El formato de los archivos .rules usa Starlark (consulta la especificación del lenguaje). Su sintaxis se parece a la de Python, pero está diseñado para que el motor de reglas pueda ejecutarlo de forma segura, sin efectos secundarios como modificar el sistema de archivos.