OpenClaw私域运营 - API接口文档

📋 基础信息

API版本

v1

基础URL

/api/v1

认证方式

JWT Bearer

数据格式

JSON

响应格式

展开/收起成功响应

{
  "success": true,
  "data": {},
  "message": "success",
  "timestamp": "2026-03-23T10:00:00Z",
  "request_id": "req_1234567890"
}

🔐 认证授权接口

POST /auth/register 用户注册

参数	类型	必填	说明
username	string	✅	3-20字符
email	string	✅	邮箱格式
password	string	✅	8-32字符
phone	string	否	手机号
captcha	string	✅	验证码

展开/收起响应示例

{
  "success": true,
  "data": {
    "user_id": "uuid",
    "username": "user123",
    "access_token": "eyJhbGci...",
    "refresh_token": "eyJhbGci...",
    "expires_in": 2592000
  }
}

POST /auth/login 用户登录

参数	类型	必填	说明
username	string	✅	用户名
password	string	✅	密码
captcha	string	✅	验证码

展开/收起响应示例

{
  "success": true,
  "data": {
    "user_id": "uuid",
    "access_token": "eyJhbGci...",
    "profile": { "nickname": "用户昵称", "tags": ["新手","开发者"] }
  }
}

POST /auth/openclaw/login OpenClaw第三方登录

参数	类型	必填	说明
auth_code	string	✅	OpenClaw授权码
state	string	✅	防CSRF令牌

POST /auth/refresh 刷新Token

参数	类型	必填	说明
refresh_token	string	✅	刷新令牌

POST /auth/logout 退出登录

需要 Authorization: Bearer <token> 请求头

👤 用户管理接口

GET /users/profile 获取用户信息

需要 Authorization: Bearer <token>

展开/收起响应示例

{
  "success": true,
  "data": {
    "user_id": "uuid", "username": "user123",
    "avatar": "https://cdn.example.com/avatar.jpg",
    "nickname": "昵称", "tags": ["开发者","高级用户"],
    "statistics": { "login_count": 150, "content_consumed": 45 }
  }
}

PUT /users/profile 更新用户信息

参数	类型	必填	说明
nickname	string	否	2-20字符
bio	string	否	最大500字符
avatar	string	否	URL地址
tags	string[]	否	标签数组

GET /users/profile/avatar 获取用户画像

查询参数: type=basic|advanced|premium

PUT /users/profile/tags 更新用户标签

参数	类型	必填	说明
tags	string[]	✅	标签数组
action	string	✅	add/remove/replace

📚 内容运营接口

GET /contents 获取内容列表

参数	类型	必填	说明
page	number	否	默认1
limit	number	否	默认20, 最大50
category	string	否	分类
content_type	string	否	article/video/course
sort	string	否	popular/latest/recommended

GET /contents/{content_id} 获取内容详情

返回完整内容、章节、资源、作者信息、统计数据、相关推荐

POST /contents 创建内容

参数	类型	必填	说明
title	string	✅	1-200字符
content_type	string	✅	article/video/course
category_id	uuid	✅	分类ID
description	string	✅	1-500字符
content	object	✅	内容数据

POST /contents/{id}/favorite 收藏内容

需要 Authorization: Bearer <token>

POST /contents/{id}/like 点赞内容

需要 Authorization: Bearer <token>

🎯 活动管理接口

GET /events 获取活动列表

参数	类型	必填	说明
page	number	否	默认1
status	string	否	active/upcoming/completed
type	string	否	challenge/contest/webinar

GET /events/{event_id} 获取活动详情

返回活动详情、任务列表、FAQ、奖品、参与统计、排名

POST /events/{id}/register 报名活动

参数	类型	必填	说明
team_name	string	否	团队名称
member_info	object[]	否	成员列表

POST /events/{id}/tasks/{task_id}/submit 提交任务

参数	类型	必填	说明
evidence	string	否	证据URL
notes	string	否	备注
files	string[]	否	文件URL

📊 数据分析接口

GET /analytics/behaviors 用户行为数据

参数	类型	必填	说明
start_date	string	否	YYYY-MM-DD
end_date	string	否	YYYY-MM-DD
metric	string	否	指标类型
granularity	string	否	daily/weekly/monthly

GET /analytics/learning-progress 学习进度数据

返回课程完成率、学习时长、连续学习天数、进度趋势

GET /analytics/events/{id}/performance 活动效果数据

返回参与统计、任务完成率、用户参与度、时间序列数据

🔔 通知服务接口

GET /notifications 获取通知列表

参数	类型	必填	说明
page	number	否	默认1
type	string	否	system/content/activity
read_status	string	否	all/unread/read

PUT /notifications/{id}/read 标记已读

返回未读总数

GET /notifications/unread-count 未读数量

按类型返回未读数量统计

💬 社交互动接口

GET /comments 获取评论列表

参数	类型	必填	说明
content_id	string	否	内容ID
page	number	否	默认1
sort	string	否	latest/popular

POST /comments 发表评论

参数	类型	必填	说明
content_id	string	✅	内容ID
content	string	✅	1-1000字符
reply_to_id	string	否	回复的评论ID

POST /users/{id}/follow 关注用户

需要 Authorization: Bearer <token>

🔗 OpenClaw集成接口

GET /openclaw/user/{user_id} 获取OC用户信息

返回OC用户信息、权限、项目列表、使用统计

POST /openclaw/sync/projects 同步OC项目数据

参数	类型	必填	说明
force_sync	boolean	否	是否强制同步

GET /openclaw/recommendations OC推荐内容

参数	类型	必填	说明
limit	number	否	默认10
type	string	否	projects/users/content

⚙️ 系统管理接口

GET /health 健康检查

返回数据库、Redis、存储、API各组件健康状态

GET /config 系统配置

返回站点名称、功能开关、维护模式等系统配置

POST /upload/file 上传文件

Content-Type: multipart/form-data

参数	类型	必填	说明
file	file	✅	文件数据
type	string	否	avatar/content/evidence

🚨 错误码说明

错误码	说明	HTTP状态码
SUCCESS	请求成功	200
INVALID_REQUEST	请求参数错误	400
UNAUTHORIZED	未授权	401
FORBIDDEN	访问被拒绝	403
NOT_FOUND	资源不存在	404
RATE_LIMITED	请求频率超限	429
INTERNAL_ERROR	服务器内部错误	500
SERVICE_UNAVAILABLE	服务不可用	503

🔌 API接口文档

响应格式