agente-de-codificacion

Agente de Codificación

Úselo para construcciones de funcionalidades en segundo plano, revisiones de PR, refactorizaciones grandes y bucles de issue a PR. No lo use para ediciones simples, consultas de solo lectura, trabajo ligado al hilo ACP, ni ninguna ejecución dentro de ~/.openclaw, $OPENCLAW_STATE_DIR o directorios de estado activos de OpenClaw.

Reglas estrictas

• Láncese siempre con background:true.
• Codex y OpenCode: use pty:true.
• Codex: nunca herede el CODEX_HOME ambiental o el ~/.codex predeterminado. Use un home de agente de codificación autenticado por separado y delimítelo a cada comando de Codex.
• Claude Code: sin PTY; use claude --permission-mode bypassPermissions --print.
• Capture una ruta de notificación real antes de generar el trabajador.
• El trabajador debe enviar finalización/fallo a través de openclaw message send.
• No dependa de latidos, eventos del sistema o notificación al salir.
• Monitoree con process; no mate trabajadores lentos sin motivo.
• Si el usuario solicitó un agente específico, use ese agente.
• Si el trabajador falla/se cuelga, reintente o pregunte; no codifique manualmente en silencio.
• Nunca haga checkout de ramas ni ejecute agentes de codificación en segundo plano en ~/Projects/openclaw; use un checkout aislado.
• Clasifique la referencia fuente como confiable o no confiable antes de cualquier checkout o creación de árbol de trabajo. Nunca materialice una referencia controlada por un colaborador fuera del sandbox/flujo de revisión de PR no confiable aprobado del repositorio, y nunca lance un trabajador con permisos omitidos en él.
• Para tareas que modifican un proyecto basado en Git, prepare y verifique el árbol de trabajo de Git antes del lanzamiento, luego incluya el bloque de preparación de Git exacto a continuación en el prompt del trabajador.

Preparación obligatoria de Git

Antes de lanzar Codex, Claude Code u OpenCode para trabajo que modifique un proyecto basado en Git:

1. Establezca el repositorio de destino previsto, luego seleccione su remoto canónico. Prefiera upstream cuando exista y coincida con ese destino; de lo contrario, verifique origin. Resuelva la rama predeterminada del remoto seleccionado dinámicamente. Determine la base de destino a partir de una rama de tarea explícita o metadatos autorizados de PR existentes; para otras ramas compartidas, demuestre la base configurada/rastreada o pregunte. Use la predeterminada canónica solo para trabajo nuevo sin otra base especificada. Deténgase si el repositorio, remoto o base de destino no se puede probar.
2. Clasifique la referencia fuente como confiable o no confiable antes de cualquier checkout o creación de árbol de trabajo. Para referencias controladas por colaboradores, use el flujo de trabajo de revisión sandbox/PR no confiable aprobado del repositorio, que debe poseer la materialización de la referencia dentro del sandbox, o deténgase. Los pasos restantes y los formularios de lanzamiento son solo para referencias confiables.
3. Para trabajo nuevo confiable, ejecute git fetch --prune <canonical> inmediatamente antes de crear un nuevo árbol de trabajo aislado y una rama desde <canonical>/<targetBaseBranch>.
4. Para trabajo nuevo confiable, verifique que el HEAD inicial del árbol de trabajo sea igual al SHA de la base de destino obtenida. Registre el remoto canónico, la rama predeterminada canónica, la rama base de destino, el SHA base, la ruta del árbol de trabajo y la rama.
5. Para un PR existente confiable o una rama compartida, obtenga la base de destino canónica y la rama fuente inmediatamente antes de crear un árbol de trabajo aislado desde la rama fuente obtenida. Registre esa referencia fuente y el SHA inicial, informe su divergencia de la base de destino actualizada, y no rebase, fusione, reinicie, haga push forzado ni reescriba el historial compartido de otro modo.
6. Lance el trabajador en el árbol de trabajo aislado, nunca en el checkout principal. Para OpenClaw, el checkout principal en ~/Projects/openclaw permanece prohibido.

Para tareas que modifican un proyecto basado en Git, agregue este bloque al prompt del trabajador con valores reales:

Preparación de Git (obligatoria antes de editar):
- remoto canónico: <canonicalRemote>
- rama predeterminada canónica: <canonicalDefaultBranch>
- rama base de destino: <targetBaseBranch>
- SHA de la base de destino obtenida: <targetBaseSha>
- modo de preparación: <nuevo trabajo | PR existente/rama compartida>
- confianza de checkout: confiable
- referencia fuente preparada: <canonicalRemote/targetBaseBranch | referencia fuente confiable obtenida>
- SHA inicial preparado: <preparedStartSha>
- árbol de trabajo aislado: <worktreePath>
- rama de trabajo: <branch>
- recibo de preparación: <nuevo trabajo: `git fetch --prune <canonicalRemote>` se ejecutó inmediatamente antes de la creación desde `<canonicalRemote>/<targetBaseBranch>` | rama existente: la base de destino canónica y la referencia fuente confiable se obtuvieron inmediatamente antes de que se creara el árbol de trabajo desde `<preparedSourceRef>` en `<preparedStartSha>`>

Antes de editar, verifique que el directorio actual sea el árbol de trabajo aislado y que su HEAD inicial sea igual a <preparedStartSha>. Para trabajo nuevo, ese SHA debe ser igual a <targetBaseSha>. Nunca edite el checkout principal. Para trabajo en PR existente/rama compartida, informe la divergencia y no rebase, fusione, reinicie, haga push forzado ni reescriba el historial compartido a menos que se le solicite explícitamente.
Inmediatamente antes del push final o PR para trabajo recién creado, ejecute `git fetch --prune <canonicalRemote>` y `git merge-base --is-ancestor <canonicalRemote>/<targetBaseBranch> HEAD`. Si la verificación de ascendencia falla, actualice la nueva rama sobre la base de destino más reciente, vuelva a ejecutar la prueba relevante, y solo entonces haga push sin forzar. Para PR existente/rama compartida, informe una verificación de ascendencia fallida y siga el flujo de trabajo del repositorio sin reescribir la rama.

Para referencias confiables, el lanzador debe crear y verificar el árbol de trabajo antes de iniciar el trabajador de edición; no delegue la creación del árbol de trabajo a ese trabajador. El flujo de trabajo de PR no confiable aprobado debe, en cambio, poseer el checkout y la materialización del árbol de trabajo dentro de su sandbox. Nunca inicie un trabajador en ~/Projects/openclaw. Las tareas de solo lectura y el trabajo de prueba no relacionado con el proyecto no requieren el bloque de preparación de Git.

Bloque de notificación

Agregue esta forma a cada prompt de trabajador con valores reales:

Ruta de notificación:
- canal: <notifyChannel>
- destino: <notifyTarget>
- cuenta: <notifyAccount u omitir>
- responder_a: <notifyReplyTo u omitir>
- id_hilo: <notifyThreadId u omitir>

Cuando termine, envíe exactamente un mensaje de finalización o fallo usando:
openclaw message send --channel <channel> --target '<target>' --message '<resultado breve>'
Agregue --account, --reply-to o --thread-id solo cuando estén presentes arriba.
No use openclaw system event ni heartbeat.

Si no existe una ruta confiable, indique que la auto-notificación de finalización no está disponible.

Formularios de lanzamiento

Escriba el prompt del trabajador en un archivo temporal primero. Esto evita errores de escapado de shell cuando el bloque de notificación requerido contiene comillas o nuevas líneas.

PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
Tarea.
<bloque de preparación de Git obligatorio>
<bloque de notificación>
EOF
printf 'archivo de prompt: %s\n' "$PROMPT"

Use $PROMPT al lanzar desde el mismo shell/sesión. Si usa una llamada de herramienta separada, sustituya la ruta impresa. Los formularios de lanzamiento a continuación son solo para checkouts confiables; las referencias de colaboradores no confiables requieren el flujo de trabajo de revisión/sandbox aprobado del repositorio.

Antes del primer trabajador de Codex en un host, prepare un home de autenticación dedicado en primer plano. No copie auth.json ni otras credenciales del ~/.codex ambiental; autorice este home por separado. Codex delimita tanto las credenciales de archivo como de llavero por CODEX_HOME.

CODEX_WORKER_HOME="$HOME/.codex-coding-agent"
mkdir -p "$CODEX_WORKER_HOME"
if ! env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY \
  CODEX_HOME="$CODEX_WORKER_HOME" codex login status >/dev/null 2>&1; then
  printf 'Se requiere inicio de sesión de Codex para agente de codificación en %s\n' "$CODEX_WORKER_HOME"
  env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY \
    CODEX_HOME="$CODEX_WORKER_HOME" codex login --device-auth
fi
printf 'Home del trabajador de Codex: %s\n' "$CODEX_WORKER_HOME"

El inicio de sesión es un paso de configuración interactivo en primer plano, no un trabajador en segundo plano. El comando de lanzamiento repite el home fijo y entrecomillado y elimina las anulaciones de autenticación ambiental de Codex y OpenAI. Nunca exporte el home del trabajador al entorno de OpenClaw Gateway.

Codex:

bash pty:true background:true workdir:/ruta/arbol-de-trabajo-aislado command:"env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY CODEX_HOME=\"$HOME/.codex-coding-agent\" codex exec - < \"$PROMPT\""

Claude Code:

bash background:true workdir:/ruta/arbol-de-trabajo-aislado command:"claude --permission-mode bypassPermissions --print < \"$PROMPT\""

OpenCode:

bash pty:true background:true workdir:/ruta/arbol-de-trabajo-aislado command:"opencode run < \"$PROMPT\""

Trabajo largo de issue a PR

1. Cree/reutilice un issue de GitHub como especificación duradera.
2. Incluya URL del issue, repositorio, remoto canónico/rama predeterminada, rama base de destino/SHA, árbol de trabajo aislado, rama de trabajo, PR esperado, prueba y ruta de notificación.
3. Incluya el bloque de preparación de Git obligatorio, luego indique al trabajador que implemente, pruebe, ejecute la revisión hasta que no haya hallazgos accionables aceptados y abra el PR.
4. Devuelva la URL del issue y sessionId inmediatamente.
5. Monitoree con process; cancele a través del Registro de Tareas si está reflejado allí.

Codex de prueba

Codex necesita un repositorio git confiable. Este andamio desechable no es trabajo de proyecto y no tiene remoto canónico, por lo que el bloque de preparación de Git no aplica:

SCRATCH=$(mktemp -d)
git -C "$SCRATCH" init
PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
Construya X.
<bloque de notificación>
EOF
printf 'archivo de prompt: %s\n' "$PROMPT"
bash pty:true background:true workdir:$SCRATCH command:"env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY CODEX_HOME=\"$HOME/.codex-coding-agent\" codex exec - < \"$PROMPT\""

Acciones de proceso

• list: sesiones activas/recientes.
• poll: estado.
• log: salida.
• submit: enviar entrada + Enter.
• write: stdin sin procesar.
• paste: pegar texto.
• kill: terminar.

Estado para el usuario

• Diga qué comenzó, dónde y sessionId.
• Actualice solo en hitos, preguntas del trabajador, errores, acción necesaria del usuario o finalización.
• Si se terminó, diga por qué.