全网最全！GitHub 30万星 AI 神器 OpenClaw 保姆级部署教程

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

学习路径总览

第一阶段：安装与启动

1.1 系统要求

检查并安装 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

向导会依次引导完成：

注意：向导完成后 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 能力的核心机制，分为三类：

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;
}
}

学习资源与社区

官方资源

国内生态

常见问题

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 官方提示词工程文档整理。