全网最全！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 |bashsource ~/.bashrc # 或 source ~/.zshrc nvm install22 nvm use 22 nvm alias default 22# 设为默认版本# 验证node--version# 应输出 v22.x.x

1.2 安装 OpenClaw

# 推荐：使用 npm 全局安装npminstall-g openclaw@latest # 或使用 pnpm（速度更快）pnpmadd-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 能力的核心机制，分为三类：

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:30agent: main prompt:"抓取今日 AI 行业资讯前 5 条，整理成摘要发送到 Telegram"channel: telegram -name: weekly-report schedule:"0 18 * * 5"# 每周五 18:00agent: 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.yamlname: code-assistant description:"专注代码相关任务的 Agent"profile: openai-gpt4o # 引用 auth-profiles.json 中的 IDsystemPrompt:| 你是一位专业的代码审查助手，擅长 Python 和 TypeScript。 回答时直接给出代码，附简短解释。skills:- shell-execution - file-operations - github # MCP Server

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

# ~/.openclaw/config.yamlrouting: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:15burstAllowance:3throttleDelayMs:500

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

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

# 在本地机器执行，将远程服务器的 18789 映射到本地ssh-N-L18789: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 官方提示词工程文档整理。