Skip to content
OpenClaw 书稿预览

第13章 Skill进阶：让它稳定可靠

🎯 本章目标：学完这章，你能把“能跑”的 Skill 做成“稳定可复用”的 Skill

⏱️ 预计时间：25分钟

📋 前置要求：已完成第12章（写第一个 Skill）

本章你将学会什么

Section titled “本章你将学会什么”
  • 幂等性（可理解为“重复点两次也不出双份”）
  • 错误处理：失败时给出可执行下一步
  • 超时与重试：避免任务卡死
  • 限流与降级：避免额度和成本失控
  • 文档与版本：让迭代可追溯、可回滚

13.1 幂等性（重复执行不出双份）

Section titled “13.1 幂等性（重复执行不出双份）”

13.1.1 为什么 Skill 特别需要幂等（防止重复产出）

Section titled “13.1.1 为什么 Skill 特别需要幂等（防止重复产出）”

在真实环境里，同一个 Skill 可能被重复触发：

  1. 用户连续点了两次；
  2. 上游渠道重试；
  3. 你手动重跑任务做校验。

如果 Skill 非幂等，结果常见是：重复写文件、重复发消息、重复调用外部 API。

13.1.2 幂等的三条实操规则（都很接地气）

Section titled “13.1.2 幂等的三条实操规则（都很接地气）”
  1. 输出路径可预测：同一个输入，输出到同一个目标。
  2. 先查状态再动作：已有结果就直接返回，不重复执行。
  3. 覆盖写优先于追加写：减少重复内容堆积。

补一条官方实践：路径尽量用 Skill 相对上下文变量（如 {baseDir}）推导，少写死绝对路径，迁移 workspace 时不容易炸。

13.1.3 示例：把“每日报告”做成幂等

Section titled “13.1.3 示例：把“每日报告”做成幂等”
## Steps


1. 解析日期 date（默认今天）。
2. 计算输出文件：reports/daily-{date}.md。
3. 如果文件已存在：
   - 读取并返回摘要；
   - 不重复写入。
4. 若不存在：生成完整内容并一次性写入。

13.2 错误处理：失败时给清楚下一步

Section titled “13.2 错误处理：失败时给清楚下一步”

13.2.1 错误分层（别把所有错误混成一句“失败”）

Section titled “13.2.1 错误分层（别把所有错误混成一句“失败”）”

建议至少分三层：

  • 输入错误：参数不合法、缺关键输入；
  • 环境错误：缺依赖、权限不足、路径不存在；
  • 外部错误：网络波动、第三方服务异常。

13.2.2 返回信息模板（对小白友好）

Section titled “13.2.2 返回信息模板（对小白友好）”

失败时至少给三段信息：

  1. 发生了什么（What）
  2. 可能原因（Why）
  3. 下一步该做什么（Next）

示例：

日报生成失败：无法写入 reports 目录。
可能原因：当前目录无写权限。
下一步：请先执行 mkdir -p reports，并确认目录可写后重试。

13.2.3 Skill 内写法建议

Section titled “13.2.3 Skill 内写法建议”
## Steps


1. 校验输入 date 格式（YYYY-MM-DD）。
2. 若格式错误，直接返回“输入错误 + 正确示例”。
3. 写文件前先检查目标目录是否可写。
4. 若不可写，返回“修复命令 + 重试建议”。

13.3 超时与重试：别让卡住的调用拖死

Section titled “13.3 超时与重试：别让卡住的调用拖死”

13.3.1 不要“无限等待”

Section titled “13.3.1 不要“无限等待””

官方 exec 工具支持 timeout（秒）、yieldMs、background。
只要你的 Skill 涉及命令执行，就要给上限时间，别让会话一直挂住。

示意（概念）：

调用 exec 时设置 timeout=30（秒）
超时后返回“本次操作已中止，请稍后重试”

如果你是通过工具参数写法，建议同时把“是否转后台”写清楚，避免“看起来卡住”：

exec:
  timeout: 30
  yieldMs: 5000
  background: true

补充一点：进入后台后要记得用 process 轮询结果，不然你只知道“发起了”，不知道“有没有跑完”。

13.3.2 重试要“有限次 + 有间隔”

Section titled “13.3.2 重试要“有限次 + 有间隔””

重试不是越多越好，推荐你这样做：

  • 最多 2~3 次
  • 每次有递增等待（例如 2s → 5s → 10s）
  • 只对“临时性错误”重试（网络超时、503）

对“确定性错误”（参数错、权限错）不重试，直接给修复建议。

13.3.3 在 Skill 里怎么表达

Section titled “13.3.3 在 Skill 里怎么表达”
## Steps


1. 第一次请求失败且属于临时错误时，等待 2 秒后重试。
2. 第二次失败再等待 5 秒重试。
3. 第三次失败停止，返回明确错误与人工处理建议。

13.3.4 exec 的安全底线（别省）

Section titled “13.3.4 exec 的安全底线（别省）”

官方文档明确：exec approvals 是工具策略之外的第二道防线。
实操上建议你记住两句：

  1. 先用“基础档位 + 放行名单 + 禁用名单”（tools.profile / allow / deny）缩小可执行范围；
  2. 再用审批策略兜底“高风险命令必须确认”。

尤其要避免误用 security=full 作为默认值——它是给受控场景的“快速通道”，不适合作为新手常态配置。

13.4 限流与降级：保护额度与成本

Section titled “13.4 限流与降级：保护额度与成本”

13.4.1 限流：先保护系统，再谈体验

Section titled “13.4.1 限流：先保护系统，再谈体验”

高频任务建议做“入口限流”：

  • 单用户短时间内最多触发 N 次；
  • 超出后返回“稍后再试”而不是硬跑；
  • 在群聊场景尤其重要。

小白可直接用一句话落地：
宁可“慢一点 + 可恢复”，也不要“快一点 + 全线雪崩”。

13.4.2 降级：主链路失败时有 B 计划

Section titled “13.4.2 降级：主链路失败时有 B 计划”

典型降级顺序：

  1. 主流程（全功能）
  2. 轻量流程（少工具、短输出）
  3. 最后兜底（只返回可执行建议）

13.4.3 用官方工具策略做“硬保险”

Section titled “13.4.3 用官方工具策略做“硬保险””

你可以在配置层限制高风险工具暴露范围，例如：

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"]
  }
}

需要执行命令时再临时放开，比默认全开安全得多。

再补一个更稳的降级打法（按模型降权限）：

{
  tools: {
    profile: "coding",
    byProvider: {
      "openai/gpt-5.2": { profile: "minimal" }
    }
  }
}

含义：全局默认给 coding，但对你观察到“不稳定”的某个 provider/model，单独收紧到 minimal。

可用键有两种：

  • provider（例如 google-antigravity）
  • provider/model（例如 openai/gpt-5.2）

记忆方式：先全局给能力，再对特定模型做减法。

13.5 文档与版本：让 Skill 可维护

Section titled “13.5 文档与版本：让 Skill 可维护”

13.5.1 版本号用语义化规范

Section titled “13.5.1 版本号用语义化规范”

采用 MAJOR.MINOR.PATCH：

  • MAJOR：不兼容变更
  • MINOR：兼容新增功能
  • PATCH：兼容修复

13.5.2 CHANGELOG 最小模板

Section titled “13.5.2 CHANGELOG 最小模板”
# Changelog


## [1.1.0] - 2026-02-20
### Added
- 支持 date 参数校验


### Changed
- 输出模板改为固定三段结构


### Fixed
- 修复重复触发导致重复写文件的问题

13.5.3 发布纪律（建议）

Section titled “13.5.3 发布纪律（建议）”
  1. 本地先过 skills list --eligible；
  2. 再跑一次 openclaw skills check；
  3. 预发布先看 clawhub sync --dry-run；
  4. 再 clawhub publish 或 clawhub sync --all；
  5. 发布时补 --changelog，别留“这版改了啥”黑盒；
  6. 版本和 changelog 一起提交，不做“裸发布”。

可直接按这个最小顺序执行：

Terminal window
openclaw skills list --eligible
openclaw skills check
clawhub sync --dry-run

确认后再发布：

Terminal window
clawhub sync --all

或发布单个 Skill：

Terminal window
clawhub publish <你的技能目录> --version <版本号> --changelog "<本次改动>"

13.6 生产级 Skill 检查清单

Section titled “13.6 生产级 Skill 检查清单”

发布前至少过一遍：

  • 同输入重复执行，结果一致（幂等）
  • 错误信息包含“原因 + 下一步”
  • 涉及命令执行的步骤有超时上限
  • 重试次数有限，并区分可重试/不可重试错误
  • 高风险工具有策略约束（profile/allow/deny/审批）
  • 若使用 sandbox，已验证容器内依赖与环境变量可用
  • 版本号和 changelog 已更新
  • 本地 openclaw skills list --eligible 通过
  • 本地 openclaw skills check 通过

本章小结

Section titled “本章小结”
  1. 稳定 Skill 的核心不是“写更多字段”，而是“流程可控”。
  2. 幂等、错误分层、超时重试，是最值钱的三件事。
  3. 限流和降级能把事故变成可恢复问题。
  4. 版本与 changelog 让你能回滚、能协作、能交接。

下一步：第14章，系统化排障（从现象到根因）。

动手试试

Section titled “动手试试”
  1. 拿你现有 Skill，检查是否幂等。
  2. 给失败路径补“下一步建议”。
  3. 把执行步骤补上超时与有限重试说明。
  4. 更新一次 changelog 并发布一个 patch 版本。
  5. 跑 openclaw skills list --eligible 做发布前门禁。