Codex-skills

适用场景

用户希望将 Codex 用作真正的编码智能体（coding agent），而非通用聊天助手：例如检查代码仓库、执行受控范围内的编辑、运行 review 模式、恢复中断的工作、安全使用 MCP，或在具备清晰可验证证据的前提下移交工作成果。

当问题难点不在于“编写代码”，而在于“确保 Codex 在 CLI、exec、review、resume、MCP、app-server、云任务或本地 OSS-provider 工作流中行为安全且可预测”时，请使用本技能。

架构

记忆数据存储于 ~/codex/ 目录下。若该目录不存在，请先运行 setup.md。目录结构规范详见 memory-template.md。

~/codex/
|-- memory.md          # 持久化激活边界与运行默认配置
|-- repo-profiles.md   # 按仓库定义的约定、测试面（test surface）及影响范围（blast-radius）说明
|-- safety.md          # 沙箱、审批与信任策略默认值
|-- mcp-notes.md       # 已批准的 MCP 服务器列表、作用域及拒绝原因
`-- incidents.md       # 卡住的会话、失败命令及对应恢复模式

快速参考

仅加载当前阻塞问题所需的最小文件。

前提要求

• codex 二进制程序已在目标机器上正确安装并可运行。
• 已通过 codex login 完成活跃认证；或在启用该模式时，明确配置了 OPENAI_API_KEY。
• 当任务涉及仓库检查、差异审查（diff review）或提交就绪（commit-ready）流程时，需确保系统中已安装并可用 git。
• 在执行危险沙箱绕过、远程 MCP 调用、Codex Cloud 应用、生产环境命令，或任何具有不可逆副作用的操作前，必须获得用户的显式批准。
• 将模型名称、功能特性及 app-server 行为视为实时演进的产品界面：应始终通过 codex --help、子命令帮助或官方文档进行验证，切勿硬编码过时假设。

运行覆盖范围

本技能将 Codex 视为一个可操作的编码界面（operational coding surface），而非泛化的 AI 建议工具。其覆盖范围包括：

• 交互式 Codex CLI 使用，明确指定工作目录与安全策略
• 非交互式 codex exec 与 codex review 工作流
• resume、fork 及支持工作移交的会话恢复机制
• 依据影响范围（blast radius）选择沙箱与审批策略
• MCP 服务器信任决策，以及本地工具与远程工具的边界划分
• 仅在明确认知其额外信任要求与审查义务的前提下，才使用 Codex app-server 和云任务
• 当用户明确希望本地执行时，通过 --oss 与 --local-provider 启用本地 OSS-provider 路由

数据存储

仅将持久化的 Codex 运行上下文保存至 ~/codex/：

• 已批准供 Codex 使用的仓库或工作区列表
• 按任务类型设定的默认沙箱与审批策略
• 首选执行界面：交互式 CLI、exec、review、云服务或本地 OSS provider
• 已批准的 MCP 服务器列表，及其各自允许访问的资源范围
• 高频恢复笔记：如错误目录、脏工作树（dirty worktree）、停滞命令、认证失效等场景的处理方案

核心规则

1. 在 Codex 执行前完成任务预检

• 首先锁定五个关键事实：目标仓库、当前目录、工作树是否已修改、所需权限、预期验证方式。
• 若其中任一要素不明确，须暂停操作并在启用 Codex 写入能力前彻底厘清。
• “开始编码”绝不能成为陌生仓库中的第一步操作。

2. 显式选择运行模式

• 探索性仓库工作使用交互式 Codex；有明确边界的非交互式执行使用 codex exec；需先审查再操作的任务使用 codex review。
• 若需恢复或分支已有工作，优先使用 resume 或 fork，而非从头重新描述全部上下文。
• 将云服务、app-server 与 MCP 辅助运行视作独立模式，各自承担不同风险等级。

3. 根据影响范围匹配沙箱与审批策略

• 只读模式适用于检查、规划与低信任度探索。
• workspace-write 模式适用于在已批准仓库内进行常规本地编码。
• 完全访问权限或危险绕过属于特殊用例，必须基于用户明确意图，并配套外部沙箱方案。
• 切勿为图方便而将高信任模式设为默认。

4. 编辑前务必先阅读仓库

• 在提出修改建议前，先检查目录结构、git 状态、入口点、项目约定及测试覆盖面。
• 当工作树已处于脏状态时，需区分用户变更与代理变更，避免破坏性清理。
• Codex 应适配仓库本身，而非强迫仓库迁就通用工作流。

5. 确保变更可审查且范围可控

• 优先采用最小化 diff、定向命令与显式文件所有权声明。
• 除非用户明确要求，否则避免无关清理、推测性重构或“顺手改一下”（while here）类编辑。
• 若某条命令或编辑意外扩大影响范围，须立即中止并主动向用户揭示该扩展。

6. 将认证、MCP 与云服务视为信任边界

• 某工具“可用”不等于“已获批准”。
• 启用任一 MCP 服务器前，均需审查其作用域、数据访问权限及潜在副作用。
• 尽可能复用现有登录会话；未经用户明确授权，禁止从本地文件中提取密钥（secrets）。
• 在本地应用云服务输出前，必须先行审查其 diff。

7. 验证结果并留下可移交的工作痕迹

• 一次成功的 Codex 运行应以校验收尾，而非仅止步于代码修改。
• 报告内容需涵盖：实际变更项、已验证项、失败项、以及仍存风险项。
• 对被中断或长时间运行的任务，须留下清晰、无歧义的检查点（checkpoint），使其他操作者可无缝接手，无需猜测上下文。

Codex 常见陷阱

• 在错误目录下运行 Codex → 修改将作用于错误仓库或超出预期范围。
• 误认为 workspace-write 安全无害 → 它仍会真实写入文件，且可能迅速扩大 diff 范围。
• 对日常任务滥用 --dangerously-bypass-approvals-and-sandbox → 方便性将转化为不可审查的风险。
• 仅因 MCP 服务器“存在”即启用 → 隐蔽的数据访问与副作用将悄然扩散。
• 未审查 diff 即直接应用云服务输出 → 本地仓库变更将变得不可见、不可追溯。
• 在脏工作树中放任 Codex 工作且未明确权属 → 引发审查噪音与意外覆盖风险。
• 中断后重复运行模糊提示 → 导致工作重复与验证结果不一致。

外部端点

除非用户显式批准，否则仅允许以下外部端点类别：

除非用户明确批准额外的 MCP 服务器、Git 远程地址或服务端点，否则不会向其他外部地址发送任何数据。

安全与隐私

离开您设备的数据包括：

• 发送至 OpenAI 服务的提示词，以及为 Codex 运行所选取的仓库上下文
• 仅针对用户已批准的 MCP 服务器发送的可选载荷
• 仅在用户有意使用 Codex Cloud 时，才发送的可选云任务载荷与 diff

保留在本地的数据包括：

• ~/.codex/config.toml 及用户的本地 Codex 会话/配置状态
• ~/codex/ 下的持久化运行记录
• 本地 diff、验证输出及仓库元数据（除非用户显式推送或上传）

本技能绝不：

• 默认接受危险绕过行为
• 静默启用远程 MCP 或云服务应用
• 为“辅助认证成功”而擅自从任意文件中提取令牌（tokens）
• 向用户隐藏沙箱或审批策略选项
• 声称 CLI、app-server、云服务与本地 --oss 流程具有相同风险等级

信任声明

使用本技能时，Codex 工作可能将提示词与所选仓库上下文发送至 OpenAI，并可能将数据发送至用户显式批准的任意 MCP 端点。
请仅在您信任这些服务处理相关数据的前提下安装本技能。

作用范围

本技能仅用于：

• 在真实编码环境中安全、高效地运行 Codex
• 将仓库工作结构化为明确的执行、审查与移交模式
• 为已批准仓库、安全策略及高频恢复模式维护持久化记忆

本技能永不：

• 将所有可用 Codex 功能自动视为已批准
• 将破坏性 git 清理作为默认修复方案予以推荐
• 模糊本地执行、云服务与 MCP 辅助执行之间的界限
• 修改其自身技能文件

关联技能

若用户确认，可通过 clawhub install 安装以下技能：

• agentic-engineering —— 强化围绕并行编码智能体与影响范围思维（blast-radius thinking）的人机协作流程。
• coding —— 在 Codex 已稳定运行于正确仓库边界内后，进一步提升实现质量。
• git —— 安全处理分支、差异比对及非破坏性仓库恢复。
• api —— 当 Codex 与外部服务集成时，复用结构化 API 调用与请求调试模式。
• workflow —— 将重复性 Codex 任务转化为可复现、可审查的执行路径。

反馈

• 若本技能有用：clawhub star codex
• 保持更新：clawhub sync