API 参考

本文档列出 MateClaw 所有 REST API 端点，包含请求/响应示例。

所有接口统一前缀 /api/v1/，需要认证的接口需携带 Authorization: Bearer <token> 请求头。

统一响应格式

json

{
  "code": 200,
  "data": { ... },
  "message": "success"
}

错误响应：

json

{
  "code": 400,
  "data": null,
  "message": "参数错误：name 不能为空"
}

认证（Auth）

用户登录

http

POST /api/v1/auth/login
Content-Type: application/json

请求体：

json

{
  "username": "admin",
  "password": "admin123"
}

响应：

json

{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
    "expiresIn": 86400
  }
}

聊天（Chat）

发送消息

http

POST /api/v1/chat/{agentId}/message
Authorization: Bearer <token>
Content-Type: application/json

请求体：

json

{
  "content": "帮我搜索最新的 AI 论文",
  "conversationId": "1"
}

响应：

json

{
  "code": 200,
  "data": {
    "messageId": "123",
    "conversationId": "1",
    "role": "assistant",
    "content": "我来帮你搜索最新的 AI 论文..."
  }
}

SSE 流式输出

http

GET /api/v1/chat/{agentId}/stream?conversationId={conversationId}
Authorization: Bearer <token>
Accept: text/event-stream

事件格式：

event: message
data: {"type":"text","content":"这是"}

event: message
data: {"type":"text","content":"流式"}

event: message
data: {"type":"text","content":"输出"}

event: tool_call
data: {"type":"tool_call","name":"web_search","arguments":{"query":"AI 论文"}}

event: tool_result
data: {"type":"tool_result","name":"web_search","result":"..."}

event: done
data: {"type":"done","messageId":"123"}

Agent

获取 Agent 列表

http

GET /api/v1/agents
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "通用助手",
      "description": "一个通用的 AI 助手",
      "agentType": "REACT",
      "modelName": "qwen-max",
      "enabled": true,
      "createTime": "2024-01-15T10:00:00"
    }
  ]
}

创建 Agent

http

POST /api/v1/agents
Authorization: Bearer <token>
Content-Type: application/json

请求体：

json

{
  "name": "代码助手",
  "description": "专注于代码编写和审查",
  "agentType": "REACT",
  "modelName": "qwen-max",
  "systemPrompt": "你是一个专业的代码助手...",
  "toolIds": [1, 2, 3],
  "enabled": true
}

响应：

json

{
  "code": 200,
  "data": {
    "id": 2,
    "name": "代码助手",
    "description": "专注于代码编写和审查",
    "agentType": "REACT",
    "modelName": "qwen-max",
    "enabled": true,
    "createTime": "2024-01-16T09:00:00"
  }
}

获取单个 Agent

http

GET /api/v1/agents/{id}
Authorization: Bearer <token>

更新 Agent

http

PUT /api/v1/agents/{id}
Authorization: Bearer <token>
Content-Type: application/json

请求体（同创建，字段可选）：

json

{
  "name": "代码助手 Pro",
  "modelName": "qwen-plus",
  "systemPrompt": "更新后的系统提示词..."
}

删除 Agent

http

DELETE /api/v1/agents/{id}
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "data": null,
  "message": "删除成功"
}

技能（Skills）

获取技能列表

http

GET /api/v1/skills
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "web-search",
      "displayName": "网页搜索",
      "description": "搜索互联网获取最新信息",
      "version": "1.0.0",
      "enabled": true,
      "securityStatus": "PASSED",
      "createTime": "2024-01-15T10:00:00"
    }
  ]
}

创建技能

http

POST /api/v1/skills
Authorization: Bearer <token>
Content-Type: application/json

请求体：

json

{
  "name": "my-skill",
  "displayName": "我的技能",
  "description": "自定义技能描述",
  "version": "1.0.0",
  "content": "---\nname: my-skill\nversion: 1.0.0\n---\n\n# My Skill\n...",
  "enabled": true
}

获取单个技能

http

GET /api/v1/skills/{id}
Authorization: Bearer <token>

更新技能

http

PUT /api/v1/skills/{id}
Authorization: Bearer <token>
Content-Type: application/json

删除技能

http

DELETE /api/v1/skills/{id}
Authorization: Bearer <token>

启用/禁用技能

http

PUT /api/v1/skills/{id}/toggle
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "data": {
    "id": 1,
    "enabled": false
  }
}

获取活跃技能列表

http

GET /api/v1/skills/runtime/active
Authorization: Bearer <token>

返回当前运行时中已加载的活跃技能列表。

获取技能运行状态

http

GET /api/v1/skills/runtime/status
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "data": {
    "totalSkills": 10,
    "activeSkills": 8,
    "loadedAt": "2024-01-16T09:00:00"
  }
}

刷新技能运行时

http

POST /api/v1/skills/runtime/refresh
Authorization: Bearer <token>

强制重新加载所有技能，应用最新的配置变更。

工具（Tools）

获取工具列表

http

GET /api/v1/tools
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "web_search",
      "displayName": "网页搜索",
      "description": "搜索互联网信息",
      "type": "BUILTIN",
      "enabled": true,
      "approvalPolicy": "auto_approve"
    },
    {
      "id": 2,
      "name": "date_time",
      "displayName": "日期时间",
      "description": "获取当前日期和时间",
      "type": "BUILTIN",
      "enabled": true,
      "approvalPolicy": "auto_approve"
    }
  ]
}

创建工具

http

POST /api/v1/tools
Authorization: Bearer <token>
Content-Type: application/json

请求体：

json

{
  "name": "custom_tool",
  "displayName": "自定义工具",
  "description": "工具描述",
  "type": "MCP",
  "config": {
    "serverUrl": "http://localhost:3000/mcp",
    "transport": "sse"
  },
  "enabled": true,
  "approvalPolicy": "manual_approve"
}

获取单个工具

http

GET /api/v1/tools/{id}
Authorization: Bearer <token>

更新工具

http

PUT /api/v1/tools/{id}
Authorization: Bearer <token>
Content-Type: application/json

删除工具

http

DELETE /api/v1/tools/{id}
Authorization: Bearer <token>

会话（Conversations）

获取会话列表

http

GET /api/v1/conversations
Authorization: Bearer <token>

查询参数：

参数	类型	说明
`agentId`	long	按 Agent 筛选
`page`	int	页码（默认 1）
`size`	int	每页数量（默认 20）

响应：

json

{
  "code": 200,
  "data": {
    "records": [
      {
        "id": 1,
        "agentId": 1,
        "title": "关于 AI 论文的讨论",
        "createTime": "2024-01-16T09:00:00",
        "updateTime": "2024-01-16T09:30:00"
      }
    ],
    "total": 15,
    "current": 1,
    "size": 20
  }
}

获取单个会话

http

GET /api/v1/conversations/{id}
Authorization: Bearer <token>

获取会话消息

http

GET /api/v1/conversations/{id}/messages
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "conversationId": 1,
      "role": "user",
      "content": "你好",
      "createTime": "2024-01-16T09:00:00"
    },
    {
      "id": 2,
      "conversationId": 1,
      "role": "assistant",
      "content": "你好！有什么可以帮你的？",
      "toolCalls": null,
      "createTime": "2024-01-16T09:00:01"
    }
  ]
}

更新会话

http

PUT /api/v1/conversations/{id}
Authorization: Bearer <token>
Content-Type: application/json

请求体：

json

{
  "title": "新的会话标题"
}

删除会话

http

DELETE /api/v1/conversations/{id}
Authorization: Bearer <token>

模型（Models）

获取模型提供商列表

http

GET /api/v1/model-providers
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "DashScope",
      "protocol": "dashscope",
      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "enabled": true,
      "sortOrder": 1
    }
  ]
}

创建模型提供商

http

POST /api/v1/model-providers
Authorization: Bearer <token>
Content-Type: application/json

请求体：

json

{
  "name": "My OpenAI",
  "protocol": "openai",
  "baseUrl": "https://api.openai.com/v1",
  "apiKey": "sk-your-key",
  "enabled": true
}

获取模型配置列表

http

GET /api/v1/model-configs
Authorization: Bearer <token>

查询参数：

参数	类型	说明
`providerId`	long	按提供商筛选
`modelType`	string	按类型筛选（chat / embedding / image）

响应：

json

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "providerId": 1,
      "modelName": "qwen-max",
      "displayName": "通义千问 Max",
      "modelType": "chat",
      "maxTokens": 8192,
      "contextWindow": 128000,
      "enabled": true
    }
  ]
}

创建模型配置

http

POST /api/v1/model-configs
Authorization: Bearer <token>
Content-Type: application/json

请求体：

json

{
  "providerId": 1,
  "modelName": "qwen-turbo",
  "displayName": "通义千问 Turbo",
  "modelType": "chat",
  "maxTokens": 4096,
  "contextWindow": 128000,
  "enabled": true,
  "properties": {
    "temperature": 0.7,
    "top_p": 0.9
  }
}

渠道（Channels）

获取渠道列表

http

GET /api/v1/channels
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "Web 聊天",
      "channelType": "WEB",
      "agentId": 1,
      "enabled": true,
      "config": {}
    },
    {
      "id": 2,
      "name": "钉钉机器人",
      "channelType": "DINGTALK",
      "agentId": 1,
      "enabled": false,
      "config": {
        "webhookUrl": "https://oapi.dingtalk.com/robot/...",
        "secret": "SEC..."
      }
    }
  ]
}

创建渠道

http

POST /api/v1/channels
Authorization: Bearer <token>
Content-Type: application/json

请求体：

json

{
  "name": "飞书机器人",
  "channelType": "FEISHU",
  "agentId": 1,
  "enabled": true,
  "config": {
    "appId": "cli_xxx",
    "appSecret": "your-secret"
  }
}

更新渠道

http

PUT /api/v1/channels/{id}
Authorization: Bearer <token>
Content-Type: application/json

删除渠道

http

DELETE /api/v1/channels/{id}
Authorization: Bearer <token>

MCP 服务器

获取 MCP 服务器列表

http

GET /api/v1/mcp-servers
Authorization: Bearer <token>

响应：

json

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "文件系统 MCP",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "enabled": true,
      "status": "CONNECTED"
    }
  ]
}

创建 MCP 服务器

http

POST /api/v1/mcp-servers
Authorization: Bearer <token>
Content-Type: application/json

请求体：

json

{
  "name": "GitHub MCP",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_TOKEN": "ghp_xxx"
  },
  "enabled": true
}

系统设置

获取系统设置

http

GET /api/v1/system-settings
Authorization: Bearer <token>

更新系统设置

http

PUT /api/v1/system-settings
Authorization: Bearer <token>
Content-Type: application/json

请求体：

json

{
  "key": "default_model",
  "value": "qwen-max"
}

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数错误
401	未认证或 Token 过期
403	权限不足
404	资源不存在
500	服务器内部错误

分页参数

支持分页的接口统一使用以下查询参数：

参数	类型	默认值	说明
`page`	int	1	页码
`size`	int	20	每页数量

分页响应格式：

json

{
  "records": [...],
  "total": 100,
  "current": 1,
  "size": 20,
  "pages": 5
}

API 参考 ​

统一响应格式 ​

认证（Auth） ​

用户登录 ​

聊天（Chat） ​

发送消息 ​

SSE 流式输出 ​

Agent ​

获取 Agent 列表 ​

创建 Agent ​

获取单个 Agent ​

更新 Agent ​

删除 Agent ​

技能（Skills） ​

获取技能列表 ​

创建技能 ​

获取单个技能 ​

更新技能 ​

删除技能 ​

启用/禁用技能 ​

获取活跃技能列表 ​

获取技能运行状态 ​

刷新技能运行时 ​

工具（Tools） ​

获取工具列表 ​

创建工具 ​

获取单个工具 ​

更新工具 ​

删除工具 ​

会话（Conversations） ​

获取会话列表 ​

获取单个会话 ​

获取会话消息 ​

更新会话 ​

删除会话 ​

模型（Models） ​

获取模型提供商列表 ​

创建模型提供商 ​

获取模型配置列表 ​

创建模型配置 ​

渠道（Channels） ​

获取渠道列表 ​

创建渠道 ​

更新渠道 ​

删除渠道 ​

MCP 服务器 ​

获取 MCP 服务器列表 ​

创建 MCP 服务器 ​

系统设置 ​

获取系统设置 ​

更新系统设置 ​

HTTP 状态码 ​

分页参数 ​

API 参考

统一响应格式

认证（Auth）

用户登录

聊天（Chat）

发送消息

SSE 流式输出

Agent

获取 Agent 列表

创建 Agent

获取单个 Agent

更新 Agent

删除 Agent

技能（Skills）

获取技能列表

创建技能

获取单个技能

更新技能

删除技能

启用/禁用技能

获取活跃技能列表

获取技能运行状态

刷新技能运行时

工具（Tools）

获取工具列表

创建工具

获取单个工具

更新工具

删除工具

会话（Conversations）

获取会话列表

获取单个会话

获取会话消息

更新会话

删除会话

模型（Models）

获取模型提供商列表

创建模型提供商

获取模型配置列表

创建模型配置

渠道（Channels）

获取渠道列表

创建渠道

更新渠道

删除渠道

MCP 服务器

获取 MCP 服务器列表

创建 MCP 服务器

系统设置

获取系统设置

更新系统设置

HTTP 状态码

分页参数