OpenClaw API 接口完整文档
OpenClaw提供了完善的RESTful API接口，支持广告位管理、广告投放、数据查询等全功能操作，方便开发者将OpenClaw能力集成到自有系统中。
一、API认证方式
OpenClaw API使用Bearer Token认证：
// 获取API Token
POST /api/v1/auth/token
Content-Type: application/json
{
"username": "your_username",
"password": "your_password"
}
// 响应
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"expires_in": 86400,
"token_type": "Bearer"
}
// 使用Token调用接口
GET /api/v1/zones
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
二、广告位管理接口
// 获取广告位列表
GET /api/v1/zones?page=1&per_page=20&status=active
// 创建广告位
POST /api/v1/zones
{
"name": "首页顶部横幅",
"size": "320x50",
"type": "banner",
"floor_price": 1.50,
"allowed_ad_types": ["image", "html5"]
}
// 更新广告位
PUT /api/v1/zones/{zone_id}
// 删除广告位（软删除）
DELETE /api/v1/zones/{zone_id}
三、广告请求接口
核心广告请求接口，用于获取展示广告：
// 请求广告
GET /api/v1/ad/request
?zone_id=12345
&app_id=com.example.app
&user_id=user_hash_value // 用户标识的Hash值，保护隐私
&ip=123.123.123.123
&ua=Mozilla/5.0...
&country=CN
&os=android
&os_version=12
&device_type=phone
// 响应格式
{
"status": "success",
"ad": {
"ad_id": 98765,
"type": "banner",
"width": 320,
"height": 50,
"html": "广告内容HTML",
"click_url": "https://track.openclaw.io/click/...",
"impression_url": "https://track.openclaw.io/imp/...",
"extra": {}
}
}
四、统计数据接口
// 获取广告数据报告
GET /api/v1/reports/summary
?start_date=2025-01-01
&end_date=2025-01-31
&group_by=zone_id,date
&metrics=impressions,clicks,ctr,revenue,ecpm
// 实时数据接口（5分钟延迟）
GET /api/v1/reports/realtime?zone_id=12345
// 导出报表（异步）
POST /api/v1/reports/export
{
"report_type": "daily_summary",
"date_range": {"start": "2025-01-01", "end": "2025-01-31"},
"format": "xlsx"
}
五、Webhook事件推送
OpenClaw支持通过Webhook主动推送事件到你的服务器：
// 配置Webhook
POST /api/v1/webhooks
{
"url": "https://your-server.com/openclaw-webhook",
"events": ["ad.impression", "ad.click", "zone.fill_rate_low"],
"secret": "your_webhook_secret" // 用于验证请求合法性
}
// Webhook推送格式
POST https://your-server.com/openclaw-webhook
X-OpenClaw-Signature: sha256=...
{
"event": "ad.click",
"timestamp": 1735689600,
"data": {
"ad_id": 98765,
"zone_id": 12345,
"click_id": "click_xxx",
"revenue": 0.05
}
}
六、API限流规则
为保证系统稳定，API接口设有限流策略：普通API（报表查询等）：100次/分钟；广告请求API：10000次/秒；认证接口：10次/分钟；批量操作接口：10次/分钟。超出限流后返回HTTP 429状态码，建议实现指数退避重试。
七、SDK集成
OpenClaw提供多语言SDK简化集成：PHP SDK（Composer安装：composer require openclaw/php-sdk）；Python SDK（pip install openclaw-python）；Node.js SDK（npm install openclaw）；Java SDK（Maven依赖）。
八、总结
OpenClaw API遵循RESTful设计规范，接口文档完整，SDK支持多语言。建议先在沙盒环境充分测试API集成，确认功能正确后再切换到生产环境。API密钥需妥善保管，定期轮换，避免泄露造成安全风险。