English | 中文
Agentshire — 让你的 OpenClaw/QClaw Agent 住进你亲手搭建的3D游戏小镇，而不是ChatBox。
Agentshire 是一个支持OpenClaw/QClaw的插件，让 AI Agent 变成 3D 游戏小镇里活生生的 NPC——你可以观看、对话、也可以亲手改造这个世界。它融合了生活模拟与 UGC 工具：天气系统、昼夜循环、NPC 自主社交、地图编辑器、角色工坊。
同时支持 OpenClaw CLI 和 QClaw 桌面端。
⚠️ 兼容性说明
平台 版本 状态 OpenClaw CLI 2026.3.13 ✅ 推荐 QClaw 桌面端 0.2.x ✅ 支持 OpenClaw CLI 2026.3.7 – 3.12 ⚠️ 可能兼容 OpenClaw CLI 2026.4.x+ ❌ 暂不支持 — Channel 初始化存在回归问题 版本相关问题请查看故障排除。
一座小镇，不是仪表盘。
https://github.com/user-attachments/assets/c888d2ef-dcba-4caa-b0af-9b5f3e3b1365
造你的居民——选模型，赋灵魂，看他活过来。
https://github.com/user-attachments/assets/b9697432-b3ba-4e23-85fe-4c0b5c35a1b9
造你的小镇——拖拽搭建，一键预览。
https://github.com/user-attachments/assets/3328aa6c-3432-4f71-abfd-91aea4db15df
每个居民都有自己的想法。
https://github.com/user-attachments/assets/720a63fc-863c-483c-bfdf-5e07e82c6f0e
下达任务，居民集结。
https://github.com/user-attachments/assets/1983f60b-aaf6-4adc-b46c-5612e4ba4c83
干太久？班味 Boss 来了。消灭它。
https://github.com/user-attachments/assets/9be946e0-9ecf-42de-b793-a5d7ebe55612
任务完成。烟花庆祝。成品交付。
https://github.com/user-attachments/assets/fa6563ae-e78b-49b1-ae7b-8a8a96738341
/new /help /stop）插件随 QClaw 预装。如需更新：
openclaw-gateway 进程已完全停止）提示：你的数据（聊天历史、Agent 配置、管家工作区）存储在
~/.qclaw/，卸载重装不会丢失。
⚠️ 插件尚未发布到 npm。 请使用下面的 link 安装 方式。
# 1. 克隆仓库
git clone https://github.com/Agentshire/Agentshire.git
cd Agentshire
# 2. 构建前端
cd town-frontend && npm install && npm run build && cd ..
# 3. Link 安装到 OpenClaw
openclaw plugins install --link .
workspace-town-steward/）openclaw.json 中注册 town-steward Agentsubagents.runTimeoutSeconds: 600 — 子 Agent 运行超时 10 分钟，防止提前终止状态目录自动检测：OpenClaw CLI 为
~/.openclaw/，QClaw 为~/.qclaw/。重要：请勿在
openclaw.json中手动添加tools配置段。插件通过api.registerTool()注册工具。手动添加tools.allow列表会覆盖插件注册的工具，导致 Agent 无法使用。
QClaw 用户：卸载并重新安装插件，然后重启 QClaw。
OpenClaw CLI 用户：
cd Agentshire && git pull
cd town-frontend && npm install && npm run build && cd ..
openclaw plugins install --link .
然后重启 Gateway。
bash
openclaw gateway提示：如果浏览器没有自动打开，手动访问：
http://localhost:55210?ws=ws://localhost:55211
访问 http://localhost:55210/citizen-editor.html 打开居民工坊，创建和配置你的 NPC 团队。
访问 http://localhost:55210/editor.html 打开小镇编辑器，可视化编辑地图布局。
在你的 openclaw.json 中自定义端口和行为（OpenClaw CLI 为 ~/.openclaw/openclaw.json，QClaw 为 ~/.qclaw/openclaw.json）：
{
"plugins": {
"entries": {
"agentshire": {
"enabled": true,
"config": {
"wsPort": 55211,
"townPort": 55210,
"autoLaunch": true
}
}
}
}
}
| 配置项 | 默认值 | 说明 |
|---|---|---|
wsPort |
55211 | WebSocket 端口（插件与前端实时通信） |
townPort |
55210 | HTTP 端口（前端静态资源 + 编辑器 API） |
autoLaunch |
true | 启动时自动在浏览器中打开小镇 |
| 工具名 | 说明 |
|---|---|
town_announce |
在小镇广播消息 |
town_spawn_npc |
生成新 NPC |
town_effect |
触发视觉特效（庆祝/烟花/光圈等） |
town_set_time |
控制游戏时钟（设置时间） |
town_set_weather |
控制天气（12 种天气可选） |
town_status |
查看小镇当前状态 |
register_project |
注册简单项目（单 Agent 或管家独立完成） |
create_project |
创建多 Agent 项目目录 |
create_task |
创建单次委派任务目录 |
create_plan |
创建协作计划（分步骤并行执行，需先 create_project 或 create_task） |
next_step |
查询计划进度，获取下一步指令 |
mission_complete |
统一完成处理 — 自动判断触发庆祝结束或仅发交付物卡片 |
每个 NPC 都有独立的灵魂文件（Markdown），定义了角色的性格、说话风格、专长和工作方式。
灵魂文件格式：以 # 角色名 开头的 Markdown 文件，可包含元数据（模型 id、性别、岗位）、人设核心、性格详细设定、对话示例等。内容会作为 system prompt 注入 Agent。
搜索优先级（后者覆盖前者）：
插件内置/town-souls/ — 预设灵魂（8 个居民 + 管家）当前工作目录/town-souls/ — 项目级灵魂{状态目录}/town-souls/ — 用户自定义灵魂（~/.openclaw/ 或 ~/.qclaw/）town-data/souls/ — 居民工坊发布的灵魂你可以：
- 在居民工坊中 AI 一键生成灵魂文件
- 修改内置灵魂文件来调整角色性格
- 在状态目录的 town-souls/ 下放置自定义灵魂来覆盖预设
- 创建全新的灵魂文件来定义新角色
┌──────────────────────────────────────────────────────────┐
│ OpenClaw Runtime │
│ │
│ Gateway ─── Agent Sessions ─── Hook System ─── LLM │
└──────┬────────────────────────────┬──────────────────────┘
│ dispatch │ hook callback
▼ ▼
┌──────────────────────────────────────────────────────────┐
│ Plugin Layer (Node.js) src/plugin/ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ channel │ │ hook- │ │ws-server │ │ tools │ │
│ │ dispatch │ │translator│ │ WS:55211 │ │ 11 tools │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ plan- │ │ editor- │ │ citizen- │ │llm-proxy │ │
│ │ manager │ │ serve │ │ router │ │ 2 concur │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────┬───────────────┬───────────────────────────────────┘
│ WS :55211 │ HTTP :55210
│ AgentEvent │ Editor API
▼ ▼
┌──────────────────────────────────────────────────────────┐
│ Bridge Layer (Browser) src/bridge/ │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ DirectorBridge — Phase State Machine │ │
│ │ idle→summoning→assigning→office→working→publish→ret│ │
│ └────────────────────────────────────────────────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Event- │ │ Route- │ │ Citizen- │ │implicit- │ │
│ │Transltor │ │ Manager │ │ Manager │ │ chat │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────┬────────────────────────────────────────────┬──────┘
│ GameEvent (65) GameAction │
▼ (14) ▲
┌──────────────────────────────────────────────────────────┐
│ Frontend Layer (Three.js) town-frontend/src/ │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ MainScene ── EventDispatcher ── update() loop │ │
│ └────────────────────────────────────────────────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │workflow/ │ │ npc/ │ │ ui/ │ │ audio/ │ │
│ │Choreogr │ │ NPC 7-SM │ │ChatBubbl │ │ BGM+Amb │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ scene/ │ │ editor/ │ │ engine/ │ │ data/ │ │
│ │Town/Offc │ │Workshop │ │ Render │ │ Protocol │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────────────────────────────────────┘
开发者架构指南见 AGENTS.md。
# 克隆仓库后
cd agentshire
# 构建小镇前端
cd town-frontend && npm install && npm run build
# 开发模式（前端热更新）
cd town-frontend && npm run dev
# 运行测试
npm test # 插件 + 桥接层
cd town-frontend && npx vitest run # 前端
前端有 4 个入口页面：
| 页面 | URL | 说明 |
|---|---|---|
| 小镇主页 | index.html |
3D 小镇 + 聊天 |
| 小镇编辑器 | editor.html |
地图可视化编辑 |
| 居民工坊 | citizen-editor.html |
角色创建和配置 |
| 编辑器预览 | preview.html |
游戏级预览窗口 |
开发者架构指南见 AGENTS.md。
基础功能不需要额外下载——小镇、办公室、NPC 使用的内置模型（KayKit + Kenney）已包含在仓库中。
如果你需要以下高级功能，可以下载扩展资产包：
agentshire-assets.7z（约 164MB，解压后约 4.4GB）bash
cd /path/to/agentshire
7z x agentshire-assets.7zagentshire/
├── assets/
│ ├── Characters_1/ ← Library 角色模型 + 共享动画
│ └── Map_1/ ← Cartoon City 编辑器资产
├── src/
├── town-frontend/
└── ...
不下载资产包时：游戏正常运行，编辑器基础资产可用，居民工坊仅显示内置和自定义模型。
资产来源和许可证见 THIRD_PARTY_NOTICES.md。
现象：管家 Agent 无法找到 create_project、create_plan 等插件工具。
原因：OpenClaw 2026.3.13 中 Rollup 代码分割会创建独立的模块实例，导致 api.registerTool() 注册的工具对 Agent 运行时不可见。此外，openclaw.json 中手动添加的 tools 配置段会覆盖插件注册的工具。
解决：
1. 删除 openclaw.json 中的整个 tools 配置段（如果有）
2. 重启 Gateway
原因：关闭 QClaw 窗口不会停止后台 openclaw-gateway 进程。
解决：重启前先杀掉 gateway：ps aux | grep openclaw-gateway | grep -v grep | awk '{print $2}' | xargs kill
现象：插件加载成功但 WebSocket 连接未建立，小镇页面一直显示"连接中…"。
原因：OpenClaw 2026.4.x 在外部插件的 Channel 初始化流程中存在回归 Bug，defineChannelPluginEntry 生命周期未被正确调用。
解决：降级到 OpenClaw 2026.3.13。这是已知的上游问题。
现象：在角色工坊中点击"AI 生成"失败。
原因：灵魂生成接口需要 openclaw.json 中配置有效的 LLM 提供商。如果未配置或 API Key 无效，请求会失败。
解决：确保 openclaw.json 中有有效的 models 配置，详见 OpenClaw 文档。
Agentshire 这个名字的灵感来自《指环王》里的夏尔（Shire）。
夏尔最打动人的地方，从来不是宏大的史诗感，而是它的宁静、日常、缓慢、丰饶，与那种"这里适合好好生活"的感觉。是田野、小路、窗灯、饭香、邻里、散步、闲谈——一种不需要时刻战斗、时刻加速的存在状态。
今天很多 AI 产品对未来的想象，总是赛博朋克的、高压的、极度加速的。Agent 活在 dashboard 里，活在日志/接口里，却不像真正生活在某个地方。
但我想象的是另一种未来——一个更安静的未来，一个更温柔的界面。让智能体不只是被调用、被驱动、被消费，而是可以真正"住下来"的地方。
如果智能体会越来越进入我们的生活，那么它们也应该拥有一个像"家"一样的地方。
不是冰冷的机房，不是永远待命的控制台，而是一个有道路、有广场、有咖啡馆、有日常节奏的游戏小镇。
AI 的未来不一定非要长得像未来战场。它也可以像一个让人愿意住进去、也愿意让自己的 Agent 住进去的地方。
团队不住在仪表盘里。团队住在一座小镇里。
当孤岛连成大陆，小镇就长成了世界。
| 阶段 | 方向 | 状态 |
|---|---|---|
| 一座小镇 | 3D 可视化、工作流编排、灵魂系统、居民工坊、双模式界面 | ✅ 已实现 |
| 让小镇稳定运行 | QClaw + OpenClaw 兼容、双语 i18n、话题讨论、npm 发布 | 🔥 当前重点 |
| 让小镇活起来 | 编辑器打通、生活模拟（衣食住行玩）、成长体系、手机版 | 📋 下一步 |
| 连成世界 | 小镇联邦协议、跨镇 NPC 互访、技能交换、世界事件 | 🌍 远期愿景 |
详见 VISION.md 和 ROADMAP.md。
MIT
$ claude mcp add Agentshire \
-- python -m otcore.mcp_server <graph>