OpenClaw

主题

API 参考 ​

OpenClaw 提供完整的 API 接口，方便开发者集成和扩展。

基础 API ​

会话管理 ​

创建会话 ​

http
POST /api/sessions
Content-Type: application/json

{
  "model": "claude-3-5-sonnet-20241022",
  "context": {
    "userId": "user-123"
  }
}

响应：

json
{
  "sessionId": "sess-abc123",
  "status": "created"
}

获取会话 ​

http
GET /api/sessions/:sessionId

删除会话 ​

http
DELETE /api/sessions/:sessionId

消息发送 ​

http
POST /api/sessions/:sessionId/messages
Content-Type: application/json

{
  "content": "帮我整理一下今天的会议记录",
  "attachments": [
    {
      "type": "file",
      "path": "/path/to/file.txt"
    }
  ]
}

响应：

json
{
  "messageId": "msg-xyz789",
  "response": {
    "content": "我已经整理好了...",
    "actions": [
      {
        "type": "file_created",
        "path": "/Documents/meeting-notes.md"
      }
    ]
  }
}

流式响应 ​

http
POST /api/sessions/:sessionId/messages/stream
Content-Type: application/json

{
  "content": "帮我写一段代码"
}

响应（Server-Sent Events）：

data: {"type": "text", "content": "我来帮你"}
data: {"type": "text", "content": "写一段"}
data: {"type": "code", "content": "console.log('Hello')"}
data: {"type": "done"}

技能 API ​

列出技能 ​

http
GET /api/skills

响应：

json
{
  "skills": [
    {
      "name": "github",
      "version": "1.2.0",
      "enabled": true
    }
  ]
}

执行技能 ​

http
POST /api/skills/:skillName/execute
Content-Type: application/json

{
  "action": "create-repo",
  "params": {
    "name": "my-new-repo",
    "private": true
  }
}

安装技能 ​

http
POST /api/skills/install
Content-Type: application/json

{
  "source": "clawhub",
  "name": "notion"
}

记忆 API ​

存储记忆 ​

http
POST /api/memory
Content-Type: application/json

{
  "key": "user-preference",
  "value": {
    "theme": "dark",
    "language": "zh-CN"
  },
  "metadata": {
    "category": "preferences"
  }
}

检索记忆 ​

http
GET /api/memory/search?q=preference&limit=10

响应：

json
{
  "results": [
    {
      "key": "user-preference",
      "value": { "theme": "dark" },
      "score": 0.95,
      "createdAt": "2026-03-01T00:00:00Z"
    }
  ]
}

删除记忆 ​

http
DELETE /api/memory/:key

文件 API ​

读取文件 ​

http
GET /api/files/read?path=/Documents/notes.md

写入文件 ​

http
POST /api/files/write
Content-Type: application/json

{
  "path": "/Documents/new-file.md",
  "content": "# Hello World"
}

列出目录 ​

http
GET /api/files/list?path=/Documents

搜索文件 ​

http
GET /api/files/search?pattern=*.md&path=/Documents

命令 API ​

执行命令 ​

http
POST /api/commands/execute
Content-Type: application/json

{
  "command": "ls -la",
  "cwd": "/Projects",
  "timeout": 30000
}

响应：

json
{
  "stdout": "total 32\ndrwxr-xr-x  ...",
  "stderr": "",
  "exitCode": 0
}

浏览器 API ​

打开页面 ​

http
POST /api/browser/open
Content-Type: application/json

{
  "url": "https://example.com"
}

截图 ​

http
GET /api/browser/screenshot?fullPage=true

执行脚本 ​

http
POST /api/browser/execute
Content-Type: application/json

{
  "script": "document.querySelector('#search').value = 'OpenClaw'"
}

Webhook API ​

配置 Webhook ​

http
POST /api/webhooks
Content-Type: application/json

{
  "event": "message.received",
  "url": "https://your-server.com/webhook",
  "secret": "your-webhook-secret"
}

Webhook 事件 ​

事件说明
message.received收到新消息
message.sent消息已发送
skill.executed技能已执行
task.completed任务已完成
error.occurred发生错误

任务调度 API ​

创建定时任务 ​

http
POST /api/tasks
Content-Type: application/json

{
  "name": "daily-report",
  "schedule": "0 9 * * *",
  "action": {
    "type": "skill",
    "name": "report-generator",
    "params": {}
  }
}

列出任务 ​

http
GET /api/tasks

删除任务 ​

http
DELETE /api/tasks/:taskId

WebSocket API ​

连接 ​

javascript
const ws = new WebSocket('ws://localhost:3000/ws')

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels: ['messages', 'tasks']
  }))
}

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log('Received:', data)
}

事件类型 ​

类型说明
message新消息
task.started任务开始
task.completed任务完成
error错误通知

SDK ​

JavaScript/TypeScript ​

bash
npm install openclaw-sdk
typescript
import { OpenClaw } from 'openclaw-sdk'

const client = new OpenClaw({
  apiKey: 'your-api-key',
  baseUrl: 'http://localhost:3000'
})

// 发送消息
const response = await client.messages.send({
  content: '你好'
})

// 流式响应
const stream = await client.messages.stream({
  content: '帮我写代码'
})

for await (const chunk of stream) {
  console.log(chunk.content)
}

Python ​

bash
pip install openclaw-sdk
python
from openclaw import OpenClaw

client = OpenClaw(
    api_key='your-api-key',
    base_url='http://localhost:3000'
)

# 发送消息
response = client.messages.send(
    content='你好'
)

# 流式响应
for chunk in client.messages.stream(
    content='帮我写代码'
):
    print(chunk.content)

错误处理 ​

所有 API 错误遵循统一格式：

json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "请求参数无效",
    "details": {
      "field": "content",
      "reason": "不能为空"
    }
  }
}

错误码 ​

错误码说明
INVALID_REQUEST请求参数无效
UNAUTHORIZED未授权
FORBIDDEN权限不足
NOT_FOUND资源不存在
RATE_LIMITED请求频率超限
INTERNAL_ERROR内部错误

速率限制 ​

API限制
消息发送100/分钟
技能执行50/分钟
文件操作200/分钟

超出限制返回：

json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "请求频率超限，请稍后重试",
    "retryAfter": 60
  }
}

下一步 ​

基于 MIT 许可发布

Copyright © 2026 OpenClaw 知识库