OpenClaw 入门到进阶完整学习教程（2026）

OpenClaw 是 GitHub 上最受欢迎的个人 AI 助手开源框架（309,000 Stars），可在 WhatsApp、Telegram、Slack、Discord、iMessage 等 20+ 渠道中接入 AI 能力，实现跨平台统一管理。本教程分为四个阶段——安装配置 → 渠道接入 → 技能与工具 → 进阶自动化——从零开始手把手完成 OpenClaw 全功能部署，并覆盖每个阶段最常见的坑点。

学习路径总览

阶段	内容	难度	预计时间
第一阶段：安装与启动	环境准备 → npm 安装 → Onboard 向导 → Gateway 启动	⭐	30 分钟
第二阶段：配置 API 与渠道	auth-profiles.json → Provider 配置 → 渠道接入 → 设备配对	⭐⭐	1 小时
第三阶段：技能与 MCP 工具	ClawHub 技能安装 → 内置工具 → MCP Server 接入	⭐⭐⭐	2 小时
第四阶段：进阶自动化	Cron 定时任务 → 多 Agent 路由 → 自定义 Skill → 性能优化	⭐⭐⭐⭐	按需

第一阶段：安装与启动

1.1 系统要求

依赖	最低版本	推荐版本	说明
Node.js	v22.0.0	v22 LTS	低于 v22 会在 onboard 时报错
npm	10+	随 Node.js 自带	或使用 pnpm
操作系统	macOS 13 / Ubuntu 20.04 / Windows WSL2	macOS 14 / Ubuntu 22.04	Windows 原生不支持，需 WSL2

检查并安装 Node.js：

# 检查当前版本
node --version
 
# 若低于 v22，使用 nvm 升级
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc  # 或 source ~/.zshrc
 
nvm install 22
nvm use 22
nvm alias default 22  # 设为默认版本
 
# 验证
node --version  # 应输出 v22.x.x

1.2 安装 OpenClaw

# 推荐：使用 npm 全局安装
npm install -g openclaw@latest
 
# 或使用 pnpm（速度更快）
pnpm add -g openclaw@latest
 
# 验证安装
openclaw --version

权限报错处理：若出现 EACCES permission denied，执行 npm config set prefix ~/.npm-global && echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc，再重新安装。

1.3 运行 Onboard 向导

Onboard 向导是 OpenClaw 官方提供的交互式配置工具，自动完成 Gateway 守护进程注册、初始配置文件创建和健康检查。

openclaw onboard --install-daemon

向导会依次引导完成：

1. 选择安装位置：默认 ~/.openclaw/

2. 注册守护进程：macOS 写入 ~/Library/LaunchAgents/com.openclaw.gateway.plist；Linux 写入 ~/.config/systemd/user/openclaw-gateway.service

3. API Key 初始配置：填入第一个 Provider 的 API Key

4. 健康检查：自动运行 openclaw doctor 验证配置

注意：向导完成后 Gateway 会自动启动并在系统重启时自动恢复。

1.4 验证 Gateway 运行

# 查看 Gateway 状态
openclaw gateway status
 
# 测试 HTTP 健康端点
curl -s http://127.0.0.1:18789/health | python3 -m json.tool
# 正常输出应包含 "status": "ok"
 
# 查看实时日志
openclaw logs --follow --level info

Gateway 控制命令速查：

openclaw gateway start    # 启动
openclaw gateway stop     # 停止
openclaw gateway restart  # 重启（配置修改后使用）
openclaw gateway status   # 查看状态

第二阶段：配置 API 与渠道

2.1 配置文件位置总览

~/.openclaw/
├── config.yaml                          # 全局配置
├── agents/
│   └── main/
│       └── agent/
│           └── auth-profiles.json       # API Key 配置（最重要）
│       └── skills/                      # 已安装技能
└── logs/                                # 日志（若配置固定路径）

2.2 auth-profiles.json：配置 LLM Provider

这是 OpenClaw 最核心的配置文件，控制使用哪个 AI 提供商的哪个模型。

国际 Provider 配置示例：

{
  "profiles": [
    {
      "id": "claude-main",
      "type": "api-key",
      "provider": "anthropic",
      "apiKey": "sk-ant-你的anthropic-key",
      "model": "claude-sonnet-4-6"
    },
    {
      "id": "openai-backup",
      "type": "api-key",
      "provider": "openai",
      "apiKey": "sk-你的openai-key",
      "model": "gpt-4o"
    }
  ],
  "default": "claude-main"
}

国内 Provider 配置（兼容 OpenAI API 格式）：

{
  "profiles": [
    {
      "id": "deepseek",
      "type": "api-key",
      "provider": "openai",
      "apiKey": "sk-你的deepseek-key",
      "baseURL": "https://api.deepseek.com/v1",
      "model": "deepseek-chat"
    },
    {
      "id": "kimi",
      "type": "api-key",
      "provider": "openai",
      "apiKey": "sk-你的kimi-key",
      "baseURL": "https://api.moonshot.cn/v1",
      "model": "kimi-k2.5"
    }
  ],
  "default": "deepseek"
}

七牛云 MaaS 统一接入（一个 Key 切换多个国内模型）：

{
  "profiles": [
    {
      "id": "qiniu-maas",
      "type": "api-key",
      "provider": "openai",
      "apiKey": "你的七牛云api-key",
      "baseURL": "https://api.qnaigc.com/v1",
      "model": "deepseek-chat"
    }
  ],
  "default": "qiniu-maas"
}

配置生效：修改 auth-profiles.json 后执行 openclaw gateway restart 使配置生效。

2.3 接入渠道

OpenClaw 支持 20+ 渠道，以下是最常用的几种接入方式：

Telegram（最推荐入门渠道）

# 1. 在 Telegram 中找 @BotFather，发送 /newbot 创建 Bot
# 2. 复制 Bot Token（格式：123456:ABCdefGHI...）
# 3. 在 OpenClaw 中配置
openclaw channels add telegram --token 你的BOT_TOKEN

Discord

# 1. 在 Discord Developer Portal 创建应用
# 2. 在 Bot 页面生成 Token，复制 Application ID
openclaw channels add discord --token 你的BOT_TOKEN --application-id 你的APP_ID

Slack

# 1. 在 api.slack.com 创建 App
# 2. 获取 Bot Token（xoxb-开头）和 App Token（xapp-开头）
openclaw channels add slack --bot-token xoxb-xxx --app-token xapp-xxx

查看已配置渠道

openclaw channels list

2.4 设备配对安全机制

OpenClaw 对 WebChat（浏览器控制台）和未知发件人默认启用设备配对审批机制：首次访问时生成 pairing request，需要人工审批后才能通信。

# 查看待审批的配对请求
openclaw devices list
# 输出示例：
# ID: req_abc123  Type: browser  Status: pending  IP: 127.0.0.1
 
# 批准指定设备
openclaw devices approve req_abc123
 
# 批准全部待审请求
openclaw devices approve --all

常见问题：浏览器访问 http://localhost:18789 后显示 disconnected (1006): no reason，多数是设备配对未完成——先检查 openclaw devices list 是否有 pending 请求。

第三阶段：技能与 MCP 工具

3.1 OpenClaw 技能体系

OpenClaw 的技能（Skills）是扩展 AI 能力的核心机制，分为三类：

技能类型	存放位置	说明
内置技能	OpenClaw 核心包	Shell 执行、文件操作、浏览器控制、截图，开箱即用
ClawHub 技能	~/.openclaw/agents/main/skills/	从 ClawHub 市场（5,400+ 技能）安装
Workspace 技能	项目目录下 skills/	仅在指定 workspace 生效的私有技能

3.2 安装 ClawHub 技能

# 搜索技能
clawhub search 关键词
 
# 安装技能（需先登录）
clawhub login --token 你的clawhub-token  # 从 https://clawhub.ai/settings 获取
clawhub install 技能名称
 
# 列出已安装技能
openclaw skills list
 
# 卸载技能
clawhub uninstall 技能名称

ClawHub DNS 故障绕过（2026 年 3 月 13 日起）：若 clawhub search 超时，改用 npx skills add https://github.com/仓库地址直接从 GitHub 安装。

3.3 内置工具使用

OpenClaw 内置四大工具，可在对话中直接调用：

Shell 执行：

在 Telegram / Discord 中发送消息：
"帮我查一下当前目录有哪些文件"
→ OpenClaw 自动调用 Shell 工具执行 ls，返回结果

浏览器控制：

"打开 https://example.com，截图给我"
→ OpenClaw 启动无头 Chrome，访问页面并返回截图

文件操作：

"把这段内容保存到 ~/Documents/notes.txt"
→ OpenClaw 调用文件写入工具，保存文件

3.4 接入 MCP 协议工具

MCP（Model Context Protocol）是 OpenClaw 支持的标准化工具接口协议，可将 GitHub、Jira、数据库等外部系统作为工具接入。

MCP Server 配置（在 ~/.openclaw/config.yaml 中）：

mcp:
  servers:
    - name: github
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: 你的github-token
 
    - name: filesystem
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/你的用户名/Documents"]
 
    - name: sqlite
      command: npx
      args: ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "/path/to/db.sqlite"]

重启生效后验证：

openclaw gateway restart
openclaw tools list  # 应显示来自 MCP Server 的工具

使用示例（在对话中）：

"查看我的 GitHub 仓库列表"
→ OpenClaw 通过 MCP 调用 GitHub Server，返回仓库信息
 
"搜索 Documents 目录下包含 '季度报告' 的文件"
→ 调用 filesystem MCP Server 执行搜索

第四阶段：进阶自动化

4.1 Cron 定时任务

OpenClaw 内置 Cron 系统，无需 crontab 或外部调度工具，直接在对话中创建定时任务：

"每天早上 8:30 帮我抓取今日 AI 资讯摘要，发送到我的 Telegram"
→ OpenClaw 自动创建一个 Cron 任务，每天定时执行

通过配置文件显式定义 Cron 任务（~/.openclaw/config.yaml）：

crons:
  - name: daily-news
    schedule: "30 8 * * *"       # 每天 8:30
    agent: main
    prompt: "抓取今日 AI 行业资讯前 5 条，整理成摘要发送到 Telegram"
    channel: telegram
 
  - name: weekly-report
    schedule: "0 18 * * 5"       # 每周五 18:00
    agent: main
    prompt: "生成本周工作周报草稿，保存到 ~/Documents/weekly-report.md"

# 查看所有 Cron 任务
openclaw crons list
 
# 手动触发某个任务
openclaw crons run daily-news
 
# 暂停任务
openclaw crons pause daily-news

4.2 多 Agent 路由与 Workspace

OpenClaw 支持创建多个 Agent（代理），每个 Agent 可有独立的 Provider、技能集和系统提示词，通过 Workspace 隔离不同工作场景。

创建专用 Agent（~/.openclaw/agents/ 目录下）：

# ~/.openclaw/agents/code-assistant/agent.yaml
name: code-assistant
description: "专注代码相关任务的 Agent"
profile: openai-gpt4o    # 引用 auth-profiles.json 中的 ID
systemPrompt: |
  你是一位专业的代码审查助手，擅长 Python 和 TypeScript。
  回答时直接给出代码，附简短解释。
skills:
  - shell-execution
  - file-operations
  - github              # MCP Server

路由规则（按关键词自动分发到不同 Agent）：

# ~/.openclaw/config.yaml
routing:
  rules:
    - pattern: "代码|debug|PR|commit"
      agent: code-assistant
    - pattern: "资讯|新闻|总结"
      agent: research-assistant
    - default: main

4.3 自定义 Skill 编写

Skill 是一个 Markdown 文件（skill.md），定义工作流步骤，由 OpenClaw 解析并执行。

最简 Skill 示例：

# 日报生成器 ## 触发词日报 / 生成今日报告 ## 步骤 ### Step 1：收集信息收集今天的工作记录。提问用户：今天完成了哪些任务？遇到什么问题？ ### Step 2：生成报告（此步骤全自动执行，不需要用户任何操作）基于 Step 1 的信息，生成一份结构化日报，包含： - 今日完成事项 - 遇到的问题和解决方案 - 明日计划 ### Step 3：保存报告使用 Write 工具保存报告到 ~/Documents/daily-reports/YYYY-MM-DD.md 完成标准：文件存在且内容不为空后，此步骤完成。 部署 Skill：

# 将 skill.md 放入技能目录
mkdir -p ~/.openclaw/agents/main/skills/daily-reporter
cp skill.md ~/.openclaw/agents/main/skills/daily-reporter/
 
# 验证技能被识别
openclaw skills list | grep daily-reporter

Skill 编写最佳实践（基于 Anthropic 官方提示词工程文档）：

● 每个步骤只做一件事（原子化）

● 自动执行的步骤加 此步骤全自动执行，不需要用户任何操作。

● 用 depends_on 或括号注明步骤依赖关系

● 每步说明「完成标准」而非只说「做什么」

4.4 防限速与高可用配置

高频使用场景下，配置多 API Key 和速率限制可大幅提升稳定性：

// auth-profiles.json：同一 Provider 多 Key 自动 failover
{
  "profiles": [
    { "id": "claude-1", "type": "api-key", "provider": "anthropic", "apiKey": "sk-ant-key-1" },
    { "id": "claude-2", "type": "api-key", "provider": "anthropic", "apiKey": "sk-ant-key-2" },
    { "id": "claude-3", "type": "api-key", "provider": "anthropic", "apiKey": "sk-ant-key-3" }
  ],
  "default": "claude-1"
}

# config.yaml：内置限速配置（防止多 Agent 并发耗尽配额）
agents:
  defaults:
    rateLimit:
      maxRequestsPerMinute: 15
      burstAllowance: 3
      throttleDelayMs: 500

4.5 远程访问：SSH 隧道 vs Nginx 反代

方案 A：SSH 隧道（最简单，推荐入门）

# 在本地机器执行，将远程服务器的 18789 映射到本地
ssh -N -L 18789:127.0.0.1:18789 user@your-server-ip
# 然后本地浏览器访问 http://127.0.0.1:18789

方案 B：Nginx 反向代理（生产环境）

server {
    listen 80;
    server_name openclaw.example.com;
    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Origin "http://127.0.0.1:18789";
        proxy_read_timeout 3600s;
        proxy_buffering off;
    }
}

学习资源与社区

官方资源

资源	地址
GitHub 仓库	https://github.com/openclaw/openclaw
ClawHub 技能市场	https://clawhub.ai
GitHub Issues	https://github.com/openclaw/openclaw/issues
Release Notes	https://github.com/openclaw/openclaw/releases

国内生态

工具/服务	说明
Linclaw	七牛云推出的 OpenClaw 桌面版，零部署，原生支持微信/钉钉/飞书/QQ，macOS DMG / Windows EXE 双击安装
ArkClaw	字节跳动火山引擎版，深度集成豆包/Claude
QClaw	腾讯电脑管家版，微信直联

常见问题

Q：入门应该用哪个 Provider 和渠道？

Provider 推荐 DeepSeek（兼容 OpenAI 格式，国内可直连，成本低），渠道推荐 Telegram（配置最简单，只需一个 Bot Token，无需企业账号）。两者结合是入门门槛最低的组合。Q：Onboard 向导完成后，怎么验证 OpenClaw 工作正常？

依次执行：openclaw gateway status（确认守护进程运行）→ curl http://127.0.0.1:18789/health（确认 HTTP 端点正常）→ 向已配对渠道发送一条 “hello”（确认 AI 响应）→ openclaw doctor（全面健康检查）。四步全通则配置正确。

Q：技能执行时 Claude 经常跳步，怎么避免？

核心是「步骤原子化 + 完成标准」：每步只做一件事，步骤末尾注明「完成标准：XX 文件存在后继续」，自动执行步骤加此步骤全自动执行，不需要用户任何操作。详见 Anthropic 官方提示词工程文档（2026 年 3 月版）。

Q：如何在不同设备间同步 OpenClaw 配置？

同步 ~/.openclaw/ 目录中的 config.yaml、auth-profiles.json 和 skills/ 目录（注意 auth-profiles.json 包含 API Key，同步前确认目标存储安全）。可借助 rsync、Syncthing 或加密 Git 仓库实现跨设备同步。

Q：OpenClaw 的学习曲线太陡，有更简单的方案吗？

Linclaw（七牛云推出的 OpenClaw 桌面版）将本教程中第一、二阶段的全部命令行操作封装为图形化向导，安装后 5 分钟内即可接入微信/钉钉/飞书，适合技术基础较弱的用户。进阶功能（MCP、Cron、多 Agent）则仍建议使用 OpenClaw 原版以获得完整灵活性。

总结

OpenClaw 的学习路径可分为清晰的四阶段：安装启动（Node.js ≥22 + npm install + onboard 向导）→ 配置接入（auth-profiles.json 配 Provider + 渠道 Token + 设备配对）→ 技能工具（ClawHub 技能 + MCP Server 配置）→ 进阶自动化（Cron 定时任务 + 多 Agent 路由 + 自定义 Skill）。每个阶段独立可验证，完成一个阶段后即可获得实际可用的 AI 助手能力，不必等到全部配置完成才能体验效果。

本文内容基于 OpenClaw 官方 GitHub 文档和 2026 年 3 月 Anthropic 官方提示词工程文档整理，建议配合官方 Release Notes（https://github.com/openclaw/openclaw/releases）持续跟进版本变化。