OpenClaw 3.13 Skill编写初探（Docker）

基于"say hello" skill尝试开发总结

🎯 核心理解

OpenClaw 技能的本质

SKILL.md 是纯文档 - 只描述技能，不执行代码
技能激活是提示 - 告诉助手这个技能相关
助手手动执行 - 看到技能激活后，助手调用实际脚本
返回脚本输出 - 把脚本执行结果返回给用户

错误理解 vs 正确理解

❌ 错误：SKILL.md 包含可执行逻辑
✅ 正确：SKILL.md 只是说明书，代码在 scripts/ 目录
❌ 错误：技能自动运行脚本
✅ 正确：助手看到技能后手动运行脚本

📁 最简技能结构

必需文件

复制代码

my-skill/
├── SKILL.md      # 技能描述（必需）
└── scripts/      # 脚本目录（推荐）
    └── main.py   # 主脚本

可选文件

复制代码

my-skill/
├── skill.json    # 配置（可选）
└── references/   # 参考文档（可选）

📝 SKILL.md 编写

最简模板

markdown 复制代码

# 技能名称

## 描述
一句话说明技能功能。

## 使用场景
用户说什么话时激活。

## 执行指令
```bash
cd /path/to/skill/scripts && python3 main.py

示例输出

复制代码

这里是脚本执行后的输出示例。

### 小东技能示例
```markdown
# 小东 - 简洁打招呼

## 描述
当用户说"小东"时回复问候和当前时间。

## 使用场景
用户说 "小东"

## 执行指令
```bash
cd /home/node/.openclaw/workspace/skills/xiaodong/scripts && python3 simple_hello.py

示例输出

复制代码

在呢！晚上好啊，现在是 2026-03-22 23:56 (北京时间)。需要我干点啥不？

---

## 🐍 Python 脚本编写

### 最简模板
```python
#!/usr/bin/env python3
# scripts/main.py

def main():
    # 你的业务逻辑
    result = "处理结果"
    print(result)  # 重要：使用 print 输出结果

if __name__ == '__main__':
    main()

小东脚本示例

python 复制代码

#!/usr/bin/env python3
# scripts/simple_hello.py

import datetime

def get_beijing_time():
    """获取北京时间 (UTC+8)"""
    utc_now = datetime.datetime.now(datetime.timezone.utc)
    return utc_now + datetime.timedelta(hours=8)

def get_greeting(hour):
    """根据小时返回问候语"""
    if 5 <= hour < 12: return "早上好"
    elif 12 <= hour < 14: return "中午好"
    elif 14 <= hour < 18: return "下午好"
    else: return "晚上好"

def main():
    beijing_time = get_beijing_time()
    hour = beijing_time.hour
    greeting = get_greeting(hour)
    time_str = beijing_time.strftime("%Y-%m-%d %H:%M")
    
    # 输出结果，助手会把这个返回给用户
    print(f"在呢！{greeting}啊，现在是 {time_str} (北京时间)。需要我干点啥不？")

if __name__ == '__main__':
    main()

🚀 开发流程

1. 创建目录

bash 复制代码

mkdir my-skill
cd my-skill
mkdir scripts

2. 编写脚本

bash 复制代码

cat > scripts/main.py << 'EOF'
#!/usr/bin/env python3
print("这是我的技能输出")
EOF

chmod +x scripts/main.py

3. 编写 SKILL.md

bash 复制代码

cat > SKILL.md << 'EOF'
# 我的技能

## 描述
测试技能

## 使用场景
用户说 "测试"

## 执行指令
```bash
cd /path/to/my-skill/scripts && python3 main.py

示例输出

复制代码

这是我的技能输出

EOF

复制代码

### 4. 部署技能
```bash
# 复制到工作区技能目录
cp -r my-skill /home/node/.openclaw/workspace/skills/

5. 测试技能

用户说技能关键词（如"测试"）
助手看到技能激活
助手手动执行 ：cd /path/to/skill/scripts && python3 main.py
助手返回脚本输出

📍 部署位置

正确位置（推荐）

复制代码

/home/node/.openclaw/workspace/skills/my-skill/

权限要求

目录所有者必须是 node 用户
OpenClaw 以 node 用户运行

🔧 调试技巧

1. 手动测试脚本

bash 复制代码

cd /path/to/skill/scripts
python3 main.py

2. 检查权限

bash 复制代码

ls -la /home/node/.openclaw/workspace/skills/my-skill/
# 应该显示所有者是 node

3. 检查技能激活

用户说定义的关键词
助手应该看到技能提示
助手手动执行脚本

4. 查看脚本输出

bash 复制代码

# 直接运行看输出
python3 scripts/main.py

❌ 常见误区

误区1：SKILL.md 包含可执行代码

❌ 错误：在 SKILL.md 中写 Python 代码
✅ 正确：SKILL.md 只写描述，代码在 scripts/

误区2：技能自动运行

❌ 错误：认为技能关键词会自动触发脚本
✅ 正确：助手看到关键词后手动运行脚本

误区3：需要 .sh 包装脚本

❌ 错误：创建 run.sh 包装 Python 脚本
✅ 正确：直接执行 Python 脚本更简洁

误区4：复杂目录结构

❌ 错误：创建复杂的 references/ assets/ 等目录
✅ 正确：从最简结构开始，需要时再添加

🎯 最佳实践

1. 保持简洁

一个技能解决一个问题
最简文件结构：SKILL.md + scripts/main.py
避免不必要的配置文件

2. 明确输出

脚本使用 print() 输出结果
输出格式友好，适合直接显示
包含必要的上下文信息

3. 完整文档

SKILL.md 包含清晰的执行指令
提供示例输入和输出
说明技能的使用场景

4. 易于测试

脚本可以独立运行测试
提供简单的测试方法
输出结果可预测

📚 小东技能完整代码

文件结构

复制代码

xiaodong/
├── SKILL.md
└── scripts/
    └── simple_hello.py

SKILL.md

markdown 复制代码

# 小东 - 简洁打招呼

## 描述
当用户说"小东"时回复问候和当前时间。

## 使用场景
用户说 "小东"

## 执行指令
```bash
cd /home/node/.openclaw/workspace/skills/xiaodong/scripts && python3 simple_hello.py

示例输出

复制代码

在呢！晚上好啊，现在是 2026-03-22 23:56 (北京时间)。需要我干点啥不？

### scripts/simple_hello.py
```python
#!/usr/bin/env python3
import datetime

def get_beijing_time():
    utc_now = datetime.datetime.now(datetime.timezone.utc)
    return utc_now + datetime.timedelta(hours=8)

def get_greeting(hour):
    if 5 <= hour < 12: return "早上好"
    elif 12 <= hour < 14: return "中午好"
    elif 14 <= hour < 18: return "下午好"
    else: return "晚上好"

def main():
    beijing_time = get_beijing_time()
    hour = beijing_time.hour
    greeting = get_greeting(hour)
    time_str = beijing_time.strftime("%Y-%m-%d %H:%M")
    print(f"在呢！{greeting}啊，现在是 {time_str} (北京时间)。需要我干点啥不？")

if __name__ == '__main__':
    main()