添加第一个技能

技能 (Skills) 是 OpenClaw 的核心能力扩展机制。这一页带你理解技能是什么、如何添加、以及如何让技能真正发挥作用。

技能是什么

技能是预定义的能力模块，让 Agent 能够执行特定类型的任务。比如：

• 网页搜索 - 让 Agent 能搜索互联网获取最新信息
• 天气查询 - 让 Agent 能查询天气信息
• 文件操作 - 让 Agent 能读写本地文件
• 代码执行 - 让 Agent 能运行代码片段

技能与工具的区别

很多初学者会把技能和工具混为一谈。它们的区别是：

简单记法：技能是"能做什么"，工具是"用什么做"。

技能市场

OpenClaw 有一个丰富的技能市场，目前已有 349+ 开源技能可供使用。

浏览可用技能

# 列出所有可用技能
openclaw skills list

# 搜索特定技能
openclaw skills search weather

# 查看技能详情
openclaw skills info web-search

通过 Control UI 浏览

1. 打开 openclaw dashboard
2. 进入 Skills 页面
3. 浏览分类或搜索关键词
4. 查看技能评分和使用量

技能选择指南

在技能市场中选择技能时，建议参考这些标准：

安装技能

通过 CLI 安装

# 安装官方技能
openclaw skills install web-search

# 安装社区技能
openclaw skills install community/weather-alert

# 从本地路径安装
openclaw skills install ./my-custom-skill

通过配置文件

在 Agent 配置中添加：

{
  "skills": [
    "web-search",
    "weather",
    "calculator"
  ]
}

配置技能

很多技能需要额外配置才能正常工作：

API 密钥配置

{
  "skills": {
    "web-search": {
      "provider": "google",
      "apiKey": "${GOOGLE_SEARCH_API_KEY}",
      "searchEngineId": "${SEARCH_ENGINE_ID}"
    }
  }
}

环境变量方式

推荐使用环境变量管理敏感信息：

# ~/.openclaw/.env
GOOGLE_SEARCH_API_KEY=your-api-key
SEARCH_ENGINE_ID=your-engine-id

然后在配置中引用：

{
  "skills": {
    "web-search": {
      "apiKey": "${GOOGLE_SEARCH_API_KEY}"
    }
  }
}

技能依赖管理

安装技能时注意它的依赖关系：

• API 依赖：技能需要调用外部 API，确保你有对应的 API Key 并已正确配置
• 工具依赖：某些技能依赖特定的工具，需要先启用对应的工具
• 版本依赖：部分技能需要特定版本的 Gateway，安装前查看兼容性
• 权限依赖：声明了特定权限的技能，需要先在 Gateway 中授权

常用技能推荐

信息获取类

生产力类

开发者类

按场景选择技能组合

根据你的需求场景，推荐这些技能组合：

个人日常助理：web-search + weather + notes + calendar + tasks

学习研究助手：web-search + wikipedia + news + translator + notes

开发者工具：github + code-exec + web-search + docker（可选）

内容创作助手：web-search + notes + news + translator

创建自定义技能

如果现有技能不能满足需求，可以创建自定义技能：

技能结构

my-skill/
├── skill.json       # 技能元数据
├── prompt.md        # 提示词模板
├── tools.json       # 工具定义
└── examples/        # 示例对话
    └── example1.md

skill.json 示例

{
  "name": "my-custom-skill",
  "version": "1.0.0",
  "description": "我的自定义技能",
  "author": "your-name",
  "tools": ["tool1", "tool2"],
  "prompts": ["prompt.md"],
  "examples": ["examples/example1.md"]
}

提示词模板

# My Custom Skill

你是一个专业的助手，擅长处理以下任务：

1. 任务类型 A
2. 任务类型 B

当用户请求帮助时，你应该：
- 首先理解用户的具体需求
- 提供清晰、结构化的回答
- 必要时使用可用工具

自定义技能的最佳实践

• 单一职责：一个技能只做一件事，做好一件事
• 清晰命名：技能名称和描述应让用户一眼知道它能做什么
• 完整示例：提供至少 1-2 个示例对话，帮助 Agent 理解使用场景
• 声明权限：明确声明技能需要的 API、工具和权限
• 版本管理：使用语义化版本号，方便跟踪变更

测试技能

安装技能后，测试是否正常工作：

# 测试特定技能
openclaw skills test web-search --query "今天的新闻"

# 检查技能状态
openclaw skills status

# 查看技能日志
openclaw skills logs web-search

技能测试检查清单

完成基础测试后，逐条确认：

• 技能能被 Agent 正确识别和调用
• 技能调用返回了预期结果
• 配置的 API Key 有效，没有认证错误
• 技能在对话中的表现符合预期
• 技能调用速度在可接受范围内
• 如果依赖外部服务，服务可用性正常

技能管理

更新技能

# 更新单个技能
openclaw skills update web-search

# 更新所有技能
openclaw skills update --all

禁用技能

# 临时禁用
openclaw skills disable web-search

# 重新启用
openclaw skills enable web-search

卸载技能

openclaw skills uninstall web-search

技能生命周期管理

安装技能后，建议定期做这些维护工作：

• 月度检查：检查已安装技能是否有可用更新
• 使用审计：查看哪些技能被高频使用，哪些几乎没用
• 清理冗余：卸载不再使用的技能，减少上下文噪声
• 配置验证：API Key 是否过期？需要更新的配置是否已经更新？

技能组合与冲突处理

当 Agent 配置了多个技能时，注意这些组合问题：

技能优先级

如果多个技能有重叠能力，Agent 可能不知道该调用哪个。解决方法：

• 确保技能描述足够精确，Agent 能根据描述区分
• 避免安装功能高度重叠的技能
• 必要时通过配置调整技能调用优先级

常见冲突模式

常见技能误区

技能对性能的影响

技能不是免费的。每个已安装并启用的技能都会影响 Agent 的表现：

• 上下文消耗：Agent 需要理解每个技能的描述和调用规则，技能越多 token 消耗越大
• 决策延迟：Agent 需要在多个技能中选择合适的那个，技能越多决策时间越长
• 错误概率：更多技能意味着更多可能的调用失败点

建议控制单个 Agent 的技能数量在 5-8 个以内，超过这个数量后性价比明显下降。

常见问题

技能安装失败

检查：

• 网络连接是否正常
• 技能名称是否正确
• 是否有必要的权限
• 技能市场是否可访问

技能不工作

检查：

• 配置是否正确
• API 密钥是否有效
• 查看技能日志排查问题
• 技能是否需要特定的 Gateway 版本

技能冲突

如果多个技能有重叠功能：

• 检查技能优先级配置
• 考虑只保留必要的技能
• 使用技能分组管理

Agent 没有调用已安装的技能

检查：

• 技能是否被正确分配给了 Agent
• Agent 的 systemPrompt 是否覆盖了该技能的使用场景
• 技能的触发关键词或条件是否合理

技能调用返回错误

检查：

• API Key 是否过期
• 外部服务是否可用
• 传入参数是否符合技能要求
• 查看技能错误日志获取详细信息

下一步

• 技能系统详解
• 自定义技能开发
• 工具配置指南
• 技能市场浏览