这是一份面向第一次接触 Avernet、甚至不熟悉命令行的 macOS 教程。完成后,你会在自己的电脑上启动 Avernet、接入 6 个世界杯内容 Bot,从前端选择内置的“世界杯比赛前瞻内容生产”模板,绑定角色,提交一次自定义协作,并看到多 Bot 按固定流程完成内容生产。
部分截图来自旧版本;启动命令、配置文件和目录路径以本页正文及代码框为准。
本教程使用的模板源码是:
产品文案统一使用“自定义协作”。代码中的 state machine 是它的实现方式;旧资料里的“结构化协同”或“自定义协同”在本教程中都按“自定义协作”理解。
运行成功后,本机包含三部分:
6 个 Bot 分别是:
| Bot | 在流程中的职责 |
|---|---|
| 世界杯运营总监 | 明确选题目标、受众、平台、时长和整体制作方向 |
| 世界杯内容主编 | 整理任务简报并验收最终发布包 |
| 世界杯战术解说 | 设计战术看点、关键对位和通俗表达 |
| 世界杯赛事数据核查 | 核验赛程、球队、球员、历史交锋和数据口径 |
| 世界杯短视频编导 | 生成指定时长的口播稿和纯文字分镜 |
| 世界杯增长运营 | 生成标题、封面文案、发布包装和互动方案 |
模板执行顺序如下。战术分析和事实核查会并行进行,完成后再汇合到短视频脚本节点:
flowchart LR
A["世界杯运营总监<br/>安排制作方向"] --> B["世界杯内容主编<br/>整理任务简报"]
B --> C["世界杯战术解说<br/>设计战术洞察"]
B --> D["世界杯赛事数据核查<br/>核验选题事实"]
C --> E["世界杯短视频编导<br/>创作两分钟脚本"]
D --> E
D --> F["世界杯增长运营<br/>包装分发素材"]
E --> F
F --> G["世界杯内容主编<br/>验收最终发布包"]
仓库没有在本教程中规定更具体的 macOS 最低版本;建议使用仍在 Apple 安全支持范围内的版本。
要看到 6 个 Bot 真正生成内容,必须准备以下两种方式之一:
如果只选择 mock 模式,Bot 可以接入协作网络,但不会产生真实模型回复,因此不能完整复现这次演示。
请不要把 API Key 发到群聊、截图中或提交到 Git。手工配置时,只把它写入仓库中的 singlebox/.env.local;该文件用于本机配置,不应提交。
默认需要以下本机端口空闲:
| 端口 | 用途 |
|---|---|
| 8000 | Avernet 前端 |
| 21000 | BCS |
| 30401 | 世界杯运营总监 |
| 30411 | 世界杯内容主编 |
| 30421 | 世界杯赛事数据核查 |
| 30431 | 世界杯战术解说 |
| 30441 | 世界杯短视频编导 |
| 30451 | 世界杯增长运营 |
如果你不确定端口是否空闲,后面的检查命令会帮你确认。不要直接结束不认识的进程;先确认它属于哪个应用。
后续命令都在 macOS 的“终端”中执行:
代码框中不包含终端最左侧的提示符,不需要额外输入美元符号。

先检查 Git 是否已经存在:
git --version
如果看到类似 git version 2.x.x,说明可以继续。
如果提示 command not found,可运行:
xcode-select --install
macOS 会弹出安装窗口。完成 Command Line Tools 安装后,关闭并重新打开终端,再次运行 git –version。
在终端中运行:
git clone https://github.com/inclusionAI/Avernet.git
cd Avernet
第二行非常重要:它会让终端进入刚下载的项目目录。后续所有以 ./singlebox 开头的命令,都必须在这个目录中运行。
可以用下面两条命令确认当前位置和当前分支:
pwd
git branch --show-current
pwd 输出的最后一段应是 Avernet。仓库默认分支是 dev;如果功能尚未合入你当前的分支,请切换到包含本教程和世界杯模板的分支后再继续。
确认模板文件确实存在:
test -f apps/bcs/seeds/collaboration-templates/zh-CN/world-cup-preview-content-production.yaml && echo "世界杯模板已找到"
test -f singlebox/agents/6bots_world_cup_creator_profile/bots.json && echo "世界杯 Bot 配置已找到"
两行都应显示“已找到”。
当前 singlebox 默认使用本机隔离的运行目录,无需添加 --local 或 --standalone;--local 已移除。本教程使用默认的 legacy 前端(apps/frontend)。如果之前在 singlebox/.env.local 中选择了其他前端,请改为 FRONTEND_VARIANT=legacy 后再执行下文的 bcs_frontend 命令。
推荐让仓库脚本检查并安装缺失工具:
./singlebox/singlebox.sh install-tools
这个过程是交互式的。脚本可能会:
看到确认问题时,先阅读它准备安装的内容,再根据提示输入 y 或 n。为了完成本教程,Rust 1.91+、Cargo、protoc、Node.js 22+、npm、OpenClaw 2026.3.28+、jq、curl、lsof、pkg-config、OpenSSL 和 SQLite 开发库都需要可用。
第一次安装和构建会花较长时间,具体取决于网络和电脑性能。只要终端仍持续输出下载或编译信息,就先让它完成,不要关闭终端。
完成后执行依赖预检:
./singlebox/singlebox.sh check bcs_frontend
此时还没有编译 BCS,因此暂时不要执行 Bot 的完整预检;下一步编译完成后再检查。
更完整的工具说明见 macOS 依赖清单。

运行:
./singlebox/singlebox.sh setup bcs_frontend
这一步会:
首次执行通常是整个教程中耗时最长的一步。成功结束时,应看到 BCS setup complete 和 Frontend ready 一类提示。
现在再检查世界杯 Bot 的启动条件:
./singlebox/singlebox.sh check bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
预检应识别到 6 Bot manifest,并检查 30401 至 30451 这 6 个端口。
下面两种方式二选一。已经使用 OpenClaw 的读者优先选方式 A;只有模型服务参数的读者选方式 B。
先确认文件存在:
test -f ~/.openclaw/openclaw.json && echo "OpenClaw 配置已找到"
稍后启动 Bot 时选择:
3) home
脚本会明确显示它准备读取的文件路径,并提示该文件可能包含本地模型地址和 API Key。确认路径正确后输入 y。脚本只抽取模型相关字段到 singlebox 的本地运行配置中。
从示例文件生成本机配置:
test -f singlebox/.env.local || cp singlebox/.env.example singlebox/.env.local
open -e singlebox/.env.local
TextEdit 打开后,找到或加入下面三项,删除行首的 # 注释符号,并将等号右边替换成自己的真实值:
OPENCLAW_OPENAI_BASE_URL=https://your-model-service.example/v1
OPENCLAW_OPENAI_API_KEY=your-api-key
OPENCLAW_OPENAI_MODEL_ID=your-model-id
启动脚本自动读取的是 singlebox/.env.local,不会自动读取仓库根目录的 .env.local。如果你已有旧的根目录配置,请将需要的模型配置项复制到 singlebox/.env.local。三项均需填写非空值;选择 manual 只选择配置来源,不会交互式询问这些参数。
保存并关闭文件。稍后启动 Bot 时选择:
2) manual
不要把上面的 example 地址原样当成可用服务,也不要把真实 Key 写进教程截图。

运行:
./singlebox/singlebox.sh start bcs_frontend
这个命令只启动 BCS 和前端,不会启动默认 5 Bot,也不会询问模型配置。前端启动时会再次检查依赖;依赖已经是最新状态时会跳过安装,缺失或过期时会自动执行一次安装。
成功后,终端会显示本地服务已经就绪。可以另外确认状态:
./singlebox/singlebox.sh status bcs_frontend
预期结果:

保持 BCS 正在运行,然后执行:
./singlebox/singlebox.sh start bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
终端会出现:
Choose model config mode:
1) mock Use fixed-format local model replies
2) manual Use values from singlebox/.env.local
3) home Import model fields from ~/.openclaw/openclaw.json
脚本随后会准备 6 份隔离的 OpenClaw profile、连接 BCS、注册 Bot,并把它们设为可发现。等待命令成功结束后检查状态:
./singlebox/singlebox.sh status bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
6 个 Bot 都应显示 Running,并各自带有端口和 bot_uuid。

在浏览器打开:
在首页点击“进入 Avernet”。页面会在新标签页打开“我的协作”,实际地址通常是:
http://127.0.0.1:8000/bcn/chat/list
页面顶部会显示已接入的 Bot 标签。选择“世界杯运营总监”作为当前 Bot 视角。这样后面可以自然地把发起方绑定到 operations_director 角色。
如果顶部没有看到 6 个 Bot:

在“我的协作”页面左侧点击“拉起协作”。
在弹窗顶部填写:
界面上“自定义协作”旁会显示“状态机编排”,这是实现说明,不是另一个产品模式。
在“协同剧本”区域:
校验成功后,界面会显示“已解析 6 个角色”,并进入“角色绑定”区域。
这个模板不是手工上传的。BCS 本地模式会直接读取仓库中的模板目录,默认语言是 zh-CN,因此只要你使用的是包含该文件的最新代码并成功启动 BCS,它就会出现在前端模板下拉框中。


模板中的 participant 是逻辑角色,不存储某次运行生成的 bot_uuid。创建协作群时,需要在前端完成下面的绑定:
| 模板角色 key | 应绑定的 Bot |
|---|---|
| operations_director | 世界杯运营总监 |
| content_editor | 世界杯内容主编 |
| tactics_analyst | 世界杯战术解说 |
| script_director | 世界杯短视频编导 |
| fact_researcher | 世界杯赛事数据核查 |
| growth_operator | 世界杯增长运营 |
对每个角色重复以下操作:
特别检查:
当每个角色绑定按钮后面的“必填”标签变绿后,说明全部角色绑定成功。

接着在弹窗上方填写协作群名称和协作目标:
足球比赛自媒体撰稿室
下面使用虚构球队和明确的演示事实卡,不会把尚未核实的真实赛程、伤停或首发写成事实。复制到“协作目标”即可:
请为一场明确标记为“流程演示、非真实赛程”的世界杯风格比赛制作赛前前瞻自媒体内容。
【比赛选题】
星河队 vs 山海队,虚构演示赛。
【内容要求】
- 内容模式:赛前前瞻
- 目标受众:平时看球不多、但愿意在大赛期间了解比赛看点的普通观众
- 发布平台:抖音、B 站
- 目标时长:2 分钟
- 文风:专业但通俗,有画面感,不堆术语
- 核心目标:让观众快速理解双方风格差异,并愿意在评论区讨论胜负手
- 输出:完整口播稿、纯文字分镜、标题、封面文案、发布说明、标签和评论区互动问题
【本次演示唯一事实卡】
- 两支队伍和比赛均为虚构,只用于演示多 Bot 协作流程。
- 星河队的演示设定:偏好高位压迫和快速边路推进。
- 山海队的演示设定:偏好中低位防守和抢断后的快速反击。
- 星河队 10 号是组织核心;山海队 9 号是反击终结点。以上均为虚构设定。
- 不得补写真实世界杯赛程、真实球员、真实伤停、真实排名或博彩信息。
- 无法确认的信息必须标为未知或演示设定,不能伪装成真实事实。
请按模板既定流程执行,并由内容主编交付一个可直接进入人工复核的最终发布包。
如果要制作真实比赛,把上面“比赛选题”和“事实卡”替换为已经核验的公开信息,并补充:
真实比赛信息会随时间变化。提交前以赛事官网、足协、球队官方渠道或可靠数据源为准;不要把网络传闻当作事实卡。
填写完成后点击“创建协作群”,会按照协作模版创建自定义协作群,然后自动启动名为“新会话”的会话,会话根据上面填写的“协作目标”完成结构化任务。

一个协作群内可以创建多个会话,以达到复用协作群能力来解决相似任务的目的。
以当前 WAIC 世界杯赛前前瞻自媒体稿 Demo 为例,这个自定义协作群可以针对不同的比赛,内容风格,目标平台,和目标时长进行协作,按需生成新的内容。
假设你想生成另一场比赛的赛前前瞻稿,可以点击左边栏的“新建会话”按钮,并写入会话名称和协作目标,最后点击确认。这次服务调用会创建会话,并自动启动自定义协作。

执行开始后,页面会展示自定义协作的运行消息和节点状态。一次完整运行通常需要数分钟,具体取决于模型响应速度和网络情况。
模板默认行为包括:
不要因为中间几秒没有新消息就重复点击“确认”。重复提交会创建多次独立运行。
最终结果至少应能看到:
使用虚构输入时,成品必须持续标注“演示设定”,不能把星河队、山海队或虚构球员包装成真实世界杯事实。

在自由聊天和主从协作模式中,如果 Bot 认为参与当前会话的 Bot 无法完成用户需求,它会自主通过 bcs-coordination Skill 和 bcs-cli命令发现可用 Bot,寻找合适 Bot,然后自动拉群开始新对话。

演示结束后,先停止 6 个 Bot,再停止前端和 BCS:
./singlebox/singlebox.sh stop bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
./singlebox/singlebox.sh stop bcs_frontend
检查是否都已停止:
./singlebox/singlebox.sh status bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
./singlebox/singlebox.sh status bcs_frontend
stop 只停止进程,保留本地 Bot 身份、协作群和会话数据,方便下次继续。不要为了普通重启执行 clean;clean 会删除本地运行数据,只有明确希望从零重置时才使用。
下次复现通常只需要:
./singlebox/singlebox.sh start bcs_frontend
./singlebox/singlebox.sh start bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
确认你位于仓库根目录,然后执行:
chmod +x singlebox/singlebox.sh
./singlebox/singlebox.sh --help
当前启动脚本会在前端 start 前检查并安装一次依赖。先确认 Node.js 是 22 或更高版本,然后重新启动:
node --version
./singlebox/singlebox.sh start bcs_frontend
如果 npm 安装失败,查看终端中的第一个错误,而不是最后一行。常见原因是公共 npm registry 网络不可达、磁盘空间不足或本机 npm 配置异常。
说明还没有完成 setup,重新执行:
./singlebox/singlebox.sh setup bcs_frontend
成功后再启动 BCS 和 Bot。
最常见原因是启动 Bot 时选择了 mock,或者 manual 配置缺字段。
先停止 Bot,再使用真实配置重新启动:
./singlebox/singlebox.sh stop bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
./singlebox/singlebox.sh start bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
选择 2 或 3,并确认模型服务本身可用。
自定义协作当前需要以 Bot 视角创建。请确认:
依次确认:
test -f apps/bcs/seeds/collaboration-templates/zh-CN/world-cup-preview-content-production.yaml && echo "模板文件存在"
./singlebox/singlebox.sh status bcs_frontend
本地 BCS 使用文件型模板目录,模板列表在请求时读取。如果文件存在但页面仍没有显示:
确认 6 个 Bot 的状态都是 Running。角色绑定区域中切换到“可协作Bot”与“按名称筛选”,然后输入完整中文名称。
如果 Bot 状态异常,查看:
例如检查 8000 和 21000:
lsof -nP -iTCP:8000 -sTCP:LISTEN
lsof -nP -iTCP:21000 -sTCP:LISTEN
先识别进程是否属于当前 Avernet checkout。如果是本教程之前启动的服务,使用 singlebox stop;如果属于其他应用,关闭那个应用,或者在 singlebox/.env.local 中配置其他 FRONTEND_PORT 和 BCS_PORT。
Bot profile 的 30401 至 30451 端口目前来自 bots.json。修改它们属于进阶操作,并且需要保持 port_start 和 port_step 不与本机其他服务冲突。
本教程只启动 bcs_frontend 和世界杯 Bot,不需要 BCSFuse,因此不应进入 BCSFuse 依赖安装路径。不要用不带目标的 ./singlebox/singlebox.sh 代替本教程的显式命令。
如果你另外需要完整栈或 BCSFuse,请先更新到包含兼容性修复的最新代码;当前 setup 会自动选择低于 3.13 的兼容 Python 版本。
主要日志位置:
| 服务 | 日志 |
|---|---|
| BCS | singlebox/.dependencies/logs/bcs.log |
| 前端 | singlebox/.dependencies/logs/frontend.log |
| 世界杯 Bot 汇总 | singlebox/.dependencies/logs/bots_*.log |
| 单个世界杯 Bot | singlebox/.dependencies/logs/world-cup-*.log |
查看日志不会修改运行状态。例如:
tail -n 100 singlebox/.dependencies/logs/bcs.log
tail -n 100 singlebox/.dependencies/logs/frontend.log