OpenClaw Gateway 暴露了一套 REST API，让你可以从任意外部系统调用 AI 助手、 触发工作流或接收事件通知。本文是完整的开发者参考。
API 基础信息
默认 Base URL：http://localhost:18789
认证方式：Bearer Token（在 openclaw.json 中配置）
内容类型：application/json
查看 Gateway 状态：
bash
curl http://localhost:18789/health
# 返回：{"status":"ok","version":"1.4.2"}认证配置
在 ~/.openclaw/openclaw.json 中设置 API Token：
json
{
"api": {
"enabled": true,
"token": "your-secret-api-token",
"allowedOrigins": ["http://localhost:3000", "https://your-app.com"]
}
}所有 API 请求需携带认证头：
bash
curl -H "Authorization: Bearer your-secret-api-token" http://localhost:18789/api/sessions核心 API 端点
发送消息给 AI
bash
# POST /api/message
curl -X POST http://localhost:18789/api/message -H "Authorization: Bearer your-token" -H "Content-Type: application/json" -d '{
"message": "帮我分析这段代码的性能瓶颈",
"sessionKey": "dev-session-001"
}'
# 响应：
{
"success": true,
"reply": "分析如下：...",
"sessionKey": "dev-session-001",
"usage": { "inputTokens": 245, "outputTokens": 512 }
}会话管理
bash
# 列出所有会话
GET /api/sessions
# 获取特定会话历史
GET /api/sessions/{sessionKey}/messages
# 清空会话历史
DELETE /api/sessions/{sessionKey}
# 创建新会话
POST /api/sessions
{
"label": "我的开发会话",
"model": "claude-sonnet-4-5"
}触发事件
bash
# POST /api/trigger —— 触发自定义事件
curl -X POST http://localhost:18789/api/trigger -H "Authorization: Bearer your-token" -H "Content-Type: application/json" -d '{
"event": "deploy_complete",
"data": {
"version": "v2.3.1",
"environment": "production",
"deployer": "CI/CD"
}
}'在 SOUL.md 中处理该事件：
markdown
## 事件处理
### deploy_complete 事件
收到后：
1. 发 Telegram 通知：版本 + 环境 + 操作人
2. 在 Notion 「发布记录」中创建条目
3. 更新 HEARTBEAT.md 中的部署状态主动推送通知
bash
# POST /api/notify —— 向指定频道发消息（不经过 AI 处理）
curl -X POST http://localhost:18789/api/notify -H "Authorization: Bearer your-token" -H "Content-Type: application/json" -d '{
"channel": "telegram",
"message": "🚨 服务器 CPU 超过 90%，请立即查看！",
"target": "chat_id_或_用户名"
}'流式响应（Streaming）
对于长回复，使用 Server-Sent Events（SSE）流式接收：
javascript
// Node.js 示例
const EventSource = require('eventsource');
const es = new EventSource(
'http://localhost:18789/api/message/stream?message=写一首诗',
{ headers: { 'Authorization': 'Bearer your-token' } }
);
es.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === 'text_delta') {
process.stdout.write(data.text);
} else if (data.type === 'end') {
console.log('
完成');
es.close();
}
};MCP（Model Context Protocol）集成
OpenClaw 支持作为 MCP Host，让 AI 访问 MCP 服务器提供的工具：
json
// ~/.openclaw/openclaw.json
{
"mcp": {
"servers": [
{
"name": "filesystem",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
},
{
"name": "github",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
}
]
}
}配置后，Claude 可以直接使用 MCP 工具：
你：帮我在 GitHub 上创建一个新 Issue，标题是「修复登录 Bug」
Claude：[调用 github MCP 工具] 已创建 Issue #45：修复登录 Bug
在应用中嵌入 OpenClaw
Python SDK 示例
python
import requests
class OpenClawClient:
def __init__(self, base_url="http://localhost:18789", token="your-token"):
self.base_url = base_url
self.headers = {"Authorization": f"Bearer {token}"}
def chat(self, message: str, session: str = "default") -> str:
resp = requests.post(
f"{self.base_url}/api/message",
headers=self.headers,
json={"message": message, "sessionKey": session}
)
return resp.json()["reply"]
def notify(self, message: str, channel: str = "telegram"):
requests.post(
f"{self.base_url}/api/notify",
headers=self.headers,
json={"channel": channel, "message": message}
)
# 使用
client = OpenClawClient()
reply = client.chat("分析这个错误：" + error_log)
print(reply)典型集成场景
python
# CI/CD 流水线集成：构建失败时 AI 自动分析
def on_build_failure(build_log: str):
client = OpenClawClient()
analysis = client.chat(
f"这是构建失败日志，分析根本原因并给出修复建议：
{build_log}",
session="ci-analysis"
)
client.notify(f"构建失败分析：
{analysis}")API 限流配置
防止外部系统滥用 API：
json
{
"api": {
"rateLimit": {
"requestsPerMinute": 60,
"burstSize": 10
}
}
}来源：OpenClaw 官方文档 - docs.openclaw.ai/gateway