使用说明

codex工具循环

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

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

为什么使用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<br/>(roles + steps + policies)"]
  RT -->|stream + events| Codex["Codex backend<br/>(app-server / exec / sdk)"]
  Codex --> Repo[(Repo workspace)]

  RT --> Artifacts["Run artifacts<br/>(JSONL traces, reports, diffs)"]

  RT <-->|discover + call tools| Tools[Tool substrate]
  Tools -->|local HTTP or stdio| ToolServers["Tool servers<br/>(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参考： https://developers.openai.com/codex/cli/reference/
非交互模式(codex exec): https://developers.openai.com/codex/noninteractive/
Codex SDK： https://developers.openai.com/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 <path>`	执行SPEC驱动的运行（计划）
`codex-toolloop run workflow <name>`	执行指定的工作流（计划）
`codex-toolloop session list`	列出运行、线程ID和状态（计划）
`codex-toolloop session inspect <runId>`	检查运行工件并报告（计划）

典型工作流程

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进行线程控制

参考文献

应用服务器提供商： https://ai-sdk.dev/providers/community-providers/codex-app-server
执行非交互模式： https://developers.openai.com/codex/noninteractive/
Codex SDK： https://developers.openai.com/codex/sdk/
AI SDK ToolLoopAgent： https://ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent

运行工件

每次运行都会生成一个目录（默认： ~/.toolloop/runs/<runId>/)与：

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}
}