前置准备 — 你需要什么Prerequisites — What You Need Prerequisites — What You Need
Mac Mini（M1 / M2 / M3 / M4 任意芯片均可），macOS 12+ 系统。推荐 M4 款 16GB 内存，约 $600，安静节能，24/7 运行年电费约 $10-15。
Mac Mini (M1/M2/M3/M4 any chip), macOS 12+. Recommended: M4 with 16GB RAM (~$600), silent, energy-efficient, ~$10-15/year electricity for 24/7 operation.
稳定的互联网连接。如果你在中国大陆，Telegram 需要代理/VPN；飞书不需要。API 调用也需要能访问对应的模型服务商。
Stable internet. In mainland China, Telegram requires proxy/VPN; Feishu does not. API calls need access to your chosen model provider.
至少准备一个 AI 模型的 API Key（如 Anthropic Claude、OpenAI GPT、火山引擎/豆包等）。后面会详细讲配置。
At least one AI model API key (Anthropic Claude, OpenAI GPT, Volcengine/Doubao, etc.). Configuration covered later.
下面所有命令都在 Mac 的「终端」(Terminal) 应用中执行。打开方式：按 ⌘ + 空格，输入 "Terminal"，回车即可。
All commands below are run in the Mac "Terminal" app. Open it: press ⌘ + Space, type "Terminal", press Enter.
安装 Homebrew 和 Node.jsInstall Homebrew & Node.js Install Homebrew & Node.js
Homebrew 是 macOS 上安装软件的神器。打开终端，粘贴以下命令并回车：
Homebrew is the best way to install software on macOS. Open Terminal, paste and run:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
安装过程中可能需要输入你的 Mac 密码（输入时不会显示字符，这是正常的），然后按提示操作。
You may need to enter your Mac password during installation (characters won't show — that's normal).
安装完成后，终端会提示你运行两行命令来配置 PATH。请务必复制并执行那两行！通常是：
After install, Terminal will show two commands to configure PATH. You MUST run them! Usually:
# Apple Silicon Mac 通常是这两行（请以实际输出为准）
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew --version，看到版本号如 Homebrew 4.x.x 即表示成功。
Verify: run brew --version. Seeing something like Homebrew 4.x.x means success.
OpenClaw 需要 Node.js 22 或更高版本。用 Homebrew 安装：
OpenClaw requires Node.js 22+. Install via Homebrew:
brew install node@22
node -v，看到 v22.x.x 或更高即可。同时运行 npm -v 确认 npm 也已安装。
Verify: run node -v → should show v22.x.x or higher. Also run npm -v to confirm npm is installed.
如果 npm 下载缓慢，可以先换源：npm config set registry https://registry.npmmirror.com
If npm is slow in China, set mirror: npm config set registry https://registry.npmmirror.com
安装 OpenClaw 并运行 OnboardInstall OpenClaw & Run Onboard Install OpenClaw & Run Onboard
npm install -g openclaw@latest
这会把 OpenClaw 安装为全局命令行工具。等待安装完成（可能需要几分钟）。
This installs OpenClaw as a global CLI tool. Wait for completion (may take a few minutes).
openclaw -v，看到版本号即成功，如 2026.3.x。
Verify: run openclaw -v → shows version like 2026.3.x.
说明 npm 全局路径不在 PATH 里。运行以下命令修复：
npm global path is not in your PATH. Fix with:
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc source ~/.zshrc
OpenClaw 自带交互式引导向导，帮你一步步配置 Gateway、工作目录、频道和技能。强烈推荐用这个方式！
OpenClaw includes an interactive wizard for step-by-step Gateway, workspace, channels, and skills setup. Highly recommended!
openclaw onboard --install-daemon
--install-daemon 会同时安装守护进程（launchd 服务），让 OpenClaw Gateway 开机自启、后台常驻。向导中会问你选 Quickstart 还是 Custom：
--install-daemon also installs the daemon (launchd service) so the Gateway auto-starts and runs in background. The wizard asks Quickstart vs Custom:
Custom：手动配置 API Key、模型等高级选项。 Quickstart: Default settings, fastest start, best for beginners.
Custom: Manual API keys, models, and advanced options.
按提示操作即可。向导会引导你选择 AI 模型提供商、设置 API Key、选择安装哪些 Skills（技能）。
Follow the prompts. The wizard guides you through model provider, API key, and Skills selection.
openclaw gateway status，看到 running 表示 Gateway 已启动成功。
When done, run openclaw gateway status → seeing running means Gateway is up.
配置 AI 模型 (API Key)Configure AI Model (API Key) Configure AI Model (API Key)
OpenClaw 本身不是 AI 模型，它需要调用一个外部 LLM。推荐使用最强的最新模型以获得最佳体验。以下是常见选项：
OpenClaw is not an AI model itself — it calls an external LLM. Use the strongest latest model for best experience. Common options:
前往 console.anthropic.com 注册并获取 API Key。然后配置：
Go to console.anthropic.com, sign up and get your API key. Then configure:
openclaw config set models.providers.anthropic.apiKey "sk-ant-xxxxxxxxxx"
前往 platform.openai.com 获取 API Key。然后配置：
Go to platform.openai.com for your API key. Then configure:
openclaw config set models.providers.openai.apiKey "sk-xxxxxxxxxx"
前往 火山引擎控制台 开通大模型服务（豆包 Doubao），获取 API Key。然后配置：
Go to Volcengine Console, enable Doubao model service, get API key. Then configure:
openclaw config set models.providers.volcengine.apiKey "your-volcengine-api-key"
openclaw models list 查看已配置的模型。你也可以在 onboard 向导中直接设置。
Verify: run openclaw models list to see configured models. You can also set this during the onboard wizard.
接入 Telegram 客户端Connect Telegram Channel Connect Telegram Channel ✈️
打开 Telegram，搜索 @BotFather（注意认准蓝色认证徽章 ✓），然后：
Open Telegram, search for @BotFather (verify blue checkmark ✓), then:
/newbot # BotFather 会问你 bot 名称（显示名），随便起 # 然后问 username（必须以 bot 结尾），如：my_openclaw_bot # 创建成功后 BotFather 会给你一个 Token，形如： 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
把 Token 填入 OpenClaw 配置：
Add the token to OpenClaw config:
# 用你自己的 Token 替换下面的值
openclaw config set channels.telegram.enabled true --json
openclaw config set channels.telegram.botToken "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
openclaw config set channels.telegram.dmPolicy "pairing"
然后重启 Gateway：
Then restart Gateway:
openclaw gateway restart
在 Telegram 中搜索你刚创建的 bot，给它发一条消息（比如 /start）。Bot 会回复一个配对码。
In Telegram, find your new bot and send it a message (e.g. /start). It will reply with a pairing code.
回到终端，批准配对：
Back in Terminal, approve the pairing:
# 查看待批准的配对请求 openclaw pairing list telegram # 批准配对（用实际的配对码替换） openclaw pairing approve telegram <pairing_code> --notify
接入飞书 (Feishu) 客户端Connect Feishu (Lark) Channel Connect Feishu (Lark) Channel 📘
登录 飞书开放平台（国际版 Lark 用 open.larksuite.com），点击 「创建企业自建应用」。
Log in to Feishu Open Platform (or open.larksuite.com for Lark). Click "Create Enterprise App".
设置应用名称、图标、描述。创建后在 「凭证与基础信息」 页面复制 App ID（形如 cli_xxxx）和 App Secret。
Set app name, icon, description. After creation, copy App ID (like cli_xxxx) and App Secret from the Credentials page.
在飞书开放平台的应用管理后台，依次操作：
In the Feishu app management console, do the following:
① 开启机器人能力：应用能力 → 机器人 → 开启
② 添加权限：权限管理 → 批量开通以下权限：
• im:message（接收消息）
• im:message:send_as_bot（以机器人身份发送消息）
③ 事件订阅 → 选择「使用长连接」（WebSocket 模式）⚡ 这一步最关键！
• 不要选 Webhook/HTTP 回调！长连接不需要公网 URL
• 添加事件：im.message.receive_v1（接收消息事件）
④ 发布应用：版本管理与发布 → 创建版本 → 发布
• 企业自建应用通常自动审批通过
① Enable Bot: App Capability → Bot → Enable
② Add Permissions: Permissions → Batch import:
• im:message (receive messages)
• im:message:send_as_bot (send as bot)
③ Event Subscription → Select "Long Connection" (WebSocket mode) ⚡ This is critical!
• Do NOT use Webhook/HTTP callback! Long connection needs no public URL
• Add event: im.message.receive_v1
④ Publish App: Version Management → Create Version → Publish
• Self-built enterprise apps usually auto-approve
把飞书应用的凭证填入 OpenClaw：
Add Feishu app credentials to OpenClaw:
# 用你自己的 App ID 和 App Secret 替换
openclaw config set channels.feishu.enabled true --json
openclaw config set channels.feishu.appId "cli_xxxxxxxxxxxx"
openclaw config set channels.feishu.appSecret "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
openclaw config set channels.feishu.connectionMode "websocket"
openclaw config set channels.feishu.dmPolicy "pairing"
如果你用的是国内飞书，不需要额外设置 domain（默认就是 feishu）。如果用国际版 Lark，需要额外运行：openclaw config set channels.feishu.domain "lark"
If using domestic Feishu, no extra domain config needed (defaults to feishu). For international Lark, add: openclaw config set channels.feishu.domain "lark"
重启 Gateway：
Restart Gateway:
openclaw gateway restart
打开飞书 App，找到你创建的应用（搜索应用名称），给它发一条消息。Bot 会回复配对码。
Open Feishu, find your app (search by name), send it a message. Bot replies with a pairing code.
# 批准飞书配对
openclaw pairing approve feishu <pairing_code> --notify
为什么选 Telegram 而不是 WhatsApp？Why Telegram over WhatsApp? Why Telegram over WhatsApp?
OpenClaw 连接 WhatsApp 用的是第三方库 Baileys，原理是模拟浏览器登录 WhatsApp Web。但 WhatsApp 官方没有提供任何 Bot 接口，所有自动化都是逆向工程搞出来的，WhatsApp 不仅不支持，还会主动检测和打击。
OpenClaw connects to WhatsApp via Baileys, a third-party library that emulates a WhatsApp Web browser session. WhatsApp offers no official Bot API — all automation is reverse-engineered, and WhatsApp actively fights it.
频繁断线Frequent disconnections
一天断开好几次，每次 5-11 秒。断开期间消息直接丢失，无报错。Multiple drops per day, 5-11 seconds each. Messages during gaps silently lost.
静默死亡Silent dead state
连接看起来正常，实际已收不到消息。只能手动重启修复。Looks healthy but stops receiving. Only a full restart fixes it.
每 30 分钟强制重连Forced reconnect every 30 min
无消息时系统主动断开重连，通常能恢复，偶尔连不回来。System disconnects if idle 30 min. Usually recovers, sometimes doesn't.
每 ~14 天重新扫码Re-scan every ~14 days
WhatsApp 定期踢掉关联设备，必须用手机重新扫二维码。WhatsApp periodically kicks linked devices — phone QR re-scan required.
封号风险Ban risk
程序崩溃反复重启会被判异常，封号 48-72 小时起步。Repeated crash-restarts trigger abuse detection — 48-72+ hour bans.
WhatsApp 自动化 =WhatsApp automation =
偷偷翻墙进去的，模拟浏览器蒙混过关。随时可能被发现、断线、封号。Sneaking in the back door pretending to be a browser. Could get caught anytime.
Telegram 完全不同——官方专门设计了 Bot API，鼓励开发者接入。用 Bot 完全合规，零封号风险。
Telegram is fundamentally different — they provide an official Bot API designed for automation. Fully supported, zero ban risk.
官方支持，接口稳定Official support, stable API
Bot 是平台核心功能，接口向后兼容，文档完善。Bots are first-class citizens. Backward-compatible, well-documented.
3 分钟搞定配置3-minute setup
@BotFather 创建 → 拿 token → 填进 OpenClaw。不需扫码，不需关联设备。@BotFather → get token → paste into OpenClaw. No QR, no device linking.
永不断线Never disconnects
HTTP 轮询或 Webhook，服务器重启自动恢复，无需重新认证。HTTP long-polling or webhooks. Survives restarts, no re-auth needed.
不依赖手机Phone-independent
Bot 独立运行，手机关机没网都不影响。WhatsApp 需手机在线。Bot runs independently. Phone can be off — bot keeps working.
零封号风险Zero ban risk
官方接口，用 Bot 就是 Telegram 希望你做的事。Using Bot API is exactly what Telegram wants you to do.
Telegram 自动化 =Telegram automation =
人家给你发了正式邀请函，正大光明走前门进去。稳如磐石。Walking in the front door with an official key. Rock solid.
| ✈️ Telegram | ||
|---|---|---|
| 接入方式Connection | 逆向工程模拟浏览器Reverse-engineered 非官方Unofficial | 官方 Bot APIOfficial Bot API 官方Official |
| 稳定性Stability | 每天多次断线Multiple daily drops | 几乎不断线Almost never |
| 封号风险Ban risk | 有，48-72h+Yes, 48-72h+ ⚠ | 零Zero ✓ |
| 扫码？QR scan? | 每 ~14 天Every ~14 days | 不需要Never |
| 依赖手机？Phone? | 是Yes | 否No |
| 消息丢失Msg loss | 断线期间静默丢失Silent loss during drops | 不会No loss |
一句话总结：WhatsApp 是偷偷翻墙进去的，随时被赶出来；Telegram 是人家发了正式邀请函进门的，稳如老狗。 Bottom line: WhatsApp is climbing over someone's wall uninvited — kicked out anytime. Telegram is a formal invitation — solid as a rock.
验证 & 日常运维Verify & Daily Operations Verify & Daily Operations
# 查看 Gateway 状态 openclaw gateway status # 查看所有频道连接状态 openclaw channels status # 实时查看日志（调试利器） openclaw logs --follow # 查看当前配置 openclaw config get # 重启 Gateway openclaw gateway restart # 更新到最新版本 npm install -g openclaw@latest # 诊断问题 openclaw doctor
说明 WebSocket 长连接未建立。检查：①事件订阅是否选了「长连接」；②应用是否已发布；③权限是否已全部开通。修改后需重新发布应用！
WebSocket connection not established. Check: ①Event subscription set to "Long Connection"; ②App is published; ③All permissions granted. Re-publish after any changes!
运行 openclaw logs --follow 查看日志。常见原因：Token 填错、网络不通（国内需代理）、Gateway 未启动。
Run openclaw logs --follow to check logs. Common causes: wrong token, network issues (proxy needed in China), Gateway not running.
如果看到 sharp 相关错误，试试设置环境变量后重装：SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
If you see sharp-related errors, try: SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
安全提醒Security Reminders Security Reminders
彻底卸载 OpenClawCompletely Uninstall OpenClaw Completely Uninstall OpenClaw
先把 OpenClaw 的所有运行进程和后台服务停掉：
First stop all running processes and background services:
# 停止 Gateway openclaw gateway stop # 卸载 launchd 守护进程（开机自启服务） launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist 2>/dev/null rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist # 如果用了旧版名称 (moltbot/clawdbot)，也一并清理 launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.moltbot.gateway.plist 2>/dev/null rm -f ~/Library/LaunchAgents/com.moltbot.gateway.plist # 确保没有残留进程 pkill -f "openclaw" 2>/dev/null
ps aux | grep openclaw，不应再看到任何 openclaw 进程。
Verify: run ps aux | grep openclaw — no openclaw processes should appear.
# 卸载 OpenClaw 全局包 npm uninstall -g openclaw # 如果你用 pnpm 安装的 pnpm remove -g openclaw 2>/dev/null
openclaw -v，应显示 command not found。
Verify: run openclaw -v — should show command not found.
这是最关键的一步。OpenClaw 会在以下位置存放配置、会话记录、技能、日志等数据：
This is the key step. OpenClaw stores config, sessions, skills, and logs in these locations:
包括你的 API Key 配置、对话历史、自定义 Skills 等。如需备份请先复制到其他位置。
Including API keys, conversation history, custom Skills, etc. Back up first if needed.
# ⚡ 主配置目录（包含 openclaw.json、API Key、会话记录、Agent 数据等） rm -rf ~/.openclaw # ⚡ 旧版名称的残留目录（如果从 Clawdbot/Moltbot 迁移过来的） rm -rf ~/.clawdbot rm -rf ~/.moltbot # ⚡ 工作目录（如果你指定过自定义 workspace） # 默认在 ~/.openclaw/workspace，上面已删除；如果自定义了路径请自行删除 # ⚡ 应用支持目录（macOS Companion App 的数据） rm -rf ~/Library/Application\ Support/OpenClaw rm -rf ~/Library/Application\ Support/Moltbot rm -rf ~/Library/Application\ Support/Clawdbot # ⚡ macOS Companion App 本体（如果安装了 .app） rm -rf /Applications/OpenClaw.app rm -rf /Applications/Moltbot.app # ⚡ 缓存目录 rm -rf ~/Library/Caches/OpenClaw rm -rf ~/Library/Caches/ai.openclaw.app # ⚡ 日志目录 rm -rf ~/Library/Logs/OpenClaw # ⚡ Preferences（偏好设置 plist） rm -f ~/Library/Preferences/ai.openclaw.app.plist defaults delete ai.openclaw.app 2>/dev/null
如果你之前在 Shell 配置文件中添加过 OpenClaw 相关的环境变量，需要手动清理：
If you added OpenClaw env variables to your shell config, clean them up manually:
# 用编辑器打开你的 Shell 配置文件 nano ~/.zshrc # 查找并删除包含以下关键词的行： # OPENCLAW_ # TELEGRAM_BOT_TOKEN # FEISHU_APP_ID # FEISHU_APP_SECRET # VOLCENGINE_API_KEY # ANTHROPIC_API_KEY（如果是专为 OpenClaw 设置的） # OPENAI_API_KEY（如果是专为 OpenClaw 设置的） # 保存退出后重新加载 source ~/.zshrc
别忘了在各平台撤销 OpenClaw 的访问权限：
Don't forget to revoke OpenClaw's access on each platform:
Telegram：在 @BotFather 中发送 /deletebot，选择你的 bot 删除（或用 /revoke 仅作废 Token）
飞书：登录 飞书开放平台，进入应用管理，停用或删除你创建的应用
AI 模型 API Key：如果 Key 是专为 OpenClaw 创建的，到对应平台（Anthropic / OpenAI / 火山引擎）删除或禁用该 Key
Telegram: Send /deletebot to @BotFather and select your bot (or /revoke to just invalidate the token)
Feishu: Log in to Feishu Open Platform, disable or delete the app
AI Model API Keys: If keys were created specifically for OpenClaw, delete or disable them on the respective platform (Anthropic / OpenAI / Volcengine)
# 确认命令已不存在 which openclaw # 应输出：openclaw not found # 确认配置目录已删除 ls ~/.openclaw 2>&1 # 应输出：No such file or directory # 确认没有残留进程 ps aux | grep -v grep | grep openclaw # 应无输出 # 确认 launchd 服务已移除 launchctl list | grep openclaw # 应无输出