OpenClaw 使用教程 - 从入门到迁移

什么是 OpenClaw

OpenClaw 是一个开源的 AI Agent 项目，基于 Model Context Protocol (MCP) 构建，支持多种大语言模型（OpenAI、Anthropic、OpenRouter 等），可以通过命令行或配置文件与用户交互。

它的核心特点是高度可扩展的 Skill 系统和多平台消息集成（Telegram、Discord、Slack、WhatsApp 等）。

核心概念

1. Skill（技能）

Skill 是 OpenClaw 的核心扩展单位。每个 Skill 是一个独立的文件夹，包含：

  • SKILL.md - 技能描述和使用说明
  • scripts/ - 相关脚本
  • references/ - 参考文档

Skills 让你可以让 AI Agent 学会特定领域的知识和操作能力。

2. Workspace（工作空间）

Workspace 是 OpenClaw 的知识库目录，通常包含：

  • SOUL.md - Agent 的核心人格设定
  • MEMORY.md - 长期记忆
  • USER.md - 用户信息
  • skills/ - 自定义技能

3. Platform（平台集成）

OpenClaw 支持连接到多个消息平台，每个平台需要独立的 bot token 或认证信息。

快速开始

安装

1
2
3
4
5
6
7
# 通过 pip 安装
pip install openclaw

# 或者从源码克隆
git clone https://github.com/your-repo/openclaw.git
cd openclaw
pip install -e .

初始化

1
2
3
4
5
# 首次运行，自动引导配置
openclaw setup

# 或者手动指定配置路径
openclaw setup --config ~/.openclaw/openclaw.json

基本命令

1
2
3
4
5
6
7
8
9
10
11
# 启动 Agent（交互模式）
openclaw run

# 以特定模型启动
openclaw run --model anthropic/claude-3-5-sonnet

# 查看当前配置
openclaw config show

# 测试 API 连接
openclaw doctor

Skill 系统详解

安装 Skill

1
2
3
4
5
6
7
8
# 从 Skills Hub 安装
openclaw skills install skill-name

# 从本地目录安装
openclaw skills install /path/to/skill-folder

# 查看已安装技能
openclaw skills list

常用官方 Skills

Skill 名称 功能
github GitHub PR/Issue 管理
filesystem 文件系统操作
web-search 网络搜索
memory 增强的记忆能力

创建自定义 Skill

创建一个 Skill 只需要三个步骤：

1. 创建目录结构

1
2
3
4
5
6
my-skill/
├── SKILL.md          # 必需：技能说明
├── scripts/
│   └── run.py        # 核心逻辑
└── references/
    └── api.md        # 可选：API 文档

2. 编写 SKILL.md

1
2
3
4
5
6
7
8
9
10
11
# My Skill

## 功能
描述这个技能做什么。

## 使用方法
> 使用 my-skill <参数>

## 参数说明
- `param1`: 参数1说明
- `param2`: 参数2说明

3. 安装并使用

1
openclaw skills install ./my-skill

配置文件说明

OpenClaw 的主配置文件 openclaw.json 结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "models": {
    "providers": {
      "openai": {
        "apiKey": "your-api-key",
        "model": "gpt-4"
      },
      "anthropic": {
        "apiKey": "your-api-key",
        "model": "claude-3-5-sonnet-20241022"
      }
    }
  },
  "channels": {
    "telegram": {
      "botToken": "your-bot-token"
    }
  },
  "thinking": {
    "default": "medium"
  }
}

常用配置项

配置项 说明 示例值
models.default 默认模型 openai/gpt-4
thinking.default 思考深度 medium, high, low
channels.* 平台配置 各平台 bot token

平台集成

Telegram

1
2
3
4
5
6
7
8
9
10
11
12
13
# 获取 Bot Token
# 1. 在 Telegram 搜索 @BotFather
# 2. 发送 /newbot
# 3. 记录获得的 token

# 在配置文件中添加
{
  "channels": {
    "telegram": {
      "botToken": "123456:ABC-DEF..."
    }
  }
}

Discord

需要创建 Discord Application 并添加 Bot：

  1. 访问 Discord Developer Portal
  2. 创建 Application → 添加 Bot
  3. 复制 Bot Token
  4. 使用 OAuth2 生成邀请链接

其他平台

每个平台的配置略有不同，具体请参考官方文档。

数据迁移

OpenClaw 支持平滑迁移到 Hermes Agent：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 自动检测并引导迁移
hermes setup

# 或手动执行迁移命令
hermes claw migrate

# 预览迁移内容（不执行）
hermes claw migrate --dry-run

# 执行迁移（包含 API keys）
hermes claw migrate --preset full

# 仅迁移用户数据（不包含敏感信息）
hermes claw migrate --preset user-data

迁移内容

数据类型 说明
SOUL.md Agent 人格设定
MEMORY.md 记忆数据
USER.md 用户信息
Skills 自定义技能
API Keys 各平台密钥（可选）

常见问题

Q: 提示 “OpenClaw directory not found”

OpenClaw 默认查找 ~/.openclaw，也可以是 ~/.clawdbot 或 ~/.moltbot。可以手动指定路径：

1
hermes claw migrate --source /path/to/.openclaw

Q: 迁移后 Skill 不生效

Skills 需要在新会话中加载。重启 Agent 或开启新对话即可。

Q: Telegram/Discord 连接失败

  1. 确认 Bot token 正确
  2. 检查 Bot 是否已经在服务器中
  3. 确保 Gateway 已停止后再启动新服务

进阶使用

自定义思考模式

1
2
3
4
# 不同的思考深度会影响响应质量
openclaw run --thinking high    # 更详细的推理
openclaw run --thinking low      # 更快的响应
openclaw run --thinking medium   # 平衡模式

多模型混合

可以配置不同的 Skill 使用不同的模型：

1
2
3
4
5
6
7
8
9
10
{
  "skills": {
    "github": {
      "model": "anthropic/claude-3-5-sonnet"
    },
    "web-search": {
      "model": "openai/gpt-4"
    }
  }
}

私有模型支持

通过 OpenRouter 可以访问更多开源模型：

1
2
3
4
5
6
7
8
9
10
{
  "models": {
    "providers": {
      "openrouter": {
        "apiKey": "your-openrouter-key",
        "baseUrl": "https://openrouter.ai/api/v1"
      }
    }
  }
}

总结

OpenClaw 是一个功能强大的 AI Agent 框架，特别适合：

  • 需要多平台消息集成的场景
  • 希望自定义 Agent 能力的开发者
  • 需要平滑迁移到其他 Agent 系统的用户

如果你正在寻找一个灵活、可扩展的 AI Agent 解决方案，OpenClaw 值得一试。

本文基于 OpenClaw 最新版本编写，如有问题欢迎留言交流。