安全与参考

工作台配置

模型和权限在设置里配；某个智能体用哪些技能、频道和记忆，在 Work → 智能体 里配。组织策略可能只开放其中一部分，只读项请找管理员，不要改本地文件绕过。

建议顺序：

在 设置 → AI 与语音 接入一个已批准的模型，完成一句不含敏感信息的对话。
按任务需要再加技能、MCP 或频道，不要一次全开。
凭据只填在对应字段里。
较大调整前，到 设置 → 安全与恢复 导出备份。

备份、产品分析和频道显示字段的细节如下。改频道凭据的操作路径见频道。

产品分析与隐私

产品分析设置只向拥有现有“实例设置管理”权限的本地操作者显示。客户端包含这项设置并不表示产品分析已经启用：如果当前发行配置没有显式启用产品分析，或没有受批准的 HTTPS 接收端，设置页会显示此构建不可用，不显示首次披露，也不会发送产品分析事件。

在受批准且启用的发行配置中，本地操作者必须先阅读当前版本的披露，并明确选择“允许”或 “保持关闭”。没有地区推断或默认同意。之后可以在通用设置中关闭产品分析；组织管理员的关闭优先于用户选择。关闭会清空尚未发送的队列，也可以在二次确认后重置随机 installation ID，但界面不会显示这个 ID。

允许后只采集固定 allowlist 中的产品操作结果、阶段、粗粒度耗时或大小分桶，以及稳定错误码。不会采集 prompt、消息、文件内容、文件名或路径、Workspace 内容、secret、token、credential、模型或 endpoint 自定义值、工具参数或结果，以及用户命名的 Agent 或 Automation 文本。标识只关联到随机、持久且可重置的 installation ID，不使用账号、硬件 ID、MAC 地址或系统序列号。

目标保留期为 3 个月；在外部保留策略和 production readback 完成验证前，产品分析仍保持不可用。 Product Analytics 不包含诊断包、崩溃日志或本地 Browser trace；选择允许产品分析不会暗含同意上传这些数据。

本地备份

备份中心在 设置 → 安全与恢复。它提供两个相互独立的开关：每 24 小时自动备份默认开启，安装更新前自动备份默认关闭。为缓解长期使用后完整备份体积过大、拖慢更新的问题，修复版首次运行时也会将旧版的更新前备份开关按关闭处理。需要这项保护时，可以在设置中重新开启，之后会保存你的选择。关闭其中一个不会改变另一个，也不会删除已有备份。自动恢复点按最近 7 个有备份日、4 个有备份周和 6 个有备份月保留，同一份备份可同时满足多个周期；手动备份不会被这项策略自动清理。

手动开启后，如果安装更新前备份失败，更新默认停止。你可以修复问题后重试，也可以只为当前这次更新明确选择“不备份，继续”；这个选择不会关闭以后更新前的自动备份。

这项安装门禁从已经运行 2.3 的客户端发起后续更新时生效。2.2.1 → 2.3.0 的首次升级仍由旧客户端执行，因此无法反向使用 2.3 新增的更新前备份门禁。同理，从旧版升级到本次修复版的那一次仍使用旧版设置；默认关闭在修复版启动后生效。

完整备份可能包含模型或渠道凭据等敏感配置，当前归档不承诺内容加密。请只把导出的备份保存在可信位置，不要上传到公开网盘、公开仓库或支持工单。

恢复全局配置时，如果当前本地配置只是仍可由应用修复的语法问题，自定义恢复会读取并保留未选中的本地普通 Agent；完整恢复则以归档配置作为普通 Agent 的基线，可能移除归档中不存在的本地普通 Agent。选择保留本地受保护配置时，两种模式都会保留 security 和 MCP；两种模式还会保留本地 System Managed Agent 引用。若本地配置已截断、不是 UTF-8 或无法安全读取，自定义恢复会跳过全局配置替换，避免把未知的本地状态误当成空配置；完整恢复仍可应用归档，但不会执行基于空本地状态的覆盖。Workspace 恢复不会因此被中止。

全局工具详情显示

根配置 config.json 中的 show_tool_details 是所有频道共用的开关，默认值为 true。它只决定已启用的工具调用和工具结果是否包含详情，不会开启工具消息，也不控制 reasoning/thinking。设为 false 时，工作台和外部频道都会只显示工具摘要。

智能体频道配置

频道配置位于对应智能体的 agent.json 中，结构为 channels.<channel-key>。内建频道使用类型化 schema，插件频道允许在同一 channels 对象中增加已注册的 key。日常请在 Work → 连接 或智能体详情的连接分区修改。

json

{
  "channels": {
    "console": {
      "enabled": true
    },
    "feishu": {
      "enabled": true,
      "app_id": "<app-id>",
      "app_secret": "<secret>",
      "dm_policy": "allowlist",
      "group_policy": "allowlist",
      "allow_from": ["<stable-user-or-room-id>"],
      "show_tool_calls": false,
      "show_tool_results": false,
      "show_thinking": false,
      "tool_call_max_length": 200,
      "tool_result_max_length": 500
    }
  }
}

直接编辑文件前先停止并发写入，保留备份，并在保存后重新读取有效配置：

bash

coginework channels config --agent-id <id>
coginework channels list --agent-id <id>

共享频道字段

所有内建外部频道继承以下公共合同：

字段	类型/默认	说明
`enabled`	`false`	是否启用；工作台渠道始终保持启用
`bot_prefix`	`""`	可选机器人前缀
`dm_policy`	`open`	私聊入口：`open` 或 `allowlist`
`group_policy`	`open`	群聊入口：`open` 或 `allowlist`
`allow_from`	`[]`	平台稳定用户/群/房间 ID
`deny_message`	`""`	被拒绝时的公开消息；不得包含敏感诊断
`require_mention`	`false`	群聊是否必须点名机器人
`dm_disabled`	`false`	完全关闭私聊入口
`group_disabled`	`false`	完全关闭群聊入口
`no_text_debounce`	`true`	媒体无文本时是否立即处理
`show_tool_calls`	`false`	外部频道显示工具调用
`show_tool_results`	`false`	外部频道显示工具结果
`show_thinking`	`false`	外部频道显示 thinking
`tool_call_max_length`	`200`	工具调用预览字符上限；`0` 表示不截断
`tool_result_max_length`	`500`	工具结果预览字符上限；`0` 表示不截断

工作台渠道的每频道 show_tool_calls、show_tool_results 和 show_thinking 默认为 true；外部频道的对应默认值为 false。所有频道都服从同一个根级 show_tool_details。

显示字段迁移

旧版本使用负向字段 filter_tool_messages 和 filter_thinking。新版本只把正向字段作为运行时真相：

存在合法的新 show_* 字段时，按新字段读取。
只有旧字段时，按等价的负向语义反转迁移：旧值为 true 时对应的 show_* 为 false，旧值为 false 时对应的 show_* 为 true。
新旧字段混合时，新字段生效，并记录不含配置值的诊断告警。
成功写入后移除旧字段，避免两套 active truth source。
未显式配置旧字段或新字段时采用当前频道默认值；如需改变默认行为，使用新的 show_* 字段。

迁移是幂等和可重试的：替换前会校验新结构，创建备份，并使用原子写入。坏 JSON、无效长度或写入中断不会触发清空整个配置，也不会删除 Agent、Workspace、session、skill、plugin、model、credential 或 backup。

群聊会话字段

部分频道支持 share_session_in_group：

false：群聊按真实发送者隔离上下文。
true：同一群共用对话上下文。

Feishu、OneBot 默认 false；Matrix 和 WeCom 保留各自协议的现有默认。切换不会自动合并或重写旧会话。ACL、审批、审计和 reply route 始终保留真实发送者身份，不因共享上下文而共享权限。

自定义 endpoint

Feishu、Telegram、OneBot、Xiaoyi、Yuanbao 等频道可能提供 endpoint、gateway、proxy 或监听地址字段。这些值会改变网络信任边界：

只允许合法、明确的协议和地址；凭据不得嵌入 URL。
非 loopback OneBot listener 必须配置 token。
组织策略必须允许 channels.configure；插件的 manifest.trust 不能自动授权。
远程媒体必须经过 redirect、大小、content type、timeout、Workspace 和 File Guard 校验。
endpoint 变更失败时应 fail closed，不回退到未知或不受控地址。

插件频道配置

只有成功注册、版本兼容且通过 schema 校验的频道插件会进入工作台。能被 JSON 解析不代表插件合法。表单字段、密钥遮罩和开发合同见开发频道插件。

写入与 reload

配置保存后会触发对应智能体的 zero-downtime reload。新实例启动成功后才替换旧实例；旧实例仍有活跃任务时会等待任务完成再释放频道、client 和队列。

一次频道坏配置只应阻止该频道或该智能体的安全启动，不应重置其他智能体。保存后建议验证：

bash

coginework channels list --agent-id default
coginework doctor

随后在测试机器人中覆盖私聊、群聊、保存/reload、进程重启、streaming、错误、审批、history/replay、媒体和主动发送。自动化通过不等于真实平台、打包或发布已验证。

相关页面：工作台 · 安全 · 频道 · 命令行 · 插件 · 开发频道插件