codex-cli-bridge

Codex CLI Bridge 技能

目的

此技能在 Claude Code 和 OpenAI 的 Codex CLI 之间建立全面的桥接，实现无缝互操作：

1. 文档转换：将 CLAUDE.md 转换为 AGENTS.md（基于引用，不复制文件）
2. 执行辅助工具：为 Codex CLI 命令提供 Python 封装（始终使用 codex exec）
3. 技能文档：让 Codex CLI 用户能够使用 Claude Skills

主要功能

1. 生成 CLAUDE.md → AGENTS.md

• 解析 CLAUDE.md 和项目结构
• 扫描 .claude/skills/、.claude/agents/、documentation/ 文件夹
• 生成全面的 AGENTS.md，并包含文件路径引用
• 基于引用：不复制文件，仅链接到现有文件
• 根据最合适的使用方式（bash 脚本或提示词引用）记录 Skills

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（绝不使用普通的 codex——这对 Claude Code 至关重要）

4. 面向 Codex CLI 的技能文档

• 仅提示词类技能：展示如何在 Codex 提示词中引用
• 功能型技能：展示如何直接执行 Python 脚本
• 复杂技能：同时展示两种方法
• 包含正确的 codex exec 命令语法
• 提供模型选择指南（gpt-5 与 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": "Your task description",
  "model": "gpt-5|gpt-5-codex",
  "sandbox": "read-only|workspace-write|danger-full-access"
}

输出格式

AGENTS.md 结构

# AGENTS.md

## Project Overview
[From CLAUDE.md]

## Available Skills
### Skill Name
**Location**: `path/to/skill/`
**Using from Codex CLI**: [Most relevant method]

## Workflow Patterns
[Slash commands → Codex equivalents]

## MCP Integration
[MCP server references]

## Command Reference
| Claude Code | Codex CLI |
|-------------|-----------|
[Mappings]

执行辅助工具输出

{
  "status": "success|error",
  "output": "Command 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 各个部分
• 扫描技能、Agent、命令
• 提取质量门禁和 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

• 为 Codex CLI 命令提供 Python 封装
• 智能选择模型（gpt-5 与 gpt-5-codex）
• 沙盒模式辅助工具
• 会话管理
• 始终使用 codex exec

使用示例

示例 1：生成 AGENTS.md

用户提示词：

Generate AGENTS.md for this project

执行过程：

1. 安全机制检查 Codex CLI 是否已安装
2. 检查 CLAUDE.md 是否存在（若缺少则自动运行 /init）
3. 解析 CLAUDE.md 和项目结构
4. 生成包含文件引用的 AGENTS.md
5. 根据最合适的使用方法记录所有技能

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

---

示例 2：执行 Codex 分析任务

用户提示词：

Use Codex to analyze this codebase for security vulnerabilities

执行过程：

from codex_executor import CodexExecutor

executor = CodexExecutor()
result = executor.exec_analysis(
    "Analyze this codebase for security vulnerabilities",
    model="gpt-5"
)

执行命令：

codex exec -m gpt-5 -s read-only \
  -c model_reasoning_effort=high \
  "Analyze this codebase for security vulnerabilities"

---

示例 3：执行 Codex 代码编辑

用户提示词：

Use Codex to refactor main.py for better async patterns

执行过程：

executor = CodexExecutor()
result = executor.exec_edit(
    "Refactor main.py for better async patterns",
    model="gpt-5-codex"
)

执行命令：

codex exec -m gpt-5-codex -s workspace-write \
  -c model_reasoning_effort=high \
  "Refactor main.py for better async patterns"

---

示例 4：恢复 Codex 会话

用户提示词：

Continue the previous Codex session

执行过程：

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

执行命令：

codex exec resume --last

最佳实践

生成 AGENTS.md

1. 始终在包含 CLAUDE.md 的项目中运行（或让自动初始化创建该文件）
2. 先验证 Codex CLI 是否已安装
3. 使用最相关的方法记录技能（bash 或提示词）
4. 采用基于引用的方式（不重复文件）

执行 Codex

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

技能文档

1. 仅提示词的技能：在 Codex 提示词中引用
2. 功能型技能：直接执行 Python 脚本
3. 复杂技能：展示两种方法
4. 始终提供可运行的示例

命令集成

此技能与现有的 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 的封装命令

安装

前提条件

1. 已安装 Codex CLI：

   codex --version  # Should show v0.48.0 or higher
   

2. 已完成 Codex 身份验证：

   codex login
   

3. Claude Code v1.0+

安装技能

选项 1：复制到项目

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

选项 2：从此仓库使用

# Skill auto-discovered when Claude Code loads this project

故障排除

错误：“Codex CLI not found”

解决方案：安装 Codex CLI，并确保其位于 PATH 中

which codex  # Should return path
codex --version  # Should work

错误：“CLAUDE.md not found”

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

# Manually run /init
/init

错误：“stdout is not a terminal”

解决方案：始终使用 codex exec，绝不直接使用 codex

❌ codex -m gpt-5 "task"
✅ codex exec -m gpt-5 "task"

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 Skills Factory 维护对象：跨工具团队协作（Claude Code ↔ Codex CLI） 同步状态：基于引用的桥接（一向同步：CLAUDE.md → AGENTS.md）