设置 API

设置 API 管理管理员站点配置，以及无需认证读取的公开设置。管理员设置存储为键值对，响应遵循统一的 code、data、msg 结构。

端点总览

认证与权限

管理员端点需要 JWT 或具备对应权限的 API Key：

• admin:settings:read：读取设置
• admin:settings:update：更新、重置和触发通知渠道测试
• audit:export：审计日志归档（archive-audit-logs 两个端点）

公开设置端点无需认证。管理 API 通常由管理后台使用，不应作为匿名公共 API。

读取设置

curl -X GET "https://your-domain.com/api/v1/admin/site-settings?category=general" \\
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

category 可选，取值包括 general、security、email、storage、notification、memory、audit、sso、retrieval、dingtalk、wechat、feishu、slack、webhook。单个设置响应包含 key、value、value_type、category、description 和 is_public。

更新设置

更新单个设置：

curl -X PUT "https://your-domain.com/api/v1/admin/site-settings/site_name" \\
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{"value":"My Clouisle Instance"}'

批量更新：

{
  "settings": {
    "site_name": "My Clouisle Instance",
    "smtp_enabled": true
  }
}

使用 PUT /api/v1/admin/site-settings 提交批量对象。后端会按每个设置的类型和约束校验值；校验失败时读取响应中的 data 和 msg。

后台记忆提取设置

memory 分类会在配置的冷却时间后处理待处理用户轮次，或在达到待处理轮次阈值时立即触发后台提取。Agent 还必须启用记忆；关闭该总开关或 Agent 记忆都不会创建提取任务。管理后台页面为 /site-settings/memory。

读取该分类：

curl -X GET "https://your-domain.com/api/v1/admin/site-settings?category=memory" \\
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

提取模型按以下顺序回退：显式配置且启用的模型、Agent 分配的模型、系统默认聊天模型、首个可用聊天模型。冷却时间内会去抖；待处理轮次达到阈值时立即排队任务。

重置设置

curl -X POST "https://your-domain.com/api/v1/admin/site-settings/reset?category=general" \\
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

不提供 category 时重置全部设置；提供分类时只重置该分类。

公开设置

curl -X GET "https://your-domain.com/api/v1/site-settings/public"

只返回 is_public: true 的字段，例如站点名称、默认语言、认证页布局、主题、注册策略和知识库上传大小限制。后台 memory 设置不会通过此端点公开。

自动通知与测试

自动通知配置端点：

GET /api/v1/admin/site-settings/auto-notifications
PUT /api/v1/admin/site-settings/auto-notifications

通知测试端点包括 test-email、test-dingtalk、test-wechat、test-feishu、test-webhook 和 test-slack，均需 admin:settings:update。test-email 接收 { "email": "admin@example.com" }，且要求 smtp_enabled 为 true，否则返回 smtp_not_configured；其他测试端点无需请求体，但渠道必须已启用并完成配置，否则返回 *_not_configured。

审计日志归档

POST /api/v1/admin/site-settings/archive-audit-logs
GET  /api/v1/admin/site-settings/archive-audit-logs/{task_id}

启动端点返回后台任务 ID，再使用查询端点读取归档状态。两个端点都需要 audit:export 权限；启动端点在排队成功后返回 { "task_id": "...", "status": "pending" }。

常见错误

更多后台配置说明参阅站点设置。

Last Updated: 2026-09-09