🦞 OpenClaw 保姆级部署教程

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 技能包

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(至少一个):
  • 一个额外手机号(用于 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

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

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

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

openclaw onboard --install-daemon

5. 连接 Telegram(推荐新手)

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

步骤一:创建 Telegram Bot

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

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

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

步骤三:在 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

步骤五:发送第一条消息

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

6. 连接 WhatsApp

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

步骤一:准备副手机号

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

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

编辑 ~/.openclaw/openclaw.json,添加 WhatsApp 配置:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+8613800138000"]
    }
  }
}

+8613800138000 替换为你个人手机号(国际格式,含国家代码)。这样只有你的手机能跟 AI 对话。

步骤三:扫码绑定 WhatsApp

openclaw channels login

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

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

扫码成功后,你会看到 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 配置文件中填写对应平台的 baseURLapiKey,即可无缝切换,完全不需要修改 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

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

可选模型名称

模型名 说明
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

  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访问令牌"
    }
  }
}

可选模型名称

模型名 说明
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

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

可选模型名称

模型名 说明
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 不回复消息?

检查以下几点:

  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/,里面包含:

文件 用途
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 运行日志

相关链接


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

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐