Codex GitHub Action

使用 Codex GitHub Action（openai/codex-action@v1）可以在 GitHub Actions 工作流程中執行 Codex、應用補丁，或從工作流程中釋出審查結果。這個 action 會安裝 Codex CLI，在你提供 API key 時啟動 Responses API 代理，並按你指定的權限執行 codex exec。

當你需要下面這些能力時，優先使用這個 action：

在不自行管理 CLI 的前提下，為 pull request 或 release 自動執行 Codex 回饋
將由 Codex 驅動的質量檢查納入 CI 流水線的准入條件
通過工作流程檔案執行可重複的 Codex 任務，例如程式碼審查、釋出準備或遷移

有關完整的 CI 範例，可結合非互動模式閱讀，也可以直接檢視 openai/codex-action 儲存庫。

前提條件

使用前請準備好：

將 OpenAI API key 儲存為 GitHub Secret，例如 OPENAI_API_KEY，並在工作流程中引用它
在 Linux 或 macOS 執行器上執行任務；如果必須在 Windows 上執行，需要顯式設定 safety-strategy: unsafe
在執行 action 之前先檢出程式碼，讓 Codex 能讀取儲存庫內容
預先確定提示詞來源。你可以用 prompt 傳內聯文本，也可以用 prompt-file 指向儲存庫中已提交的檔案

範例工作流程

下面的範例會在新的 pull request 開啟或更新時觸發 Codex 審查，捕獲 Codex 的回覆，並把結果回貼到 PR：

name: Codex pull request review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge
          fetch-depth: 0
          persist-credentials: false

      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          output-file: codex-output.md

  post_feedback:
    runs-on: ubuntu-latest
    needs: codex
    if: needs.codex.outputs.final_message != ''
    permissions:
      issues: write
      pull-requests: write
    steps:
      - name: Post Codex feedback
        uses: actions/github-script@v7
        with:
          github-token: ${{ github.token }}
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: process.env.CODEX_FINAL_MESSAGE,
            });
        env:
          CODEX_FINAL_MESSAGE: ${{ needs.codex.outputs.final_message }}

將 .github/codex/prompts/review.md 換成你自己的提示詞檔案即可；如果你更喜歡內聯文本，也可以直接使用 prompt。這個範例還會把 Codex 的最終訊息寫入 codex-output.md，方便後續檢查或上傳為建置產物。

設定 `codex exec`

這個 action 的很多輸入項都直接對映到 codex exec：

prompt 或 prompt-file：二選一。可以傳內聯任務說明，或者引用儲存庫中的 Markdown / 文本路徑；常見做法是把提示詞放在 .github/codex/prompts/
codex-args：附加 CLI 參數，可以傳 JSON 陣列（例如 ["--ephemeral"]），也可以傳 shell 風格字串（例如 --profile ci），用於設定會話、設定檔或 MCP 設定
model 和 effort：控制本次執行的 Codex 智能體設定；留空則使用預設值
sandbox：把 workspace-write、read-only、danger-full-access 這類沙箱模式和任務所需權限對齊
output-file：把最終訊息寫入磁碟，方便後續上傳建置產物或比較差異
codex-version：固定某個 CLI 版本；留空則使用最新發布版本
codex-home：如果你要在多個步驟間複用設定檔或 MCP 設定，可以指定共享的 Codex 主目錄

管理權限

在 GitHub 託管執行器上，Codex 預設能接觸到的環境很廣，所以你應顯式收緊權限。常見控制項包括：

safety-strategy：預設是 drop-sudo，會在執行 Codex 前移除 sudo。這是對整個作業不可逆的操作，適合用來保護記憶體中的敏感資訊。在 Windows 上必須改為 unsafe
unprivileged-user：需要與 safety-strategy: unprivileged-user 和 codex-user 搭配使用，讓 Codex 以指定賬號執行。要確保該使用者對儲存庫檢出目錄具有讀寫權限；必要時可參考 unprivileged-user 範例中的 ownership 修復方式
read-only：阻止 Codex 修改檔案或使用網路，但它仍然可能以高權限身份執行，所以不要只靠這一項來保護敏感資訊
sandbox：限制 Codex 自身的檔案系統與網路存取範圍，應選擇能完成任務的最小權限
allow-users 與 allow-bots：限制哪些使用者或機器人可以觸發該工作流程。預設只有擁有寫權限的使用者能執行這個 action；如果需要放行額外的受信任賬號，請顯式列出，留空則保持預設行為

捕獲輸出

這個 action 會通過 final-message 輸出 Codex 的最後一條訊息。你可以像上面的範例一樣把它對映成作業輸出，或者在後續步驟裡直接使用。

如果你還想收集執行器上的完整輸出，可以把 output-file 與建置產物上傳一起使用；如果你需要結構化資料，則可以通過 codex-args 傳入 --output-schema，強制最終結果滿足指定 JSON 結構。

安全檢查清單

在把 Codex 接入 GitHub Actions 前，至少確認以下幾點：

限制能夠觸發工作流程的物件。優先使用受信任事件或顯式審批，不要讓所有人都能對儲存庫執行 Codex
清洗來自 PR、commit message 或 issue body 的提示詞輸入，避擴音示詞注入。尤其要留意 HTML 註釋或隱藏文本
用 drop-sudo 或 unprivileged-user 保護 OPENAI_API_KEY；在多租戶執行器上不要讓 action 停留在 unsafe 模式
儘量把 Codex 放在作業的最後一步，避免後續步驟繼承意外狀態
如果懷疑代理日誌或 action 輸出暴露了敏感資訊，立即輪換金鑰

故障排查

同時設定了 prompt 和 prompt-file：二者只能二選一
responses-api-proxy 沒有寫出服務端資訊：確認 API key 存在且有效；只有在提供 openai-api-key 時代理才會啟動
預期移除了 sudo，但 sudo 仍然成功：確認沒有更早的步驟恢復 sudo，並確認執行器是 Linux 或 macOS；必要時用全新 job 重跑
drop-sudo 後出現權限錯誤：可以在 action 執行前給工作目錄補足寫權限，例如執行 chmod -R g+rwX "$GITHUB_WORKSPACE"，或者改用 unprivileged-user 模式
觸發者未被允許，工作流程被阻止：如果你需要放行預設寫權限協作者之外的服務賬號，請檢查 allow-users 和 allow-bots

來源：</zh-TW/docs/github-action> 更新時間：2026-07-10（UTC）

最近搜尋

建議搜尋

文件導覽

前提條件

範例工作流程

設定 `codex exec`

管理權限

捕獲輸出

安全檢查清單

故障排查

前提條件

範例工作流程

設定 codex exec

管理權限

捕獲輸出

安全檢查清單

故障排查

設定 `codex exec`