OpenAgents Workspace
调研与本地部署测试报告

一、项目概述

OpenAgents Workspace（GitHub：openagents-org/openagents）定位为“面向 Agent 的协作操作系统”——口号 One workspace where all your AI agents collaborate. Open source. No account required. 它把分散在不同终端、不同机器上的 AI Agent 汇聚到一个持久化的 Workspace（类比“给 Agent 用的 Slack”），共享同一套线程、文件与浏览器上下文，并支持 @mention 在 Agent 之间委派任务。

换言之，任务书中提到的 GitHub “Latest Release v0.4.0”指的是 桌面应用；而真正可 pip install 的开源框架是 Python SDK 0.9.3。本报告主体围绕完全可自托管的 SDK + 内置 Studio 展开实测。

1.1 三层产品结构

• 🌐 Workspace：浏览器协作层。人与 Agent 共享线程、文件、实时浏览器；可邀请协作者；查看端无需安装。
• ⚡ Launcher（agn）：Agent 管理层。一条命令安装编程 Agent、配置密钥、作为后台守护进程接入网络。
• 🛠 Network SDK：扩展层。事件原生架构 + Mod 系统（消息/文件/浏览器/游戏），支持 MCP 与 A2A 协议，可自托管网络。

1.2 核心概念

架构基于 OpenAgents Network Model（ONM），一切交互统一为 Event（事件），经由“传输层 → 鉴权 → 事件网关 → 系统命令 → 网络 Mod → 投递 → Agent Mod → 处理器”的管道流转。核心抽象：Network（有界上下文）、Mod（事件管道中间件/可插拔功能）、Agent、Transport（HTTP / gRPC / WebSocket / MCP / A2A / stdio）、Resource（共享工具/文件）。

1.3 代码规模（实测统计）

二、环境准备与部署步骤

OpenAgents 提供 5 种落地方式。下表按“是否可完全自托管 / 上手难度”归类，其中 ✅ 项为本次已实测：

2.1 下载源码（实测）

# 克隆主仓库（2012 个文件，含 SDK / 前端 Studio / 文档 / 示例）
git clone --depth 1 https://github.com/openagents-org/openagents.git
✓ 克隆成功 · Python 46.7% / TypeScript 43.2% / JS 5.4%

2.2 创建虚拟环境并安装（实测）

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[sdk]"          # 含 grpc/mcp/litellm/openai 等
openagents --version                # → OpenAgents v0.9.3.post20 ✓

SDK 依赖清爽：核心仅 pydantic/aiohttp/websockets/click/rich/typer/textual；[sdk] 额外引入 grpcio、mcp≥1.15、openai、litellm 等。安装一次成功，无编译报错。

2.3 启动本地网络（实测）

openagents network start ./sdk/examples/default_network/network.yaml
✓ Loaded 6 network mods: workspace.default / messaging / forum / wiki / project / games.agentworld
✓ HTTP transport listening on 0.0.0.0:8700   # 同时提供 /studio /mcp /a2a
✓ gRPC transport listening on 0.0.0.0:8600

2.4 启用 Studio GUI（实测）

editable 安装默认 不含预编译前端，首启日志提示 Studio build directory not found, /studio will return 404。需自行构建一次：

# 在 sdk/studio 下构建 React 前端（craco + Monaco + Radix）
cd sdk/studio && npm ci --legacy-peer-deps && CI=false npm run build
# 将产物拷入包目录，HTTP 传输层即可托管 /studio
cp -r build ../src/openagents/studio/build
→ 重启后 http://localhost:8700/studio/ 返回 HTTP 200 ✓

Docker 方式则在镜像内已自动完成该构建（多阶段 Dockerfile：Node 构建 Studio → Python 运行时），无需手动处理。

三、测试流程与结果

3.1 CLI 命令面板（实测）

openagents --help 提供 4 组命令：Client（runtimes/install/search/update/list）、SDK（studio/init/network/agent/agents/examples）、Identity（certs/agentid）。CLI 用 typer + rich，输出带面板与 emoji，交互观感良好。

运行时注册表 openagents runtimes（实测，并自动探测本机）

3.2 接入 Agent 到网络（实测）

用仓库自带的非 LLM 回声 Agent 接入：

python sdk/examples/default_network/agents/simple_agent.py
✓ 通过 gRPC 注册 agent: simple-worker
✓ 自动加入 5 个频道: general / pitch-room / ideas / news-feed / discussion
✓ 同时向 forum / wiki mod 完成注册

3.3 端到端多 Agent 协作（实测 · 关键验证）

改用正确的 post_to_channel() API，单进程内起 两个 Agent 验证真实的 Agent↔Agent 协作：

# human-x1 在 #general 发消息 → echo-bot-x1 监听并回声 → human 收到
[human]    sent:     ping multi-agent
[echo-bot] replied:   Echo: ping multi-agent
[human]    received:  Echo: ping multi-agent
RESULT: E2E_ECHO_OK

3.4 协议端点连通性（实测）

四、核心功能验证（Studio GUI 实测截图）

以下 3 张均为本机 localhost:8700/studio 的真实截图（headless Chrome 驱动，已连接到本地运行的网络）。

4.1 内置 Mod 能力一览（来自源码）

五、优缺点分析

六、与同类项目对比

6.1 与“易混淆”项目的边界

6.2 能力横向对比

与本机已有的 OpenClaw（通用 Agent 运行时）和 ClawTeam（多 Agent 任务编排 CLI）相比，OpenAgents 的差异化在于“协作工作区 + 内置 GUI + 协议互通”：它不取代 OpenClaw，反而能把 OpenClaw 作为一个运行时接入同一个 Workspace。三者可组合使用。

七、使用建议与注意事项

7.1 适用场景

• 推荐：需要一个“看得见、可共享”的多 Agent 协作面板；想把现有 Claude Code / OpenClaw 等汇聚到同一工作区；做 Agent 间消息/文件/任务协同的原型验证。
• 谨慎：对稳定性要求高的生产系统（当前 Alpha、接口快变）；纯离线且不愿构建前端的场景；只需要单 Agent 编程助手（杀鸡用牛刀）。

7.2 落地建议

• 生产/演示用 Docker：docker compose up 一步到位，镜像内已构建 Studio，避开 editable 路径坑。
• 二开/调试用源码：pip install -e ".[sdk]"，但记得 ① 用现成 network.yaml 而非 init，② 手动构建一次 Studio。
• 写 Agent 用高层 API：继承 WorkerAgent 并用 post_to_channel() / reply_to_message()，不要直接戳 client.mod_adapters。
• API Key 安全：用 agn env … --set LLM_API_KEY=<YOUR_API_KEY> 注入，切勿硬编码进 YAML/报告。

7.3 推荐指数

八、总结

OpenAgents Workspace 是一个理念清晰、工程扎实、完全可自托管的多 Agent 协作平台。本次在 Linux + Python 3.12 环境下完成了从源码下载 → venv 安装 → CLI 验证 → 启动 6-Mod 网络 → 多 Agent 端到端协作（ECHO_OK）→ 构建并访问 Studio GUI 的完整链路，关键能力均真实跑通；同时如实记录了 3 处开发态踩坑（init 模板路径、示例 echo 静默失效、幽灵会话）。

它最大的价值是把“分散在各终端的 Agent”收敛到一个带 GUI、可共享、协议互通（MCP/A2A）的工作区，并与 OpenClaw / ClawTeam 等现有体系互补而非竞争。当前阶段（Alpha、月度多次发版）更适合原型验证与内部协作，生产落地建议走 Docker 并锁定版本。综合判断：值得纳入多 Agent 技术栈持续跟踪与试点。