OpenClaw API集成指南

概述

OpenClaw提供了完整的RESTful API，方便开发者进行集成和自动化操作。

快速开始

认证方式

API使用Token认证机制：

# 登录获取token
curl -X POST http://localhost:8181/api/v1/login \
  -d "username=your_username" \
  -d "password=your_password"

基础请求

所有API请求需要在Header中携带Authorization：

curl -H "Authorization: your_token_here" \
  http://localhost:8181/api/ai/books

核心接口

1. 获取书籍列表

接口: GET /api/ai/books

响应示例:

{
  "message": "操作成功",
  "data": {
    "books": [
      {
        "book_id": 1,
        "book_name": "示例书籍",
        "identify": "demo-book"
      }
    ],
    "count": 1
  }
}

2. 获取文档列表

接口: GET /api/ai/books/:book_id/documents

参数:

• book_id: 书籍ID（路径参数）

3. 保存文档

接口: POST /api/ai/save

参数:

示例代码:

import requests
url = "http://localhost:8181/api/ai/save"
headers = {
    "Authorization": "your_token_here"
}
data = {
    "book_identify": "openclaw",
    "doc_name": "新文档",
    "markdown": "# 标题\n\n这是内容",
    "auto_publish": True
}
response = requests.post(url, headers=headers, data=data)
print(response.json())

4. 发布书籍

接口: POST /api/ai/publish

参数:

• book_identify: 书籍标识

高级特性

自动添加目录

API会自动为文档添加 [TOC] 标记，确保目录正确显示。

自动渲染

设置 auto_publish=true 时，系统会：

1. 保存Markdown内容
2. 自动渲染为HTML
3. 发布到前端可见
4. 生成文档目录

错误处理

常见错误码

错误响应格式

{
  "message": "错误描述",
  "data": null
}

最佳实践

1. 批量操作

处理大量文档时，建议：

• 使用队列机制控制并发
• 每次请求间隔100ms以上
• 监控API响应时间

2. 内容格式

Markdown内容建议：

• 使用标准Markdown语法
• 代码块指定语言类型
• 图片使用绝对路径
• 表格保持格式规范

3. 错误重试

网络异常时建议：

import time
def save_with_retry(data, max_retries=3):
    for i in range(max_retries):
        try:
            response = requests.post(url, data=data)
            if response.status_code == 200:
                return response.json()
        except Exception as e:
            if i == max_retries - 1:
                raise e
            time.sleep(2 ** i)  # 指数退避

安全建议

1. Token管理

   • 定期更换token
   • 不要在代码中硬编码
   • 使用环境变量存储

2. 访问控制

   • 只授予必要的权限
   • 定期审查API访问日志
   • 限制IP白名单

3. 数据验证

   • 验证输入内容长度
   • 过滤特殊字符
   • 防止XSS注入

性能优化

缓存策略

from functools import lru_cache
@lru_cache(maxsize=100)
def get_book_list(token):
    # 缓存书籍列表，减少API调用
    return requests.get(url, headers={"Authorization": token})

连接池

session = requests.Session()
adapter = requests.adapters.HTTPAdapter(pool_connections=10, pool_maxsize=20)
session.mount('http://', adapter)

常见问题

Q: 文档保存成功但前端不显示？
A: 确保 auto_publish=true 且有足够的权限。

Q: 如何批量导入文档？
A: 循环调用 /api/ai/save 接口，注意控制并发数。

Q: Token过期如何处理？
A: 收到401错误时重新登录获取新token。

Q: 支持文档更新吗？
A: 是的，使用相同的doc_name会更新现有文档。

文档版本: v1.0
更新时间: 2026-02-02
技术支持: support@openclaw.dev