OpenClaw 使用说明文档

Posted recently Updated recently

By Administrator

58~75 min read

OpenClaw 简介

什么是 OpenClaw?

OpenClaw 是一个自托管的多渠道网关,用于连接各种聊天应用(WhatsApp、Telegram、Discord、iMessage 等)到 AI 编码代理(如 Pi)。你可以在自己的硬件上运行单个网关进程,它将成为你的消息应用和始终可用的 AI 助手之间的桥梁。

核心特性

自托管: 运行在你的硬件上,你的规则
多渠道: 一个网关同时服务 WhatsApp、Telegram、Discord 等
代理原生: 为编码代理构建,支持工具使用、会话、内存和多代理路由
开源: MIT 许可,社区驱动

主要功能

多渠道网关 (WhatsApp, Telegram, Discord, iMessage)
插件渠道 (Mattermost 等)
多代理路由 (每个代理、工作区或发送者的隔离会话)
媒体支持 (发送和接收图像、音频、文档)
Web 控制界面 (浏览器仪表板)
移动节点 (配对 iOS 和 Android 节点)

系统要求与安装

系统要求

Node.js: 22 或更新版本
操作系统: macOS, Linux, Windows
API 密钥: 来自你选择的提供商（Anthropic, OpenAI 等）

检查 Node 版本:

node --version

安装方法

方法 1: 快速安装脚本 (推荐)

macOS/Linux:

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell):

iwr -useb https://openclaw.ai/install.ps1 | iex

方法 2: npm 全局安装

npm install -g openclaw@latest

方法 3: 使用 pnpm (推荐用于开发)

pnpm add -g openclaw@latest

快速开始

第一步: 运行引导向导

openclaw onboard --install-daemon

引导向导会配置:

认证设置
网关配置
可选的聊天渠道

第二步: 检查网关状态

openclaw gateway status

第三步: 打开控制界面

openclaw dashboard

或直接访问: http://127.0.0.1:18789/

第四步: 发送测试消息 (可选)

需要先配置渠道:

openclaw message send --target +15555550123 --message "Hello from OpenClaw"

命令行工具详解

全局选项

--dev                # 开发模式 (隔离状态到 ~/.openclaw-dev)
--profile <name>     # 使用命名配置文件 (隔离到 ~/.openclaw-<name>)
--no-color           # 禁用 ANSI 颜色
-V, --version        # 显示版本号
-h, --help           # 显示帮助信息

核心命令分类

1. 设置与配置

命令	说明	示例
`setup`	初始化配置和工作区	`openclaw setup --workspace ~/.openclaw/workspace`
`onboard`	交互式引导向导	`openclaw onboard --install-daemon`
`configure`	交互式配置向导	`openclaw configure`
`config get`	获取配置值	`openclaw config get agents.defaults.workspace`
`config set`	设置配置值	`openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4-6"`
`config unset`	删除配置值	`openclaw config unset tools.web.search.apiKey`

2. 网关管理

命令	说明	示例
`gateway`	运行网关	`openclaw gateway --port 18789`
`gateway status`	检查网关状态	`openclaw gateway status`
`gateway start`	启动网关服务	`openclaw gateway start`
`gateway stop`	停止网关服务	`openclaw gateway stop`
`gateway restart`	重启网关服务	`openclaw gateway restart`
`gateway install`	安装网关服务	`openclaw gateway install --port 18789`
`gateway uninstall`	卸载网关服务	`openclaw gateway uninstall`

3. 渠道管理

命令	说明	示例
`channels list`	列出已配置的渠道	`openclaw channels list`
`channels status`	检查渠道健康状态	`openclaw channels status --probe`
`channels login`	登录渠道 (WhatsApp)	`openclaw channels login --channel whatsapp`
`channels logout`	登出渠道	`openclaw channels logout --channel whatsapp`
`channels add`	添加新渠道	`openclaw channels add --channel telegram --token $TOKEN`
`channels remove`	移除渠道	`openclaw channels remove --channel telegram --delete`
`channels logs`	查看渠道日志	`openclaw channels logs --channel telegram --lines 100`

4. 消息管理

命令	说明	示例
`message send`	发送消息	`openclaw message send --target +15555550123 --message "Hi"`
`message poll`	创建投票	`openclaw message poll --channel discord --target channel:123 --poll-question "Snack?" --poll-option Pizza`
`message react`	添加反应	`openclaw message react --message-id 123 --emoji "👍"`
`message delete`	删除消息	`openclaw message delete --message-id 123`
`message edit`	编辑消息	`openclaw message edit --message-id 123 --message "Updated"`

5. 模型管理

命令	说明	示例
`models list`	列出可用模型	`openclaw models list`
`models status`	显示模型状态	`openclaw models status`
`models set`	设置主模型	`openclaw models set anthropic/claude-sonnet-4-6`
`models scan`	扫描可用模型	`openclaw models scan`
`models auth add`	添加认证	`openclaw models auth add`

6. 代理管理

命令	说明	示例
`agent`	运行单次代理回合	`openclaw agent --message "Hello" --deliver`
`agents list`	列出已配置的代理	`openclaw agents list`
`agents add`	添加新代理	`openclaw agents add myagent --workspace ~/myworkspace`
`agents delete`	删除代理	`openclaw agents delete myagent`

7. 会话管理

命令	说明	示例
`sessions`	列出会话	`openclaw sessions`
`status`	显示会话健康状态	`openclaw status`
`health`	获取网关健康状态	`openclaw health`

8. 节点管理

命令	说明	示例
`nodes status`	显示节点状态	`openclaw nodes status`
`nodes list`	列出节点	`openclaw nodes list`
`nodes approve`	批准节点配对	`openclaw nodes approve <requestId>`
`nodes camera snap`	拍照	`openclaw nodes camera snap --node myphone`
`nodes notify`	发送通知	`openclaw nodes notify --node myphone --title "Alert"`

9. 浏览器控制

命令	说明	示例
`browser status`	浏览器状态	`openclaw browser status`
`browser start`	启动浏览器	`openclaw browser start`
`browser open`	打开 URL	`openclaw browser open https://example.com`
`browser screenshot`	截图	`openclaw browser screenshot`
`browser snapshot`	快照	`openclaw browser snapshot`

10. 定时任务

命令	说明	示例
`cron list`	列出定时任务	`openclaw cron list`
`cron add`	添加任务	`openclaw cron add --name backup --every 1h --message "Backup"`
`cron enable`	启用任务	`openclaw cron enable <id>`
`cron disable`	禁用任务	`openclaw cron disable <id>`
`cron rm`	删除任务	`openclaw cron rm <id>`

11. 工具与实用程序

命令	说明	示例
`doctor`	健康检查和快速修复	`openclaw doctor`
`logs`	查看网关日志	`openclaw logs --follow`
`dashboard`	打开控制界面	`openclaw dashboard`
`tui`	打开终端界面	`openclaw tui`
`backup create`	创建备份	`openclaw backup create`
`reset`	重置配置/状态	`openclaw reset --scope config`
`uninstall`	卸载 OpenClaw	`openclaw uninstall --all`
`update`	更新 OpenClaw	`openclaw update`

配置文件说明

配置文件位置

主配置文件: ~/.openclaw/openclaw.json

格式: JSON5 (支持注释和尾随逗号)

最小配置示例

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"]
    }
  },
}

完整配置示例

{
  // 网关设置
  gateway: {
    port: 18789,
    bind: "loopback",  // loopback | lan | tailnet | auto | custom
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",  // 环境变量引用
    },
    reload: {
      mode: "hybrid",  // hybrid | hot | restart | off
      debounceMs: 300,
    },
  },

  // 代理设置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.2"],
      },
      heartbeat: {
        every: "30m",
        target: "last",
      },
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },

  // 渠道配置
  channels: {
    // WhatsApp
    whatsapp: {
      dmPolicy: "pairing",  // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
    },

    // Telegram
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
      },
      streaming: "partial",  // off | partial | block | progress
    },

    // Discord
    discord: {
      enabled: true,
      token: "${DISCORD_BOT_TOKEN}",
      dmPolicy: "pairing",
      allowFrom: ["1234567890"],
      guilds: {
        "123456789012345678": {
          requireMention: false,
          channels: {
            general: { allow: true },
          },
        },
      },
    },
  },

  // 会话管理
  session: {
    dmScope: "per-channel-peer",  // main | per-peer | per-channel-peer
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },

  // 定时任务
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },

  // Webhooks
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

配置热重载

网关会监视配置文件并自动应用更改,大多数设置无需手动重启。

重载模式:

hybrid (默认): 安全更改立即应用,关键更改自动重启
hot: 仅应用安全更改,需要重启时记录警告
restart: 任何配置更改都重启网关
off: 禁用文件监视

环境变量

配置中可以使用环境变量引用:

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  models: {
    providers: {
      openai: {
        apiKey: "${OPENAI_API_KEY}"
      }
    }
  },
}

环境变量来源:

父进程环境变量
当前目录的 .env 文件
~/.openclaw/.env 文件

文件路径与目录结构

主目录结构

~/.openclaw/
├── openclaw.json              # 主配置文件
├── openclaw.json.bak          # 配置备份
├── workspace/                 # 代理工作区
│   ├── AGENTS.md             # 代理指南
│   ├── SOUL.md               # 代理个性
│   ├── USER.md               # 用户信息
│   ├── IDENTITY.md           # 代理身份
│   ├── TOOLS.md              # 工具笔记
│   ├── HEARTBEAT.md          # 心跳配置
│   ├── MEMORY.md             # 长期记忆
│   └── memory/               # 每日记忆
│       └── YYYY-MM-DD.md
├── credentials/              # 凭证存储
│   ├── whatsapp/            # WhatsApp 会话
│   ├── telegram/            # Telegram 会话
│   └── discord/             # Discord 会话
├── logs/                    # 日志文件
│   ├── gateway.log
│   └── channels.log
├── agents/                  # 多代理配置
├── devices/                 # 设备配对
├── cron/                    # 定时任务
├── browser/                 # 浏览器数据
├── canvas/                  # Canvas 数据
├── identity/                # 身份数据
├── extensions/              # 插件扩展
├── delivery-queue/          # 消息队列
├── telegram/                # Telegram 数据
└── exec-approvals.json      # 执行批准

重要文件说明

文件/目录	说明
`openclaw.json`	主配置文件 (JSON5 格式)
`workspace/`	代理工作区,包含记忆、工具、技能等
`credentials/`	渠道认证凭证 (敏感数据)
`logs/`	网关和渠道日志
`devices/`	配对的移动设备信息
`cron/`	定时任务配置和运行日志

环境变量覆盖

# 自定义状态目录
export OPENCLAW_STATE_DIR=~/custom-openclaw

# 自定义配置文件
export OPENCLAW_CONFIG_PATH=~/custom-openclaw.json

# 自定义 HOME 目录
export OPENCLAW_HOME=/custom/home

常用场景示例

场景 1: 配置 WhatsApp

# 1. 登录 WhatsApp
openclaw channels login --channel whatsapp --verbose

# 2. 扫描二维码

# 3. 配置允许的发送者
openclaw config set channels.whatsapp.allowFrom '["+15555550123"]'

# 4. 发送测试消息
openclaw message send --target +15555550123 --message "Hello!"

场景 2: 配置 Telegram Bot

# 1. 从 @BotFather 获取 bot token

# 2. 添加 Telegram 渠道
openclaw channels add --channel telegram --token "YOUR_BOT_TOKEN"

# 3. 配置 DM 策略
openclaw config set channels.telegram.dmPolicy "pairing"

# 4. 发送消息
openclaw message send --channel telegram --target @username --message "Hi"

场景 3: 设置多代理

# 1. 添加工作代理
openclaw agents add work --workspace ~/work-workspace

# 2. 添加个人代理
openclaw agents add personal --workspace ~/personal-workspace

# 3. 配置路由绑定
openclaw config set bindings '[
  { "agentId": "work", "match": { "channel": "telegram", "accountId": "work-bot" } },
  { "agentId": "personal", "match": { "channel": "whatsapp" } }
]'

场景 4: 设置定时任务

# 每小时备份
openclaw cron add --name backup --every 1h --system-event "Run backup"

# 每天早上 9 点提醒
openclaw cron add --name morning --at "09:00" --message "Good morning!"

# 查看任务
openclaw cron list

# 启用/禁用任务
openclaw cron enable <id>
openclaw cron disable <id>

场景 5: 配置心跳检查

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",        // 每 30 分钟
        target: "last",      // 发送到最后一个渠道
        directPolicy: "allow",
      },
    },
  },
}

在 workspace/HEARTBEAT.md 中配置检查项:

# HEARTBEAT.md

## 检查项

- 每 2 小时检查一次邮件
- 每天早上检查日历
- 每 4 小时检查天气

场景 6: 使用浏览器自动化

# 启动浏览器
openclaw browser start

# 打开网页
openclaw browser open https://example.com

# 截图
openclaw browser screenshot --full-page

# 点击元素
openclaw browser click "button[type=submit]"

# 输入文本
openclaw browser type "input[name=search]" "OpenClaw"

场景 7: 节点配对 (iOS/Android)

# 生成配对二维码
openclaw qr

# 查看待批准的配对请求
openclaw nodes pending

# 批准配对
openclaw nodes approve <requestId>

# 查看已配对节点
openclaw nodes list

# 使用节点拍照
openclaw nodes camera snap --node myphone --facing back

# 发送通知到节点
openclaw nodes notify --node myphone --title "Alert" --body "Check this"

故障排查

常见问题

1. 网关无法启动

# 检查配置
openclaw doctor

# 查看日志
openclaw logs --follow

# 验证配置文件
openclaw config validate

2. 渠道连接失败

# 检查渠道状态
openclaw channels status --probe

# 查看渠道日志
openclaw channels logs --channel telegram --lines 100

# 重新登录
openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp

3. 模型认证问题

# 检查模型状态
openclaw models status

# 添加认证
openclaw models auth add

# 扫描可用模型
openclaw models scan

4. 端口冲突

# 使用不同端口
openclaw gateway --port 18790

# 或强制杀死占用端口的进程
openclaw gateway --force

5. 配置验证失败

# 运行 doctor 自动修复
openclaw doctor --fix

# 或手动验证
openclaw config validate --json

日志位置

# 网关日志
# ~/.openclaw/logs/gateway.log

# 渠道日志
# ~/.openclaw/logs/channels.log

# 查看实时日志
openclaw logs --follow

# 查看最近 200 行
openclaw logs --limit 200

重置和清理

# 重置配置 (保留凭证和会话)
openclaw reset --scope config

# 重置配置和凭证
openclaw reset --scope config+creds+sessions

# 完全重置 (包括工作区)
openclaw reset --scope full

# 卸载服务
openclaw gateway uninstall

# 完全卸载
openclaw uninstall --all

获取帮助

# 查看命令帮助
openclaw --help
openclaw gateway --help
openclaw channels --help

# 查看文档
openclaw docs

# 在线文档
# https://docs.openclaw.ai

附录

常用环境变量

变量	说明
`OPENCLAW_HOME`	自定义 HOME 目录
`OPENCLAW_STATE_DIR`	自定义状态目录
`OPENCLAW_CONFIG_PATH`	自定义配置文件路径
`OPENCLAW_GATEWAY_TOKEN`	网关认证令牌
`OPENCLAW_GATEWAY_PASSWORD`	网关密码
`TELEGRAM_BOT_TOKEN`	Telegram Bot 令牌
`DISCORD_BOT_TOKEN`	Discord Bot 令牌
`OPENAI_API_KEY`	OpenAI API 密钥
`ANTHROPIC_API_KEY`	Anthropic API 密钥

快捷命令别名

# 添加到 ~/.bashrc 或 ~/.zshrc

alias oc='openclaw'
alias ocg='openclaw gateway'
alias ocs='openclaw status'
alias ocl='openclaw logs --follow'
alias ocd='openclaw dashboard'
alias ocm='openclaw message send'