API 概述 REST API

ChatAI Plugin 提供 REST API 用于管理和扩展功能，支持 Web 面板和第三方集成。

基础信息

项目	值	说明
Base URL	`http://localhost:3000/api`	端口可在配置中修改
认证方式	JWT Token	支持 Cookie 或 Bearer Token
响应格式	JSON	统一 JSON 响应结构
限流	60 req/min	默认限流规则

架构总览

API 模块

模块说明

每个模块提供一组相关的 API 接口，可独立使用。

模块	路径	说明	文档
认证	`/api/auth`	登录、验证、Token 管理	查看
配置	`/api/config`	配置读取与更新、渠道管理、群组配置	查看
对话	`/api/conversations`	对话历史查看与清理	查看
预设	`/api/presets`	预设 CRUD、预设文件管理	查看
工具	`/api/tools`	工具管理、执行、日志、危险工具配置	查看
MCP	`/api/mcp`	MCP 服务器连接、管理、SSE 状态推送	查看
技能	`/api/skills`	Skills Agent 接口、工具分类、全局开关、SSE	查看
群管理	`/api/group-admin`	群组独立配置、群管登录	查看
系统	`/api/system`	健康检查、版本信息、统计数据	查看
记忆	`/api/memories`	结构化用户记忆管理、分类、统计	查看
知识库	`/api/knowledge`	知识库文档 CRUD、搜索	查看
知识图谱	`/api/graph`	实体、关系、属性的 CRUD、可视化数据	查看
绘图	`/api/image`	绘图预设管理、远程预设缓存	查看
游戏	`/api/game`	Galgame 角色预设管理	查看
日志	`/api/logs`	日志文件列表、错误日志查看	查看
代理	`/api/proxy`	网络代理配置管理	查看
作用域	`/api/scope`	用户/群组级别独立配置管理	查看

认证

获取方式

在机器人中发送 #ai管理面板 获取临时登录链接，或 #ai管理面板永久 获取永久链接。

API 调用认证

Cookie 认证Bearer Token

bash

# 浏览器自动携带 Cookie
curl http://localhost:3000/api/config \
  -H "Cookie: auth_token=xxx"

bash

# 适用于第三方调用
curl http://localhost:3000/api/config \
  -H "Authorization: Bearer xxx"

响应格式

成功响应错误响应

json

{
  "success": true,
  "data": { ... }
}

json

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

错误码

状态码	说明	常见原因
`200`	成功	-
`400`	请求参数错误	缺少必需参数、参数格式错误
`401`	未认证	Token 缺失或已过期
`403`	权限不足	无权访问该资源
`404`	资源不存在	请求的资源未找到
`429`	请求过于频繁	超出限流限制
`500`	服务器内部错误	服务端异常

限流

限流规则

窗口时间：60 秒
最大请求数：60 次
超出限制返回 429 状态码

SSE 接口

部分接口支持 Server-Sent Events 实时推送：

javascript

const eventSource = new EventSource('/api/skills/sse')

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log('Status update:', data)
}

eventSource.onerror = (error) => {
  console.error('SSE Error:', error)
}

API 详细文档

文档	说明	主要接口
认证接口	登录与验证	`POST /auth/verify`, `POST /auth/logout`
配置接口	配置与渠道管理	`GET /config`, `PUT /config`, `POST /config/channels`
聊天接口	对话与记忆	`POST /chat`, `GET /chat/history`
工具接口	工具管理	`GET /tools`, `POST /tools/:name/execute`
技能接口	Skills Agent	`GET /skills/categories`, `POST /skills/toggle-category`
MCP 接口	MCP 服务器	`GET /mcp/servers`, `POST /mcp/servers/:name/connect`
记忆接口	用户记忆	`GET /memories/users`, `POST /memories/user/:userId`
知识库接口	知识库文档	`GET /knowledge`, `GET /knowledge/search`
知识图谱接口	实体与关系	`GET /graph/entities`, `POST /graph/relations`
绘图接口	绘图预设	`GET /image/presets`, `PUT /image/config`
游戏接口	Galgame	`GET /game/presets`, `POST /game/presets`
日志接口	日志查看	`GET /logs`, `GET /logs/recent`
代理接口	网络代理	`GET /proxy`, `PUT /proxy/scopes/:scope`
作用域接口	粒度配置	`GET /scope/users`, `PUT /scope/group/:groupId`

API 概述 REST API ​

基础信息 ​

架构总览 ​

API 模块 ​

认证 ​

获取登录链接 ​

登录流程 ​

API 调用认证 ​

响应格式 ​

错误码 ​

限流 ​

SSE 接口 ​

API 详细文档 ​