OpenClaw (原版小龙虾)保姆级部署教程 (兼容国内大模型平台DeepSeek / 阿里云百炼 / 百度千帆 / 腾讯混元)
🦞 OpenClaw 保姆级部署教程
OpenClaw 是一个开源、自托管的个人 AI 助理框架,让你可以通过 WhatsApp、Telegram、Discord、iMessage 等你已经在用的聊天软件与 AI 对话,并让它帮你执行真实任务:发邮件、管日历、控制浏览器、读写文件……
本教程面向零基础用户,手把手带你从安装到跑通第一条消息。
目录
- OpenClaw 是什么?
- 准备工作(环境 & 账号)
- 安装 OpenClaw
- 运行引导向导
- 连接 Telegram(推荐新手)
- 连接 WhatsApp
- 配置 AI 模型(API Key)
- 接入国内大模型平台(DeepSeek / 阿里云百炼 / 百度千帆 / 腾讯混元)
- 启动 Gateway & 测试
- 设置开机自启(守护进程)
- 常用配置说明
- 常用聊天命令
- 常见问题 FAQ
- 进阶:安装 Skills 技能包
1. OpenClaw 是什么?
OpenClaw(前身为 Clawdbot / Moltbot)是一个运行在你自己设备上的开源 AI Agent 框架,由开发者 Peter Steinberger 创作,MIT 协议开源。
核心特点
| 特性 | 说明 |
|---|---|
| 自托管 | 数据不上传云端,完全运行在你自己的机器上 |
| 多渠道 | WhatsApp、Telegram、Discord、iMessage、Slack 等 20+ 平台 |
| 可扩展 | 通过 SKILL.md 格式安装社区技能包(5000+ 个) |
| 多 Agent | 可以路由到不同的 AI 工作区,支持多角色 |
| 心跳调度 | 可以设置定时任务,让 AI 主动联系你 |
| 开源免费 | GitHub MIT 协议,永久免费 |
架构示意
你的手机 (WhatsApp / Telegram)
│
▼
┌──────────────────────┐
│ Gateway │ ← 运行在你的电脑/服务器上
│ (控制平面 :18789) │
└──────────┬───────────┘
│
┌──────┴──────┐
│ Pi Agent │ ← AI 执行引擎
└─────────────┘
2. 准备工作
2.1 系统要求
| 系统 | 支持情况 |
|---|---|
| macOS (Intel / Apple Silicon) | ✅ 原生支持,体验最佳 |
| Linux (Ubuntu / Debian / Arch) | ✅ 完整支持 |
| Windows 10/11 | ✅ 支持(需 PowerShell) |
2.2 必须安装的软件
Node.js 22 或 24(必须)
Node.js 是运行 OpenClaw 的基础环境。
macOS / Linux 推荐使用 nvm 安装:
# 1. 安装 nvm(Node 版本管理器)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 2. 重新加载终端配置
source ~/.bashrc # Linux
source ~/.zshrc # macOS (zsh)
# 3. 安装 Node 24
nvm install 24
nvm use 24
# 4. 验证安装
node --version # 应该显示 v24.x.x
npm --version
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 的输入,这通常不是你想要的结果。
3. 安装 OpenClaw
根据你的操作系统选择对应方式:
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),说明安装成功。
4. 运行引导向导
OpenClaw 提供了一个交互式的引导向导,帮你一步步完成初始配置。新手强烈推荐从这里开始。
openclaw onboard
向导会引导你完成以下步骤:
- 选择 AI 提供商:Claude / GPT / Ollama 等
- 输入 API Key:Key 会安全存储在本地 Keychain 中
- 选择接入渠道:Telegram、WhatsApp、Discord 等
- 完成 Gateway 初始化
💡 如果你想同时将 Gateway 注册为开机自启服务,运行:
openclaw onboard --install-daemon
5. 连接 Telegram(推荐新手)
Telegram 是最简单的接入方式,不需要额外手机号。
步骤一:创建 Telegram Bot
- 打开 Telegram,搜索 @BotFather
- 发送
/newbot - 按提示输入 Bot 名字(例如:
My AI Assistant) - 输入 Bot 用户名(必须以
bot结尾,例如:myai_helper_bot) - BotFather 会回复一个 Token,格式如:
1234567890:ABCdefGHIjklMNOpqrsTUVwxyz - 复制保存这个 Token
步骤二:获取你的 Telegram 用户 ID
- 搜索 @userinfobot
- 发送任意消息
- Bot 会回复你的用户 ID,例如:
Id: 987654321 - 记下这个数字
步骤三:在 OpenClaw 配置中填入信息
编辑配置文件(首次运行 onboard 后会自动创建):
# 用你喜欢的编辑器打开配置文件
nano ~/.openclaw/openclaw.json
# 或者
code ~/.openclaw/openclaw.json
在 channels 部分添加 Telegram 配置:
{
"channels": {
"telegram": {
"token": "你的BotFather Token",
"allowFrom": [987654321]
}
}
}
将
987654321替换为你的真实 Telegram 用户 ID。allowFrom是白名单,只有这里列出的用户才能跟 AI 对话,防止他人滥用。
步骤四:登录渠道
openclaw channels login
步骤五:发送第一条消息
- 打开 Telegram,搜索你刚创建的 Bot 用户名
- 点击 Start 或发送
/start - 发送任意消息,比如:“你好,介绍一下你自己”
- AI 应该会回复你 🎉
6. 连接 WhatsApp
⚠️ 再次提醒:请使用专用副号,不要用个人主号。
步骤一:准备副手机号
- 可以用副卡、eSIM、网络虚拟号等
- 该号码需要能收到短信验证码
- 将该号码在手机上注册好 WhatsApp(正常使用一次即可)
步骤二:配置允许的联系人
编辑 ~/.openclaw/openclaw.json,添加 WhatsApp 配置:
{
"channels": {
"whatsapp": {
"allowFrom": ["+8613800138000"]
}
}
}
将
+8613800138000替换为你个人手机号(国际格式,含国家代码)。这样只有你的手机能跟 AI 对话。
步骤三:扫码绑定 WhatsApp
openclaw channels login
运行后会弹出一个 二维码,用装有 WhatsApp 副号的手机扫描:
- 打开副号手机上的 WhatsApp
- 点击右上角
⋮→ 已关联的设备 - 点击 关联设备
- 扫描终端中显示的二维码
扫码成功后,你会看到 WhatsApp connected 的提示。
步骤四:从主号发消息测试
用你的个人主号(即 allowFrom 里填的号码)给副号发一条 WhatsApp 消息,AI 应该会自动回复。
7. 配置 AI 模型(API Key)
方式一:通过引导向导配置(推荐)
openclaw onboard
向导会提示你选择提供商并安全存储 Key。
方式二:手动填入配置文件
编辑 ~/.openclaw/openclaw.json:
{
"agent": {
"model": "anthropic/claude-opus-4-6",
"workspace": "~/.openclaw/workspace",
"thinkingDefault": "high",
"timeoutSeconds": 1800
}
}
常用模型名称对照
| 提供商 | 模型配置值 | 备注 |
|---|---|---|
| Anthropic | anthropic/claude-opus-4-6 |
最强,推荐 |
| Anthropic | anthropic/claude-sonnet-4-6 |
平衡速度与能力 |
| OpenAI | openai/gpt-4o |
GPT 系列旗舰 |
| OpenAI | openai/gpt-4o-mini |
速度快,成本低 |
| 本地 Ollama | ollama/llama3.2 |
完全免费,需本地安装 Ollama |
设置 API Key 环境变量(可选)
如果不想在向导中输入,也可以通过环境变量传入:
# 在 ~/.bashrc 或 ~/.zshrc 中添加:
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export OPENAI_API_KEY="sk-xxxxx"
8. 接入国内大模型平台
📌 核心原理:DeepSeek、阿里云百炼、百度千帆、腾讯混元均完整兼容 OpenAI API 格式。只需在 OpenClaw 配置文件中填写对应平台的
baseURL和apiKey,即可无缝切换,完全不需要修改 OpenClaw 本身的任何代码。
8.1 兼容接入原理
OpenClaw 底层调用模型时,走的是标准的 OpenAI /v1/chat/completions 接口。国内各大平台均提供了与这一格式兼容的 API 端点,接入方式完全统一,三步搞定:
1. 拿到目标平台的 API Key
2. 找到该平台的 OpenAI 兼容 base_url
3. 填入 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"
}
}
}
可选模型名称
| 模型名 | 说明 |
|---|---|
deepseek-chat |
DeepSeek-V3,通用对话,速度快 |
deepseek-reasoner |
DeepSeek-R1,深度推理(思维链)模式 |
设置环境变量(推荐)
# 在 ~/.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
- 前往 https://bailian.console.aliyun.com → 登录阿里云账号
- 左侧菜单 → API Key 管理 → 创建 API Key
- 复制 Key(格式为
sk-xxxxxxxx)
第二步:填写配置
{
"agent": {
"model": "qwen-plus",
"openai": {
"baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
可选模型名称
| 模型名 | 说明 |
|---|---|
qwen3-max |
旗舰版,能力最强 |
qwen-plus |
均衡版,速度与效果兼顾(推荐) |
qwen-turbo |
轻量快速版,适合高频对话 |
qwq-plus |
深度推理版(类 DeepSeek-R1) |
deepseek-v3.2 |
百炼平台托管的 DeepSeek-V3 |
deepseek-r1 |
百炼平台托管的 DeepSeek-R1 |
💡 百炼平台同时托管了 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
- 前往 https://aistudio.baidu.com → 登录百度账号
- 右上角头像 → 访问令牌(Access Token) → 生成 / 复制 Token
第二步:填写配置
{
"agent": {
"model": "ernie-4.5-8k",
"openai": {
"baseURL": "https://aistudio.baidu.com/llm/lmapi/v3",
"apiKey": "你的AI_Studio访问令牌"
}
}
}
可选模型名称
| 模型名 | 说明 |
|---|---|
ernie-4.5-8k |
文心 4.5 旗舰版,8K 上下文 |
ernie-4.5-turbo-8k |
文心 4.5 快速版 |
ernie-x1 |
深度推理版,适合复杂任务 |
ernie-3.5-8k |
轻量版,速度快,成本低 |
设置环境变量(推荐)
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
- 前往 https://console.cloud.tencent.com/hunyuan → 登录腾讯云
- 左侧菜单 → API Key 管理 → 新建 API Key
- 复制生成的 Key
第二步:填写配置
{
"agent": {
"model": "hunyuan-turbos-latest",
"openai": {
"baseURL": "https://api.hunyuan.cloud.tencent.com/v1",
"apiKey": "你的腾讯混元API Key"
}
}
}
可选模型名称
| 模型名 | 说明 |
|---|---|
hunyuan-turbos-latest |
混元旗舰版,综合能力强(推荐) |
hunyuan-lite |
轻量版,速度快 |
hunyuan-t1-latest |
深度推理版,适合逻辑推理任务 |
hunyuan-vision-latest |
多模态版,支持图片理解 |
设置环境变量(推荐)
export HUNYUAN_API_KEY="你的腾讯混元API Key"
8.7 四大平台对比速查
| 平台 | base_url | 模型系列 | 费用参考 | 适合场景 |
|---|---|---|---|---|
| DeepSeek | https://api.deepseek.com/v1 |
deepseek-chat / deepseek-reasoner | 极低(¥0.002/千 token 起) | 预算优先、代码、推理 |
| 阿里云百炼 | https://dashscope.aliyuncs.com/compatible-mode/v1 |
qwen 系列 | 低(有免费额度) | 中文对话、多任务、国内合规 |
| 百度千帆 | https://aistudio.baidu.com/llm/lmapi/v3 |
ernie 系列 | 低(有免费额度) | 中文理解、知识问答 |
| 腾讯混元 | https://api.hunyuan.cloud.tencent.com/v1 |
hunyuan 系列 | 低(有免费额度) | 腾讯生态集成、中文场景 |
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。
9. 启动 Gateway & 测试
启动 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 # 检查安全配置风险
10. 设置开机自启(守护进程)
让 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
11. 常用配置说明
配置文件路径:~/.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": [987654321]
},
"whatsapp": {
"allowFrom": ["+8613800138000"],
"groups": {
"*": {
"requireMention": true
}
}
}
},
"session": {
"scope": "per-sender",
"resetTriggers": ["/new", "/reset"],
"reset": {
"mode": "daily",
"atHour": 4,
"idleMinutes": 10080
}
}
}
关键配置项说明
| 配置项 | 说明 |
|---|---|
agent.model |
使用的 AI 模型 |
agent.workspace |
AI 的工作目录(存放记忆、指令文件) |
agent.heartbeat.every |
心跳间隔,AI 会主动联系你。"0m" 表示关闭,"30m" 表示每 30 分钟 |
channels.whatsapp.allowFrom |
WhatsApp 白名单号码列表 |
channels.telegram.allowFrom |
Telegram 白名单用户 ID 列表 |
groups.*.requireMention |
群聊中是否只响应 @mention |
session.reset.mode |
会话重置模式,daily 表示每天凌晨自动重置 |
12. 常用聊天命令
在任何已连接的渠道(WhatsApp/Telegram 等)发送以下命令:
| 命令 | 功能 |
|---|---|
/status |
查看当前会话状态、模型、Token 用量 |
/new 或 /reset |
开启一个全新会话(清除上下文记忆) |
/help |
显示可用命令列表 |
13. 常见问题 FAQ
Q: WhatsApp 二维码一直不显示怎么办?
删除已有认证文件,重新扫码:
rm -rf ~/.openclaw/auth_whatsapp/
openclaw channels login
Q: Telegram Bot 不回复消息?
检查以下几点:
- 确认 Token 填写正确,没有多余空格
- 确认你发送了
/start给 Bot - 确认你的用户 ID 在
allowFrom白名单中 - 运行
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/,里面包含:
| 文件 | 用途 |
|---|---|
AGENTS.md |
AI 行为指令(可自定义 AI 的性格、能力) |
SOUL.md |
AI 的身份设定 |
MEMORY.md |
长期记忆(可手动编辑) |
USER.md |
关于你的个人信息 |
TOOLS.md |
工具使用说明 |
💡 建议把
~/.openclaw/workspace/目录初始化为一个私有 Git 仓库,方便备份和迁移。
14. 进阶:安装 Skills 技能包
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" 时,执行以下操作:
1. 步骤一
2. 步骤二
附录:快速参考
常用命令速查
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
重要文件路径
| 路径 | 用途 |
|---|---|
~/.openclaw/openclaw.json |
主配置文件 |
~/.openclaw/workspace/ |
AI 工作目录(记忆、指令) |
~/.openclaw/auth_whatsapp/ |
WhatsApp 认证数据 |
/tmp/openclaw/*.log |
运行日志 |
相关链接
- 官网:https://openclaw.ai
- GitHub:https://github.com/openclaw/openclaw
- 官方文档:https://docs.openclaw.ai
- 社区 Discord:通过官网加入
教程基于 OpenClaw 最新版本编写,如遇版本差异请以官方文档为准。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)