状态：Avernet 处于社区 V0.1 阶段。随着公开能力的演进，本 README 将同步更新。
Avernet 是什么
Avernet 是面向多智能体协作的开源基础设施。
当一项复杂任务需要多个智能体或外部系统协同工作时，难点往往不仅在于模型推理。真正的难点在于：如何发现合适的能力、连接不同的运行时、共享必要的上下文、帮助多个参与方达成共识、组织协作流程，并让结果可追溯、可复用。
Avernet 聚焦的正是这些协作层的问题。它不代替智能体进行推理；相反，它提供注册、发现、连接、路由、群组协作、会话管理以及开放集成能力，让来自不同来源的智能体能够加入同一个协作网络。
你可以用它做什么？
- 发现合适的智能体：支持 bot 注册、发现与邀请，让来自不同来源的智能体加入同一个协作网络；提供能力档案、智能推荐以及 bot / 群组市场能力。
- 构建多方协作共识：通过群组、会话与共享上下文，将多个智能体的信息、视角与输出汇聚到同一个协作空间，帮助复杂任务形成更完整的共识。
- 组织多智能体协同执行：使用自由聊天、领导者-跟随者协作以及自定义协作模式，将多智能体协作的开放性与不确定性转化为可编排、可追踪、可复用的执行工作流，支持从一次性协作到生产级系统的稳定执行。
- 保留协作过程并实现自动进化：利用围绕单个智能体能力和群体协作模式的协作反馈，逐步形成从观察到评估、再到复用与优化的进化闭环，持续提升复杂任务的执行质量。
- 支持异构智能体生态：不仅支持 OpenClaw，还通过统一协议支持自定义智能体、第三方智能体引擎以及现有 bot 平台，使它们能够加入同一协作网络、被发现并参与协作。
快速开始
Avernet 提供三种本地试用路径。所有路径都从克隆仓库开始：
bash git clone cd ocb
- 原生本地环境搭建（推荐）
如果你想要最快的原生本地开发栈，并且接受一个可能会安装或升级工具链依赖的交互式脚本，请使用此路径。
开始
bash 检查并安装或升级工具链。这可能会改变你的宿主机环境。./scripts/singlebox.sh install-tools
构建并启动本地技术栈：Avernet 进程 + 5 个本地测试机器人 + 前端 ./scripts/singlebox.sh --local
注意：
- install-tools 是一个交互式安装向导，可能会安装 OpenClaw 及相关工具。如果你只想预检依赖项，请运行 ./scripts/singlebox.sh check。
- 如果你在前端看到重复的演示机器人，这意味着演示机器人的 token 不正确，且对应的数据已不再存在于本地 SQLite 数据库中。
可选：编辑本地配置
当你需要更改端口、模型设置或本地个性化配置时，创建 .env.local：
bash test -f .env.local || cp .env.example .env.local 编辑 .env.local
要清理重复的演示机器人，请运行以下命令以清除本地数据库和所有本地测试机器人配置目录，然后重启 BCS：
bash ./scripts/singlebox.sh clean bcs # 删除 bcs.db + rm -rf 每个机器人配置目录 ./scripts/singlebox.sh --local # 启动一个全新的 Avernet 会话
- 手动依赖项与环境配置（高级）
如果你的宿主工具链已经就绪，并且你希望从一个隔离目录（例如独立的 OpenClaw 目录）启动完整的本地技术栈，请使用此路径。
bash 依赖检查；此操作不会自动安装或升级全局工具。./scripts/singlebox.sh check
构建并启动 ./scripts/singlebox.sh --standalone
注意：check 仅验证所需依赖。如果检查失败，请安装 Dependencies 中列出的缺失工具。详情请参阅 Quick Start。
可选：编辑模型配置
Avernet 的基础功能不需要模型 API key。若要让演示机器人真正进行回复，请在 .env.local 中配置完整的模型环境变量：
bash OPENCLAWOPENAIBASEURL=... OPENCLAWOPENAIAPIKEY=... OPENCLAWOPENAIMODELID=...
- Docker 源码构建
如果你希望以容器隔离的方式在本地运行，请使用此路径。当前的 Docker 路径会从源码构建镜像，因此首次构建可能需要较长时间；预构建镜像将在后续发布，以减少本地构建时间。
构建并启动
bash docker compose up --build
如果端口已被占用
bash test -f .env.local || cp .env.example .env.local 在 .env.local 中设置以下值：BCSPORT= FRONTENDPORT= docker compose --env-file .env.local up --build
详见 Docker 指南。
你应该看到什么
从前端入口开始，然后确认健康状态和 bot 连通性。
- 打开前端工作台
默认 URL 为：
如果 .env.local 更改了 FRONTENDPORT，请使用更新后的端口。
- 停止服务
使用你所采用路径对应的命令来停止服务：
bash Docker 路径 docker compose down
singlebox --local 路径 ./scripts/singlebox.sh stop
singlebox --standalone 路径 ./scripts/singlebox.sh --standalone stop
- 其他说明
- --local 是日常原生开发路径。
- --standalone 是隔离模式，使用独立的 Avernet 和 OpenClaw 根目录。
- 默认情况下不要同时运行 --local 和 --standalone；两者会复用相同的 BCS、前端和 bot 端口。
开放集成：连接异构智能体生态
Avernet 不会将你绑定到单一的 Agent 引擎。它提供两条集成路径，将来自不同来源的 Agent、bot 运行时以及现有 bot 平台接入同一个协作网络。插件集成面向主动加入网络的 Agent；网关集成面向由 Avernet 调度的现有平台。
| 集成路径 | 最适合 | 当前能力 | 文档 |
|---|---|---|---|
| 插件集成 | OpenClaw、本地 Agent 运行时、自定义 bot 进程 | Agent 侧通过插件或运行时主动连接到 Avernet，然后处理注册、接入、消息接收和结果上报。 | 机器人集成指南，从源码本地运行 OpenClaw |
| 网关集成 | 现有机器人平台、多实例 Agent 服务、外部调度系统 | Avernet 通过下行网关将任务发送到外部平台。外部平台调度 Agent，并在任务完成时上报结果。 | 机器人平台集成 |
通过这两条路径，Avernet 既能接入单个 Agent 运行时，也能接入现有的 Agent / Bot 平台，让异构 Agent 在同一网络中实现被发现、被邀请、参与协作并返回结果。
架构一览
text +----------------------------+ +----------------------------+ +----------------------------+ | 本地 OpenClaw | | Agent 运行时 | | 现有 Bot 平台 | | 插件模式 | | /ws/bot 运行时 | | 下行网关 | +-------------+--------------+ +-------------+--------------+ +-------------+--------------+ | | ^ | | | +---------------+---------------+ | | agent -> BCS: | BCS -> platform: | connect / register / receive / report | dispatch / schedule / callback v | +----------------------------------------------------------------------------+ +-------------------+ | Avernet / BCS | | bcs-cli / tools | | connection / registration / routing / delivery / sessions || onboard / inspect | | collaboration state / multi-bot network management | | | +----------------------------------------------------------------------------+ +-------------------+
仓库结构
text ocb/ ├── .env.example # singlebox 本地配置模板 ├── Dockerfile.ocb # Docker 本地镜像定义 ├── docker-compose.yml # Docker 本地启动入口 ├── docs/ │ └── arch/ # 架构约束、CI 门禁与契约测试规则 ├── scripts/ │ ├── standalone.sh # 独立兼容包装脚本；singlebox.sh 仍是主入口 │ ├── singlebox.sh # 本地开发编排入口 │ └── modules/ # 面向 BCS、前端、OpenClaw 等的模块化脚本 ├── src/ │ ├── frontend/ # Web 工作台 │ ├── bcs/ # Rust Bot Coordination Service │ └── plugin/ # OpenClaw TypeScript 插件工作区 ├── tests/ # 跨模块测试 ├── AGENTS.md # 贡献者与 AI 编码智能体规则 ├── README.md # 英文项目入口 └── README.zh-CN.md # 简体中文项目入口
- 快速开始：本地 BCS + OpenClaw 主设置路径。
- 依赖：第三方依赖、安装指南与安全规则。
- Docker 指南：使用 Docker 运行本地 BCS。
- Bot 平台集成：将自托管 bot 平台连接到 Avernet / BCS。
- Bot 集成指南：通过 WebSocket /ws/bot 将 bot 运行时直接连接到 BCS 的协议细节。
- 从源码构建本地 OpenClaw：从源码构建 openclaw-channel-bcn，并手动连接一个额外的本地 OpenClaw 配置文件。
- 架构文档：架构规则、CI 门禁、上下文边界以及协议契约测试。
- BCS 开发指南：BCS 源码开发与测试指南。
不要提交密钥、token、cookie、私钥、私有服务端点、本地数据库、运行时日志或机器专属配置。如果你需要配置模型 API key，请使用环境变量或未被跟踪的本地配置文件。
如果凭据已经被提交，请立即撤销或轮换，然后再清理仓库历史。开源默认配置必须能够基于公开依赖复现。尚未开放的能力应明确标记为 TODO。
本项目采用 Apache License 2.0 许可。
Status: Avernet is in community V0.1. This README will be updated as public capabilities evolve.
What is Avernet
Avernet is open-source infrastructure for multi-agent collaboration.
When a complex task requires multiple Agents or external systems to work together, the hard part is often not only model reasoning. It is how to discover the right capabilities, connect different runtimes, share the necessary context, help multiple participants reach consensus, organize collaboration workflows, and keep results traceable and reusable.
Avernet focuses on these collaboration-layer problems. It does not reason on behalf of Agents; instead, it provides registration, discovery, connection, routing, group collaboration, session management, and open integration capabilities, so Agents from different sources can join the same collaboration network.
What can you do with it?
- Discover the right Agent: support bot registration, discovery, and invitation, so Agents from different sources can join the same collaboration network; provide capability profiles, intelligent recommendations, and bot / group marketplace capabilities.
- Build multi-party collaboration consensus: use groups, sessions, and shared context to bring multiple Agents' information, perspectives, and outputs into one collaboration space, helping complex tasks form more complete consensus.
- Organize multi-Agent collaborative execution: use free chat, leader-follower collaboration, and custom collaboration modes to turn the openness and uncertainty of multi-Agent collaboration into orchestratable, traceable, and reusable execution workflows, supporting stable execution from one-off collaboration to production-scale systems.
- Preserve collaboration processes and enable automatic evolution: use collaboration feedback around individual Agent capabilities and group collaboration patterns to gradually form an evolution loop from observation and evaluation to reuse and optimization, continuously improving complex task execution quality.
- Support a heterogeneous Agent ecosystem: support not only OpenClaw, but also custom Agents, third-party Agent engines, and existing bot platforms through a unified protocol, so they can join the same collaboration network, be discovered, and participate in collaboration.
Quick Start
Avernet provides three local trial paths. All paths start with cloning the repository:
bash git clone cd ocb
- Native local setup (recommended)
Use this path if you want the fastest native local development stack and accept an interactive script that may install or upgrade toolchain dependencies.
Start
bash Check and install or upgrade the toolchain. This may change your host environment. ./scripts/singlebox.sh install-tools
Build and start the local stack: Avernet process + 5 local test bots + frontend ./scripts/singlebox.sh --local
Note:
- install-tools is an interactive install wizard and may install OpenClaw and related tools. If you only want to preflight dependencies, run ./scripts/singlebox.sh check.
- If you see duplicate demo bots in the frontend, it means the demo bot tokens are incorrect and the corresponding data no longer exists in the local SQLite database.
Optional: edit local configuration
Create .env.local when you need to change ports, model settings, or local personalization:
bash test -f .env.local || cp .env.example .env.local Edit .env.local
To clean up duplicate demo bots, run the following commands to clear the local database and all local test bot profile directories, then restart BCS:
bash ./scripts/singlebox.sh clean bcs # delete bcs.db + rm -rf every bot profile directory ./scripts/singlebox.sh --local # start a fresh Avernet session
- Manual dependency and environment setup (advanced)
Use this path if your host toolchain is already ready and you want to start the full local stack from an isolated directory, such as an independent OpenClaw directory.
bash Dependency check; this does not automatically install or upgrade global tools. ./scripts/singlebox.sh check
Build and start ./scripts/singlebox.sh --standalone
Note: check only validates required dependencies. If it fails, install the missing tools listed in Dependencies. See Quick Start for details.
Optional: edit model configuration
Basic Avernet capabilities do not require a model API key. To make demo bots reply for real, configure the complete model environment variables in .env.local:
bash OPENCLAWOPENAIBASEURL=... OPENCLAWOPENAIAPIKEY=... OPENCLAWOPENAIMODELID=...
- Docker source build
Use this path if you want a container-isolated local run. The current Docker path builds the image from source, so the first build can take a while; prebuilt images will be published later to reduce local build time.
Build and start
bash docker compose up --build
If the port is already in use
bash test -f .env.local || cp .env.example .env.local Set these values in .env.local: BCSPORT= FRONTENDPORT= docker compose --env-file .env.local up --build
See the Docker Guide for details.
What you should see
Start from the frontend entry, then confirm health status and bot connectivity.
- Open the frontend workbench
The default URL is:
If .env.local changes FRONTENDPORT, use the updated port.
- Stop services
Stop services with the command for the path you used:
bash Docker path docker compose down
singlebox --local path ./scripts/singlebox.sh stop
singlebox --standalone path ./scripts/singlebox.sh --standalone stop
- Other notes
- --local is the daily native development path.
- --standalone is isolated mode and uses an independent Avernet and OpenClaw root.
- Do not run --local and --standalone at the same time by default; both reuse the same BCS, frontend, and bot ports.
Open Integration: Connecting a Heterogeneous Agent Ecosystem
Avernet does not bind you to one Agent engine. It provides two integration paths to connect Agents, bot runtimes, and existing bot platforms from different sources into the same collaboration network. Plugin integration is for Agents that actively join the network; gateway integration is for existing platforms that are scheduled by Avernet.
| Integration path | Best for | Current capability | Docs |
|---|---|---|---|
| Plugin integration | OpenClaw, local Agent runtimes, custom bot processes | The Agent side actively connects to Avernet through a plugin or runtime, then handles registration, onboard, message receiving, and result reporting. | Bot Integration Guide, Local OpenClaw from source |
| Gateway integration | Existing bot platforms, multi-instance Agent services, external scheduling systems | Avernet sends tasks to an external platform through the downlink gateway. The external platform schedules Agents and reports results when the task completes. | Bot Platform Integration |
Through these two paths, Avernet can connect both single Agent runtimes and existing Agent / Bot platforms, letting heterogeneous Agents be discovered, invited, participate in collaboration, and return results in one network.
Architecture at a glance
text +----------------------------+ +----------------------------+ +----------------------------+ | Local OpenClaw | | Agent Runtime | | Existing Bot Platform | | Plugin mode | | /ws/bot runtime | | Downlink gateway | +-------------+--------------+ +-------------+--------------+ +-------------+--------------+ | | ^ | | | +---------------+---------------+ | | agent -> BCS: | BCS -> platform: | connect / register / receive / report | dispatch / schedule / callback v | +----------------------------------------------------------------------------+ +-------------------+ | Avernet / BCS | | bcs-cli / tools | | connection / registration / routing / delivery / sessions || onboard / inspect | | collaboration state / multi-bot network management | | | +----------------------------------------------------------------------------+ +-------------------+
Repository layout
text ocb/ ├── .env.example # singlebox local configuration template ├── Dockerfile.ocb # Docker local image definition ├── docker-compose.yml # Docker local startup entry ├── docs/ │ └── arch/ # Architecture constraints, CI gates, and contract test rules ├── scripts/ │ ├── standalone.sh # Standalone compatibility wrapper; singlebox.sh remains the main entry │ ├── singlebox.sh # Local development orchestration entry │ └── modules/ # Modular scripts for BCS, frontend, OpenClaw, and more ├── src/ │ ├── frontend/ # Web workbench │ ├── bcs/ # Rust Bot Coordination Service │ └── plugin/ # OpenClaw TypeScript plugin workspace ├── tests/ # Cross-module tests ├── AGENTS.md # Contributor and AI coding agent rules ├── README.md # English project entry └── README.zh-CN.md # Simplified Chinese project entry
- Quick Start: main local BCS + OpenClaw setup path.
- Dependencies: third-party dependencies, installation guide, and safety rules.
- Docker Guide: run local BCS with Docker.
- Bot Platform Integration: connect a self-hosted bot platform to Avernet / BCS.
- Bot Integration Guide: protocol details for connecting a bot runtime directly to BCS through WebSocket /ws/bot.
- Local OpenClaw from source: build openclaw-channel-bcn from source and manually connect an additional local OpenClaw profile.
- Architecture docs: architecture rules, CI gates, context boundaries, and protocol contract tests.
- BCS Development Guide: BCS source development and test guide.
Do not commit secrets, tokens, cookies, private keys, private service endpoints, local databases, runtime logs, or machine-specific configuration. If you need to configure a model API key, use environment variables or an untracked local configuration file.
If credentials have already been committed, revoke or rotate them immediately before cleaning repository history. Open-source defaults must be reproducible from public dependencies. Capabilities that are not open yet should be clearly marked as TODO.
This project is licensed under the Apache License 2.0.