企业官网建设流程全解析

上个月我给自己定了一个小目标：在 OpenClaw 里把日常能自动化的事情全部 Skill 化。一个月过去，写了 11 个 Skill，推倒重来了 3 个，最后真正留在线上的只有 7 个。这中间最让我花时间的，不是让代码跑起来，而是怎么把一个模糊的“想法”变成一个可靠的 Skill。今天就把这段时间对 Skill 的理解整理出来，给正在用 OpenClaw、或者正准备动手写自己的 Skill 的朋友一些参考。

1. 先摸清 OpenClaw 的脾气：Skill 在平台里的位置

1.1 OpenClaw 是什么

OpenClaw 是一个可以自己搭建的智能助手运行底座，你可以把它想象成一个带工具袋的管家。它本身不是什么都会干，但你可以给它配消息接入、知识库、定时任务、外部 API 这些能力。OpenClaw 的核心不是聊天，而是执行。用户跟它说一句话，它得知道该调用什么、参数填什么、结果怎么返回。这套“知道该调什么”的机制，正是 Skill 发挥作用的地方。

我最早接触 OpenClaw 时，以为它和普通聊天机器人差不多，无非是套了一层“能干活”的外壳。用了几天才发现，它在设计上是把“思考”和“执行”分开的：思考交给模型，执行交给 Skill。模型负责从用户的话里理解意图、抽取信息，Skill 负责实实在在地把事办成。这种分工明确之后，整个系统的稳定性比塞一堆 prompt 硬写的机器人高太多了。

1.2 Skill 的定位：不是插件，也不是工作流

很多人刚上手时会纠结一个问题：Skill、插件、工作流到底有什么不同？我自己也一度把它们混为一谈。实际跑起来之后，我的理解是：Skill 是一个原子化的能力单元，它只做一件事，把这件事做好；工作流则是把这些 Skill 串起来，编排成一个完整的闭环；插件则是更偏向于外部系统的连接器，负责和某个具体的外部系统打招呼。

我可以把一个最直观的对比放在这里：

看懂这个区别之后，很多设计决策就清晰了。比如我有段时间想把“查日程”和“安排日程”写进一个 Skill 里，因为逻辑上它们是一对。但真这么做之后，每次调用时不仅要传日期，还要传动作类型，模型经常搞混参数。后来拆成两个独立的 Skill，各自只干一件事，准确率一下子提上来了。

1.3 Skill 由哪几块拼成

把一个 Skill 拆开看，它其实由四部分组成：

• 元数据：告诉 OpenClaw “这个 Skill 叫什么、什么时候该被触发”。
• 输入定义：声明调用这个 Skill 需要哪些参数，每个参数怎么描述、什么类型。
• 执行逻辑：实际干活的部分，通常是一段 Python 代码，也可以是脚本或外部命令。
• 输出规范：给调用方返回什么结构的结果，让后续环节能稳定解析。

OpenClaw 里的 Skill 目录结构大概长这样：

skills/ my_skill/ skill.yaml main.py requirements.txt

skill.yaml 就是元数据和输入定义的声明文件，main.py 是执行逻辑。这种把声明和实现分开的做法，最大的好处是：模型不需要去看你的 Python 代码，它只需要读 skill.yaml 就能知道这个 Skill 能干什么、该怎么调用。这也解释了为什么我在后面会反复强调 yaml 里描述文本的重要性。

2. Skill 设计：好的 Skill 长什么样

2.1 从需求到设计：先定义“边界”

我写 Skill 最大的教训就是：一个 Skill 别贪多。你越想把一堆相关功能塞进一个 Skill，它越容易在真实对话里出各种幺蛾子。好的 Skill 一定是有明确边界的，它只解决一类问题。

举个例子。我想做个“日程管理”的 Skill，一开始图省事，把查、增、删、改全写在一个 Skill 里。结果用户说“帮我看看周五下午有没有空”的时候，模型会把“查”以外的逻辑也推理一番，偶尔还自作主张给你“顺带创建一条日程”。真是一言难尽。

后来我拆成“日程查询”和“日程写入”两个 Skill，边界非常清楚：查询的只负责返回结果，写入的才负责改动数据。这样每个 Skill 的参数都更精简，模型判断要不要触发时也更准确。设计 Skill 时，你面对的不只是一段代码，而是一段会被模型阅读理解的能力说明书。边界越清晰，说明书越短，调用准确率就越高。

2.2 参数设计是重中之重

我一度觉得 Skill 的代码才是最核心的，后来发现参数设计比代码更容易决定成败。OpenClaw 里的模型是从对话里抽取参数来填充 Schema 的，所以你在参数描述里怎么写，直接影响它能不能抽得准。

假设我要写一个“查天气”的 Skill，输入参数可能这么定义：

name: weather_query description: 查询指定城市当天的天气情况 parameters: - name: city type: string description: 城市名称，例如“北京”“上海” required: true - name: date type: string description: 查询日期，格式为 YYYY-MM-DD，不传则默认为今天 required: false

这里有几件事值得注意：“description” 不要写得含含糊糊，比如“城市”就不如“城市名称，例如‘北京’‘上海’”准确。模型在理解用户自然语言时，本质上是做文本匹配，你的描述越具体，它抽参数的命中率越高。

另外，必填参数和可选参数要分清楚。如果一个参数不是每次都必须有，就把它设置为非必填，并且在描述里说明缺省时怎么处理。我排查过很多“参数丢失”的情况，追到底通常是这个参数本身描述不够，或者它明明可缺省却被设计成了必填，导致整个调用失败。

2.3 触发与上下文：让 Skill 知道“何时出手”

Skill 的元数据里，name 和 description 决定了模型什么时候会调用它。这里有一个极其容易踩的坑：名字起得太短。

我刚写第一个 Skill 时，起名叫query，描述写的是“查询东西”。结果用户说“帮我在文档里查一下这句话是谁说的”，三个 Skill 同时触发：文档查询、网页搜索、数据库查询，乱成一团。后来我把名字改成doc_text_search，描述写成“在已导入的内部文档目录中搜索文本，返回文件名和上下文片段”，触发就精准多了。

除触发之外，上下文传递也很关键。Skill 不是独立运行的，它需要从对话上下文中拿到参数。如果用户在上一句说“帮我查一下魔都的天气”，下一句说“那明天呢”，这时候模型需要把“魔都”保留到上下文，并在第二轮补上“明天”这个日期。OpenClaw 处理这种上下文补全的能力，其实很大程度取决于你的参数描述和 Skill 描述提供了多少线索。换句话说，你的 Skill 说明写得越细，模型表现越聪明。

3. 动手写一个 Skill：从零到能跑的完整过程

3.1 环境准备：先把目录搭对

开始动手之前，先确认 OpenClaw 的运行环境是正常的。我用的是官方建议的安装方式，装好之后在项目根目录下会有一个skills/目录。所有自定义 Skill 都放在这个目录下，一个子目录就是一个 Skill。

我这边的组织方式是这样的：

skills/ weather_query/ skill.yaml main.py requirements.txt

skill.yaml 是最关键的一个文件，OpenClaw 通过它来感知 Skill 的存在。yaml 里的字段大致包括：name、description、parameters、output_schema、permissions 这些。刚上手时不要贪多，先写最小的 yaml，确认能被平台加载，再慢慢加字段。

我的第一个 weather_query skill.yaml 长这样：

name: weather_query description: 查询指定城市当天的天气情况，适用于询问气温、降水、风力等问题 parameters: - name: city type: string description: 城市名称 required: true - name: date type: string description: 查询日期，格式 YYYY-MM-DD，默认今天 required: false output_schema: type: object properties: city: type: string weather: type: string temperature: type: string permissions: network: - "https://api.example-weather.com/*"

这里我给 permissions 里配了一个外部天气服务的访问权限。这一点容易被忽略：OpenClaw 的 Skill 默认不请求外部网络，你如果不声明，代码里就算写了requests.get也会被拦截。权限声明是新手上路的第一道坎，但它同时也是安全保障，避免 Skill 乱访问地址。

3.2 用 Python 写核心逻辑

Skill 的执行逻辑我用 Python 写，OpenClaw 对 Python 支持最好。main.py 的骨架其实很简单：接收一个参数字典，处理逻辑，返回一个可序列化的结果。

一个不会出错的模板长这样：

import json import requests def run(params): city = params.get("city", "") date = params.get("date", "") if not city: return {"success": False, "error": "缺少 city 参数"} # 调用天气服务 API resp = requests.get( "https://api.example-weather.com/v1/weather", params={"city": city, "date": date}, timeout=8, ) resp.raise_for_status() data = resp.json() return { "success": True, "city": city, "weather": data.get("weather", "未知"), "temperature": data.get("temperature", "未知"), }

这段代码有几个地方是我特意注意的。一是params.get一定要给默认值，鬼知道模型会不会漏传参数，你直接params["city"]遇到缺失就直接崩了。二是timeout必须设，网络请求挂起会拖垮整个调用链。三是返回的结构尽量和 yaml 里 output_schema 对齐，这样后续如果要做二次加工，解析起来省很多事。

3.3 本地调试与验证：用三条命令跑通

写完之后先别急着让模型去调，我们自己在本地把 Skill 跑通。OpenClaw 有调试命令可以直接给 Skill 传参数，类似：

openclaw skill run weather_query '{"city": "上海", "date": "2025-01-15"}'

这条命令会直接执行 main.py，打印返回结果。调试的重点有两个：一个是参数传进去之后代码能不能正确处理，另一个是返回结果是否符合预期的 schema。

我调试时习惯先在本地用纯 Python 跑一遍核心函数，确认没有低级错误，再通过openclaw skill run做一次真实链路验证。日志输出里可以看到 OpenClaw 将参数解析成了什么样的 JSON，这能帮我判断 yaml 里参数描述写得是否合格。

提示：如果skill run提示找不到 Skill，先检查 skills 目录下的文件夹名、skill.yaml 里的 name 是否完全一致。大小写不一致是最常见的坑。

3.4 部署上线：热加载、权限与版本控制

本地跑通之后，部署就简单了。OpenClaw 支持热加载，修改 Skill 代码之后不需要重启整个服务，它会自动重新加载。不过在某些版本里，修改 skill.yaml 可能需要手动触发一次 reload 命令，具体看日志提示。

上线之前有两件事必须做。第一件是检查权限配置，只给 Skill 它真正需要的最小权限。我见过有人图省事，直接给network: "*"，这样虽然能跑，但一旦下个 Skill 写错了，风险面就非常大。第二件是把 skills 目录纳入版本控制。我是用 Git 管理整个项目目录的，每次改 Skill 都留一个提交记录，遇到改崩了随时回退。这个习惯帮我挽回过很多次。

4. 一个月里踩过的坑：常见问题排查实录

4.1 参数丢了：助手没把参数传进来

这是我最常遇到的问题，没有之一。表现是：模型明明理解了用户意图，也触发了正确的 Skill，但打开日志一看，params是空的，或者少了关键字段。

排查方法是从日志里看模型到底把参数解析成了什么。通常原因有三种：一是参数描述太抽象，模型不知道该填什么；二是必填参数设计得太多，模型抽不全就直接放弃；三是参数名和用户常用说法差距太大，比如用户说“魔都”，参数叫city_code，模型根本不知道这俩是一回事。

解法也很直接：把参数描述改成带示例的形式，尽量减少必填参数的数量，缺省逻辑在代码里做好。我后面在参数描述里都加了“例如”示例，命中率提升了非常多。

4.2 跑太久超时：同步任务扛不住

有一个 Skill 需要请求外部服务并等待返回结果，一开始正常，后来越来越频繁报超时。原因是外部服务偶尔响应慢，而 Skill 默认的同步调用是有超时限制的，超时之后整个调用失败，用户那边就收到一条错误提示。

我的处理思路是区分两种场景：如果外部服务通常 1~2 秒内能返回，那把代码里的 timeout 调短一点，比如 8 秒，快速失败，避免一直占用资源。如果确实需要长任务，就先返回一个“任务已受理”的结果，再去后台异步执行，把最终结果通过消息推送回来。这两种策略侧重点不一样，但都不要指望同步请求一直扛着。

4.3 权限不足：Skill 想访问外部服务被拦

第一次写带网络请求的 Skill 时，代码明明没问题，但就是报了一堆权限错误。我一开始以为是什么防火墙问题，后来查文档才发现，OpenClaw 的 Skill 出于安全考虑，默认不允许发起外部网络请求。这是设计上的取舍，不能让 Skill 随便连外网。

解法是在 skill.yaml 里声明 permissions，并把允许的域名写清楚。这里我提一个细节：声明的域名要写完整，如果 API 有多套环境（测试、生产），可能会不小心把测试环境地址漏掉，到时候调试阶段又会被拦一道。

4.4 Skill 之间互相污染

有一次我写了一个读取本地文件的 Skill，运行一次之后，另一个 Skill 开始时不时报奇怪的错误，日志里还出现了不属于它该访问的文件路径。排查了很久，最后发现问题出在全局变量上。两个 Skill 在同一个进程里跑，某个 Skill 代码里写了全局变量，被后面执行的其他 Skill 给改了。

从那以后，我写 Skill 有两个铁律：一个是不用全局变量，需要什么数据都在run(params)内部局部处理；另一个是尽量保证 Skill 之间不做任何隐式共享，哪怕访问同一个文件，也要通过参数显式传递路径。把每个 Skill 当成独立小程序来写，能避开绝大多数脏问题。

4.5 误触发：名字太短导致总是被调用

这个问题在 2.3 提到过，但值得单独拿出来说。Skill 元数据里的name和description会直接参与模型的理解过程。名字太通用，比如search、query、get_info，会让模型在多意向对话里挑错工具。

我后来给自己定了一条规则：Skill 命名要有明确的业务位面，描述里包含“什么时候用”“处理什么领域”“不处理什么”。比如：

name: issue_query_github description: 查询项目仓库里的 issue 列表和状态。仅用于技术项目问题追踪，不用于搜索引擎。

听起来很啰嗦？实际上，描述越具体，模型在模糊场景下越不容易误触发。这个做法和给参数写示例是一个道理，都是在给模型喂线索。

最后再分享一个小技巧

如果你也在用 OpenClaw 调 Skill，我强烈建议你专门写一个 echo_skill。它的作用只有一个：把接收到的参数原样返回。

name: params_echo description: 调试专用 Skill，原样返回所有参数，用于检查参数映射是否正确 parameters: - name: raw_input type: string description: 任意文本 required: false

main.py 直接返回params的 JSON 即可。这个 Skill 听起来毫无价值，却是我这一个月里调试频率最高的工具。遇到“模型到底给 Skill 传了什么参数”的疑问时，先让它 echo 一下，问题当场就清晰。很多东西你光靠猜是猜不出来的，直接看一眼最快。

Skill 不是一榔头买卖，它像一把要慢慢养的手艺工具。你先把它当代码写，接着把它当文案写，最后把它当服务来运营——这才是 OpenClaw 用了一个月之后，我对 Skill 最真实的理解。