Ensemble 新手教程

Ensemble 是一个桌面多 Agent 工作台。你可以把 Claude、OpenAI、OpenAI Compat 和 Codex CLI agent 组织成 team，在同一个 workspace 里通过 peer_send / peer_query 协作。

快速开始

  1. 下载并安装当前平台版本：Windows x64 为 Ensemble_0.0.28_x64-setup.exe；macOS Apple Silicon / Intel 为 Ensemble_0.0.26_aarch64.dmg / Ensemble_0.0.26_x64.dmg。
  2. 打开左侧 Providers，添加至少一个 provider。
  3. 点击 + team 创建团队，给每个成员选择独立 provider、model 和角色 prompt；也可以先用 + 创建单 agent。
  4. 在聊天框输入任务，按 Enter 发送。
Windows 与 macOS 按平台隔离 manifest 更新。客户端只选择自己系统和架构对应的安装包；缺失某个平台条目时不会误提示下载另一个系统的安装包。

Provider

Provider用途凭据
anthropic-local使用本机 Claude Code 登录态已安装并登录的 claude CLI
openai-localOpenAI 官方 APIsk-...
openai-compatOpenAI 兼容服务baseUrl + apiKey
openai-codex使用本机 Codex CLI / ChatGPT 登录态已安装并登录的 codex CLI

本地 Claude / Codex 需要先在系统终端安装并登录对应 CLI。Ensemble 复用本机凭证，不存 token；CLI 缺失或未登录时会在应用内提醒。

Teams

团队把一组 agent 的共同目标、成员角色和跨模型协作关系固定下来。创建 team 时可以为每个成员独立选择 provider + model：例如 Claude 做架构、Codex 做代码执行、GPT 做审阅。

团队 purpose 会注入成员 prompt。编辑团队、成员角色或团队归属后，Ensemble 会清理对应 resume 指针，让下一轮使用新 prompt，同时保留聊天历史和用户设置。

Agent 互相通知

peer_send 用来异步向另一个 agent 发送新消息，peer_query 用来读取另一个 agent 的最近上下文且不触发运行。

peer_send 支持 raw / continue / review / fork。includeSource 默认为 auto：raw 只送消息，其他交接模式会附带有界来源输出。目标正在运行时消息会排队，批量 queued peer send 会合并；紧急 interrupt 必须写明 interruptReason，只作为安全阀。

请通知 Reviewer：
target: Reviewer
mode: review
message: 请检查这个实现是否有回归风险。

Codex CLI

  1. 先安装并登录 Codex CLI：npm i -g @openai/codex，然后运行 codex login。
  2. 在 Ensemble 的 Provider 面板添加 OpenAI -> Codex CLI。
  3. 为 Codex agent 设置 workspace、sandbox 和 reasoning effort。
Codex 是本机 CLI subprocess，不是旧 SDK 直连。Ensemble 使用隔离 CODEX_HOME，支持 read-only / workspace-write / danger-full-access sandbox；Codex peer tools 通过本地 stdio MCP bridge 暴露。

Claude / Codex 的 thinking mode 可在 Agent 设置中通过 reasoning effort 继承或覆盖。

Cloud beta

Cloud beta 通过 Ensemble server / cloud infrastructure 提供账号、workspace 同步、网页工作区、远程发送和部分 agent 设置入口。登录网页后，桌面在线时可以向本地 agent 发送消息并查看结果；模型调用、本地文件访问、CLI 登录态、MCP 和权限审批仍由桌面端执行。

官网 Cloud workspace 可查看同步后的 teams、agents 和消息；桌面在线时，可以从网页向指定本地 agent 发送远程消息、查看返回结果，或提交部分设置变更。

MCP 和 Skills

MCP 是外部工具服务，支持 stdio、http、sse。Skills 是 SKILL.md 指令包，来源包括 project、ensemble、user 和 system，支持 auto、forced 和 disabled 状态。

左侧 Skills 面板可以新建、编辑和重扫 ensemble 管理的 skill；agent 可用 skill_list 查看技能，用 skill_invoke 加载指定技能。

用量统计

输入 /cost 可打开 Usage Stats，按 agent、model、provider、日期查看 token / cost breakdown，并导出 CSV。Codex 订阅型 turn 会记录 token，但不会按 API 单价重复计费。

Loop

用 /loop 给 agent 开循环：你只填目标，agent 做完后自己在 TASKS.md 写下 ## DONE。命令校验是可选项。Team 上可以一块看板、多个隔离 runner、可选 reviewer；可选 git worktree（停环不删）。这是 Ensemble 编排器的 Stop-gate，不会加载 Claude settingSources。

常见问题

如果目标 agent 收到消息但运行失败，说明 peer_send 已送达，失败点通常在目标 provider 的 key、baseUrl 或 model。

流式输出会自动跟随到底部；如果你手动滚动离开底部，Ensemble 会尊重当前位置。

返回官网首页