OpenClaw 使用说明文档

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. 设置与配置

2. 网关管理

3. 渠道管理

4. 消息管理

5. 模型管理

6. 代理管理

7. 会话管理

8. 节点管理

9. 浏览器控制

10. 定时任务

11. 工具与实用程序

配置文件说明

配置文件位置

主配置文件: ~/.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}"
      }
    }
  },
}

环境变量来源:

1. 父进程环境变量
2. 当前目录的 .env 文件
3. ~/.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      # 执行批准

重要文件说明

环境变量覆盖

# 自定义状态目录
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

附录

常用环境变量

快捷命令别名

# 添加到 ~/.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'

相关链接

• 官方网站: https://openclaw.ai
• 文档: https://docs.openclaw.ai
• GitHub: https://github.com/openclaw/openclaw
• Discord 社区: https://discord.com/invite/clawd
• 技能市场: https://clawhub.com