🔌 API 开发文档

基于 OpenClaw + Claude Code 的端到端研发自动化系统 - RESTful API 接口规范

API 版本：v2.0 | OpenAPI 3.0 规范 | 最后更新：2026 年 3 月 14 日

API 概览

基础信息

本 API 文档描述了基于 OpenClaw + Claude Code 的端到端研发自动化系统的所有 RESTful 接口。所有 API 遵循 OpenAPI 3.0 规范，采用 JSON 作为数据交换格式。

属性 值
基础 URL https://api.openclaw-cocode.system/v2
认证方式 JWT Bearer Token / OAuth 2.0
数据格式 application/json
字符编码 UTF-8
API 版本 v2.0（当前稳定版）

HTTP 方法语义

方法 描述 幂等性
GET 获取资源或资源列表 是
POST 创建新资源或执行操作 否
PUT 全量更新资源 是
DELETE 删除资源 是
PATCH 部分更新资源 否
💡 快速开始：
  1. 获取访问令牌（见认证授权章节）
  2. 在请求头中添加 Authorization: Bearer <token>
  3. 发送 HTTP 请求并处理响应

认证授权

JWT Bearer Token 认证

系统采用 JWT（JSON Web Token）进行身份验证。所有受保护的 API 端点都需要在请求头中提供有效的 JWT Token。

1

凭证交换

使用 API Key 或用户名密码换取 access_token

→
2

Token 存储

客户端安全存储 access_token 和 refresh_token

→
3

携带 Token

在 Authorization 头中携带 Bearer Token

→
4

Token 刷新

access_token 过期时使用 refresh_token 刷新

获取访问令牌

POST /auth/token

使用 API 凭证获取访问令牌

请求参数

参数名 类型 必填 描述
grant_type string 必填 授权类型：client_credentials 或 password
client_id string 必填 客户端 ID（API Key）
client_secret string 必填 客户端密钥
username string 可选 用户名（仅 password 模式）
password string 可选 密码（仅 password 模式）

请求示例

curl -X POST https://api.openclaw-cocode.system/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

成功响应（200 OK）

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "scope": "read write admin",
  "issued_at": "2026-03-14T10:30:00Z"
}

刷新访问令牌

POST /auth/refresh

使用 refresh_token 获取新的 access_token

请求参数

参数名 类型 必填 描述
refresh_token string 必填 之前获取的 refresh_token

请求示例

curl -X POST https://api.openclaw-cocode.system/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
  }'

权限模型

系统采用 RBAC（Role-Based Access Control）权限模型，定义了以下角色和权限：

角色 权限范围 适用场景
admin 所有 API 的完全访问权限 系统管理员
product_manager PRD、需求、项目管理的读写权限 产品经理
architect 技术方案、架构设计的读写权限 架构师
developer 代码、任务、测试的读写权限 开发工程师
tester 测试用例、测试报告的读写权限 测试工程师
devops 部署、流水线、监控的读写权限 DevOps 工程师
viewer 所有资源的只读权限 观察员/审计员
⚠️ 安全提示：
  • 永远不要在客户端代码中硬编码 client_secret
  • access_token 有效期建议设置为 1 小时
  • refresh_token 应安全存储，建议有效期 7-30 天
  • 所有 API 通信必须使用 HTTPS 加密
  • 定期轮换 API Key 和客户端凭证

用户管理 API

用户管理相关接口，包括用户 CRUD 操作、角色分配、权限管理等。

获取用户列表

GET /users

获取系统用户列表，支持分页、筛选和排序

查询参数

参数名 类型 必填 默认值 描述
page integer 可选 1 页码（从 1 开始）
pageSize integer 可选 20 每页数量（最大 100）
role string 可选 - 按角色筛选
status string 可选 - 按状态筛选：active, inactive, suspended
search string 可选 - 搜索关键词（匹配用户名、邮箱、姓名）
sortBy string 可选 createdAt 排序字段
sortOrder string 可选 desc 排序方向：asc, desc

请求示例

curl -X GET "https://api.openclaw-cocode.system/v2/users?page=1&pageSize=20&role=developer" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

成功响应（200 OK）

{
  "data": [
    {
      "id": "usr_abc123def456",
      "username": "zhangsan",
      "email": "zhangsan@example.com",
      "fullName": "张三",
      "role": "developer",
      "status": "active",
      "avatar": "https://cdn.example.com/avatars/usr_abc123def456.jpg",
      "department": "研发中心",
      "createdAt": "2026-01-15T08:30:00Z",
      "lastLoginAt": "2026-03-14T09:15:00Z"
    },
    {
      "id": "usr_xyz789ghi012",
      "username": "lisi",
      "email": "lisi@example.com",
      "fullName": "李四",
      "role": "product_manager",
      "status": "active",
      "avatar": "https://cdn.example.com/avatars/usr_xyz789ghi012.jpg",
      "department": "产品部",
      "createdAt": "2026-02-01T10:00:00Z",
      "lastLoginAt": "2026-03-13T18:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 156,
    "totalPages": 8,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

创建用户

POST /users

创建新用户账户

请求体

字段名 类型 必填 描述
username string 必填 用户名（3-20 字符，字母数字下划线）
email string 必填 邮箱地址（需唯一）
password string 必填 密码（最少 8 字符，包含大小写字母和数字）
fullName string 必填 真实姓名
role string 可选 角色，默认 developer
department string 可选 所属部门

请求示例

curl -X POST https://api.openclaw-cocode.system/v2/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "username": "wangwu",
    "email": "wangwu@example.com",
    "password": "SecurePass123!",
    "fullName": "王五",
    "role": "tester",
    "department": "质量保障部"
  }'

成功响应（201 Created）

{
  "id": "usr_new789xyz456",
  "username": "wangwu",
  "email": "wangwu@example.com",
  "fullName": "王五",
  "role": "tester",
  "status": "pending_verification",
  "department": "质量保障部",
  "createdAt": "2026-03-14T10:45:00Z",
  "verificationEmailSent": true
}

获取用户详情

GET /users/{userId}

获取指定用户的详细信息

路径参数

参数名 类型 必填 描述
userId string 必填 用户 ID

请求示例

curl -X GET https://api.openclaw-cocode.system/v2/users/usr_abc123def456 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

更新用户信息

PUT /users/{userId}

全量更新用户信息

请求体

与创建用户相同的字段结构，所有字段均为可选（除 password 外）。

请求示例

curl -X PUT https://api.openclaw-cocode.system/v2/users/usr_abc123def456 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "张三丰",
    "department": "架构组",
    "role": "architect"
  }'

删除用户

DELETE /users/{userId}

删除用户账户（软删除，保留审计日志）

查询参数

参数名 类型 必填 描述
hard boolean 可选 是否物理删除，默认 false（软删除）

请求示例

curl -X DELETE https://api.openclaw-cocode.system/v2/users/usr_abc123def456 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

成功响应（204 No Content）

// 无响应体

项目管理 API

项目管理相关接口，包括项目 CRUD、成员管理、PRD 关联等。

创建项目

POST /projects

创建新项目

请求体

字段名 类型 必填 描述
name string 必填 项目名称
description string 可选 项目描述
key string 必填 项目标识符（大写，如 ECOM）
ownerId string 必填 项目负责人 ID
members array 可选 初始成员列表
visibility string 可选 可见性：private, internal, public

请求示例

curl -X POST https://api.openclaw-cocode.system/v2/projects \
  -H "Authorization: Bearer ..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "电商后台管理系统",
    "description": "新一代电商后台管理平台",
    "key": "ECOM",
    "ownerId": "usr_abc123def456",
    "members": ["usr_xyz789ghi012"],
    "visibility": "internal"
  }'

成功响应（201 Created）

{
  "id": "prj_ecom2026031401",
  "name": "电商后台管理系统",
  "key": "ECOM",
  "description": "新一代电商后台管理平台",
  "ownerId": "usr_abc123def456",
  "status": "active",
  "visibility": "internal",
  "members": [
    {"userId": "usr_abc123def456", "role": "owner"},
    {"userId": "usr_xyz789ghi012", "role": "member"}
  ],
  "stats": {
    "totalTasks": 0,
    "completedTasks": 0,
    "totalPRDs": 0,
    "totalDeployments": 0
  },
  "createdAt": "2026-03-14T11:00:00Z"
}

获取项目列表

GET /projects

获取当前用户可访问的项目列表

查询参数

参数名 类型 必填 描述
status string 可选 项目状态筛选
role string 可选 按用户角色筛选：owner, member

任务管理 API

任务/工单管理接口，支持敏捷开发的 Story、Task、Bug 等工单类型。

创建任务

POST /projects/{projectId}/tasks

在项目下创建新任务

路径参数

参数名 类型 必填 描述
projectId string 必填 项目 ID

请求体

字段名 类型 必填 描述
type string 必填 任务类型：story, task, bug, epic
title string 必填 任务标题
description string 可选 任务描述（支持 Markdown）
assigneeId string 可选 负责人 ID
priority string 可选 优先级：critical, high, medium, low
storyPoints number 可选 故事点估算
parentTaskId string 可选 父任务 ID（用于子任务）
labels array 可选 标签列表

请求示例

curl -X POST https://api.openclaw-cocode.system/v2/projects/prj_ecom2026031401/tasks \
  -H "Authorization: Bearer ..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "story",
    "title": "用户登录功能实现",
    "description": "实现基于 JWT 的用户登录认证功能",
    "assigneeId": "usr_abc123def456",
    "priority": "high",
    "storyPoints": 5,
    "labels": ["backend", "authentication"]
  }'

成功响应（201 Created）

{
  "id": "task_ecom001",
  "key": "ECOM-1",
  "projectId": "prj_ecom2026031401",
  "type": "story",
  "title": "用户登录功能实现",
  "description": "实现基于 JWT 的用户登录认证功能",
  "status": "todo",
  "assigneeId": "usr_abc123def456",
  "reporterId": "usr_xyz789ghi012",
  "priority": "high",
  "storyPoints": 5,
  "labels": ["backend", "authentication"],
  "createdAt": "2026-03-14T11:30:00Z",
  "updatedAt": "2026-03-14T11:30:00Z"
}

更新任务状态

PUT /tasks/{taskId}/status

更新任务状态（流转）

路径参数

参数名 类型 必填 描述
taskId string 必填 任务 ID

请求体

字段名 类型 必填 描述
status string 必填 新状态：todo, in_progress, review, testing, done
comment string 可选 状态变更说明

Agents API

AI Agent 管理和控制接口，用于激活、配置、监控各角色 Agent。

激活 Agent

POST /agents/{agentType}/activate

激活指定类型的 AI Agent 并分配任务

路径参数

参数名 类型 必填 描述
agentType string 必填 Agent 类型：product, architecture, api, backend, frontend, test, devops, qa

请求体

字段名 类型 必填 描述
taskId string 必填 关联的任务 ID
input object 必填 Agent 输入数据
config object 可选 Agent 配置参数
notifyOnComplete boolean 可选 完成后是否通知，默认 true

请求示例

curl -X POST https://api.openclaw-cocode.system/v2/agents/product/activate \
  -H "Authorization: Bearer ..." \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "task_ecom001",
    "input": {
      "requirement": "实现用户中心模块，支持手机号登录、邮箱登录、第三方登录",
      "context": "电商后台管理系统 v1.0"
    },
    "config": {
      "model": "claude-sonnet-4",
      "temperature": 0.7,
      "outputFormat": "markdown"
    },
    "notifyOnComplete": true
  }'

成功响应（202 Accepted）

{
  "activationId": "act_prod2026031401",
  "agentType": "product",
  "taskId": "task_ecom001",
  "status": "processing",
  "estimatedCompletionTime": "2026-03-14T12:00:00Z",
  "progressUrl": "/agents/activations/act_prod2026031401/progress"
}

查询 Agent 执行进度

GET /agents/activations/{activationId}/progress

查询 Agent 任务执行进度和中间结果

路径参数

参数名 类型 必填 描述
activationId string 必填 激活 ID

成功响应（200 OK）

{
  "activationId": "act_prod2026031401",
  "agentType": "product",
  "status": "processing",
  "progress": 65,
  "currentStep": "生成验收标准",
  "steps": [
    {"name": "需求解析", "status": "completed", "progress": 100},
    {"name": "用户故事生成", "status": "completed", "progress": 100},
    {"name": "功能拆解", "status": "completed", "progress": 100},
    {"name": "优先级排序", "status": "completed", "progress": 100},
    {"name": "生成验收标准", "status": "in_progress", "progress": 65},
    {"name": "文档格式化", "status": "pending", "progress": 0}
  ],
  "intermediateResults": {
    "userStories": [...],
    "featureList": [...]
  },
  "logs": [
    {"timestamp": "2026-03-14T11:35:00Z", "level": "info", "message": "开始需求分析"},
    {"timestamp": "2026-03-14T11:38:00Z", "level": "info", "message": "已生成 12 个用户故事"}
  ]
}

获取 Agent 输出结果

GET /agents/activations/{activationId}/result

获取 Agent 任务的最终输出结果

路径参数

参数名 类型 必填 描述
activationId string 必填 激活 ID

成功响应（200 OK）

{
  "activationId": "act_prod2026031401",
  "status": "completed",
  "output": {
    "prdDocument": "# 用户中心模块 PRD\n\n## 1. 产品概述\n...",
    "userStories": [...],
    "acceptanceCriteria": [...],
    "attachments": [
      {
        "name": "user-story-map.png",
        "url": "https://cdn.example.com/outputs/act_prod2026031401/story-map.png"
      }
    ]
  },
  "metrics": {
    "executionTime": 1847,
    "tokensUsed": 15234,
    "model": "claude-sonnet-4"
  },
  "completedAt": "2026-03-14T11:52:00Z"
}

流水线 API

CI/CD 流水线管理接口，用于触发、监控、控制构建和部署流程。

触发流水线

POST /pipelines/{pipelineId}/trigger

手动触发 CI/CD 流水线执行

路径参数

参数名 类型 必填 描述
pipelineId string 必填 流水线 ID

请求体

字段名 类型 必填 描述
branch string 可选 Git 分支，默认主分支
commit string 可选 Git Commit SHA
environment string 可选 部署环境：dev, test, staging, prod
skipTests boolean 可选 是否跳过测试，默认 false
variables object 可选 环境变量覆盖

成功响应（202 Accepted）

{
  "buildId": "build_20260314_120501",
  "pipelineId": "pipe_ecom_main",
  "status": "queued",
  "queuePosition": 2,
  "triggeredBy": "usr_abc123def456",
  "triggeredAt": "2026-03-14T12:05:01Z",
  "estimatedStartTime": "2026-03-14T12:07:00Z"
}

获取构建详情

GET /builds/{buildId}

获取构建执行的详细信息

路径参数

参数名 类型 必填 描述
buildId string 必填 构建 ID

成功响应（200 OK）

{
  "buildId": "build_20260314_120501",
  "pipelineId": "pipe_ecom_main",
  "status": "running",
  "currentStage": "test",
  "progress": 60,
  "stages": [
    {
      "name": "checkout",
      "status": "success",
      "duration": 15,
      "startedAt": "2026-03-14T12:07:00Z",
      "finishedAt": "2026-03-14T12:07:15Z"
    },
    {
      "name": "build",
      "status": "success",
      "duration": 180,
      "startedAt": "2026-03-14T12:07:15Z",
      "finishedAt": "2026-03-14T12:10:15Z"
    },
    {
      "name": "test",
      "status": "running",
      "progress": 45,
      "startedAt": "2026-03-14T12:10:15Z"
    },
    {
      "name": "deploy",
      "status": "pending"
    }
  ],
  "artifacts": [
    {
      "name": "app.jar",
      "size": 45678912,
      "url": "https://artifacts.example.com/build_20260314_120501/app.jar"
    }
  ],
  "logs": {
    "console": "https://logs.example.com/build_20260314_120501/console",
    "testReport": "https://logs.example.com/build_20260314_120501/test-report"
  }
}

部署管理 API

部署相关接口，用于管理应用在不同环境的部署。

创建部署

POST /deployments

创建新的部署任务

请求体

字段名 类型 必填 描述
applicationId string 必填 应用 ID
environment string 必填 目标环境
version string 必填 部署版本号
strategy string 可选 部署策略：rolling, blue-green, canary
approvals array 可选 审批人列表（生产环境必需）

回滚部署

POST /deployments/{deploymentId}/rollback

回滚到之前的部署版本

路径参数

参数名 类型 必填 描述
deploymentId string 必填 当前部署 ID

请求体

字段名 类型 必填 描述
targetVersion string 可选 回滚目标版本，默认上一版本
reason string 必填 回滚原因

测试管理 API

测试相关接口，包括测试用例管理、测试执行、测试报告等。

执行测试套件

POST /tests/suites/{suiteId}/run

执行指定的测试套件

路径参数

参数名 类型 必填 描述
suiteId string 必填 测试套件 ID

请求体

字段名 类型 必填 描述
environment string 可选 测试环境
browsers array 可选 浏览器列表，默认 ['chromium']
parallel integer 可选 并行执行数，默认 4

获取测试报告

GET /tests/runs/{runId}/report

获取测试执行报告

Webhooks API

Webhook 管理接口，用于配置事件通知。

创建 Webhook

POST /webhooks

创建新的 Webhook 订阅

请求体

字段名 类型 必填 描述
url string 必填 回调 URL
events array 必填 订阅的事件列表
secret string 可选 签名密钥
active boolean 可选 是否启用，默认 true

可用事件

  • project.created - 项目创建
  • task.updated - 任务更新
  • agent.completed - Agent 任务完成
  • build.started - 构建开始
  • build.completed - 构建完成
  • deployment.success - 部署成功
  • deployment.failed - 部署失败
  • test.failed - 测试失败

错误处理

错误响应格式

所有 API 错误都遵循统一的响应格式：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "人类可读的错误描述",
    "details": {...},
    "requestId": "req_abc123",
    "timestamp": "2026-03-14T12:30:00Z"
  }
}

常见错误码

HTTP 状态码 错误码 描述
400 INVALID_REQUEST 请求参数无效或格式错误
401 UNAUTHORIZED 未认证或 Token 无效
403 FORBIDDEN 权限不足
404 NOT_FOUND 资源不存在
409 CONFLICT 资源冲突（如重复创建）
422 VALIDATION_ERROR 数据验证失败
429 RATE_LIMITED 请求频率超限
500 INTERNAL_ERROR 服务器内部错误
503 SERVICE_UNAVAILABLE 服务暂时不可用

错误响应示例

// 404 Not Found
{
  "error": {
    "code": "NOT_FOUND",
    "message": "用户不存在",
    "details": {
      "resource": "user",
      "id": "usr_invalid123"
    },
    "requestId": "req_abc123def456",
    "timestamp": "2026-03-14T12:30:00Z"
  }
}

// 422 Validation Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "请求数据验证失败",
    "details": {
      "fields": [
        {
          "field": "email",
          "message": "邮箱格式不正确",
          "code": "invalid_format"
        },
        {
          "field": "password",
          "message": "密码长度至少为 8 位",
          "code": "min_length"
        }
      ]
    },
    "requestId": "req_xyz789",
    "timestamp": "2026-03-14T12:35:00Z"
  }
}

限流策略

限流规则

系统采用令牌桶算法进行 API 限流，不同用户等级有不同的限流配额：

用户等级 请求/分钟 请求/小时 并发连接
Free 60 1,000 5
Pro 300 10,000 20
Enterprise 1,000 50,000 100

限流响应头

所有 API 响应都包含以下限流相关的 HTTP 头：

X-RateLimit-Limit: 300        # 每分钟请求上限
X-RateLimit-Remaining: 287     # 剩余请求数
X-RateLimit-Reset: 1710411600  # 重置时间戳（Unix 秒）
Retry-After: 45                # 建议重试等待时间（秒）
💡 最佳实践：
  • 实现指数退避重试策略
  • 监控 X-RateLimit-Remaining 头，提前调整请求频率
  • 对于批量操作，使用批量 API 减少请求次数
  • 非实时需求可使用 Webhooks 替代轮询