Etkileşimsiz mod

Etkileşimsiz mod, etkileşimli TUI'ı açmadan Codex'i betiklerden (örneğin sürekli entegrasyon (CI) işleri) çalıştırmanızı sağlar. Bu modu codex exec ile çağırırsınız.

Bayrak düzeyindeki ayrıntılar için codex exec bölümüne bakın.

codex exec ne zaman kullanılır?

Codex'in şunları yapmasını istediğinizde codex exec kullanın:

• Bir işlem hattının parçası olarak çalışmak (CI, birleştirme öncesi denetimler, zamanlanmış işler).
• Diğer araçlara aktarabileceğiniz çıktılar üretmek (örneğin sürüm notları veya özetler oluşturmak için).
• Komut çıktısını Codex'e bağlayan ve Codex çıktısını başka araçlara ileten CLI iş akışlarına doğal biçimde uyum sağlamak.
• Açıkça önceden ayarlanmış korumalı alan ve onay ayarlarıyla çalışmak.

Temel kullanım

Görev istemini tek bir bağımsız değişken olarak iletin:

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

codex exec çalışırken Codex ilerlemeyi stderr hedefine aktarır ve stdout hedefine yalnızca son ajan mesajını yazdırır. Bu, nihai sonucu yönlendirmeyi veya aktarmayı kolaylaştırır:

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

Oturum rollout dosyalarını diskte kalıcı olarak saklamak istemediğinizde --ephemeral kullanın:

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

stdin aktarılıyorsa ve ayrıca bir istem bağımsız değişkeni sağlarsanız Codex, istemi talimat; aktarılan içeriği ise ek bağlam olarak değerlendirir.

Bu sayede bir komutla girdi oluşturup doğrudan Codex'e vermek kolaylaşır:

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

Daha gelişmiş stdin aktarma kalıpları için Gelişmiş stdin aktarma bölümüne bakın.

İzinler ve güvenlik

codex exec varsayılan olarak salt okunur bir korumalı alanda çalışır. Otomasyonda, iş akışının gerektirdiği en düşük izinleri ayarlayın:

• Düzenlemelere izin verme: codex exec --sandbox workspace-write "<task>"
• Daha geniş erişime izin verme: codex exec --sandbox danger-full-access "<task>"

danger-full-access değerini yalnızca denetimli bir ortamda (örneğin yalıtılmış bir CI çalıştırıcısı veya kapsayıcı) kullanın.

Codex, codex exec --full-auto değerini kullanımdan kaldırılmış bir uyumluluk bayrağı olarak tutar ve bir uyarı yazdırır. Yeni betiklerde açık --sandbox workspace-write bayrağını tercih edin.

$CODEX_HOME/config.toml yüklemeyen bir çalıştırmaya ihtiyacınız olduğunda --ignore-user-config, denetimli bir otomasyon ortamında kullanıcı ve proje execpolicy .rules dosyalarını atlamanız gerektiğinde ise --ignore-rules kullanın.

required = true ile etkinleştirilmiş bir MCP sunucusu yapılandırırsanız ve sunucu başlatılamazsa codex exec, o sunucu olmadan devam etmek yerine bir hatayla sonlanır.

Çıktıyı makine tarafından okunabilir hâle getirme

Codex çıktısını betiklerde kullanmak için JSON Lines çıktısını kullanın:

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

--json özelliğini etkinleştirdiğinizde stdout, Codex'in çalışırken yayımladığı her olayı yakalayabilmeniz için bir JSON Lines (JSONL) akışına dönüşür. Olay türleri arasında thread.started, turn.started, turn.completed, turn.failed, item.* ve error bulunur.

Öğe türleri arasında ajan mesajları, akıl yürütme, komut yürütmeleri, dosya değişiklikleri, MCP aracı çağrıları, web aramaları ve plan güncellemeleri bulunur.

Örnek JSON akışı (her satır bir JSON nesnesidir):

{"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}}

Yalnızca son mesaja ihtiyacınız varsa -o <path>/--output-last-message <path> ile bunu bir dosyaya yazın. Bu işlem son mesajı dosyaya yazar ve ayrıca stdout hedefine yazdırmaya devam eder (ayrıntılar için codex exec bölümüne bakın).

Bir şemayla yapılandırılmış çıktılar oluşturma

Sonraki adımlar için yapılandırılmış verilere ihtiyacınız varsa JSON Schema'ya uyan bir nihai yanıt istemek üzere --output-schema kullanın. Bu, kararlı alanlara ihtiyaç duyan otomatik iş akışlarında (örneğin iş özetleri, risk raporları veya sürüm meta verileri) kullanışlıdır.

schema.json

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

Codex'i şemayla çalıştırın ve nihai JSON yanıtını diske yazın:

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

Örnek nihai çıktı (stdout):

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

Otomasyonda kimlik doğrulama

codex exec varsayılan olarak kaydedilmiş CLI kimlik doğrulamasını yeniden kullanır. CI'da kimlik bilgilerini açıkça sağlamak yaygındır:

API key ile kimlik doğrulama kullanma

GitHub Actions için CLI'ı kendiniz yükleyip kimlik doğrulaması yapmak yerine Codex GitHub Action kullanın. Bu eylem, Codex'i yükleyerek, bir Responses API proxy'si başlatarak ve Codex'i yapılandırılabilir bir güvenlik stratejisiyle çalıştırarak API key'in açığa çıkma riskini azaltmak üzere tasarlanmıştır.

Depo tarafından denetlenen kodu kullanıma alan veya çalıştıran iş akışlarında OPENAI_API_KEY ya da CODEX_API_KEY değerini iş düzeyinde bir ortam değişkeni olarak ayarlamayın. Aynı işteki derleme betikleri, testler, bağımlılık yaşam döngüsü kancaları veya güvenliği ihlal edilmiş bir eylem bu ortam değişkenlerini okuyabilir.

Diğer otomasyon ortamlarında CODEX_API_KEY değerini yalnızca tek bir codex exec çağrısı için ayarlayın ve aynı işlem ortamında güvenilmeyen hiçbir kodun çalışmadığından emin olun.

Tek bir çalıştırmada farklı bir API key kullanmak için CODEX_API_KEY değerini satır içinde ayarlayın:

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

CODEX_API_KEY yalnızca codex exec içinde desteklenir.

Etkileşimsiz bir oturumu sürdürme

Önceki bir çalıştırmayı sürdürmeniz gerekiyorsa (örneğin iki aşamalı bir işlem hattında) resume alt komutunu kullanın:

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

codex exec resume <SESSION_ID> ile belirli bir oturum kimliğini de hedefleyebilirsiniz.

Git deposu gerekli

Codex, yıkıcı değişiklikleri önlemek için komutların bir Git deposu içinde çalıştırılmasını gerektirir. Ortamın güvenli olduğundan eminseniz bu denetimi codex exec --skip-git-repo-check ile geçersiz kılın.

Yaygın otomasyon kalıpları

Örnek: GitHub Actions içindeki CI hatalarını otomatik düzeltme

GitHub Actions iş akışlarında Codex'i yükleyip API key'i bir kabuk adımına iletmek yerine openai/codex-action kullanın. Bu eylem, OpenAI API key için güvenli bir proxy başlatır.

Bir CI iş akışı başarısız olduğunda otomatik olarak düzeltme önermesi için Codex'i kullanabilirsiniz. Kalıp şöyledir:

1. Ana CI iş akışınız bir hatayla tamamlandığında takip iş akışını tetikleyin.
2. Başarısız commit'i yalnızca depo okuma izinleriyle kullanıma alın.
3. OpenAI API key'inizi bu adımlara açmadan kurulum komutlarını Codex'ten önce çalıştırın.
4. Codex GitHub Action'ı çalıştırın.
5. Codex'in yerel değişikliklerini bir yama çıktısı olarak kaydedin.
6. Ayrı bir işte yamayı uygulayın ve bir pull request açın.

Aşağıdaki Codex işi yalnızca contents: read iznine sahiptir. Codex çalıştıktan sonra yalnızca farkı bir çıktı olarak serileştirir. open_pr işi depo yazma izinlerini alır ancak OPENAI_API_KEY değerini almaz.

Örnek bir Node.js projesi varsayar. Kurulum ve test komutlarını teknoloji yığınınıza uyacak şekilde ayarlayın.

Daha kapsamlı bir güvenlik denetim listesi için Codex GitHub Action güvenlik kılavuzuna bakın.

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

Gelişmiş stdin aktarma

Başka bir komut Codex için girdi ürettiğinde, stdin kalıbını talimatın nereden gelmesi gerektiğine göre seçin. Talimatı zaten biliyorsanız ve aktarılan çıktıyı bağlam olarak vermek istiyorsanız istem artı stdin yaklaşımını kullanın. stdin'in istemin tamamına dönüşmesi gerektiğinde codex exec - kullanın.

İstem artı stdin kullanma

İstem artı stdin, başka bir komut Codex'in incelemesini istediğiniz verileri zaten ürettiğinde kullanışlıdır. Bu modda talimatı kendiniz yazar ve çıktıyı bağlam olarak aktarırsınız; böylece komut çıktıları, günlükler ve oluşturulmuş veriler etrafında kurulan CLI iş akışlarına doğal biçimde uyar.

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 -

stdin istem olduğunda codex exec - kullanma

İstem bağımsız değişkenini atlarsanız Codex istemi stdin'den okur. Bu davranışı açıkça zorlamak istediğinizde codex exec - kullanın.

- belirteci, istemin tamamını başka bir komut veya betik dinamik olarak oluşturduğunda kullanışlıdır. İstemleri dosyalarda sakladığınızda, kabuk betikleriyle birleştirdiğinizde veya istemin tamamını Codex'e vermeden önce canlı komut çıktısını talimatlarla birleştirdiğinizde iyi bir seçimdir.

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