#bots.json 配置

通过 ~/.botmux/bots.json 配置机器人。运行 botmux setup 交互式创建，或手动编辑。文件是一个数组，每个元素是一个 bot（生产环境一个 bot 对应一个独立 daemon 进程）。

多数字段可选——只填 larkAppId / larkAppSecret 就能跑起来，其余按需增配。适用：想手动调 CLI / 模型 / 工作目录 / 权限 / 沙箱等；日常配置更推荐用 dashboard 的 Bot 配置页（改的是同一份 bots.json）。改完 botmux restart 生效。

[
  {
    "larkAppId": "cli_xxx_bot1",
    "larkAppSecret": "secret_1",
    "name": "claude-main",
    "cliId": "claude-code",
    "model": "sonnet",
    "lang": "zh",
    "workingDir": "~/projects",
    "allowedUsers": ["alice@company.com"],
    "allowedChatGroups": ["oc_xxx_team"],
    "p2pOpen": true,
    "oncallChats": [{ "chatId": "oc_xxx_oncall", "workingDir": "~/projects/foo" }]
  },
  {
    "larkAppId": "cli_xxx_bot2",
    "larkAppSecret": "secret_2",
    "cliId": "codex",
    "model": "gpt-5-codex",
    "workingDir": "~/work",
    "autoStartOnNewTopic": true
  }
]

字段较多，按用途分组列出，绝大多数都是可选的——只填 larkAppId / larkAppSecret 就能跑起来，其余按需增配。

#必填

#CLI 与模型

#Codex 兼容发行版

如果一个独立发行的 CLI 完整保留 Codex 的参数、交互、rollout / resume 和认证语义，不需要为它新增 cliId。保留协议适配器 cliId: "codex"，再声明具体运行时：

{
  "cliId": "codex",
  "cliPathOverride": "vendor-codex",
  "cliRuntime": {
    "id": "vendor-codex",
    "displayName": "Vendor Codex",
    "executable": "vendor-codex",
    "update": { "provider": "npm", "packageName": "@vendor/codex" }
  }
}

• id 是稳定身份，只能使用字母、数字、.、_、-，最长 64 个字符；改名会被视为切换发行版。
• executable 是一个可执行文件名或路径，不是 shell 命令；不要在里面拼参数。Dashboard 保存时会执行只读的 --version 预检，输出需包含可识别的 X.Y.Z 版本号。
• displayName 只影响卡片、状态与 Dashboard 展示，省略时使用 id。
• update.provider 可选 auto、self、npm、none。auto 只信任可精确追溯到该二进制的唯一 npm 包；无法确定来源时标记为“未托管”，绝不拿官方 Codex 的版本号比较。self 才会使用 CLI 自报的结构化 doctor 信息，并要求其中的当前版本与 --version 一致；npm 必须同时给自己的 packageName；none 关闭该运行时的更新检查。
• cliRuntime 目前只支持 cliId: "codex"，不能和 wrapperCli 同时使用。BotMux 写入配置时会生成一个与 executable 完全相同的 cliPathOverride 降级影子；新版本以 cliRuntime 为准，旧版本仍能从影子启动同一二进制。手工配置时也必须像上例一样同时写入这个等值影子；缺失或不相等都会直接校验失败，避免出现只能升级、不能安全降级的配置。wrapper / 网关仍走下面的旧入口覆盖机制。
• 旧 cliPathOverride 配置不会失效；BotMux 会继续启动它，并对更新探测采取同样的安全 auto 策略。Dashboard 会把它显示为只读兼容态：只改模型会保留旧入口，显式选择 Official Codex 才会清除，也可选择“自定义兼容版”迁移到 cliRuntime。由于旧字段无法证明完整兼容契约，Codex RPC 等增强能力仍保持关闭。

会话创建时会冻结自己的 runtime 快照。只修改模型仅影响新会话；切换 CLI、runtime 或 wrapper 时，BotMux 会立即关闭仍使用旧启动身份的活跃会话，避免它们之后 lazy resume 到错误的发行版。存量会话不会被静默换用另一 runtime。

#接入 GLM / 第三方服务商（per-bot env）

让某个 bot 跑 GLM Coding Plan（或其它 Anthropic 兼容服务商），另一个 bot 仍跑官方 Claude——给前者配 env：

{
  "cliId": "claude-code",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你的 GLM Coding Plan key"
  }
}

• GLM 国内站把 ANTHROPIC_BASE_URL 换成 https://open.bigmodel.cn/api/anthropic。
• 给 Codex 这类 OpenAI 协议 CLI 接入时，填 OPENAI_BASE_URL / OPENAI_API_KEY（服务商的 OpenAI 兼容端点）而非 ANTHROPIC_*。
• 隔离：env 按会话注入到 CLI 进程，全后端一致（tmux / zellij 经每个 pane 注入，绝不写共享 server 全局），所以一个 bot 的服务商配置不会串到别的 bot。
• 安全：值以明文存在 bots.json 与进程环境，不是密钥保险箱；/config get 等聊天面会脱敏显示（dashboard 编辑器 owner 鉴权后显示原值）。
• 改完下个新会话生效。

#Codex App 纯净输入（实验性）

codexAppCleanInput 用于清理 Codex App 中显示的用户消息，同时保留 Botmux 调用模型所需的上下文。默认值为 false / off，关闭时完全沿用原来的组合 prompt 行为。

可由 owner / allowedUsers 通过 /botconfig 热更新，无需重启 daemon：

/botconfig set codexAppCleanInput on
/botconfig set codexAppCleanInput off

也可直接写进对应 bot 的配置（手改 bots.json 后仍按本文末尾说明重启）：

{
  "cliId": "codex-app",
  "codexAppCleanInput": true
}

• 仅 Botmux 托管且 session 实际 CLI 为 codex-app 时使用此开关；其它 CLI 和 /adopt 外部桥接 session 不受影响。session 已冻结的 CLI 优先于后来修改的 bot 默认 CLI。
• 开启后，用户发起的 turn 以用户原文作为 Codex App 的文本 UserMessage；Botmux 自己发起的 external trigger、文档预热等合成 turn 使用简短可读标签。sender、mentions、附件路径、引用、role、whiteboard、Skills 和合成 turn 的内部指令等上下文主要通过隐藏的 additionalContext 提供。可读的绝对路径图片还会作为 localImage 输入；缺失、相对或不可读图片会跳过原生图片项并记录提示，但附件路径仍留在上下文中。
• 可识别的 Codex CLI >= 0.135 才启用纯净文本和 additionalContext；>= 0.136 时还会附带独立的 clientUserMessageId。版本过旧或无法识别时直接使用 legacy 组合 prompt。
• 只有 app-server 在 turn/started 前明确拒绝 additionalContext / clientUserMessageId 实验字段时，runner 才用 legacy prompt 重试一次，并在该 runner 生命周期内关闭纯净模式。网络、超时、模型或一般 turn 错误不会自动重试，以免重复执行。
• /botconfig 切换在下一次派发给 Codex worker时采样；普通 live 消息通常就是下一条消息，等待 repo 选择的首轮则在 repo commit 时采样。已排队或正在执行的 turn 不会被中途改写，也不会回填既有历史。
• additionalContext 不出现在 Codex App 的普通用户消息气泡中，但仍可能保存在原始 rollout / 诊断记录里。开启时 Botmux 自身也会保留 legacy prompt 与结构化 sidecar 以支持兼容降级和 retry_last_task。此功能只解决 App 展示与普通历史阅读的整洁度，不是隐私擦除或安全脱敏机制。

#工作目录

#权限与授权

#文件沙盒

ZMX 无法执行文件沙盒或实际生效的读隔离，开启这些边界的配置组合会 fail closed，详见 ZMX 后端边界。

#卡片与终端

#主动开工

#群消息监听

让 Bot 主动盯住某个群：命中条件的群消息无需 @ 就自动拉起一个会话去处理。典型用途是报警运维——监控/告警系统本来就有自己的飞书机器人在往群里发告警，把这个 Bot 拉进那个群、开启监听，每条告警自动开工排查，不必额外配 Webhook 接入点。

推荐在 Dashboard「角色 → 消息监听」 里按群配置（可预览最近 24h 命中的消息、试运行验证效果）；也可直接写 bots.json 的 messageListeners（键为 chat_id，值为下表配置）：

{
  "messageListeners": {
    "oc_xxxxxxxxxxxxxxxx": {
      "enabled": true,
      "name": "告警监听",
      "prompt": "群里每条告警都是线上事件。定位受影响服务、给出初步排查方向；确认是误报就说明理由。",
      "senderPolicy": { "mode": "all_except_excluded", "includeSenderTypes": ["bot"] }
    }
  }
}

约定与边界（V1）:

• 只处理群聊顶层消息：已有话题里的普通回复不处理；显式 @ 本 Bot 的消息仍走普通 @ 路由（不重复触发）。
• 每条命中消息各拉起一个会话，回复到该消息下方的新话题。
• 触达方式：实时事件路径覆盖飞书推送到的消息；其他机器人发的、以及未 @ 的消息，靠约 30s 一次的历史轮询补齐（即最长约 30s 延迟）。所以监听第三方告警机器人时用黑名单模式（all_except_excluded + 含 "bot"）最稳——白名单按 open_id 匹配，而历史接口里第三方机器人按 app_id 上报、可能解析不出 open_id 从而命中不到。

#总结命令

示例：

{
  "summaryRange": {
    "limit": 50,
    "sinceHours": 24
  },
  "summaryMemory": true,
  "summaryMemoryPath": "docs/summary.md"
}

• 只有显式 @机器人 /summary 会触发总结；不 @ 机器人时仍按普通群/话题的既有路由规则处理，不会因为关键词自动唤醒。
• dashboard 的「/summary 总结范围」保存的就是 summaryRange；「开启记忆」开关与「记忆文件路径」输入框分别保存 summaryMemory 与 summaryMemoryPath。
• 如果本次触发前存在上一条 @同一机器人 /summary，总结窗口只包含上一条之后到本次触发为止的消息；找不到上一条时回退到 limit / sinceHours。
• limit 与 sinceHours 是默认（无显式边界）总结窗口的安全上限；两者都为 0 时表示不做该维度限制。显式边界按设计优先于该上限：当 summaryMemory 开启且 /summary 带了边界文字时，botmux 尊重用户「从这条起」的明确意图，从命中的边界消息起全部纳入——普通群里 limit 仍约束扫描量，但比 sinceHours 更早的边界、以及话题群里任意早的边界都会被接受，可能超出默认配置范围。若不希望某个 bot 读入过旧内容，最可靠的做法是不要带边界文字；普通群还可以调低 limit 约束扫描量（但 sinceHours、以及话题群里的边界都不受配置范围约束）。
• 仅当 summaryMemory 开启时，/summary 命令后跟随的文字会被当作「硬边界」：在触发前的历史里定位最近一条包含该文字的消息，只总结从这条到本次触发为止的内容；如果扫描到的历史里找不到该边界，则不回退到更宽范围，而是把「未找到边界」错误与空历史一起交给 agent（此时记忆写入指令仍会执行）。summaryMemory 关闭时，/summary 后的文字仅作为对本次总结的侧重提示，历史窗口仍按 summaryRange 读取。
• 记忆文件由 agent 在其工作目录内写入。如果 bot 开启了 sandbox，且 summaryMemoryPath 指向工作目录之外（绝对路径，或用 ../ 逃出工作目录的相对路径），请把该文件已存在的父目录加进 sandboxPaths.readWrite；worker 在 spawn 时会过滤掉尚不存在的路径，而新记忆文件通常还不存在，所以只加文件本身会被丢弃（除非文件已预先创建）。否则写入可能被沙盒拒绝。

#旧内容触发配置

#语音

#会议监听角色与群内输出形式

vcMeetingAgent.meetingConsumer.consumerProfiles 可以定义通用的会议监听角色。responseMode 与 listenerDelivery.placement 是两个独立维度：

Dashboard 的“会议角色预设”提供本地内置模板库，当前包含“会议重要信息同步”“会议纪要与行动项”“会议主持”“方案评审与风险挑战”“访谈与需求洞察”。点击“使用此模板”会复制出一个普通、可完整编辑的 profile；之后修改模板不会改写用户配置。模板目录带稳定的 templateId、版本和来源，未来可以在同一模型上接入社区源。本期不联网、不上传模板使用情况，因此不提供热度或使用量排行。

• responseMode: "silent"：自动模型输出不可见；适合只做内部处理或通过受管会议能力执行动作。
• responseMode: "listener_thread"：允许把自动模型输出发到会议监听群，需要 listener.output.request capability。
• listenerDelivery.placement: "auto"：兼容旧行为，沿用当前会话的群/话题路由；省略该字段等同于 auto。
• listenerDelivery.placement: "chat"：每次同步都作为群顶层消息发送。
• listenerDelivery.placement: "topic"：首条有效同步作为固定话题根消息，后续同步都回复到同一话题；移除并重新启用该 profile 后会开启新话题。

listener_thread 的自动输出使用 botmux 内部的 skip | publish 控制协议：Agent 判断当前是否值得发布，botmux 只在 publish 时把消息正文发到飞书，控制 JSON 本身不会出现在群里。该协议不做语义指纹去重，也不提供 debounce/interval 配置；是否为新信息、是否继续观察以及何时发布，都由 Agent 根据 profile prompt 和完整会议上下文判断。格式异常会 fail closed，不会把模型原始控制文本发到群里。显式人工消息仍按原引用关系回复，不走此协议。

下面是一个“会议重要信息同步”预设。它不包含事故专用结构，只通过 prompt 定义“什么值得同步”，因此也适用于项目评审、发布协调等会议：

{
  "id": "important-sync",
  "agentAppId": "cli_your_agent_app_id",
  "label": "会议重要信息同步",
  "role": "important-information-sync",
  "instructions": "持续监听会议，只发布对群内协作者有实际价值的新信息：已确认的结论或决定、状态变化、明确阻塞或风险、需要群内人员知晓或行动的事项。讨论尚未形成明确变化时先不发布；是否继续观察以及何时发布，由你根据会议语义自行判断。忽略讨论过程、重复表述、寒暄和未经确认的猜测。每次只发布相对上次的新内容，使用简洁中文；有负责人、截止时间或影响范围时一并写明。此前信息的时间、负责人、范围、状态或结论发生修正时，必须作为新信息发布，不能因为其他内容大部分一致而忽略。字幕发生修订时重新判断，但不要重复发布未发生变化的事项。",
  "filter": {
    "activityTypes": ["transcript_received", "chat_received"]
  },
  "responseMode": "listener_thread",
  "listenerDelivery": {
    "placement": "topic"
  },
  "capabilities": ["listener.output.request", "meeting.read"]
}

agentAppId 是实际执行该角色的 bot App ID。把 profile id 加入 defaultConsumerIds，并将 defaultMode 设为 agents，可让它在监听开始时默认启用；否则可在会中消费者选择卡片里手动启用。

#运行时状态（自动维护，勿手改）

下列字段由 botmux 自身写入并随授权 / 开关一起持久化进 bots.json，列出仅为说明，不要手动编辑：

配置优先级：BOTS_CONFIG 环境变量 → ~/.botmux/bots.json。改完跑 botmux restart 生效。