明明能自动，偏要手动？

"每次都要打开终端敲一遍，太浪费时间了。"

开始之前

codex exec 是什么？

Codex 的非交互执行模式

当你输入 codex 时，启动的是交互式 REPL（读取-求值-输出循环）。输入 codex exec 则进入一次性执行模式：

# 交互模式
codex
> explain this function

# exec 模式
codex exec "explain this function"

prompt 参数详解

三种传入指令的方式

codex exec "fix the login bug"

cat issue.txt | codex exec -

echo "上下文" | codex exec "总结以下"

--json 结构化输出

让脚本能解析 Codex 的每一步

加上 --json 后，Codex 输出 JSONL（每行一个 JSON 对象）到 stdout，而不是纯文本。事件类型包括 thread.started、turn.started、turn.completed、turn.failed、item.started、item.completed、error。

codex exec --json "list all TODO comments" | while read -r line; do
  echo "$line" | jq -r '.type'
done

# 只提取最终回复（item.type 为 agent_message 的 item.completed）
codex exec --json "fix this" | jq -r \
  'select(.type=="item.completed" \
   and .item.type=="agent_message") \
   | .item.text'

# 或用 --output-last-message 直接写入文件（更简单）
codex exec --output-last-message result.txt "fix this"

-s 沙箱模式

控制代码能触碰什么

--sandbox（短写 -s）决定 Codex 执行中对文件系统和网络的访问权限：

codex exec -s read-only "review this PR"

codex exec -s workspace-write "fix lint errors"

codex exec -s danger-full-access "install deps"

-p profile 与 --cd

控制执行环境与行为

codex exec -p fast "quick review"
codex exec -p thorough "deep audit"

codex exec --cd ./packages/api \
  "refactor this module"

codex exec --full-auto "fix lint errors"

codex exec -o result.txt "summarize"

# 组合示例：在指定目录用快速模式审查
codex exec --cd src/ -p fast -s read-only \
  --json "review security issues"

exec 核心参数速查

交互模式 vs exec 模式

codex mcp-server

让 Codex 成为其他工具的后端

codex mcp-server 是 CLI 独有的子命令：把 Codex 引擎作为 MCP 服务器 暴露出去。其他 MCP 客户端（自定义工具、IDE 插件、Agent 框架）可以通过 标准 stdio 管道 连接到它。

# 直接连接
codex mcp-server | your_mcp_client

# 也可以作为 MCP server 添加到 ~/.codex/config.toml
# 让其他 Codex 实例能调用它

mcp-server 协议细节

JSON-RPC 2.0 —— 轻量、通用、可调试

codex mcp-server 使用标准 MCP 传输协议。消息格式严格遵循 JSON-RPC 2.0 规范，通过 stdio 的一行一个 JSON 进行通信。

// 客户端 → 服务器：列出可用工具
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

// 服务器 → 客户端：工具定义
{ "jsonrpc": "2.0", "id": 1, "result": {
  "tools": [
    { "name": "codex", "description": "Execute a Codex turn" },
    { "name": "codex-reply", "description": "Reply to an existing thread" }
  ]
}}

// 客户端 → 服务器：调用 codex 工具
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "codex",
    "arguments": { "prompt": "fix the bug", "threadId": null }
  }
}

// 服务器 → 客户端：响应
{ "jsonrpc": "2.0", "id": 2,
  "result": { "content": [{"type": "text", "text": "Fixed."}] }
}

mcp-server 暴露的工具

mcp-server 实战演示

用 Python 连接 codex mcp-server

import json, subprocess

proc = subprocess.Popen(
    ["codex", "mcp-server"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True
)

def rpc(method, params=None):
    msg = {"jsonrpc": "2.0", "id": 1, "method": method}
    if params: msg["params"] = params
    proc.stdin.write(json.dumps(msg) + "\n")
    proc.stdin.flush()
    return json.loads(proc.stdout.readline())

# 调用 codex 工具
result = rpc("tools/call", {
    "name": "codex",
    "arguments": {"prompt": "explain recursion in 2 lines"}
})
print(result["result"]["content"])

Python SDK —— openai-codex

用 Python 编排 Codex 工作流

官方 Python SDK 提供同步 API，适合脚本和自动化任务。

pip install openai-codex

from openai_codex import Codex

with Codex() as codex:
    thread = codex.thread_start()
    result = thread.run(
        "Explain this repository in three bullets."
    )
    print(result.final_response)

Python SDK 完整示例

多轮对话 + 读取结果对象

from openai_codex import Codex

with Codex() as codex:
    # 启动线程
    thread = codex.thread_start()

    # 第一轮：让 Codex 分析代码
    r1 = thread.run(
        "Find the top 3 performance bottlenecks in src/"
    )
    print("分析结果:", r1.final_response)
    print("执行项目数:", len(r1.items))

    # 第二轮：基于第一轮结果继续追问
    r2 = thread.run(
        "Rewrite the #1 bottleneck with an optimized version"
    )
    print("修复结果:", r2.final_response)

Python SDK 异步用法

asyncio 并发多个 Codex 任务

import asyncio
from openai_codex import AsyncCodex

async def main():
    async with AsyncCodex() as codex:
        thread = await codex.thread_start()

        # 并发执行多个独立任务
        results = await asyncio.gather(
            thread.run("fix parse.py"),
            thread.run("fix render.py"),
            thread.run("fix route.py"),
        )
        for r in results:
            print(r.final_response[:200])

asyncio.run(main())

Python SDK Sandbox 控制

逐 turn 细粒度权限

Python SDK 允许在 thread_start() 和 run() 级别分别设置沙箱模式：

from openai_codex import Codex, Sandbox

with Codex() as codex:
    # 线程级别：workspace-write
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)

    # 第一轮：正常写操作
    thread.run("Add input validation to the form")

    # 第二轮覆盖为 read-only（只审查）
    review = thread.run(
        "Review the diff only.",
        sandbox=Sandbox.read_only  # 覆盖线程默认
    )
    print(review.final_response)

TypeScript SDK

在 Node.js 中编排 Codex

官方 TypeScript SDK 适合构建 CLI 工具、VS Code 扩展、GitHub Action。

npm install @openai/codex-sdk

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const turn = await thread.run(
  "Diagnose the test failure and propose a fix"
);

console.log(turn.finalResponse);
console.log(turn.items);

const codex = new Codex({
  baseUrl: "https://api.openai.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
});

const codex = new Codex({
  config: {
    sandbox_workspace_write: {
      network_access: true
    }
  }
});

TypeScript resume 与流式

恢复已有线程 + 事件监听

// 恢复已有线程
const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run(
  "Pick up where you left off"
);
console.log(result2.finalResponse);

OSS 本地模型

数据不出本机的 Codex

Codex 支持连接本地运行的 Ollama 或 LM Studio 作为模型后端。所有推理在本地完成，无需 API 调用。

OSS 配置方式

config.toml 与环境变量

在 ~/.codex/config.toml 中声明 OSS provider：

# ~/.codex/config.toml
[model_providers.my-local]
name = "My Local LLM"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

# 指定 provider
model_provider = "my-local"

更简单的方式 —— 用 --oss 标志或 oss_provider 配置：

# 方式 1：命令行标志（默认 Ollama）
codex --oss "fix the build"

# 方式 2：config.toml 指定 OSS provider
# oss_provider = "lmstudio"   # 或 "ollama"

# 方式 3：自定义 provider（非标端口等）
# [model_providers.my-ollama]
# name = "My Ollama"
# base_url = "http://localhost:8080/v1"
# model_provider = "my-ollama"

OSS 模型要求

不是所有模型都适合 Codex

OSS 限制与权衡

实战 1：CI 自动化

用 codex exec + --json 嵌入 GitHub Actions

在 CI 中自动 review PR、生成 changelog、检查安全漏洞：

# .github/workflows/codex-review.yml
name: Codex Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node (for codex CLI)
        uses: actions/setup-node@v4
        with: { node-version: "20" }
      - name: Install Codex CLI
        run: npm install -g @openai/codex
      - name: Codex Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec \
            --cd "$GITHUB_WORKSPACE" \
            -s read-only \
            --json "Review this PR for bugs, security issues, and style problems."
          echo "Review complete."

实战 2：批量处理文件

for loop + codex exec 批处理

给仓库中每个 Python 文件添加类型注解：

#!/bin/bash
# 批量为 Python 文件添加类型注解
for file in $(find src/ -name "*.py"); do
  echo "Processing: $file"
  codex exec \
    --cd "$(dirname $file)" \
    -s workspace-write \
    "Add type annotations to every function. Do not change logic."
  if [ $? -ne 0 ]; then
    echo "ERROR: Failed on $file" >&2
    exit 1
  fi
done
echo "All files processed."

实战 3：Python SDK 自动化工作流

"代码审计 + 修复 + 验证"流水线

from openai_codex import Codex, Sandbox

def audit_and_fix(project_path: str):
    with Codex() as codex:
        thread = codex.thread_start(
            sandbox=Sandbox.workspace_write
        )

        # 1. 安全审计
        audit = thread.run(
            "Scan for SQL injection, XSS, "
            "and hardcoded secrets."
        )
        print(f"Found {len(audit.items)} issue items")

        # 2. 修复
        fix = thread.run(
            "Fix all HIGH severity issues. "
            "Leave MEDIUM and LOW as TODOs."
        )

        # 3. 验证（只读回顾）
        final = thread.run(
            "Re-review: are all HIGH issues resolved?",
            sandbox=Sandbox.read_only
        )
        print("Verification:", final.final_response[:200])

audit_and_fix("./myproject")

实战 4：Ollama 处理敏感任务

内部代码审查，数据零上云

# 终端 1：启动 Ollama（如果未运行）
ollama serve &
ollama pull codellama:13b-instruct

# 终端 2：运行 Codex 连接本地模型
codex --oss \
  --cd ./internal-docs/ \
  -s read-only \
  "Review this data pipeline for compliance risks."

# 或者直接用 --model 覆盖
codex exec --model codellama:13b-instruct \
  -s read-only \
  "Audit this code for PII leaks."

实战 5：mcp-server + Python Agent

把 Codex 嵌入自定义 Agent 框架

#!/usr/bin/env python3
"""一个极简的 Codex-backed Agent"""
import json, subprocess, sys

class CodexAgent:
    def __init__(self):
        self.proc = subprocess.Popen(
            ["codex", "mcp-server"],
            stdin=subprocess.PIPE,
            stdout=subprocess.PIPE,
            text=True
        )
        self._id = 0

    def call(self, name, arguments):
        self._id += 1
        msg = {"jsonrpc": "2.0", "id": self._id,
               "method": "tools/call",
               "params": {"name": name,
                          "arguments": arguments}}
        self.proc.stdin.write(json.dumps(msg) + "\n")
        self.proc.stdin.flush()
        resp = json.loads(self.proc.stdout.readline())
        return resp.get("result", {})

    def run(self, task):
        return self.call("codex", {"prompt": task})

if __name__ == "__main__":
    agent = CodexAgent()
    r = agent.run(sys.argv[1])
    print(r["content"][0]["text"])

实战 5 续：多步 Agent 循环

持续对话直到任务完成

def run_until_done(agent, goal, max_turns=10):
    """让 Codex agent 自主迭代直到任务完成"""
    thread_id = None
    for i in range(max_turns):
        result = agent.call(
            "codex" if not thread_id else "codex-reply",
            {"prompt": goal if not thread_id
                     else "continue from previous step",
             "threadId": thread_id},
        )
        text = result["content"][0]["text"]
        thread_id = result.get("threadId", thread_id)
        print(f"[Turn {i+1}] {text[:300]}")
        if "DONE" in text or "finish" in text:
            break

if __name__ == "__main__":
    agent = CodexAgent()
    run_until_done(agent, "fix all lint issues in src/")

实战选择指南

常见错误（上）

# ❌ 错误：特殊字符被 shell 解析
codex exec "fix bug in src/file (urgent)!"

# ✅ 正确：用引号保护或 stdin
echo "fix bug in src/file (urgent)!" | codex exec -

# ❌ 误解：$? 反映任务结果
codex exec "fix it"
if [ $? -eq 0 ]; then echo "Fixed!"; fi

# ✅ 正确：用 --json + jq 判断
codex exec --json "fix it" | jq -e \
  "select(.type==\"turn.completed\")"

# ❌ 报错：not authenticated

# ✅ 正确：CI 用 OPENAI_API_KEY 替代 login
env:
  OPENAI_API_KEY: \${{ secrets.OPENAI_API_KEY }}
run: codex exec "..."

常见错误（下）

# ❌ 默认端口被占用
# "connection refused on :11434"

# ✅ 正确：在 config.toml 中自定义 provider
# [model_providers.my-ollama]
# base_url = "http://localhost:11435/v1"
# model_provider = "my-ollama"

# ❌ 进程残留
codex = Codex()
thread = codex.thread_start()
# 子进程还在跑

# ✅ 正确：用 context manager
with Codex() as codex:
    thread = codex.thread_start()
    thread.run("...")
# 退出 with 块自动清理

# ❌ 忘记换行符
proc.stdin.write(json.dumps(msg))

# ✅ 正确：每条消息以 \n 结尾
proc.stdin.write(json.dumps(msg) + "\n")
proc.stdin.flush()

Codex 脚本化生态全景

全系列回顾

11 章旅程，从安装到脚本化

你的学习路径

从"会用"到"驾驭"

本章总结