SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场codex-session-patcher

codex-session-patcher

安全与审计

查看项目

更新于 10-15 14:53

技能介绍

用途

codex-session-patcher 是一个轻量级 Python 工具，主要面向使用 Codex CLI、Claude Code 和 OpenCode 进行安全测试（如 CTF 竞赛、授权渗透测试）的用户。它的核心目标是：检测并清理会话文件中 AI 的拒绝回复，使会话能够继续；同时通过向工具配置或工作区注入安全测试上下文，从源头降低未来出现拒绝的概率。

主要能力

会话清理

扫描会话文件中的拒绝回复，并将其替换为可协作的内容，以便恢复会话继续对话。支持 Codex CLI（JSONL）、Claude Code（JSONL）和 OpenCode（SQLite）三种会话格式。

CTF 提示注入

将安全测试上下文注入到工具配置或工作区中，以降低拒绝概率。不同平台的注入方式不同：

  • Codex CLI：支持 Profile 模式与全局模式。
  • Claude Code：注入工作区（Workspace）。
  • OpenCode：注入工作区（Workspace）。

Web UI

提供统一仪表盘，用于多平台会话管理、差异预览和实时日志，支持中英文界面切换。

拒绝检测

采用两级检测机制：强关键词进行全文匹配（低误报），弱关键词在回复开头匹配（避免过度触发）。支持通过配置或 API 添加自定义关键词。

AI 辅助重写

可选启用 LLM 生成上下文相关的替换回复，兼容 OpenAI 接口的 API（如 OpenAI、OpenRouter、本地 Ollama）。

备份与恢复

在修改会话前自动备份，支持列出备份并按索引恢复，便于撤销误操作。

使用方式

安装

git clone https://github.com/ryfineZ/codex-session-patcher.git
cd codex-session-patcher

# 仅 CLI（无额外依赖）
pip install -e .

# CLI + Web UI
pip install -e ".[web]"
cd web/frontend && npm install && npm run build && cd ../..

CLI 常用命令

# 干跑预览，不修改文件
codex-patcher --dry-run --show-content

# 清理最近一次会话（自动检测 Codex 格式）
codex-patcher --latest

# 清理全部会话
codex-patcher --all

# 指定平台
codex-patcher --latest --format claude
codex-patcher --latest --format opencode

# 安装 CTF 提示注入
codex-patcher --install-ctf           # Codex profile 模式
codex-patcher --install-claude-ctf    # Claude Code 工作区
codex-patcher --install-opencode-ctf  # OpenCode 工作区

Web UI

# 生产模式
./scripts/start-web.sh
# 或
uvicorn web.backend.main:app --host 127.0.0.1 --port 8080

# 开发模式（热重载，前后端）
./scripts/dev-web.sh

打开 http://localhost:8080，支持中英文界面切换。

配置

共享配置文件位于 ~/.codex-patcher/config.json，主要字段包括：

  • mock_response：AI 重写关闭时的回退替换文本。
  • ai_enabled：是否使用 LLM 生成上下文相关替换回复，默认 false。
  • ai_endpoint：OpenAI 兼容 API 基础 URL。
  • ai_key：API 密钥（建议使用环境变量）。
  • ai_model：模型名称。
  • custom_keywords：额外的拒绝检测短语。
  • ctf_prompts：按平台注入的系统提示。
  • ctf_templates：自定义 CTF 上下文模板。

API 密钥可通过环境变量设置，例如 export OPENAI_API_KEY="sk-..." 或 export OPENROUTER_API_KEY="sk-or-..."，然后在配置中引用 ${OPENAI_API_KEY}。

CTF/渗透测试工作流

Codex CLI

# 1. 安装 CTF profile（仅在显式调用时生效）
codex-patcher --install-ctf

# 2. 使用 CTF profile 启动，不影响正常会话
codex -p ctf

# 3. 若出现拒绝，清理会话
codex-patcher --latest --dry-run   # 预览
codex-patcher --latest             # 应用

# 4. 恢复清理后的会话
codex resume

Claude Code

# 1. 安装 CTF 工作区
codex-patcher --install-claude-ctf
# 创建 ~/.claude-ctf-workspace，并注入项目级 CLAUDE.md

# 2. 从 CTF 工作区启动
cd ~/.claude-ctf-workspace && claude

# 3. 出现拒绝时清理会话
codex-patcher --latest --format claude

# 4. 继续对话

OpenCode

# 1. 安装 OpenCode CTF 工作区
codex-patcher --install-opencode-ctf
# 创建 ~/.opencode-ctf-workspace，并注入 AGENTS.md

# 2. 必须从工作区启动（OpenCode 无 profile 机制）
cd ~/.opencode-ctf-workspace && opencode

# 3. 出现拒绝时清理会话
codex-patcher --latest --format opencode

Python API

核心库提供会话解析、拒绝检测、会话修补、格式策略、备份恢复和 CTF 安装等模块，可编程调用。例如：

from codex_session_patcher.core.parser import SessionParser
from codex_session_patcher.core.detector import RefusalDetector
from codex_session_patcher.core.patcher import SessionPatcher
from codex_session_patcher.core.formats import FormatStrategy

strategy = FormatStrategy.detect()
parser = SessionParser(strategy)
session = parser.get_latest_session()
messages = parser.parse(session)

detector = RefusalDetector()
refusals = detector.find_refusals(messages)

patcher = SessionPatcher(strategy, ai_enabled=False)
result = patcher.patch_session(session, dry_run=True)
print(result.diff)

适用场景

  • 在授权 CTF 竞赛或渗透测试中，因 AI 拒绝回复导致会话中断，需要清理会话以继续。
  • 希望通过注入安全测试上下文，减少在安全测试场景下的拒绝概率。
  • 需要统一管理 Codex CLI、Claude Code、OpenCode 多平台会话，并进行差异预览和日志查看。
  • 希望通过 Python API 将会话清理与拒绝检测集成到自有工作流中。

限制

  • 无法绕过平台级硬性安全策略，明确的策略违规在修补后仍可能被拒绝。
  • 效果会随模型版本更新而变化。
  • OpenCode 的 CTF 注入需要从工作区目录启动（无 profile 机制）。
  • 清理后需要手动恢复会话以还原对话上下文。
  • 会话文件路径因平台而异：Codex 为 ~/.codex/sessions/，Claude Code 为 ~/.claude/projects/，OpenCode 为应用数据目录中的 SQLite 数据库。