OpenClaw 实操教程 多通道 AI 助手搭建 + 常用命令 + 故障排查

OpenClaw 是一款可在本机运行的 AI 助手运行时，核心优势的是能让 GPT、Claude 等大模型无缝对接各类 IM 通道，支持多 Agent 协同、网关管理、定时任务等强大功能。本文从安装、常用命令、通道接入到故障排查，全方位拆解实操流程，助力新手快速上手，轻松搭建属于自己的多场景 AI 助手系统。

一、什么是 OpenClaw？

用一句话说：OpenClaw 是一个跑在你本机的 AI 助手运行时，能让 GPT / Claude / Gemini 等大模型”长在”你的 IM 上。

它的核心能力大概是这样：

运行时要求：Node 24（推荐）或 Node 22.16+，支持 macOS / Linux / Windows。

二、一分钟极速安装

OpenClaw 的安装体验做得相当好，基本上一条命令跑完引导，一条命令启动：

# 1. 全局安装 CLI（三选一）
npm install -g openclaw@latest
pnpm add -g openclaw@latest
bun add -g openclaw@latest
# 2. 交互式引导 + 自动安装后台守护进程
openclaw onboard --install-daemon

引导过程会问你几个问题：

• 你想用哪家大模型？（OpenAI / Anthropic / Gemini / 本地 Ollama / LM Studio / …）
• API Key 是啥？
• Gateway 监听哪个端口？（默认 18789）
• 要不要安装后台服务？（推荐 Yes，这样开机自启）

小贴士：如果你已经在用 Codex / Claude CLI 订阅，可以直接选 openai-codex 或 claude-cli，完全不用手输 key，OpenClaw 会自动复用它们的登录凭据。

验证安装：

openclaw --version
openclaw status

如果看到 Gateway 状态 running、Health ok，恭喜你，已经跑起来了。

三、开箱必备：10 个最常用的命令

我按使用频率给你排了个序，这 10 条命令基本覆盖 80% 的日常场景：

openclaw status                          # ① 看一眼整体状态（最常用！）
openclaw doctor                          # ② 出问题先跑它
openclaw gateway restart                 # ③ 改完配置重启网关
openclaw logs --follow                   # ④ 实时看日志
openclaw channels list                   # ⑤ 查看接入了哪些通道
openclaw channels status --probe         # ⑥ 实时探测每个通道是否健康
openclaw agents list --bindings          # ⑦ 查看 agent 和通道的绑定
openclaw agent -m "hello" --deliver      # ⑧ 和 AI 聊一句并投递到默认通道
openclaw message send --to +86xxx -m "x" # ⑨ 主动发消息
openclaw config get agents.list          # ⑩ 读配置

四、接入第一个聊天通道

OpenClaw 支持的通道很多，这里挑三个最典型的演示。

4.1 Telegram（最简单）

去 @BotFather 创建 bot，拿到 token：

# 方式一：明文传入
openclaw channels add --channel telegram --token 123456:ABCDEF...
# 方式二：走环境变量（推荐）
export TELEGRAM_BOT_TOKEN=123456:ABCDEF...
openclaw channels add --channel telegram --use-env

加完后重启 Gateway：

openclaw gateway restart
openclaw channels status --probe

然后到 Telegram 里给你的 bot 发条消息，AI 就会自动回复了。

4.2 Discord

Discord Developer Portal 创建应用和 Bot：

export DISCORD_BOT_TOKEN=xxx
openclaw channels add --channel discord --token "$DISCORD_BOT_TOKEN"

4.3 WhatsApp（需要扫码）

# 交互式扫码登录
openclaw channels login --channel whatsapp --account personal

终端会弹出一个二维码，用手机 WhatsApp 扫描即可完成配对。多个账号就跑多次：

openclaw channels login --channel whatsapp --account biz
openclaw channels login --channel whatsapp --account family

4.4 批量查看接入情况

openclaw channels list --json
openclaw channels status --probe
openclaw channels capabilities --channel discord --json

五、启动与管理 Gateway（核心网关）

Gateway 是 OpenClaw 的”心脏”，所有通道、Agent、RPC 调用都经过它。

5.1 前台运行（调试时最常用）

openclaw gateway --port 18789 --verbose

5.2 作为后台服务运行（生产推荐）

openclaw gateway install         # 安装服务（macOS=launchd / Linux=systemd / Windows=schtasks）
openclaw gateway start
openclaw gateway status
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

5.3 查看运行状态

openclaw gateway status --json
openclaw gateway health
openclaw gateway probe          # 深度探测：本地 + 远程 gateway 全扫一遍
openclaw gateway discover       # 扫描局域网内的 Gateway（Bonjour）
openclaw gateway usage-cost --days 7    # 最近 7 天 LLM 消耗成本

5.4 低级 RPC 调用（调试利器）

openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs":60000}'

踩坑提示：改了 ~/.openclaw/openclaw.json 配置后，一定要 openclaw gateway restart，否则新配置不生效。

六、配置管理：改配置不用手撕 JSON

OpenClaw 提供了非交互式的 config 命令，告别手动改 JSON：

# 查看配置文件路径
openclaw config file
# 读取单个配置
openclaw config get gateway.port
openclaw config get agents.list[0].id
# 写入配置
openclaw config set gateway.port 19000 --strict-json
openclaw config set agents.defaults.heartbeat.every "2h"
# 删除配置
openclaw config unset plugins.entries.brave
# 验证配置是否合法
openclaw config validate --json
# 导出 JSON Schema（给 IDE 补全用）
openclaw config schema > openclaw.schema.json

交互式向导：

openclaw configure                          # 全量向导
openclaw configure --section channels       # 只配通道
openclaw configure --section gateway        # 只配网关

七、和 AI 对话：agent 命令详解

openclaw agent 是无头对话入口，跑一轮 agent 并拿到结果：

# 最简：写一句话让 AI 回
openclaw agent -m "今天该做什么？"
# 开启高强度思考（需模型支持）
openclaw agent -m "帮我 review 这段代码..." --thinking high
# 指定某个 agent（多 agent 场景）
openclaw agent --agent work -m "总结一下今天日程"
# 把结果自动投递到 Slack 某个频道
openclaw agent -m "生成周报" --deliver --reply-channel slack --reply-to "#weekly"
# JSON 输出（写脚本用）
openclaw agent -m "list 3 ideas" --json --timeout 120
# 保持在同一个会话里（多轮对话）
openclaw agent --session-id my-coding-session -m "继续刚才的话题"

关键参数速查：

八、多 Agent 协同：给不同通道配不同”人格”

这是 OpenClaw 最有意思的功能之一。一个 Gateway 里可以跑多个 Agent，每个 Agent 有独立的 workspace、记忆、模型、权限。

8.1 创建多个 Agent

# 开一个专门处理编程任务的 agent，用 Claude Opus
openclaw agents add coding \
  --workspace ~/.openclaw/workspace-coding \
  --model anthropic/claude-opus-4-6 \
  --non-interactive
# 开一个社交聊天的 agent，用 GPT
openclaw agents add social \
  --workspace ~/.openclaw/workspace-social \
  --model openai/gpt-5.4 \
  --non-interactive
# 开一个运维告警的 agent
openclaw agents add ops \
  --workspace ~/.openclaw/workspace-ops \
  --model anthropic/claude-sonnet-4-6 \
  --non-interactive

8.2 绑定通道（路由规则）

# Telegram coding 频道 -> coding agent
openclaw agents bind --agent coding --bind telegram:coding
# 整个 WhatsApp -> social agent
openclaw agents bind --agent social --bind whatsapp
# Discord 的 ops 服 + Slack team-a -> ops agent
openclaw agents bind --agent ops --bind discord:ops
openclaw agents bind --agent ops --bind slack:team-a

绑定粒度超细，支持按 通道 → 账号 → 群组 → 某个用户 逐级匹配，原则是 最具体的规则优先。

8.3 查看绑定关系

openclaw agents list --bindings --json
openclaw agents bindings --agent coding

8.4 解绑和删除

openclaw agents unbind --agent ops --bind slack:team-a
openclaw agents unbind --agent ops --all
openclaw agents delete coding --force

8.5 举个实际场景

老板的需求：个人 WhatsApp 交给”家庭助手”，公司 WhatsApp 交给”工作助手”。

// ~/.openclaw/openclaw.json 片段
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" }
    ]
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }
  ]
}

应用：

openclaw gateway restart
openclaw agents list --bindings

搞定！两个 WhatsApp 号，两个完全独立的 AI，互不串线。

九、消息高阶玩法：广播、投票、编辑、置顶

openclaw message 是通用的消息操作命令，功能非常丰富。

9.1 发消息

# 发文本
openclaw message send --channel telegram --target @mychat -m "hello"
# 发图片
openclaw message send --channel telegram --target @mychat --media ./chart.png
# 引用回复某条消息
openclaw message send --channel discord --target channel:123 -m "同意" --reply-to 456

9.2 广播到所有通道

openclaw message broadcast --channel all \
  --targets +86139xxxx --targets @tgchat --targets channel:discord123 \
  --message "服务器 10 分钟后重启" \
  --dry-run         # 先预演，确认没问题再去掉

9.3 发投票（Discord / Telegram）

openclaw message poll --channel discord --target channel:123 \
  --poll-question "今天吃什么?" \
  --poll-option 火锅 --poll-option 烤肉 --poll-option 轻食 \
  --poll-multi --poll-duration-hours 2

9.4 加表情反应 / 读取历史 / 编辑 / 删除 / 置顶

openclaw message react --channel slack --target C123 --message-id 456 --emoji "🎉"
openclaw message read --channel discord --target channel:123 --limit 50
openclaw message edit --channel slack --target C123 --message-id T123 -m "已更新"
openclaw message delete --channel telegram --target @mychat --message-id 42
openclaw message pin --channel discord --target channel:123 --message-id 456

9.5 Discord 管理命令

openclaw message timeout --guild-id 123 --user-id 456 --duration-min 30 --reason "spam"
openclaw message kick --guild-id 123 --user-id 456
openclaw message ban --guild-id 123 --user-id 456 --delete-days 1

十、定时任务：每天早上自动发晨报

openclaw cron 让 AI 按时工作，非常实用：

# 每天早上 7 点，让 AI 总结昨晚消息并发到 Slack
openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --session isolated \
  --message "总结昨晚团队聊天重要信息" \
  --announce --channel slack --to "channel:C1234567890" \
  --light-context
# 查看所有定时任务
openclaw cron list
# 手动触发一次（不等到 cron 时间）
openclaw cron run <job-id>
# 查看运行历史
openclaw cron runs --id <job-id> --limit 20
# 修改投递目标
openclaw cron edit <job-id> --channel telegram --to "@team-channel"
# 暂停 / 启用 / 删除
openclaw cron disable <job-id>
openclaw cron enable  <job-id>
openclaw cron rm      <job-id>

还支持一次性任务（--at）和间隔任务（--every 10m），详细可参考 openclaw cron add --help。

十一、远程访问：Tailscale + 手机扫码配对

OpenClaw 和 Tailscale 集成得非常好，两条命令就能把你本地的 AI 助手变成全球可达：

# 本机 Gateway 通过 Tailscale Serve 暴露（仅你自己的 Tailnet 内可达）
openclaw gateway --bind tailnet --tailscale serve
# 远程笔记本接入
openclaw --profile remote onboard --mode remote \
  --remote-url wss://mymac.tailnet.ts.net:18789 \
  --remote-token "$OPENCLAW_GATEWAY_TOKEN"
# 给手机生成配对二维码（扫一下即可接入）
openclaw qr --remote

附加能力：把手机变成 Node 节点

# 手机上安装 OpenClaw iOS/Android 端 → 扫码配对
# PC 端审批
openclaw nodes pending
openclaw nodes approve <requestId>
# 之后你的 AI 就能调用手机相机
openclaw nodes camera snap --node phone --facing back
openclaw nodes location get --node phone --accuracy precise
# Mac 作为节点：让 AI 远程打开网页、截屏
openclaw nodes canvas navigate https://example.com --node mac
openclaw nodes screen record --node mac --duration 20s --out ./rec.mp4

想象一下：“Siri，用我家 Mac 打开淘宝搜一下 XXX 并截图发我 Telegram” —— 这些都能脚本化实现。

十二、故障排查：doctor 一把梭

碰到问题怎么办？记住这套排查三板斧：

# 第一步：看状态
openclaw status --deep
openclaw health --verbose
# 第二步：实时日志
openclaw logs --follow
openclaw channels logs --channel all --lines 500
# 第三步：自动修复
openclaw doctor
openclaw doctor --deep
openclaw doctor --fix

doctor --fix 能自动修复 90% 的常见问题：

• Gateway 服务安装不正确
• Workspace 缺失 AGENTS.md
• SecretRef 引用断裂
• 通道凭据过期
• 端口占用 / 旧进程残留

如果 doctor 都救不了，还有终极大招：

openclaw reset --scope config # 只重置配置
openclaw reset --scope config+creds+sessions # 重置配置+凭据+会话（workspace 保留）
openclaw onboard --reset # 重置后再重新引导

十三、模型与 Provider 切换

# 看当前在用什么模型
openclaw models status
# 列出所有可用模型
openclaw models list --all
# 切换默认模型
openclaw models set anthropic/claude-sonnet-4-6
openclaw models set-image openai/gpt-image-1
# 配置失败回退链（主模型挂了自动切换）
openclaw models fallbacks add openai/gpt-5.4
openclaw models fallbacks list
# 登录各家 Provider
openclaw models auth login --provider openai
openclaw models auth login --provider anthropic --method claude-cli --set-default
openclaw models auth login-github-copilot     # GitHub Copilot 特殊 OAuth
# 探活测试（看哪些 key 过期了）
openclaw models status --probe --json

独立推理能力（可以脱离 agent 单独调用）：

openclaw infer model run --prompt "写一首关于龙虾的诗" --json
openclaw infer image generate --prompt "一只戴皇冠的龙虾，像素风" --json
openclaw infer audio transcribe --file ./meeting.m4a --json
openclaw infer tts convert --text "你好" --output ./out.mp3 --json
openclaw infer web search --query "OpenClaw 最新版本" --json

这些命令相当于给你提供了一套标准化的 LLM 工具 CLI，可以直接在 shell 脚本里用。

十四、安全加固：API Key 不再明文落盘

千万别把 API Key 明文写进 openclaw.json，万一误传到 Git 就炸了。

正确做法：用 SecretRef 把 key 引用到环境变量：

# 1. 在 shell 或 ~/.openclaw/.env 里配置
export DISCORD_BOT_TOKEN=xxx
echo "OPENAI_API_KEY=sk-xxx" >> ~/.openclaw/.env
# 2. 配置改成引用
openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN
# 3. Dry-run 先预演
openclaw config set channels.discord.token \
  --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN \
  --dry-run
# 4. 审计一下有没有明文 key 残留
openclaw secrets audit --check
openclaw security audit --deep
# 5. 热重载
openclaw secrets reload

如果企业场景需要更安全的密钥管理，还支持 file 和 exec 形式的 Provider（比如接入 HashiCorp Vault）。

十五、升级、备份、卸载

升级

openclaw update                        # 升级到最新 stable
openclaw update --channel beta         # 切换到 beta 通道
openclaw update --channel dev          # nightly
openclaw update status
openclaw update wizard

备份

openclaw backup create --output ./openclaw-backup.tar.gz --verify
openclaw backup verify ./openclaw-backup.tar.gz --json

卸载

openclaw uninstall # 交互选择要删除什么
openclaw uninstall --all --yes # 全删（服务 + 状态 + workspace + 应用）
openclaw uninstall --dry-run # 先预览

附：高频命令速查表

复制保存这张表，平时用的时候翻一翻就够了：

结语

OpenClaw 给我的最大感受是：它把”把大模型装进生活”这件事做成了一套工程化、可运维的系统。你可以当它是玩具，也可以用它搭一个全天候的 AI 秘书、代码助手、社群机器人。

我个人目前的用法：

• Telegram 绑定 coding agent → 做代码 review、翻译、写 commit message
• WhatsApp 绑定 home agent → 家庭日常、购物清单、日历管理
• Slack 绑定 ops agent → 接告警、自动值班、每日站会纪要
• Discord 绑定 social agent → 社群机器人
• iPhone Node → 远程截图、拍照、查位置
• Cron 定时任务 → 每天晨报、周报、月度总结

如果你也有类似需求，强烈建议动手玩一下。这篇教程涵盖了我平时 90% 以上的操作，从零开始跟着敲一遍，差不多 30 分钟就能搭好一个属于你自己的多通道 AI 助手。

OpenClaw 以简洁的安装流程、丰富的命令工具、灵活的多通道与多 Agent 配置，实现了大模型与日常场景的深度融合。掌握文中核心操作，既能高效管理 AI 助手，也能通过远程访问、安全加固等功能拓展使用边界，轻松让 AI 成为工作生活的得力帮手。

相关资源

• 官方文档：点击这里
• GitHub：点击这里

以上关于OpenClaw 实操教程 多通道 AI 助手搭建 + 常用命令 + 故障排查的文章就介绍到这了，更多相关内容请搜索码云笔记以前的文章或继续浏览下面的相关文章，希望大家以后多多支持码云笔记。