coding-agent

Coding Agent

Use para construção de funcionalidades em segundo plano, revisões de PR, refatorações grandes e loops de issue para PR. Não use para edições simples, consulta somente leitura, trabalho vinculado a thread ACP ou qualquer execução dentro de ~/.openclaw, $OPENCLAW_STATE_DIR ou diretórios de estado ativos do OpenClaw.

Regras rígidas

• Sempre inicie com background:true.
• Codex e OpenCode: use pty:true.
• Codex: nunca herde o CODEX_HOME ambiente ou o ~/.codex padrão. Use um home de coding-agent autenticado separadamente e escopo-o para cada comando Codex.
• Claude Code: sem PTY; use claude --permission-mode bypassPermissions --print.
• Capture uma rota de notificação real antes de iniciar.
• O worker deve enviar conclusão/falha via openclaw message send.
• Não confie em heartbeat, eventos de sistema ou notify-on-exit.
• Monitore com process; não mate workers lentos sem motivo.
• Se o usuário solicitou um agente específico, use esse agente.
• Se o worker falhar/travar, reinicie ou pergunte; não codifique manualmente em silêncio.
• Nunca faça checkout de branches ou execute coding agents em segundo plano em ~/Projects/openclaw; use um checkout isolado.
• Classifique a referência de origem como confiável ou não confiável antes de qualquer checkout ou criação de worktree. Nunca materialize uma ref controlada por um contribuidor fora do sandbox/workflow de revisão de PR não confiável aprovado do repositório, e nunca inicie um worker com permissão ignorada dentro dele.
• Para tarefas que modificam um projeto com Git, prepare e verifique a worktree Git antes de iniciar, então inclua o bloco exato de preparação Git abaixo no prompt do worker.

Preparação Git obrigatória

Antes de iniciar Codex, Claude Code ou OpenCode para trabalho que modifica um projeto com Git:

1. Estabeleça o repositório alvo pretendido e selecione seu remote canônico. Prefira upstream quando ele existe e corresponde a esse alvo; caso contrário, verifique origin. Resolva a branch padrão do remote selecionado dinamicamente. Determine a base alvo a partir de uma branch de tarefa explícita ou metadados de PR existente com autoridade; para outras branches compartilhadas, prove a base configurada/rastreada ou pergunte. Use o padrão canônico apenas para trabalho novo sem outra base especificada. Pare se o repositório, remote ou base alvo não puderem ser provados.
2. Classifique a referência de origem como confiável ou não confiável antes de qualquer checkout ou criação de worktree. Para refs controladas por contribuidores, use o sandbox/workflow de revisão de PR não confiável aprovado do repositório, que deve possuir a materialização da ref dentro do sandbox, ou pare. As etapas restantes e formas de inicialização são apenas para refs confiáveis.
3. Para trabalho novo confiável, execute git fetch --prune <canonical> imediatamente antes de criar uma nova worktree e branch isoladas a partir de <canonical>/<targetBaseBranch>.
4. Para trabalho novo confiável, verifique se o HEAD inicial da worktree é igual ao SHA da base alvo obtida. Registre o remote canônico, branch padrão canônica, branch base alvo, SHA da base, caminho da worktree e branch.
5. Para um PR existente confiável ou branch compartilhada, busque a base alvo canônica e a branch de origem imediatamente antes de criar uma worktree isolada a partir da branch de origem obtida. Registre essa ref de origem e o SHA inicial, informe sua divergência da base alvo atualizada e não faça rebase, merge, reset, force-push ou reescreva o histórico compartilhado automaticamente.
6. Inicie o worker na worktree isolada, nunca no checkout principal. Para OpenClaw, o checkout principal em ~/Projects/openclaw permanece proibido.

Para tarefas que modificam um projeto com Git, anexe este bloco ao prompt do worker com valores reais:

Preparação Git (obrigatória antes de edições):
- remote canônico: <canonicalRemote>
- branch padrão canônica: <canonicalDefaultBranch>
- branch base alvo: <targetBaseBranch>
- SHA da base alvo obtida: <targetBaseSha>
- modo de preparação: <trabalho novo | PR existente/branch compartilhada>
- confiança do checkout: confiável
- ref de origem preparada: <canonicalRemote/targetBaseBranch | ref de origem confiável obtida>
- SHA inicial preparado: <preparedStartSha>
- worktree isolada: <worktreePath>
- branch de trabalho: <branch>
- recibo de preparação: <trabalho novo: `git fetch --prune <canonicalRemote>` foi executado imediatamente antes da criação a partir de `<canonicalRemote>/<targetBaseBranch>` | branch existente: a base alvo canônica e a ref de origem confiável foram obtidas imediatamente antes de a worktree ser criada a partir de `<preparedSourceRef>` em `<preparedStartSha>`>

Antes de editar, verifique se o diretório atual é a worktree isolada e seu HEAD inicial é igual a <preparedStartSha>. Para trabalho novo, esse SHA deve ser igual a <targetBaseSha>. Nunca edite o checkout principal. Para trabalho em PR/branch compartilhada existente, informe a divergência e não faça rebase, merge, reset, force-push ou reescreva o histórico compartilhado a menos que explicitamente solicitado.
Imediatamente antes do push final ou PR para trabalho recém-criado, execute `git fetch --prune <canonicalRemote>` e `git merge-base --is-ancestor <canonicalRemote>/<targetBaseBranch> HEAD`. Se a verificação de ancestralidade falhar, atualize a nova branch para a base alvo mais recente, reexecute a prova relevante e só então faça push sem force. Para PR/branch compartilhada existente, informe uma verificação de ancestralidade falhada e siga o workflow do repositório sem reescrever a branch.

Para refs confiáveis, o lançador deve criar e verificar a worktree antes de iniciar o worker de edição; não delegue a criação da worktree a esse worker. O workflow aprovado de PR não confiável deve, em vez disso, possuir o checkout e a materialização da worktree dentro de seu sandbox. Nunca inicie um worker em ~/Projects/openclaw. Tarefas somente leitura e trabalho de rascunho não relacionado a projeto não exigem o bloco de preparação Git.

Bloco de notificação

Anexe este formato a cada prompt de worker com valores reais:

Rota de notificação:
- canal: <notifyChannel>
- destino: <notifyTarget>
- conta: <notifyAccount ou omitir>
- responder_para: <notifyReplyTo ou omitir>
- thread_id: <notifyThreadId ou omitir>

Quando terminar, envie exatamente uma mensagem de conclusão ou falha usando:
openclaw message send --channel <channel> --target '<target>' --message '<resumo do resultado>'
Adicione --account, --reply-to ou --thread-id apenas quando presentes acima.
Não use openclaw system event ou heartbeat.

Se nenhuma rota confiável existir, informe que a auto-notificação de conclusão não está disponível.

Formas de inicialização

Escreva o prompt do worker em um arquivo temporário primeiro. Isso evita bugs de escaping de shell quando o bloco de notificação obrigatório contém aspas ou quebras de linha.

PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
Tarefa.
<bloco de preparação Git obrigatório>
<bloco de notificação>
EOF
printf 'arquivo de prompt: %s\n' "$PROMPT"

Use $PROMPT ao iniciar do mesmo shell/sessão. Se estiver usando uma chamada de ferramenta separada, substitua pelo caminho impresso. As formas de inicialização abaixo são apenas para checkouts confiáveis; refs de contribuidores não confiáveis exigem o sandbox/workflow de revisão aprovado do repositório.

Antes do primeiro worker Codex em um host, prepare um home de autenticação dedicado em primeiro plano. Não copie auth.json ou outras credenciais do ~/.codex ambiente; autorize este home separadamente. Codex escopa tanto credenciais de arquivo quanto de keyring 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 'Login do Codex coding-agent necessário para %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 do worker Codex: %s\n' "$CODEX_WORKER_HOME"

O login é uma etapa de configuração interativa em primeiro plano, não um worker em segundo plano. O comando de inicialização repete o home fixo e entre aspas e remove substituições de autenticação Codex e OpenAI ambientes. Nunca exporte o home do worker para o ambiente do OpenClaw Gateway.

Codex:

bash pty:true background:true workdir:/caminho/worktree-isolada 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:/caminho/worktree-isolada command:"claude --permission-mode bypassPermissions --print < \"$PROMPT\""

OpenCode:

bash pty:true background:true workdir:/caminho/worktree-isolada command:"opencode run < \"$PROMPT\""

Trabalho longo de issue para PR

1. Crie/reutilize uma issue do GitHub como especificação durável.
2. Inclua URL da issue, repositório, remote canônico/branch padrão, branch base alvo/SHA, worktree isolada, branch de trabalho, PR esperado, prova e rota de notificação.
3. Inclua o bloco obrigatório de preparação Git, depois instrua o worker a implementar, testar, executar revisão até que não haja achados acionáveis aceitos e abrir o PR.
4. Retorne URL da issue e sessionId imediatamente.
5. Monitore com process; cancele através do Task Registry se espelhado lá.

Scratch Codex

Codex precisa de um repositório Git confiável. Este scaffold descartável não é trabalho de projeto e não tem remote canônico, portanto o bloco de preparação Git não se aplica:

SCRATCH=$(mktemp -d)
git -C "$SCRATCH" init
PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
Construa X.
<bloco de notificação>
EOF
printf 'arquivo 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\""

Ações de processo

• list: sessões em execução/recentes.
• poll: status.
• log: saída.
• submit: enviar entrada + Enter.
• write: stdin bruto.
• paste: colar texto.
• kill: encerrar.

Status para o usuário

• Informe o que foi iniciado, onde e sessionId.
• Atualize apenas em marco, pergunta do worker, erro, ação necessária do usuário ou conclusão.
• Se encerrado, informe o motivo.