Codex CLI Bridge 技能

目的

这项技能在 Claude Code 和 OpenAI的Codex CLI 之间创建了一个全面的桥梁，通过以下方式实现无缝互操作性：

文档翻译：将 CLAUDE.md 转换为 AGENTS.md（基于参考，无文件重复）
执行助手：Python 包装器用于 Codex CLI 命令（始终使用 codex exec）
技能文档：使 Claude 技能对 Codex CLI 用户可访问

主要功能

1. CLAUDE.md → AGENTS.md 生成

解析 CLAUDE.md 和项目结构
扫描 .claude/skills/, .claude/agents/, documentation/ 文件夹
生成包含文件路径引用的全面 AGENTS.md
基于参考：无文件重复，仅链接到现有文件
用最相关的方法记录技能（bash脚本与提示引用）

2. 安全机制

自动检查 Codex CLI 安装（codex --version）
如果 CLAUDE.md 缺失则自动运行 /init（并通知用户）
验证认证和环境
用户友好的错误消息

3. Codex CLI 执行助手

exec_analysis() - 只读分析任务（gpt-5, 只读沙箱）
exec_edit() - 代码编辑任务（gpt-5-codex, 工作区写入）
exec_with_search() - 启用网络搜索的任务
resume_session() - 继续上一个 Codex 会话
始终使用 codex exec（对 Claude Code 至关重要）

4. Codex CLI 的技能文档

仅提示技能：展示如何在 Codex 提示中引用
功能技能：展示如何直接执行 Python 脚本
复杂技能：展示两种方法
包括正确的 codex exec 命令语法
模型选择指导（gpt-5 vs gpt-5-codex）

输入要求

为 AGENTS.md 生成

{
  "action": "generate-agents-md",
  "project_root": "/path/to/project",
  "options": {
    "validate_codex": true,
    "auto_init": true,
    "include_mcp": true,
    "skill_detail_level": "relevant"
  }
}

为 Codex 执行

{
  "action": "codex-exec",
  "task_type": "analysis|edit|search",
  "prompt": "您的任务描述",
  "model": "gpt-5|gpt-5-codex",
  "sandbox": "read-only|workspace-write|danger-full-access"
}

输出格式

AGENTS.md 结构

# AGENTS.md

## 项目概览
[来自 CLAUDE.md]

## 可用技能
### 技能名称
**位置**: `path/to/skill/`
**从 Codex CLI 使用**: [最相关的方法]

## 工作流模式
[Slash 命令 → Codex 等效项]

## MCP 集成
[MCP 服务器引用]

## 命令参考
| Claude Code | Codex CLI |
|-------------|-----------|
[映射]

执行助手输出

{
  "status": "success|error",
  "output": "命令输出",
  "session_id": "uuid",
  "model_used": "gpt-5|gpt-5-codex",
  "command": "codex exec ..."
}

Python 脚本

safety_mechanism.py

检查 Codex CLI 安装
验证 CLAUDE.md 存在（如果缺失则自动运行 /init）
环境验证
用户通知

claude_parser.py

解析 CLAUDE.md 部分
扫描技能、代理、命令
提取质量门和 MCP 配置
返回文件路径（无内容重复）

project_analyzer.py

自动检测项目结构
发现所有 Claude Code 资产
生成项目元数据
构建参考映射

agents_md_generator.py

基于模板的 AGENTS.md 生成
文件路径引用（无重复）
技能文档（最相关的方法）
工作流翻译（Claude → Codex）

skill_documenter.py

为 Codex CLI 用户记录技能
确定每种技能的最相关使用方法
为 Python 脚本生成 bash 示例
创建 Codex 提示模板

codex_executor.py

Python 包装器用于 Codex CLI 命令
智能模型选择（gpt-5 vs gpt-5-codex）
沙箱模式助手
会话管理
始终使用 codex exec

使用示例

示例 1: 生成 AGENTS.md

用户提示：

为这个项目生成 AGENTS.md

发生什么：

安全机制检查 Codex CLI 是否已安装
检查 CLAUDE.md 是否存在（如果缺失则自动运行 /init）
解析 CLAUDE.md 和项目结构
生成带有文件引用的 AGENTS.md
用最相关的方法记录所有技能

输出：项目根目录中的完整 AGENTS.md 文件

示例 2: 执行 Codex 分析任务

用户提示：

使用 Codex 分析这个代码库以寻找安全漏洞

发生什么：

from codex_executor import CodexExecutor

executor = CodexExecutor()
result = executor.exec_analysis(
    "分析这个代码库以寻找安全漏洞",
    model="gpt-5"
)

执行：

codex exec -m gpt-5 -s read-only \
  -c model_reasoning_effort=high \
  "分析这个代码库以寻找安全漏洞"

示例 3: 执行 Codex 代码编辑

用户提示：

使用 Codex 重构 main.py 以获得更好的异步模式

发生什么：

executor = CodexExecutor()
result = executor.exec_edit(
    "重构 main.py 以获得更好的异步模式",
    model="gpt-5-codex"
)

执行：

codex exec -m gpt-5-codex -s workspace-write \
  -c model_reasoning_effort=high \
  "重构 main.py 以获得更好的异步模式"

示例 4: 继续 Codex 会话

用户提示：

继续上一个 Codex 会话

发生什么：

executor = CodexExecutor()
result = executor.resume_session()

执行：

codex exec resume --last

最佳实践

为 AGENTS.md 生成

始终在有 CLAUDE.md 的项目上运行（或让自动初始化创建它）
首先验证 Codex CLI 是否已安装
保持技能文档化，使用最相关的方法（bash vs 提示）
使用基于参考的方法（无文件重复）

为 Codex 执行

始终使用 codex exec（在 Claude Code 中永远不要使用纯 codex）
选择正确的模型：
- gpt-5: 通用推理、架构、分析
- gpt-5-codex: 代码编辑、专业编码任务
选择正确的沙箱：
- read-only: 安全分析（默认）
- workspace-write: 文件修改
- danger-full-access: 网络访问（很少需要）
需要时启用搜索（--search 标志）

为技能文档

仅提示技能：在 Codex 提示中引用
功能技能：直接执行 Python 脚本
复杂技能：展示两种方法
始终提供工作示例

命令集成

这项技能与现有的 Claude Code 命令集成：

/init: 在 CLAUDE.md 创建后自动生成 AGENTS.md
/update-claude: 当 CLAUDE.md 变化时重新生成 AGENTS.md
/check-docs: 验证 AGENTS.md 存在且同步
/sync-agents-md: 手动重新生成 AGENTS.md
/codex-exec <task>: 使用 codex_executor.py 的包装器

安装

先决条件

Codex CLI 安装：

codex --version  # 应显示 v0.48.0 或更高版本

Codex 认证：
```
codex login
```
Claude Code v1.0+

安装技能

选项 1: 复制到项目

cp -r generated-skills/codex-cli-bridge ~/.claude/skills/

选项 2: 从此仓库使用

# 当 Claude Code 加载此项目时自动发现技能

故障排除

错误：“Codex CLI 未找到”

解决方案：安装 Codex CLI 并确保它在 PATH 中

which codex  # 应返回路径
codex --version  # 应工作

错误：“CLAUDE.md 未找到”

解决方案：技能自动运行 /init 并通知。如果失败：

# 手动运行 /init
/init

错误：“stdout 不是终端”

解决方案：始终使用 codex exec，永远不要使用纯 codex

❌ codex -m gpt-5 "任务"
✅ codex exec -m gpt-5 "任务"

AGENTS.md 不同步

解决方案：手动重新生成

/sync-agents-md

参考

Codex CLI 文档：openai-codex-cli-instructions.md
Claude 技能文档：claude-skills-instructions.md
示例技能：claude-skills-examples/codex-cli-skill.md
AGENTS.md 规范：https://agents.md/

版本

v1.0.0 - 初始发布（2025-10-30）

许可证

Apache 2.0

创建者：Claude Code 技能工厂 维护者：跨工具团队协作（Claude Code ↔ Codex CLI） 同步状态：基于参考的桥梁（单向同步：CLAUDE.md → AGENTS.md）