OpenClaw（前身为Clawdbot/Moltbot）核心是一个自托管的消息网关 + AI代理运行时，它的“API”主要体现在两个层面：
官方文档（https://docs.openclaw.ai/）中，API部分主要集中在**Gateway API（端口默认18789）和插件开发SDK**。本文基于官方仓库（github.com/openclaw/openclaw）、docs.openclaw.ai及社区实践，提供最实用的API使用教程与代码示例。
Gateway默认监听 **http://localhost:18789**（可通过`openclaw gateway --port xxxx`修改），暴露以下主要接口：
| 接口类型 | 路径/方式 | 主要功能 | 认证方式 |
|---|---|---|---|
| WebSocket | ws://localhost:18789/ws | 实时双向通信（发送用户消息、接收Agent回复、状态推送） | Bearer Token 或 Session ID |
| HTTP POST | /api/v1/messages | 发送单条消息（类似REST方式触发Agent） | API Key 或 Bearer Token |
| HTTP GET | /api/v1/status | 查看Gateway/Agent运行状态 | 无（或配置后需Token） |
| HTTP POST | /api/v1/agents/{agentId}/invoke | 直接调用指定Agent（绕过聊天渠道） | Bearer Token |
| HTTP GET | /api/v1/channels | 列出已配置渠道及状态 | Bearer Token |
获取API访问凭证（Token） 大多数接口需要认证。启动Gateway后，在终端运行：
网站资讯
关于我们openclaw token create --name "my-dev-client" --expires-in 30d会输出类似：
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...保存这个Token，后续请求都带在Header：Authorization: Bearer <token>
Node.js 示例（使用ws库）
// npm install ws
const WebSocket = require('ws');
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // 你的Bearer Token
const ws = new WebSocket('ws://localhost:18789/ws', {
headers: { Authorization: `Bearer ${token}` }
});
ws.on('open', () => {
console.log('已连接到OpenClaw Gateway');
// 发送消息给默认Agent（或指定sessionId/agentId）
ws.send(JSON.stringify({
type: 'message',
content: '帮我写一个Python函数计算斐波那契数列第n项（使用记忆化）',
channel: 'api', // 或你的自定义channel id
metadata: { userId: 'dev-user-001' }
}));
});
ws.on('message', (data) => {
const msg = JSON.parse(data);
console.log('收到回复：', msg.content);
// msg 结构示例：
// {
// type: 'response' | 'tool_call' | 'status' | 'error',
// content: string,
// agentId: string,
// sessionId: string,
// timestamp: number
// }
});
ws.on('close', () => console.log('连接断开'));
ws.on('error', (err) => console.error('WebSocket错误:', err));Python 示例（使用websocket-client）
# pip install websocket-client
import websocket
import json
token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
ws = websocket.WebSocketApp(
"ws://localhost:18789/ws",
header=[f"Authorization: Bearer {token}"],
on_message=lambda ws, msg: print("收到:", json.loads(msg)["content"]),
on_open=lambda ws: ws.send(json.dumps({
"type": "message",
"content": "给我分析一下今天的Hacker News前5条热门",
"channel": "api"
}))
)
ws.run_forever()cURL 示例
curl -X POST http://localhost:18789/api/v1/messages \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json" \
-d '{
"content": "自动在~/projects/my-repo创建新分支feature/api-integration，写一个Express中间件记录请求日志，然后commit并push",
"agentId": "dev-coder", // 可选，指定Agent
"sessionId": "cron-job-20260306" // 可选，自定义会话追踪
}'返回示例（同步等待完成时）：
{
"status": "completed",
"finalReply": "已完成：分支创建、代码写入、commit & push成功。PR链接：https://github.com/xxx/pull/123",
"toolCalls": [...],
"durationMs": 28450
}OpenClaw所有聊天渠道（Telegram/WhatsApp等）都是基于插件SDK实现的。你可以开发自己的Channel来接入企业微信、钉钉、自定义WebHook、甚至你的App内聊天框。
步骤概要（详见 https://docs.openclaw.ai/plugins/channel-sdk 或 github.com/openclaw/openclaw/tree/main/packages/plugin-sdk）：
创建插件项目：
npx create-openclaw-plugin my-custom-channel实现核心接口（src/index.ts）：
import { ChannelPlugin, Message } from '@openclaw/plugin-sdk';
export default class MyCustomChannel implements ChannelPlugin {
async sendMessage(to: string, msg: Message): Promise<void> {
// 实现发送逻辑，例如调用你的API
await fetch('https://your-app/api/send', {
method: 'POST',
body: JSON.stringify({ to, text: msg.content })
});
}
// 接收外部消息 → 调用 onMessage 推给Gateway
// 通常在构造函数中启动WebHook / 长轮询
}打包 & 安装：
npm run build
openclaw channels install ./dist/my-custom-channel.plugin在onboarding或config中启用你的channel。
Skill本质是预设的Prompt模板 + Tool定义，Tool是可执行函数。
快速创建Skill示例（JSON格式，放在~/openclaw/skills/）：
{
"slug": "auto-deploy-vercel",
"name": "一键Vercel部署",
"description": "自动部署当前项目到Vercel预览环境",
"prompt": "你现在是Vercel部署专家。步骤：1. 确认git状态 2. push main 3. 用Vercel CLI创建preview部署 4. 返回预览链接",
"tools": [
{
"name": "run_vercel_deploy",
"description": "执行vercel deploy --prebuilt",
"parameters": { "type": "object", "properties": {} }
}
]
}然后在聊天中直接调用：@auto-deploy-vercel 部署我的Next.js项目
通过Gateway的WebSocket/REST API，你可以：
更多细节参考：
