FlowPilot · codex-flow

智能、高效、自适应的 Codex 多 Agent 策略编排引擎

English Documentation · 多策略运行时 · 深入配置 · 遥测机制 · 原生悬浮窗 · 基准评测

📢 社区公测：codex-flow 现已正式在 LINUX DO 开启公测，欢迎各位佬友前往体验、讨论与反馈！

“ 让昂贵的 Parent 做高价值判断，让高性价比 Worker 用更深推理承担探索、实现、验证与调试循环；当用户明确要求最高质量时，把高级 capability 精确投放到关键 Implementer / Reviewer，而不是无差别升级所有 Worker。”

✨ 核心亮点

🧠 多策略运行时 (FlowPilot) FlowPilot 从单一分发策略升级为统一 Strategy Runtime。内置 `efficient` / `balanced` / `quality` / `speed`，统一通过 TaskProfile → WorkerBudget → ExecutionPlan v7 驱动执行。	⚙️ 动态 Worker Budget Worker 数不再写死为 1~2 个。Runtime 根据不确定性、工作流隔离、Quota 与线程上限动态计算 Explorer / Implementer / Reviewer，并且可写并发始终要求真实隔离证据。
🧠 Worker-first Reasoning 默认 Parent 以 `high` 为主，便宜的 Worker 以 `xhigh` 起步；委派时各 Worker role reasoning 至少比 Parent 高一档，Parent 已为 `max` 时除外。	🏆 Quality Intent `quality` 支持 `normal / strong / absolute` 三档当前任务质量意图。普通 Explorer 继续优先 `latest-efficient`；强质量意图可把关键 Implementer / Reviewer 升级到 `latest-capable`。只有技术风险本身达到 critical 时，Explorer 才会升级到 Parent 级 capability。

🧩 四种内置策略

Strategy	优化目标	高需求任务的 Worker 倾向
`efficient`	减少昂贵 Parent 消耗与无效总成本	最多约 2 Explorer / 2 Implementer，低 speculation，Quota 紧张会自动收敛
`balanced`	平衡质量、额度与耗时	最多约 3 Explorer / 3 Implementer，适度安全并行
`quality`	最大化正确性与验证置信度	普通 complex 优先 Luna + `max` reasoning；`strong/absolute` 只把关键 Implementer / Reviewer 升级到 Parent 级 capability，Explorer 默认保持高性价比
`speed`	最小化 wall-clock latency	最多 8 个 Implementer budget；实际数量由已证明 writable workstreams 与 Runtime ceiling 决定

quality_intent 是当前任务语义，不是持久化配置，也不是 risk 的别名；并且只有 quality strategy 会消费它：

normal   → 普通质量目标，优先 latest-efficient Worker + 深 reasoning
strong   → 明确质量优先，允许关键 Implementer / Reviewer 使用 latest-capable
absolute → 明确最高质量优先，在安全 ceiling 内 correctness > quota / latency；Explorer 仍默认 latest-efficient

默认配置仍是：

strategy = efficient
routing = adaptive

但 v1.7 的 fresh-install 资源策略已经从“Parent 与 Worker 相近 reasoning”调整为 Parent 高价值决策 + Worker 深推理执行。已有用户的自定义 reasoning 配置在 update/reinstall 时会无损保留。

🚀 快速安装

前置要求 (Prerequisites)

💡 特别说明：Codex CLI 仅用于首次安装的环境校验与一次性 Hook 授权。初始化完成后，日常使用完全使用 Codex 桌面端 APP 即可，无需在终端中启动或使用 CLI。

确保环境拥有 Codex CLI（用于首次安装与授权）：

# npm 全局安装
npm install -g @openai/codex

# 或 macOS Homebrew 安装
brew install codex

快速安装

方式一：PyPI 安装（全平台推荐，支持 Windows / macOS / Linux）

# 推荐使用 pipx（独立隔离环境）
pipx install codex-flow

# 或使用标准 pip
pip install codex-flow

# 初始化配置与环境
codex-flow install

方式二：Homebrew 安装（macOS / Linux）

brew install ParsifalC/tap/codex-flow
codex-flow install

方式三：一键发布安装脚本

首次安装统一使用 GitHub Release 中与你的系统和 CPU 架构匹配的正式 artifact，不需要 clone 仓库。

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ParsifalC/codex-flow/main/install-release.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/ParsifalC/codex-flow/main/install-release.ps1 | iex

安装器会自动识别 OS / CPU、解析 Latest Stable Release、下载对应 artifact、校验 SHA-256、安装到 ~/.codex/codex-flow/versions/<version>，并运行健康检查。Windows 自动选择 x86_64 / ARM64 ZIP；macOS 直接使用 Release 中已经预编译好的 FlowPilot，安装完成后悬浮按钮会自动启动，不会在本机执行 build.sh。

⚠️ 最后一步：

首次一次性授权：在终端启动一次 codex，在对话框中输入 /hooks 批准 FlowPilot telemetry（仅需做一次，完成永久信任）。

重启 Codex 桌面端：完全退出 Codex 桌面应用后重新打开。FlowPilot 悬浮窗已在 macOS 桌面自动运行，后续所有日常工作直接在 Codex 桌面端使用即可，无需再打开终端。

安装器还会把带有明确标记的 FlowPilot 入口写入生效的全局 AGENTS.md。入口会要求当前 Agent 在仓库技术工作前读取已安装 skill 并取得策略门禁 receipt，因此不需要在提示中点名 skill。安装后请开始新任务或完整重新加载 Codex，确保新的指令生效。全局开关关闭或本任务的一次性 bypass 已消费时，该任务按普通流程执行。这个提示入口依赖当前宿主遵循指令，不是 100% 的强制边界；生命周期 hooks 仍只用于遥测。

🎮 基本使用

1. 查看 / 切换默认策略

codex-flow strategy show
codex-flow strategy profiles
codex-flow strategy set quality
codex-flow strategy set efficient
codex-flow strategy routing adaptive

2. 对话内自然语言覆盖

当前任务可以临时覆盖持久配置：

👉 策略覆盖："质量优先" / "尽量少用 Plan 额度" / "尽快完成"
👉 强质量："质量优先，必要时使用更强模型" → quality_intent=strong
👉 最高质量："成本不重要，用最强模型和独立验证" → quality_intent=absolute
👉 自动路由："按默认策略实现" / "自适应处理"
👉 强制委派："delegate" / "使用子 agent 实现" / "交给 worker 处理"
👉 单兵直出："direct" / "不要使用子 agent，直接完成" / "这次直接做"

Strategy 与 Routing 正交，例如：

quality + direct

表示使用 quality 的能力/推理目标，但当前任务不使用子 Agent。

3. 查看确定性的 ExecutionPlan

codex-flow strategy plan \
  --profile quality \
  --quality-intent strong \
  --complexity complex \
  --uncertainty high \
  --parallelism high

Plan 会输出 quality_intent、Strategy 的 worker_budget，以及 Runtime 实际编译出的三组角色资源：

explorer_capability_policy / explorer_model / explorer_reasoning
implementer_capability_policy / implementer_model / implementer_reasoning
reviewer_capability_policy / reviewer_model / reviewer_reasoning

同时包含 exploration_workers、implementation_workers、reviewer_workers 和 planned_worker_count。

4. 交互式控制台

codex-flow

最新控制台同时集成了 Overlay 构建/启动入口、策略状态、Benchmark 与遥测：

╭────────────────────────────────────────────────────────────────────╮
│                  🚀 codex-flow 控制台 (v2.1.13)                  │
│    FlowPilot 智能编排 · 确定性任务遥测 · 本地 Benchmark 验证     │
╰────────────────────────────────────────────────────────────────────╯
  [1] 🪟 macOS 原生悬浮窗 (overlay widget)
  [2] 📊 查看最新任务卡片 (usage last)
  [3] 📜 浏览历史任务列表 (usage list)
  [4] 📈 项目聚合统计分析 (usage stats)
  [5] 🎯 查看生效策略配置 (status)
  [6] 🩺 运行系统诊断检查 (doctor)
  [7] ⚡ 本地快速 Benchmark (benchmark-local quick)
  [8] 🔄 检查与拉取更新 (update)
  [0] 🚪 退出

Overlay 子菜单支持直接启动、编译并启动、仅编译，以及运行时的重编译/重启、展开切换和数据推送，不再要求用户手动先执行 build.sh。

5. 常用 CLI

codex-flow usage last
codex-flow usage list --today
codex-flow usage stats -d 30
codex-flow doctor
codex-flow update

6. MCP 客户端与平台集成 (Claude Desktop / Cursor / Smithery / Glama)

codex-flow 内置标准的 Model Context Protocol (MCP) 服务端，支持将 FlowPilot 确定性遥测注入任意支持 MCP 的宿主：

Claude Desktop / Cursor (stdio 模式)：在 claude_desktop_config.json 中配置：

{
  "mcpServers": {
    "flowpilot": {
      "command": "codex-flow-mcp",
      "args": ["--stdio"]
    }
  }
}

Smithery.ai：配置文件见根目录 smithery.yaml，已支持一键发现与客户端挂载。
Glama：认证元数据见根目录 glama.json，已入驻 Glama MCP 注册目录。

🪟 FlowPilot macOS 原生悬浮窗

专为 macOS 深度定制的 100% 纯原生毛玻璃效能看板，打通任务生命周期与 Quota 监控。

🟢 灵动微胶囊 (Capsule)：闲置时边缘半收起，呼吸光环显示任务状态与最新消耗。
⚡️ 实时巡检 (Inspector)：耗时 / Tokens / 费用、Quota 水位与 Agent 拓扑。
📜 历史回溯 (History)：跨项目任务时间线与详情回溯。
📊 效能看板 (Analytics)：7d/30d 缓存命中率、Worker 算力卸载比与模型/仓库分布。

codex-flow overlay start
codex-flow overlay toggle

📚 深入文档

模块	文档入口	核心内容
🧠 多策略运行时	docs/strategy-runtime.md	TaskProfile、Quality Intent、WorkerBudget、Strategy Registry、ExecutionPlan v7、role-scoped resources
⚙️ 策略与配置	docs/configuration.md	policy schema v4、Worker-first reasoning、路由、Runtime ceiling
📈 确定性遥测	docs/telemetry.md	Hook 生命周期、Token 差值归因、账户 Quota
🪟 原生悬浮窗	docs/overlay.md	交互、IPC 与 SwiftUI 架构
🧪 本地基准测试	docs/benchmark.md	本地无 Key 评测与多策略对比
☁️ Actions 评测	docs/benchmark-actions.md	GitHub Actions Benchmark
🌐 多语言支持	docs/localization.md	中英双语与本地化范围

📄 开源协议

本项目采用 MIT License 开源协议。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
apps		apps
benchmark		benchmark
bin		bin
completions		completions
docs		docs
packaging		packaging
policy		policy
scripts		scripts
templates		templates
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.en.md		README.en.md
README.md		README.md
VERSION		VERSION
glama.json		glama.json
install-release.ps1		install-release.ps1
install-release.sh		install-release.sh
install.ps1		install.ps1
install.sh		install.sh
pyproject.toml		pyproject.toml
setup.py		setup.py
smithery.yaml		smithery.yaml

Navigation Menu

Repository files navigation

FlowPilot · codex-flow

✨ 核心亮点

🧠 多策略运行时 (FlowPilot)

⚙️ 动态 Worker Budget

🧠 Worker-first Reasoning

🏆 Quality Intent

🧩 四种内置策略

🚀 快速安装

前置要求 (Prerequisites)

快速安装

方式一：PyPI 安装（全平台推荐，支持 Windows / macOS / Linux）

方式二：Homebrew 安装（macOS / Linux）

方式三：一键发布安装脚本

🎮 基本使用

1. 查看 / 切换默认策略

2. 对话内自然语言覆盖

3. 查看确定性的 ExecutionPlan

4. 交互式控制台

5. 常用 CLI

6. MCP 客户端与平台集成 (Claude Desktop / Cursor / Smithery / Glama)

🪟 FlowPilot macOS 原生悬浮窗

📚 深入文档

📄 开源协议

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

FlowPilot · codex-flow

✨ 核心亮点

🧠 多策略运行时 (FlowPilot)

⚙️ 动态 Worker Budget

🧠 Worker-first Reasoning

🏆 Quality Intent

🧩 四种内置策略

🚀 快速安装

前置要求 (Prerequisites)

快速安装

方式一：PyPI 安装（全平台推荐，支持 Windows / macOS / Linux）

方式二：Homebrew 安装（macOS / Linux）

方式三：一键发布安装脚本

🎮 基本使用

1. 查看 / 切换默认策略

2. 对话内自然语言覆盖

3. 查看确定性的 ExecutionPlan

4. 交互式控制台

5. 常用 CLI

6. MCP 客户端与平台集成 (Claude Desktop / Cursor / Smithery / Glama)

🪟 FlowPilot macOS 原生悬浮窗

📚 深入文档

📄 开源协议

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages