Modo não interativo

O modo não interativo permite executar o Codex em scripts, como os usados em jobs de integração contínua (CI), sem abrir a interface interativa de terminal (TUI). Para usar esse modo, execute codex exec.

Para mais detalhes sobre as opções, consulte codex exec.

Quando usar codex exec

Use codex exec quando quiser que o Codex:

• Faça parte de um pipeline de CI, de verificações antes do merge ou de jobs agendados.
• Produza uma saída que você possa enviar por pipe a outras ferramentas, por exemplo, para gerar notas de versão ou resumos.
• Integre fluxos de trabalho da CLI que enviam a saída de comandos ao Codex e encaminham a saída do Codex a outras ferramentas.
• Use configurações explícitas de sandbox e aprovação definidas com antecedência.

Uso básico

Passe o prompt da tarefa como um único argumento:

codex exec "resuma a estrutura do repositório e liste as 5 áreas de maior risco"

Durante a execução de codex exec, o Codex envia atualizações de progresso para stderr e grava apenas a mensagem final do agente em stdout. Assim, você pode redirecionar o resultado final ou enviá-lo por pipe:

codex exec "gere notas de versão para os últimos 10 commits" | tee release-notes.md

Use --ephemeral quando não quiser salvar em disco os arquivos que registram a execução da sessão:

codex exec --ephemeral "faça uma triagem deste repositório e sugira os próximos passos"

Se os diretórios pessoais dos workers forem montados pela rede, veja como manter o estado do job no disco local e preservar o registro de execução da sessão.

Se você enviar dados por pipe para stdin e também passar um prompt como argumento, o Codex usará o prompt como instrução e os dados do pipe como contexto adicional.

Assim, você pode gerar a entrada com um comando e enviá-la diretamente ao Codex:

curl -s https://jsonplaceholder.typicode.com/comments \
  | codex exec "organize os primeiros 20 itens em uma tabela Markdown" \
  > table.md

Para conhecer outras formas de usar pipes com stdin, consulte Uso avançado de pipes com stdin.

Permissões e segurança

Por padrão, codex exec é executado em uma sandbox somente leitura. Em automações, conceda apenas as permissões necessárias para o fluxo de trabalho:

• Para permitir edições, use codex exec --sandbox workspace-write "<task>".
• Para permitir acesso mais amplo, use codex exec --sandbox danger-full-access "<task>".

Use danger-full-access apenas em um ambiente controlado, como um runner de CI isolado ou um contêiner isolado.

O Codex deixou de oferecer suporte a --full-auto. Atualize os scripts para usar --sandbox workspace-write ou use --approve-for-me para encaminhar as solicitações de aprovação à revisão automática com a sandbox workspace-write.

Use --ignore-user-config quando precisar executar o Codex sem carregar $CODEX_HOME/config.toml e --ignore-rules quando precisar ignorar os arquivos .rules da política de execução do usuário e do projeto em um ambiente de automação controlado.

Se você configurar um servidor MCP habilitado com required = true e a inicialização desse servidor falhar, codex exec será encerrado com um erro em vez de continuar sem esse servidor.

Gere uma saída que os scripts possam processar

Para processar a saída do Codex em scripts, use o formato JSON Lines:

codex exec --json "resuma a estrutura do repositório" | jq

Quando você habilita --json, stdout passa a transmitir dados no formato JSON Lines (JSONL). Assim, você pode capturar cada evento que o Codex emite durante a execução. Os tipos de evento incluem thread.started, turn.started, turn.completed, turn.failed, item.* e error.

Os tipos de item incluem mensagens do agente, raciocínio, execuções de comandos, alterações em arquivos, chamadas a ferramentas MCP, pesquisas na Web e atualizações do plano.

Exemplo de fluxo JSON (cada linha contém um objeto JSON):

{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Repo contains docs, sdk, and examples directories."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122,"reasoning_output_tokens":0}}

Se precisar apenas da mensagem final, grave-a em um arquivo com -o <path> ou --output-last-message <path>. O Codex grava a mensagem final no arquivo e também a envia para stdout (consulte codex exec para mais detalhes).

Crie saídas estruturadas com um schema

Se precisar de dados estruturados para as próximas etapas, use --output-schema para solicitar uma resposta final que siga um schema definido em JSON Schema. Isso é útil em fluxos de trabalho automatizados que dependem de um conjunto estável de campos, por exemplo, em resumos de jobs, relatórios de risco ou metadados de versão.

schema.json

{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["project_name", "programming_languages"],
  "additionalProperties": false
}

Execute o Codex com o schema e grave a resposta JSON final em disco:

codex exec "Extraia os metadados do projeto" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

Exemplo de saída final (stdout):

{
  "project_name": "Codex CLI",
  "programming_languages": ["Rust", "TypeScript", "Shell"]
}

Autenticação em automações

Por padrão, codex exec reutiliza as credenciais de autenticação salvas pela CLI. Em CI, é comum fornecer as credenciais explicitamente.

Use a autenticação por chave de API

No GitHub Actions, use a GitHub Action do Codex em vez de instalar a CLI e configurar a autenticação por conta própria. Para reduzir a exposição da chave de API, a ação instala o Codex, inicia um proxy para a Responses API e executa o Codex com uma estratégia de segurança configurável.

Não defina OPENAI_API_KEY nem CODEX_API_KEY como variável de ambiente no nível do job em fluxos de trabalho que fazem checkout de código controlado pelo repositório ou executam esse código. Scripts de build, testes, hooks do ciclo de vida das dependências ou uma ação comprometida no mesmo job podem ler essas variáveis de ambiente.

Em outros ambientes de automação, defina CODEX_API_KEY apenas para a execução do Codex que precisa da chave e garanta que somente código confiável seja executado no mesmo ambiente de processo.

Para usar outra chave de API em uma única execução, defina CODEX_API_KEY na mesma linha do comando:

CODEX_API_KEY=<api-key> codex exec --json "faça a triagem dos relatos de bugs em aberto"

Você pode usar CODEX_API_KEY com codex exec, codex review, o SDK para TypeScript e codex exec-server --remote.

Retome uma sessão não interativa

Se precisar continuar uma execução anterior, por exemplo, em um pipeline de duas etapas, use o subcomando resume:

codex exec "revise a alteração em busca de condições de corrida"
codex exec resume --last "corrija as condições de corrida que você encontrou"

Você também pode retomar uma sessão específica pelo ID com codex exec resume <SESSION_ID>.

Repositório Git obrigatório

Para evitar alterações destrutivas, o Codex exige que os comandos sejam executados dentro de um repositório Git. Se tiver certeza de que o ambiente é seguro, use codex exec --skip-git-repo-check para ignorar essa verificação.

Padrões comuns de automação

Exemplo de correção automática de falhas de CI no GitHub Actions

Nos fluxos de trabalho do GitHub Actions, use openai/codex-action em vez de instalar o Codex e passar a chave de API para uma etapa de shell. A ação inicia um proxy seguro para a chave de API da OpenAI.

Você pode usar o Codex para propor correções automaticamente quando um fluxo de CI falhar. Siga estas etapas:

1. Acione um segundo fluxo de trabalho quando o fluxo principal de CI terminar com erro.
2. Faça checkout do commit que apresentou a falha, usando apenas permissão de leitura no repositório.
3. Execute os comandos de preparação antes do Codex, sem expor sua chave de API da OpenAI a essas etapas.
4. Execute a GitHub Action do Codex.
5. Salve as alterações locais do Codex como um artefato de patch.
6. Em um job separado, aplique o patch e abra um pull request.

O job do Codex abaixo tem apenas a permissão contents: read. Após a execução do Codex, o job apenas salva o diff como artefato. O job open_pr recebe permissões de gravação no repositório, mas não recebe OPENAI_API_KEY.

O exemplo pressupõe um projeto Node.js. Ajuste os comandos de preparação e teste às tecnologias do seu projeto.

Para consultar uma lista mais detalhada de verificações de segurança, veja as orientações de segurança da GitHub Action do Codex.

name: Codex auto-fix on CI failure

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  generate_fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      has_patch: ${{ steps.diff.outputs.has_patch }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
          persist-credentials: false

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: |
          if [ -f package-lock.json ]; then npm ci; fi

      - name: Run Codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            O fluxo de CI "${{ github.event.workflow_run.name }}" falhou no commit
            ${{ github.event.workflow_run.head_sha }}.

            Execute `npm test --silent` para reproduzir a falha. Identifique a menor
            alteração necessária para que os testes passem. Implemente apenas essa
            alteração e execute `npm test --silent` novamente.

            Não refatore arquivos que não tenham relação com a falha.

      - name: Create patch artifact
        id: diff
        run: |
          git add -N .
          git diff --binary HEAD > codex.patch
          if [ -s codex.patch ]; then
            echo "has_patch=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_patch=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Upload patch artifact
        if: steps.diff.outputs.has_patch == 'true'
        uses: actions/upload-artifact@v4
        with:
          name: codex-fix-patch
          path: codex.patch
          if-no-files-found: error

  open_pr:
    runs-on: ubuntu-latest
    needs: generate_fix
    if: needs.generate_fix.outputs.has_patch == 'true'
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0

      - uses: actions/download-artifact@v4
        with:
          name: codex-fix-patch

      - name: Apply Codex patch
        run: git apply --index codex.patch

      - name: Open pull request
        env:
          GH_TOKEN: ${{ github.token }}
          FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
          FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
          RUN_ID: ${{ github.event.workflow_run.run_id }}
        run: |
          branch="codex/auto-fix-$RUN_ID"

          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git switch -c "$branch"
          git commit -m "Auto-fix failing CI via Codex"
          git push origin "$branch"

          {
            echo "Codex generated this patch after CI failed for \`$FAILED_HEAD_SHA\`."
            echo
            echo "Review the changes before merging."
          } > pr-body.md

          gh pr create \
            --base "$FAILED_HEAD_BRANCH" \
            --head "$branch" \
            --title "Auto-fix failing CI via Codex" \
            --body-file pr-body.md

Uso avançado de pipes com stdin

Quando outro comando gera a entrada para o Codex, a forma de usar stdin depende da origem da instrução. Combine um prompt com stdin quando já souber qual instrução dar e quiser usar a saída do comando como contexto. Use codex exec - quando stdin contiver o prompt inteiro.

Combine um prompt com stdin

Combinar um prompt com stdin é útil quando outro comando já gera os dados que você quer que o Codex examine. Nesse modo, você escreve a instrução e envia a saída do comando por pipe para fornecer contexto. Isso facilita o uso em fluxos de trabalho da CLI que lidam com saídas de comandos, logs e dados gerados.

npm test 2>&1 \
  | codex exec "resuma os testes que falharam e proponha a menor alteração que provavelmente os fará passar" \
  | tee test-summary.md

tail -n 200 app.log \
  | codex exec "identifique a provável causa raiz, cite os erros mais importantes e sugira os próximos três passos para a depuração" \
  > log-triage.md

curl -vv https://api.example.com/health 2>&1 \
  | codex exec "explique a falha de TLS ou HTTP e sugira a correção com maior probabilidade de resolver o problema" \
  > tls-debug.md

gh run view 123456 --log \
  | codex exec "escreva uma mensagem breve sobre a falha de CI, pronta para enviar no Slack, e inclua a causa provável e o próximo passo" \
  | pbcopy

gh run view 123456 --log \
  | codex exec "resuma a falha em 5 tópicos para a discussão do pull request" \
  | gh pr comment 789 --body-file -

Use codex exec - quando stdin contiver o prompt

Se você omitir o argumento do prompt, o Codex lerá o prompt de stdin. Use codex exec - para exigir esse comportamento de forma explícita.

O argumento especial - é útil quando outro comando ou script gera dinamicamente o prompt inteiro. Ele é indicado quando você armazena prompts em arquivos, monta prompts com scripts de shell ou combina a saída de comandos em tempo real com instruções antes de enviar o prompt completo ao Codex.

cat prompt.txt | codex exec -

printf "Resuma este log de erros em 3 tópicos:\n\n%s\n" "$(tail -n 200 app.log)" \
  | codex exec -

generate_prompt.sh | codex exec - --json > result.jsonl