OpenFlow 是一款用于多 Agent AI 工作流的可视化构建工具。 在画布上拖拽角色卡片，连线构建流水线（规划者 planner → 架构师 architect → 编码者 coder），保存后即可由真实的并行 Agent 运行。

OpenFlow 是一个独立的项目。它基于 opencode 构建并以其 fork 分支形式发布，底层由 OpenCode 的无头引擎（opencode serve）驱动各个 Agent。OpenFlow 的全部专属代码均位于 packages/flow 中；未对上游包进行任何修改，因此 OpenCode 引擎可以始终保持最新，且与上游的合并保持干净。后文附有原始的 OpenCode README 说明。

前提条件

• Bun 1.3 或更高版本 —— OpenFlow 唯一需要的运行时（用于运行引擎、构建流程和画布前端）。可通过 bun --version 检查版本。
• Git。

获取代码

bash git clone https://github.com/SeeRay11/OpenFlow.git cd OpenFlow bun install

bun install 会拉取整个工作区 —— 包括 OpenCode 引擎以及 packages/flow 中 OpenFlow 的专属代码。首次安装体积较大；它会下载引擎的原生依赖项，并运行一个 postinstall 脚本将引擎预构建的 node-pty 辅助程序标记为可执行文件（在 Windows 上为空操作）。

停止已在运行的进程

OpenFlow 使用两个端口：引擎使用 4096，画布使用 5174。如果先前的运行仍占有着这些端口，手动启动引擎将失败并提示 Error: Unexpected error / ServeError —— 这表示端口已被绑定，而非安装损坏。

bun openflow.ts 会自动处理此问题：它会复用已在提供服务的端口，并释放已退出的死进程占用的端口。只有在需要全新启动引擎时才需要手动终止旧进程 —— 例如在编辑了 opencode.json 之后，因为引擎在启动时会缓存项目配置且不会重新读取。

Windows (PowerShell)

powershell Get-NetTCPConnection -LocalPort 4096,5174 -State Listen -ErrorAction SilentlyContinue | Select-Object -ExpandProperty OwningProcess -Unique | ForEach-Object { taskkill /pid $_ /T /F }

macOS / Linux

bash lsof -t -i :4096 -i :5174 | xargs kill -9

在没有监听服务时运行上述命令都是安全的 —— 它们不会匹配到任何进程。它们会终止这些端口上的任何进程，因此如果该端口运行了其他服务，请先检查：

powershell Get-NetTCPConnection -LocalPort 4096,5174 -State Listen | Select-Object LocalPort,OwningProcess

如果引擎报错 database is locked： 说明另一个 opencode 引擎已经在其他地方运行 —— 可能是 OpenFlow 的第二个副本，或者之前启动脚本遗留的进程。每个引擎都会共享位于 opencode 数据目录中的单个数据库，因此后启动的引擎无法打开它。此时释放端口没有帮助，因为该引擎不一定会持有这些端口。可以通过匹配正在运行的命令来终止它：

powershell Get-CimInstance Win32_Process -Filter "Name='bun.exe'" | Where-Object { $.CommandLine -match 'openflow.ts|src/index.ts serve|packages/flow dev' } | ForEach-Object { Stop-Process -Id $.ProcessId -Force }

bash pkill -f 'openflow.ts|src/index.ts serve|packages/flow dev'

然后重新启动 OpenFlow。如果每次都出现此问题，很可能是因为你在两处克隆了 OpenFlow 且两者均被启动 —— 请保留一个。

一条命令即可同时启动两个进程。设置环境变量是唯一因 Shell 而异的部分，请根据你所使用的终端选择对应命令。

PowerShell（Windows 默认）：

powershell $env:FLOW_MANAGE_SERVER=1; bun openflow.ts

bash、zsh、Git Bash、WSL、macOS、Linux：

bash FLOW_MANAGE_SERVER=1 bun openflow.ts

Windows cmd.exe：

cmd set FLOW_MANAGE_SERVER=1 && bun openflow.ts

fish：

fish env FLOW_MANAGE_SERVER=1 bun openflow.ts

该命令会启动引擎，等待其响应，随后在 http://localhost:5174 打开画布；按 Ctrl+C 可同时停止两者。残留的被占用端口会先被释放，已提供服务的端口会被直接复用而非重复启动。

FLOW_MANAGE_SERVER=1 将引擎的管理权交给画布，从而启用其重启按钮 —— 一键即可停止 opencode serve、重新启动它，并重新读取 Agent、模型和 MCP 状态。这是在不离开应用的情况下应用合并后的 Agent、新技能（Skill）或 MCP 更改的简便方法。该选项属于可选功能且绝不会接管正在运行的引擎；若要以非托管模式启动引擎，去掉该变量即可（在所有 Shell 中运行 bun openflow.ts）。

项目为习惯使用平台原生启动器的用户提供了两个封装脚本。它们本身不包含独立逻辑 —— 只是将参数转换为 openflow.ts 已经能够读取的环境变量。

在 Windows 上封装脚本可能拒绝启动： PowerShell 默认不运行未签名的本地脚本，因此 .\openflow.ps1 可能会失败并提示 "openflow.ps1 cannot be loaded because running scripts is disabled on this system"。另外，如果仓库是以 ZIP 格式下载而非 git clone，它还会被系统标记为来自网络，从而触发第二道拦截。直接使用 bun openflow.ts 则不受这两项限制，是绕过它们的最快方式。如需继续使用封装脚本，请为当前用户账户允许本地脚本，并对解压自 ZIP 的文件解除锁定：

powershell Set-ExecutionPolicy -Scope CurrentUser RemoteSigned Unblock-File .\openflow.ps1

命令行参数均为可选，三种配置方式最终解析出的执行计划相同：

PowerShell	shell	环境变量	说明
-Project <dir>	-p, --project <dir>	OPENFLOW_PROJECT	Agent 读取和写入的仓库路径 —— 它们会修改真实文件
-ServerPort <n>	-s, --server-port <n>	OPENCODE_SERVER_URL	引擎端口，默认为 4096
-Built	-b, --built	OPENFLOW_BUILT=1	构建并提供静态打包资源，而非运行 vite
-Manage	-m, --manage	FLOW_MANAGE_SERVER=1	让画布接管引擎，从而启用其重启按钮
-Help	-h, --help	—	打印参数列表
—	—	OPENFLOW_DRY_RUN=1	打印解析后的执行计划，不启动任何程序

或者手动分步启动这两个进程。先启动服务端：

bash bun run --cwd packages/opencode --conditions=browser src/index.ts serve --port 4096

接着启动画布界面，访问 http://localhost:5174：

bash bun run --cwd packages/flow dev

或者以构建产物模式运行（不经 vite 直接托管应用）：

bash bun run --cwd packages/flow start

• 无需 API Key 即可立即运行。 opencode 的 opencode (zen) 提供商提供了一个免费层级 —— 即 ID 以 -free 结尾的模型 —— OpenFlow 允许节点在未连接任何凭据的情况下直接使用它们。该配额为共享配额，因此出现 429 或模型返回 400 表示该免费层正忙，而非安装损坏；更换其他 -free 模型，或使用节点模型旁边的 test 按钮在整个运行前进行测试即可。
• 对于其他模型，点击标题栏中的 "api keys"。 此时将打开一个两步连接对话框 —— 选择提供商，粘贴对应的 Key —— 该 Key 将立即生效，无需重启服务端。该面板还支持导入 opencode CLI 已经保存的 Key：opencode providers login 会将 Key 写入 auth.json，而该服务端原本不会为此读取模型目录，因此将其导入即可生效。付费模型需要配置此项；未配置 Key 的全新安装无法产生费用。
• 将 OPENFLOW_PROJECT 设置为 Agent 应工作的目标仓库。 默认指向当前项目，请注意这些 Agent 会写入真实文件。
• 点击 "merge agents" 后需重启 opencode serve。 服务端仅在启动时读取一次项目的 opencode.json 并将其缓存，因此新合并的 Agent 在重启前不可见。Flow 的预检机制会拒绝本次运行，以避免节点以不存在的 Agent 身份执行。若启动时带有 -Manage / -m / FLOW_MANAGE_SERVER=1，只需在标题栏点击重启按钮即可一键完成。
• 权限默认为 auto， 即针对每次单独调用自动批准请求。如果希望手动审查，可在工具栏中切换为 ask me。无论哪种方式，所有决策都会被记录到运行日志中。
• 升级说明： 生成的 Agent 现在按节点（node）而非按角色（role）编制键名，因此在此项变更前保存的流水线需要重新运行一次 "merge agents" 才能再次运行。该操作只需执行一次。

关于端点、引擎、数据模型、生成的 Agent 配置等详细信息，请参阅 packages/flow/README.md。

---

开源 AI 编码 Agent。

OpenFlow 是一个独立的分支项目。它与 OpenCode 团队没有关联，未获其赞助，亦未获其背书。

---

bash

一键快速安装 (YOLO)

curl -fsSL https://opencode.ai/install | bash

包管理器安装

npm i -g opencode-ai@latest # 或使用 bun/pnpm/yarn scoop install opencode # Windows choco install opencode # Windows brew install anomalyco/tap/opencode # macOS 与 Linux (推荐，保持最新) brew install opencode # macOS 与 Linux (官方 brew formula，更新频率较低) sudo pacman -S opencode # Arch Linux (Stable) paru -S opencode-bin # Arch Linux (来自 AUR 的最新版) mise use -g opencode # 全平台 nix run nixpkgs#opencode # 或使用 github:anomalyco/opencode 获取最新 dev 分支

提示
安装前请先卸载早于 0.1.x 的旧版本。

OpenCode 还提供桌面端应用程序。可直接从 releases 页面 或 opencode.ai/download 下载。

平台	下载文件
macOS (Apple Silicon)	opencode-desktop-mac-arm64.dmg
macOS (Intel)	opencode-desktop-mac-x64.dmg
Windows	opencode-desktop-windows-x64.exe
Linux	.deb, .rpm, 或 .AppImage

bash

macOS (Homebrew)

brew install --cask opencode-desktop

Windows (Scoop)

scoop bucket add extras; scoop install extras/opencode-desktop

安装脚本遵循以下安装路径优先级：

1. $OPENCODE_INSTALL_DIR - 自定义安装目录
2. $XDG_BIN_DIR - 符合 XDG 基础目录规范的路径
3. $HOME/bin - 标准用户二进制目录（若已存在或可创建）
4. $HOME/.opencode/bin - 默认兜底路径

bash

示例

OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

OpenCode 内置了两个 Agent，可通过 Tab 键进行切换：

• build - 默认的全权限 Agent，用于日常开发工作。
• plan - 只读 Agent，用于分析与代码探索：
  • 默认拒绝文件编辑操作
  • 执行 bash 命令前会询问权限
  • 非常适合探索不熟悉的代码库或规划方案变更

此外还内置了一个 general 子 Agent，用于处理复杂搜索和多步骤任务。该 Agent 供内部使用，可在对话消息中通过 @general 进行调用。

了解更多关于 Agent 的信息。

有关如何配置 OpenCode 的更多信息，请前往官方文档。

如果您有意向为 OpenCode 贡献代码，请在提交 Pull Request 前阅读我们的 贡献文档。

如果您正在开发与 OpenCode 相关的项目并在名称中包含 "opencode"（例如 "opencode-dashboard" 或 "opencode-mobile"），请在项目的 README 中注明相应说明。

OpenFlow is a visual builder for multi-agent AI workflows. Drag role cards onto a canvas, wire a pipeline (planner → architect → coder), save it, and run it with real parallel agents.

OpenFlow is its own project. It is built on — and ships as a fork of — opencode, whose headless engine (opencode serve) drives the agents underneath. All of OpenFlow's own code lives in packages/flow; no upstream package is modified, so the OpenCode engine stays current and upstream merges stay clean. The original OpenCode README follows below.

Prerequisites

• Bun 1.3 or newer — the only runtime OpenFlow needs (it runs the engine, the build, and the canvas). bun --version to check.
• Git.

Get the code

git clone https://github.com/SeeRay11/OpenFlow.git
cd OpenFlow
bun install

bun install pulls the whole workspace — the OpenCode engine plus OpenFlow's own code in packages/flow. First install is large; it downloads the engine's native deps and runs a postinstall that marks the engine's prebuilt node-pty helpers executable — a no-op on Windows.

Stop anything already running

OpenFlow uses two ports: 4096 for the engine and 5174 for the canvas. If a previous run is still holding them, starting the engine by hand fails with Error: Unexpected error / ServeError — that is a port already bound, not a broken install.

bun openflow.ts handles this for you: it reuses a port that is already serving and frees one a dead run left bound. Kill the old processes yourself only when you want a genuinely fresh engine — after editing opencode.json, for example, since the engine caches project config at boot and never re-reads it.

Windows (PowerShell)

Get-NetTCPConnection -LocalPort 4096,5174 -State Listen -ErrorAction SilentlyContinue |
  Select-Object -ExpandProperty OwningProcess -Unique |
  ForEach-Object { taskkill /pid $_ /T /F }

macOS / Linux

lsof -t -i :4096 -i :5174 | xargs kill -9

Both are safe to run when nothing is listening — they simply match no process. They kill any process on those ports, so check first if you run something else there:

Get-NetTCPConnection -LocalPort 4096,5174 -State Listen | Select-Object LocalPort,OwningProcess

If the engine fails withdatabase is locked, another opencode engine is already running somewhere else — a second copy of OpenFlow, or one a previous launcher left behind. Every engine shares a single database in your opencode data directory, so the second one to start cannot open it. Freeing the ports does not help here, because that engine need not be holding them. Stop it by what it is running instead:

Get-CimInstance Win32_Process -Filter "Name='bun.exe'" |
  Where-Object { $_.CommandLine -match 'openflow\.ts|src/index\.ts serve|packages/flow dev' } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force }


pkill -f 'openflow\.ts|src/index\.ts serve|packages/flow dev'

Then start OpenFlow again. If it happens every time, you most likely have OpenFlow cloned in two places and both are being started — keep one.

One command starts both processes. Setting the variable is the only part that differs per shell, so pick the line for the terminal you are in.

PowerShell (the Windows default):

$env:FLOW_MANAGE_SERVER=1; bun openflow.ts

bash, zsh, Git Bash, WSL, macOS, Linux:

FLOW_MANAGE_SERVER=1 bun openflow.ts

Windows cmd.exe:

set FLOW_MANAGE_SERVER=1 && bun openflow.ts

fish:

env FLOW_MANAGE_SERVER=1 bun openflow.ts

It starts the engine, waits until it answers, then opens the canvas on http://localhost:5174; Ctrl+C stops both. A port a dead run left bound is freed first, and a port that is already serving is reused rather than started twice.

FLOW_MANAGE_SERVER=1 hands the engine to the canvas, so its restart button works — one click stops opencode serve, starts it again, and re-reads agents, models and MCP status. This is the easy way to apply a merged agent, a new skill or an MCP change without leaving the app. It is opt-in and never adopts a running engine; drop it (bun openflow.ts, on every shell) to start the engine unmanaged.

Two shims wrap that same file for people who prefer their platform's own launcher. They hold no logic of their own — they translate flags into the environment variables openflow.ts already reads.

On Windows the shim may refuse to start: PowerShell does not run unsigned local scripts by default, so .\openflow.ps1 can fail with "openflow.ps1 cannot be loaded because running scripts is disabled on this system". A repo downloaded as a ZIP rather than cloned is also marked as coming from the internet, which blocks it a second way. bun openflow.ts is subject to neither and is the shortest way past both. To use the shim instead, allow local scripts for your own account, and unblock the file if it came from a ZIP:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
Unblock-File .\openflow.ps1

Flags are optional, and the three surfaces resolve to the same plan:

PowerShell	shell	environment	what it does
-Project <dir>	-p, --project <dir>	OPENFLOW_PROJECT	the repo the agents read and write — they edit real files
-ServerPort <n>	-s, --server-port <n>	OPENCODE_SERVER_URL	engine port, default 4096
-Built	-b, --built	OPENFLOW_BUILT=1	build and serve the static bundle instead of running vite
-Manage	-m, --manage	FLOW_MANAGE_SERVER=1	let the canvas own the engine, which makes its restart button work
-Help	-h, --help	—	print the flag list
—	—	OPENFLOW_DRY_RUN=1	print the resolved plan and start nothing

Or start the two processes by hand. The server first:

bun run --cwd packages/opencode --conditions=browser src/index.ts serve --port 4096

Then the canvas, on http://localhost:5174:

bun run --cwd packages/flow dev

Or run it built, which serves the same app without vite:

bun run --cwd packages/flow start

• You can run something immediately, with no key. opencode's opencode (zen) provider serves a free tier — the models whose ids end in -free — and OpenFlow lets a node use them with no credential connected. It is a shared quota, so a 429 or a model that answers 400 is the tier being busy, not a broken install; pick another -free model, or use the test button beside a node's model to check one before a whole run.
• For anything else, click "api keys" in the titlebar. It opens a two-step connect dialog — pick a provider, paste its key — and the key takes effect immediately, with no server restart. That panel also offers to import keys the opencode CLI already holds: opencode providers login writes them to auth.json, which this server never reads for its model catalog, so importing them is what makes them count. A paid model needs this; a fresh install with no key cannot spend money.
• SetOPENFLOW_PROJECT to the repo the agents should work in. It defaults to this one, and these agents write real files.
• Restartopencode serve after "merge agents". The server reads a project's opencode.json once and caches it, so freshly merged agents stay invisible until it restarts. Flow's pre-flight check refuses the run rather than letting a node execute as an agent that does not exist. Start with -Manage / -m / FLOW_MANAGE_SERVER=1 and the titlebar's restart button does it in one click.
• Permissions default toauto, which approves each request for that one call. Switch the toolbar to ask me if you want to see them. Every decision is written to the run log either way.
• Upgrading? A generated agent is now keyed per node rather than per role, so a pipeline saved before this change needs one "merge agents" re-run before it will run again. Once only.

Details — endpoints, engine, data model, generated agent config — are in packages/flow/README.md.

---

The open source AI coding agent.

OpenFlow is an independent fork. It is not affiliated with, sponsored by, or endorsed by the OpenCode team.

English | 简体中文 | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | Bosanski | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська | বাংলা | Ελληνικά | Tiếng Việt

---

# YOLO
curl -fsSL https://opencode.ai/install | bash

# Package managers
npm i -g opencode-ai@latest        # or bun/pnpm/yarn
scoop install opencode             # Windows
choco install opencode             # Windows
brew install anomalyco/tap/opencode # macOS and Linux (recommended, always up to date)
brew install opencode              # macOS and Linux (official brew formula, updated less)
sudo pacman -S opencode            # Arch Linux (Stable)
paru -S opencode-bin               # Arch Linux (Latest from AUR)
mise use -g opencode               # Any OS
nix run nixpkgs#opencode           # or github:anomalyco/opencode for latest dev branch

Tip

Remove versions older than 0.1.x before installing.

OpenCode is also available as a desktop application. Download directly from the releases page or opencode.ai/download.

Platform	Download
macOS (Apple Silicon)	opencode-desktop-mac-arm64.dmg
macOS (Intel)	opencode-desktop-mac-x64.dmg
Windows	opencode-desktop-windows-x64.exe
Linux	.deb, .rpm, or .AppImage

# macOS (Homebrew)
brew install --cask opencode-desktop
# Windows (Scoop)
scoop bucket add extras; scoop install extras/opencode-desktop

The install script respects the following priority order for the installation path:

1. $OPENCODE_INSTALL_DIR - Custom installation directory
2. $XDG_BIN_DIR - XDG Base Directory Specification compliant path
3. $HOME/bin - Standard user binary directory (if it exists or can be created)
4. $HOME/.opencode/bin - Default fallback

# Examples
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

OpenCode includes two built-in agents you can switch between with the Tab key.

• build - Default, full-access agent for development work
• plan - Read-only agent for analysis and code exploration
  • Denies file edits by default
  • Asks permission before running bash commands
  • Ideal for exploring unfamiliar codebases or planning changes

Also included is a general subagent for complex searches and multistep tasks. This is used internally and can be invoked using @general in messages.

Learn more about agents.

For more info on how to configure OpenCode, head over to our docs.

If you're interested in contributing to OpenCode, please read our contributing docs before submitting a pull request.

If you are working on a project that's related to OpenCode and is using "opencode" as part of its name, for example "opencode-dashboard" or "opencode-mobile", please add a note to your README to clarify that it is not built by the OpenCode team and is not affiliated with us in any way.

---

Join our community Discord | X.com