Tài liệu ChatGPT
Tiếng Việt
Liên hệ goolvyouyou@gmail.com

Chế độ không tương tác

Sử dụng codex exec để chạy Codex trong tập lệnh và CI

Chế độ không tương tác cho phép bạn chạy Codex từ các tập lệnh (ví dụ: tác vụ tích hợp liên tục (CI)) mà không cần mở TUI tương tác. Bạn gọi chế độ này bằng codex exec.

Để biết chi tiết về từng cờ, hãy xem codex exec.

Khi nào nên dùng codex exec

Dùng codex exec khi bạn muốn Codex:

  • Chạy như một phần của quy trình (CI, kiểm tra trước khi hợp nhất, tác vụ theo lịch).
  • Tạo đầu ra mà bạn có thể chuyển tiếp đến các công cụ khác (ví dụ: để tạo ghi chú phát hành hoặc bản tóm tắt).
  • Kết hợp tự nhiên vào các quy trình CLI nối đầu ra của lệnh vào Codex và chuyển đầu ra của Codex sang các công cụ khác.
  • Chạy với các thiết lập sandbox và phê duyệt được đặt trước một cách rõ ràng.

Cách dùng cơ bản

Truyền lời nhắc tác vụ dưới dạng một đối số duy nhất:

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

Trong khi codex exec chạy, Codex truyền trực tiếp tiến độ đến stderr và chỉ in thông điệp cuối cùng của tác nhân ra stdout. Nhờ đó, bạn có thể dễ dàng chuyển hướng hoặc chuyển tiếp kết quả cuối cùng:

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

Dùng --ephemeral khi bạn không muốn lưu các tệp rollout của phiên vào đĩa:

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

Nếu stdin được chuyển tiếp và bạn cũng cung cấp một đối số lời nhắc, Codex sẽ coi lời nhắc là hướng dẫn và nội dung được chuyển tiếp là ngữ cảnh bổ sung.

Điều này giúp bạn dễ dàng tạo đầu vào bằng một lệnh và chuyển trực tiếp đầu vào đó cho Codex:

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

Để biết các mẫu chuyển tiếp stdin nâng cao hơn, hãy xem Chuyển tiếp stdin nâng cao.

Quyền và an toàn

Theo mặc định, codex exec chạy trong sandbox chỉ đọc. Trong môi trường tự động hóa, hãy đặt mức quyền tối thiểu cần thiết cho quy trình:

  • Cho phép chỉnh sửa: codex exec --sandbox workspace-write "<task>"
  • Cho phép quyền truy cập rộng hơn: codex exec --sandbox danger-full-access "<task>"

Chỉ dùng danger-full-access trong môi trường được kiểm soát (ví dụ: runner CI hoặc container được cô lập).

Codex giữ codex exec --full-auto dưới dạng cờ tương thích không còn được khuyến nghị và sẽ in cảnh báo. Trong các tập lệnh mới, hãy ưu tiên cờ --sandbox workspace-write rõ ràng.

Dùng --ignore-user-config khi bạn cần một lượt chạy không tải $CODEX_HOME/config.toml và dùng --ignore-rules khi bạn cần bỏ qua các tệp execpolicy .rules của người dùng và dự án trong môi trường tự động hóa được kiểm soát.

Nếu bạn cấu hình một máy chủ MCP đã bật bằng required = true và máy chủ đó không khởi tạo được, codex exec sẽ thoát với lỗi thay vì tiếp tục mà không có máy chủ đó.

Làm cho đầu ra có thể đọc bằng máy

Để sử dụng đầu ra Codex trong tập lệnh, hãy dùng đầu ra JSON Lines:

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

Khi bạn bật --json, stdout trở thành một luồng JSON Lines (JSONL), cho phép bạn thu thập mọi sự kiện Codex phát ra trong khi chạy. Các loại sự kiện bao gồm thread.started, turn.started, turn.completed, turn.failed, item.* và error.

Các loại mục bao gồm thông điệp tác nhân, quá trình suy luận, thực thi lệnh, thay đổi tệp, lần gọi công cụ MCP, tìm kiếm web và cập nhật kế hoạch.

Luồng JSON mẫu (mỗi dòng là một đối tượng 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}}

Nếu chỉ cần thông điệp cuối cùng, hãy ghi nó vào một tệp bằng -o <path>/--output-last-message <path>. Thao tác này ghi thông điệp cuối cùng vào tệp và vẫn in nó ra stdout (xem codex exec để biết chi tiết).

Tạo đầu ra có cấu trúc bằng schema

Nếu cần dữ liệu có cấu trúc cho các bước tiếp theo, hãy dùng --output-schema để yêu cầu phản hồi cuối cùng tuân theo JSON Schema. Điều này hữu ích cho các quy trình tự động cần các trường ổn định (ví dụ: bản tóm tắt tác vụ, báo cáo rủi ro hoặc siêu dữ liệu phát hành).

schema.json

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

Chạy Codex với schema và ghi phản hồi JSON cuối cùng vào đĩa:

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

Ví dụ về đầu ra cuối cùng (stdout):

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

Xác thực trong môi trường tự động hóa

Theo mặc định, codex exec tái sử dụng thông tin xác thực CLI đã lưu. Trong CI, thông tin xác thực thường được cung cấp rõ ràng:

Sử dụng xác thực bằng API key

Đối với GitHub Actions, hãy dùng Codex GitHub Action thay vì tự cài đặt và xác thực CLI. Action này được thiết kế để giảm nguy cơ lộ API key bằng cách cài đặt Codex, khởi động proxy Responses API và chạy Codex với chiến lược an toàn có thể cấu hình.

Không đặt OPENAI_API_KEY hoặc CODEX_API_KEY làm biến môi trường cấp tác vụ trong các quy trình checkout hoặc chạy mã do kho lưu trữ kiểm soát. Các tập lệnh xây dựng, bài kiểm thử, hook vòng đời phần phụ thuộc hoặc một action bị xâm phạm trong cùng tác vụ đều có thể đọc các biến môi trường đó.

Đối với các môi trường tự động hóa khác, chỉ đặt CODEX_API_KEY cho một lần gọi codex exec duy nhất và bảo đảm không có mã không đáng tin cậy nào chạy trong cùng môi trường tiến trình.

Để dùng một API key khác cho một lượt chạy, hãy đặt trực tiếp CODEX_API_KEY:

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

CODEX_API_KEY chỉ được hỗ trợ trong codex exec.

Hãy đọc phần này nếu bạn cần chạy tác vụ CI/CD bằng tài khoản người dùng Codex thay vì API key, chẳng hạn như nhóm doanh nghiệp dùng quyền truy cập Codex do ChatGPT quản lý trên các runner đáng tin cậy hoặc người dùng cần hạn mức ChatGPT/Codex thay vì sử dụng API key.

API key là lựa chọn mặc định phù hợp cho tự động hóa vì dễ cấp phát và xoay vòng hơn. Chỉ dùng phương thức này nếu bạn thực sự cần chạy bằng tài khoản Codex của mình.

Không dùng quy trình này cho kho lưu trữ công khai hoặc mã nguồn mở. Nếu codex login không phải là một tùy chọn trên runner, hãy đưa auth.json vào qua nơi lưu trữ an toàn, chạy Codex trên runner để Codex làm mới tệp tại chỗ và lưu lại tệp đã cập nhật giữa các lượt chạy.

Xem Duy trì xác thực tài khoản Codex trong CI/CD (nâng cao).

Tiếp tục một phiên không tương tác

Nếu cần tiếp tục một lượt chạy trước đó (ví dụ: quy trình hai giai đoạn), hãy dùng lệnh con resume:

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

Bạn cũng có thể nhắm đến một ID phiên cụ thể bằng codex exec resume <SESSION_ID>.

Yêu cầu kho lưu trữ Git

Codex yêu cầu các lệnh phải chạy bên trong một kho lưu trữ Git để ngăn các thay đổi có tính phá hủy. Ghi đè bước kiểm tra này bằng codex exec --skip-git-repo-check nếu bạn chắc chắn môi trường an toàn.

Các mẫu tự động hóa phổ biến

Ví dụ: Tự động sửa lỗi CI trong GitHub Actions

Đối với quy trình GitHub Actions, hãy dùng openai/codex-action thay vì cài đặt Codex và truyền API key cho một bước shell. Action này khởi động một proxy an toàn cho API key OpenAI.

Bạn có thể dùng Codex để tự động đề xuất bản sửa lỗi khi quy trình CI thất bại. Mẫu thực hiện như sau:

  1. Kích hoạt một quy trình tiếp nối khi quy trình CI chính hoàn tất với lỗi.
  2. Checkout commit bị lỗi chỉ với quyền đọc kho lưu trữ.
  3. Chạy các lệnh thiết lập trước Codex mà không để lộ API key OpenAI cho những bước đó.
  4. Chạy Codex GitHub Action.
  5. Lưu các thay đổi cục bộ của Codex dưới dạng sản phẩm bản vá.
  6. Trong một tác vụ riêng, áp dụng bản vá và mở pull request.

Tác vụ Codex bên dưới chỉ có contents: read. Sau khi Codex chạy, tác vụ chỉ tuần tự hóa phần diff dưới dạng sản phẩm. Tác vụ open_pr nhận quyền ghi kho lưu trữ nhưng không nhận OPENAI_API_KEY.

Ví dụ giả định một dự án Node.js. Hãy điều chỉnh các lệnh thiết lập và kiểm thử cho phù hợp với ngăn xếp công nghệ của bạn.

Để xem danh sách kiểm tra bảo mật chuyên sâu hơn, hãy đọc hướng dẫn bảo mật 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

Chuyển tiếp stdin nâng cao

Khi một lệnh khác tạo đầu vào cho Codex, hãy chọn mẫu stdin dựa trên nguồn của hướng dẫn. Dùng lời-nhắc-cộng-stdin khi bạn đã biết hướng dẫn và muốn truyền đầu ra được chuyển tiếp làm ngữ cảnh. Dùng codex exec - khi stdin cần trở thành toàn bộ lời nhắc.

Sử dụng lời-nhắc-cộng-stdin

Lời-nhắc-cộng-stdin hữu ích khi một lệnh khác đã tạo dữ liệu mà bạn muốn Codex kiểm tra. Trong chế độ này, bạn tự viết hướng dẫn và chuyển tiếp đầu ra làm ngữ cảnh, nhờ đó chế độ này phù hợp tự nhiên với các quy trình CLI được xây dựng quanh đầu ra lệnh, nhật ký và dữ liệu đã tạo.

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

Tóm tắt nhật ký

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

Kiểm tra sự cố TLS hoặc HTTP

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

Chuẩn bị bản cập nhật sẵn sàng đăng lên Slack

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

Soạn nhận xét pull request từ nhật ký CI

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

Sử dụng codex exec - khi stdin là lời nhắc

Nếu bạn bỏ qua đối số lời nhắc, Codex sẽ đọc lời nhắc từ stdin. Dùng codex exec - khi bạn muốn buộc Codex thực hiện rõ ràng hành vi đó.

Sentinel - hữu ích khi một lệnh hoặc tập lệnh khác đang tạo động toàn bộ lời nhắc. Cách này phù hợp khi bạn lưu lời nhắc trong tệp, lắp ghép lời nhắc bằng tập lệnh shell hoặc kết hợp đầu ra lệnh trực tiếp với hướng dẫn trước khi chuyển toàn bộ lời nhắc cho 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