# codex-cli

**Repository Path**: ppnt/codex-cli

## Basic Information

- **Project Name**: codex-cli
- **Description**: 一个skill,把**本机已安装的 Codex CLI** 变成可复用的 agent skill：让 AI 编码代理把一项工作交给另一个模型——既能**取独立第二意见**，也能**让它真的动手改文件、跑命令**——而且**执行过程默认看得见**。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-03
- **Last Updated**: 2026-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# codex-cli

把**本机已安装的 Codex CLI** 变成可复用的 agent skill：让 AI 编码代理把一项工作交给另一个模型——既能**取独立第二意见**，也能**让它真的动手改文件、跑命令**——而且**执行过程默认看得见**。

## 它解决什么问题

代理自己得出的结论无法自证，自己写的代码也难自审。这个 skill 把"交给另一个模型"变成可重复、可观察的动作，并顺手挡掉实际调用时的几类坑：

- **过程不可见**：默认的调用方式只关心最后一段回答，中间它到底跑没跑命令、跑了什么，全被丢掉。本仓库的 `-Trace` 把 `exec` 段落（真实命令 + 工作目录 + 输出）实时放出来。
- **只能看不能动**：非交互调用默认只读，需要它改代码时得自己拼沙箱与可写目录参数。
- **Windows 上 `codex.ps1` 被执行策略拒绝**，但 `codex.cmd` / `codex.exe` 可用 —— 脚本自动解析可用入口。
- **进度日志走 stderr，会让调用方退出码假性变成 1** —— 脚本区分真实退出码。
- **最终回答同时也会打到 stdout** —— 脚本只保留一份，避免答案重复。
- **含非 ASCII 字符的 `.ps1` 在 Windows PowerShell 5.1 上必须带 UTF-8 BOM**，否则报出完全看不出原因的语法错误 —— 本仓库脚本已按此落盘。

## 功能

| 能力 | 开关 | 说明 |
| --- | --- | --- |
| 第二意见 / 评审 | 默认（`read-only`） | 只读分析，用于交叉验证与独立复核 |
| 执行任务 | `-Sandbox workspace-write` | 在指定目录内改文件、跑命令 |
| 看执行过程 | `-Trace` | 实时显示 codex 的 `codex` / `exec` 段落、命令输出与 token 消耗 |
| 机器可读过程 | `-Json` | stdout 输出 JSONL 事件流 |
| 额外可写目录 | `-AddDir` | 可重复，配合写模式使用 |
| 推理摘要 | `-Summary` | `auto` / `concise` / `detailed` / `none`，是否可见取决于模型 |

## 目录结构

```
codex-cli/
├── SKILL.md                      # skill 正文：用法、过程可见性、任务模式、实测坑位
├── README.md                     # 本文件
└── scripts/
    ├── Invoke-Codex.ps1          # 包装脚本：解析入口 + 沙箱 + 过程/静默/JSON 三种输出
    └── Invoke-Codex.cmd          # Windows 便捷入口（自带 -ExecutionPolicy Bypass）
```

`SKILL.md` 采用带 YAML frontmatter（`name` + `description`）的通用 skill 约定，可被支持该约定的 agent harness 直接发现；也可当普通文档阅读。

## 安装

把整个 `codex-cli` 目录放进 harness 扫描的任一 skill 根目录即可（目录名即 skill 名）：

| 范围 | 路径 |
| --- | --- |
| 项目级 | `<项目根>/.dsh/skills/codex-cli` |
| 项目级（agents 约定） | `<项目根>/.agents/skills/codex-cli` |
| 用户级 | `~/.dsh/skills/codex-cli` |
| 用户级（agents 约定） | `~/.agents/skills/codex-cli` |

```bash
git clone <this-repo> ~/.dsh/skills/codex-cli
```

发现通常无需重启：写入后下一次会话目录刷新即可见。

## 前置条件

- 本机已安装 codex CLI 并完成登录：

  ```bash
  codex --version
  codex login status
  ```

- 模型与推理强度**不需要**在此配置：省略时自动继承 `$CODEX_HOME/config.toml`（`CODEX_HOME` 默认 `~/.codex`）中的 `model` 与 `model_reasoning_effort`。需要覆盖时用 `-Model` / `-Effort`。

## 用法

```powershell
# 取第二意见（只读，静默：只输出最终回答）
powershell -NoProfile -ExecutionPolicy Bypass -File <skill-dir>\scripts\Invoke-Codex.ps1 `
    -Prompt '这个模块的并发安全吗？' -Repo .

# 看它怎么做的
powershell -NoProfile -ExecutionPolicy Bypass -File <skill-dir>\scripts\Invoke-Codex.ps1 `
    -Prompt '列出仓库里所有 TODO 并归类' -Repo . -Trace

# 让它真的动手（先提交或 stash，收工看 git diff）
powershell -NoProfile -ExecutionPolicy Bypass -File <skill-dir>\scripts\Invoke-Codex.ps1 `
    -Prompt '给 utils.ps1 补上 -WhatIf 支持，并跑通现有测试' -Repo . `
    -Sandbox workspace-write -Trace

# 长任务写在 UTF-8 文件里，回答落盘
powershell -NoProfile -ExecutionPolicy Bypass -File <skill-dir>\scripts\Invoke-Codex.ps1 `
    -PromptFile .\task.md -Repo . -Out .\answer.md
```

PowerShell 7 / 跨平台把 `powershell -NoProfile -ExecutionPolicy Bypass -File <skill-dir>\scripts\Invoke-Codex.ps1` 换成 `pwsh -NoProfile -File <skill-dir>/scripts/Invoke-Codex.ps1`。

Windows 便捷入口：

```powershell
& '<skill-dir>\scripts\Invoke-Codex.cmd' -PromptFile .\task.md -Repo .
```

> `.cmd` 经 `cmd.exe` 会按控制台代码页转换参数，**含中文的提示词请用 `-PromptFile`**。

### 参数

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| `-Prompt` | — | 问题或任务正文，位置参数 |
| `-PromptFile` | — | 从 UTF-8 文件读取，与 `-Prompt` 二选一 |
| `-Repo` | 当前目录 | codex 的工作根目录，决定它能读到哪个仓库 |
| `-Sandbox` | `read-only` | `read-only` / `workspace-write` / `danger-full-access` |
| `-AddDir` | — | 额外授予写权限的目录，可重复 |
| `-Trace` | 关 | 实时显示执行过程，结束后单独打印最终回答 |
| `-Json` | 关 | stdout 输出 JSONL 事件流 |
| `-Model` | 继承 codex 配置 | 省略时不传 `--model` |
| `-Effort` | 继承 codex 配置 | 省略时不覆盖，例如 `medium` / `high` |
| `-Summary` | `-Trace` 时为 `auto` | 推理摘要：`auto` / `concise` / `detailed` / `none` |
| `-Out` | 临时文件 | 最终回答落盘路径 |
| `-CodexPath` | 自动解析 | 显式指定 codex 可执行文件 |

## 看执行过程

`-Trace` 实时打印 codex 自己的过程流：

```
sandbox: read-only
reasoning effort: medium
reasoning summaries: auto
--------
user
用一个命令列出当前目录下的文件，然后回复：完成
codex
我会列出当前目录下的文件。

exec
"powershell.exe" -Command 'Get-ChildItem -File' in <repo>
 succeeded in 134ms:
README.md
SKILL.md

codex
完成
tokens used
822
```

- `codex` 段落 = 模型对外的说明（它打算做什么）；
- `exec` 段落 = **它实际执行的命令、工作目录、耗时与输出** —— 核对"有没有真干活"就看这里；
- 结束后另打 `===== 最终回答 =====` 与纯文本答案，便于从过程流里摘结论。

需要程序化处理时用 `-Json`，stdout 是 JSONL：`thread.started`、`turn.started`、`item.started|completed`（`command_execution` / `agent_message` / `file_change`）、`turn.completed`。

**关于"思考过程"**：codex 只提供"推理摘要"这一个通道，且必须模型支持。合法取值 `auto` / `concise` / `detailed` / `none`，设置后 header 会显示 `reasoning summaries: <值>`。但实测在默认模型上即使 `-Summary detailed -Effort high`，输出里也没有任何思考内容（非 JSON 无思考段落，`--json` 无 `reasoning` 事件）。所以本 skill 的定位是**过程可见**：你能看到它做了什么，通常看不到它怎么想的；换用支持摘要的模型时该开关即可生效。

## 任务模式与安全

非交互 `exec` **不会弹审批**（header 固定 `approval: never`），**沙箱就是唯一边界**：

1. 必须显式 `-Sandbox workspace-write`，默认 `read-only` 下写操作会失败；
2. 可写范围是 `-Repo` 加上 `-AddDir` 追加的目录；
3. **开工前提交或 `git stash`，收工后 `git diff` 审阅**；非 git 目录没有这个安全网；
4. `danger-full-access` 跳过全部沙箱限制，只在外部已隔离的环境里用；
5. 提示词写清**交付物与验收标准**（改哪个文件、跑到什么状态算完成），比只描述意图靠谱得多；
6. 验收依据是 `git diff` 和你自己跑过的测试，不是它自称"完成"。

## 工作原理

`Invoke-Codex.ps1` 依次做四件事：

1. **解析入口**：`-CodexPath` → PATH 上的 `codex.exe` → npm 布局下的 `node + codex.js`（由 `codex.cmd` 位置推导）→ `codex.cmd` → 非 Windows 的 `codex`。刻意跳过 `codex.ps1`，因为它在受限执行策略下必然失败。
2. **组装调用**：`codex exec` + `--cd/-Repo` + `--sandbox` + `--add-dir` + `--skip-git-repo-check` + `--color never` + `--output-last-message`；`-Model` / `-Effort` / `-Summary` 只在显式给出（或 `-Trace` 默认开摘要）时才追加。
3. **执行**：期间临时把 `$ErrorActionPreference` 设为 `Continue`（否则原生命令写 stderr 会抛终止性错误）。静默模式把 stdout/stderr 重定向到临时文件；`-Trace` / `-Json` 则直接流式输出。
4. **取结果**：从 `--output-last-message` 的文件读最终回答；静默模式打印它，`-Trace` 加分隔标题，`-Json` 不打印（避免破坏 JSONL）。返回真实退出码。

## 已实测环境

- Windows 11 + Windows PowerShell 5.1（执行策略 `Restricted`，机器上无 `pwsh`）
- codex-cli 0.159.2（npm 入口）与 0.160.0（桌面版自带 `codex.exe`）
- 已实测通过：`.cmd` 入口、`.ps1` + 中文提示词、`-Trace` 过程输出、`-Json` 事件流、`-Sandbox workspace-write` 下真实创建文件、`-AddDir` 追加可写目录、`-Summary` 取值校验（非法值由 codex 直接报错并列出枚举）、静默模式回归

PowerShell 7 / Linux / macOS 的路径分支按同一逻辑编写，但未逐项实测；若你在这类环境上遇到问题，欢迎提 issue 或 PR。

## 已知限制

- 依赖本机已安装并登录的 codex CLI，本仓库不负责安装或鉴权。
- 默认只读；写模式的安全边界完全由沙箱承担，没有交互式审批兜底。
- **内部推理内容能否看到取决于模型**，当前实测的默认模型不输出推理摘要。
- 包装脚本面向 PowerShell；其他 shell 可直接参考 `SKILL.md` 里的裸命令自行封装。
- 不含 `resume` / `review` 等子命令的封装，只做单轮问答或单轮任务。

## 贡献

欢迎 issue 与 PR。若你补上其他平台（PowerShell 7 / bash / zsh）的实测结果或等价包装脚本，请一并附上验证环境的版本信息。

## 许可

尚未添加 `LICENSE` 文件；正式开源前请先选定一个（MIT 或 Apache-2.0 是常见选择）并补充版权声明。