RPC 适配器

RPC Adapter（远程过程调用适配器）是 OpenClaw Gateway 对外暴露的编程接口层。外部系统通过 RPC 协议与网关通信，实现消息发送、Agent 管理等操作。

协议概述

OpenClaw RPC 基于 HTTP + JSON 协议：

属性	说明
传输协议	HTTP/1.1 或 HTTP/2
数据格式	JSON
默认端口	18789
基础路径	/rpc
认证方式	Bearer Token

WebSocket 支持

对于需要实时推送的场景，RPC 也支持通过 WebSocket 通道进行双向通信。连接地址：ws://127.0.0.1:18789/rpc/ws

请求格式

{
  "jsonrpc": "2.0",
  "method": "agent.sendMessage",
  "params": {
    "agentName": "main",
    "channel": "web",
    "userId": "user-123",
    "message": "你好"
  },
  "id": "req-001"
}

字段	类型	说明
jsonrpc	string	协议版本，固定 "2.0"
method	string	调用方法名
params	object	方法参数
id	string	请求唯一标识

响应格式

成功响应

{
  "jsonrpc": "2.0",
  "result": {
    "messageId": "msg-456",
    "status": "delivered"
  },
  "id": "req-001"
}

错误响应

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid request",
    "data": { "detail": "Missing required field: agentName" }
  },
  "id": "req-001"
}

标准错误码

错误码	含义
-32700	Parse Error（JSON 解析失败）
-32600	Invalid Request（无效请求）
-32601	Method Not Found（方法不存在）
-32602	Invalid Params（参数无效）
-32603	Internal Error（内部错误）
-32000	Authentication Error（认证失败）

可用 RPC 方法

Agent 管理

方法	说明
agent.list	列出所有 Agent
agent.status	获取 Agent 状态
agent.reload	重载 Agent 配置
agent.sendMessage	向 Agent 发送消息

会话管理

方法	说明
session.list	列出会话
session.get	获取会话详情
session.compact	触发会话压缩
session.delete	删除会话

系统管理

方法	说明
system.health	健康检查
system.info	系统信息
system.reload	重载全局配置
usage.stats	用量统计

调用示例

cURL

curl -X POST http://127.0.0.1:18789/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "agent.list",
    "params": {},
    "id": "1"
  }'

Node.js

const response = await fetch('http://127.0.0.1:18789/rpc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'agent.list',
    params: {},
    id: '1'
  })
})
const data = await response.json()

Python

import requests

resp = requests.post(
    'http://127.0.0.1:18789/rpc',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'jsonrpc': '2.0',
        'method': 'agent.list',
        'params': {},
        'id': '1'
    }
)
print(resp.json())

身份认证

RPC 接口使用 Bearer Token 认证：

# openclaw.config.yaml
gateway:
  rpc:
    enabled: true
    auth:
      type: 'bearer'
      tokens:
        - name: 'admin'
          token: ${RPC_ADMIN_TOKEN}
          permissions: ['*']
        - name: 'readonly'
          token: ${RPC_READONLY_TOKEN}
          permissions: ['agent.list', 'session.list', 'system.health']

安全提示

生产环境中务必启用认证，不要暴露未认证的 RPC 端口到公网。