Codex CLI Guardian

Codex CLI 会话守护者。管理 API Key、任务执行与结果摘要。提供后台模式运行、API Key 验证、会话锁定与PID追踪等功能。

Security Scan

The skill's files implement a Codex orchestration tool that expects and stores an API key and requires local binaries (codex, python3, script, git), but the registry metadata declares no credentials or required binaries — these mismatches and some operational behaviors are inconsistent and warrant caution.

Purpose & Capability

The declared metadata lists no required env vars or binaries, but the skill clearly needs an API key (OPENAI_API_KEY_0011AI stored in credentials.env) and depends on local binaries: codex, script (pty wrapper), python3, git. Those are required for its stated purpose (driving Codex in background) — so the capability is plausible — but the registry declaration omits those necessary pieces, which is an incoherence the user should know about.

Instruction Scope

Runtime instructions and scripts do more than just call a remote API: they read/write files under the skill directory (credentials.env, state/current-task.json, state/tasks/*.json, codex.lock), create a temporary Git repo and a /tmp workspace, launch background codex exec sessions (with --full-auto and workspace-write), and can spawn long-running processes. They also read an environment variable fallback. The scripts rely on local filesystem state (and produce task summaries that include absolute paths). While this is consistent with a session manager, it does direct the agent to create files, run external binaries, and persist a secret locally — actions that expand the agent's reach and should be explicit in metadata.

Install Mechanism

No install spec (instruction-only) — which reduces installer risk because nothing is downloaded at install time. However the packaged skill includes executable scripts that will be run at runtime. Because no external downloads/install steps are declared, users must ensure the required host binaries (codex, script, python3, git) are present and understood.

Credentials

Although the registry lists no required env vars/primary credential, the code expects and stores OPENAI_API_KEY_0011AI in credentials.env. The skill also accepts the key from an environment variable fallback. Requesting and persisting a single service API key is reasonable for the stated purpose, but the omission from metadata is a mismatch. Additionally, Codex runs with --full-auto and workspace-write, which effectively gives the invoked Codex session broad file-system write capability (not just the API key) — this increases the blast radius of the stored key and of any agent-driven actions.

Persistence & Privilege

always:false (no forced inclusion) and autonomous invocation is allowed by default. The skill persists data (credentials.env, state files, lock file) and launches background child processes; this is coherent with a session manager. No evidence the skill modifies other skills' configs or requests system-wide persistent privileges beyond writing under its own skill directory and /tmp. Still, background execution + stored API key + broad Codex execution flags increases potential risk if the skill is misused.

What to consider before installing

Key points to consider before installing: - The skill will ask you to provide an API key (OPENAI_API_KEY_0011AI) and will store it in skills/codex-cli-guardian/credentials.env (permissions 600). The registry metadata does NOT declare this credential — treat that omission as a red flag and verify you are comfortable storing the key there. - The package expects local binaries that are not declared: the 'codex' CLI, the 'script' PTY wrapper, python3, and git. Confirm you know what those binaries are, that they are the authentic tools you expect, and that calling them is acceptable in your environment. - The skill runs Codex with --full-auto and workspace-write (and uses a PTY wrapper). That means the invoked Codex session can perform arbitrary file writes within the workspace and run commands — review whether you want an automated component that can make changes without interactive approvals. - The scripts create and persist state and summary files (which may include absolute paths from your environment). If exposing file paths or generated summaries is a concern, inspect/relocate the state directory before use. - Although codex-call.sh uses Python shlex.quote() to reduce injection risk, any component that shells out with user-supplied task text still requires careful review. Inspect the scripts yourself (bin/codex-call.sh, bin/session.sh, scripts/init-setup.sh) and test in a safe sandbox before granting access to sensitive keys or production data. - Practical steps: (1) run scripts/init-setup.sh check to see current state, (2) inspect the credentials.env path and consider using a transient test key, (3) ensure the codex binary is the real official client, (4) run the skill in an isolated environment (container or dedicated user account) first, and (5) rotate the API key after testing if you used a real key. If you want, I can produce a concise checklist of commands to inspect and sandbox this skill before enabling it in your agent.

Codex CLI 会话守护者 — 管理 API Key、任务执行与结果摘要

---

技能职责

1. API Key 管理 — 首次引导输入并验证，验证通过才写入（init-setup）；codex-call 直接读取 credentials.env，不重复验证
2. 任务执行 — 后台模式运行 Codex，主人可继续聊天
3. 结果摘要 — 使用 -o 输出文件，只保存 Codex 完成语
4. 并发控制 — PID 锁防止多任务同时执行
5. 状态追踪 — 实时记录任务状态，支持超时警告
6. Worker 编排 — 提供标准化 Worker 模板和编排模式

不是：coding-agent 的替代品，是其底层基础设施。

---

调用方式（重要）

必须使用 background:true，否则主 agent 会等待 Codex 执行完毕才响应：

exec:
  command: bash bin/codex-call.sh "任务描述"
  background: true   # ← 必须加，默认行为

不加 background:true → 主 agent 阻塞 → 无法中途回复主人 加 background:true → 主 agent 立即返回 → 可以继续聊天

标准调用方式：

exec background:true command:"bash bin/codex-call.sh \"任务描述\""

进度/状态查询（不走 exec，直接读文件）：

# 读 state/current-task.json
# 读 state/tasks/ 最新任务历史

原因：进度查询走 exec 反而会产生新的 exec，形成嵌套，效率低。

---

多步骤任务编排

当主人描述的任务涉及多个阶段时，会自动加上步骤指引，引导 Codex 依次执行：

请按以下步骤执行：
1. 【侦察】先摸清现状和关键文件
2. 【评审】分析风险和可行方案
3. 【实施】执行核心工作
4. 【验证】确认结果正确

每步完成后简报。

常用步骤组合：

场景	步骤组合
代码重构	侦察 → 评审 → 实施 → 验证
复杂开发	需求确认 → 搭建框架 → 核心功能 → 测试
Bug 修复	复现 → 定位 → 修复 → 验证
批量修改	扫描 → 分析 → 执行 → 确认

---

触发场景

两层确认机制

第一层：触发关键词

主人说以下内容时，进入「意图确认」流程：

关键词	触发场景
写代码	「帮我写代码」
写个	「帮我写个爬虫」「写个脚本」
写一个	「写一个计算器」
开发	「帮我开发一个 API」
重构	「帮我重构这个模块」
Codex	「用 Codex 写」「用 Codex 跑」
脚本	「写个脚本处理数据」
程序	「写个程序」
/codex-guardian	管理命令前缀

注意：单独说「代码」「谢谢」等词不触发。

---

第二层：确认流程

检测到关键词后，回复确认：

🔍 检测到代码开发意图，要用 Codex 执行吗？

任务：帮我写一个爬虫

→ 直接回「是」/「好」/「执行」 → 执行
→ 回「不用」/「取消」 → 取消

主人确认后，执行 codex-call.sh，后台运行。

---

触发短语（agent 识别后执行，无需确认）

触发短语	执行动作
任务进度	读取 state/current-task.json 展示状态
终止任务	调用 session.sh kill
任务历史	调用 session.sh list
/codex-guardian status	调用 session.sh status
/codex-guardian reset	调用 session.sh reset

---

执行步骤

1. 主人发起任务
      ↓
2. codex-call.sh 加载 Key（文件不存在 → 触发 init-setup）
      ↓
3. 检查 PID 锁 → 被占用 → 拒绝
      ↓（空闲）
4. 生成 task_id（如 20260404-001）
      ↓
5. 写入 state/current-task.json（status: running）
      ↓
6. codex-call.sh 启动后台子进程执行 codex exec
      ↓
7. codex-call.sh 主进程立即返回 task_id（不阻塞）
      ↓
8. Codex 执行中（主人可继续聊其他事）
      ↓
9. Codex 完成 → 写 state/tasks/<task_id>.json（摘要）
      ↓
10. 通知主人任务完成

超时策略：不自动终止。超时后继续运行，主人可随时说「终止任务」。

---

PID 锁逻辑

进入 → 检查 lock 文件 → PID 存在且进程存活 → 拒绝
                              → PID 不存在或进程已死 → 清理 → 继续

---

命令接口

codex-call.sh

bash bin/codex-call.sh "<任务描述>"

• 返回：{"task_id":"...","pid":...}
• 始终后台执行，不阻塞

session.sh

bash bin/session.sh status   # 健康检查（含超时警告）
bash bin/session.sh list     # 列出最近任务
bash bin/session.sh kill     # 终止当前任务
bash bin/session.sh reset    # 重置状态（不清历史）

init-setup.sh

bash scripts/init-setup.sh        # 交互式设置向导
bash scripts/init-setup.sh check # 仅检查状态

• 首次引导：输入 Key → 验证通过才写入
• 已有 Key：询问是否重设

---

输出标准

任务完成

🚀 已启动任务 [20260404-001]：帮我写个爬虫
（后台执行中，你可以继续聊其他事情）

✅ 任务 [20260404-001] 完成：
spider.py 已创建完成，包含以下功能：
- 支持多页面爬取
- 自动去重

任务失败

❌ 任务 [20260404-001] 失败：
原因：API Key 无效或已过期

忙碌拒绝

⚠️ Codex 忙碌中，请稍后再试。

健康检查

=== Codex Guardian 状态 ===
任务状态   : idle
累计任务   : 5
最后使用   : 3 分钟前
当前任务   : 无

超时警告（>=25 分钟）

运行时长   : 25 分钟 / 30 分钟 ⚠️ 即将超时
如需终止任务，请说：「终止任务」

---

文件清单

路径	用途
credentials.env	API Key（skill 目录内，600 权限）
state/current-task.json	运行中任务
state/tasks/*.json	历史任务摘要
state/codex.lock	PID 锁文件

---

安全原则

1. API Key 不落日志
2. credentials.env 权限 600
3. credentials.env 已被 .gitignore 忽略，不会被 git 提交
4. init-setup 验证 Key 通过才写入，失败不保存（codex-call 不验证 Key）

---

参见

• REFERENCES.md — 完整格式标准
• CLI.md — Codex CLI 正确用法
• workers/ — Worker 模板
  • standard-preamble.md — Worker 前言
  • reviewer.md — 评审者
  • researcher.md — 研究者
  • implementer.md — 实现者
  • verifier.md — 验证者
  • scout.md — 侦察者
  • context-pack.md — Context Pack
  • patterns.md — 编排模式