OpenClaw Gateway 命令与交互指南

WebSocket API 集成

Gateway 通过 WebSocket 暴露了超过 84 个 RPC 方法，适合构建自动化工作流或第三方集成。

连接与认证

建立连接时需携带协议版本、角色及认证信息。响应中会返回设备 Token 用于后续鉴权。

const WebSocket = require('ws');
const ws = new WebSocket('ws://localhost:18789');

ws.on('open', () => {
  // 发送连接请求
  ws.send(JSON.stringify({
    type: 'req', id: 'conn-1', method: 'connect',
    params: {
      minProtocol: 3, maxProtocol: 3,
      role: 'operator',
      auth: { token: process.env.OPENCLAW_GATEWAY_TOKEN }
    }
  }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data);
  if (msg.type === 'res' && msg.ok) {
    console.log('Connected:', msg.payload);
  }
});

核心功能模块

1. 系统状态与配置

获取运行时状态、系统信息及配置快照。

# 查询当前状态
openclaw gateway call status

# 获取完整配置（含哈希校验）
openclaw gateway call config.get --params '{}'

# 部分更新配置
openclaw gateway call config.patch --params '{ "raw": "agents:\n defaults:\n workspace: ~/.openclaw/workspace", "baseHash": "..." }'

2. Agent 调度与执行

Agent 是实际处理业务逻辑的单元。支持流式调用工具，如 Shell 执行或文件操作。

# 调用工具（流式响应）
openclaw gateway call agent.invoke --params '{ "agentId": "main", "tool": "shell.exec", "args": { "command": "ls -la ~" } }' --expect-final

# 列出所有 Agent
openclaw gateway call agents.list

# 查看 Agent 详细信息
openclaw gateway call agents.describe --params '{ "id": "main" }'

3. 会话与渠道管理

管理聊天会话、渠道连接状态及节点资源。

# 列出活动会话
openclaw gateway call sessions.list --params '{ "filter": "active" }'

# 渠道状态检查
openclaw gateway call channels.status --params '{ "platform": "whatsapp" }'

# 节点列表（Peekaboo 等）
openclaw gateway call nodes.list

聊天斜线命令

在支持的聊天平台（WhatsApp、Telegram 等）中，用户可直接使用斜线命令与 Agent 交互。

高级交互

对于特定任务，可使用子智能体或限制执行范围。

# 管理子智能体
/subagents list
/subagents stop <uuid>
/subagents info <uuid>

# 限制 Agent 访问目录
/agent focus ~/project
/agent unfocus

# 快捷执行 Shell 命令
/shell ls -la ~ --background
/file read ~/data.csv
/web search "AI news 2026"

权限与安全

Gateway 采用基于角色的访问控制（RBAC），确保操作安全。

角色定义

• operator: 本地控制客户端，拥有完全访问权限。
• node: 执行节点（如 Peekaboo），受限于声明的能力。
• adapter: 聊天平台适配器，仅负责消息收发。

认证配置

推荐使用环境变量或配置文件设置令牌。

# 方式 1：环境变量
export OPENCLAW_GATEWAY_TOKEN="my-secret-token"

# 方式 2：CLI 指定
openclaw gateway call status --token "my-secret-token"

# 方式 3：配置文件 (~/.openclaw/openclaw.json)
{
  "gateway": {
    "auth": { "token": "my-secret-token" }
  }
}

首次连接新设备时，Gateway 会要求批准配对码，授权后设备将获得 deviceToken 用于后续免密连接。

事件类型

Gateway 通过事件推送实时更新，常见事件包括：

• chat.*: 消息收发、编辑、删除及在线状态。
• agent.*: 思考过程、工具调用、错误及完成通知。
• gateway.*: 就绪、重启、配置变更及节点连接状态。

典型工作流

一个完整的端到端任务通常包含以下步骤：

1. 用户在聊天平台发送消息。
2. Adapter 接收并转换为标准格式路由至 Gateway。
3. Agent 分析意图，选择合适工具（如 Shell、Web Search）。
4. Gateway 转发请求至 Node 或本地执行。
5. 结果回传 Agent 生成回复，最终送达用户。

注意：所有命令和 API 调用均需有效的 Gateway 令牌。若未配置认证，请确保网络环境安全。