codex-collab

March 6, 2026 · View on GitHub

在 Claude Code 中与 Codex 协作——派发任务、审查代码、并行研究，全程不用离开 Claude 会话。

demo

codex-collab 是一个 Claude Code 技能，借助 Codex app server 的 JSON-RPC 协议驱动 Codex——从会话的维护、结构化事件的实时推送，到工具调用的审批管控与对话恢复，全部在 Claude 会话内闭环完成。

核心优势

结构化通信 — 与 Codex 之间通过 stdio JSON-RPC 通信，每个事件都有完整的类型定义，可解析、可追踪。
实时进度反馈 — Codex 工作时实时推送进度，Claude 随时掌握运行状态。
一键代码审查 — 一条命令即可在只读沙箱中审查 PR、未提交更改或特定 commit。
会话复用 — 接续先前的会话继续对话，在既有上下文基础上推进，不必从头开始。
审批控制 — 按需配置工具调用的审批策略：自动批准、交互确认或拒绝。

安装

需要 Bun >= 1.0 和 Codex CLI（npm install -g @openai/codex）并加入 PATH。已在 Linux (Ubuntu 22.04)、macOS 与 Windows 10 上测试通过。

git clone https://github.com/Kevin7Qi/codex-collab.git
cd codex-collab

Linux / macOS

./install.sh

Windows

powershell -ExecutionPolicy Bypass -File install.ps1

安装完成后，重新打开终端以使 PATH 生效，然后运行 codex-collab health 验证安装。

安装脚本会自动构建独立 bundle，部署到主目录下（Linux/macOS 为 ~/.claude/skills/codex-collab/，Windows 为 %USERPROFILE%\.claude\skills\codex-collab\），并添加可执行文件到 PATH。完成后 Claude 即可自动发现该技能。

开发模式

使用 --dev 以符号链接方式安装，源码变更实时生效：

# Linux / macOS
./install.sh --dev

# Windows（可能需要启用开发者模式或使用管理员终端以创建符号链接）
powershell -ExecutionPolicy Bypass -File install.ps1 -Dev

快速开始

# 向 Codex 提问
codex-collab run "这个项目是做什么的？" -s read-only --content-only

# 代码审查
codex-collab review --content-only

# 恢复会话继续对话
codex-collab run --resume <id> "现在检查错误处理" --content-only

CLI 命令

命令	说明
`run "prompt" [opts]`	新建会话、发送提示、等待完成并输出结果
`review [opts]`	代码审查（PR、未提交更改、指定 commit）
`jobs [--json] [--all]`	列出会话（`--limit <n>` 限制数量）
`kill <id>`	中断运行中的会话
`output <id>`	查看会话完整日志
`progress <id>`	查看近期活动（日志尾部）
`models`	列出可用模型
`health`	检查依赖项

会话管理

命令	说明
`delete <id>`	归档会话，删除本地文件
`clean`	清理过期日志和失效映射
`approve <id>`	批准待处理的请求
`decline <id>`	拒绝待处理的请求

选项

参数	说明
`-d, --dir <path>`	工作目录
`-m, --model <model>`	模型名称（默认: 自动选择最新可用模型）
`-r, --reasoning <level>`	low, medium, high, xhigh（默认: 自动选择模型支持的最高级别）
`-s, --sandbox <mode>`	read-only, workspace-write, danger-full-access（默认: workspace-write；review 始终使用 read-only）
`--mode <mode>`	审查模式: pr, uncommitted, commit, custom
`--ref <hash>`	指定 commit 哈希（配合 `--mode commit`）
`--resume <id>`	恢复已有会话
`--approval <policy>`	审批策略: never, on-request, on-failure, untrusted（默认: never）
`--content-only`	隐藏进度输出；配合 `output` 时仅返回正文内容
`--timeout <sec>`	单轮超时时间，单位秒（默认: 1200）
`--base <branch>`	PR 审查的基准分支（默认: main）

默认值与配置

默认情况下，codex-collab 自动选择最新模型（优先选择 -codex 变体）及该模型支持的最高推理级别。无需配置——新模型发布后自动更新。

使用 codex-collab config 持久化覆盖默认值：

codex-collab config                     # 查看当前配置
codex-collab config model gpt-5.3-codex # 设置默认模型
codex-collab config reasoning high      # 设置默认推理级别
codex-collab config model --unset       # 取消单个设置（恢复自动检测）
codex-collab config --unset             # 取消所有设置

可配置项: model、reasoning、sandbox、approval、timeout

优先级: CLI 参数 > 配置文件 > 自动检测

配置存储于 ~/.codex-collab/config.json。

参与贡献

欢迎贡献！开发环境搭建及贡献流程详见 CONTRIBUTING.md。本项目遵循 Contributor Covenant 行为准则。