Codex Toolloop

codex工具循环

 

      

基于OpenAI Codex和Vercel AI SDK v6构建的本地第一编码代理工作流。

codex-toolloop 是一个Node.js TypeScript CLI和运行时，用于构建可重复的多步骤编码代理工作流：计划、研究、实现、测试、审查和生成审计级运行工件（跟踪、差异、报告）。它旨在与Codex CLI身份验证（ChatGPT帐户使用）紧密集成，同时使用AI SDK代理模式进行编排和未来的UI集成。

______________________________________________________________________

目录

• codex工具循环

- 目录 - 为什么使用codex工具循环 - 主要特点 - 建筑 - 高级组件 - 功能开发运行（顺序） - 快速入门 - 先决条件 - 安装 - 启动本地工具服务器（可选，推荐） - 运行工作流 - 用法 - 命令（概述） - 典型工作流程 - 配置 - 配置文件 - 工具和集成 - 可扩展MCP工具服务器 - 后端 - 运行工件 - 发展 - 回购结构 - 构建 - 测试 - 文档 - 路线图 - 贡献 - 安全 - 许可证 - 如何引用 - BibTeX

______________________________________________________________________

为什么使用codex工具循环

如果你已经每天使用Codex，你通常想要两件简单的“终端聊天”无法可靠提供的东西：

1. 可重复使用的工作流程：可以再次运行命名的参数化管道（功能开发、审计、迁移）。
2. 工装纪律：受控的工具访问、一致的上下文收集以及所采取的每一项行动的可检查证据。

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跟踪。

典型工作流程

• 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执行后端。

参考文献

• 应用服务器提供商：
• 执行非交互模式：
• 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）
• 跑步记录和回放（金色轨迹）

______________________________________________________________________

贡献

欢迎捐款。

推荐流量：

1. 打开一个描述用例和预期行为的问题。
2. 在以下位置添加或更新SPEC docs/specs/ 对于非微不足道的变化。
3. 为行为更改添加测试（单元或集成）。
4. 保持变化小而集中。

______________________________________________________________________

安全

• 默认政策旨在确保地方发展的安全：

- 沙盒： 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}
}