OpenClaw（Clawdbot）完全手册：Skill 体系、全平台部署、大模型 API 对接与问题排查

2026-03-23 3642

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

简介： OpenClaw（常被称作“小龙虾 AI”）是一套面向智能体的模块化执行框架，核心能力由 Skill 体系支撑。Skill 本质是可复用、可插拔的**专业能力扩展包**，将领域知识、执行流程、工具调用、模板资源封装为标准化结构，让基础大模型快速获得可落地的专业能力。

一、OpenClaw 与 Skill 核心原理

OpenClaw（常被称作“小龙虾 AI”）是一套面向智能体的模块化执行框架，核心能力由 Skill 体系支撑。Skill 本质是可复用、可插拔的专业能力扩展包，将领域知识、执行流程、工具调用、模板资源封装为标准化结构，让基础大模型快速获得可落地的专业能力。

1.1 Skill 的核心定位

领域专家知识库：承载垂直领域的专业知识与最佳实践
结构化工作流：明确任务执行步骤、参数规则、异常处理
可复用工具箱：集成脚本、API、命令行工具、参考文档
精准触发引擎：通过描述字段实现语义匹配，避免误调用
目前阿里云部署 OpenClaw 只需两步，全网最简单，步骤流程访问阿里云OpenClaw一键部署专题页面 了解。

1.2 为什么需要 Skill

原生大模型具备通用知识，但缺少程序性知识：

无明确操作步骤（如 PDF 旋转、天气查询、数据可视化）
无工具调用规范（如 curl、API 签名、环境依赖）
无领域边界（容易超出能力范围给出错误答案）
Skill 把这些能力固化，让 AI 从“通用对话”升级为“专业执行”。

1.3 Skill 触发与执行流程

用户提问 → 匹配 description → 加载 SKILL.md 上下文 → 调用工具/脚本 → 返回结构化结果
以天气查询为例：

匹配 weather Skill 的描述关键词
加载使用场景、命令、依赖
执行 curl wttr.in/城市名
格式化输出温度、降水、风力

1.4 Skill 标准目录结构

skill-name/
├── SKILL.md          # 必需：技能核心定义（元数据+使用指南）
├── scripts/           # 可选：可执行脚本（Python/Shell/JS）
├── references/        # 可选：API 文档、Schema、示例
└── assets/            # 可选：模板、图片、脚手架资源

1.5 SKILL.md 规范

SKILL.md 是 Skill 的入口文件，采用 YAML Frontmatter + Markdown 正文 结构。

1.5.1 YAML 元数据（必需）

---
name: pdf-rotate
description: "旋转 PDF 页面，支持 90/180/270 度，批量处理"
metadata:
  openclaw:
    emoji: "📄"
    requires:
      bins: ["python3", "pdftk"]
---

关键字段：

name：小写字母、数字、连字符，唯一标识
description：触发核心，写明用途、场景、边界
requires.bins：声明依赖命令行工具

1.5.2 Markdown 正文（必需）

When to Use：明确触发问句
When NOT to Use：避免越权场景
操作步骤：命令、参数、示例
常见问题：故障排查、注意事项

二、Skill 全生命周期管理

2.1 Skill 创建（标准化流程）

场景定义：明确用户问题、任务类型、边界
资源规划：确定脚本、参考文档、模板
初始化：用 init_skill.py 生成目录结构
编写 SKILL.md：完善元数据与使用指南
验证打包：执行打包脚本生成 .skill 压缩包

# 初始化 Skill
python3 scripts/init_skill.py --name pdf-rotate
# 打包 Skill
python3 scripts/package_skill.py ./skills/pdf-rotate

2.2 Skill 安装、搜索、卸载、更新

# 从 ClawHub 搜索
openclaw skills search weather
# 安装技能
openclaw skills install weather
# 本地安装
openclaw skills install ./pdf-rotate.skill
# 查看已安装
openclaw skills list
# 卸载
openclaw skills uninstall weather
# 检查更新
openclaw skills outdated
# 更新指定技能
openclaw skills update weather

2.3 多 Skill 协同与优先级

协同：一个任务可串联多个 Skill（PDF 提取 → 数据分析 → 报告生成）
优先级：语义匹配度 > 描述长度（更具体优先）

三、2026 年阿里云部署 OpenClaw 完整流程

3.1 环境准备

阿里云 ECS：2核 2GB 以上，Ubuntu 22.04
开通百炼大模型服务，获取 API Key
安全组开放 18789 端口（Web 控制台）

阿里云用户零基础部署 OpenClaw 喂饭级步骤流程

第一步：打开访问阿里云OpenClaw一键部署专题页面，找到并点击【一键购买并部署】。

第二步：打开选购阿里云轻量应用服务器，配置参考如下：

镜像：OpenClaw(Moltbot)镜像（已经购买服务器的用户可以重置系统重新选择镜像）
实例：内存必须2GiB及以上。
地域：默认美国（弗吉尼亚），目前中国内地域（除香港）的轻量应用服务器，联网搜索功能受限。
时长：根据自己的需求及预算选择。

轻量应用服务器OpenClaw镜像.png

第三步：打开访问阿里云百炼大模型控制台，找到密钥管理，单击创建API-Key。

阿里云百炼密钥管理图.png

前往轻量应用服务器控制台，找到安装好OpenClaw的实例，进入「应用详情」放行18789端口、配置百炼API-Key、执行命令，生成访问OpenClaw的Token。
阿里云百炼密钥管理图2.png

端口放通：需要放通对应端口的防火墙，单击一键放通即可。
配置百炼API-Key，单击一键配置，输入百炼的API-Key。单击执行命令，写入API-Key。
配置OpenClaw：单击执行命令，生成访问OpenClaw的Token。
访问控制页面：单击打开网站页面可进入OpenClaw对话页面。

阿里云百炼Coding Plan API-Key 获取、配置保姆级教程：

创建API-Key，推荐访问订阅阿里云百炼Coding Plan，阿里云百炼Coding Plan每天两场抢购活动，从按tokens计费升级为按次收费，可以进一步节省费用！

购买后，在控制台生成API Key。注：这里复制并保存好你的API Key，后面要用。
回到轻量应用服务器-控制台，单击服务器卡片中的实例 ID，进入服务器概览页。
在服务器概览页面单击应用详情页签，进入服务器详情页面。
端口放通在OpenClaw使用步骤区域中，单击端口放通下的执行命令，可开放获取OpenClaw 服务运行端口的防火墙。
这里系统会列出我们第一步中创建的阿里云百炼 Coding Plan的API Key，直接选择就可以。
获取访问地址单击访问 Web UI 面板下的执行命令，获取 OpenClaw WebUI 的地址。

3.2 部署步骤

# 1. 更新系统依赖
sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl

# 2. 安装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash
sudo apt install -y nodejs
node -v # 验证 v22.x

# 3. 安装 pnpm
npm install -g pnpm

# 4. 创建部署目录
mkdir -p /opt/openclaw && cd /opt/openclaw

# 5. 克隆 2026 稳定版源码
git clone -b 2026-stable https://gitee.com/openclaw-team/openclaw.git .

# 6. 安装依赖
pnpm install

# 7. 初始化配置
openclaw onboard
# 按向导设置密码、模型提供商、端口

# 8. 后台启动
openclaw gateway start --daemon

# 9. 访问控制台
# 浏览器打开：http://ECS公网IP:18789

3.3 阿里云千问大模型 API 配置

登录阿里云百炼控制台 → 密钥管理 → 创建 API Key

执行配置命令：

openclaw configure
# 选择 阿里云百炼
# 输入 API Key、API Secret
# 设置默认模型：qwen3-max-2026-01-23

配置文件校验（~/.openclaw/config.json）：

{
     
"llm": {
     
 "provider": "aliyun-bailian",
 "api_key": "sk-sp-xxxx",
 "api_secret": "your-secret",
 "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
 "model": "qwen3-max-2026-01-23",
 "temperature": 0.7
}
}

3.4 阿里云 Coding Plan 免费额度配置

2026 年阿里云百炼提供免费 Coding Plan：新用户 90 天 7000 万 Token，Qwen3-Max 输入输出各 100 万 Token 免费。

控制台进入 Coding Plan 页面领取免费额度
创建 API Key，替换上述配置中的密钥
关闭自动续费，开启用量监控

四、本地全平台部署（MacOS / Linux / Windows11）

4.1 MacOS 部署

# 安装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js 22、Git
brew install node@22 git
echo 'export PATH="/usr/local/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 官方一键安装
curl -fsSL https://openclaw.ai/install.sh | bash

# 初始化并启动
openclaw onboard
openclaw gateway start

4.2 Linux（Ubuntu/Debian）部署

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash
sudo apt install -y nodejs
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard
openclaw gateway start --daemon

4.3 Windows11 部署

以管理员身份打开 PowerShell：

# 安装 nvm-windows 管理 Node.js
iwr -useb https://raw.githubusercontent.com/coreybutler/nvm-windows/master/nvm-setup.exe | iex
# 安装并启用 Node.js 22
nvm install 22
nvm use 22.22.0
# 官方脚本安装
iwr -useb https://openclaw.ai/install.ps1 | iex
# 初始化
openclaw onboard
# 启动服务
openclaw gateway start

访问：http://localhost:18789

五、免费大模型 API 配置（Coding Plan 通用）

5.1 免费模型接入规范

支持 DeepSeek、Kimi、MiniMax、智谱 GLM 等免费 Coding Plan，配置模板一致：

openclaw configure
# 选择 Custom Provider
# 输入 Base URL
# 输入 API Key
# 选择模型名称

5.2 示例：MiniMax 免费 Coding Plan 配置

{
   
  "llm": {
   
    "provider": "custom",
    "api_key": "your-minimax-key",
    "base_url": "https://api.minimax.chat/v1",
    "model": "minimax-m2.5-free",
    "temperature": 0.6
  }
}

5.3 验证模型连通性

openclaw healthcheck
# 返回 LLM connection: ok 即配置成功

六、Skill 开发实战案例

以 pdf-rotate 技能为例：

6.1 SKILL.md 元数据

---
name: pdf-rotate
description: "旋转 PDF 单页/全部页面，支持 90/180/270 度，支持批量文件处理"
metadata:
  openclaw:
    emoji: "🔄"
    requires:
      bins: ["python3", "pdftk"]
---

6.2 Markdown 正文

PDF Rotate Skill

旋转 PDF 页面角度，支持批量操作。

When to Use

旋转 PDF 页面
PDF 颠倒/横向修正
批量旋转文件夹内所有 PDF

When NOT to Use

加密 PDF（需先解密）
损坏/无法读取的文件
图片型 PDF（需 OCR 先提取）

使用命令

# 旋转全部页面 90 度
pdftk input.pdf cat 1-endE output output.pdf
# 180 度
pdftk input.pdf cat 1-endD output output.pdf
# 270 度
pdftk input.pdf cat 1-endS output output.pdf

七、常见问题与故障排查（FAQ）

7.1 部署类问题

端口 18789 占用

# Linux/Mac
lsof -i :18789
# Windows
netstat -ano | findstr "18789"
# 杀死占用进程
kill -9 PID

Node.js 版本过低
升级到 v22.x，重新执行安装脚本
依赖安装失败
切换 npm 镜像：npm config set registry https://registry.npmmirror.com

7.2 Skill 调用问题

Skill 不触发

检查 description 是否包含关键词
确认技能已安装：openclaw skills list
重启网关：openclaw gateway restart

工具依赖缺失
按 requires.bins 安装对应命令行工具
权限不足

Linux/Mac：加 sudo 执行
Windows：以管理员身份运行终端

7.3 大模型 API 问题

API 调用失败

检查密钥是否正确
确认额度未用尽
验证 base_url 格式正确

响应缓慢

切换就近地域节点
降低 temperature 减少推理耗时
检查服务器带宽与防火墙

7.4 运行稳定性问题

服务自动退出
使用 --daemon 后台运行，配置系统服务自启
内存占用过高
关闭不常用 Skill，启用白名单模式：
```
openclaw config set skills.allowBundled true
```

八、2026 年 OpenClaw 最佳实践

最小技能集：只安装高频技能，避免冲突
模型分层：免费模型做简单任务，付费模型做复杂推理
定期更新：保持框架与技能为最新版

安全审计：安装 clawsec 技能，扫描恶意脚本

npx clawhub@latest install clawsec
clawsec audit pdf-rotate

本文完整覆盖 OpenClaw Skill 原理、全平台部署、阿里云与免费模型 API 配置、技能开发、问题排查，可作为个人与团队落地 OpenClaw 的标准化手册。

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料