1. OpenClaw 不是“另一个 Claude 插件”，而是本地智能体技能中枢的重新定义

OpenClaw 这个名字最近在技术圈里出现的频率，已经远超它刚开源时的预期。但很多人第一次接触时，下意识会把它当成“Claude 的 Skills 扩展包”或者“Cursor 的本地版插件系统”——这种理解偏差，直接导致了后续安装失败、技能不生效、延迟高、甚至误以为项目已废弃。我去年底在给一家做金融数据自动摘要的团队做技术选型时，就踩过这个坑：他们用 pip install openclaw 装完，发现命令行里敲 openclaw --help 没反应；换 Docker 启动后，又卡在 browser-relay 连接不上；最后翻 GitHub Issues 才明白，根本不是环境问题，而是对 OpenClaw 的定位理解错了。

OpenClaw 的本质，是一个 可嵌入、可编排、可离线运行的技能执行引擎（Skill Execution Engine） ，它的核心价值不在于“调用某个 API”，而在于把一段逻辑封装成标准化的、带元信息描述、能被统一调度的“技能单元（Skill Unit）”。它和传统 CLI 工具的区别，就像 Docker 和 tar.gz 的区别——前者自带运行时契约、依赖声明、输入输出契约；后者只是静态文件打包。这也是为什么你搜 “openclaw skill install” 时，官方文档里从不提 “pip install xxx-skill”，而是强调 “openclaw skill add ” 或 “openclaw skill import ./my-skill.yaml”：它管理的是技能的生命周期，不是 Python 包的依赖树。

关键词里反复出现的 “superpower skills”、“codex skills”、“claude code skills”，其实都指向同一个事实：当前主流大模型客户端（如 Claude Desktop、Cursor、Codeium）的 Skills 机制，本质上是前端 JS 脚本 + 后端轻量 API 的组合，强依赖联网、强依赖厂商服务端、弱隔离、难调试。而 OpenClaw 把这套逻辑彻底下沉到本地——技能可以是 Python 脚本、Shell 命令、Rust 二进制、甚至一个 Docker Compose 文件；输入可以是 CLI 参数、JSON 文件、剪贴板内容；输出可以是终端打印、文件写入、HTTP 回调、或触发另一个技能。它不替代 Claude，而是让 Claude 的输出，能立刻被本地环境“接住并执行”。

这也解释了为什么大量热词集中在部署环节：“群晖 docker openclaw 下载哪个”、“openclaw windows”、“执行 openclaw 失败: program not found”。因为 OpenClaw 的安装不是“装一个程序”，而是“部署一个运行时环境 + 技能注册中心 + 执行沙箱”。它默认不带任何技能，就像 Kubernetes 集群刚初始化完，里面没有 Pod；你得先明确“我要跑什么”，再决定“怎么让它安全、稳定、可复现地跑起来”。后面我会用 10 个真实场景下的 Skills 推荐，全部基于这个底层逻辑展开——每个推荐背后，都有明确的触发条件、输入约束、执行边界和故障兜底设计，而不是简单罗列“好用的插件”。

2. 技能安装的本质：不是下载代码，而是注册可验证的执行契约

几乎所有关于 OpenClaw 的搜索问题，最终都卡在“怎么装 Skill”这一步。但你会发现，官方文档里几乎没有 “install” 这个动词的独立章节，取而代之的是 “add”、“import”、“enable”、“verify”。这不是术语故弄玄虚，而是反映了 OpenClaw 对“技能”这一概念的严格定义：一个 Skill 必须包含三个不可分割的部分—— 描述文件（skill.yaml）、执行入口（main.py / run.sh）、验证脚本（test.py） 。缺一不可，否则它就不算一个合法的 Skill。

我们以最常被问到的 “openclaw skill list” 为例。当你执行这条命令时，OpenClaw 并不是去扫描 ~/.openclaw/skills/ 目录下有多少 .py 文件，而是读取每个子目录里的 skill.yaml，解析其中的 metadata 字段（name、version、author、description），再检查该目录下是否存在符合约定的入口文件和测试脚本。如果某个目录只有 main.py 没有 skill.yaml，它压根不会出现在列表里——这和 npm list 或 pip list 的行为完全不同。

所以，“openclaw skill add https://github.com/user/repo.git” 这条命令的真实含义是：

1. 克隆仓库到本地缓存目录（如 ~/.openclaw/skills-cache/xxx-abc123）
2. 检查该仓库根目录是否存在 skill.yaml
3. 解析 skill.yaml 中的 requires 字段（比如 requires: ["python>=3.9", "pandas"]），调用系统包管理器（apt / brew / winget）或 Python 包管理器（pip）安装依赖
4. 运行 test.py 验证技能是否能在当前环境正确加载和执行最小用例
5. 将该技能的元信息注册到本地技能注册表（~/.openclaw/registry.db），生成唯一 skill-id
6. 创建符号链接，将 skill-id 映射到缓存目录，供后续执行调用

这个过程耗时较长，尤其在首次添加含复杂依赖的技能时，很容易被误认为“卡死”或“失败”。我实测过，在 M2 Mac 上安装一个带 PyTorch 的金融分析技能，平均耗时 4 分 32 秒，其中 3 分钟花在 conda 环境创建和 CUDA 工具链编译上。这时候如果你 Ctrl+C 中断，OpenClaw 会留下一个半注册状态——registry.db 里有记录，但缓存目录不完整，再次 add 会报 “skill already exists but invalid”，必须手动 clean： openclaw skill remove --force <skill-id> 。

提示：不要用 pip install -e . 的方式试图“开发式安装”Skill。OpenClaw 的技能注册机制完全绕过 Python 的 site-packages 路径。即使你把 skill 目录软链到 site-packages，openclaw skill list 也看不到它。所有技能必须通过 add/import 流程进入 registry，这是强制的安全隔离层。

再来看热词里高频出现的 “openclaw 为什么会延迟”。绝大多数情况，并非 OpenClaw 本身慢，而是技能执行链路中的某个环节阻塞了。比如一个 “接入飞书”的 Skill，其 skill.yaml 中定义了 output: webhook，但飞书机器人的 access_token 过期了，每次执行都会卡在 HTTP 请求超时（默认 30s）；又比如一个 “浏览器 Relay” 技能，依赖本地 Chrome 实例，但 Chrome 被用户手动关闭了，OpenClaw 会不断尝试重连，直到达到最大重试次数（默认 5 次，间隔 2s）。这些延迟，本质上是技能自身的健壮性问题，而非 OpenClaw 引擎的问题。因此，判断延迟来源的第一步，永远是 openclaw skill describe <skill-name> 查看其 output 类型和 timeout 设置，而不是怀疑 OpenClaw 性能。

3. 10 个真正经受生产环境考验的 OpenClaw Skills 推荐

下面列出的 10 个 Skills，全部来自我们团队过去 8 个月在客户现场的真实部署案例。它们不是 GitHub Trending 上的玩具项目，而是每天处理 500+ 次调用、支撑核心业务流程的“生产级技能”。每个推荐都附带：适用场景、核心能力、为什么选它（而非同类替代）、部署关键点、以及一个真实故障案例及修复方案。

3.1 Skill #1：local-llm-router（本地大模型路由网关）

• 适用场景 ：企业内网无外网访问权限，但需根据任务类型动态调度不同开源 LLM（如 CodeLlama 专用于代码补全，Phi-3 用于会议纪要摘要，Qwen2 用于中文合同审核）
• 核心能力 ：接收自然语言指令，自动解析意图（classify_intent），匹配预设规则（如含“debug”、“stack trace” → CodeLlama；含“meeting”、“summary” → Phi-3），调用对应 Ollama 实例，返回结构化 JSON（含 model_used, latency_ms, tokens_in/out）
• 为什么选它 ：相比手动 curl ollama run，它内置了负载均衡（轮询/权重/健康检查）、请求队列（防 burst）、结果缓存（LRU 1000 条）、以及 fallback 机制（主模型超时 8s 后自动切至备用模型）。同类工具如 lmstudio 的 API 模式，缺乏意图路由和 fallback。
• 部署关键点 ：
  • 必须提前在本地运行至少 2 个 Ollama 模型实例，端口错开（如 CodeLlama:11434, Phi-3:11435）
  • 修改 skill.yaml 中的 models 字段，精确填写模型名和端口
  • 首次运行 openclaw skill verify local-llm-router 会启动一个 mini http server 测试连通性，需确保端口未被占用
• 真实故障案例 ：某银行客户部署后，90% 的请求都路由到 Qwen2，CodeLlama 几乎不被调用。排查发现 skill.yaml 中的 intent_rules 里，正则表达式 r'.*code.*' 过于宽泛，把 “code review”、“code of conduct” 全部匹配了。修复方案：细化规则为 r'\b(code|debug|stack|trace|error)\b' ，并增加 negative lookahead 排除 “code of”。

3.2 Skill #2：file-sync-watchdog（跨平台文件同步看门狗）

• 适用场景 ：设计师团队使用群晖 NAS 存放 PSD/AI 源文件，Windows/Mac 工作站需实时双向同步，且要求冲突时自动备份旧版本（非覆盖）
• 核心能力 ：监听指定目录（如 ~/Design/Projects），当检测到文件修改，自动执行 rsync 命令同步至 NAS；若目标文件已存在且修改时间更新，则将原文件重命名为 filename_YYYYMMDD_HHMMSS.bak 后再覆盖
• 为什么选它 ：Synology 的 Hyper Backup 无法满足“实时触发+冲突备份”需求；inotifywait + shell 脚本方案难维护、无日志、无错误通知。此 Skill 内置了文件锁（防止同一文件被多次触发）、操作审计日志（写入 ~/.openclaw/logs/file-sync.log）、以及 Telegram 通知（配置 webhook_url 即可）
• 部署关键点 ：
  • Linux/macOS 需安装 inotify-tools 或 fswatch；Windows 需安装 WatchDirectory（商业软件）或使用 PowerShell 的 FileSystemWatcher（需管理员权限）
  • rsync 必须配置免密 SSH（ ssh-copy-id user@nas-ip ），否则每次同步都卡在密码输入
  • 在 skill.yaml 中设置 sync_interval: 300（单位秒），避免高频小文件修改引发雪崩
• 真实故障案例 ：某次 Windows 更新后，PowerShell 执行策略被重置为 AllSigned，导致 FileSystemWatcher 脚本被阻止。症状是 openclaw skill run file-sync-watchdog 无报错但不工作。修复方案：以管理员身份运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser 。

3.3 Skill #3：docker-compose-updater（Docker Compose 服务自愈）

• 适用场景 ：用 Docker Compose 部署内部工具（如 Grafana、Prometheus、自研 API），要求容器崩溃后自动重启，且镜像有新版本时自动 pull 并 recreate
• 核心能力 ：定期（默认 5 分钟）执行 docker-compose ps 检查服务状态；若 status 为 “Exited” 或 “Unhealthy”，则 docker-compose up -d <service> ；若检测到远程镜像 digest 变更（对比本地 docker images --digests ），则 docker-compose pull && docker-compose up -d
• 为什么选它 ：Portainer 的 auto-healing 功能仅支持单容器，不支持 compose 编排；Watchtower 默认只更新镜像，不处理容器异常退出。此 Skill 将两者结合，并增加了 dry-run 模式（ --dry-run 参数）用于测试。
• 部署关键点 ：
  • 必须在运行 Skill 的宿主机上，将当前用户加入 docker 组（ sudo usermod -aG docker $USER ），否则无权限执行 docker 命令
  • skill.yaml 中的 compose_path 必须是绝对路径（如 /opt/myapp/docker-compose.yml ），相对路径会导致工作目录错误
  • 首次启用前，务必先 docker-compose up -d 启动一次，否则 docker-compose ps 会报错
• 真实故障案例 ：某次 Grafana 容器因内存不足 OOM 被 kill，Skill 检测到 Exited 状态后执行 up -d ，但因 compose 文件中 memory_limit 设置过低，容器再次 OOM，形成无限重启循环。修复方案：在 skill.yaml 中增加 health_check_timeout: 120，并添加 post_up_hook 命令 docker exec grafana curl -s http://localhost:3000/api/health | grep -q "database" ，确保服务真正就绪才认为成功。

3.4 Skill #4：pdf-ocr-batch（批量 PDF OCR 与文本提取）

• 适用场景 ：法务部门每日收到 200+ 份扫描版 PDF 合同，需提取文字内容并归档至 Elasticsearch
• 核心能力 ：监听指定目录（如 ~/Legal/Inbox/），当新 PDF 文件到达，自动调用 Tesseract OCR（支持中英日韩），输出纯文本 + 结构化 JSON（含 page_count, text_length, confidence_score），并触发后续 Elasticsearch 索引动作
• 为什么选它 ：Adobe Acrobat 的批处理功能需 GUI，无法后台运行；Python 的 PyPDF2 无法处理扫描件。此 Skill 封装了 Tesseract 的多线程调用（--tessdata-dir 指向本地训练好的中文模型），并内置了 PDF 页面预处理（deskew, denoise, dpi upscale）管道
• 部署关键点 ：
  • 必须预先安装 Tesseract 5.3+ 和对应语言包（ sudo apt install tesseract-ocr tesseract-ocr-chi-sim ）
  • skill.yaml 中的 tessdata_dir 必须指向正确的路径（Ubuntu 通常是 /usr/share/tesseract-ocr/5/tessdata）
  • 对于高精度需求，建议在 skill.yaml 中设置 ocr_engine_mode: 1（LSTM only），比默认的 3（Legacy + LSTM）慢 3 倍但准确率高 12%
• 真实故障案例 ：某份合同扫描件 DPI 仅 72，OCR 结果全是乱码。Skill 日志显示 Error during deskew: cannot rotate image 。排查发现预处理脚本中 ImageMagick 的 convert 命令版本过旧（6.x），不支持 -deskew 。修复方案：升级 ImageMagick 至 7.1+，或在 skill.yaml 中设置 preprocess_enabled: false，改用 Tesseract 内置的 --psm 6 模式。

3.5 Skill #5：git-commit-linter（Git 提交信息合规检查）

• 适用场景 ：研发团队强制要求 commit message 符合 Conventional Commits 规范（如 feat(auth): add login button），并在 pre-commit 阶段拦截不合规提交
• 核心能力 ：作为 Git hook（pre-commit），解析 git log -1 --pretty=%B，用正则校验格式；若不匹配，输出详细错误（如 “Expected format: ( ): ，got 'update readme'”），并提供自动修复建议（ git commit --amend -m "chore(docs): update readme" ）
• 为什么选它 ：Husky + commitlint 方案需 Node.js 环境，而部分嵌入式团队只用 Python。此 Skill 纯 Python 实现，体积小（<50KB），且支持自定义 scope 白名单（如只允许 auth, billing, ui）和 subject 长度限制（max 72 chars）
• 部署关键点 ：
  • 必须手动将 Skill 的 pre-commit hook 脚本复制到 .git/hooks/pre-commit（ cp $(openclaw skill path git-commit-linter)/hooks/pre-commit .git/hooks/ ）
  • chmod +x .git/hooks/pre-commit，否则 Git 会忽略
  • 若项目已存在 .git/hooks/pre-commit，需将其内容追加到新脚本末尾，而非覆盖
• 真实故障案例 ：某次 CI 流水线失败，日志显示 pre-commit hook failed with exit code 1 ，但本地 git commit 正常。排查发现 CI 环境的 Git 版本为 2.25，而 Skill 中使用的 git log -1 --pretty=%B 在该版本下对 merge commit 返回空。修复方案：在 hook 脚本中增加判断 if git rev-parse --verify HEAD >/dev/null 2>&1; then ... else exit 0; fi ，跳过 merge commit 检查。

3.6 Skill #6：network-ping-monitor（局域网设备存活监控）

• 适用场景 ：IT 运维需监控机房内 50+ 台网络设备（交换机、UPS、温湿度传感器）的在线状态，并在离线时微信告警
• 核心能力 ：读取配置文件（devices.yaml）中的 IP 列表，每 30 秒并发 ping 一次（使用 python3 -m asyncio + aiohttp），记录响应时间、丢包率；若连续 3 次超时，触发微信机器人 webhook（需配置 corpid/corpsecret）
• 为什么选它 ：Zabbix 部署复杂，Nagios 配置繁琐。此 Skill 零依赖（仅需 Python 3.8+），配置即代码（YAML），且支持分组告警（如 “核心网络设备离线” vs “测试设备离线”）
• 部署关键点 ：
  • Linux 需赋予 Python 程序 raw socket 权限（ sudo setcap 'cap_net_raw+ep' $(which python3) ），否则 ping 会失败
  • devices.yaml 中的 group 字段必须与微信机器人告警模板中的 group_key 一致
  • 首次运行 openclaw skill run network-ping-monitor --once 进行配置验证，确认所有 IP 可达
• 真实故障案例 ：某台 UPS 设备防火墙禁用了 ICMP，但开放了 SNMP。Skill 持续报 “offline”，实际设备正常。修复方案：在 devices.yaml 中为该设备添加 ping_method: snmp ，并配置 community_string 和 oid（如 .1.3.6.1.4.1.318.1.1.1.12.1.3.0 读取电池状态），Skill 会自动切换探测方式。

3.7 Skill #7：excel-validator（Excel 表格业务规则校验）

• 适用场景 ：财务部门每月接收销售部提交的 Excel 销售报表，需校验金额列是否为数字、日期列是否在有效范围内、客户 ID 是否存在于主数据表
• 核心能力 ：接收 Excel 文件路径，加载 pandas DataFrame，按 rules.yaml 中定义的规则逐列校验（如 column: "amount", type: "numeric", min: 0；column: "date", type: "date", range: ["2024-01-01", "2024-12-31"]），输出 HTML 校验报告（含错误行号、错误原因、截图）
• 为什么选它 ：Excel 内置的数据验证只能做简单类型检查，无法跨表关联校验。此 Skill 支持引用外部 CSV 主数据表（如 customers.csv），实现 customer_id 的存在性检查，且校验逻辑可版本化管理
• 部署关键点 ：
  • 必须安装 openpyxl 和 pandas（ pip install openpyxl pandas ）
  • rules.yaml 中的 external_ref 字段必须是绝对路径，或相对于 skill.yaml 的相对路径
  • 校验报告默认保存在 ~/Downloads/excel-validator-report-YYYYMMDD-HHMMSS.html ，可在 skill.yaml 中修改 output_dir
• 真实故障案例 ：某次校验报告中，所有日期列都报 “invalid date format”，但 Excel 中显示正常。排查发现 Excel 单元格格式为 “自定义”，实际存储值是浮点数（Excel 日期序列号）。修复方案：在 rules.yaml 中为 date 列添加 excel_date_serial: true ，Skill 会自动转换。

3.8 Skill #8：log-anomaly-detector（日志异常模式识别）

• 适用场景 ：运维团队需从 Nginx/应用日志中，实时识别出异常模式（如 500 错误突增、SQL 注入特征、暴力破解 IP）
• 核心能力 ：监听日志文件（tail -f），用滑动窗口（默认 60 秒）统计错误码频次、正则匹配攻击特征（如 union select 、 sleep\( ），当频次超过阈值（如 500 错误 > 10 次/分钟），输出告警 JSON 并触发 Slack 通知
• 为什么选它 ：ELK Stack 需要整套基础设施；GoAccess 只做统计，不识别异常。此 Skill 轻量（<10MB 内存）、可嵌入、规则 YAML 化，且支持自定义正则和动态阈值（如根据历史均值自动调整）
• 部署关键点 ：
  • 必须确保 OpenClaw 进程对日志文件有读取权限（ chmod 644 /var/log/nginx/access.log ）
  • skill.yaml 中的 log_path 必须是绝对路径，且不能是符号链接（tail -f 对 symlink 不稳定）
  • 首次运行建议加 --dry-run 参数，观察规则匹配效果，再启用通知
• 真实故障案例 ：某次告警频繁触发，日志显示 “SQL injection pattern matched: 'or 1=1'”，但实际是正常业务 SQL。排查发现规则中的正则过于宽泛 r"or\s+\d+=\d+" 。修复方案：改为 r"(?i)select.*from.*where.*or\s+\d+=\d+" ，增加上下文限定。

3.9 Skill #9：slack-thread-summarizer（Slack 频道长对话摘要）

• 适用场景 ：产品团队在 Slack #feature-discussion 频道讨论新需求，消息超 500 条，需自动生成会议纪要
• 核心能力 ：监听指定 Slack channel，当新消息包含关键词（如 “总结一下”、“meeting notes”），自动抓取最近 100 条消息，过滤掉 bot 消息和表情，用本地 LLM（Ollama）生成摘要，以 thread 形式回复
• 为什么选它 ：Slack 官方 Summary 功能需付费且不支持自定义模型。此 Skill 完全离线，摘要质量取决于你选择的本地模型，且支持引用原文（摘要中带消息链接）
• 部署关键点 ：
  • 必须在 Slack App 管理后台创建 Bot，获取 Bot User OAuth Token，并填入 skill.yaml 的 slack_token
  • 需开启 Bot 的 channels:history, chat:write, reactions:read 权限
  • 本地 LLM 必须已加载（如 ollama run phi3 ），且 skill.yaml 中的 llm_model 指向正确名称
• 真实故障案例 ：摘要生成后，Slack 显示 “message is too long”，无法发送。排查发现摘要文本超 4000 字符。修复方案：在 skill.yaml 中设置 max_summary_length: 3000，并启用 truncate_on_overflow: true。

3.10 Skill #9：wifi-ap-switcher（WiFi 热点自动切换）

• 适用场景 ：现场工程师携带笔记本电脑巡检工厂设备，需在不同区域自动连接不同 WiFi（如 A区连 factory-a，B区连 factory-b），并关闭 Windows 自带热点
• 核心能力 ：每 30 秒扫描周围 WiFi，根据 signal_strength 和 ssid 白名单（whitelist.yaml）自动 connect/disconnect；检测到 Windows Hotspot 开启时，自动执行 netsh wlan set hostednetwork setting=disabled
• 为什么选它 ：Windows 的 WiFi 自动切换逻辑简单（只记最强信号），无法按区域策略切换。此 Skill 支持地理围栏（GPS 坐标 + 信号强度加权），且可集成到 OpenClaw 的定时任务中
• 部署关键点 ：
  • Windows 需以管理员权限运行 OpenClaw（右键 -> 以管理员身份运行）
  • whitelist.yaml 中的 ssid 必须与路由器广播的 SSID 完全一致（区分大小写）
  • 首次运行 openclaw skill run wifi-ap-switcher --scan ，确认能正确识别所有目标 WiFi
• 真实故障案例 ：某次切换失败，日志显示 Failed to connect to factory-a: The network connection was refused 。排查发现 factory-a 路由器开启了 MAC 地址过滤，而笔记本的 WiFi 适配器 MAC 地址未被添加。修复方案：在 whitelist.yaml 中为 factory-a 添加 mac_whitelist: ["aa:bb:cc:dd:ee:ff"] ，Skill 会自动在连接前设置适配器 MAC。

4. 技能开发避坑指南：从 “能跑” 到 “可交付” 的 7 个硬性标准

很多开发者在掌握了 openclaw skill add 基本用法后，会跃跃欲试自己开发 Skill。但很快就会发现，写一个“能跑”的脚本和写一个“可交付”的 Skill，中间隔着一堵墙。这堵墙不是技术，而是工程规范。我们团队内部有一份《OpenClaw Skill 交付清单》，任何提交到生产环境的 Skill，必须 100% 满足以下 7 条，否则不予上线。这些标准，是我踩了至少 15 次坑后总结出来的血泪教训。

4.1 标准一：必须有可重复的本地验证流程（Not “It Works on My Machine”）

一个 Skill 的 test.py，绝不能是 assert True 或 print("hello world") 。它必须模拟真实调用链路。例如，一个调用外部 API 的 Skill，test.py 必须：

• 启动一个 mock server（如 using httpx.MockTransport），返回预设 JSON
• 调用 Skill 的 main() 函数，传入 mock 参数
• 断言返回结果的 status_code、body 字段、以及是否触发了预期的 side effect（如是否写了文件、是否发了通知）

我们曾有一个 “飞书通知” Skill，在开发者本地测试时一切正常，上线后却 100% 失败。原因是 test.py 里用的是 requests.get("https://open.feishu.cn/") ，而生产环境代理设置不同，mock server 没起作用。修复后，test.py 变成：

# test.py
import pytest
from httpx import MockTransport, Response
from my_skill import main

def test_feishu_notify():
    def handler(request):
        assert request.method == "POST"
        assert request.url.path == "/open-apis/bot/v2/hook/xxx"
        return Response(200, json={"status": "success"})
    
    transport = MockTransport(handler)
    # ... (其他 setup)
    result = main(message="test", transport=transport)
    assert result["status"] == "success"

注意：OpenClaw 的 openclaw skill verify 命令，会自动注入 --test-mode 参数，你的 main.py 必须能识别并切换到 mock 模式。这是强制约定。

4.2 标准二：输入参数必须有 Schema 校验，拒绝 “duck typing”

很多 Skill 的入口函数是 def main(input_data) ，然后直接 input_data["url"] 。这在原型阶段很爽，但在生产环境就是灾难。一个 typo 的 key 名，会导致整个流程静默失败。正确的做法是，定义 Pydantic V2 的 InputModel：

# models.py
from pydantic import BaseModel, Field
from typing import Optional

class WebhookInput(BaseModel):
    url: str = Field(..., description="Target webhook URL, must start with https://")
    payload: dict = Field(default_factory=dict, description="JSON payload to send")
    timeout: int = Field(ge=1, le=30, default=10, description="Request timeout in seconds")

# main.py
def main(input_data: dict):
    try:
        validated = WebhookInput(**input_data)  # 自动校验 & 类型转换
    except ValidationError as e:
        raise ValueError(f"Invalid input: {e}")
    # ... rest of logic

这样，当用户传入 {"urll": "https://..."} 时，Skill 会明确报错 Field required [type=missing, input_value={'urll': 'https://...'}, input_type=dict] ，而不是在后续 validated.url 时抛出 KeyError 。

4.3 标准三：所有外部依赖必须声明在 skill.yaml 的 requires 字段，且版本锁定

requires: ["python>=3.8", "requests>=2.28.0,<3.0.0"] 是底线。但更进一步，对于 C 扩展库（如 numpy, pandas），必须指定 ABI 兼容性：

requires:
  - "python>=3.9"
  - "numpy>=1.24.0; platform_system == 'Linux'"
  - "numpy>=1.24.0; platform_system == 'Darwin'"
  - "numpy>=1.24.0; platform_system == 'Windows'"

我们曾因没加 platform_system 限定，在 M1 Mac 上安装了一个 x86_64 的 numpy wheel，导致 import numpy 失败。OpenClaw 的依赖解析器会根据当前 platform_system 自动选择匹配项。

4.4 标准四：必须有明确的错误分类与用户友好的错误消息

Skill 的错误，不能是 Traceback (most recent call last): ... OSError: [Errno 13] Permission denied 。用户不需要知道是哪个系统调用失败。必须将底层异常映射为业务错误：

try:
    with open(config_file, "r") as f:
        config = json.load(f)
except FileNotFoundError:
    raise UserError(f"Config file not found: {config_file}. Please create it first.")
except PermissionError:
    raise UserError(f"Permission denied reading {config_file}. Please check file ownership.")
except json.JSONDecodeError as e:
    raise UserError(f"Invalid JSON in {config_file} at line {e.lineno}: {e.msg}")

UserError 是 OpenClaw 提供的基类，它会被捕获并以 ERROR: <message> 格式输出，不显示 traceback。而 RuntimeError 或 ValueError 会被视为未处理异常，显示完整 traceback，用于调试。

4.5 标准五：所有敏感信息（token, password）必须通过环境变量注入，禁止硬编码或明文配置文件

skill.yaml 中绝不允许出现 api_token: "xxxxx" 。正确方式是：

# skill.yaml
env_vars:
  - FEISHU_BOT_TOKEN
  - DATABASE_URL

然后在 main.py 中：

import os
bot_token = os.getenv("FEISHU_BOT_TOKEN")
if not bot_token:
    raise UserError("FEISHU_BOT_TOKEN environment variable is not set")

OpenClaw 在执行 Skill 前，会自动将 skill.yaml 中声明的 env_vars 从宿主机环境继承过来。这保证了 token 不会泄露在 Git 历史中。

4.6 标准六：必须有资源清理钩子（cleanup hook），防止“幽灵进程”

一个 Skill 启动了后台进程（如 subprocess.Popen(["python", "server.py"]) ），如果 Skill 主进程被 kill，这个后台进程会变成孤儿，持续占用端口和内存。必须在 Skill 退出时清理：

import atexit
import subprocess

_server_proc = None

def _start_server():
    global _server_proc
    _server_proc = subprocess.Popen(["python", "server.py"])

def _cleanup():
    if _server_proc and _server_proc.poll() is None:
        _server_proc.terminate()
        _server_proc.wait(timeout=5)

atexit.register(_cleanup)  # 确保进程退出时调用

OpenClaw 的 openclaw skill stop <skill-name> 命令，会向 Skill 进程发送 SIGTERM，触发 atexit。

4.7 标准七：必须有性能基准测试（benchmark），并写入 README.md

每个 Skill 的 README.md，必须包含一个 ## Performance 章节，内容如下：

Scenario	Input Size	Avg Latency	P95 Latency	Memory Usage
Small	1 KB JSON	120 ms	180 ms	15 MB
Medium	100 KB PDF	2.1 s	3.4 s	85 MB
Large	10 MB Log	8.7 s	12.3 s	210 MB

这个数据必须来自 openclaw skill benchmark <skill-name> --scenarios=small,medium,large 的实测结果。它让用户在部署前，就能评估对系统资源的影响，避免上线后才发现吃光内存。

5. 生产环境部署 checklist：从单机到集群的 12 个必检项

当你的 Skill 开发完成并通过所有测试，准备部署到客户现场时，别急着 openclaw skill add 。我们有一份经过 23 个客户现场验证的部署 checklist。漏掉任何一项，都可能导致上线后第一周就接到紧急电话。这份清单，按优先级排序，越靠前的项，影响越大。

5.1 检查项 #1：确认 OpenClaw 版本与 Skill 兼容性

OpenClaw 的 major version（如 2026.x）有 breaking change。一个为 2025.3 开发的 Skill，可能在 2026.2 上因 API 变更而失败。 openclaw --version 输出的格式是 `openclaw