正文内容
codex-runner 技能
描述
使用 Codex CLI 在后台长时间运行编码任务，不受 OpenClaw 会话生命周期限制。
⚠️ 重要：异步执行
该技能立即返回，不阻塞主会话！
任务在后台独立运行，你可：
- 继续与 OpenClaw 对话
- 发送新消息
- 实时查看日志进度
使用场景
- 需要 Agent 整夜编写代码
- 长时间运行的大型项目开发
- 避免因 OpenClaw 会话超时导致任务中断
前提条件
- 已全局安装 Codex CLI（
npm install -g @openai/codex） - 已配置代理（翻墙）
- 目标目录需为 Git 仓库（已执行
git init）
命令
start
启动 Codex 后台任务（异步执行，不阻塞会话）
codex-runner start "实现一个 React TODO 应用" my-task /Users/tianyanan/my-project
参数说明：
-
$1: 任务描述（必需） -
$2（可选）: 任务名称，用于日志文件命名，默认为codex-task -
$3（可选）: 目标目录路径，默认为当前目录
关键：必须通过 background=true 执行！
由于 OpenClaw 默认同步等待命令完成，需显式启用后台模式：
# 在 skill 命令中指定 background 参数
或直接使用 sessions_spawn 创建完全隔离的子会话：
# 让 Codex 在独立会话中运行，彻底解耦主会话
status
检查 Codex 进程当前状态
codex-runner status
log
查看指定任务的日志输出
codex-runner log my-task
参数说明：
-
$1（可选）: 任务名称，默认为codex-task
stop
终止正在运行的 Codex 任务
codex-runner stop
推荐方案：使用 sessions_spawn
由于 OpenClaw 主会话中直接调用 exec 会导致阻塞，最佳实践是使用 sessions_spawn 创建独立子会话来运行 Codex。
使用方式
由 AI 助手（即我）自动调用 sessions_spawn 启动任务：
# 我将执行如下指令：
sessions_spawn {
"runtime": "subagent",
"task": "在 ~/my-project 实现一个简单的 Hello World",
"label": "codex-hello"
}
示例：启动 Codex 任务
你可以这样说：
“用 codex 在桌面创建 test 文件夹，里面放一个 hello.txt”
我的处理流程为：
- 调用
sessions_spawn创建独立子会话 - 在子会话中执行 Codex 完成对应任务
- 主会话立即返回，持续响应你的后续输入
旧版命令（已弃用，仅作兼容参考）
start（不推荐）
# 使用 --dangerously-bypass-approvals-and-sandbox 完全跳过沙箱机制
TASK_NAME=${2:-codex-task}
TARGET_DIR=${3:-.}
nohup bash -c "
cd '$TARGET_DIR'
export https_proxy=http://127.0.0.1:8118
export http_proxy=http://127.0.0.1:8118
codex --dangerously-bypass-approvals-and-sandbox exec '$1'
" > ~/.codex-logs/codex-$TASK_NAME.log 2>&1 &
⚠️ 关键参数说明
必须使用 --dangerously-bypass-approvals-and-sandbox 才能向文件系统写入内容：
codex --dangerously-bypass-approvals-and-sandbox exec '任务描述'
| 参数 | 说明 |
|---|---|
--dangerously-bypass-approvals-and-sandbox |
完全绕过沙箱与审批流程（强制必需） |
exec |
非交互式执行模式 |
⚠️ 注意事项
- 目标目录必须是 Git 仓库（已执行
git init） - 启用该参数存在安全风险，请确保在受信、隔离环境中使用
开发任务模板（强烈建议遵循）
建议在任务描述中明确包含标准化开发流程要求：
codex-runner start " 实现一个用户管理系统，包含： 1. 用户增删改查 API 2. 用户列表页面 开发流程要求： 1. 先写单元测试，再写业务代码 2. 编码完成后执行单元测试：npm test 3. 如果单测失败，自动修复直到通过 4. 单测通过后执行构建：npm run build 5. 如果构建失败，自动修复直到通过 6. 单测和构建均通过后，任务才算完成 " my-task /Users/tianyanan/my-project
开发流程规范
| 步骤 | 要求 |
|---|---|
| 1. 单元测试 | 必须先编写测试用例，再实现业务逻辑 |
| 2. 执行单测 | 运行 npm test 或 npm run test
|
| 3. 自动修复单测 | 若失败，持续迭代修复直至全部通过 |
| 4. 执行构建 | 运行 npm run build
|
| 5. 自动修复构建 | 若失败，持续迭代修复直至成功 |
| 6. 完成判定 | 单元测试 + 构建均成功通过，方可标记为完成 |
监控方法
# 查看 Codex 相关进程 ps aux | grep codex | grep -v grep # 实时追踪日志（推荐） tail -f ~/.codex-logs/codex-my-task.log # 快速检查完成状态（搜索关键标志） grep "已完成\|build\|test" ~/.codex-logs/codex-my-task.log
日志存储位置
- 默认路径：
~/.codex-logs/codex-.log
测试验证结果
- ✅ 持续运行稳定可靠
- ✅ 支持文件系统写入（依赖
--dangerously-bypass-approvals-and-sandbox） - ✅ 可生成结构完整的 React 项目
- ✅ 构建流程验证通过
参考信息
- 方案灵感源自 Eliason 提出的 “Agent 整夜写代码” 实践
- 测试周期：2026-03-04 ~ 2026-03-05
- 最近更新：2026-03-05（新增开发流程规范）