codex工具循环
基于OpenAI Codex和Vercel AI SDK v6构建的本地第一编码代理工作流。
codex-toolloop 是一个Node.js TypeScript CLI和运行时，用于构建可重复的多步骤编码代理工作流：计划、研究、实现、测试、审查和生成审计级运行工件（跟踪、差异、报告）。它旨在与Codex CLI身份验证（ChatGPT帐户使用）紧密集成，同时使用AI SDK代理模式进行编排和未来的UI集成。
______________________________________________________________________
目录
- 目录 - 为什么使用codex工具循环 - 主要特点 - 建筑 - 高级组件 - 功能开发运行（顺序） - 快速入门 - 先决条件 - 安装 - 启动本地工具服务器（可选，推荐） - 运行工作流 - 用法 - 命令（概述） - 典型工作流程 - 配置 - 配置文件 - 工具和集成 - 可扩展MCP工具服务器 - 后端 - 运行工件 - 发展 - 回购结构 - 构建 - 测试 - 文档 - 路线图 - 贡献 - 安全 - 许可证 - 如何引用 - BibTeX
______________________________________________________________________
为什么使用codex工具循环
如果你已经每天使用Codex，你通常想要两件简单的“终端聊天”无法可靠提供的东西：
- 可重复使用的工作流程：可以再次运行命名的参数化管道（功能开发、审计、迁移）。
- 工装纪律：受控的工具访问、一致的上下文收集以及所采取的每一项行动的可检查证据。
codex-toolloop 围绕Codex支持的工程运行添加了一个工作流引擎、键入的切换、策略控制和工件跟踪。
______________________________________________________________________
主要特点
- 工作流引擎 用于多步骤工程运行（功能开发、代码审查、审计）。
- 多代理角色 （规划者、研究人员、实施者、验证者、审阅者）进行严格的打字交接。
- Codex首次执行 支持：
- 持续会话和跑中修正（应用服务器模式） - 具有JSONL跟踪和结构化输出模式的非交互式自动化（exec模式） - 通过Codex TypeScript SDK进行程序化控制（可选）
- 类型安全架构 everywhere（Zod v4）用于工具输入、步骤输出和结构化报告。
- 当地第一批文物：每次运行都会生成一个可以检查、区分和共享的日志和输出目录。
______________________________________________________________________
建筑
高级组件
flowchart LR
Dev[Developer] -->|CLI commands| CLI[toolloop CLI]
CLI --> RT["Workflow runtime
(roles + steps + policies)"]
RT -->|stream + events| Codex["Codex backend
(app-server / exec / sdk)"]
Codex --> Repo[(Repo workspace)]
RT --> Artifacts["Run artifacts
(JSONL traces, reports, diffs)"]
RT |discover + call tools| Tools[Tool substrate]
Tools -->|local HTTP or stdio| ToolServers["Tool servers
(first-party + third-party)"]功能开发运行（顺序）
sequenceDiagram
participant Dev as Developer
participant TL as toolloop
participant P as Planner
participant C as Codex backend
participant T as Tool servers
participant R as Repo workspace
Dev->>TL: toolloop run workflow feature-dev --spec specs/...
TL->>P: Produce plan (typed)
P-->>TL: PlanOutput
TL->>C: Implement step (context pack + policies)
C->>R: Read/write files, run commands
C->>T: Call tools (docs, repo, etc.)
T-->>C: Tool results
C-->>TL: Stream events + final output
TL->>TL: Verify + Review
TL-->>Dev: Final report + artifact path______________________________________________________________________
快速入门
先决条件
- Node.js v24 LTS（运行时；AI SDK MCP STDIO传输所需）
- pnpm（通过Corepack推荐）
- Codex CLI已安装并通过身份验证（ChatGPT登录或API密钥）
- Git（推荐）
Codex CLI参考文献：
- CLI参考：
- 非交互模式(
codex exec): - Codex SDK：
安装
git clone https://github.com/BjornMelin/codex-toolloop
cd codex-toolloop
pnpm install
# verify environment
pnpm dev:cli -- doctor默认情况下，pnpmv10会阻止依赖生命周期脚本。此回购使用最小的、经过审计的分配列表 在 pnpm-workspace.yaml （目前 @biomejs/biome 和 esbuild).如果你添加依赖项 需要构建脚本，更新allowlist（或运行 pnpm approve-builds).
启动本地工具服务器（可选，推荐）
# Planned (SPEC 010 + SPEC 040)
# pnpm dev:cli -- mcp start运行工作流
# Planned (SPEC 030 + SPEC 040)
# pnpm dev:cli -- run spec ./docs/specs/040-cli.md
# pnpm dev:cli -- run workflow feature-dev --approval on-failure --sandbox workspace-write______________________________________________________________________
用法
命令（概述）
当前实施状态（SPEC 000）：仅 doctor 实施。以下其他命令 是路线图的一部分，并由其相应的SPEC跟踪。
| 命令 | 目的 |
|---|---|
codex-toolloop doctor | 验证环境（节点、pnpm、codex） |
codex-toolloop mcp start | 启动本地工具服务器（计划中） |
| `codex-toolloop run spec | |
| ` | 执行SPEC驱动的运行（计划） |
codex-toolloop run workflow | 执行指定的工作流（计划） |
codex-toolloop session list | 列出运行、线程ID和状态（计划） |
codex-toolloop session inspect | 检查运行工件并报告（计划） |
典型工作流程
feature-dev：计划->研究->实施->验证->审查->最终确定review：分析当前分支机构或差异，提出调查结果和建议audit：深入检查是否存在弃用、API不匹配和文档缺口
______________________________________________________________________
配置
codex-toolloop 读取单个配置文件（加上环境变量）。
配置文件
默认路径（可配置）： ./toolloop.config.toml
[toolloop]
artifacts_dir = "~/.toolloop/runs"
default_backend = "app-server"
[policies]
approval_mode = "on-failure" # untrusted | on-failure | on-request | never
sandbox_mode = "workspace-write" # read-only | workspace-write | danger-full-access
[tools]
# domain allowlist for network fetching tools (if enabled)
allowed_domains = ["ai-sdk.dev", "developers.openai.com", "vercel.com", "github.com"]
# tool allowlist at the workflow level (optional)
allowed_tools = ["repo.readFile", "repo.listDir", "repo.ripgrep", "docs.fetch"]
[codex]
# codex model alias used by backends
model = "gpt-5.2-codex"
# optional: configure MCP-compatible tool servers here (see next section)______________________________________________________________________
工具和集成
工具作为 共享工具基板 它可以在运行时被发现和调用。这使工作流可扩展，而无需将每个功能硬编码到CLI中。
Codex ToolLoop使用AI SDK v6原语进行MCP和动态工具：
- MCP客户端通过
createMCPClient()(@ai-sdk/mcp) - 动态工具通过
dynamicTool()（适用于大型或不断发展的工具目录）
可扩展MCP工具服务器
您可以将MCP服务器连接到：
- 提供repo实用程序（搜索、读取、目录列表）
- 从已分配的域中获取文档
- 连接到第三方工具生态系统
设计要点： 避免工具定义上下文膨胀.
- 工具分为小类 捆绑包 并按工作流/角色/步骤按需加载（ADR 0009、SPEC 011）。
- 默认传输是HTTP （可部署）； stdio仅限于本地 并且可能需要Node.js。
- 对于大型目录，我们只公开了一小部分MCP元工具，这些工具是用
dynamicTool()（SPEC 011）而不是注入每个工具模式。
请参阅：
- ADR 0003：
docs/adr/0003-mcp-tooling.md - ADR 0009：
docs/adr/0009-dynamic-tool-loading.md - 规范010：
docs/specs/010-mcp-platform.md - 规范011：
docs/specs/011-dynamic-tool-loading.md
______________________________________________________________________
后端
codex-toolloop 支持单个接口后面的三个Codex执行后端。
| 后端 | 最适合 | Notes |
|---|---|---|
app-server （默认） | 长时间交互式多步运行 | 持久线程、运行中注入、事件流 |
exec | 可脚本化的自动化 | JSONL跟踪和 --output-schema 用于严格结构化的输出 |
sdk （可选） | 编程集成 | 使用Codex TypeScript SDK进行线程控制 |
参考文献
- 应用服务器提供商：
- 执行非交互模式：
- Codex SDK：
- AI SDK ToolLoopAgent：
______________________________________________________________________
运行工件
每次运行都会生成一个目录（默认： ~/.toolloop/runs//)与：
meta.json（后端、策略、时间、线程id）events.jsonl（标准化事件流）tool-calls.jsonl（工具调用和编辑结果）final-report.md（人类可读报告）step-outputs/（每一步键入JSON输出）diff-summary.md（发生了什么变化）
这是为以下目的而设计的：
- 调试失败
- 与队友共同跑步
- 比较运行时间
- 为工作流创建黄金测试
______________________________________________________________________
发展
回购结构
apps/
cli/ # CLI entrypoint and streaming UX
packages/
codex-toolloop/ # runtime: workflows, steps, artifacts, policies
codex/ # codex backends (app-server, exec, sdk)
mcp/ # tool substrate + local tool servers
workflows/ # named workflows and role definitions
testkit/ # fixtures, temp dirs, mocks
docs/ # PRD, architecture, ADRs
specs/ # implementation specs构建
pnpm build______________________________________________________________________
测试
Vitest用于：
- 单元测试（纯TypeScript）
- 集成测试（模拟Codex和工具服务器）
- 型式试验(
expectTypeOf)
运行测试：
pnpm test运行类型检查：
pnpm typecheck______________________________________________________________________
文档
- PRD：
docs/PRD.md - 架构：
docs/architecture.md - ADR：
docs/adr/ - 规格：
docs/specs/
______________________________________________________________________
路线图
- 稳定的工作流程包：功能开发、审查、审计
- 工具服务器目录和发现用户体验
- 步骤边界的结构化输出更强（模式优先）
- 用于浏览运行工件和启动运行的可选本地UI（Next.js）
- 跑步记录和回放（金色轨迹）
______________________________________________________________________
贡献
欢迎捐款。
推荐流量：
- 打开一个描述用例和预期行为的问题。
- 在以下位置添加或更新SPEC
docs/specs/对于非微不足道的变化。 - 为行为更改添加测试（单元或集成）。
- 保持变化小而集中。
______________________________________________________________________
安全
- 默认政策旨在确保地方发展的安全：
- 沙盒： workspace-write - 批准： on-failure
- 除非您完全了解风险，否则请避免使用危险的沙盒模式运行。
- 在可能的情况下，工具输出在写入工件之前会被编辑。
如果您发现安全问题，请打开私人报告或创建GitHub安全公告（首选）。
______________________________________________________________________
许可证
看 LICENSE.
______________________________________________________________________
如何引用
如果你使用 codex-toolloop 在学术工作或技术报告中，将其作为软件引用。
BibTeX
@software{melin_codex_toolloop_2026,
author = {Bjorn Melin},
title = {codex-toolloop: Local-first coding-agent workflows built on OpenAI Codex and Vercel AI SDK},
year = {2026},
url = {https://github.com/BjornMelin/codex-toolloop}
}