基于OpenClaw框架构建AI技能助手：从中医穴位查询到实践部署

1. 项目缘起当剥龙虾遇上AI Agent最近在琢磨怎么把一些个人兴趣和AI技术结合起来搞点有意思又能实际用起来的东西。正好前两天在家剥龙虾处理起来挺费劲得一边看教程视频一边操作手上沾满了汁水想暂停或者回放都特别不方便。当时就想要是能有个“AI助手”在旁边我动动嘴皮子问“下一步怎么处理虾线”或者“这个部位能吃吗”它就能立刻给出准确的指导那体验就完全不一样了。这个想法其实可以延伸到很多需要“手眼并用”的场景比如维修家电、组装家具、学习乐器甚至是一些传统的手工艺。在这些场景里我们的双手被占用眼睛要盯着手上的活最自然的交互方式就是语音。而AI特别是具备多轮对话和上下文理解能力的Agent智能体正好能扮演这个“语音助手”的角色。顺着这个思路我决定动手实践一下。目标很明确构建一个能通过自然语言对话指导用户完成特定技能操作的AI Agent。为了增加点趣味性和文化内涵我选择了“中医技能”作为第一个试水的领域比如指导用户进行简单的穴位按摩、认识常见的中药材或者了解一些食疗方子。这既是一个有实用价值的技能库也符合当下大家对健康生活的关注用来起号做内容分享也很有潜力。整个项目的核心就是利用现有的AI Agent开发框架将一个非结构化的、需要经验传递的“技能”比如剥龙虾、找穴位封装成一个可以随时通过对话调用的“智能服务”。下面我就把自己从构思、选型到实现、调试的全过程以及踩过的那些坑详细记录下来。2. 技术选型为什么是OpenClaw与Agent框架确定了要做“技能型AI助手”后接下来就是技术栈的选择。市面上相关的工具和概念很多比如直接调用大模型的API、使用LangChain这类应用框架或者寻找更垂直的Agent开发平台。我的需求有几个关键点轻量且易部署个人项目最好能在本地或低成本云服务器上跑起来。支持技能Skill的封装与管理我希望能把“剥龙虾”、“按揉足三里”这样的具体操作流程写成一个个独立的、可复用的模块。具备记忆Memory能力对话不能是“金鱼记忆”需要记住上下文。比如用户问“我上一步做到哪了”或者“刚才说的那个穴位在哪条腿上”AI要能答上来。易于集成与扩展未来可能想接入飞书、微信等平台或者增加图像识别让AI“看”到你手上的动作是否正确的能力。基于这些需求我重点考察了OpenClaw和Hermes Agent这两个框架也参考了Claude Code、Skill Creator等概念。2.1 OpenClaw专为技能与Agent而生的开源框架OpenClaw在社区里的热度很高它不是一个通用的大模型而是一个专门用于构建、管理和执行“技能”的AI Agent框架。你可以把它理解为一个“技能操作系统”。核心理念它将复杂的任务分解为一个个可组合、可调用的Skill。每个Skill都是一个独立的函数或模块有明确的输入、输出和执行逻辑。例如“识别龙虾种类”可以是一个Skill“讲解虾线去除步骤”是另一个Skill。优势所在结构化清晰强迫你将模糊的指令转化为结构化的技能步骤这本身就是一个很好的工程化实践。易于管理所有技能集中注册和管理方便测试、更新和复用。与模型解耦它负责技能调度和逻辑判断具体的大模型能力如理解、生成通过配置来接入比如接入GPT、Claude或本地部署的Llama灵活性很强。为什么选择它对于我的“中医技能助手”项目我可以把“查询穴位位置”、“口述按摩手法”、“列出药材功效”等分别写成OpenClaw的Skill。当用户说“我肩膀疼按哪里”时OpenClaw的Agent会先理解意图然后调用“穴位查询”Skill再将结果用自然语言组织起来回复给用户。这种架构非常契合我的需求。2.2 Hermes Agent 与 其他Agent框架的对比Hermes Agent也是一个流行的AI Agent框架它更侧重于智能体的自主规划和工具使用。而LangChain/LlamaIndex则是更底层的链式编排框架。Hermes Agent它强调Agent的自主性适合完成“帮我写一份市场分析报告”这类需要自主拆解任务、搜索信息、整合输出的开放式目标。对于我这种步骤相对固定、流程明确的“技能指导”场景有点“杀鸡用牛刀”而且可能引入不必要的复杂性。LangChain功能强大生态丰富是很多AI应用的基础。但对于快速构建一个聚焦于“技能执行”的垂直应用来说直接使用LangChain需要自己搭建不少轮子比如技能路由、状态管理等。而OpenClaw在这方面提供了更开箱即用的抽象。最终决定以OpenClaw为核心框架来构建我的技能Agent。因为它最贴近“技能库”这个核心概念架构干净学习曲线相对平缓。大模型能力则通过配置一个可靠的API如OpenAI的GPT-4o或本地模型如通过Ollama部署的Qwen来提供。2.3 关于Memory记忆的实现无论是OpenClaw还是其他框架Memory都是关键组件。我需要的是Conversation Buffer Memory对话缓冲记忆或Summary Memory摘要记忆用来保存对话历史。在OpenClaw中通常可以通过配置来实现。它会将历史的对话记录作为上下文随每次请求一同发送给大模型。这意味着记忆功能实际上由底层大模型和框架的上下文窗口共同决定。一个实操细节对于长对话需要警惕上下文过长导致的问题如成本增加、模型性能下降。一种策略是只保留最近N轮对话或者将更早的对话总结成一段摘要。这在OpenClaw的Skill设计中可以通过自定义逻辑来处理。3. 实战构建“中医基础技能”Agent全流程确定了以OpenClaw为骨架下面就开始动手搭建。我的目标是创建一个能回答中医基础问题、指导简单操作的对话机器人。3.1 环境准备与OpenClaw部署首先是在本地开发环境搭建项目。我选择了Docker方式部署这样能避免复杂的依赖问题保持环境纯净。# 1. 拉取OpenClaw的官方镜像假设镜像名为openclaw/openclaw:latest docker pull openclaw/openclaw:latest # 2. 准备一个配置文件 config.yaml 和技能目录 skills/ mkdir my_tcm_agent cd my_tcm_agent mkdir skills touch config.yaml touch docker-compose.ymldocker-compose.yml文件内容大致如下用于定义服务version: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: tcm_skill_agent ports: - 8000:8000 # 将容器的8000端口映射到本机 volumes: - ./config.yaml:/app/config.yaml # 挂载配置文件 - ./skills:/app/skills # 挂载技能目录 - ./data:/app/data # 挂载数据目录用于持久化记忆等 environment: - OPENAI_API_KEY${OPENAI_API_KEY} # 通过环境变量传入API密钥 restart: unless-stoppedconfig.yaml是核心配置文件这里需要定义模型后端和技能路径model: provider: openai # 使用OpenAI的API name: gpt-4o-mini # 选用性价比高的模型 api_key: ${OPENAI_API_KEY} # 密钥从环境变量读取 skills: path: /app/skills # 技能文件存放路径 agent: name: TCM_Helper description: 一个提供中医基础知识和技能指导的助手。注意这里遇到了第一个坑。最初我尝试直接使用某些教程里提到的openclaw/crestodian这类标签的镜像结果拉取失败或运行报错。后来发现OpenClaw的镜像命名和版本更迭较快最稳妥的方法是去其GitHub仓库的Release页面或文档中查找最新的、稳定的镜像名称。直接使用latest标签有时会指向不稳定的开发版。3.2 编写第一个Skill穴位查询OpenClaw的Skill通常是一个Python文件里面包含一个继承了特定基类的类。我们来创建一个acupoint_query.py放在skills/目录下。# skills/acupoint_query.py import logging from typing import Dict, Any from openclaw.skill import BaseSkill # 假设OpenClaw的Skill基类叫这个 class AcupointQuerySkill(BaseSkill): 一个用于查询中医穴位信息的技能。 def __init__(self): super().__init__() self.name acupoint_query self.description 根据穴位名称查询其位置、主治功能和按摩方法。 # 一个简单的内置穴位数据库实际项目应使用外部数据库 self.acupoint_db { 足三里: { location: 小腿外侧犊鼻穴下3寸胫骨前嵴外一横指处。, functions: 健脾和胃扶正培元通经活络。主治胃痛、呕吐、腹胀、泄泻、便秘等胃肠疾病以及虚劳羸瘦、下肢痿痹。, method: 用拇指或食指指腹按压力度以感到酸、麻、胀为度每次按压5-10分钟每日1-2次。 }, 合谷: { location: 手背第一、二掌骨之间约平第二掌骨中点处。, functions: 镇静止痛通经活络解表泄热。主治头痛、目赤肿痛、齿痛、口眼歪斜、咽喉肿痛、热病无汗、多汗。, method: 用另一只手拇指指尖用力掐按每次1-3分钟。 }, # ... 可以继续添加更多穴位 } async def execute(self, arguments: Dict[str, Any]) - Dict[str, Any]: 执行技能的核心方法。 :param arguments: 包含用户输入等参数的字典。 :return: 包含技能执行结果的字典。 user_input arguments.get(input, ) # 这里可以写更复杂的NLP逻辑来提取穴位名初期我们先简单匹配 acupoint_name None for name in self.acupoint_db.keys(): if name in user_input: acupoint_name name break if not acupoint_name: return { success: False, message: 抱歉我没有在您的提问中识别到明确的穴位名称。请告诉我您想查询哪个穴位例如‘足三里在哪里’ } info self.acupoint_db.get(acupoint_name) if not info: return { success: False, message: f抱歉我的知识库中暂时没有关于‘{acupoint_name}’穴位的详细信息。 } # 组织回复内容 response f【{acupoint_name}】\n response f**位置**{info[location]}\n response f**主要功效**{info[functions]}\n response f**按摩方法**{info[method]}\n response \n温馨提示以上信息仅供参考不能替代专业医疗建议。如有严重不适请及时就医。 return { success: True, message: response, data: info # 也可以返回结构化数据供后续使用 }编写完Skill后需要在OpenClaw中注册它。通常是在一个主文件或配置中导入并注册。假设OpenClaw通过扫描skills目录自动注册我们需要确保Skill类的命名符合其规范。3.3 测试与调试让Agent“听懂”并调用Skill启动服务# 在项目根目录下设置API密钥并启动 export OPENAI_API_KEYyour-openai-api-key-here docker-compose up -d服务启动后我们可以通过API接口如http://localhost:8000/chat或OpenClaw可能提供的Web界面进行测试。核心是看Agent能否正确理解用户意图并路由到我们编写的acupoint_query技能。测试用例1用户输入“足三里穴在哪里”期望Agent识别出意图是查询穴位调用acupoint_query技能并传入“足三里”作为参数返回上述结构化的信息。测试用例2用户输入“我肚子不舒服应该按哪个穴位”期望这是一个更模糊的查询。理想情况下底层大模型GPT-4o应该能理解这是寻求治疗建议然后可能先调用一个“症状-穴位匹配”的技能如果我们编写了或者直接基于知识生成回答“针对一般的肠胃不适可以尝试按摩足三里穴它有健脾和胃的功效。它的位置是……”。这涉及到更复杂的意图识别和技能编排逻辑。踩坑记录在初期测试时我经常遇到技能未被调用的情况。排查发现有两个主要原因技能描述description不够精准OpenClaw的Agent依赖技能的name和description来判断何时调用它。最初我的description写的是“查询穴位信息”过于笼统。后来改为“根据穴位名称查询其位置、主治功能和按摩方法。”后模型匹配的准确率提高了。大模型提示词Prompt需要优化OpenClaw在将用户请求路由给技能前会用一个提示词Prompt来让大模型分析意图。默认的提示词可能不适合中医领域。我修改了配置在提示词中加入了“你是一个中医助手拥有以下技能……”的引导显著提升了意图识别的准确性。3.4 扩展更多技能与实现记忆有了穴位查询的基础我们可以如法炮制添加更多技能herb_query_skill.py中药材查询。massage_guide_skill.py分步骤引导按摩类似剥龙虾的步骤指导。symptom_analysis_skill.py根据症状进行初步分析需谨慎务必在回复中强调仅供参考不能替代医生。关于记忆Memory在OpenClaw的配置中我们可以启用对话记忆。这通常意味着Agent会自动将对话历史作为上下文附加到每次与大模型的交互中。对于技能执行类Agent记忆的关键在于跨技能的记忆用户先问“足三里在哪”然后问“怎么按它”。第二个问题需要Agent记住之前讨论的穴位是“足三里”。实现方式这很大程度上依赖于底层大模型的长上下文能力。在Skill的execute方法中我们可以通过arguments获取到当前的会话历史如果框架支持从而做出更精准的响应。更复杂的实现可能需要自己维护一个外部的对话状态存储。4. 从Demo到产品优化、部署与“起号”思考一个能跑通的Demo只是第一步。要让它真正可用甚至作为内容创作的“数字员工”还需要做很多优化。4.1 性能与稳定性优化技能响应速度如果技能需要查询外部数据库或调用慢速API要考虑异步操作和缓存。例如将穴位信息存入SQLite或轻量级数据库并在Skill初始化时加载到内存中。错误处理与降级网络波动、API限额、技能内部异常都需要被妥善处理。在Skill的execute方法中要有完善的try-except并返回友好的错误信息。甚至可以设置一个“兜底技能”当所有其他技能都无法匹配时由一个通用的、基于大模型知识库的聊天技能来响应。处理“幻觉”问题对于中医这类专业领域大模型的“幻觉”编造信息是致命伤。我们的策略是尽可能将核心知识固化在技能的内部数据或可靠的外部知识库中大模型主要扮演“理解用户意图”和“组织自然语言回复”的角色。对于技能数据覆盖不到的问题应明确告知用户“该问题超出我的知识范围”。4.2 部署与集成本地部署 vs 云服务个人学习可以用Docker本地部署。如果想作为7x24小时在线服务就需要购买云服务器如阿里云、腾讯云的轻量应用服务器将Docker服务部署上去并配置域名、SSL证书等。接入平台OpenClaw通常提供HTTP API。我们可以编写一个简单的微信机器人、飞书机器人或Telegram Bot这些机器人后端接收到用户消息后调用OpenClaw的API再将回复返回给用户。这就实现了“随时随地用语音或文字咨询中医小知识”。以飞书为例在飞书开放平台创建一个自定义机器人将其消息接收地址指向我们部署好的OpenClaw服务的/webhook/feishu端点可能需要自己编写一个简单的适配层即可在飞书群聊或私聊中使用这个Agent。4.3 内容创作与“起号”思路这就是标题中“边做个中医技能来起号”的由来。一个稳定运行的AI中医技能助手本身就是一个高质量的内容生成器和互动工具。内容素材库Agent在回答用户成千上万个问题的过程中会产生大量高质量的问答对。这些经过我们技能库“校正”过的问答本身就是极佳的图文或短视频素材。可以定期从日志中提取有趣、常见的问答加工成科普文章、信息图或短视频脚本。个性化IP延伸为这个Agent设计一个名字、头像和性格如“沉稳耐心的AI中医小学徒”。让它在你社交媒体账号如公众号、抖音、小红书的评论区充当“智能客服”回答粉丝关于中医保健的简单问题能极大提升账号的互动性和专业感。直播辅助工具如果你做中医养生类直播可以把这个Agent作为后台支持。当观众提问“主播刚才说的那个穴位怎么找”时你可以直接让助手给出标准答案你再来演示配合得天衣无缝。付费技能包将技能进一步深化和垂直化比如开发“儿童常见病家庭护理技能包”、“办公室肩颈放松技能包”等作为知识付费的轻度产品。4.4 遇到的典型错误与解决在开发过程中一些常见的报错和解决方案openclaw llamap svr operator(): got exception: { error: { code: 400 ...问题这通常是请求底层大模型API如OpenAI时出错可能是API密钥无效、请求格式错误、或模型参数不匹配。解决检查config.yaml中的模型配置和API密钥确认OpenClaw版本与模型API的兼容性查看更详细的日志定位具体错误信息。java: outofmemoryerror: insufficient memory/memory write error问题这类错误在本地部署大模型或处理大量数据时常见。Docker容器内存不足或者Java应用如果涉及堆内存设置过小。解决调整Docker容器的内存限制在docker-compose.yml中添加mem_limit如果使用Java组件调整JVM参数-Xmx优化技能代码避免一次性加载过大数据到内存。技能不被调用或调用错误问题Agent总是用通用聊天回复而不触发特定技能。解决首先检查技能文件是否放在正确的skills目录并被正确加载查看启动日志。其次精炼技能的name和description确保它们能清晰地被意图识别模块理解。最后优化Agent的提示词Prompt明确告诉它优先使用技能库来回答问题。构建这样一个AI技能Agent的过程就像教一个聪明的学徒。你需要把模糊的经验比如“剥龙虾”拆解成明确的步骤Skill为它准备好工具和数据知识库并设计好与它沟通的方式提示词和对话流。当它最终能流畅地指导用户时那种成就感不亚于成功剥出一只完整的龙虾。这个项目不仅让我对AI Agent的开发有了更落地的理解也真切地感受到AI与具体场景的结合能创造出许多提升效率和生活趣味的新可能。