OpenClaw 是一个开源、自托管的个人 AI 助理框架，让你可以通过 WhatsApp、Telegram、Discord、iMessage 等你已经在用的聊天软件与 AI 对话，并让它帮你执行真实任务：发邮件、管日历、控制浏览器、读写文件……

本教程面向零基础用户，手把手带你从安装到跑通第一条消息。

1. OpenClaw 是什么？
2. 准备工作（环境 & 账号）
3. 安装 OpenClaw
4. 运行引导向导
5. 连接 Telegram（推荐新手）
6. 连接 WhatsApp
7. 配置 AI 模型（API Key）
8. 接入国内大模型平台（DeepSeek / 阿里云百炼 / 百度千帆 / 腾讯混元）
9. 启动 Gateway & 测试
10. 设置开机自启（守护进程）
11. 常用配置说明
12. 常用聊天命令
13. 常见问题 FAQ
14. 进阶：安装 Skills 技能包

OpenClaw（前身为 Clawdbot / Moltbot）是一个运行在你自己设备上的开源 AI Agent 框架，由开发者 Peter Steinberger 创作，MIT 协议开源。

核心特点

架构示意

你的手机 (WhatsApp / Telegram)

 │ ▼ 

┌──────────────────────┐ │ Gateway │ ← 运行在你的电脑/服务器上 │ (控制平面 :18789) │ └──────────┬───────────┘

 │ ┌──────┴──────┐ │ Pi Agent │ ← AI 执行引擎 └─────────────┘

2.1 系统要求

2.2 必须安装的软件

Node.js 22 或 24（必须）

Node.js 是运行 OpenClaw 的基础环境。

macOS / Linux 推荐使用 nvm 安装：

# 1. 安装 nvm（Node 版本管理器） 

Windows 用户：

前往 https://nodejs.org 下载 LTS 版本（22 或 24）并安装。安装完成后打开 PowerShell 验证：

node –version npm –version

2.3 需要准备的账号 / 资源

• AI API Key（至少一个）：

• Anthropic Claude：https://console.anthropic.com → API Keys
• OpenAI GPT：https://platform.openai.com → API Keys
• 也支持本地 Ollama（免费）

• 一个额外手机号（用于 WhatsApp 接入）：建议用副卡或 eSIM，不要用个人主号
• Telegram 账号（可选，新手推荐）：无需额外手机号，用现有账号即可

⚠️ 重要提示：如果接入 WhatsApp，强烈建议用一个专用的副手机号，而不是你的个人主号。将你的主号绑定到 OpenClaw 意味着所有发给你的消息都会变成 AI 的输入，这通常不是你想要的结果。

根据你的操作系统选择对应方式：

macOS / Linux（推荐）

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

或者通过 npm 安装：

npm install -g openclaw@latest

Windows（PowerShell）

# 使用官方 PowerShell 安装脚本 iwr -useb https://openclaw.ai/install.ps1 | iex

或者通过 npm：

npm install -g openclaw@latest

验证安装成功

openclaw –version

如果输出版本号（例如 openclaw/1.x.x），说明安装成功。

OpenClaw 提供了一个交互式的引导向导，帮你一步步完成初始配置。新手强烈推荐从这里开始。

openclaw onboard

向导会引导你完成以下步骤：

1. 选择 AI 提供商：Claude / GPT / Ollama 等
2. 输入 API Key：Key 会安全存储在本地 Keychain 中
3. 选择接入渠道：Telegram、WhatsApp、Discord 等
4. 完成 Gateway 初始化

💡 如果你想同时将 Gateway 注册为开机自启服务，运行：

openclaw onboard –install-daemon

Telegram 是最简单的接入方式，不需要额外手机号。

步骤一：创建 Telegram Bot

1. 打开 Telegram，搜索 @BotFather
2. 发送 /newbot
3. 按提示输入 Bot 名字（例如：My AI Assistant）
4. 输入 Bot 用户名（必须以 bot 结尾，例如：myai_helper_bot）
5. BotFather 会回复一个 Token，格式如：:ABCdefGHIjklMNOpqrsTUVwxyz
6. 复制保存这个 Token

步骤二：获取你的 Telegram 用户 ID

1. 搜索 @userinfobot
2. 发送任意消息
3. Bot 会回复你的用户 ID，例如：Id:
4. 记下这个数字

步骤三：在 OpenClaw 配置中填入信息

编辑配置文件（首次运行 onboard 后会自动创建）：

# 用你喜欢的编辑器打开配置文件 nano ~/.openclaw/openclaw.json 
或者
 
code ~/.openclaw/openclaw.json

在 channels 部分添加 Telegram 配置：

{ “channels”: { 
"telegram": { "token": "你的BotFather Token", "allowFrom": [] } 
 
} }

将 替换为你的真实 Telegram 用户 ID。allowFrom 是白名单，只有这里列出的用户才能跟 AI 对话，防止他人滥用。

步骤四：登录渠道

openclaw channels login

步骤五：发送第一条消息

1. 打开 Telegram，搜索你刚创建的 Bot 用户名
2. 点击 Start 或发送 /start
3. 发送任意消息，比如：“你好，介绍一下你自己”
4. AI 应该会回复你 🎉

⚠️ 再次提醒：请使用专用副号，不要用个人主号。

步骤一：准备副手机号

• 可以用副卡、eSIM、网络虚拟号等
• 该号码需要能收到短信验证码
• 将该号码在手机上注册好 WhatsApp（正常使用一次即可）

步骤二：配置允许的联系人

编辑 ~/.openclaw/openclaw.json，添加 WhatsApp 配置：

{ “channels”: { 
"whatsapp": { "allowFrom": ["+00"] } 
 
} }

将 +00 替换为你个人手机号（国际格式，含国家代码）。这样只有你的手机能跟 AI 对话。

步骤三：扫码绑定 WhatsApp

openclaw channels login

运行后会弹出一个 二维码，用装有 WhatsApp 副号的手机扫描：

1. 打开副号手机上的 WhatsApp
2. 点击右上角 ⋮ → 已关联的设备
3. 点击 关联设备
4. 扫描终端中显示的二维码

扫码成功后，你会看到 WhatsApp connected 的提示。

步骤四：从主号发消息测试

用你的个人主号（即 allowFrom 里填的号码）给副号发一条 WhatsApp 消息，AI 应该会自动回复。

方式一：通过引导向导配置（推荐）

openclaw onboard

向导会提示你选择提供商并安全存储 Key。

方式二：手动填入配置文件

编辑 ~/.openclaw/openclaw.json：

{ “agent”: { 
"model": "anthropic/claude-opus-4-6", "workspace": "~/.openclaw/workspace", "thinkingDefault": "high", "timeoutSeconds": 1800 
 
} }

常用模型名称对照

设置 API Key 环境变量（可选）

如果不想在向导中输入，也可以通过环境变量传入：

# 在 ~/.bashrc 或 ~/.zshrc 中添加： export ANTHROPIC_API_KEY=“sk-ant-xxxxx” export OPENAI_API_KEY=“sk-xxxxx”

📌 核心原理：DeepSeek、阿里云百炼、百度千帆、腾讯混元均完整兼容 OpenAI API 格式。只需在 OpenClaw 配置文件中填写对应平台的 baseURL 和 apiKey，即可无缝切换，完全不需要修改 OpenClaw 本身的任何代码。

8.1 兼容接入原理

OpenClaw 底层调用模型时，走的是标准的 OpenAI /v1/chat/completions 接口。国内各大平台均提供了与这一格式兼容的 API 端点，接入方式完全统一，三步搞定：

1. 拿到目标平台的 API Key 
            
     
              
 
               
找到该平台的 OpenAI 兼容 base_url
 
               
填入 openclaw.json 的 agent.openai 节点
 
              

8.2 通用配置格式

编辑 ~/.openclaw/openclaw.json，在 agent 节点下增加 openai 字段：

{ “agent”: { “model”: “平台对应的模型名”, “openai”: { “baseURL”: “平台的兼容接口地址”, “apiKey”: “你的API Key” } } }

8.3 DeepSeek

DeepSeek 的 API 完整兼容 OpenAI 格式，只需将 base_url 指向 https://api.deepseek.com 并替换 API Key，即可直接使用 OpenAI SDK 的所有功能。

第一步：获取 API Key

前往 https://platform.deepseek.com → 登录 → API Keys → 创建新 Key。

第二步：填写配置

{ “agent”: { “model”: “deepseek-chat”, “openai”: { “baseURL”: “https://api.deepseek.com/v1”, “apiKey”: “sk-xxxxxxxxxxxxxxxxxxxxxxxx” } } }

可选模型名称

设置环境变量（推荐）

# 在 ~/.bashrc 或 ~/.zshrc 中添加 export DEEPSEEK_API_KEY=“sk-xxxxxxxxxxxxxxxxxxxxxxxx”

然后配置文件中 apiKey 可以省略，OpenClaw 会自动读取环境变量。

💡 费用参考：DeepSeek 的 API 计费通常比 OpenAI 或 Anthropic 便宜 10-30 倍，是预算有限时的首选。

8.4 阿里云百炼（通义千问）

阿里云百炼的通义千问系列模型完整支持 OpenAI 兼容接口，只需调整 API Key、BASE_URL 和模型名称，即可将原有 OpenAI 代码迁移至百炼服务使用。

第一步：获取 API Key

1. 前往 https://bailian.console.aliyun.com → 登录阿里云账号
2. 左侧菜单 → API Key 管理 → 创建 API Key
3. 复制 Key（格式为 sk-xxxxxxxx）

第二步：填写配置

{ “agent”: { “model”: “qwen-plus”, “openai”: { “baseURL”: “https://dashscope.aliyuncs.com/compatible-mode/v1”, “apiKey”: “sk-xxxxxxxxxxxxxxxxxxxxxxxx” } } }

可选模型名称

💡 百炼平台同时托管了 DeepSeek 模型，如果你已经有了百炼账号，可以直接用同一个 Key 访问 DeepSeek，无需再注册 DeepSeek 官方账号。

多地域说明

百炼服务在多个地域均有部署，国内用户一般使用北京地域（https://dashscope.aliyuncs.com/compatible-mode/v1）即可，海外用户可选新加坡（https://dashscope-intl.aliyuncs.com/compatible-mode/v1）。

设置环境变量（推荐）

export DASHSCOPE_API_KEY=“sk-xxxxxxxxxxxxxxxxxxxxxxxx”

8.5 百度千帆（文心 ERNIE）

百度千帆通过 AI Studio 开发者平台提供 OpenAI 兼容接口，使用文心 ERNIE 系列模型。

第一步：获取 Access Token

1. 前往 https://aistudio.baidu.com → 登录百度账号
2. 右上角头像 → 访问令牌（Access Token） → 生成 / 复制 Token

第二步：填写配置

{ “agent”: { “model”: “ernie-4.5-8k”, “openai”: { “baseURL”: “https://aistudio.baidu.com/llm/lmapi/v3”, “apiKey”: “你的AI_Studio访问令牌” } } }

可选模型名称

设置环境变量（推荐）

export AI_STUDIO_API_KEY=“你的AI_Studio访问令牌”

⚠️ 注意：百度千帆使用的是 AI Studio 访问令牌，格式与其他平台的 sk-xxx 不同，Token 较长，请完整复制。

8.6 腾讯混元

腾讯混元 API 兼容了 OpenAI 的接口规范，只需将 base_url 替换为 https://api.hunyuan.cloud.tencent.com/v1，填入混元控制台的 API Key，即可直接使用 OpenAI SDK 无缝切换。

第一步：获取 API Key

1. 前往 https://console.cloud.tencent.com/hunyuan → 登录腾讯云
2. 左侧菜单 → API Key 管理 → 新建 API Key
3. 复制生成的 Key

第二步：填写配置

{ “agent”: { “model”: “hunyuan-turbos-latest”, “openai”: { “baseURL”: “https://api.hunyuan.cloud.tencent.com/v1”, “apiKey”: “你的腾讯混元API Key” } } }

可选模型名称

设置环境变量（推荐）

export HUNYUAN_API_KEY=“你的腾讯混元API Key”

8.7 四大平台对比速查

8.8 通过 LiteLLM 代理接入（进阶）

如果你想在不修改 openclaw.json 的情况下随时切换不同平台，可以在本地跑一个 LiteLLM 代理，把所有国内模型统一转为标准 OpenAI 格式的本地端点：

# 安装 LiteLLM pip install litellm 
启动代理（以 DeepSeek 为例）
 
litellm –model deepseek/deepseek-chat –api_base https://api.deepseek.com/v1 –api_key sk-xxx –port 4000

然后 openclaw.json 只需指向本地代理：

{ “agent”: { 
"model": "deepseek/deepseek-chat", "openai": { "baseURL": "http://localhost:4000/v1", "apiKey": "任意字符串即可" } 
 
} }

这样可以在同一个 OpenClaw 实例里，通过修改 LiteLLM 配置来热切换任意模型，无需每次重启 OpenClaw。

启动 Gateway

openclaw gateway –port 18789

成功启动后，终端会显示类似输出：

✓ Gateway started on ws://127.0.0.1:18789 ✓ WhatsApp connected ✓ Telegram connected ✓ Pi agent ready Control UI → http://127.0.0.1:18789/

打开 Web 控制面板

在浏览器中打开：

http://127.0.0.1:18789/

这里可以：

• 直接在网页上跟 AI 对话（无需手机）
• 查看各渠道连接状态
• 管理会话记录
• 实时查看日志

检查运行状态

openclaw status # 查看本地状态 openclaw status –all # 完整诊断（可粘贴给社区求助） openclaw doctor # 检查安全配置风险

让 OpenClaw 在系统启动时自动运行，无需每次手动开启。

macOS / Linux（使用 systemd 或 launchd）

# 安装守护进程 openclaw daemon install 
启动守护进程
 
openclaw daemon start
 
查看守护进程状态
 
openclaw daemon status
 
停止守护进程
 
openclaw daemon stop
 
卸载守护进程（不再开机自启）
 
openclaw daemon uninstall

一步到位（安装时同时设置自启）

openclaw onboard –install-daemon

Windows（作为系统服务）

以管理员身份运行 PowerShell：

openclaw daemon install openclaw daemon start

配置文件路径：~/.openclaw/openclaw.json

以下是一个完整的参考配置示例：

{ “logging”: { 
"level": "info" 
 
}, “agent”: {
 
"model": "anthropic/claude-opus-4-6", "workspace": "~/.openclaw/workspace", "thinkingDefault": "high", "timeoutSeconds": 1800, "heartbeat": { "every": "0m" } 
 
}, “channels”: {
 
"telegram": { "token": "你的Telegram Bot Token", "allowFrom": [] }, "whatsapp": { "allowFrom": ["+00"], "groups": { "*": { "requireMention": true } } } 
 
}, “session”: } }

关键配置项说明

在任何已连接的渠道（WhatsApp/Telegram 等）发送以下命令：

Q: WhatsApp 二维码一直不显示怎么办？

删除已有认证文件，重新扫码：

rm -rf ~/.openclaw/auth_whatsapp/ openclaw channels login

Q: Telegram Bot 不回复消息？

检查以下几点：

1. 确认 Token 填写正确，没有多余空格
2. 确认你发送了 /start 给 Bot
3. 确认你的用户 ID 在 allowFrom 白名单中
4. 运行 openclaw status –deep 查看 Telegram 连接状态

Q: 提示 “API Key 无效” 怎么办？

# 重新配置 API Key openclaw onboard

或者检查环境变量是否正确：

echo $ANTHROPIC_API_KEY

Q: Gateway 启动后浏览器打不开控制面板？

确认端口没有被占用：

lsof -i :18789 # macOS / Linux netstat -ano | findstr :18789 # Windows

如果端口被占用，换一个端口：

openclaw gateway –port 18790

Q: 如何查看运行日志？

# 日志默认存放在： ls /tmp/openclaw/ 
macOS 实时查看日志
 
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

Q: 如何更新到最新版本？

npm install -g openclaw@latest 
更新后重启守护进程
 
openclaw daemon restart

Q: AI 的记忆存储在哪里？

AI 的工作目录默认在 /.openclaw/workspace/，里面包含：

💡 建议把 /.openclaw/workspace/ 目录初始化为一个私有 Git 仓库，方便备份和迁移。

Skills 是 OpenClaw 的扩展能力，社区已发布 5000+ 个 Skill，可以让 AI 操作 Spotify、控制 Philips Hue 智能灯、管理 Obsidian 笔记等。

查找 Skill

直接在聊天里问 AI：

帮我找一个能控制 Spotify 的 Skill

启用 ClawHub 后，AI 可以自动搜索并安装 Skill：

{ “clawhub”: { 
"enabled": true 
 
} }

手动安装 Skill

# 安装单个 Skill openclaw skill install spotify 
查看已安装的 Skill
 
openclaw skill list

自己写一个 Skill

在工作目录 ~/.openclaw/workspace/skills/ 中创建一个 SKILL.md 文件：

# My Custom Skill 
描述
 
这个 Skill 可以做 XXX
 
使用方法
 
当用户说 “XXX” 时，执行以下操作：
 
                        
     
                          
 
                           
步骤一
 
                           
步骤二
 
                          

常用命令速查

openclaw onboard # 运行引导向导 openclaw gateway # 启动 Gateway openclaw gateway –port 8080 # 指定端口启动 openclaw channels login # 渠道登录（扫码等） openclaw status # 查看状态 openclaw status –all # 完整诊断 openclaw doctor # 安全配置检查 openclaw daemon install # 安装开机自启 openclaw daemon start # 启动守护进程 openclaw daemon stop # 停止守护进程 openclaw daemon restart # 重启守护进程 openclaw skill list # 查看已安装 Skill

重要文件路径

相关链接

• 官网：https://openclaw.ai
• GitHub：https://github.com/openclaw/openclaw
• 官方文档：https://docs.openclaw.ai
• 社区 Discord：通过官网加入

教程基于 OpenClaw 最新版本编写，如遇版本差异请以官方文档为准。