全局配置

全局配置管理整个空间的全局设置，包括主题、默认模型、客户端准入、内容安全、文件存储方式和会话合规策略。

什么时候用

• 需要配置默认模型或模型组时
• 需要控制哪些客户端可以调用API时
• 需要配置内容安全策略（脱敏、阻断、PII检测）时
• 需要切换文件存储方式（本地/S3）时
• 需要配置会话合规和审计策略时
• 需要自定义全局系统提示词时

你需要准备

• （配置模型）至少一个已接入的模型，详见接入模型供应商
• （配置S3存储）S3服务地址、Bucket、AccessKey和SecretKey
• （管理员）只有管理员可以修改这些配置

操作步骤

第 1 步：进入系统设置

左侧菜单 -> 系统设置。

页面分为多个区域：

• 主题设置
• 基础设置
• 通知配置
• 客户端设置
• 存储配置
• 会话合规配置

第 2 步：配置主题

在「主题设置」区域：

1. （可选）开启「跟随系统」自动切换亮色/暗色主题
2. （如不跟随系统）手动选择「亮色」或「暗色」主题
3. 点击主题卡片预览效果

主题设置仅影响当前用户的控制台界面。

第 3 步：配置基础设置

在「基础设置」区域：

3.1 默认模型/模型组

重要：默认模型和默认模型组互斥，选择一个会自动清空另一个。

1. 在「默认模型」下拉框中选择模型，或
2. 在「默认模型组」下拉框中选择模型组
3. 当智能体未单独设置模型时，会使用此默认配置

3.2 模型展示模式

在「模型展示模式」下拉框中选择：

• 全部展示：模型 + 模型组
• 仅展示模型
• 仅展示模型组

3.3 全局系统提示词

在「全局系统提示」文本框中输入内容，会作为所有对话的底层基础人设，叠加在Agent的系统提示词之前。

3.4 保存基础设置

点击「保存设置」按钮。

第 4 步：配置客户端设置

在「客户端设置」区域：

4.1 允许客户端预置智能体

开关「允许客户端预置智能体」：

• 开启：客户端可以在对话开头插入系统级消息
• 关闭：客户端插入的系统级消息会被自动移除，只使用平台内配置的智能体

4.2 客户端白名单

在「客户端白名单」多选框中配置：

• 输入客户端标识（如opencode、cherrystudio）
• 系统按客户端标识做大小写不敏感的子串匹配
• 重要：空列表 = 拒绝所有第三方客户端调用
• 平台内置客户端不可移除

4.3 会话提取规则

配置各客户端的会话ID提取方式：

• 查看系统预设规则（只读）
• 点击「新增规则」添加自定义规则
• 自定义规则会覆盖同客户端的系统预设

每个规则包含：

• 客户端标识：如opencode
• 提取类型：请求头/请求体/元数据
• 提取位置：如某个字段名或路径

4.4 保存客户端设置

点击「保存设置」按钮。

第 5 步：配置存储配置

在「存储配置」区域：

5.1 选择文件存储方式

在「文件存储方式」下拉框中选择：

• 跟随系统配置（默认）：使用平台管理员设置的存储
• 自定义S3兼容存储：使用自己的S3服务

5.2 配置S3存储

如选择自定义S3存储，填写：

• Endpoint：S3服务地址
• Bucket：存储桶名
• AccessKey ID：访问密钥ID
• SecretKey：访问密钥
  • 已配置后：显示「已配置（留空保持不变）」
  • 留空不修改，传非空覆盖

5.3 保存存储配置

点击「保存存储配置」按钮。

第 6 步：配置会话合规

在「会话合规配置」区域：

6.1 审计模式

选择审计模式：

• 不脱敏展示：展示和保存均为原始内容
• 脱敏展示：保存原始内容，展示时脱敏
• 仅保存脱敏：保存时即脱敏，展示也为脱敏后内容

6.2 脱敏规则

在「脱敏规则」文本框中输入JSON数组格式的正则表达式，匹配到的内容会在审计日志中脱敏。

示例：

["EMP\\d{6}", "1[3-9]\\d{9}"]

6.3 PII检测

开启「PII检测」开关，自动检测消息中的敏感个人信息（仅审计不阻断）。

6.4 操作审计

开启「操作审计」开关，记录管理员对资源的创建、更新、删除等操作日志。

6.5 禁止模式

在「禁止模式」文本框中输入JSON数组格式的正则表达式，消息内容命中任一模式时会记录安全事件并可能阻断请求。

示例：

["(密码|password)\\s*[:：]\\s*\\S+"]

6.6 消息保留天数

在「消息保留天数」数字框中设置，0表示永不过期。

6.7 保存合规配置

点击「保存合规配置」按钮。

怎么验证成功了

1. 保存设置后刷新页面，配置内容正确保留
2. 设置默认模型后，未绑定模型的Agent能正常对话
3. 配置客户端白名单后，白名单内的客户端能调用API，不在白名单的返回403
4. 配置S3存储后，能正常上传和下载文件
5. 配置脱敏规则后，审计日志中敏感信息被脱敏

常见问题

为什么设置默认模型后Agent还是报错503

检查：

• 模型确实已启用
• 模型属于当前或公共可用模型
• Agent没有绑定自己的模型（Agent独立绑定的模型优先于默认）

客户端白名单为空为什么拒绝所有请求

这是设计如此。白名单为空时会拦截所有请求。如果你想放行所有，需要了解你的客户端标识并显式添加到列表中。

如何清空S3 SecretKey

无法通过界面清空。一旦配置了S3 SecretKey，如需清除请联系平台管理员。

修改正则被拒绝

系统会对正则表达式做安全检测，过于复杂的正则模式会被拒绝。请简化正则表达式。

为什么看不到通知配置

通知配置在同一页面，往下滚动即可看到。通知配置详见配置通知渠道。

深入

认证与Token机制

平台使用双Token机制：

全局吊销：每次登录时，系统会生成一个新的jti并写入租户设置。旧的refresh_token中的jti与数据库不匹配，会被自动拒绝。这意味着：

• 重新登录后，之前签发的所有refresh_token立即失效
• 不存在「多设备同时在线」（除非共用同一份token）

部署模式

部署模式由平台管理员设置，决定租户管理员能否编辑可执行代码：

通过公共端点可以查询部署模式信息，无需认证。

前端应以can_edit_executable_code_by_tenant_admin控制租户admin的编辑入口；后端仍会按部署模式强制校验。

默认模型

租户可配置一个默认模型或默认模型组，两者互斥——设置一个会自动清空另一个。

默认模型的作用：

• Agent未绑定模型时，使用租户默认模型
• 租户没有默认模型且Agent未绑模型 → API返回503 service_unavailable

客户端准入控制

allowed_api_clients是一个字符串列表，控制哪些客户端可以调用聊天API。

• 空列表 = 全部拒绝，不是「全部允许」
• 每个条目通常是客户端标识（如opencode、curl、自定义SDK名称）
• 提交时自动去重、去空串
• 如果客户端不在白名单中，API返回403 permission_error

内容安全策略

安全性：

• 脱敏规则和禁用模式启用安全检测，不安全的模式会被拒绝
• 脱敏与阻断是两套独立的规则，互不影响

S3存储

平台支持两种存储后端：

S3 SecretKey遵循敏感字段更新与查询规则：

• 写：传非空覆盖，传空保持原值
• 读：不返回明文，仅返回secret_configured布尔标记

权限边界

注意事项

• 修改默认模型后请检查：模型确实已激活、模型属于当前租户、Agent没有绑定自己的模型
• 客户端白名单为空 = 全部拒绝
• S3 SecretKey无法通过更新清空
• 不安全的正则模式会被拒绝
• 修改allow_external_role影响已有会话
• access_token过期后不要重复登录，应该用refresh_token刷新

排错速查

• 需要先接入模型才能设置默认模型，详见接入模型供应商和添加与配置模型
• 部分功能可能需要插件支持，详见插件管理