deep_research/docs/codex-usage.md

Codex Native Adapter

v0.20 起，Codex 是 Deep Research 的表层 adapter。共享核心迁移到 Python runtime：scripts/dr.py、scripts/runtime/**、configs/models.yaml 和 .agents/skills。Codex 不再复制核心调度逻辑。

Architecture

Layer	Shared	OpenCode	Codex
方法论	AGENTS.md	✅	✅
Skills	.agents/skills	继续保留 .opencode/skills	✅
Agent 定义	Python role runtime 为准	.opencode/agents/*.md 仅兼容	$CODEX_HOME/agents/*.toml 仅兼容
命令入口	scripts/dr.py	.opencode/commands/*.md wrapper	$CODEX_HOME/commands/*.md wrapper
Phase 4 确定性流水线	scripts/*.py	✅	✅

Codex 官方行为要点：

• 用户级配置放在 ~/.codex/config.toml 或 $CODEX_HOME/config.toml；项目级 .codex/** 不是 v0.20 推荐路径。
• Codex 会从项目根向当前目录读取 AGENTS.md。
• repo skills 放在 .agents/skills/*/SKILL.md。
• adapter templates 保存在 codex_adapter_templates/codex/**，部署脚本会复制到 $CODEX_HOME。
• subagents/agent threads 是 Codex 表层增强能力；v0.20 默认研究并发由 Python worker pool 执行。

Setup

cd /Users/tankai/Documents/Projects/deep_research
source scripts/activate.sh

首次使用 Codex adapter 前确认：

uv run python scripts/deploy_adapters.py codex --dry-run
uv run python scripts/deploy_adapters.py codex --force
find .agents/skills -maxdepth 2 -name SKILL.md | sort
uv run python scripts/dr.py status <slug>

默认部署不会写入 config.toml，避免覆盖现有 Codex 全局配置。只有确认要安装本项目 bundled profile 时，才运行 uv run python scripts/deploy_adapters.py codex --force --include-config。

新机器部署后可以先跑自检：

uv run python scripts/deploy_check.py

如果 $CODEX_HOME adapter 缺失或 skills 没同步：

uv run python scripts/deploy_check.py --repair --force

默认自动化权限：

• sandbox_mode = "workspace-write"：允许写入当前研究 workspace。
• approval_policy = "never"：命令执行不逐次弹窗。
• web_search = "live"：默认使用实时网络检索。
• [sandbox_workspace_write].network_access = true：脚本和 MCP server 默认可访问网络。
• Tavily / Brave / Exa MCP 默认启用，且 required = false，某个搜索服务临时不可用时不阻塞 Codex 主流程。

Codex Commands

Codex custom command templates 的真源位于 codex_adapter_templates/codex/commands/，部署后位于 $CODEX_HOME/commands/。在 CLI 中也可以绕过平台命令，直接用 scripts/dr.py prompt 从模板展开：

uv run python scripts/dr.py prompt dr-run dual-target-rnai-pipeline-2026
codex exec "$(uv run python scripts/dr.py prompt dr-run dual-target-rnai-pipeline-2026)"

推荐入口是 Python core。Codex command 只包装 CLI，不再让 Codex 主线程主动调度 subagents。

uv run python scripts/dr.py run <slug-or-topic>
uv run python scripts/dr.py research <slug> --workers 6
uv run python scripts/dr.py finalize <slug>

分阶段命令保留为调试和人工接管入口：

codex exec "$(uv run python scripts/dr.py prompt dr-init '<topic>')"
codex exec "$(uv run python scripts/dr.py prompt dr-frame <slug>)"
codex exec "$(uv run python scripts/dr.py prompt dr-research <slug>)"
codex exec "$(uv run python scripts/dr.py prompt dr-review <slug>)"
uv run python scripts/dr.py finalize <slug>

Phase 4 默认中文原生成稿：

uv run python scripts/dr.py finalize <slug> --model-profile medium

旧英译中 pipeline 仅用于兼容旧项目：

uv run python scripts/dr.py finalize <slug> --legacy-translate

网络不稳时可显式降并发：

uv run python scripts/dr.py finalize <slug> \
  --model-profile medium \
  --translate-workers 1 \
  --glossary-workers 3 \
  --polish-workers 1

术语核查策略可选：

uv run python scripts/dr.py finalize <slug> --model-profile medium --glossary-mode low-confidence
uv run python scripts/dr.py finalize <slug> --model-profile medium --glossary-mode full
uv run python scripts/dr.py finalize <slug> --model-profile medium --glossary-mode off

Adapter Boundary

Codex 可以继续用于审阅、解释和少量人工接管，但默认研究并发由 Python task-card runtime 控制。模型选择与 role/task 映射以 configs/models.yaml 为准。

Git Hygiene

本仓库常有大量 projects/** 研究产物处于修改状态。Codex adapter 提交时只 stage 系统文件：

git add codex_adapter_templates .agents/skills scripts docs configs README.md PLAN.md AGENTS.md
git diff --staged --name-only

提交前确认 staged 列表不包含：

• projects/**
• 已生成 PDF/DOCX/TXT
• 临时检查脚本或一次性研究产物

Deploying Adapter Files

不要在仓库内维护 .codex/**。如果需要 Codex native adapter，请把模板部署到用户级 Codex home：

uv run python scripts/deploy_adapters.py codex --force

兼容旧命令仍可用，但默认也会走外部部署：

uv run python scripts/install_codex_adapter.py --force

部署来源：

• codex_adapter_templates/codex/** → $CODEX_HOME/** 或 ~/.codex/**
• .agents/skills/** → $CODEX_HOME/skills/**

如果旧版本已经把仓库内 .codex/** 加进 Git，需要在本机清一次索引，让它回到“本地部署产物”身份：

git rm -r --cached .codex

部署后，在 Codex 中运行 /debug-config，确认 user config 或 CODEX_HOME config 已加载。

Config Troubleshooting

如果 Codex adapter 配置生效后启动报错，先按下面顺序排查：

1. 确认部署目标正确：默认是 $CODEX_HOME，未设置时是 ~/.codex。
2. Tavily / Brave / Exa MCP 默认启用但不是 required。若某个 server 启动异常，先确认对应环境变量存在，再临时把该 server 改成 enabled = false。
3. 如果要完全离线排障，先把第三方 MCP 全部关掉，只保留 OpenAI Docs MCP 和内置 web search。
4. 如果仍然报错，临时保留最小配置确认 Codex 主体能启动：

model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
approval_policy = "never"
project_doc_max_bytes = 65536
web_search = "live"

[agents]
max_threads = 6
max_depth = 1

[sandbox_workspace_write]
network_access = true

这个最小配置只启用模型、沙盒、项目说明、web search 与 subagent 上限；确认能启动后，再逐个恢复 profiles 和 MCP server。