OpenClaw 入门与 Skill 开发

前言

[一、重新认知 OpenClaw：开源本地优先的 AI Agent 执行平台](#一、重新认知 OpenClaw：开源本地优先的 AI Agent 执行平台)

[1.1 开源：完全可控的二次开发底座](#1.1 开源：完全可控的二次开发底座)

[1.2 本地优先：数据自主掌控，兼顾离线与联网能力](#1.2 本地优先：数据自主掌控，兼顾离线与联网能力)

[1.3 AI Agent：从 "问答生成" 升级为 "目标驱动任务执行"](#1.3 AI Agent：从 “问答生成” 升级为 “目标驱动任务执行”)

[1.4 OpenClaw 与普通聊天 AI 全方位对比](#1.4 OpenClaw 与普通聊天 AI 全方位对比)

[二、OpenClaw 四层系统架构：读懂智能体运行底层逻辑](#二、OpenClaw 四层系统架构：读懂智能体运行底层逻辑)

[2.1 用户入口：多渠道统一交互终端](#2.1 用户入口：多渠道统一交互终端)

[2.2 Gateway 消息网关：统一消息分发中枢](#2.2 Gateway 消息网关：统一消息分发中枢)

[2.3 Agent 智能体：平台的决策大脑](#2.3 Agent 智能体：平台的决策大脑)

[2.4 Tools 与 Skills：真实操作执行层](#2.4 Tools 与 Skills：真实操作执行层)

[三、OpenClaw 部署方案选型：适配不同学习与使用需求](#三、OpenClaw 部署方案选型：适配不同学习与使用需求)

[3.1 快速体验场景：桌面安装包 / 阿里云一键部署](#3.1 快速体验场景：桌面安装包 / 阿里云一键部署)

[3.2 技能开发学习场景：WSL / Linux 虚拟机 / 本地 Linux 主机](#3.2 技能开发学习场景：WSL / Linux 虚拟机 / 本地 Linux 主机)

[3.3 长期稳定生产运行场景：Linux 云服务器](#3.3 长期稳定生产运行场景：Linux 云服务器)

[四、OpenClaw 核心命令全集：开发调试必备工具](#四、OpenClaw 核心命令全集：开发调试必备工具)

[4.1 openclaw 主程序核心命令](#4.1 openclaw 主程序核心命令)

[4.2 clawhub 技能市场管理命令](#4.2 clawhub 技能市场管理命令)

[五、Skill 核心概念：OpenClaw 能力扩展的核心载体](#五、Skill 核心概念：OpenClaw 能力扩展的核心载体)

[5.1 Skill 本质：封装完整业务能力的标准化模块](#5.1 Skill 本质：封装完整业务能力的标准化模块)

[5.2 Skill 标准目录结构](#5.2 Skill 标准目录结构)

[5.3 SKILL.md：技能能否被调用的决定性文件](#5.3 SKILL.md：技能能否被调用的决定性文件)

[5.3.1 YAML 头部规范写法](#5.3.1 YAML 头部规范写法)

[5.3.2 Markdown 正文标准内容](#5.3.2 Markdown 正文标准内容)

[六、实战开发：最小可运行天气查询 Skill weather-bit](#六、实战开发：最小可运行天气查询 Skill weather-bit)

[6.1 技能目录搭建](#6.1 技能目录搭建)

[6.2 编写 SKILL.md 核心配置](#6.2 编写 SKILL.md 核心配置)

[6.3 编写执行脚本 get_weather.py](#6.3 编写执行脚本 get_weather.py)

[6.4 分步测试流程（标准 Skill 开发规范步骤）](#6.4 分步测试流程（标准 Skill 开发规范步骤）)

[6.5 分层排错逻辑](#6.5 分层排错逻辑)

[七、Skill 开发高频问题与完整调试思路](#七、Skill 开发高频问题与完整调试思路)

[7.1 问题一：Agent 识别不到 / 不调用 Skill](#7.1 问题一：Agent 识别不到 / 不调用 Skill)

[7.2 问题二：系统识别 Skill，但脚本执行失败](#7.2 问题二：系统识别 Skill，但脚本执行失败)

[7.3 问题三：Skill 成功调用，但模型输出回答混乱](#7.3 问题三：Skill 成功调用，但模型输出回答混乱)

[八、LangChain、LangGraph、OpenClaw 三者定位与递进学习路线](#八、LangChain、LangGraph、OpenClaw 三者定位与递进学习路线)

[8.1 三款工具定位拆解](#8.1 三款工具定位拆解)

[8.2 递进学习路线总结](#8.2 递进学习路线总结)

[九、OpenClaw 进阶学习路线：从入门 Skill 到企业级自动化方案](#九、OpenClaw 进阶学习路线：从入门 Skill 到企业级自动化方案)

[9.1 第一阶段：文件输出类 Skill------ 二维码生成 qrcode-gen](#9.1 第一阶段：文件输出类 Skill—— 二维码生成 qrcode-gen)

[9.2 第二阶段：完整资源型 Skill------ 运用 references 与 assets 目录](#9.2 第二阶段：完整资源型 Skill—— 运用 references 与 assets 目录)

[9.3 第三阶段：综合实战 ------ 每日资讯早报自动化 Skill](#9.3 第三阶段：综合实战 —— 每日资讯早报自动化 Skill)

十、全文总结

前言

近两年大模型应用开发赛道出现了清晰的分层路线：LangChain 提供 LLM 基础组件、LangGraph 负责复杂智能体工作流编排，而 OpenClaw 填补了 "Agent 落地实操" 的空白。很多开发者在学习完链式调用、图结构智能体后，都会陷入一个瓶颈：代码只能在本地脚本运行，无法对接办公软件、自动化执行本地文件操作、长期稳定在线处理任务。普通对话 AI 只能生成文字回答，没办法真正操控电脑、调用第三方接口、定时完成重复性工作，OpenClaw 的出现恰好解决了这一痛点。

不同于闭源商业 AI 工具，OpenClaw 是一款开源、本地优先的 AI Agent 执行平台，核心定位并非 "聊天机器人"，而是本地 AI 执行网关。它打通了大模型意图理解、任务拆解、工具调用、真实环境操作全链路，依靠 Skill 技能体系无限扩展自动化能力，可对接 Web、终端、飞书、钉钉等多渠道入口，把纸上的 Agent 代码转化为能 7×24 小时运行的自动化助手。

本文将完整梳理 OpenClaw 底层逻辑、系统架构、部署选型、核心命令、Skill 开发全流程，结合可落地的天气查询实战案例，厘清它与 LangChain、LangGraph 的定位差异，同时整理开发高频踩坑问题与进阶学习路线，完整覆盖从零基础入门到自定义业务 Skill 开发的全部知识，适合想搭建私有化自动化 AI 助手的开发者、运维人员、企业办公自动化从业者阅读。

一、重新认知 OpenClaw：开源本地优先的 AI Agent 执行平台

想要用好 OpenClaw，首先要跳出传统聊天 AI 的固有认知，拆解它三大核心标签：开源、本地优先、AI Agent。三者共同定义了它和 ChatGPT、豆包等商用对话产品的本质区别。

1.1 开源：完全可控的二次开发底座

市面上绝大多数通用大模型产品属于闭源服务，用户仅能使用官方预置功能，无法修改底层逻辑、新增专属工具、对接企业内部私有接口。OpenClaw 开源特性带来三大核心优势：第一，全链路可自定义。开发者可自主替换底层大模型，既支持 Ollama 本地私有化模型，也兼容 GPT、DeepSeek、通义千问等云端 API；第二，能力无限扩展。通过 Skill 机制编写专属业务工具，例如企业订单查询、内网数据抓取、本地文件批量处理等私有能力，不受官方功能限制；第三，部署无门槛。支持 Windows、Linux、Docker、WSL、云服务器等多环境，可免费私有化部署，无需按调用量付费，适合个人自动化、中小企业内部使用。

开源不代表上手门槛极高，官方提供标准化 Skill 开发规范、统一命令行工具 clawhub，降低自定义能力的开发成本，普通掌握 Python/JS 基础的开发者即可独立完成技能开发。

1.2 本地优先：数据自主掌控，兼顾离线与联网能力

"本地优先" 是 OpenClaw 最具竞争力的特性，核心逻辑是配置、文件、任务执行流程全部存储在用户自有设备，而非第三方云端服务器。很多企业和个人用户担心文件上传、工作数据泄露，本地优先架构从根源规避数据安全风险。

需要区分一个关键概念：本地优先≠完全离线运行。OpenClaw 具备灵活的网络适配能力：

纯离线场景：搭配 Ollama 本地大模型，仅使用本地文件读写、终端操作类 Skill，全程不访问外网，所有交互、文件处理均在本机完成；
混合联网场景（主流实用场景）：本地部署程序本体，按需联网调用搜索引擎、天气 API、飞书钉钉 Webhook、网页抓取服务，仅传输任务所需少量接口数据，用户核心文件、本地目录不会上传公网；
云端部署场景：云服务器本地运行 OpenClaw，公网仅开放消息交互端口，业务数据留存服务器本地，可自行配置防火墙、密钥保护数据。

对比商用 AI，后者所有对话内容、上传文件都会同步至厂商云端，数据所有权不在用户手中，而 OpenClaw 将数据控制权完全交还使用者，是企业私有化 AI 自动化方案的优选。

1.3 AI Agent：从 "问答生成" 升级为 "目标驱动任务执行"

普通对话 AI 的运行逻辑是被动应答：用户输入提问，模型基于训练数据生成文字答案，无法自主拆解任务、调用工具、执行操作。例如用户发送指令 "整理下载文件夹，区分图片、PDF、压缩包分类存放"，通用 AI 只会输出一段手动操作步骤，不会实际操作电脑文件。

OpenClaw 作为标准 AI Agent 平台，拥有完整的自主任务闭环：理解用户目标→拆解分步任务→匹配对应工具 / Skill→执行真实操作→获取执行结果→迭代完成剩余步骤→汇总结果反馈用户。面对同样的文件夹整理需求，OpenClaw 会自动读取本地下载目录、识别文件后缀、新建分类文件夹、批量移动文件，最终输出整理完成的目录结构，全程无需人工干预。

由此可以得出核心结论：OpenClaw 的核心竞争力不在于对话、写作、文案生成能力，而在于真实环境任务执行能力，代表 AI 产业从 "问答生成式工具" 向 "自动化执行智能体" 的关键转型。

1.4 OpenClaw 与普通聊天 AI 全方位对比

为直观区分二者定位，整理完整对比表格：

对比维度	普通云端聊天 AI	OpenClaw 本地 Agent 平台
运行载体	厂商云端服务器	用户电脑 / 自建云服务器，本地优先
核心功能	文字问答、文案生成、内容创作	工具调用、本地文件操作、浏览器自动化、定时任务、办公软件推送、全流程自动化
数据存储	对话、文件全部上传厂商云端	核心数据本地留存，仅按需传输接口请求数据
能力扩展方式	仅使用官方预制功能，无自定义入口	通过 Skill 开发自定义任意业务能力，开放全量工具接口
目标使用人群	普通大众，轻量化内容需求	开发者、运维、企业行政、自动化爱好者
核心运行逻辑	单次输入单次输出，无任务规划	目标驱动，自主拆解多步骤任务，循环执行直至完成
部署权限	无法私有化部署，依赖厂商服务	全开源，支持本地单机、Docker、云服务器私有化部署

在使用 OpenClaw 时，必须彻底转变传统 AI 使用思维：不再关注 "模型能输出什么文字"，而是聚焦 "智能体能调用哪些工具、完成哪些自动化任务、如何新增专属技能"。常见落地场景覆盖本地文件管理、行业资讯抓取汇总、代码调试辅助、每日定时简报推送、企业内部数据查询、浏览器批量操作等，所有场景的共性是需要真实操作环境，而非单纯文字生成。

二、OpenClaw 四层系统架构：读懂智能体运行底层逻辑

OpenClaw 整体采用分层解耦架构，模块职责清晰，降低后期自定义、二次开发难度，整体链路自上而下分为四层：用户交互入口、Gateway 消息网关、Agent 智能体核心、Tools/Skills 执行层，最终对接本地系统、第三方接口等真实世界。完整链路如下：

复制代码

多渠道用户入口
    ↓
Gateway统一消息网关（消息标准化、路由分发）
    ↓
Agent智能体大脑（意图识别、任务拆解、工具选择、结果整合）
    ↓
Tools基础工具 + Skills自定义业务技能（脚本执行、真实操作）
    ↓
本地文件/终端/浏览器/第三方API/办公软件（真实世界）

逐层拆解各模块核心职责：

2.1 用户入口：多渠道统一交互终端

OpenClaw 不局限单一网页对话窗口，支持多渠道接入，覆盖开发调试、日常办公两大场景：

TUI 终端界面：命令行交互窗口，开发调试首选，报错日志、Skill 调用链路完整展示；
WebUI 网页控制台：可视化控制面板，默认本地地址http://127.0.0.1:18789，适合非开发人员日常使用；
办公协同渠道：飞书、钉钉、企业微信，支持群聊机器人自动响应指令、推送日报；
第三方聊天渠道：Telegram、Discord，适合海外个人自动化场景。

不同渠道消息格式存在差异，飞书、Web、终端的消息结构完全不同，若直接交由 Agent 处理会造成逻辑混乱，因此 Gateway 网关承担消息统一处理工作。

2.2 Gateway 消息网关：统一消息分发中枢

网关是整个系统的 "消息中转站"，两大核心职能：第一，消息标准化。接收来自 Web、飞书、终端等不同渠道的异构消息，统一转换成 OpenClaw 内部标准消息格式，屏蔽各平台接口差异；第二，双向路由分发。将标准化用户消息转发至 Agent 核心处理；Agent 完成任务后，再把执行结果按照对应渠道格式封装，原路返回给用户。

网关的解耦设计带来极大扩展性：后续新增任意聊天渠道，仅需开发对应网关适配插件，无需修改 Agent 核心逻辑，大幅降低多端接入开发成本。

2.3 Agent 智能体：平台的决策大脑

Agent 是 OpenClaw 的核心逻辑层，承担全部思考、规划工作，完整执行链路分为五步：

意图识别：解析用户自然语言指令，判断用户核心需求；
任务拆解：复杂多步骤任务拆分，例如 "抓取 AI 新闻→总结 5 条要点→推送飞书" 拆分为三个子任务；
工具匹配：检索全部已加载 Skill、基础 Tools，根据描述匹配完成子任务所需能力；
循环执行：调用对应技能获取结果，判断是否完成全部任务，未完成则继续调用工具；
结果整合：将结构化工具输出整理为通顺自然语言，交由网关返回用户。

Agent 不直接操作本地文件、接口，仅负责决策调度，所有真实操作全部下放至底层 Tools 与 Skills，职责分层清晰，便于单独调试业务技能。

2.4 Tools 与 Skills：真实操作执行层

这是 OpenClaw 落地自动化的核心执行单元，二者定位区分明确：

Tools：平台内置通用基础工具箱，属于底层原生能力，无需额外安装，包含文件读写、终端命令执行、Playwright 浏览器控制、网页抓取、全网搜索、操作系统操作等通用能力，是所有 Skill 的底层依赖；
Skills：用户自定义 / 第三方安装的业务扩展能力，面向细分场景，例如天气查询、二维码生成、每日资讯早报、企业订单查询等，聚焦单一业务需求，基于 Tools 封装专属逻辑。

简单总结四层架构分工：Gateway 管消息流转，Agent 管任务决策，Tools/Skills 管真实操作，多渠道 Channels 负责对接外部用户。理解分层架构，后续部署排错、Skill 开发、多渠道接入都会事半功倍。

三、OpenClaw 部署方案选型：适配不同学习与使用需求

OpenClaw 提供多元化部署方案，包含桌面安装包、Docker、WSL、Windows 原生、Linux 云服务器、阿里云一键部署六大方式，不同方案适配学习、开发、长期生产运行三类场景，下面分场景给出选型建议与优劣分析。

3.1 快速体验场景：桌面安装包 / 阿里云一键部署

适用人群：零基础新手，仅想快速体验功能，暂时不深入 Skill 开发。优势：零环境配置、一键安装，无需手动配置 Node、Python、依赖库，开箱即用；阿里云一键部署省去服务器初始化、端口配置流程，五分钟搭建云端可用实例。劣势：底层封装度高，无法深入理解运行目录、Skill 加载逻辑；遇到脚本报错、权限问题时，底层日志难以排查，不利于后续自定义技能开发。

3.2 技能开发学习场景：WSL / Linux 虚拟机 / 本地 Linux 主机

适用人群：计划系统学习 Skill 开发，编写自动化脚本、浏览器抓取、定时推送类技能。推荐优先级：WSL（Windows 用户首选）> Linux 虚拟机 > 实体 Linux 电脑。优势：绝大多数自动化工具、脚本、定时任务、Playwright 浏览器依赖原生 Linux 生态，Node、Python、Git 权限、编码、定时任务运行稳定，极少出现 Windows 特有报错；Skill 开发社区案例、官方教程均基于 Linux 环境编写，踩坑成本最低。 Windows 原生 PowerShell 裸跑不推荐：极易出现 Python 路径错乱、中文目录编码报错、PowerShell 执行策略拦截、浏览器自动化依赖缺失、文件读写权限不足等问题，前期调试会耗费大量时间处理环境兼容问题。稳妥学习路线：先学习架构与 Skill 理论，用桌面版简单体验，再切换 WSL 系统正式开发自定义技能。

3.3 长期稳定生产运行场景：Linux 云服务器

适用人群：需要 7×24 小时在线运行的自动化场景，例如每日早报定时推送、企业飞书常驻机器人、内网数据定时同步。优势：服务器永久在线，不受本地电脑开关机限制；支持配置公网接口回调，外部系统可主动调用 OpenClaw 能力；适合团队多人共用一套 Agent 平台。注意事项：云服务器部署需做好安全防护，禁止随意开放高危端口；妥善保管模型 API Key、第三方接口 Token、数据库密钥；限制公网访问权限，配置防火墙仅开放必要端口，避免密钥泄露、服务器被恶意调用。

四、OpenClaw 核心命令全集：开发调试必备工具

OpenClaw 分为两套命令体系：主程序openclaw负责平台启动、面板查看、技能状态管理；clawhub是配套 Skill 市场命令行工具，负责技能搜索、安装、同步，是开发阶段高频使用工具。

4.1 openclaw 主程序核心命令

openclaw tui 启动终端交互式界面，Skill 开发调试首选工具。实时展示 Agent 思考流程、技能调用日志、脚本报错信息，能直观验证自定义 Skill 是否被正确识别、触发，新手调试阶段优先使用。
openclaw dashboard 启动 Web 可视化控制台，默认本地访问地址http://127.0.0.1:18789。云服务器部署时，需通过 SSH 端口隧道映射本地访问，可视化面板适合日常使用、批量配置渠道插件。
openclaw skills list 查看当前平台已加载全部 Skill 列表，开发自定义技能后，第一条排查命令。若编写完成的技能未出现在列表中，代表目录、SKILL.md 格式存在错误，无法被系统识别。
openclaw plugins list 查看渠道插件加载状态，飞书、钉钉、企业微信等多端接入插件通过该命令校验是否正常加载，排查机器人无法接收消息问题。

4.2 clawhub 技能市场管理命令

clawhub 需要全局 npm 安装，安装指令：npm i -g clawhub，核心功能为第三方 Skill 检索与安装：

clawhub search "tavily"：按关键词搜索市场内公开技能，例如搜索搜索引擎、浏览器自动化相关 Skill；
clawhub install openclaw-tavily-search：一键安装指定第三方 Skill，自动配置依赖、加载至平台；
clawhub list：查看通过 clawhub 安装的所有第三方技能；
clawhub sync：同步本地 Skill 目录，新增、修改自定义技能后执行，刷新平台技能缓存。

记忆区分：openclaw管控平台本体运行、状态查看；clawhub专门管理外部技能市场，实现技能一键分发安装。

五、Skill 核心概念：OpenClaw 能力扩展的核心载体

Skill 是 OpenClaw 区别于其他 Agent 框架的核心设计，也是开发者二次开发的核心对象。想要自主扩展自动化能力，必须吃透 Skill 的定义、目录结构、核心文件 SKILL.md 设计规范。

5.1 Skill 本质：封装完整业务能力的标准化模块

Skill 完整定义：一套标准化的能力扩展文件夹，包含意图描述文档、执行脚本、配套资源、参考资料，完整告知 Agent：该技能适用场景、入参、调用方式、输出格式、业务限制，触发需求时自动运行脚本完成真实操作。

Skill 与 Prompt 存在本质区别：Prompt 仅通过文字引导模型调整输出话术，无法执行任何本地操作；Skill 不止包含描述文本，还附带可运行代码，能够操控文件、调用接口、生成资源，让 Agent 从 "只会说话" 变成 "能动手做事"。

以二维码生成场景举例：单纯 Prompt 只能告诉模型 "你是二维码助手"，无法生成图片文件；完整二维码 Skill 会定义触发条件、执行 Python 脚本、输出图片路径，Agent 识别用户生成二维码需求后，自动调用脚本生成 PNG 图片并返回本地文件地址。

5.2 Skill 标准目录结构

完整规范 Skill 文件夹包含四层目录，最小可用技能仅需 SKILL.md 与 scripts 文件夹：

复制代码

自定义技能名/
├── SKILL.md          # 核心配置文件（必填，不可缺失）
├── scripts/          # 执行脚本存放目录（Python/JS/Bash）
├── references/       # 业务参考资料（API文档、业务规则、限制说明）
└── assets/           # 静态资源（模板文件、图片、配置样例）

各目录用途细分：

SKILL.md：技能唯一核心文件，由 YAML 头部配置 + Markdown 正文组成，决定 Agent 能否识别、正确调用该技能；
scripts：存放业务执行代码，是真正完成任务的逻辑载体，支持多语言脚本；
references：存放业务配套文档，例如第三方接口文档、企业内部业务规范、接口限流规则，Agent 执行时可读取参考内容约束操作；
assets：静态资源，包含日报 Markdown 模板、推送消息样式、图标、配置模板等，脚本运行时可读取使用。

5.3 SKILL.md：技能能否被调用的决定性文件

SKILL.md 是 Skill 的灵魂，采用 YAML Frontmatter+Markdown 正文格式，YAML 头部的 name、description 字段是 Agent 识别技能的关键，采用渐进式披露机制：平台启动时仅加载所有 Skill 的 name 与 description，用户发送指令后，Agent 通过描述匹配候选技能，匹配成功才会完整读取 SKILL.md 全部内容获取调用规则。

5.3.1 YAML 头部规范写法

复制代码

---
name: weather-bit
description: 查询北京、上海两地天气信息，用户询问温度、湿度、风向、出行建议、是否带伞时触发，仅支持北京、上海两座城市。
---

name：技能唯一标识符，规范小写字母 + 连字符命名，禁止中文、空格，示例qrcode-gen、daily-news-push；
description：重中之重，描述必须清晰明确，写明触发场景、功能范围、使用限制。模糊描述如 "好用的天气工具" 会导致 Agent 无法匹配需求，直接造成技能不调用问题。

5.3.2 Markdown 正文标准内容

正文需要补充三大模块，规范 Agent 调用逻辑：

何时使用：细化所有触发场景，覆盖用户可能提问方式；
如何使用：完整脚本调用命令、入参说明；
输出格式：定义脚本返回数据结构，推荐 JSON 结构化输出，便于 Agent 解析整合答案。

一份合格的 SKILL.md，既要让 Agent 精准识别触发时机，也要清晰告知调用方式与数据格式，二者缺一不可。

六、实战开发：最小可运行天气查询 Skill weather-bit

理论落地必须通过实战验证，本节从零搭建极简天气 Skill，不对接真实第三方天气 API，使用模拟固定数据，核心目标是跑通完整链路：自然语言提问→Agent 识别意图→匹配 Skill→执行 Python 脚本→返回结构化 JSON→整合自然语言回复。

6.1 技能目录搭建

新建文件夹weather-bit，最简结构仅两个文件：

复制代码

weather-bit/
├── SKILL.md
└── scripts/
    └── get_weather.py

6.2 编写 SKILL.md 核心配置

复制代码

---
name: weather-bit
description: 查询北京、上海实时天气，用户询问气温、湿度、风向、出行建议、是否下雨、是否需要带伞时调用，仅支持北京、上海，其他城市无数据。
---
# weather-bit 天气查询技能
## 何时使用
用户提问包含：北京天气、上海温度、明天上海下雨吗、北京出行建议、湿度多少、要不要带伞等相关天气问题。
## 调用方式
python scripts/get_weather.py [城市名]
入参：城市名，仅支持"北京""上海"
## 输出格式
JSON结构化数据，包含city城市、weather天气状况、temperature温度、wind风向、humidity湿度、suggestion出行建议六个字段。

6.3 编写执行脚本 get_weather.py

脚本接收城市名称入参，输出标准 JSON 格式，便于 Agent 解析：

复制代码

import sys
import json

def get_weather(city):
    data = {
        "city": city,
        "weather": "",
        "temperature": "",
        "wind": "",
        "humidity": "",
        "suggestion": ""
    }
    if city == "北京":
        data.update({
            "weather": "小雨",
            "temperature": "18℃",
            "wind": "东北风",
            "humidity": "72%",
            "suggestion": "降雨天气，建议携带雨伞，注意添衣保暖。"
        })
    elif city == "上海":
        data.update({
            "weather": "多云",
            "temperature": "24℃",
            "wind": "东南风",
            "humidity": "60%",
            "suggestion": "天气舒适，适合外出，无需携带雨具。"
        })
    else:
        data["suggestion"] = "当前演示版天气技能仅支持北京、上海，暂不支持该城市查询。"
    return json.dumps(data, ensure_ascii=False)

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print(json.dumps({"msg": "请传入城市名称参数"}, ensure_ascii=False))
    else:
        city_name = sys.argv[1]
        print(get_weather(city_name))

6.4 分步测试流程（标准 Skill 开发规范步骤）

开发 Skill 必须遵循 "先单独测脚本，再接入平台调试" 的顺序，完整九步开发流程：

明确技能适用场景：用户查询北京、上海天气；
确定输入：单一城市名称字符串；
确定输出：标准化 JSON 天气数据；
梳理限制条件：仅支持两座城市；
编写 SKILL.md 配置文档；
编写 scripts 执行 Python 脚本；
本地独立运行脚本，验证输出正确性：

测试北京

python weather-bit/scripts/get_weather.py 北京

测试上海

python weather-bit/scripts/get_weather.py 上海

测试不支持城市

python weather-bit/scripts/get_weather.py 广州

脚本输出无报错、JSON 格式完整，再进行下一步； 8. 将 Skill 文件夹放入 OpenClaw 技能目录，执行clawhub sync同步，openclaw skills list确认技能识别成功； 9. 打开openclaw tui终端界面，自然语言提问 "今天北京天气怎么样，需要带伞吗？"，验证 Agent 自动调用 weather-bit 并整合结果回复。

6.5 分层排错逻辑

若集成后技能无法正常使用，按照从底层到上层分层排查：

脚本层：单独运行脚本是否报错，检查 Python 依赖、路径、中文编码；
目录配置层：确认 Skill 存放目录正确，执行 clawhub 同步刷新缓存；
SKILL.md 层：检查 YAML 格式、description 描述是否清晰、调用命令是否书写正确；
Agent 匹配层：调整描述文字，补充全部触发场景，让模型精准识别需求。

七、Skill 开发高频问题与完整调试思路

开发自定义技能时，绝大多数问题分为三类：Agent 完全不调用 Skill、脚本运行报错、技能调用成功但回复效果差，对应完整解决方案。

7.1 问题一：Agent 识别不到 / 不调用 Skill

核心诱因与解决办法：

SKILL.md 的 description 描述模糊，未写明触发场景。优化方案：在描述中完整列举用户提问关键词、使用场景、业务限制；
Skill 文件夹放置路径错误，平台未扫描到。执行openclaw skills list校验列表，无结果则调整目录位置，执行clawhub sync同步缓存；
YAML 头部格式错误，存在空格、换行语法问题，导致 SKILL.md 解析失败；
技能未刷新缓存，新增 / 修改技能后未执行同步命令。

7.2 问题二：系统识别 Skill，但脚本执行失败

底层脚本报错是最常见问题，优先脱离 OpenClaw 单独运行脚本复现错误：

Python/JS 运行环境缺失，缺少第三方依赖库，提前安装脚本所需依赖；
脚本绝对 / 相对路径书写错误，SKILL.md 内调用命令路径与实际目录不匹配；
中文编码异常，Windows 环境极易出现，推荐统一使用 UTF-8 编码；
文件读写权限不足，云服务器、WSL 环境脚本无操作本地文件权限；
入参传递逻辑错误，用户输入参数未正确传入脚本。

7.3 问题三：Skill 成功调用，但模型输出回答混乱

根本原因是脚本输出无统一结构化格式，Agent 无法解析字段含义：

强制脚本输出 JSON 格式数据，每个业务字段清晰命名；
在 SKILL.md 正文标注每个输出字段代表的含义，引导模型按照字段信息组织回答；
完善脚本异常返回逻辑，查询失败、参数错误时返回标准化报错 JSON，避免纯文本乱码输出。

稳定可用的标准 Skill 三大标准：触发描述清晰无歧义、脚本独立运行无报错、输出结构化 JSON，错误提示明确易懂。

八、LangChain、LangGraph、OpenClaw 三者定位与递进学习路线

很多初学者会混淆三款工具的作用，三者不存在竞争替代关系，而是完整连贯的分层技术栈，学习顺序循序渐进。

8.1 三款工具定位拆解

LangChain：大模型应用基础组件库提供 LLM 调用、提示词模板、工具绑定、RAG 检索、短期记忆、输出解析等底层封装组件，解决 "如何调用大模型、组装基础 AI 能力" 的问题，适合编写单次、轻量化 LLM 应用脚本，无任务持久化、多轮复杂工作流能力。
LangGraph：复杂 Agent 工作流编排框架基于 LangChain 底层组件构建，引入状态 State、节点 Node、流向 Edge、持久化检查点 Checkpoint 概念，支持循环任务、分支路由、人工介入、失败重试、多智能体协作，专门解决多步骤、长流程复杂任务规划问题，但仅能在代码脚本内运行，无法对接外部渠道、操作本地真实环境。
OpenClaw：可落地部署的 AI Agent 执行平台以 LangChain、LangGraph 的智能体逻辑为底层基础，搭建完整可运行平台，新增 Gateway 多渠道消息网关、本地文件 / 浏览器 / 办公软件操作能力、Skill 标准化扩展机制、后台可视化面板、7×24 小时常驻运行能力，核心解决 "智能体如何落地到真实环境自动化运行" 的痛点。

8.2 递进学习路线总结

LangChain 学习基础 LLM 组件 → LangGraph 学习复杂任务编排逻辑 → OpenClaw 将智能体部署为可长期运行的自动化平台 → 开发自定义 Skill 持续扩展平台业务能力。简单概括：LangChain 写组件、LangGraph 编排流程、OpenClaw 落地部署、Skill 扩展业务能力。

九、OpenClaw 进阶学习路线：从入门 Skill 到企业级自动化方案

完成 weather-bit 基础天气技能开发后，可按照由浅入深顺序学习进阶案例，逐步掌握全部核心开发能力。

9.1 第一阶段：文件输出类 Skill------ 二维码生成 qrcode-gen

天气 Skill 仅返回文本 JSON 数据，二维码技能新增本地文件生成逻辑，补充全新知识点：Python 第三方依赖安装、图片资源输出目录设计、文件路径返回、图片异常捕获处理。目录新增 output 文件夹存放生成图片：

复制代码

qrcode-gen/
├── SKILL.md
├── scripts/make_qr.py
└── output/

9.2 第二阶段：完整资源型 Skill------ 运用 references 与 assets 目录

掌握静态资源、业务参考文档使用场景，例如企业内部业务 Skill：将接口文档放入 references、日报推送 Markdown 模板存入 assets，脚本运行时读取模板生成标准化文档，让 Skill 从单一脚本升级为完整业务能力包。

9.3 第三阶段：综合实战 ------ 每日资讯早报自动化 Skill

覆盖 OpenClaw 生产环境全部核心能力，是综合验收项目：

Playwright 浏览器自动化抓取行业资讯；
文本过滤、摘要总结，生成 Markdown 简报；
通过飞书 Webhook 推送文档至企业群；
配置定时任务，每日固定时间自动执行；
完善异常捕获、日志记录、接口限流处理。该案例完整覆盖网页抓取、文件生成、办公渠道推送、定时调度、错误处理，学完即可独立搭建企业内部自动化 AI 助手。

十、全文总结

OpenClaw 打破了传统大模型只能问答生成的局限，将 AI 从文字工具升级为可操控本地环境、对接办公系统、长期稳定运行的自动化 Agent 平台，开源、本地优先的特性完美适配个人自动化、企业私有化部署需求。

四层分层架构（多渠道入口 - Gateway 网关 - Agent 决策 - Tools/Skills 执行）清晰划分模块职责，降低开发与维护成本；Skill 作为平台核心扩展机制，通过 SKILL.md 标准化描述 + 可运行脚本的组合，实现无限新增业务能力，是开发者二次开发的核心抓手。

对比 LangChain、LangGraph，三者形成完整学习链路：前者负责底层组件与工作流编排，OpenClaw 专注落地执行，Skill 填充细分业务场景。入门开发需彻底转变问答思维，建立 "任务执行思维"，开发技能遵循先文档、再脚本、独立测试、平台集成的标准流程，分层排查各类报错。

对于开发者而言，OpenClaw 的核心价值在于解放重复工作：无论是本地文件批量处理、每日资讯自动汇总、办公群定时推送，还是企业内网数据查询，都能通过自定义 Skill 封装成一键执行的自动化任务，打造专属私有化 AI 执行网关，真正实现 AI 落地到日常工作场景。

OpenClaw 入门与 Skill 开发

前言

一、重新认知 OpenClaw：开源本地优先的 AI Agent 执行平台

1.1 开源：完全可控的二次开发底座

1.2 本地优先：数据自主掌控，兼顾离线与联网能力

1.3 AI Agent：从 "问答生成" 升级为 "目标驱动任务执行"

1.4 OpenClaw 与普通聊天 AI 全方位对比

二、OpenClaw 四层系统架构：读懂智能体运行底层逻辑

2.1 用户入口：多渠道统一交互终端

2.2 Gateway 消息网关：统一消息分发中枢

2.3 Agent 智能体：平台的决策大脑

2.4 Tools 与 Skills：真实操作执行层

三、OpenClaw 部署方案选型：适配不同学习与使用需求

3.1 快速体验场景：桌面安装包 / 阿里云一键部署

3.2 技能开发学习场景：WSL / Linux 虚拟机 / 本地 Linux 主机

3.3 长期稳定生产运行场景：Linux 云服务器

四、OpenClaw 核心命令全集：开发调试必备工具

4.1 openclaw 主程序核心命令

4.2 clawhub 技能市场管理命令

五、Skill 核心概念：OpenClaw 能力扩展的核心载体

5.1 Skill 本质：封装完整业务能力的标准化模块

5.2 Skill 标准目录结构

5.3 SKILL.md：技能能否被调用的决定性文件

5.3.1 YAML 头部规范写法

5.3.2 Markdown 正文标准内容

六、实战开发：最小可运行天气查询 Skill weather-bit

6.1 技能目录搭建

6.2 编写 SKILL.md 核心配置

6.3 编写执行脚本 get_weather.py

6.4 分步测试流程（标准 Skill 开发规范步骤）

测试北京

测试上海

测试不支持城市

6.5 分层排错逻辑

七、Skill 开发高频问题与完整调试思路

7.1 问题一：Agent 识别不到 / 不调用 Skill

7.2 问题二：系统识别 Skill，但脚本执行失败

7.3 问题三：Skill 成功调用，但模型输出回答混乱

八、LangChain、LangGraph、OpenClaw 三者定位与递进学习路线

8.1 三款工具定位拆解

8.2 递进学习路线总结

九、OpenClaw 进阶学习路线：从入门 Skill 到企业级自动化方案

9.1 第一阶段：文件输出类 Skill------ 二维码生成 qrcode-gen

9.2 第二阶段：完整资源型 Skill------ 运用 references 与 assets 目录

9.3 第三阶段：综合实战 ------ 每日资讯早报自动化 Skill

十、全文总结