OpenClaw 用户使用手册

目录

1. 简介
2. 安装与配置
3. 快速入门
4. 通道配置
5. 代理系统
6. 工具使用
7. 技能系统
8. 安全配置
9. 高级功能
10. 故障排除

简介

OpenClaw 是一个跨平台的消息网关，用于连接 AI 代理与各种消息服务，如 WhatsApp、Telegram、Discord、iMessage 等。它提供了一个统一的接口来处理来自不同渠道的消息，并将其路由到 AI 代理进行处理。

主要特性

• 支持多平台消息服务（WhatsApp、Telegram、Discord、iMessage 等）
• AI 代理集成（内置 Pi 编码代理）
• 消息会话管理
• 安全访问控制
• 可扩展的工具和技能系统

安装与配置

系统要求

• Node.js 版本 ≥ 22
• pnpm（推荐，用于源码构建）

安装步骤

1. 安装 OpenClaw CLI

# 推荐方式：使用 curl 安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 或使用 npm
npm install -g openclaw@latest

# 或使用 pnpm
pnpm add -g openclaw@latest

2. 运行初始化向导

openclaw onboard --install-daemon

此命令将引导您完成：

• 模型/认证配置（推荐 OAuth）
• 网关设置
• 通道配置（WhatsApp/Telegram/Discord 等）
• 配对接入默认设置（安全 DM）
• 工作区引导 + 技能
• 可选的后台服务安装

3. 启动网关服务
   如果在向导中安装了服务，网关应该已经在运行：

openclaw gateway status

手动启动网关：

openclaw gateway --port 18789 --verbose

验证安装

openclaw status
openclaw health
openclaw security audit --deep

快速入门

第一次运行

1. 打开控制面板（最快聊天方式，无需通道设置）

openclaw dashboard

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

2. 配置通道
   使用 CLI 登录 WhatsApp：

openclaw channels login

扫描 WhatsApp → 设置 → 已连接的设备 中显示的二维码

3. 测试连接
   发送测试消息：

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

基本命令

# 查看状态
openclaw status

# 查看健康状况
openclaw health

# 查看当前配置
openclaw config get

# 查看日志
openclaw logs --follow

通道配置

WhatsApp 配置

基本配置

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": { "requireMention": true }
      },
      "sendReadReceipts": true
    }
  }
}

多账号配置

{
  "channels": {
    "whatsapp": {
      "accounts": {
        "default": {},
        "personal": {},
        "business": {}
      }
    }
  }
}

配对接入管理

• 未知发件人会收到配对代码
• 使用以下命令查看待处理请求：

openclaw pairing list whatsapp

• 批准配对：

openclaw pairing approve whatsapp <code>

Telegram 配置

基本配置

{
  "channels": {
    "telegram": {
      "botToken": "your-telegram-bot-token",
      "dmPolicy": "pairing",
      "allowFrom": ["tg:123456789"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

高级配置

{
  "channels": {
    "telegram": {
      "customCommands": [
        { "command": "backup", "description": "Git backup" },
        { "command": "generate", "description": "Create an image" }
      ],
      "historyLimit": 50,
      "streamMode": "partial"
    }
  }
}

Discord 配置

基本配置

{
  "channels": {
    "discord": {
      "token": "your-discord-bot-token",
      "dm": {
        "enabled": true,
        "policy": "pairing",
        "allowFrom": ["1234567890"]
      },
      "guilds": {
        "123456789012345678": {
          "slug": "friends-of-openclaw",
          "requireMention": false,
          "channels": {
            "general": { "allow": true },
            "help": {
              "allow": true,
              "requireMention": true
            }
          }
        }
      }
    }
  }
}

其他通道

iMessage（仅 macOS）

{
  "channels": {
    "imessage": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["+15555550123", "user@example.com"]
    }
  }
}

Signal

{
  "channels": {
    "signal": {
      "reactionNotifications": "own"
    }
  }
}

代理系统

默认代理配置

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallbacks": ["openai/gpt-4o"]
      },
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none"
      }
    }
  }
}

多代理配置

{
  "agents": {
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "sandbox": {
          "mode": "all",
          "scope": "agent",
          "workspaceAccess": "ro"
        },
        "tools": {
          "allow": ["read", "sessions_list", "sessions_history"],
          "deny": ["write", "exec", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "personal",
      "match": {
        "channel": "whatsapp",
        "accountId": "personal"
      }
    },
    {
      "agentId": "work",
      "match": {
        "channel": "whatsapp",
        "accountId": "business"
      }
    }
  ]
}

代理身份配置

{
  "agents": {
    "list": [
      {
        "id": "main",
        "identity": {
          "name": "Samantha",
          "theme": "helpful sloth",
          "emoji": "🦥",
          "avatar": "avatars/samantha.png"
        }
      }
    ]
  }
}

工具使用

核心工具介绍

1. exec - 执行命令

# 在工作区执行命令
openclaw exec --command "ls -la"

参数说明：

• command (必需) - 要执行的命令
• yieldMs - 自动后台运行超时时间
• background - 立即后台运行
• timeout - 超时时间（秒）
• host - 运行主机（sandbox | gateway | node）

2. web_search - 网络搜索

# 搜索网络
openclaw web_search --query "OpenClaw 架构"

需要配置 Brave API 密钥：

openclaw configure --section web

3. web_fetch - 获取网页内容

# 获取网页内容
openclaw web_fetch --url "https://docs.openclaw.ai/"

4. browser - 浏览器控制

# 启动浏览器
openclaw browser start --profile chrome

# 截图
openclaw browser screenshot --target https://example.com

# 获取页面快照
openclaw browser snapshot --target https://example.com

5. message - 发送消息

# 发送消息
openclaw message send --target +15555550123 --message "Hello"

工具策略配置

{
  "tools": {
    "profile": "coding",
    "allow": ["read", "write", "exec", "web_search"],
    "deny": ["gateway", "process"],
    "byProvider": {
      "openai/gpt-4o": {
        "allow": ["read", "write", "web_search"]
      }
    }
  }
}

技能系统

技能结构

技能存储在 SKILL.md 文件中，包含 YAML 前置元数据：

---
name: skill-name
description: Skill description
metadata:
 {
   "openclaw":
   {
     "requires": { "bins": ["binary"], "env": ["ENV_VAR"], "config": ["browser.enabled"] },
     "primaryEnv": "ENV_VAR",
     "os": ["darwin", "linux", "win32"],
     "emoji": "🦞",
     "homepage": "https://example.com"
   }
 }
---
# 技能说明和指令

技能位置

1. 工作区技能: <workspace>/skills（最高优先级）
2. 管理/本地技能: ~/.openclaw/skills
3. 捆绑技能: 随安装包分发（最低优先级）

安装第三方技能

# 从 ClawHub 安装技能
clawhub install skill-name

# 更新所有技能
clawhub update --all

技能配置

{
  "skills": {
    "entries": {
      "skill-name": {
        "enabled": true,
        "apiKey": "API_KEY_HERE",
        "env": {
          "ENV_VAR": "VALUE"
        },
        "config": {
          "custom_option": "value"
        }
      }
    }
  }
}

安全配置

网关安全

{
  "gateway": {
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your-long-random-token"
    }
  }
}

访问控制策略

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

安全审计

定期运行安全审计：

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix

沙箱配置

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none"
      }
    }
  }
}

高级功能

定时任务（Cron）

# 添加定时任务
openclaw cron add --job '{
  "name": "daily-report",
  "schedule": {
    "kind": "every",
    "everyMs": 86400000
  },
  "payload": {
    "kind": "systemEvent",
    "text": "Daily report"
  },
  "sessionTarget": "main"
}'

节点管理

# 查看节点状态
openclaw nodes status

# 描述节点
openclaw nodes describe --node node-id

# 在节点上运行命令
openclaw nodes run --node node-id -- echo "Hello"

会话管理

# 列出会话
openclaw sessions_list

# 查看会话历史
openclaw sessions_history --sessionKey session-key

# 向会话发送消息
openclaw sessions_send --sessionKey session-key --message "Hello"

子代理

# 启动子代理
openclaw sessions_spawn --task "Perform analysis" --label "analysis-task"

故障排除

常见问题

1. 网关无法启动

检查配置文件格式：

openclaw doctor

2. 通道连接失败

• 验证凭据是否正确
• 检查网络连接
• 查看日志：

openclaw logs --follow

3. 工具调用失败

• 检查工具策略配置
• 确认工具是否被允许
• 查看安全审计结果

4. 消息无法发送

• 验证目标地址格式
• 检查通道配置
• 确认授权状态

诊断命令

# 全面状态报告
openclaw status --all

# 健康检查
openclaw health

# 安全审计
openclaw security audit --deep

# 日志查看
openclaw logs --follow

# 配置验证
openclaw doctor

重启服务

# 停止网关
openclaw gateway stop

# 重启网关
openclaw gateway restart

# 检查服务状态
openclaw gateway status

最佳实践

安全最佳实践

1. 保持直接消息锁定（配对/允许列表）
2. 在群组中优先使用提及门控
3. 将敏感工具限制为可信代理
4. 定期运行安全审计

性能最佳实践

1. 合理配置沙箱设置
2. 设置适当的会话历史限制
3. 使用缓存和重试策略
4. 监控资源使用情况

维护最佳实践

1. 定期备份配置文件
2. 使用版本控制系统管理配置
3. 设置适当的日志保留策略
4. 定期更新到最新版本

附录

配置参考

完整的安全基线配置

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your-long-random-token"
    }
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main",
        "scope": "session",
        "workspaceAccess": "none"
      }
    }
  }
}

命令速查表

• openclaw status - 查看状态
• openclaw health - 健康检查
• openclaw logs --follow - 查看实时日志
• openclaw config get - 获取配置
• openclaw security audit - 安全审计
• openclaw gateway status - 网关状态
• openclaw pairing list <channel> - 查看配对请求
• openclaw pairing approve <channel> <code> - 批准配对