OpenClaw API参考文档
# OpenClaw API参考文档
本API文档详细介绍了OpenClaw系统提供的RESTful API接口，包括端点、请求参数、响应格式和使用示例。
# 1. API概述
# 基础信息
- 基础URL:
https://api.openclaw.com/v1 - 认证方式: Bearer Token
- 数据格式: JSON
- 版本控制: 语义化版本控制
# 认证
所有API请求都需要在请求头中包含认证信息：
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
1
2
2
# 2. 核心API端点
# 2.1 任务管理
# 创建任务
POST /tasks
1
请求参数:
{
"name": "string",
"type": "string",
"parameters": "object",
"priority": "integer",
"timeout": "integer"
}
1
2
3
4
5
6
7
2
3
4
5
6
7
响应示例:
{
"id": "task_12345",
"name": "示例任务",
"status": "pending",
"created_at": "2026-03-12T10:30:00Z",
"updated_at": "2026-03-12T10:30:00Z"
}
1
2
3
4
5
6
7
2
3
4
5
6
7
# 获取任务状态
GET /tasks/{task_id}
1
响应示例:
{
"id": "task_12345",
"name": "示例任务",
"status": "running",
"progress": 75,
"result": null,
"error": null,
"created_at": "2026-03-12T10:30:00Z",
"updated_at": "2026-03-12T10:35:00Z"
}
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
# 取消任务
DELETE /tasks/{task_id}
1
# 2.2 会话管理
# 创建会话
POST /sessions
1
请求参数:
{
"agent_id": "string",
"context": "object",
"ttl": "integer"
}
1
2
3
4
5
2
3
4
5
响应示例:
{
"session_id": "session_67890",
"agent_id": "qwencode",
"created_at": "2026-03-12T10:30:00Z",
"expires_at": "2026-03-12T11:30:00Z"
}
1
2
3
4
5
6
2
3
4
5
6
# 会话对话
POST /sessions/{session_id}/messages
1
请求参数:
{
"content": "string",
"type": "string"
}
1
2
3
4
2
3
4
响应示例:
{
"message_id": "msg_11111",
"content": "回复内容",
"role": "assistant",
"timestamp": "2026-03-12T10:30:00Z"
}
1
2
3
4
5
6
2
3
4
5
6
# 2.3 工具管理
# 获取可用工具
GET /tools
1
响应示例:
[
{
"name": "file-processor",
"description": "文件处理工具",
"version": "1.0.0",
"input_schema": {},
"output_schema": {}
}
]
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# 执行工具
POST /tools/{tool_name}/execute
1
请求参数:
{
"parameters": "object"
}
1
2
3
2
3
响应示例:
{
"result": "执行结果",
"metadata": {
"execution_time": 123,
"memory_used": "2.5MB"
}
}
1
2
3
4
5
6
7
2
3
4
5
6
7
# 3. 错误响应格式
所有API错误都会返回标准的JSON格式错误响应：
{
"error": {
"code": "ERROR_CODE",
"message": "错误描述信息",
"details": "详细错误信息"
}
}
1
2
3
4
5
6
7
2
3
4
5
6
7
# 常见错误码
INVALID_REQUEST: 请求参数无效UNAUTHORIZED: 认证失败FORBIDDEN: 权限不足NOT_FOUND: 资源不存在INTERNAL_ERROR: 服务器内部错误
# 4. 状态码
200 OK: 请求成功201 Created: 资源创建成功400 Bad Request: 请求参数错误401 Unauthorized: 认证失败403 Forbidden: 权限不足404 Not Found: 资源不存在429 Too Many Requests: 请求过于频繁500 Internal Server Error: 服务器错误
# 5. 速率限制
API请求受到速率限制：
- 默认限制: 1000次/小时
- 高级账户: 10000次/小时
- 企业账户: 100000次/小时
超过限制时会返回 429 Too Many Requests 状态码。
# 6. 使用示例
# Python客户端示例
import requests
# 创建任务
response = requests.post(
'https://api.openclaw.com/v1/tasks',
headers={
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
json={
'name': '数据处理任务',
'type': 'data-processing',
'parameters': {'input_file': 'data.csv'}
}
)
task_id = response.json()['id']
print(f'任务创建成功: {task_id}')
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# JavaScript客户端示例
// 获取任务状态
const response = await fetch('https://api.openclaw.com/v1/tasks/task_12345', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
}
});
const task = await response.json();
console.log(`任务状态: ${task.status}`);
1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
# 7. 版本管理
API采用语义化版本控制：
- v1.x.x: 稳定版本，向后兼容
- v2.x.x: 可能包含不兼容的更改
- v1.0.0: 初始稳定版本
# 8. 安全注意事项
- HTTPS: 所有API请求必须通过HTTPS传输
- Token管理: API令牌应安全存储，不要硬编码
- 输入验证: 服务端会对所有输入进行验证
- 速率限制: 避免恶意请求影响服务稳定性
通过本API文档，开发者可以快速上手OpenClaw系统，实现各种自动化任务和智能代理功能。
上次更新: 3/18/2026