1. 项目概述当Agent对Skill“视而不见”时最近在折腾一个基于国产大模型的AI Agent项目核心是想让Agent能像人一样根据任务需求灵活调用我给它准备好的各种“技能”Skill。我花了大力气用OpenClaw框架写了5个功能各异的Skill从数据查询到文件处理一应俱全。结果呢部署上去一测试Agent要么像个固执的木头人坚持用自己的基础能力硬扛要么就是胡乱尝试完全无视我精心编排的技能库。那种感觉就像你给一位大厨配齐了顶级厨具和精选食材他却非要用手和路边摊的调料来做菜让人既困惑又有点抓狂。这个项目标题“写了5个Skillagent一个都不用OpenClaw 国产模型的Skill调度踩坑实录”精准地戳中了当前AI Agent开发尤其是结合国产大模型和新兴框架时的一个典型痛点技能调度失灵。它不仅仅是代码报错更深层的是意图理解、技能匹配与执行链路中的逻辑断点。OpenClaw作为一个新兴的、对国产模型友好的Agent框架其设计理念和实现细节与我们所熟悉的LangChain、AutoGen等有诸多不同。而国产大模型在函数调用Function Calling、工具使用Tool Use方面的能力特性和“脾气”也与GPT系列模型存在差异。这两者结合就形成了一个充满“暗坑”的新领域。本文旨在复盘这次完整的踩坑历程。我不会只停留在“如何安装OpenClaw”或“如何定义一个Skill”的浅层教程上而是会深入拆解从Skill定义、Agent配置、模型调用到调度决策的完整链条。我会详细分析Agent“不用”Skill的几种典型表现及其背后的根本原因并分享最终让5个Skill“各司其职”的解决方案和调试心法。无论你是刚开始接触OpenClaw和国产模型Agent开发还是在技能调度上遇到了类似瓶颈希望这篇来自一线的实战记录能帮你少走弯路。2. 核心困境拆解为什么Agent对Skill“无动于衷”在开始技术细节之前我们必须先厘清问题现象。Agent“不用”Skill并非一个单一错误而是多种故障模式的表现。根据我的踩坑经验主要可以归纳为以下三类每一类都指向调度链路中不同的环节。2.1 现象一Agent完全无视坚持“自力更生”这是最令人沮丧的情况。你给Agent一个明确需要特定技能的任务比如“请总结/data/report.pdf这个PDF文件的核心观点”。你已经写好了一个PDFSummarySkill它内部会调用PyMuPDF或langchain的文档加载器来解析并总结。但Agent的回复却是“我是一个语言模型无法直接访问或读取本地文件。您可以手动打开文件将内容复制给我我来帮您总结。” 它完全绕过了Skill退回到了基础语言模型的保守回答模式。根本原因分析意图识别与技能描述脱节Agent或者说其背后的LLM没有将用户的查询意图与你定义的Skill描述关联起来。这可能是因为Skill的description字段写得太模糊、太技术化或者与用户自然语言查询的常见表述方式不匹配。模型无法从“总结PDF文件”联想到“需要使用一个名为PDFSummarySkill的工具”。工具/技能列表未成功注入上下文在调用模型进行决策时框架没有将可用的Skill列表以模型能理解的格式通常是特定的JSON Schema或函数定义放入提示词Prompt中。模型根本“不知道”有这些技能可用。模型本身工具调用能力弱某些国产大模型在工具调用Tool Calling或函数调用Function Calling方面的指令遵循能力较弱。即使技能列表给对了模型也可能无法正确解析“现在你需要选择一个工具”这个指令或者其输出格式不符合框架的解析预期。2.2 现象二Agent错误调用“张冠李戴”这种情况比完全无视更进一步Agent意识到了需要调用工具但匹配错了。例如用户问“今天的天气怎么样”你有一个WeatherQuerySkill需要城市参数和一个WebSearchSkill通用搜索。Agent却可能调用WebSearchSkill并传入参数query“今天的天气怎么样”而不是更精准地调用WeatherQuerySkill并传入city“北京”假设能推断出城市。根本原因分析技能描述相似度干扰如果多个Skill的description字段都包含“查询”、“获取”、“搜索”等宽泛词汇模型在快速匹配时可能选错。它没有深入理解参数约束。参数提取与验证失效模型可能正确选择了WeatherQuerySkill但在提取参数city时失败或者提取的值如city“”在框架执行前验证不通过导致整个技能调用被回退或降级到其他技能。调度策略过于简单框架默认的调度策略可能只是简单的语义相似度计算如通过嵌入向量Cosine相似度缺乏基于参数完备性、技能历史成功率等更复杂的决策逻辑。2.3 现象三调用流程异常执行链路中断这是最隐蔽的一类问题。Agent正确选择了Skill也传入了参数但在执行阶段报错导致用户最终看到的还是失败或无结果。错误可能发生在Skill的代码逻辑内部如第三方API调用失败、Skill的输入输出格式与框架期望不符、或者Skill执行结果返回后框架在结果整合到对话上下文时出错。根本原因分析Skill实现代码有Bug这是最直接的原因。比如在FileReadSkill中没有做好文件路径安全校验或编码处理。依赖缺失或环境配置问题Skill依赖的Python包未安装或需要的外部服务如数据库、API密钥未正确配置。在OpenClaw中Skill通常作为独立模块运行环境隔离可能导致依赖问题。框架与Skill的接口契约不清晰OpenClaw对Skill的run方法应该接收什么参数、返回什么格式纯文本JSON是否有明确要求如果返回了一个复杂的Python对象而不是字符串框架可能无法处理。国产模型输出格式解析失败即使模型发出了正确的工具调用请求其输出格式可能不符合OpenClaw的解析器Parser的预期。例如一些模型返回的JSON可能有多余的标记、格式错误或者键名与框架定义的不一致导致解析失败技能调用被静默丢弃。注意区分这三类现象至关重要因为它们对应的调试方向完全不同。现象一重点查提示词和模型能力现象二重点查技能描述和调度策略现象三重点查代码实现和接口规范。我的5个Skill问题就混杂了以上所有类型。3. 技术栈深度解析OpenClaw与国产模型的特性要解决问题必须深入理解我们手中的“工具”。OpenClaw和国产大模型在这个场景下有哪些特性需要我们特别关注3.1 OpenClaw框架的设计哲学与关键组件OpenClaw并非LangChain的简单复制。它更强调轻量、模块化和对国产模型的深度适配。其核心调度流程可以简化为以下几步技能注册Skill Registration将编写好的Skill类在框架中注册。这不仅仅是导入还包括将技能的自然语言描述、参数Schema等信息存入一个中央仓库。意图理解与技能匹配Intent Matching当用户输入到来框架会将输入文本与所有已注册技能的描述进行匹配。OpenClaw早期版本可能使用简单的关键词匹配但更先进的版本会利用嵌入模型Embedding Model计算语义相似度生成一个候选技能列表。模型决策LLM Decision将用户输入、候选技能列表及其参数定义整合到一个精心设计的提示词中交给大语言模型LLM做最终决策。LLM需要输出“是否调用技能”、“调用哪个技能”、“技能的参数具体是什么”。技能执行Skill Execution框架根据LLM的决策实例化对应的Skill类传入参数并执行其run方法。结果整合Result Integration将技能执行的结果通常是文本返回给LLM让LLM生成面向用户的最终回答。关键踩坑点技能描述Description这是匹配的“钥匙”。描述不能是代码注释式的“This skill is used to...”而应该从用户视角出发用自然语言描述技能能解决什么问题。例如WeatherQuerySkill的描述应该是“查询指定城市当前天气和未来几天的预报”而不是“调用某某天气API”。参数Schema定义OpenClaw通常使用Pydantic模型来定义技能参数。这里要极其严格参数名、类型、是否必需、描述字段description都必须准确。国产模型对格式要求有时比GPT更“挑剔”。提示词模板Prompt Template这是驱动模型决策的“大脑”。OpenClaw可能内置了模板但往往需要根据所用国产模型的特性进行微调。例如某些模型需要在提示词中更明确地指示输出格式“请严格按照以下JSON格式输出你的决策...”。3.2 国产大模型在工具调用上的“特殊习性”与GPT-4等模型相比我在使用通义千问、文心一言、DeepSeek等国产模型进行Agent开发时观察到一些需要特别注意的点格式遵循的严格性有些国产模型对输出格式的指令非常敏感。如果你在提示词中说“输出一个JSON”它可能真的只输出{}内容而忘记在对话上下文中它还需要说一些引导性的话。这可能导致框架的解析器找不到预期的JSON块而失败。解决方案通常是在提示词模板中提供更精确的示例Few-shot。工具描述的理解深度对于复杂的、参数多的工具国产模型有时会忽略一些参数约束或者错误理解参数类型。将参数描述写得极其简单、直白甚至枚举可选值往往比复杂的类型定义更有效。“拒绝”倾向当模型不太确定时它可能更倾向于拒绝调用工具而选择用自身知识回答。这需要通过提示词进行引导强调“当你需要最新信息、计算或操作外部资源时必须使用提供的工具”。上下文长度与成本国产模型的上下文窗口可能各异将大量工具的描述塞进上下文可能会挤占核心任务的理解空间或增加成本。需要设计更高效的技能检索Retrieval机制而不是每次都全量注入。实操心得不要假设国产模型能像GPT-4一样“智能”地理解工具。把它当作一个需要清晰、具体、有时甚至是重复指令的合作者。你的技能描述和提示词就是给它的“工作手册”。4. 从零到一构建一个能被“看见”和“用好”的Skill理论说再多不如动手写一个。下面我以一个真实的NewsFetchSkill新闻获取技能为例展示从定义到调试的全过程并穿插那些容易踩坑的细节。4.1 Skill定义的“魔鬼细节”一个健壮的Skill定义远不止一个run方法。以下是基于OpenClaw常见模式的代码示例并附上关键注释from typing import Dict, Any, Optional from pydantic import BaseModel, Field import aiohttp import asyncio # 1. 定义输入参数模型这是与LLM沟通的“合同” class NewsFetchInput(BaseModel): query: str Field(..., description需要搜索的新闻关键词例如人工智能、奥运会) max_results: Optional[int] Field( 5, ge1, le20, description最多返回的新闻条数最小1条最多20条默认为5条 ) # 注意描述字段要极度用户友好说明“是什么”和“限制” # 2. 实现Skill类 class NewsFetchSkill: # 技能名称保持简短、英文、无空格用于内部标识 name fetch_news # 技能描述这是最重要的部分从用户角度用中文写清楚能力。 description 根据提供的关键词从互联网上搜索并返回最新的相关新闻摘要和来源链接。当你需要获取实时信息或最新事件时使用此技能。 # 关联输入参数模型 args_schema NewsFetchInput def __init__(self): # 初始化操作如设置API端点、会话等 self.search_api_url https://news-api.example.com/search # 示例URL self.session None async def _create_session(self): if self.session is None: self.session aiohttp.ClientSession() return self.session # 3. 核心执行方法 async def run(self, query: str, max_results: int 5) - Dict[str, Any]: 执行新闻搜索。 注意run方法的参数名必须与NewsFetchInput模型的字段名完全一致 这是框架进行参数绑定的关键。 try: session await self._create_session() params {q: query, limit: max_results} async with session.get(self.search_api_url, paramsparams) as response: if response.status 200: data await response.json() # 4. 格式化返回结果建议返回结构化的字典便于框架和LLM处理 news_items [] for item in data.get(articles, [])[:max_results]: news_items.append({ title: item.get(title, 无标题), summary: item.get(description, ), url: item.get(url, #), source: item.get(source, {}).get(name, 未知), published_at: item.get(publishedAt, ) }) return { success: True, data: news_items, count: len(news_items), message: f成功获取到{len(news_items)}条关于{query}的新闻。 } else: return {success: False, error: fAPI请求失败状态码{response.status}} except Exception as e: # 5. 异常处理必须捕获异常并返回友好错误避免整个Agent崩溃 return {success: False, error: f技能执行内部错误{str(e)}} async def cleanup(self): 可选的资源清理方法 if self.session: await self.session.close()关键注意事项description是灵魂确保它涵盖了技能的核心功能、适用场景。多换几种用户可能的口吻来测试这个描述是否容易被匹配。参数描述要具体Field(..., description...)里的描述要写明参数的意义、格式、示例和约束。max_results的描述就是一个好例子。run方法签名必须匹配参数名query、max_results必须和NewsFetchInput模型定义的字段一一对应包括默认值。返回结构标准化建议始终返回一个字典至少包含success键。这样在调度层可以统一处理成功和失败方便做技能调用的降级或重试。异步支持OpenClaw通常运行在异步环境中如FastAPI所以Skill最好用async/await实现避免阻塞。4.2 技能注册与配置让框架“认识”你的Skill写好Skill类只是第一步接下来需要让OpenClaw框架知道它的存在。这通常在应用启动或Agent初始化时完成。# 假设在你的主应用文件如 main.py或Agent初始化模块中 from openclaw import Agent, SkillManager from my_skills.news_fetch import NewsFetchSkill from my_skills.weather_query import WeatherQuerySkill # ... 导入其他Skill async def setup_agent(): # 1. 初始化技能管理器 skill_manager SkillManager() # 2. 注册技能这里有个大坑 # 错误方式只注册类框架可能无法正确提取描述和参数。 # skill_manager.register(NewsFetchSkill) # 正确方式通常需要实例化并以名称-实例对的形式注册。 news_skill_instance NewsFetchSkill() weather_skill_instance WeatherQuerySkill() skill_manager.register_skill(news_skill_instance) skill_manager.register_skill(weather_skill_instance) # 或者使用批量注册方法如果框架支持 # skill_manager.register_skills([news_skill_instance, weather_skill_instance]) # 3. 验证注册是否成功打印已注册技能列表 print(已注册技能, skill_manager.list_skills()) # 输出应包含技能名称和描述检查描述是否正确加载 # 4. 创建Agent并注入技能管理器 agent Agent( llm_modelqwen-max, # 指定国产模型如通义千问 skill_managerskill_manager, # 其他配置如模型API密钥、温度等 ) return agent踩坑实录我曾遇到注册后skill_manager.list_skills()返回的技能描述是None。原因是我的Skill类description被定义为一个实例方法property而框架的注册逻辑可能只在类级别查找属性。解决方案确保name和description是类属性直接定义在类内部而不是__init__里。如果框架要求实例属性则在__init__中初始化self.description “...”。4.3 提示词工程教会Agent何时以及如何调用这是连接LLM与Skill的“翻译官”和“指挥官”。OpenClaw可能有默认提示词但为了适配国产模型我们常常需要自定义或微调。核心是修改或创建Agent的system_message系统提示词和tool_call_prompt工具调用提示词。以下是一个增强版的系统提示词示例你是一个强大的AI助手可以调用各种工具来帮助你完成任务。以下是你可以使用的工具列表 {skill_descriptions_formatted} 请遵循以下规则 1. 当用户的问题需要实时信息、计算、文件操作、专业查询等超出你固有知识范围的能力时**你必须**考虑使用上述工具。 2. 决定使用工具时请严格按照以下JSON格式回应 json {{ thought: 简要分析为什么需要使用工具以及选择哪个工具。, skill_to_use: 技能的唯一名称必须来自上述列表例如fetch_news, parameters: {{ 参数名1: 参数值1, 参数名2: 参数值2 }} }}如果用户的问题不需要任何工具或者工具不适用请直接以自然语言回答。工具的参数值必须是你从用户问题或对话上下文中推断出的具体值。如果缺少必要参数请向用户询问。现在开始对话吧。**关键点解析** - **{skill_descriptions_formatted}**这是一个占位符框架会在运行时将格式化的技能描述名称、描述、参数schema填充进来。确保这个列表清晰易读。 - **明确指令**使用“**你必须**”等强语气减少模型的犹豫和拒绝倾向。 - **结构化输出示例**提供具体的JSON输出格式示例这对于规范国产模型的输出至关重要。键名thought, skill_to_use, parameters必须与框架的解析器期待的一致。 - **思维链Thought**要求模型先输出思考过程这不仅能提高决策质量在调试时也是 invaluable 的日志让你知道模型“当时是怎么想的”。 **实操心得** 对于复杂的技能调度可以考虑两阶段提示。第一阶段让模型判断“是否需要工具需要哪个工具”第二阶段再让模型根据选定的工具参数schema来生成具体的参数值。这可以降低单次提示的复杂度提高国产模型响应的准确性。 ## 5. 调试与排错实战让5个Skill“复活”的完整流程 当你的Agent仍然不调用Skill时不要慌张。按照以下系统化的调试流程从外到内层层排查。 ### 5.1 第一步环境与基础检查 1. **依赖检查**确保OpenClaw及其所有依赖已正确安装。特别是检查与国产模型API交互的SDK如dashscope, qianfan版本是否兼容。pip list | grep -E (openclaw|dashscope|qianfan)。 2. **模型连通性**单独测试你的LLM配置是否能正常工作。写一个最简单的脚本不涉及Skill只调用模型进行对话确认API密钥、基础URL等配置正确。 3. **技能注册验证**在Agent初始化后立即打印或日志记录已注册的技能列表。确认你的5个Skill都在列表中且name和description字段正确无误。 ### 5.2 第二步观察决策日志定位故障环节 OpenClaw应该提供某种程度的日志输出。如果没有你需要手动添加。关键是在两个地方打日志 - **在技能匹配/决策后**打印出模型接收到的完整提示词包含技能列表以及模型返回的原始响应。这能帮你判断是模型没收到技能信息还是收到了但没理解。 - **在技能执行前后**打印出即将调用的技能名称和参数以及执行后的结果。 **示例添加决策日志** python # 在你的Agent执行循环或框架的决策钩子hook中 raw_prompt construct_prompt_with_skills(user_input, skills) # 假设这是构造提示词的函数 print([DEBUG] 发送给模型的提示词前200字符, raw_prompt[:200]) llm_response await llm_client.call(raw_prompt) print([DEBUG] 模型原始响应, llm_response) # 尝试解析响应 try: decision parse_llm_response(llm_response) # 假设这是解析函数 print(f[DEBUG] 解析结果技能{decision.skill_to_use}, 参数{decision.parameters}) except Exception as e: print(f[DEBUG] 解析模型响应失败错误{e}原始响应{llm_response})通过这个日志你就能清晰看到如果raw_prompt里根本没有你的技能描述问题出在技能信息注入环节。如果raw_prompt里有技能描述但llm_response是自然语言回答问题出在模型决策环节提示词指令不够强或模型能力不足。如果llm_response包含了类似工具调用的内容但解析失败问题出在输出格式解析环节。5.3 第三步针对国产模型的提示词微调如果日志显示模型收到了技能列表但未调用你需要强化提示词增加示例Few-shot Learning在系统提示词中直接提供2-3个“用户提问 - 模型决策调用工具”的完整示例。这是提升国产模型格式遵循能力最有效的方法之一。简化技能描述如果技能列表很长描述很复杂模型可能“看花了眼”。尝试暂时只注册1个最简单的Skill测试是否能被调用。如果可以再逐步增加并优化其他技能的描述使其更简短、更具区分度。调整温度Temperature和Top_p对于工具调用这类需要确定性的任务将温度调低如0.1减少模型输出的随机性。尝试不同模型如果条件允许换一个国产模型试试。不同模型在工具调用上的能力差异可能很大。通义千问最新版本、DeepSeek-Chat等在这方面都有不错的表现。5.4 第四步技能匹配策略调优如果模型决策正确输出了正确的技能名和参数但Agent最终没有执行该技能或者执行了错误的技能问题可能出在框架的匹配或执行层。检查参数绑定确保run方法的参数名与Pydantic模型定义完全一致包括大小写。框架通常通过反射或字典映射来绑定参数不匹配会导致参数传递失败技能可能被静默跳过。验证技能执行器有些框架包括OpenClaw的某些设计有一个“技能执行器”组件它负责将解析出的决策转化为实际的函数调用。检查这个环节是否有错误日志。你可以手动模拟调用await skill_instance.run(**parameters)看是否能成功。审查调度策略如果框架提供了可配置的调度策略如基于向量相似度的检索器检查其配置。例如相似度阈值是否设得太高导致所有技能都被认为“不相关”尝试调低阈值或改用更简单的关键词匹配进行测试。5.5 第五步技能本身的健壮性测试排除上述所有环节后如果技能调用触发了但最终失败问题就在Skill内部。单元测试为每个Skill的run方法编写独立的单元测试模拟各种正常和异常的输入。确保其内部逻辑、API调用、异常处理都是正确的。依赖隔离检查Skill的依赖是否与主应用环境冲突。考虑使用虚拟环境或确保所有依赖版本一致。超时与异步如果Skill涉及网络I/O确保设置了合理的超时并且异步操作正确。一个未处理好的超时或死锁会导致整个Agent请求挂起。我的5个Skill问题排查结果Skill 1 (文件读取)问题属于“现象三”。run方法返回了一个复杂的自定义对象框架无法序列化。改为返回字典后解决。Skill 2 3 (天气和新闻)问题属于“现象二”。两者的描述都用了“查询”导致模型混淆。将WeatherQuerySkill的描述改为“获取城市的具体天气状况包括温度、湿度和预报”将NewsFetchSkill的描述改为“搜索互联网上的最新新闻和媒体报道”区分度立刻显现。Skill 4 (计算器)问题属于“现象一”。模型认为简单的数学计算自己就能完成拒绝调用。在提示词中特别强调“为了确保计算的绝对准确性所有数学运算请使用计算器工具”并提高了该技能在列表中的优先级通过调整注册顺序。Skill 5 (数据库查询)问题属于混合型。既有参数Schema定义过于复杂嵌套模型导致模型提取参数失败也有API密钥在Skill初始化时未加载。简化Schema并将密钥管理移到Skill外部通过配置注入。6. 进阶优化构建更智能、更可靠的Skill调度系统当基础问题解决后我们可以追求更优的体验。以下是一些进阶优化思路能让你的Agent从“能用技能”进化到“善用技能”。6.1 实现动态技能检索与加载当技能数量膨胀到几十上百个时每次都将全部技能描述塞进提示词是不现实的。我们需要一个“技能检索”层。方案为每个技能的name和description生成嵌入向量Embedding存入向量数据库如Chroma, FAISS。当用户输入到来时先将其转换为向量然后从向量库中检索出最相关的Top-K个技能只将这些技能的描述注入提示词。好处大幅缩短提示词长度降低成本并可能提高匹配准确率减少了无关技能的干扰。OpenClaw集成可以自定义一个SkillRetriever类在构造提示词前介入替换掉默认的全量技能列表。6.2 设计技能调用的降级与回退机制不是每次技能调用都会成功。网络错误、API限制、参数错误都可能导致失败。一个健壮的Agent需要有应对策略。降级策略当首选技能调用失败时可以尝试一个更通用或更简单的备用技能。例如WeatherQuerySkill精确查询失败后可以尝试调用WebSearchSkill通用搜索去搜索天气。参数回退与澄清如果模型提取的参数缺失或明显错误如city“”框架不应直接失败而应该根据预定义的规则要么尝试使用默认值如果允许要么生成一个追问用户的问题如“您想查询哪个城市的天气呢”将对话引导至参数补全。实现方式在Skill的run方法中返回结构化的结果包含success,error,fallback_suggestion。在框架的调度层根据这些结果决定下一步动作。6.3 建立技能效果评估与反馈循环为了让Agent越用越聪明可以引入简单的反馈机制。成功率记录为每个技能维护一个历史调用成功率的计数器。用户隐式反馈如果用户在一次技能调用后紧接着说“不对”、“错了”或开始追问可以认为这次技能调用可能不成功或不满意相应调整该技能的权重或触发条件。调度策略优化基于成功率和反馈动态调整技能匹配的权重。高成功率的技能在相似度计算中获得加分频繁失败的技能则被暂时降权。6.4 与ComfyUI等可视化工作流结合从热搜词看到ComfyUI这是一个强大的AI工作流可视化工具。虽然OpenClaw是代码驱动的Agent框架但可以思考结合点。技能作为ComfyUI节点可以将一个复杂的Skill如图像生成后处理包装成ComfyUI的一个自定义节点。这样既可以在Agent中通过代码调用也可以在ComfyUI中通过拖拽节点来使用灵活性大增。ComfyUI工作流作为Skill反过来也可以将一整个ComfyUI工作流例如一个文生图-超分-风格迁移的管道封装成一个ComfyUISkill。Agent只需要提供文本描述该技能负责在后台启动ComfyUI并执行对应工作流最后将结果返回。这极大地扩展了Agent的多模态能力。7. 总结与核心避坑清单回顾整个让Agent“学会”使用Skill的历程从最初的完全无视到最终的精准调度核心在于理解整个链路的每一个环节并对其进行精细化的控制和调试。以下是我总结的终极避坑清单希望能帮你一次性通关描述即一切技能的description和参数的description是匹配的基石。用最终用户的自然语言来写强调功能、场景和区别。契约必须遵守Skill类的args_schemaPydantic模型与run方法的参数签名必须严格一致。一个字母的错误都可能导致调用失败。提示词是方向盘系统提示词必须清晰、强硬地指令模型使用工具并提供滴水不漏的JSON输出格式示例。对于国产模型Few-shot示例效果奇佳。日志是眼睛在决策、解析、执行的每一个关键节点添加详细日志。看不到内部状态调试就是盲人摸象。返回结构要统一Skill的run方法建议返回{“success”: bool, “data”: …, “error”: …}的标准结构便于上层统一处理成功、失败和降级。从简到繁逐个验证不要一次性写5个复杂的Skill。先写1个最简单的如“回显”技能确保它能被调用和执行。然后再逐步增加复杂度。理解你的模型花时间单独测试你所用的国产大模型在工具调用指令下的表现。了解它的“脾气”是喜欢简洁指令还是详细示例是严格遵循格式还是需要一些容错解析。环境与依赖是暗礁确保Skill运行的环境与主应用环境一致特别是Python版本和第三方库版本。使用requirements.txt或poetry严格管理依赖。最后Agent技能调度不是一个“一劳永逸”的配置而是一个需要持续观察、调试和优化的过程。随着技能库的扩大和用户 query 的多样化你可能需要不断回头调整描述、提示词甚至调度算法。但一旦打通了这个流程你的Agent就将从一个简单的聊天机器人进化成一个真正能够调动外部资源、解决复杂问题的智能体。这其中的成就感足以抵消所有踩坑时的郁闷。祝你在OpenClaw和国产模型的Agent开发之路上顺利前行。