Modo não interativo

O modo não interativo permite executar o Codex a partir de scripts (por exemplo, tarefas de integração contínua (CI)) sem abrir a TUI interativa. Invoque-o com codex exec.

Para obter detalhes sobre os sinalizadores, consulte codex exec.

Quando utilizar codex exec

Utilize codex exec quando pretender que o Codex:

• Seja executado como parte de um pipeline (CI, verificações anteriores à integração, tarefas agendadas).
• Produza resultados que possa encaminhar para outras ferramentas (por exemplo, para gerar notas de versão ou resumos).
• Se integre naturalmente em fluxos de trabalho de CLI que encadeiam a saída de comandos para o Codex e transmitem a saída do Codex a outras ferramentas.
• Seja executado com definições explícitas e predefinidas de sandbox e aprovação.

Utilização básica

Forneça um pedido de tarefa como argumento único:

codex exec "summarize the repository structure and list the top 5 risky areas"

Durante a execução de codex exec, o Codex transmite o progresso para stderr e imprime apenas a mensagem final do agente em stdout. Isto facilita o redirecionamento ou encaminhamento do resultado final:

codex exec "generate release notes for the last 10 commits" | tee release-notes.md

Utilize --ephemeral quando não pretender guardar ficheiros de rollout da sessão no disco:

codex exec --ephemeral "triage this repository and suggest next steps"

Se stdin for encaminhado e também fornecer um argumento de pedido, o Codex trata o pedido como a instrução e o conteúdo encaminhado como contexto adicional.

Isto permite gerar facilmente dados de entrada com um comando e fornecê-los diretamente ao Codex:

curl -s https://jsonplaceholder.typicode.com/comments \
  | codex exec "format the top 20 items into a markdown table" \
  > table.md

Para obter padrões mais avançados de encaminhamento de stdin, consulte Encaminhamento avançado de stdin.

Permissões e segurança

Por predefinição, codex exec é executado numa sandbox só de leitura. Em automatizações, defina apenas as permissões mínimas necessárias para o fluxo de trabalho:

• Permitir edições: codex exec --sandbox workspace-write "<task>"
• Permitir um acesso mais abrangente: codex exec --sandbox danger-full-access "<task>"

Utilize danger-full-access apenas num ambiente controlado (por exemplo, um executor de CI isolado ou um contentor).

O Codex mantém codex exec --full-auto como sinalizador de compatibilidade obsoleto e apresenta um aviso. Prefira o sinalizador explícito --sandbox workspace-write em scripts novos.

Utilize --ignore-user-config quando precisar de uma execução que não carregue $CODEX_HOME/config.toml, e --ignore-rules quando precisar de ignorar ficheiros execpolicy .rules do utilizador e do projeto num ambiente de automatização controlado.

Se configurar um servidor MCP ativado com required = true e este não conseguir inicializar, codex exec termina com um erro em vez de continuar sem esse servidor.

Tornar a saída legível por máquinas

Para processar a saída do Codex em scripts, utilize a saída JSON Lines:

codex exec --json "summarize the repo structure" | jq

Quando ativa --json, stdout torna-se um fluxo JSON Lines (JSONL), permitindo capturar todos os eventos emitidos pelo Codex 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 de ficheiros, chamadas de ferramentas MCP, pesquisas na Web e atualizações do plano.

Exemplo de fluxo JSON (cada linha é 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 apenas precisar da mensagem final, escreva-a num ficheiro com -o <path>/--output-last-message <path>. Isto escreve a mensagem final no ficheiro e continua a imprimi-la em stdout (consulte codex exec para obter detalhes).

Criar resultados estruturados com um esquema

Se precisar de dados estruturados para etapas subsequentes, utilize --output-schema para solicitar uma resposta final que esteja em conformidade com um JSON Schema. Isto é útil para fluxos de trabalho automatizados que requerem campos estáveis (por exemplo, resumos de tarefas, relatórios de riscos ou metadados de versões).

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 esquema e escreva a resposta JSON final no disco:

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

Exemplo de resultado final (stdout):

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

Autenticação em automatizações

codex exec reutiliza, por predefinição, a autenticação guardada da CLI. Em CI, é comum fornecer explicitamente as credenciais:

Utilizar autenticação com API key

Para GitHub Actions, utilize a Codex GitHub Action em vez de instalar e autenticar manualmente a CLI. A ação foi concebida para reduzir a exposição da API key ao instalar o Codex, iniciar um proxy da Responses API e executar 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 ao nível da tarefa em fluxos de trabalho que obtenham ou executem código controlado pelo repositório. Scripts de compilação, testes, hooks do ciclo de vida de dependências ou uma ação comprometida na mesma tarefa podem ler essas variáveis de ambiente.

Noutros ambientes de automatização, defina CODEX_API_KEY apenas para a invocação individual de codex exec e certifique-se de que não é executado código não fidedigno no mesmo ambiente de processo.

Para utilizar uma API key diferente numa única execução, defina CODEX_API_KEY na própria linha:

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

CODEX_API_KEY apenas é suportado em codex exec.

Retomar uma sessão não interativa

Se precisar de continuar uma execução anterior (por exemplo, num pipeline de duas fases), utilize o subcomando resume:

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

Também pode especificar um ID de sessão com codex exec resume <SESSION_ID>.

Repositório Git obrigatório

O Codex exige que os comandos sejam executados dentro de um repositório Git para evitar alterações destrutivas. Substitua esta verificação com codex exec --skip-git-repo-check se tiver a certeza de que o ambiente é seguro.

Padrões comuns de automatização

Exemplo: corrigir automaticamente falhas de CI no GitHub Actions

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

Pode utilizar o Codex para propor automaticamente correções quando um fluxo de trabalho de CI falha. O padrão é o seguinte:

1. Acione um fluxo de trabalho subsequente quando o fluxo de trabalho de CI principal terminar com um erro.
2. Obtenha o commit com falhas apenas com permissões de leitura do repositório.
3. Execute os comandos de configuração antes do Codex, sem expor a sua API key da OpenAI a essas etapas.
4. Execute a Codex GitHub Action.
5. Guarde as alterações locais do Codex como um artefacto de patch.
6. Numa tarefa separada, aplique o patch e abra um pull request.

A tarefa do Codex abaixo tem apenas contents: read. Após a execução do Codex, apenas serializa o diff como artefacto. A tarefa open_pr recebe permissões de escrita no repositório, mas não recebe OPENAI_API_KEY.

O exemplo pressupõe um projeto Node.js. Ajuste os comandos de configuração e teste à sua stack.

Para obter uma lista de verificação de segurança mais aprofundada, consulte as orientações de segurança da Codex GitHub Action.

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: |
            The CI workflow "${{ github.event.workflow_run.name }}" failed for commit
            ${{ github.event.workflow_run.head_sha }}.

            Run `npm test --silent` to reproduce the failure. Identify the minimal
            change needed to make the tests pass, implement only that change, and
            run `npm test --silent` again.

            Do not refactor unrelated files.

      - 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

Encaminhamento avançado de stdin

Quando outro comando produz dados de entrada para o Codex, escolha o padrão de stdin com base na origem pretendida da instrução. Utilize pedido mais stdin quando já souber qual é a instrução e pretender fornecer a saída encaminhada como contexto. Utilize codex exec - quando stdin tiver de se tornar o pedido completo.

Utilizar pedido mais stdin

O padrão pedido mais stdin é útil quando outro comando já produz os dados que pretende que o Codex inspecione. Neste modo, escreve a instrução e encaminha a saída como contexto, o que o torna uma opção natural para fluxos de trabalho de CLI baseados em saídas de comandos, registos e dados gerados.

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix" \
  | tee test-summary.md

tail -n 200 app.log \
  | codex exec "identify the likely root cause, cite the most important errors, and suggest the next three debugging steps" \
  > log-triage.md

curl -vv https://api.example.com/health 2>&1 \
  | codex exec "explain the TLS or HTTP failure and suggest the most likely fix" \
  > tls-debug.md

gh run view 123456 --log \
  | codex exec "write a concise Slack-ready update on the CI failure, including the likely cause and next step" \
  | pbcopy

gh run view 123456 --log \
  | codex exec "summarize the failure in 5 bullets for the pull request thread" \
  | gh pr comment 789 --body-file -

Utilizar codex exec - quando stdin é o pedido

Se omitir o argumento de pedido, o Codex lê o pedido de stdin. Utilize codex exec - quando pretender forçar explicitamente esse comportamento.

O sentinela - é útil quando outro comando ou script gera dinamicamente o pedido completo. É uma boa opção quando guarda pedidos em ficheiros, compõe pedidos com scripts da shell ou combina a saída de comandos em tempo real com instruções antes de fornecer o pedido completo ao Codex.

cat prompt.txt | codex exec -

printf "Summarize this error log in 3 bullets:\n\n%s\n" "$(tail -n 200 app.log)" \
  | codex exec -

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