preset-io/agor · 上手攻略

  • 仓库：preset-io/agor
  • 链接：https://github.com/preset-io/agor
  • 分类：ai（multi-agent orchestration / self-hosted dev platform）
  • 作者：spark
  • 更新：2026-08-30

是什么

Agor 是一款自托管、multiplayer-ready 的 web 工作台，把 Claude Code、Codex、Gemini、OpenCode、GitHub Copilot、Cursor 等「coding agent」统一编排到浏览器里协作。它本身不带模型，只是驱动你已经订阅或部署的 agent SDK / CLI，按 session 自由切换 provider，无供应商锁定。

核心抽象只有三层：

  • Branch（分支）——工作单元。每个 branch 是真实 git worktree，自带独立 dev 环境（端口自动分配，互不冲突）和独立对话历史，1 branch ≈ 1 feature / PR。
  • Session & Tree（会话与树）——agent 对话带谱系。Fork 保留上下文用于探索替代方案；Spawn 派生子任务拿全新上下文窗口。
  • Board & Zone（看板与分区）——Figma 式 2D 画布，把 branch 拖进 zone 触发模板化 prompt。

在此之上还提供 Teammate（带 Knowledge-base 长期记忆、技能、调度、网关渠道的"AI 同事"）、Agor MCP Server（让 agent 自己 introspect / fork / spawn / 调度自身会话）、Scheduler（cron 触发模板化 prompt）、Message Gateway（Slack / GitHub 作为会话入口）、Artifacts（看板上的可交互应用卡片）等扩展。

解决什么问题

  • 多个 agent 并行跑时端口、目录、上下文互相打架——Agor 用 git worktree + 端口池天然隔离。
  • agent 跑在终端里，缺乏 review / 协作 / 计费可观测性——Agor 把会话搬到浏览器，提供 per-prompt token 与美元计费、结构化 tool block、model / effort 选择器、completion chime。
  • 团队协作与 agent 协作割裂——multiplayer 实时光标、面团头像、空间评论、共享会话、共享终端，加上 branch-scoped RBAC + ACL + 三档执行模式（simple / sandbox / delegated）。
  • 想给 agent 装长期记忆 / 调度 / Slack 入口，但每个工具都要自己拼——Teammate + Knowledge + Scheduler + Message Gateway 是开箱即用的组合。

快速安装

前置：Node.js ≥ 22.12、PATH 上的 Git。HTTPS remote 需要系统 CA 信任库可用；SSH remote 需要 SSH 客户端 + 配置好的 key 或 agent。

最快路径（npm）：

npm install -g agor-live
agor init          # 生成 config / database，按提示选择要安装的 agentic tools
agor daemon start  # 后台启动守护进程
agor open          # 浏览器打开 Web UI

后续切换 / 修复已安装的 agent 工具用 agor install（⚠️ 注意：agor install 只改工具，不会重新初始化 Agor 本身）。

Docker 路径（克隆仓库后用 Compose 一键起开发实例）：

git clone https://github.com/preset-io/agor
cd agor
docker compose up
# 访问 http://localhost:5173，默认账号 admin@agor.live / admin

Homebrew、源码双进程（daemon watch + UI dev server）、Postgres、团队部署等见官方 Extended Installation。

核心用法

1. 加仓库 + 第一个 session

agor open 之后跟 onboarding wizard 走：添加一个 repo → 选 branch → 选择 runtime（Claude Code / Codex / Gemini / OpenCode / Copilot / Cursor(beta)）→ 起 session。

2. 三个基础操作

# Fork session：复制上下文用于探索替代方案（仍在原 branch）
agor session fork <session-id>

# Spawn subsession：开子任务，**新上下文窗口**（节省 token）
agor session spawn <session-id> --prompt "run unit tests and summarize"

# 把 branch 拖到 zone：触发模板化 prompt（看板 UI 操作）
# 等价 CLI：agor zone trigger <zone-id> --branch <branch-id>

3. 配 Teammate（AI 同事）

Teammate 是 Agor 的一等公民：每个 Teammate 有自己的 Knowledge-base 命名空间（可被团队搜索的长期 markdown 记忆），可教对话、装技能 / MCP 工具 / 网关渠道 / 调度器。可在 UI 里 raise team helper agent in an afternoon。

4. 让 agent 调度自己（Internal MCP）

Agor 把自身通过 MCP 暴露在 POST /mcp（Bearer 鉴权）——session 启动时自动签发 token，agent 能 fork / spawn / schedule / report 自己的会话。在 Internal MCP 指南 里有详细 schema。

5. 查看每个 prompt 的 token 与美元消耗

Rich Chat UX 直接渲染结构化 tool block、per-prompt 费用、模型选择器、completion chime。所有计费有 durable history，可按 session / branch / Teammate / user 维度聚合。

典型适用场景

  • AI-native 小团队：3-10 人同时在多个 agent runtime（Claude + Codex + Gemini）上做 feature，Agor 把他们装进同一个 board，谁在跑什么一目了然。
  • 单人高频多分支开发：同时维护 5 个 feature branch，每个都跑 agent，不想手动 git worktree add、不想端口冲突——Agor 自动管。
  • 给业务团队部署"常驻 AI 同事"：Teammate + Knowledge + Scheduler 组合可以做"周报汇总 agent""PR triage agent""值守客服 agent"。
  • 把 Slack / GitHub 接入 agent 工作流：Message Gateway 让 issue / message 触发 session，session 进度回写到原渠道。

坑与注意

  • ⚠️ 许可证是 BUSL-1.1，不是 OSI 开源：可以自托管、可以用在自己 / 客户内部商业、可以做咨询 / 集成 / 二次开发，不能把 Agor 自身的 agent 编排能力作为托管 / 商业化产品转售给第三方。Change Date 是 2029-01-15 或首个 BSL 版本的第 4 周年，到期转 Apache 2.0。商业替代许可需联系 Preset, Inc.
  • ⚠️ 默认 install 不会自动选 tool：agor init 时要主动选 coding-agent CLI；如果只装 Claude Code 再想加 Codex，跑 agor install 而不是再 init。
  • ⚠️ 端口冲突只在开 dev server 时自动避免：如果 branch 自己固定了端口（比如 next dev -p 3000），Agor 的端口分配不会覆盖——要么改命令、要么用环境变量读 Agor 注入的 $PORT。
  • ⚠️ Node 版本是硬门槛 22.12：低于这个版本 npm 全局包会拒绝安装，不会给友好提示。
  • HTTPS remote + CA store：自签名证书或公司内网 MITM 证书要先 update-ca-certificates，否则 git fetch 会失败。
  • daemon stop / restart 行为：目前文档没有 --systemd 模板，生产部署要么用 Docker Compose、要么自己写 launchd / systemd unit（参考 Extended Install）。
  • Cursor 是 beta：UI 上能看到但稳定性不如 Claude Code / Codex，开 sprint 前先 smoke test。
  • BSL 限制 vs 自托管商业 = 模糊地带：单客户内部部署被许可，但多客户 SaaS 转售不行——发版前法务 review。

与同类对比

工具 核心差异 适合谁
Agor（本仓库） 自托管 multiplayer board + Teammate + Internal MCP，branch = worktree 多 agent 并行 + 团队协作 + 想让 agent 自己调度自己
Claude Code / Codex / Gemini CLI 单 CLI 终端体验，是 Agor 的 driver 不是替代 单人单 agent / 不想装 web 平台
cursor IDE-first，编辑器深度集成 个人 / 小团队重度 IDE 用户
a2a agent ↔ agent 通信协议，不是 workspace 跨框架 agent 互操作场景
goose Block 出品的本地 agent runtime，可驱动多种 LLM 偏个人 desktop 体验，无 board / multiplayer
TradingAgents 等垂直 multi-agent 框架 解决特定领域（金融）多 agent 协作，非通用 workspace 垂直领域研究

Agor 的定位最接近 "Harness Engineering" 一词——它把 harness（agent 跑的环境 + 上下文 + 工具 + 计费 + 协作）做成可组合的产品，而不是单 agent runtime。

一句话推荐

已经在用 Claude Code / Codex / Gemini、又苦于多 branch 端口打架 / 上下文丢失 / 缺计费与协作面板的团队，Agor 是当下少数把"branch-as-worktree" + "branch-as-board-card" + "Teammate + Internal MCP"三件套同时做到的产品；⚠️ 唯一硬门槛是 BUSL-1.1 许可证，发版前确认你的用例不被 Additional Use Grant 排除即可上车。

信源

  • https://github.com/preset-io/agor（README 主源，2026-08-30 fetch）
  • https://agor.live/guide/getting-started（Quick Start）
  • https://agor.live/guide/extended-install（Homebrew / Docker / Postgres / 团队部署）
  • https://agor.live/guide/architecture（架构图 + 三大基础实体）
  • https://agor.live/guide/internal-mcp（Internal MCP 协议）
  • https://agor.live/guide/sdk-comparison（驱动 vs 替代关系）
  • https://agor.live/blog/raise-team-helper-agent（Teammate 实操）

不确定 / 待核

  • ⚠️ daemon 在 macOS / Linux 上 systemd unit 模板是否存在（文档未明确，写"自己写"为暂定）。
  • ⚠️ Cursor runtime 当前稳定性状态未独立验证（仅 README 标 beta）。
  • ⚠️ 默认账号 admin@agor.live / admin 是否仅 dev 模式可用，prod 模式是否强制改密——文档未明示，部署前必查。
  • ⚠️ BSL 1.1 Change Date 按 README "2029-01-15 或第 4 周年"，以 LICENSE 文件原文为准。