Agentshire：构建AI智能体3D小镇的实战指南与架构解析

1. 项目概述：当AI智能体住进你亲手搭建的3D小镇

如果你和我一样，对AI智能体的印象还停留在冰冷的命令行、单调的聊天窗口或是密密麻麻的API日志里，那么Agentshire的出现，可能会彻底颠覆你的认知。这不仅仅是一个插件，更像是一个“创世”工具。它的核心愿景，是让那些运行在OpenClaw或QClaw框架下的AI智能体，不再是一串抽象的代码或一个任务执行器，而是成为一个个有血有肉、有自己生活的“数字公民”，住进一个由你亲手设计、可以实时观察和互动的3D小镇里。

想象一下：你不再只是通过文本与AI对话，而是可以看着它以一个小镇居民的形象，在晨曦中出门散步，在雨天躲进咖啡馆，与其他“邻居”智能体在广场上讨论问题，然后接到你的任务后，集结伙伴，走进办公楼开始协作编程。任务完成后，小镇会为你燃放庆祝的烟花。这就是Agentshire试图构建的体验——一个将多智能体协作、游戏化交互与用户生成内容（UGC）深度结合的“活”的沙盒世界。

它完美兼容OpenClaw CLI和QClaw桌面应用，本质上是一个为这两个平台设计的插件。安装后，它会自动在你的本地启动一个3D小镇前端和一个实时通信后端。你的每一个AI子智能体（Sub-agent）都会自动映射为小镇里的一个NPC（非玩家角色），拥有独特的3D外观、性格（“灵魂”文件定义）和日常行为。你可以切换两种视角：在“小镇模式”下俯瞰众生，观察他们的生活与协作；在“聊天模式”下，像使用即时通讯软件一样与任何一个“居民”深入对话或下达指令。

这个项目的魅力在于，它模糊了开发工具、游戏引擎和数字孪生模拟器之间的界限。你既是在管理一个AI团队，又像是在经营一个充满生机的虚拟社区。接下来，我将带你深入这个奇妙世界的每一个角落，从安装部署到核心机制，从日常观察到深度定制，分享我一路摸索过来的实战经验和避坑指南。

2. 核心架构与设计哲学拆解

要玩转Agentshire，不能只停留在表面操作，理解其分层架构和设计意图至关重要。这能帮助你在遇到问题时快速定位，也能让你更自由地进行扩展和定制。

2.1 三层架构：插件、桥接与前端

Agentshire的代码结构清晰地分为三层，各司其职，共同构建了这个沉浸式体验。

第一层：插件层（Node.js）这是核心逻辑与OpenClaw/QClaw运行时对接的地方，运行在Node.js环境中。它的职责最重：

• 消息调度：监听来自OpenClaw网关的指令，并将其分发给对应的处理模块。
• 钩子翻译器：将OpenClaw内部的Agent生命周期事件（如消息发送、任务开始/结束）翻译成小镇能理解的“游戏事件”。
• WebSocket服务器：在默认的55211端口运行，这是与浏览器前端进行实时双向通信的生命线。所有Agent的思考、对话、动作指令都通过这个通道流动。
• 工具注册：向OpenClaw运行时注册了多达11个AI可调用的工具（如town_announce广播、town_set_weather设置天气）。这是AI能“控制”小镇的魔法接口。
• 计划管理器：负责解析复杂的多智能体协作计划，将其拆解为并行步骤，并协调执行顺序。
• 灵魂文件路由：管理所有NPC的“灵魂”（人格定义文件），处理从公民工作坊发布的新角色。

第二层：桥接层（浏览器）这一层运行在浏览器中，是连接后端插件逻辑和前端3D渲染的“中间件”。它最重要的组件是DirectorBridge（导演桥），这是一个状态机，严格定义了智能体工作流的每一个阶段：从空闲（Idle）到召唤（Summoning）、任务分配（Assigning）、进入办公室（Office）、工作（Working）、发布成果（Publish），最后返回小镇（Return）。这个状态机确保了整个协作过程像一场编排好的戏剧，每一步都有对应的视觉和音频效果。

第三层：前端层（Three.js）这是用户直接看到的3D世界，使用Three.js引擎构建。它负责：

• 场景渲染：渲染小镇、办公室、展示厅三种场景，包括建筑、道路、植被和所有NPC模型。
• NPC行为系统：每个NPC内部有一个包含7个状态（闲逛、行走、工作、社交等）的迷你状态机，驱动其日常行为。
• 工作流编排：接收桥接层的指令，播放对应的动画序列，如智能体集结时的冲击波、进入办公室的列队行走、编码时屏幕上的流光效果等。
• 用户界面：实现聊天气泡、状态卡片、编辑器等所有交互界面。
• 音频系统：动态合成环境音（雨声、风声）并管理背景音乐（BGM）的切换。

设计心得：这种清晰的分层解耦非常高明。插件层确保与AI框架的稳定集成；桥接层专注于业务流程控制，不关心具体渲染；前端层则全力打造视觉和听觉体验。这意味着，理论上你可以替换前端层的渲染引擎（比如用Unity），只要桥接层的协议不变，整个系统依然可以工作。

2.2 双模式行为系统：算法驱动与灵魂驱动

这是Agentshire在资源消耗和体验真实性之间做出的精妙平衡，也是其“活”起来的关键。

默认模式：算法驱动（零LLM成本）为了在不频繁调用大语言模型（LLM）的情况下让小镇“活”起来，Agentshire内置了一套基于规则和概率的行为系统。

• 行为模板：预设了5大类行为模板，如“咖啡爱好者”（喜欢在咖啡馆附近徘徊）、“工作狂”（在办公建筑前停留更久）等。
• 状态机与对话库：NPC的行为由一个简单的状态机控制，并在不同状态下从包含400多句预设对话的库中随机选取台词显示在头顶气泡中。
• 环境因子：天气、时间周期会影响NPC的行为概率。例如，下雨天NPC更倾向于躲进室内建筑附近。 这种模式的优点是性能开销极低，小镇可以一直运行，充满生机，而不产生任何API费用。

灵魂模式（Soul Mode）：AI驱动（需要LLM）当你需要更深度的互动时，可以启用此模式。此时，NPC的行为将由其“灵魂文件”和背后的LLM共同驱动。

• AgentBrain三层决策：
  1. L1 日常计划：LLM为NPC生成一天的大致安排（如“上午去图书馆，下午在公园见朋友”）。
  2. L2 战术决策：根据当前环境（时间、天气、附近其他NPC）决定下一步具体动作（如“现在开始走向图书馆”）。
  3. L3 对话生成：当玩家或其他NPC与之交互时，生成符合其性格的对话内容。
• 关系图谱与叙事摘要：NPC之间会形成记忆和关系，LLM甚至会为重要NPC生成每日的叙事摘要。 这个模式能带来极其丰富和不可预测的体验，但会持续消耗LLM的Token，适合在需要深度角色扮演或测试智能体社交能力时开启。

实操建议：对于日常挂机观察和大多数开发任务，使用默认算法模式即可。当你想要进行一场有深度的“圆桌讨论”或测试某个NPC的长期人格一致性时，再针对特定NPC或会话开启灵魂模式。你可以在公民工作坊中为每个角色单独配置是否启用灵魂模式。

3. 从零开始：完整安装与初始化指南

虽然官方文档提供了安装步骤，但在实际部署中，尤其是跨平台或特定版本环境下，有几个细节决定了成败。

3.1 环境准备与版本兼容性确认

这是最重要的一步，版本错误会导致插件根本无法启动。

1. Node.js版本：确保系统已安装Node.js 18或更高版本。建议使用nvm等版本管理工具，避免全局版本冲突。

   node --version # 确认版本 >= 18

2. OpenClaw/QClaw版本：这是核心依赖，必须严格匹配。
   • 首选（最稳定）：OpenClaw CLI2026.3.13。这是目前与Agentshire兼容性最好的版本。
   • 备选：QClaw Desktop0.2.x。如果你更喜欢图形化界面，这是一个不错的选择。
   • 警告：OpenClaw CLI 2026.4.x 版本存在一个已知的通道初始化回归错误，会导致WebSocket无法连接，小镇页面永远显示“连接中”。请务必避免使用此版本。
   • 可能工作：OpenClaw CLI 2026.3.7 – 3.12，但可能存在未知小问题。

踩坑实录：我最开始使用了最新的OpenClaw 2026.4.1，结果折腾了半天，小镇前端一直无法连接到后端。查看浏览器控制台网络请求，发现WebSocket连接一直在重试但无法建立。最后在项目的Troubleshooting部分和GitHub issue中才确认是上游版本问题。降级到2026.3.13后一切正常。所以，安装前第一件事就是确认你的OpenClaw版本。

3.2 两种安装方式详解

方式一：OpenClaw CLI 标准安装（推荐）这是最直接、最不容易出错的方式，适合绝大多数用户。

# 一条命令完成安装 openclaw plugins install agentshire

安装完成后，启动OpenClaw网关，小镇会自动在浏览器中打开。

openclaw gateway

安装后自动完成了什么？插件在首次启动时会进行一系列自动化配置，这些是透明发生的，但了解它们有助于排查问题：

• 在你的状态目录（OpenClaw CLI默认为~/.openclaw/，QClaw默认为~/.qclaw/）下创建管家（steward）的工作空间workspace-town-steward/。
• 在openclaw.json配置文件中注册名为town-steward的Agent。
• 添加路由规则，将所有发送到town频道的消息导向管家Agent。
• 将子智能体的运行超时时间设置为600秒（10分钟），防止大型任务执行时智能体被过早终止。

方式二：QClaw Desktop 安装（手动克隆）由于QClaw的插件管理机制不同，需要手动将插件克隆到扩展目录。

1. 找到扩展目录：这不是常见的插件目录，而是内置扩展的目录。

   # macOS ls ~/Library/Application\ Support/QClaw/openclaw/config/extensions/ # Linux (通常) ls ~/.config/QClaw/openclaw/config/extensions/ # Windows (通常) dir %APPDATA%\QClaw\openclaw\config\extensions\

   你应该能看到类似qclaw-plugin,lossless-claw这样的文件夹。
2. 克隆并安装依赖：

   cd <上一步找到的extensions目录> git clone https://github.com/Agentshire/Agentshire.git agentshire cd agentshire && npm install

3. 重启QClaw：完全关闭QClaw应用，再重新启动。小镇会自动打开。

重要提示：QClaw关闭窗口时，后台的openclaw-gateway进程可能不会自动退出。如果你修改了插件代码或配置，发现重启QClaw后没有生效，需要手动结束这个进程：

# Unix/Linux/Mac pkill -f openclaw-gateway # 或使用更精确的方式 ps aux | grep openclaw-gateway | grep -v grep | awk '{print $2}' | xargs kill

3.3 基础配置与首次运行验证

安装完成后，通常无需额外配置即可运行。但你可以通过修改openclaw.json文件进行个性化设置。文件位置：

• OpenClaw CLI:~/.openclaw/openclaw.json
• QClaw:~/.qclaw/openclaw.json

在plugins.entries.agentshire.config下可以添加：

{ "plugins": { "entries": { "agentshire": { "enabled": true, "config": { "wsPort": 55211, // WebSocket端口，如果冲突可修改 "townPort": 55210, // 前端HTTP服务端口，如果冲突可修改 "autoLaunch": true // 是否自动打开浏览器 } } } } }

首次运行验证：

1. 启动网关（openclaw gateway）或QClaw。
2. 浏览器应自动打开http://localhost:55210。如果没有，手动访问此地址。
3. 你应该能看到一个低多边形的3D小镇，里面有建筑、道路和几个走动的NPC。右下角有聊天窗口。
4. 在聊天窗口输入/help，查看可用命令。
5. 尝试输入“Hello, town!”，观察管家（Steward）的回复，以及回复是否以打字机效果显示在某个NPC头顶。

如果以上步骤都成功，恭喜你，你的AI小镇已经成功启动了！

4. 核心功能深度体验与实操

当小镇成功运行后，真正的乐趣才刚刚开始。下面我将分模块带你深入体验Agentshire的核心功能，并分享一些官方文档未提及的实用技巧。

4.1 小镇生活观察：昼夜、天气与NPC生态

启动后，不妨先什么也别做，静静观察几分钟。你会发现这个世界是“活”的。

动态时间系统： 小镇内部运行着一个独立的24小时时钟，但速度比现实快。它被划分为6个时段（如清晨、白天、黄昏、夜晚等）。不同时段，天空盒的光照、环境光颜色和强度会平滑过渡。到了夜晚，路灯和建筑物的窗户会自动亮起暖黄色的灯光，氛围感十足。

丰富的天气系统： 系统内置了12种天气类型：晴天、多云、雾、小雨、大雨、暴风雨、雪、暴风雪、沙尘暴、极光等。天气不仅影响视觉效果（雨滴、雪花粒子），还会触发对应的环境音效（通过Web Audio API实时合成，无需加载音频文件），并且会微妙地影响NPC的行为概率（比如下雨时更多NPC会躲到屋檐下）。

NPC的日常： 在默认的算法驱动模式下，NPC们遵循一套简单的规则生活：

• 移动：他们在道路和空地上随机寻路行走。
• 停留：偶尔会在某个建筑前或广场上停留一段时间，仿佛在思考或休息。
• 社交：当两个NPC靠近时，有一定概率触发简短的对话气泡（从预设库中随机选取），比如“今天天气真不错！”或“你听说新开的咖啡馆了吗？”
• 状态显示：点击任何一个NPC，会弹出他的状态卡片，显示头像、姓名、当前状态（闲逛、交谈等）和简单的日志。

观察技巧：你可以使用AI工具来主动改变环境，加深沉浸感。在聊天窗口尝试对管家说：“把天气改成下雨天”或“把时间调到晚上”。管家会调用town_set_weather或town_set_time工具，瞬间改变小镇的环境。这对于创造特定氛围或测试不同环境下的NPC行为非常有用。

4.2 与AI公民互动：从聊天到主题讨论

Agentshire的核心交互是与你创造的AI公民进行交流。

一对一聊天： 在“小镇模式”下，直接点击任何一个NPC，聊天窗口的对话对象会自动切换到该NPC。你可以像跟一个独立的智能体一样与他对话。他的回复会基于其“灵魂文件”中定义的人格，并且对话内容会以打字机效果流式显示在他头顶的气泡中，极具沉浸感。

发起主题讨论： 这是实现多智能体协作讨论的绝佳功能。在聊天窗口中输入/discuss命令，然后按照提示选择参与的公民（可以多选）并设定一个讨论主题（例如：“我们应该如何优化这个项目的用户登录流程？”）。

• 系统会创建一个临时的讨论组。
• 公民们会按照一定的顺序发言，每个发言都会显示在各自角色的头顶。
• 讨论是结构化的，由AI管家进行温和的引导，避免跑题或陷入循环。
• 讨论结束后，你可以要求管家生成一份讨论摘要。

实操心得：主题讨论功能非常适合用于头脑风暴或方案评审。你可以把具有不同专业背景（前端、后端、产品）的AI公民拉进一个讨论，就一个具体问题征求他们的意见。由于每个公民都有独立的“灵魂”和知识背景，他们往往会给出角度各异的回答，能有效拓宽你的思路。记得在讨论开始前，通过公民工作坊为参与者配置好相关的“专长”描述。

4.3 工作流全景：从任务下达到成果交付

这才是Agentshire作为生产力工具的精华所在——将多智能体协作可视化、仪式化。

1. 下达任务： 你不需要知道具体的智能体调用命令。只需在聊天窗口中像平常一样对管家说：“我们需要开发一个简单的待办事项网页应用，使用Vue 3和Tailwind CSS。” 管家（Steward）会理解你的需求，并自动调用create_project工具，在后台创建一个项目目录结构。

2. 智能体召唤与集结： 接着，管家会根据项目需求，从可用的公民中挑选合适的成员（例如，擅长前端的“艾拉”和擅长逻辑的“本”）。此时，小镇视角会拉近，一个魔法阵般的召唤特效出现在广场，被选中的NPC会从各处走来，在特效中心集结。屏幕上会出现“Rallying...”的提示。

3. 进入办公室与协作： 集结完成后，管家会说“Follow me to the office”。所有参与任务的NPC会排成一队，走向小镇中的办公楼。镜头跟随切换，进入“办公室”场景。这里有10个工位，每个工位都有发光的电脑屏幕。 每个NPC坐到自己的工位上，屏幕开始闪烁代码滚动的动画。在后台，OpenClaw的智能体们已经开始在真实的工作空间里编写代码了。

4. 实时进度与“班味”小游戏： 在办公室场景中，你可以看到每个NPC头顶显示他们当前正在执行的具体任务（如“Writing App.vue component”）。一个有趣的设计是“班味克星”小游戏：NPC在紧张工作时，身边会产生一些漂浮的“班味能量球”。你可以用鼠标点击戳破它们，获得连击分数。甚至偶尔会出现“班味老板”Boss，击败它会有特殊奖励。这个小游戏巧妙地缓解了等待代码生成时的枯燥感。

5. 成果交付与庆祝： 任务完成后，管家会宣布“Mission Complete!”。屏幕绽放烟花，NPC们欢呼。随后，一个成果预览卡片会弹出，展示这个待办事项应用。如果是网页应用，你可以直接在一个内嵌的iframe中预览和交互；如果是其他文件，提供下载链接。 最后，NPC们会离开办公室，返回小镇，继续他们的日常生活。整个工作流如同一场精心编排的舞台剧，极具成就感。

避坑指南：有时任务可能会卡住，比如某个子智能体超时或出错。此时，办公室场景可能会停滞。你可以：

1. 在聊天窗口输入/stop命令，强制终止当前任务流。
2. 检查OpenClaw网关的日志，查看具体是哪个环节报错（通常是LLM API调用失败或代码执行错误）。
3. 调整任务描述，使其更清晰、更可执行。然后重新开始。

5. 创造你的世界：UGC工具详解

Agentshire的强大之处在于，你不仅是观察者，更是创造者。它提供了一套完整的UGC（用户生成内容）工具，让你可以深度定制小镇的每一个方面。

5.1 公民工作坊：赋予AI灵魂与形象

访问http://localhost:55210/citizen-editor.html即可打开公民工作坊。这里是创造和定制NPC的地方。

核心步骤：

1. 选择/上传模型：
   • 基础库：插件内置了KayKit和Kenney提供的几个基础人物模型。
   • 扩展资产包：为了获得更多选择，强烈建议下载官方提供的可选资产包（约164MB，解压后4.4GB）。里面包含了308个带有多种变体和颜色的角色模型，从科幻战士到中世纪农民，应有尽有。将解压后的assets/文件夹放在插件根目录下，重启后即可在工作坊中选用。
   • 自定义模型：支持上传符合格式要求的GLTF/GLB 3D模型文件，让你的AI公民拥有独一无二的外形。
2. 编辑灵魂（核心）：
   • 这是定义AI公民内在人格的地方。灵魂是一个Markdown文件。
   • 你可以手动编写，也可以点击“AI生成”按钮，让LLM根据你的描述（如“一个喜欢园艺、说话温和、但涉及专业问题时非常严谨的软件架构师”）自动生成一份灵魂文件。
   • 灵魂文件结构示例：

     # 艾拉 (Ella) * 模型: female_developer_01 * 角色: 前端开发专家 ## 核心人格 一个充满好奇心、注重细节的前端工匠。相信代码不仅是功能，更是用户体验的桥梁。 ## 性格设定 - **语调**：友好、热情，喜欢用比喻解释技术概念。 - **价值观**：简洁、可访问性、像素级完美。 - **专业知识**：Vue/React生态，CSS-in-JS，性能优化，交互动效。 - **工作风格**：喜欢先画线框图，从组件树开始构建，对代码评审非常严格。 ## 对话示例 用户：这个按钮颜色感觉不对。 艾拉：嗯，你说得对。当前的 `#4CAF50` 在深色模式下对比度可能不足。我建议试试 `#66BB6A`，并增加一个聚焦状态的光晕，这样既符合WCAG标准，又不会破坏整体美感。就像给按钮戴上一顶会发光的小帽子！

3. 配置动画映射： 每个模型可能有多个动画片段（idle, walk, work等）。你需要将模型的动画名称映射到Agentshire内部定义的8个动画槽（闲置、行走、工作、庆祝等），这样NPC才能在正确的时机播放正确的动画。
4. 发布：点击发布后，这个新公民的灵魂文件会被保存，并且会自动注册为一个新的OpenClaw子智能体，立即出现在小镇中，可供你差遣。

5.2 小镇编辑器：打造独一无二的舞台

访问http://localhost:55210/editor.html打开小镇编辑器。这是一个功能完整的可视化3D场景编辑器。

编辑功能一览：

• 拖放放置：从右侧的资产库中，将建筑、房屋、树木、路灯、长椅等模型直接拖放到场景中。
• 变换操作：选中物体后，可以进行移动（G）、旋转（R）、缩放（S）操作，快捷键与Blender等主流软件一致，上手很快。
• 对齐与吸附：开启网格吸附功能，可以让建筑整齐地沿道路排列。
• 分组管理：可以将多个物体编组，方便整体移动或隐藏。
• 撤销/重做：支持完整的操作历史记录。
• JSON导出：可以将你编辑好的整个场景布局导出为JSON文件。注意：目前编辑器与运行时的集成还在进行中，导出的地图文件尚不能直接加载到实时运行的小镇里，但未来版本会支持。

编辑器预览： 编辑器的右上角有一个“预览”按钮，点击后会打开preview.html。这是一个独立的游戏预览窗口，你可以用WASD键控制镜头在小镇中自由飞行，实时查看昼夜循环、天气效果和车辆动画，就像在玩一个简单的模拟游戏。这对于调整场景氛围和光照效果非常有帮助。

设计经验：在搭建小镇时，考虑一下“功能分区”。比如，将办公类建筑集中在一个区域，将休闲娱乐的咖啡馆、公园放在另一个区域。这样不仅看起来更真实，当AI公民根据其行为模式活动时，也会显得更有逻辑。例如，你的“工作狂”公民会更多地在办公区附近出现。

5.3 灵魂系统进阶：优先级与自定义

理解灵魂文件的加载优先级，是进行高级自定义的关键。当同名的灵魂文件存在多处时，系统按以下顺序覆盖（后者优先）：

1. plugin-builtin/town-souls/– 插件内置的8个公民和1个管家的灵魂。
2. cwd/town-souls/– 你当前工作目录下的灵魂文件。这允许你为特定项目配置专属的AI团队。
3. {stateDir}/town-souls/– 用户全局自定义灵魂目录（~/.openclaw/town-souls/或~/.qclaw/town-souls/）。这是放置你常用自定义灵魂的最佳位置。
4. town-data/souls/– 从公民工作坊“发布”出来的灵魂文件。

自定义策略：

• 微调内置角色：直接复制内置灵魂文件到你的用户状态目录，进行修改。例如，你觉得内置的“本”太严肃了，可以复制他的文件，把语气改得幽默一些。
• 创建全新角色：在公民工作坊中从头创建，或者手动在~/.openclaw/town-souls/下新建一个.md文件，按照格式编写。只要文件名和模型匹配，重启后新角色就会出现在小镇中。
• 项目特定团队：如果你正在做一个机器学习项目，可以在项目根目录创建town-souls/文件夹，里面放置擅长Python和数据科学的AI灵魂。当在这个目录下启动OpenClaw时，小镇里就会是这个专家团队。

6. 常见问题排查与性能优化

在实际使用中，你可能会遇到一些问题。以下是我遇到并解决过的一些典型情况。

6.1 插件工具无法被AI识别

症状：在聊天中让管家创建项目或计划，它回复说找不到create_project或create_plan等工具。

原因与解决：

1. 配置覆盖问题（最常见）：如果你在openclaw.json中手动配置了tools部分，它会完全覆盖插件自动注册的工具列表。
   • 解决：检查你的openclaw.json，如果存在"tools": { ... }这个配置节，请整个删除它。插件是通过api.registerTool()动态注册工具的，手动配置会使其失效。删除后重启网关。
2. OpenClaw版本模块问题：在2026.3.13版本中，Rollup打包工具的代码分割特性可能导致插件注册工具的实例与Agent运行时看到的不一致。
   • 解决：确保使用推荐的OpenClaw 2026.3.13版本，并按照上述方法清理配置。如果问题依旧，可以尝试重新安装插件：openclaw plugins uninstall agentshire然后再次安装。

6.2 公民工作坊AI生成失败（500错误）

症状：在公民工作坊点击“AI生成”按钮创建灵魂文件时，页面提示服务器500错误。

原因：这个功能需要调用配置好的LLM服务（如OpenAI GPT、Claude等）来生成文本。如果你的openclaw.json中没有正确配置models部分，或者API密钥无效、额度不足，请求就会失败。

解决：

1. 检查你的~/.openclaw/openclaw.json文件，确保models部分已正确配置了至少一个可用的LLM提供商。例如：

   { "models": { "default": "gpt-4o", "entries": { "gpt-4o": { "provider": "openai", "config": { "apiKey": "你的实际API密钥", "baseURL": "https://api.openai.com/v1" } } } } }

2. 在命令行测试LLM配置是否生效：openclaw chat，看是否能正常对话。
3. 如果配置正确，查看OpenClaw网关的日志，通常会有更详细的错误信息，例如网络超时或鉴权失败。

6.3 小镇运行卡顿或浏览器崩溃

症状：小镇页面帧率很低，操作不跟手，或者加载复杂地图时浏览器标签页崩溃。

原因与优化：

1. 硬件要求：虽然Agentshire的前端经过优化，但毕竟是一个实时3D应用，对GPU有一定要求。集成显卡或较老的独立显卡可能压力较大。
2. 资产数量：如果你通过编辑器放置了成百上千个模型实例，会极大增加渲染负担。
3. 浏览器：某些浏览器对WebGL和大量WebSocket消息的处理效率不同。

优化建议：

• 使用性能更强的浏览器：Google Chrome或Microsoft Edge通常对WebGL和现代JavaScript性能优化得更好。
• 简化场景：在编辑器中，不要过度堆砌装饰性模型。尤其是那些高面数的模型。多用复制组，但注意控制总数。
• 关闭不必要的特效：未来版本可能会提供图形设置选项。目前可以尝试在浏览器开发者工具的Console中尝试寻找降低画质的隐藏参数（但需谨慎）。
• 升级硬件驱动：确保你的显卡驱动程序是最新版本。
• 限制帧率：如果找不到设置，可以尝试使用浏览器扩展强制限制该标签页的帧率（如60FPS），以减少GPU负载。

6.4 如何备份与迁移我的小镇和公民

Agentshire的所有用户数据都保存在你的状态目录下。

• OpenClaw CLI:~/.openclaw/
• QClaw:~/.qclaw/

你需要关注以下几个子目录：

• workspace-town-steward/：管家Agent的工作空间，包含项目历史、对话记录等。
• town-souls/：你自定义的所有公民灵魂文件。
• town-data/（如果存在）：从公民工作坊发布的数据。

备份：直接复制整个状态目录，或者至少复制上述几个文件夹。迁移：在新机器上安装好Agentshire后，首次运行前，将备份的文件夹覆盖到新机器的对应状态目录下即可。注意保持OpenClaw/QClaw版本一致。

7. 开发与扩展：深入插件内部

对于开发者来说，Agentshire本身也是一个优秀的开源项目，提供了清晰的架构和开发指引。

7.1 本地开发环境搭建

如果你想修改插件功能或前端界面，需要搭建本地开发环境。

# 1. 克隆仓库 git clone https://github.com/Agentshire/Agentshire.git cd Agentshire # 2. 安装插件依赖 npm install # 3. 构建前端（必须步骤，因为仓库中dist/可能不是最新） cd town-frontend npm install npm run build # 生产构建 # 或者使用开发模式，支持热重载 npm run dev # 4. 以链接模式安装插件到OpenClaw cd .. openclaw plugins install --link .

--link参数会创建一个符号链接，这样你在本地Agentshire/目录下的任何修改，都会实时反映到运行的插件中，无需重复安装。

7.2 前端入口与模块结构

前端部分 (town-frontend/) 采用Vite + TypeScript + Three.js技术栈，结构清晰：

• src/main.ts：主入口，初始化Three.js场景、渲染循环、UI。
• src/scene/：包含TownScene（小镇场景）、OfficeScene（办公室场景）等场景类。
• src/npc/：NPC相关的所有逻辑，包括状态机、行为树（未来）、动画控制器。
• src/workflow/：工作流编排器，负责处理从桥接层发来的状态机事件，播放相应的动画序列。
• src/ui/：所有UI组件，如聊天窗口、状态卡片、编辑器等。
• src/audio/：背景音乐和环境音效管理系统。
• src/bridge/：桥接层代码，负责与后端WebSocket通信。

四个主要的HTML入口文件：

• index.html：主小镇页面。
• editor.html：地图编辑器。
• citizen-editor.html：公民工作坊。
• preview.html：编辑器预览模式。

7.3 如何添加一个新的AI工具

假设你想让AI能控制小镇里的路灯开关，你需要：

1. 在后端插件注册工具：在src/plugin/tools/目录下创建一个新的工具文件，例如town_toggle_streetlight.js。定义一个符合OpenClaw工具规范的对象，包含name,description,parameters和execute函数。

   // 示例框架 export const townToggleStreetlight = { name: 'town_toggle_streetlight', description: 'Toggle a specific streetlight on or off.', parameters: { type: 'object', properties: { lightId: { type: 'string', description: 'The ID of the streetlight' }, state: { type: 'boolean', description: 'true for on, false for off' } }, required: ['lightId', 'state'] }, execute: async (args, context) => { // 1. 验证参数 // 2. 通过WebSocket向所有连接的客户端发送一个自定义事件 context.wsServer.broadcast({ type: 'GAME_ACTION', action: 'TOGGLE_STREETLIGHT', payload: { lightId: args.lightId, state: args.state } }); return `Streetlight ${args.lightId} turned ${args.state ? 'ON' : 'OFF'}.`; } };

2. 在插件主入口注册这个工具：在src/plugin/index.js(或相应的入口文件) 中，导入并注册这个新工具。

   import { townToggleStreetlight } from './tools/town_toggle_streetlight.js'; // ... 在初始化函数中 api.registerTool(townToggleStreetlight);

3. 在前端处理这个事件：在town-frontend/src/bridge/event-translator.js或相关的事件分发器中，添加对新事件类型TOGGLE_STREETLIGHT的处理逻辑，找到对应的路灯模型，改变其材质发光属性。
4. 重建与测试：运行npm run build重新构建前端，然后重启OpenClaw网关。现在你就可以在聊天中对AI说“打开广场上的路灯”，AI会调用这个新工具，并触发前端的视觉效果。

通过这个例子，你可以看到Agentshire良好的扩展性。你可以为其添加任何你能想象到的、连接AI与3D世界的交互能力。