OpenClaw API 开发指南：用 REST API 和 Webhook 把 AI 助手集成到任意系统

curl http://localhost:18789/health
# 返回：{"status":"ok","version":"1.4.2"}

{
  "api": {
    "enabled": true,
    "token": "your-secret-api-token",
    "allowedOrigins": ["http://localhost:3000", "https://your-app.com"]
  }
}

curl -H "Authorization: Bearer your-secret-api-token"      http://localhost:18789/api/sessions

# 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 }
}

# 列出所有会话
GET /api/sessions

# 获取特定会话历史
GET /api/sessions/{sessionKey}/messages

# 清空会话历史
DELETE /api/sessions/{sessionKey}

# 创建新会话
POST /api/sessions
{
  "label": "我的开发会话",
  "model": "claude-sonnet-4-5"
}

# 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"
    }
  }'

## 事件处理

### deploy_complete 事件
收到后：
1. 发 Telegram 通知：版本 + 环境 + 操作人
2. 在 Notion 「发布记录」中创建条目
3. 更新 HEARTBEAT.md 中的部署状态

# 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_或_用户名"
  }'

// 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();
  }
};

// ~/.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" }
      }
    ]
  }
}

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)

# 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": {
    "rateLimit": {
      "requestsPerMinute": 60,
      "burstSize": 10
    }
  }
}