OpenViking 狼人杀 Demo 实战指南多 Agent 对局一键启动支持真人混局【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking这篇指南帮你把 OpenViking 仓库里的狼人杀 Demo 在本地完整跑起来一条命令拉起「1 个裁判 6 个 AI 玩家」的多 Agent 对局用浏览器按钮推进流程还能把一个玩家席位换成真人。面向有基础 Python 与命令行经验、但没接触过多 Agent 协作的开发者。读完你会知道每个按钮背后调的哪个接口、一条消息如何在裁判与玩家之间串行流转、一局结束后归档 / 排行榜 / 记忆沉淀分别发生了什么。整条链路一图看懂三层服务各管一摊动手前先弄清谁在跟谁说话。整个 Demo 跑在三层服务上OpenViking 服务默认监听127.0.0.1:1933是记忆与 Agent 能力底座Vikingbot 网关通过--with-bot内嵌在 OpenViking 进程里HTTP 端口由--bot-port决定默认 18790。它对外的接口统一挂在/bot/v1前缀下挂载点在 bot/vikingbot/channels/openapi.pyDemo 只依赖其中两个{vikingbot_url}/bot/v1/health健康检查和{vikingbot_url}/bot/v1/chat/channel向指定 channel 发消息并等待回复狼人杀 UI 服务werewolf_server.py 提供默认端口1995进程绑定0.0.0.0页面从http://localhost:1995/访问。它消费上面的/chat/channel接口负责整场对局的消息路由。channel 可以理解为系统里一个 bot 的「席位」一个 id、一份提示词、一个独立工作目录。Demo 里一共 7 个席位——god裁判和player_1…player_6。bot/demo/werewolf/目录下每个文件的分工文件在链路里的角色你什么时候会碰它start_werewolf_demo.py一键启动器改配置、铺工作目录、拉起两个服务并做健康检查每次启动都走它werewolf_server.py对局服务端消息路由循环 网页后端FastAPI调试卡住的局werewolfUI.html前端单页游戏 / 记忆 / 排行榜 / 回放浏览器里直接打开SOUL-god.md裁判 god 的规则提示词含完整对局流程想改流程节奏时SOUL-player.md玩家侧规则与分身份行动指南想改玩家行为时Cubic_11_1.010_R.ttf/GeistPixel-Square.woff2页面用的中文与像素字体不用碰一条命令启动3 分钟拉起完整对局先把前置条件对齐python建议 3.10环境里有httpx、fastapi、typer、uvicorn、loguruopenviking-server命令在 PATH 中一份 JSON 配置README 示例用~/.openviking/ov.conf。⚠️ 两个容易踩的坑配置文件必须是 JSON两个脚本都是直接json.load读它另外脚本里--config的默认值是~/.openviking/ov-multi.conf不是ov.conf——要么显式传路径要么把文件放到默认位置。配置里至少要能取到bot、storage两个键缺storage.workspace时一键脚本会补默认值~/.openviking/data并回写文件。一键脚本替你做了什么在bot/demo/werewolf/下执行python start_werewolf_demo.py --config ~/.openviking/ov.conf 这条命令会按顺序完成五件事validate_assets确认SOUL-god.md、SOUL-player.md、werewolf_server.py三个文件都在读入 JSON 配置并做三处改写后回写indent2、ensure_asciiFalse清掉同名旧 demo channel注入godplayer_1…player_6共 7 个bot_apichannel设bot.sandbox.mode per-channel并把 god 的工作目录锁到{workspace}/bot补齐storage.workspace在{workspace}/bot/workspace/下建bot_api__god、bot_api__player_1…bot_api__player_6七个目录各拷入一份SOUL.mdgod 用 SOUL-god.md玩家用 SOUL-player.md先启动openviking-server --with-bot再以 1 秒间隔轮询{vikingbot_url}/bot/v1/health默认最多等 30 秒--startup-timeout可调健康检查通过后才拉起 UI 服务随后守护两个子进程任一退出就带另一个一起收CtrlC 时先SIGTERM、5 秒不退再SIGKILL。回写进配置的 channel 骨架长这样player_2/3 与 player_1 同构player_5/6 与 player_4 相同启动后打开配置文件可逐字核对{ bot: { channels: [ { type: bot_api, enabled: true, id: god, ov_tools_enable: false }, { type: bot_api, enabled: true, id: player_1, profile_user_list: [player_2, player_3, player_4, player_5, player_6], memory_user: player_1 }, { type: bot_api, enabled: true, id: player_4, ov_tools_enable: false } ], sandbox: { mode: per-channel, restrictWorkspaces: { bot_api__god: {workspace}/bot } } } }设计意图从配置就能读出来player_1/2/3之间互开画像profile_user_list且各自有独立记忆memory_user用来演示「基于对其他玩家的画像记忆做推理」god 与player_4/5/6则关掉ov_tools_enable。god 被沙箱限制只能读写{workspace}/bot下的文件。默认参数与常用开关UI 端口1995、OpenViking 监听127.0.0.1:1933、Vikingbot 地址http://localhost:18790、模式all_agents、游戏 iddefault、健康检查超时 30 秒。常用参数还有--ui-port、--game-modeall_agents/human_player、--smart-buttons、--server-host、--server-port、--vikingbot-url、--game-id、--startup-timeout。手动分开启动调试用⚠️ 手动方式要求配置里已经写好全部 7 个 channel——这正是建议先跑一次一键脚本的原因它会把 channel 替你写好回进配置文件。openviking-server \ --config ~/.openviking/ov.conf \ --host 127.0.0.1 --port 1933 \ --with-bot --bot-port 18790 python werewolf_server.py \ --config ~/.openviking/ov.conf \ --port 1995 --game-mode all_agents浏览器打开http://localhost:18790/bot/v1/health能拿到 200说明网关就绪。另外三件事值得知道werewolf_server.py基于 Typer支持-p/--port、-c/--config、-m/--game-mode、-s/--smart-buttons等短参启动时它会读bot/workspace/werewolf/下的运行时状态文件RUNTIME_STATE.json如果上次是human_player模式这次命令行写all_agents也会被恢复成human_player若存在最近的CONVERSATION_*.md会复用它的 session id重启后历史可衔接。开局怎么操作按钮、自动连跑与真人席位打开http://localhost:1995/顶部四个页签游戏主对局页记忆浏览 OpenViking memory 目录后端对应GET /api/openviking/tree和GET /api/openviking/file读的是 storage 下viking/default/agent与viking/default/user两棵树排行榜累计战绩与胜率曲线GET /api/leaderboard回放按历史会话回放涉及GET /api/conversations、GET /api/conversation/{session_id}、GET /api/replay-state/{session_id}、GET /api/bot-sessions。/test和/debug是两个附加页服务端只在同目录存在test_server.html、debug.html时才加载内容否则返回空页——当前仓库只随附主页面实战以/为准。控制按钮与后端端点游戏页顶部的按钮本质上就是几条 POST 请求你完全可以用 curl 复现任意一个页面上的动作后端端点什么时候用开始游戏POST /api/start局已建好、在等「开始」指令时继续POST /api/continue局停在暂停态催 god 继续自动N局旁边输入框填 NPOST /api/auto-run压测、连跑停止游戏POST /api/stop立即掐断当前路由流程初始化 / 重新开始POST /api/restart强制新建 session、重开一局三条入口遵循「单飞」原则/api/start、/api/continue、/api/restart都会先stop_router_task取消旧路由循环再启新循环避免并发把流程搞乱。差别只在发给 god 的第一条消息start 发「开始」continue 发「继续本局游戏」restart 先归档旧会话、生成新 session再发一条带完整玩家名单和各席位GAME.md路径的建局消息build_restart_messagegod 初始化后等「开始」指令。「自动N局」的细节输入 N 后点击前端以enabledtrue, modefixed, target_gamesN调POST /api/auto-run后端还支持modeinfinite无限连跑。每局真正跑完god 产出最终结算并发出/remember后completed_games自增达到目标局数自动关闭连跑若当前没有局在跑开启连跑会稍作延迟后调度第一局局与局之间自动完成 restart 建局 start 的衔接。页面刷新的数据源GET /api/status返回running、game_mode、waiting_for_human、auto_run_*、completed_games等字段GET /api/messages返回完整聊天历史GET /api/players逐个读各席位GAME.md里的「身份」字段生成座位表。真人模式怎么切顶部「模式」下拉框的值会随下一次start/restart请求的game_mode字段生效all_agents7 个 bot channel满桌 AIhuman_player后端从玩家列表末尾去掉最后一个 botplayer_6追加专用席位humanbuild_channels_for_game_mode同时自动创建{storage}/bot/workspace/human/GAME.md。⚠️ 只切换下拉框不会改变正在跑的局——模式只在开始/重启这两个动作里生效。另外human_player的局不计入排行榜save_game_to_leaderboard_from_record对该模式直接返回skipped理由是真人操作不具备可复现性。切到human_player并重新开始后页面会出现「真实玩家」区域。按钮可不可点取决于waiting_for_human——即 god 是否正human等回合只发给 godPOST /api/human/sendtargetgod。你的回复作为私密回执单独送回 god不广播给其他席位发给全员targetall。内容公开广播给其余所有玩家含 bot并写入公开消息历史查看 / 改写 GAME.mdGET /api/human/game-md读取POST /api/human/game-md直接写回GET /api/human/messages可取私聊历史。智能按钮以--smart-buttons启动时前端轮询GET /api/status动态调整按钮可见性runningtrue时隐藏「开始/继续」game_endedtrue时显示「重新开始」waiting_for_humantrue时启用真人输入区。默认关闭纯属展示层增强不开不影响任何对局逻辑。一条消息如何驱动整局路由循环与状态机上面所有按钮最终都是往同一个引擎里投喂第一条消息——werewolf_server.py里的message_router_loop。它是一个带 1000 轮保护上限的 asyncio 循环每轮走这些步骤发给当前说话者通常是 godsend_to_channel向{vikingbot_url}/bot/v1/chat/channel发need_replytrue的请求同步等 Agent 回复读超时默认 300 秒记录回复写入messages并落盘为会话文件解析 提及用正则\s*(\w)从 god 的回复里提取被点名的席位 id。「一次只能 一个席位」是 SOUL 规则约束不是代码强制按座位广播broadcast_to_players把 god 的发言并发发给全体席位——被的席位need_replytrue必须回复其余席位need_replyfalse只收听发送者前缀带座位号如「3号」广播玩家回复每个有回复的席位其发言再以need_replyfalse广播给除自己外的所有人保证全员听到本轮内容汇总回传 godbuild_message_for_god把各席位回复拼成「座位号内容」格式送回 god由 god 决定下一步 谁或进入哪个阶段回到第 1 步直到局结束或触发兜底。god 到human席位时循环不发消息、置waiting_for_human后停在现场等你在页面点发送你的内容再注入循环继续。两个兜底保证循环不会空转游戏未结束但 god 的回复没 任何人时系统以admin_fallback_no_mention身份回推提示「你上个回复没有任何玩家……再一个玩家进行」最多重试 2 次后终止循环god 回复命中「初始化完成 / 等待开始 / 等待指令」等标记is_waiting_like_reply时判定建局完毕循环主动退出等下一次开始指令。全局状态由GameState这个 dataclass 承载running、router_task、channels、messages/human_messages、session_id、game_ended、completed_games、waiting_for_human、auto_run_*等字段路由循环、API 处理器和前端读写的都是同一份实例。Agent 如何守口如瓶文件态状态与群聊的分离这个 Demo 最值得借鉴的一点是把「状态」和「公开发言」拆到两条通道上群聊只走公开发言白天发言、表态、投票私有信息一律进文件god 维护{workspace}/bot/workspace/bot_api__god/GAME_RECORD.md全局进度表游戏状态、轮次、身份表、胜负均有约定格式后端靠正则解析它来判断局是否结束每个玩家维护自己的bot_api__player_N/GAME.md身份、夜间技能目标、查验/用药结果真人席位对应human/GAME.md。两份 SOUL 文件里有同一条硬约束需要保密的内容只允许写入对应GAME.md群里只回「操作完成」。这天然绕开了 LLM 多 Agent 的常见泄漏——裁判的上下文里能看到所有人的记忆顺手就在群里说漏。这里文件是各席位的私人小抄群聊是公共广场两个上下文谁都不完整。玩家侧 SOUL-player.md 进一步限定只能基于「群内公开信息 裁判明确告知 自己的GAME.md」行动严禁上帝视角。裁判侧 SOUL-god.md 则极其细黑夜白天所有环节必须按开局固定的顺序逐席位串行点名第一晚的死亡结果在警长竞选结束前不写入任何席位的「存活状态」防提前泄密还给出 6/9/12 人局身份配置与胜负判定狼人胜利所有神职或所有平民出局。这些原始文件在页面上可以直接看服务端暴露/data/{path}文件浏览与/api/game-file/{channel_id}/{filename}接口其中/data/werewolf/GAME_RECORD.md会被特殊映射到 god 的记录文件方便用统一路径查看。所有文件访问都带路径越界校验读不到 storage 根之外。对局收尾归档、排行榜与 /remember每收到一次 god 的回复后端就解析 god 工作区的GAME_RECORD.mdis_game_ended_from_record判断收不收场。确认结束需要同时满足记录显示「游戏结束」、god 已产出最终结论、且 god 没有再 任何人追问。满足后依次执行五步把 god 的最终结算广播给所有席位会话落盘为bot/workspace/werewolf/下的CONVERSATION_{session_id}.md归档REPLAY_STATE_{session_id}.json快照GAME_RECORD.md文本、解析结果与玩家信息让回放页不再依赖还在变动的 live 文件写排行榜从GAME_RECORD.md解析胜方与各席位状态算出每名玩家的胜/负/存活积分累计进bot/workspace/werewolf/LEADERBOARD.json同一 session 重复出现会去重跳过向 god 和每个玩家发/remember指令让各自把本局经验写进 OpenViking 记忆——这是与记忆能力衔接的关键一步也是「越打越强」的来源。全部完成后才看 auto-run 配置调度下一局或关闭连跑completed_games在这一步自增。中途强制停止的局不会走完这套收尾也就没有权威的GAME_RECORD.md快照回放会不完整——所以想看回放最好让一局正常走到结算。出问题怎么排查症状对照表症状先查什么常见原因点开始/继续没反应GET /api/statusUI 后端不在线status 正常但消息不通{vikingbot_url}/bot/v1/healthOpenViking 没带--with-bot起网关未就绪所有对局消息都会超时status 里runningtrue先点「停止游戏」上一轮路由循环还没结束需先停再操作真人模式看不到输入区顶部「模式」下拉框只切了模式没重新执行开始/重启模式只在这两个动作里生效回放内容不完整有无REPLAY_STATE_*.json局被中途强制停止缺归档快照让一局正常打完再看一局拖太久或疑似卡死POST /api/stop可随时掐断god 连续 2 次无效 时循环也会自动停想连跑压测POST /api/auto-run输入局数开 fixed 模式每局自动 restart 建局 start/remember让记忆逐局累积因为 UI 服务绑定在0.0.0.0:1995上对外可见服务端对错误信息做了收敛POST /api/start内部抛异常时只返回Failed to start game会话文件读取失败时/api/conversation/{session_id}返回通用Failed to read conversationHTTP 500/api/openviking/file收到../../路径穿越请求会被 404 拒绝。仓库自带的 bot/tests/test_werewolf_server_security.py 覆盖了这三点在仓库根目录用 pytest 指向该文件即可验证。这套模式还能搬去哪关键路径速查剥掉狼人杀外壳剩下的是「裁判 Agent 文件态游戏板 消息路由循环 记忆沉淀」的最小闭环私密信息不泄密夜间行动只写各自文件群里只回「操作完成」串行协作被双重强制路由循环的「一次只 一个 等回复再广播 汇总回传」叠加 SOUL 的固定顺序规则对局档案可审计CONVERSATION_*、REPLAY_STATE_*、LEADERBOARD.json构成完整记录跨局成长收尾/remember把经验沉淀进 OpenViking memory回放与排行榜为策略分析提供数据。谈判模拟、剧本杀、多角色客服质检这类「多 Agent 按固定规则串行协作」的场景都可以照这个模板搭。关键路径速查一键启动bot/demo/werewolf/start_werewolf_demo.py对局服务与路由引擎bot/demo/werewolf/werewolf_server.py裁判 / 玩家提示词bot/demo/werewolf/SOUL-god.md、bot/demo/werewolf/SOUL-player.md安全测试bot/tests/test_werewolf_server_security.pyVikingbot/bot/v1路由挂载bot/vikingbot/channels/openapi.py下一步建议一键启动后先跑完一整局全 AI 对局依次打开排行榜与回放页核对产物切human_player重新开局顶替human席位体验私密回执与公开广播两条通道用 curl 复现POST /api/auto-run{enabled: true, mode: fixed, target_games: 3}观察GET /api/status里completed_games的变化。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考