# Codex 非交互、CI 与 SDK

> codex exec、GitHub Actions、Codex GitHub Action、App Server、Codex SDK、Agents SDK 和自动化密钥的安全用法。

URL: https://docs.passion8.cc/docs/codex/noninteractive-ci-sdk
Language: zh-CN
Publisher: Passion8

Codex 自动化有三条常见路径:

| 路径 | 适合 | 首选入口 |
| --- | --- | --- |
| 一次性脚本 / CI | 运行检查、审查 diff、生成补丁 | `codex exec` |
| GitHub Actions | PR review、CI 失败自动修复、发布检查 | `openai/codex-action@v1` |
| 产品集成 / 内部平台 | 流式事件、线程、审批、深度集成 | Codex SDK 或 app-server |

## codex exec

最小用法:

```bash
codex exec "review the current diff and list only P0/P1 risks"
```

带权限:

```bash
codex exec \
  --sandbox read-only \
  --ask-for-approval never \
  "summarize this repo and identify risky areas"
```

继续会话:

```bash
codex exec "find the likely cause of this failing test"
codex exec resume --last "apply the smallest fix and rerun the test"
```




非交互模式适合可重复任务。把 prompt 写成文件并纳入版本控制,比在 CI YAML 里堆长字符串更容易维护。




## API key 自动化

`CODEX_API_KEY` 只用于 `codex exec`,适合单次自动化:

```bash
CODEX_API_KEY="$OPENAI_API_KEY" \
  codex exec --json "triage open bug reports"
```

不要把 key 暴露给整个 job 的后续步骤。CI 里如果先运行仓库脚本再设置 key,风险更低;如果先把 key 放进环境,依赖安装脚本也可能读到它。

## Passion8 CI

如果 CI 要走 Passion8,用标准 `~/.codex` 文件或临时 `CODEX_HOME`:

```bash
export CODEX_HOME="$PWD/.codex-ci"
mkdir -p "$CODEX_HOME"

cat > "$CODEX_HOME/auth.json" << 'EOF'
{
  "OPENAI_API_KEY": "sk-..."
}
EOF

cat > "$CODEX_HOME/config.toml" << 'EOF'
model_provider = "Passion8"
cli_auth_credentials_store = "file"
forced_login_method = "api"
model = "gpt-6-sol"
approval_policy = "never"
sandbox_mode = "workspace-write"

[model_providers.Passion8]
name = "Passion8"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://passion8.cc/v1"
EOF

codex exec "run the documented checks and summarize failures"
```

CI 里不要把 `.codex-ci/auth.json` 上传为 artifact。

## GitHub Action

OpenAI 官方 Action 会安装 Codex CLI,启动 Responses API proxy,并按配置运行 `codex exec`。适合在 GitHub Actions 里减少手写安装和密钥处理。

```yaml title=".github/workflows/codex-review.yml"
name: Codex review
on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  codex:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
          persist-credentials: false

      - uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: read-only
```

安全建议:

- 限制触发者,避免 fork PR 直接接触 secret
- `checkout` 时不要持久化凭据,除非后续步骤需要写回
- 让 Codex job 只产生 diff 或报告
- 写 PR 的步骤放在单独 job,不要携带模型 API key
- 对 issue、PR body、commit message 做 prompt injection 防护

## 自动修复 CI

推荐模式:

1. 主 CI 失败后触发独立 workflow
2. Checkout 失败 commit
3. 安装依赖但不暴露模型 key
4. 运行 Codex 生成 patch
5. 上传 patch artifact
6. 另一个 job 应用 patch 并开 PR

这样 OpenAI / Passion8 key 不会出现在拥有写权限的 job 环境里。

## App Server

`codex app-server` 适合做产品级集成。它通过 JSON-RPC 风格消息管理 thread、turn、stream events、审批和历史。

```bash
codex app-server
codex app-server --listen ws://127.0.0.1:4500
codex app-server --listen unix://
```

WebSocket transport 适合 localhost 或 SSH tunnel。不要在没有认证的情况下暴露到非 loopback 地址。

## Codex SDK

SDK 适合在后端服务或内部工具里调用 Codex,比 shell 包装 `codex exec` 更容易处理:

- 长会话
- 流式事件
- 结构化输出
- 审批和工具结果
- 多 agent 编排

如果只是 CI 里跑一次 review,用 `codex exec` 或 GitHub Action 更直接。需要产品集成、平台化或复杂 orchestration 时再用 SDK。

## Agents SDK + Codex MCP

Codex 可以作为 MCP server 被其他 agent 调用:

```bash
codex mcp-server
```

典型用途:

- 一个主 agent 做分派,让 Codex 负责代码实现
- 多 agent pipeline 中把 Codex 当作“可审查的代码执行者”
- 用 OpenAI Agents SDK 统一编排 handoff、trace 和 guardrails

保持每个 Codex 子任务范围清晰,并让它在独立工作目录或 worktree 中运行。

## 官方参考

- [Codex manual: Non-interactive mode](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Codex GitHub Action](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Codex SDK](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Codex App Server](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Use Codex with the Agents SDK](https://developers.openai.com/codex/codex-manual.md)