Skill

codex-dev

当用户希望以异步方式执行 Codex 任务（而非维持长时间的交互式会话）时，使用该 skill。

当用户希望将 Codex 任务提交至后台执行、立即获取作业回执，并在任务完成后查看摘要或通过 Telegram 接收通知时，使用该 skill。

What it does | 功能说明

• 启动一个后台 Codex 作业，并立即返回作业回执
• 将作业产物保存至 $HOME/.codex-dev/jobs//
• 支持保存以下文件：task.txt、status.json、codex.out.log、summary.txt 和 patch.txt
• 可选地在任务完成后将摘要发送至 Telegram
• 支持通过 --workdir 显式指定工作目录
• 适用于由 Telegram 触发的开发流程及本地 CLI 包装器（wrapper）

Files | 文件组成

• 主入口脚本：scripts/codex-dev-dispatch
• Worker 脚本：scripts/codex-dev-worker
• Telegram 通知辅助脚本：scripts/telegram-notify
• （可选）本地安装脚本：scripts/install-local.sh
• 本地配置参考文档：references/local-setup.md

When to use it | 适用场景

建议在以下情形中优先使用该 skill：

• 需要异步修改文件
• 需先返回作业回执，再异步完成执行
• 任务需在特定工作目录下运行
• 需保留补丁（patch）、日志等可追溯的执行痕迹，供后续审查

若用户仅需只读式代码检查（read-only inspection），通常直接返回响应即可，无需启用异步作业。

常见用例包括：

• “修复一个小问题，但先给我作业回执。”
• “把这个 Codex 任务放到后台运行，完成后发 Telegram 通知我。”
• “只修改这个指定目录下的文件。”

Invocation | 调用方式

直接从已安装的 skill 目录运行分发脚本：

./scripts/codex-dev-dispatch "Inspect the repo and fix one issue."

或显式指定工作目录：

./scripts/codex-dev-dispatch --workdir /absolute/path "Fix the issue only in this directory."

查询作业状态与摘要：

./scripts/codex-dev-dispatch status./scripts/codex-dev-dispatch show./scripts/codex-dev-dispatch help

若已安装本地命令行包装器（CLI wrapper），则可使用如下更简洁的命令形式：

codex-dev "Fix one issue and summarize the change."
codex-help
codex-dev-statuscodex-dev-show

中文常用调用示例：

codex-dev "修复一个小问题并总结修改"
codex-dev --workdir /absolute/path "只在这个目录里完成修改"
codex-help

Environment | 环境变量

支持以下可选环境变量：

• CODEX_DEV_DEFAULT_WORKDIR
• CODEX_DEV_JOBS_ROOT
• CODEX_DEV_CHAT_ID
• TELEGRAM_BOT_TOKEN
• CODEX_DEV_OPENCLAW_CONFIG

若未设置 TELEGRAM_BOT_TOKEN，worker 将按顺序尝试从 CODEX_DEV_OPENCLAW_CONFIG 指定路径、再从 ~/.openclaw/openclaw.json 中读取 botToken 字段。

Workdir behavior | 工作目录行为

• --workdir 必须为已存在的绝对路径
• Codex 将在该目录中执行
• 若该工作目录位于 Git 仓库内，则生成的 patch.txt 将基于检测到的仓库根目录（repo root）生成相对路径

Idempotency | 幂等性

对于写入类请求，应优先保证操作幂等：若所请求的内容已存在，不得重复追加或生成冗余内容；须在 summary.txt 中明确声明该情况。

Notes | 说明

• 本发布包仅包含该 skill 及配套辅助脚本
• OpenClaw agent 绑定逻辑、Telegram 集成逻辑以及本地 workspace 包装器均属于本地安装细节，不随包分发
• 如需将已安装的 skill 集成至本地 OpenClaw agent，请参考 references/local-setup.md
• 本包设计为通用化组件：仓库路径、Telegram chat id、默认工作目录等均需在本地完成配置
• 本社区发布包仅提供 skill 与脚本，不包含任何用户本地 agent 的绑定状态或运行时上下文
• 仓库路径、Telegram chat id、默认工作目录等配置项均需用户自行在本地设定