跳转至

配置 — 智能体会话

session.* 键:对话如何映射到会话、会话何时重置,以及谁可以查看或加入某个会话。

通信默认设置

配置会话是否可以向其他会话发起或接受消息:

{
  session: {
    communication: {
      send: "always",
      receive: "ask",
    },
  },
}

两个方向都接受 always、ask 或 never;省略的值默认为 always。ask 要求在发送或接受该消息作为新的对端输入之前由人工决定。现有的访问限制仍然适用于 always。

Control UI 的 Session settings 子菜单可以覆盖任一方向。Reset 会移除 覆盖,因此之后的配置更改会再次生效。当默认值更改时,现有的显式覆盖 不会被覆盖。重置会保留会话设置, 新的显式子会话和分叉会话会继承这些设置,并且委派的工作仍然受 其父级限制约束。采用现有会话永远不会替换其设置。 更改仅适用于新的准入,而不是已经接受的消息。

这些偏好不会替代 tools.sessions.visibility、人工共享或 面向频道的 sendPolicy。请求的回复和已授权的任务结果 保留其现有的完成权限。参见 会话工具。

旧版本不会强制执行这些偏好。在降级之前,请删除 新的配置键,并通过旧版本的工具和会话策略恢复任何限制。

会话

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    groupScope: "per-group", // main | per-group
    notifyOnCreate: true, // notify Home about new sessions (default)
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 30 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "enforce", // enforce (default) | warn
      pruneAfter: "30d",
      archiveDashboardAfter: "7d", // false or 0 disables this dashboard trigger
      maxEntries: 5000,
      preserveRecent: "7d", // opt-in protection; disabled when omitted or false
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // physical disk budget; default "10gb"
      highWaterBytes: "400mb", // optional cleanup target
      coldStorage: {
        enabled: false, // opt in to compressed inactive transcripts
        afterDays: 30,
      },
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unbind in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    sharing: {
      readOnly: true,
      suggest: true,
      drafts: true,
    },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}
会话字段详情
  • scope:群聊上下文中的基础会话分组策略。
  • per-sender(默认):每个发送者在频道上下文中获得一个隔离的会话。
  • global:频道上下文中的所有参与者共享一个会话(仅在有意共享上下文时使用)。
  • dmScope:私聊如何分组。
  • main:所有私聊共享主会话。
  • per-peer:跨频道按发送者 ID 隔离。
  • per-channel-peer:按频道 + 发送者隔离(推荐用于多用户收件箱)。
  • per-account-channel-peer:按账户 + 频道 + 发送者隔离(推荐用于多账户)。
  • groupScope:群组、房间和频道如何分组。
  • per-group(默认):让每个非直接对端保留在其频道范围内的会话中。
  • main:将非直接对端路由到代理主会话。当只有选定的受信任房间应共享主上下文时,优先使用较窄的 bindings[].session.groupScope 覆盖。
  • notifyOnCreate:在拥有该会话的代理的 Home 对话中排队新会话感知(默认:true)。待创建项共享一个有界摘要,包含可用的标题、创建者和创建来源,而不复制消息。当摘要已满时,较旧的条目会被省略,为提醒和其他事件保留队列容量。Home 会在下一轮或计划的心跳中消费它。设置 false 可禁用。草稿、隐身会话、Home 本身、隐藏的内部会话以及计划 cron 运行会被排除;重新打开或重置现有会话不会再次通知。摘要在内存中,Gateway 重启后不会保留。参见 主会话。
  • identityLinks:将规范 ID 映射到带提供商前缀的对端,用于跨频道会话共享。
  • resetTriggers:重置会话的显式命令或短语。匹配不区分大小写;由于命令别名不会自动添加,请列出每种期望的拼写。例如,["/tell"] 会重置 /tell 消息,而 /steer 保持其正常的转向行为。匹配触发器之后的后续文本会被保留,包括后续行。
  • reset:主要重置策略。none 禁用自动重置,并且是默认值;压缩改为限制活动上下文。daily 在本地时间 atHour 重置;idle 在 idleMinutes 后重置。当两者都配置时,先过期的生效。/new 和 /reset 在所有模式下都可用。每日重置的新鲜度使用会话行的 sessionStartedAt;空闲重置的新鲜度使用 lastInteractionAt。后台/系统事件写入,例如心跳、cron 唤醒、exec 通知和 gateway 簿记,可以更新 updatedAt,但它们不会保持每日/空闲会话的新鲜状态。
  • resetByType:按类型覆盖(direct、group、thread)。Doctor 会将旧版 dm 条目迁移到 direct;模式拒绝 dm。
  • resetByChannel:按提供商/频道 ID 键控的按频道重置覆盖。当会话的频道有匹配条目时,它对该会话完全优先于 resetByType/reset。仅当一个频道需要与类型级策略不同的重置行为时使用。
  • mainKey:接受但忽略。每个代理的主会话后缀始终是 main;省略此字段。全局会话范围改用 global。
  • sendPolicy:按 channel、chatType(direct|group|channel,带有旧版 dm 别名)、keyPrefix 或 rawKeyPrefix 匹配。第一个拒绝生效。
  • maintenance:会话存储清理 + 保留控制。
  • mode:enforce 应用基于年龄、数量和磁盘预算的清理,并且是默认值;warn 报告这些策略但不应用它们。独立的可选 coldStorage.enabled 开关独立控制冷转录提取。
  • pruneAfter:陈旧条目的年龄截止值(默认 30d)。符合条件的持久会话会就地归档,其身份和历史记录保持完整;这不会压缩或提取其转录行。可丢弃的自动化行会被删除。
  • archiveDashboardAfter:归档可见仪表板会话的不活动截止值(默认 7d);false 或 0 仅禁用此仪表板触发器。符合条件的会话仍可由 pruneAfter 或 maxEntries 归档。
  • maxEntries:未归档 SQLite 会话条目的最大数量(默认 5000)。已归档行不占用上限。清理会归档最旧的符合条件的普通会话,而合成运行时会话仍保持可丢弃并可能被删除。固定会话、活动或已接受的工作、模型锁定会话以及持久外部对话指针仍受保护;如果保护阻止达到上限,未归档存储将保持高于上限。运行时写入会为生产规模的上限以小的高水位缓冲批量清理;openclaw sessions cleanup --enforce 会立即应用上限,但不会取消保护行。
  • preserveRecent:可选的不活动窗口,保护最近活动的交互式会话及其所有 SQLite 历史代免受自动基于年龄、数量和磁盘预算的历史驱逐(例如 "7d")。未设置或 false 会禁用此保护。合成 model-run、cron、hook、heartbeat、ACP 和子代理会话仍符合有界清理条件。保护可以暂时使存储高于配置的条目或磁盘目标,并且不会归档会话。
  • 短生命周期的 gateway model-run 检查会话使用固定的 24h 保留期,但清理受压力门控:只有当会话条目维护/上限压力达到时,它才会删除陈旧的严格 model-run 检查行。只有匹配 agent:*:explicit:model-run-<uuid> 的严格显式检查键才符合条件;普通的 direct、group、thread、cron、hook、heartbeat、ACP 和子代理会话不会继承此 24h 保留期。当 model-run 清理运行时,它先于更广泛的 pruneAfter 陈旧条目清理和 maxEntries 上限运行。
  • 旧版 rotateBytes 被当前模式拒绝;openclaw doctor --fix 会从旧配置中移除它。
  • resetArchiveRetention:重置/删除转录归档的基于年龄的保留期。默认情况下,归档保留直到磁盘预算驱逐;设置持续时间可选择按墙钟时间删除,或 false 显式禁用。
  • maxDiskBytes:每个代理的物理磁盘预算(默认 10gb),计算 SQLite 主文件、其 -wal 文件以及代理会话目录中计入的文件。在 warn 模式下,它会记录警告。在 enforce 模式下,它首先回收可检查点的数据库空间,然后删除旧的重置/删除产物、未引用的历史代,最后删除被活动会话上限明确标记为已归档的最旧会话。手动、旧版、年龄保留、陈旧仪表板和恢复归档仍受保护。受保护的历史记录和暂时无法回收的数据库页面可能使使用量高于清理目标;这不是保证的物理上限。设置 false、0 或 "0" 可完全禁用预算。
  • highWaterBytes:预算清理后的可选目标。默认为 maxDiskBytes 的 80%。解析为零的值会回退到默认值;负值无效。使用 maxDiskBytes 禁用预算,而不是使用零高水位标记。
  • coldStorage.enabled:可选的后台提取不活动转录到压缩 JSONL 文件(默认 false)。当前和历史窗口可能符合条件;活动运行、已接受的工作和恢复拥有的会话保持受保护。这独立于仪表板归档和重置/删除归档保留期。参见 冷转录存储。
  • coldStorage.afterDays:转录符合条件之前的不活动天数,正整数(默认 30)。最近的会话活动保护当前窗口;历史窗口使用其自身的活动时间戳。活动工作、恢复和显式历史引用仍保护它们所需的转录。工作器会应用当前策略,而不需要新的聊天活动。更改这些设置无需重启 Gateway 即可生效;禁用提取会保留已归档历史可读。
  • threadBindings:线程绑定会话功能的全局默认值。
  • enabled:支持的频道线程绑定的主开关
  • idleHours:默认不活动自动解绑小时数(0 禁用;提供商可覆盖)
  • maxAgeHours:默认硬性最大年龄小时数(0 禁用;提供商可覆盖)
  • spawnSessions: 用于从 sessions_spawn 和 ACP 线程派生创建线程绑定工作会话的默认门控。Agent 派生始终创建新的子线程,并且从不绑定当前会话。当线程绑定启用时默认为 true;提供商/账户可以覆盖。

    • defaultSpawnContext: 线程绑定派生的默认原生子代理上下文("fork" 或 "isolated")。默认为 "fork"。
    • sharing: 控制所有者和 operator.admin 连接可以选择哪些按会话协作模式。每个标志默认为 true;将其设置为 false 会从 Control UI 中移除该选项,并使创建时的可见性或 session.visibility.set 拒绝它。新会话以 shared 开始,除非 Control UI 将其作为草稿启动。
    • readOnly: 允许 read-only,非成员可以查看,但不能发送、引导、中止、批准或修改会话状态。
    • suggest: 允许 suggest,查看者可以提交建议,供会话所有者或 operator.admin 连接发送、排队、编辑或忽略,而无需授予直接发送或管理会话的权限。
    • drafts: 允许 draft,该模式会将会话从非管理员、非所有者的会话列表和事件广播中隐藏。

    会话可见性和成员身份作为规范共享状态维护。结构化 session.sharing 事件携带可归因的操作者;无主体变更使用附加的 session.sharing.evidence 事件。每次共享变更还会发出已有的 sessions.changed 行刷新,因此不识别证据事件的客户端仍会刷新规范状态。这些事件和 session.suggestion 不会向会话转录中添加管理叙述。这些控制用于协调共享一个 Agent 的操作者;它们不是租户之间的安全边界。当工作需要隔离时,请使用独立的 Gateway 或 Agent。

冷存储

在 设置 → 代理默认值 → 会话 中,会话存储 面板显示 SQLite 和压缩归档中的转录计数、数据库和 WAL 大小、归档文件字节数,以及嵌入 SQLite 的压缩归档字节数。嵌入字节数已包含在数据库总计中;请勿再次相加。该面板还显示最新的后台维护结果,并分别统计新归档的转录和移回文件的嵌入归档。展开 按代理查看详情 以比较 Agent,或选择 刷新 以读取当前使用情况。需要管理员访问权限。

打开 归档较旧的转录,并将 归档后(天数) 设置为正整数。更改通过常规设置流程保存,并无需重启 Gateway 即可生效。策略保存并应用后,立即运行 会启动或加入后台批处理并快速返回。面板会跟踪其状态,直到完成或失败;离开页面不会停止工作进程。即使没有新的聊天活动,工作进程也会自动运行。当前和历史转录中不活跃的部分可以变为冷数据;打开或恢复其中一个会在使用前恢复其历史记录。

冷归档保存权威历史记录。受支持的 OpenClaw 备份命令会随数据库一起捕获其已验证内容;直接数据库复制还必须保留所引用的文件。请参阅 冷转录存储 了解适用条件和恢复,并在启用该功能前参阅 冷转录备份。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw