配置

默认情况下，Collie 仅响应你通过 collie pair 配对的设备。已配对的设备拥有完全控制权，因此 tailnet 上能访问该 URL 的任何人仍需先有一部配对的手机。若没有 COLLIE_TRUSTED_USER，bridge 会打印一条 TRUSTED_USER 警告，因为每个 tailnet 登录都可以访问配对屏幕。进一步限制访问：

# in your .env
COLLIE_TRUSTED_USER=you@example.com           # your tailnet login — Collie rejects anyone else
COLLIE_PUBLIC_HOSTS=myhost.tail1234.ts.net    # only behind your OWN proxy; on a tailnet `collie
                                              # start` discovers this for you

配置文件

Collie 的每项设置均可写入 TOML 文件中。生成一个包含所有设置及其默认值的文件：

collie config init

这会写入机器专属声明 ~/.collie/config.toml 并输出路径。其中的每个键均已被注释，因此写入的文件不会改变任何行为：取消某项键的注释并重启即可。改用运行 collie config init --instance 则会在你的 .env 旁写入 config.toml，该文件仅针对当前实例覆盖机器级配置文件。

实例文件按键逐个覆盖，绝非按文件覆盖：实例文件中缺失的键保留机器文件的值。不存在 config.<instance>.toml，因为在 Herdr 管理的安装中，配置目录本身就是按实例划分的，而在二进制安装中则是 ~/.config/collie。因此同一主机上的第二个 Collie 会把自己的配置放在它自有的配置目录中，参见 docs/deployment.md → 单台主机上的多个 Collie。项目目录内的 .collie/ 完全不会被读取。

操作该文件的三个动词：

1. 01
   collie config init 写入一个包含所有配置项及其默认值的带注释文件。
2. 02
   collie config check 校验将被读取的两个文件，或校验你指定的一个文件。
3. 03
   collie config show 打印两个路径以及每个配置项的值和来源。

优先级顺序依次为：默认值、~/.collie/config.toml、<config-dir>/config.toml、进程环境（包含你的 .env）。collie config show 会同时列出每个键的胜出者，因此“为什么我的轮询间隔仍是 1500”能在一行中得到解答。

损坏的键绝不会中止 bridge。未知的键或错误的类型是 collie config check 会打印、collie doctor 会报告的问题，并且只有该键会回退到环境变量所指定的值。文件中的其余所有键仍然生效。

Collie 仅在启动时读取 config.toml。修改后请运行 collie restart。

注意。 包含 [push] vapid_private 或 [stt] stt_key 的文件会被强制设为 600 模式，正如你的 .env 一样。如果 Collie 无法收紧权限，则仅忽略这些键，且 collie doctor 会予以说明。

环境变量仍然优先

Collie 从 ~/.config/collie 中的 .env 文件加载配置。如果安装由 Herdr 管理，CLI 会向 Herdr 查询插件配置目录（通常为 ~/.config/herdr/plugins/config/herdr.collie）。两个路径在不同 CLI 命令之间均能一致解析，因此服务会读取在此处初始化的文件：

mkdir -p ~/.config/collie && cp .env.example ~/.config/collie/.env

# on a Herdr-managed install, seed Herdr's plugin config dir instead:
cp .env.example "$(herdr plugin config-dir herdr.collie)/.env"

下文中的路径使用 ~/.config/collie/…。在由 Herdr 管理的安装中，将该前缀替换为 $(herdr plugin config-dir herdr.collie)。

Collie 仅在启动时读取 .env。修改后请运行 collie restart。

.env.example 文件列出了所有选项，collie config init --print 也是如此。

它包含 COLLIE_PORT、COLLIE_SERVE_MODE=http（用于 Headscale 或 .internal 域名）以及 COLLIE_SERVE_PORT（用于在 :443 以外的端口上暴露 HTTPS；参见 docs/deployment.md → 单台主机上的多个 Collie）。CLI 会读取 serve 参数来配置 tailscale serve，而不是将其传递给 bridge。

各部分包含的内容

配置文件将所有配置项归组在 [section] 下。某个键的环境变量名称是 COLLIE_ 加上该键的大写形式，因此 [bridge] poll_ms 对应 COLLIE_POLL_MS。

单个 Collie 在其多路复用器旁运行的 durable agent 不在 config.toml 中。每个均为 sources.json 中的一项，与 .env 位于同一文件夹（持久 agent）。| stt | 语音转文字，在 collie stt setup 运行前不存在 |

若要从多个 agent 主目录读取历史记录，请在 COLLIE_TRANSCRIPT_ROOT 中提供一个逗号分隔的列表。

docs/deployment.md 涵盖自定义域名和反向代理。Collie 强制执行同源策略，因此任何自定义主机名或外部 TLS 终止器都必须明确加入允许列表：

COLLIE_ALLOWED_ORIGINS=https://collie.example.com

若无此设置，UI 将加载为空白页面。详情请参见 问题排查。

自定义斜杠命令

将特定于机器的命令（例如 Herdr 插件 /fork-in-herdr 或自定义 /deploy）放入 commands.toml。这是共用相同读取器和加载模式的六个配置文件之一：

配置文件不会改动这些文件。它们与实例 config.toml 的目录共享位置，保留各自的格式与热重载机制，也不会被合并进去。

任何设置了该标志的行在触发前都需要进行二次点击确认。对这些文件中任一文件的修改均无需重启服务即可生效。如果 Collie 拒绝某一行，journalctl --user -u collie -n 20 会输出行号和错误信息。

cp commands.toml.example ~/.config/collie/commands.toml

[[commands]]
scope = "omp"                # optional; omit for every pane
command = "/fork-in-herdr"
description = "Fork this conversation into a new herdr tab"

[[commands]]
scope = "claude"
command = "/statusline"
description = "Set the status line"
bar = true
bar_label = "Status"

匹配你配置行的窗格仅显示这些行。最狭窄的行优先，如 ADR 0018 中所述。

要进行验证，请打开一个窗格并点击 /；你的行会显示在第一个屏幕上。

将命令放入操作栏

bar = true 还会将该行放入操作栏（键盘上方的那一行按钮）。栏行本身仍是普通的面板行，因此在两个界面上都会出现。bar_label 为按钮文本，默认值为不带斜杠的命令名称。

操作栏是一条通栏色带，位于键盘正上方。Collie 自带的控件直接位于色带上：Keys、Type、Quick、Agent 以及显示设置齿轮。当前运行 harness 的自带命令位于它们旁边，该区域带有该 harness 的品牌色底色，方便一眼看出哪些按钮会向 agent 输入内容。横向拖动可滚动色带，不会丢弃任何内容。

各 harness 随附各自的按钮，顺序如下：

Codex、Grok 和 Antigravity 没有 Effort 按钮，因为它们的 /model 选择器同时也会设置推理强度。在 Grok 中只输入 /effort 不会打开任何选择器。

pi 和 opencode 没有 effort 命令。pi 将该调节选项保留在 /settings 内部，这是一个按键面板无法有效操作的模态窗口；而 opencode 通过快捷键循环切换变体。

opencode 以自己的方式命名了两个按钮：Model 发送 /models，Resume 发送 /sessions。它的 Compact 必须在会话包含至少一个轮次后才有效，因为 opencode 仅在那时才提供 /compact。

omp 的 Tree 按钮位于 Compact 和 Resume 之间。它会在镜像中打开 omp 自带的会话树，这是一个可跳转到会话中此前任意位置的选择器。同一命令 /tree 也存在于 omp 的命令面板中。

每个 harness 按钮都会直接发送裸命令。Model 发送 /model，随后 agent 自带的模型选择器会在窗格中接管操作。 Collie 不维护模型名称列表，因为该列表属于 harness，且发生变更时不会通知我们。Effort 的运作方式与之相同。

你的栏行仅会替换其所针对窗格中随附的 harness 分段，其他窗格保持不变。Agent 面板属于独立界面，栏行绝不会将其置空（ADR 0043）。

长度超过 12 个字符的 bar_label 会被截短，但按钮仍会显示。既非 true 也非 false 的 bar 会直接丢弃该行，处理方式与无效的 confirm 相同。

即使 agent 正忙，该行也能发送内容，与命令面板一致。仅当窗格接收了文本后才会显示对勾。

Switch 按钮位于色带最右侧，用于打开窗格切换器。它仅在细线后绘制图层图标，不包含文字。在色带任意位置向上拖动均可打开同一切换器。横向拖动则为滚动色带。

Files 按钮左侧的 agents 标记统计该窗格正在运行的子 agent 数量。对于 omp 和 Gentle Shell，仅当在手机上打开该窗格的 Chat 时，才会统计其后台作业；Screen 视图不统计它们。

当文本框包含文本或附件时，功能栏最右侧的 Switch 按钮左边也会显示一个 X。点击一次会清空文本框及其保存的草稿，且不会向窗格发送任何内容。随后 X 会变成 Undo，点击可恢复文本和附件。Undo 会一直保留，直到你执行下一次操作：按键、添加附件、发送、点击功能栏上的其他按钮，或离开窗格。滚动功能栏会保留该按钮。

习惯左手操作？将 Settings → Appearance → Hand 设为 Left。工具栏会调换方向：Switch 按钮和 X 移至其左端，仍位于 Send 上方，Keys 变为最右侧的按钮，其余按钮向左滚动。Send 和 Attach 移至回复框的左侧。该设置按设备区分，并在下次打开窗格时生效。

若要验证，请打开运行 Claude Code、Codex、pi 或 omp 的窗格；着色分段位于键盘上方那一行的右侧。可在 设置 → 外观 → Harness 快捷键 中按设备关闭该分段；Collie 自带的控件仍会保留。

停止轮次

停止 按钮位于操作栏的最前端，排在 Collie 的其他按钮之前，无需滚动即可看到。只要 agent 的 harness 配置文件指定了停止按键，该按钮就会出现在那里；没有任务运行时它会变暗。它保持位置和大小不变，因此轮次开始或结束时其他按钮绝不会移动。点击变暗的按钮不会执行任何操作，也不会发送任何内容。没有指定停止按键的 agent 则没有此按钮。Stop 不会输入任何内容，也不会发送消息。它只会按一次 agent 自己的停止按键，并提示执行结果。

Stop 需要点击两次。第一次点击会就绪该按钮：文字变为 Stop? 且按钮保持大小不变。在 4 秒内再次点击即可停止轮次。若在 0.4 秒内紧接着完成第二次点击，会被视为同一次触碰并予以忽略。如果超时未点，就绪状态失效且不会按下任何键。当你打开另一个窗格时就绪状态也会失效，轮次结束时按钮变暗。第二次点击正在处理期间，按钮不再接收点击，因此快速的第三次点击不会触发第二次 Stop。

具体由哪个键来停止轮次取决于 harness 自身，由 harness 配置文件记录。大多数 agent 按 Escape 停止，部分按 Ctrl+C，还有些需要按两次 Escape。具体由配置文件决定，而不是本页面。

按键输入后，Collie 会在最多 3 秒内重新读取屏幕，并在输入框下方提示以下三种情况之一：

如果停止按键反而打开了对话框，Collie 会说明情况并引导你查看其卡片。

包括 OMP 在内的一些 agent，会在您停止轮次时将排队的消息放回其输入框中。当 Collie 在按键后立即在输入框中检测到它时，回执会进行说明，例如：“已停止。1 条排队的消息已作为草稿返回 agent。”在 Chat 中，消息会移动到 已返回输入框 卡片中。一起返回的消息共享同一张卡片。

该卡片有两个按钮，两者都会先重新读取输入框。发送 仅在轮次空闲且输入框完全保留该文本时发送草稿。舍弃 仅在输入框仍保留该文本时清空输入框；如果您修改了文本，“舍弃”会移除卡片且不执行任何按键操作。草稿存在期间，新消息会被拒绝，拒绝提示会将您引导至该卡片。

当按键可能带来破坏时，Collie 会在按下前直接拒绝：

• —
  A dialog is open. 按下 Escape 会直接对该对话框作出响应。请改在其卡片上作出响应。
• —
  The box holds your text, and this harness's stop key would clear it. 清空输入框，或使用按键面板上的 Clear 按钮，然后再次点击 Stop。
• —
  Collie cannot read this pane. Collie 不会向无法读取的屏幕发送按键。这也包括 Collie 无法判断轮次是否在运行的屏幕。
• —
  The turn had already ended. 没有正在运行的任务需要停止，因此未按下任何键。
• —
  This machine cannot stop from the phone yet. 在 crew 环境下，运行该窗格的机器安装了较旧版本的 Collie。请先更新，然后再执行停止。

如果在规定时间内没有收到来自 crew 机器的响应，Collie 会作出提示。Stop 可能已经输入，因此在再次点击 Stop 之前请先检查该窗格。

Stop 始终由你手动点击触发。对讲消息、hook、命令行以及排队操作绝不会自动按下该键。在 crew 环境下，运行该窗格的机器负责按下按键、读取屏幕，并通过 lead 发回执行回执。

作为持久 agent 运行的程序会保留其已有的 Stop。它通过自己的凭据停止所指定的轮次，且不使用 arm。

清空输入框

Keys 键盘 chip 行末尾的 Clear 按钮可一键清空 harness 的输入框，无需 arm。Collie 会根据文本长度按 harness 自身的删除键，重新读取输入框，并在 belt 上方的通知中告知输入框是否已清空或未清空的原因。当输入框为空、对话框处于打开状态或连接断开时，该按钮变灰；若输入框未能清空，Collie 会保留剩余内容并不再按键。

执行 Clear 后，通知会提供 恢复 选项，持续两分钟。点击一次即可将文本重新输入到框中，呈单行且不带 Enter，因此不会发送任何内容。一旦你再次在框中输入或打开另一个窗格，Restore 就会消失。bridge 会将清空的文本与 Clear 凭据一起保存在内存中，绝不会将其写入日志或磁盘。

自定义按键预设

您可以在 keys.toml 中替换 Keys 托盘的 Presets 行，该文件位于 commands.toml 旁边：

cp keys.toml.example ~/.config/collie/keys.toml

[[keys]]
scope = "claude"             # optional; omit for every pane
label = "Yes"
keys = ["Down", "Enter"]     # several chords go out as one batch

当窗格匹配你定义的行时，它仅显示你的预设，而不是默认的 Ctrl C/D/U/R/L/Z 按钮（ADR 0018）。这些行归你作为操作员所有，并同步至每部手机。其上方的按键板（Esc、方向键、Enter/Tab/Space、修饰键）不在本处设置：各手机会自行排列，参见下一节。

组合键使用 herdr 的语法，而非 tmux 的语法：

如需验证，打开一个窗格并点击 Keys → Presets 查看新按钮。如果 Collie 拒绝了某一行，检查 journalctl --user -u collie -n 20 查看错误详情。

自定义键盘面板

你可以重新排列 Keys 面板。打开 按键 并点击标签旁的铅笔图标：

1. 01
   点击 按键 旁边的铅笔图标。窗格上方会打开一个长面板。
2. 02
   将按键拖动到其他位置，或者点击按键并使用四个方向键按钮。
3. 03
   点击虚线框 + 可在空单元格中添加按键，或者选中某个按键并点击 更改 或 移除。

该面板是 7 列的网格。一个按键占用一个单元格，也可以更宽（1、2 或 3 列）以及更高（1 或 2 行）。选中按键并点击 宽度 或 高度 可调整其大小。它会向右和向下扩展。若尺寸会覆盖其他按键或超出面板，该选项会变暗；点击它会提示哪个按键阻挡了空间。Collie 不会自动替你移动其他按键。添加行 会在底部添加一行，最多八行。更改会立即在 dock 中显示。Collie 会将你的面板保存在当前浏览器中，因此其他浏览器会使用默认面板，直到你将布局共享到其中。默认面板与你之前的面板一致，其中空格键占三格宽，Enter 键位于第二行最左端：

Esc    Tab    Shift  Ctrl   Alt    Up     ^C
Enter  Space (3 wide)        Left   Down   Right

拖动按键会移动其整个区域。将其放在相同尺寸的按键上，两者会互换位置。将其放在其他存在冲突的位置时，目标轮廓会变为灰色虚线，并有一行文字提示哪个按键造成了冲突，随后该按键会返回原位。方向键按钮会跳过阻挡的按键，并在下一个适合放置该按键的位置停下；如果没有可用位置，按钮会保持禁用状态。

一个按键可以发送最多三个修饰键加一个普通键的组合键，例如 Ctrl+Alt+Shift+T。它还可以发送最多四步的短序列，例如 Ctrl+B 然后按 C。序列会作为单次调用按顺序发出。在按键构建器中，针对这些情况可选择 字符、命名键 或 F 键。选择 修饰键 可创建类似默认面板上的粘滞 Ctrl、Alt 或 Shift 键：点击一次可为下一个按键预备修饰键，再点一次保持按下，第三次点击则释放。修饰键是独立的，因此它没有步骤，也没有名称。每个按键的处理路径都与内置按键相同：窗格锁定或离线时它会等待，可能终止程序的按键（Ctrl+D、Ctrl+Z，或包含 Ctrl+C 的序列）会要求二次确认点击，而你的多路复用器无法发送的按键会显示为灰色。

早期版本的代码仍可导入，每个按键占用一个单元格。如果面板中缺少 Esc、Enter 或方向键，会有一行提示文字说明，并带有 放回。Prefix (Ctrl+B) 预设发送 Ctrl+B 前缀，因此适用于窗格内运行的 tmux。Navigation 预设包含 Home、End、PgUp 和 PgDn，Herdr 无法发送这些按键，因此它们在 Herdr 窗格中显示为灰色（ADR 0092）。

自定义快捷回复

您可以在 quick-replies.toml 中自定义 Quick 栏的短语：

cp quick-replies.toml.example ~/.config/collie/quick-replies.toml

[[replies]]
scope = "claude"             # optional; omit for every pane
title = "confirm"
items = ["yes", "no"]        # sent verbatim, one per button

当窗格匹配你的规则时，你的分组将替换默认分组（ADR 0018）。默认短语为英文（yes、commit and push、drastically simplify）。

使用此文件以其他语言运行，或向特定测试环境发送类似 approve 的词语。设置 scope = "shell" 的目标为标准 shell 窗格，否则这些窗格仅接收 y/n。

如需验证，打开一个窗格并点击 Quick 查看你的分组。如果某一行加载失败，journalctl --user -u collie -n 20 会输出错误。

自定义启动器

点击一次即可运行声明的命令，位于 keys.toml 旁的 launchers.toml 中：

cp launchers.toml.example ~/.config/collie/launchers.toml

[[launchers]]
command = "htop"             # required; the shell line, typed verbatim into the fresh shell
label = "Top"                # optional; defaults to the first word of command
# cwd = "~/dev/collie"       # optional; absent means "here" — see below

行在何处打开取决于你从哪里启动它，而不是该行本身。从 新页面（Shell，然后是 Command 选择中的行）启动时，Start 会创建一个以其文件夹命名的新 Space，并以该行的标签命名标签页。从 pane（向上滑动呼出的切换浮层）点击时，会在其旁边打开一个以该行命名的新 该窗格所在 Space 中的标签页。

无论哪种方式，桥接程序都会将 command 输入到新的 shell 中并发送回车。命令自行管理生命周期：自行退出的命令会一并关闭 Space 或标签页，而 htop 则会一直保留直至你退出。

cwd 是该新 Space 或标签页打开的位置。为某一行指定固定文件夹（如上文中的 htop），无论你在哪里点击该行，都会以该固定文件夹为准。

省略该项则表示“当前位置”：仪表盘会在你的主目录下打开它，窗格则在 该窗格自己的 cwd 中打开。一个没有 cwd 的行会跟随你切换检出目录，而不是始终定位在某个检出目录的根节点。

该文件以及从手机添加的行（见下文）构成允许列表。POST /api/launch 仅接受与这些行完全匹配的 command、来自机器自身列表中的 agent id（机器会自行键入该 agent 的命令）或纯 shell。更改会立即生效而无需重启，但已经打开的标签页仅在下次加载时重新读取这些行。

两个可选键向手机提供关于某行的更多信息：

[[launchers]]
command = "claude-danger"
label = "Claude Code, no prompts"
# The agent that reads the row: it is listed under Agent with that agent's mark.
harness = "claude"
# The line skips permission prompts, but an alias hides its flags.
no_prompts = true

配置的行会出现在三个位置：

• —
  在 New 页面上（在仪表盘点击 + 新建）。顶部的切换开关显示 Agent | Shell。带有 harness 的行位于 Agent 下拉框中。没有 harness 的行位于 命令 下拉框中，即 Shell 下方的下拉框。
• —
  在仪表盘的 Launch 区域中。它像 Spaces 一样折叠收起。
• —
  在切换器面板的 Launch 区域中（从窗格向上滑动）。

在 New 页面上，未指定 cwd 的行会在你在该处命名的文件夹中运行，指定了固定文件夹的行则会在该输入框处显示该文件夹。行绝不会在 worktree 中启动；如需在 worktree 启动，请选择 agent 或 Shell。指定了固定文件夹的行会显示缩写为家目录相对路径的文件夹；未指定 cwd 的行在切换器中显示为 "here"（仪表盘默认即为家目录，因此仪表盘中不作显示）。若不声明任何行，这两个区域都不会出现。

在 crew（多台机器，一个面向手机的 lead）中，每台机器读取该文件的独立副本；某一行会在您点击其仪表盘或窗格所在的机器上启动，而不是在 lead 上启动。

New 页面上的 Agent 下拉选择框是 Collie 自带的列表：Claude Code、Codex、opencode、pi、omp、Grok、Hermes、Kiro、Muse 和 Antigravity。Kiro 启动时会保留你设置的工具权限。未包含在机器登录 PATH 中的 agent 仍会保留在列表中，处于禁用状态并标记为“not installed”。对于其他终端 agent，请按上述方式为其声明一行：它会显示在 Shell 下方的 命令 下拉框中，像普通命令一样在窗格中启动，Collie 不会显示其状态。

如需验证，重新加载仪表盘并查看 herd 下方的内容。如果某一行加载失败，journalctl --user -u collie -n 20 会输出错误。

从手机添加的启动器

手机可以在某台机器上添加自己的行。这些行保存在该机器的状态文件夹 launchers-added.json 中，绝不会写入 launchers.toml，也绝不会复制到另一台机器。

在 New 页面上，点击 Agent 下拉框下方或 命令 下拉框下方的 自行添加。这会打开所选机器的 /new/add 页面。在顶部选择 Agent 或 命令。Agent 有两种添加方式：recipe（包含 harness、选项条以及 Collie 将输入的完整命令行）和 编写命令。命令类型的行一律手动编写。添加 会返回 New 页面并选中该新行。表单下方，在此机器上添加 列出了手机在该处添加的所有行，带有 重命名 和 移除，来自 launchers.toml 的行则带有锁定图标且无法操作。添加机制说明 会打开一份简短说明，包含此机器的 launchers.toml 路径以及可供复制的示例行。

[phone]
adds = true          # default true: a phone may add rows built from a recipe
free_text = false    # default false: a phone may also add a line typed by hand
run = true           # default true: a phone may run a one-off command, and run it again from history

将 [phone] 表放在 launchers.toml 中的任意位置。非 true 或 false 的值会被视作 false。bridge 负责强制执行这些开关：被拒绝的添加不会改变任何内容，被开关关闭的行会立即停止启动。该行仍保留在文件中，因此重新开启开关即可将其恢复。

recipe 指一个 agent 加上来自 bridge 自身表格的选项条，例如 Claude Code 和 "Skip permission prompts"。手机仅发送 ID，bridge 负责生成命令行。每个选项条均读取自该 agent 自身的 --help：

只有在启用 free_text = true 时，才能使用 自定义命令（例如 claude-danger 这样的别名或纯 htop）。如果不启用，编写命令 会显示一行已禁用的“已在机器上关闭”，且 添加 保持关闭状态。启用后，在 添加 开启前，检查该行 会显示该行内容，并将每个隐藏字符显示为其编码（例如 ⟨U+200B⟩）。它最多包含 200 个字符；无论是在添加时还是在每次读取时，bridge 都会拒绝其中的控制字符、行或段落分隔符以及双向文本控制字符。

每台机器最多保留 20 个添加的行。如果某一行与 launchers.toml 中的某一行内容相同，则以 launchers.toml 中的行为准。每个添加的行都会记录添加它的配对设备。通过手机或使用 collie devices revoke 撤销该设备会移除其添加的行，审计日志会记录每次添加、重命名和移除操作。

注意。 跳过权限提示的行会带有“无提示”徽章。每台设备在首次启动该行前都会询问一次，并显示命令、文件夹和机器。设置 adds = false 可关闭机器上所有通过手机添加的行。

访问 durable agent（实验性）

Collie 在其终端旁运行的每个 durable agent 均为 sources.json 中的一项，由 collie durable attach 写入（持久 agent）。以下前三个变量是旧格式，用于驱动单个名为 default 的 durable agent 的 durable-only 实例（COLLIE_MUX=durable）。设置 socket，或设置带有 token 的 URL，切勿同时设置两者。

两者均设置、提供了 URL 但没有 token，或提供了 token 但没有 URL，均属于配置错误：实例会启动并将 durable agent 显示为不可达，并标明该原因。在 https 上，每次轮询都是计费请求，因此手机端查看时 Collie 每 2 秒轮询一次，其余情况每 10 秒轮询一次。持久 agent 说明了各方式能阻挡的内容以及不能阻挡的内容。

来自持久 agent 的 starter（实验性）

持久 agent 会在其打开的“新建”页面中的 新建对话 下列出自己的 starter。starter 是一种具名的对话发起方式，例如代码审查。它不需要输入文本：点击它，持久 agent 就会决定启动什么。新对话将以窗格形式打开。使用相同的请求 ID 重复点击会打开同一个对话，不会启动新内容；如果持久 agent 没有响应，重试 会发送相同的请求 ID。无法连接的持久 agent 不会列出任何 starter。此功能处于实验阶段，可能会在任何次要版本中发生变动。

一次性命令及其历史记录

手机也可以运行一次非启动器的命令。Collie 会在您指定的文件夹中打开一个 shell 并输入该行命令，方式与启动启动器行相同。该行遵循与自定义命令相同的规则：最多 200 个字符，且不能包含控制字符、分隔符或双向文本字符。一次性命令绝不会在新建分支上启动。

此功能默认开启，因为已配对的手机本就可以打开 shell 并向其中输入内容。在 [phone] 表中设置 run = false 可移除该机器上的此快捷方式。

在“新建”页面上，切换到 Shell。此时 命令 选择框末尾会增加两项：列出该机器历史命令的 最近使用 分组，以及 输入命令…。选择 输入命令… 后，选择框正下方会出现一个文本框。输入命令并点击 启动（或显示为 运行 的回车键）。启动 上方的提示会显示运行的内容和位置，例如“在 bluefin 上的 ~/projects 中运行 htop”。对于一次性命令，worktree 开关保持关闭状态。

在首次运行前，Collie 会请求机器检查该行命令。此检查不运行任何内容，也不保留任何记录。如果该行包含跳过权限提示的标志（例如 --dangerously-skip-permissions），此手机在启动前会询问一次，与带有“无提示”徽章的行相同。如果该行违反了上述规则，系统会显示提示说明原因，且不运行任何内容。

从 最近使用 中选择一行即可再次运行。除非您手动更改了文件夹，否则 文件夹 字段会自动填入该行上次运行所在的文件夹。选中来自 最近使用 的某一行时，选择框下方会显示 从历史记录中移除 和 清除历史记录。清除历史记录 会先弹出确认提示。页面顶部的 再次运行 行同样可以重复执行一次性运行。设置了 run = false 时，最近使用 中的行仍保留在列表中但处于禁用状态，且 输入命令… 会消失。版本低于 1.19.0 的机器两者均不显示。

每个已启动的命令都会保存在该机器的状态文件夹中，位于 commands-recent.json。该文件最多保留 12 行，按时间倒序排列，并记录每行上次运行所在的文件夹。再次运行某一行会将其移至顶部。看似包含机密的行（例如 TOKEN=abc deploy、带密码的 URL，或包含 token、secret、password 等词的行）仍会运行，但不会被保存。您可以从手机中移除单行或清空列表。设置了 run = false 时列表仍会显示，但其中的任何内容都无法启动。在 crew 中，每台机器维护自己的列表，机器之间不复制任何内容。

该列表不属于权限范畴。从列表中启动某一行属于新的一次性运行，需要配对设备，因此取消配对或撤销设备不会改变列表内容。审计日志仅记录一次性命令的首个词及其长度，绝不记录整行内容，因为命令行可能包含您输入的机密信息。

自定义字体

界面字体是针对单台设备的设置。在 设置 → 外观 → 字体 下，你可以在 System、Space Grotesk、Aldrich（默认）、IBM Plex Sans、Geist 和 Atkinson Hyperlegible Next 之间选择。指定了字体的 主题 会在你选择该主题时将其写入此处一次。你可以在第四个配置文件 theme.toml 中添加自定义字体：

cp theme.toml.example ~/.config/collie/theme.toml
mkdir -p ~/.config/collie/fonts
cp departure.woff2 ~/.config/collie/fonts/

[[font]]
family = "Departure Mono"    # the picker's label AND the CSS family
file   = "departure.woff2"   # a bare name inside fonts/, woff2 only
weight = "400 700"           # optional

自定义字体会追加到内置列表末尾，而不是将其替换（ADR 0033），这与 commands.toml 和其他配置文件中的行为不同。由于字体不会触发操作，因此不存在需要遮蔽的内容。

它们会显示在预置条目下方，每个客户端设备自行选择。

需要注意的三种行为：

• —
  初次加载布局偏移。 自定义字体缺少尺寸匹配的后备字体，这会导致初次加载时出现轻微的布局偏移。内置字体没有这个问题，因为其后备字体是在构建时生成的。
• —
  冷加载延迟。 冷加载获取文件时会有短暂延迟；有缓存的客户端则会立即渲染。
• —
  仅限界面框架。 所选字体仅应用于 Collie 的界面框架。终端镜像、转录文本和渲染后的 markdown 仍保留各自的排版设置。
• —
  下次重新加载生效。 修改后无需重启，在下次重新加载页面时生效。无效配置会记录错误，可通过 journalctl --user -u collie -n 20 查看。

自定义缓存规则

使用 cache-rules.toml 可以修改已被服务商调整的提示词缓存有效期。

cp cache-rules.toml.example ~/.config/collie/cache-rules.toml

Collie 针对每个 harness 和服务商各提供一条规则。每条规则均由 Collie 在记录的日期从服务商文档页面抓取。服务商可能会在不事先通知的情况下修改该值。网关（位于 agent 与服务商之间的代理）也可能对其进行修改。在 Collie 发布更新之前，可使用此文件覆盖这些值。

[[rule]]
id = "claude.api"
ttl_seconds = 3600
source_url = "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
retrieved = "2026-09-12"
note = "our gateway sends ttl 1h on every request"

Collie 仅在满足全部四条规则时才会保留一行。id 必须指定一个自带的规则。ttl_seconds 必须是 1 到 86400 之间的整数。source_url 必须是非空字符串。retrieved 必须能解析为有效的 YYYY-MM-DD 日期，且不得晚于今天。无效行会被丢弃并记录到日志中。该文件的其余部分仍然生效。

另外两条规则决定文件的含义。具有相同 id 的两行不会报错：以靠后的行为准。若将 note 设为空字符串，则整行都会被丢弃，因此请直接省略该字段。

某一行会绑定在对应的层级规则上，即其 id 所指定的规则。该层级下的各模型细分会随之调整，因此一行即可覆盖该层级上的所有模型。

注意。 你可以更改数值。但不得移除其来源页面或检索日期。规则目录要求这两个字段必须同时存在。

collie doctor 检查三项内容。cache-claims 在 180 天内未重新核对自带规则时发出警告。cache-rules 列出每个被丢弃的行及丢弃原因。cache-env 在你在 shell 中设置了 ENABLE_PROMPT_CACHING_1H 或 FORCE_PROMPT_CACHING_5M 时进行标记。bridge 作为独立服务运行，无法读取你的 agent 的环境变量。在此处镜像这些 Claude Code 变量，以便 bridge 能够读取它们。

以下是你可以填写的规则 ID。

Prompt 缓存倒计时

每个 agent 面板上的状态标签会显示该 agent 的 prompt 缓存保持热度（warm）的时长。

所有受支持的 harness 都会缓存当前会话。在缓存保持热度期间，harness 收取的费用更低。该标签倒计时自 agent 上一次请求以来的空闲时间。它不会跟踪会话的总时长。每次发起新请求都会重置计时器。

标签上的沙漏以三种颜色之一表示状态，旁边的数字保持灰色。窗口充裕时沙漏为绿色，在最后四分之一窗口期内为红色，窗口过期或某次回话按全额计费时为蓝色。在蓝色状态下，标签显示 cold；剩余时间不足一分钟时，显示 <1m 而非秒数。

部分操作会在时间尚未耗尽时清除缓存：通过 /model 切换到其他模型、更改 effort、执行 compaction 以及 /reload-plugins --force。一旦 Claude Code 将该操作写入其 transcript，芯片即变为蓝色，且工作表会标明该操作。opencode 也以相同方式报告 compaction 和模型更改。

该标签位于面板标题第二行的最右侧，紧随面板工作区之后。在 crew 中，机器名称显示在同一行的标签旁边。点击标签可查看底层规则：规则 ID、厂商来源页面以及检索日期。

注意。 除非标有 已测量，否则数值均为记录了日期的厂商声明，并非实时测量值。Claude Code 会将缓存窗口直接写入其副本记录，因此 Claude 面板通常带有测量值。

某些面板未显示标签。这符合预期。面板仅在对应 agent 完成一轮回话后才会显示标签。Collie 在实际测量前不作任何假设。若 harness 缺少 journal 适配器，或者其厂商未发布生命周期数据，则面板不显示任何内容。

Collie 还可以在缓存过期前向手机发送推送提醒。该时机由一个变量控制。

此设置仅控制推送提醒。它不控制标签变红的时机。变红的阈值固定为每条规则 TTL 的四分之一。推送本身的触发时机取该设置与面板自身缓存生命周期一半两者中的较小值，因此 5 分钟的缓存（Codex、OpenCode、pi、omp）会在变冷前大约两分半钟发出警告，即使该时间小于配置的 300 秒。若要为特定面板或所有面板启用警告，请参阅 voice-and-push.md。

附件

输入框旁边的回形针图标用于将文件上传到主机，并将文件路径插入到消息中。

# in your .env
COLLIE_MAX_UPLOAD_MB=25              # default 10, floor 1, ceiling 512
COLLIE_UPLOAD_EXTRA_TYPES=rb,ex,zig  # bare extensions, no dot

Collie 会将文件保存到 <state-dir>/uploads 下（权限仅限所有者），并将其绝对路径追加到草稿末尾。Agent 从该路径读取文件，因为终端无法直接接收粘贴的文件。上传的文件在写入 48 小时后会被自动清理。

系统接受两类文件，并采用不同的校验方式。

图片 通过特征字节识别，绝不依赖文件名或声明的类型：png、jpg、gif 和 webp。SVG 会被明确拒绝，因为它是包含脚本的标记语言而非纯图片。

文本 通过扩展名识别，并以文件字节作为一票否决条件：如果文件的前 4 KB 包含 NUL 或异常控制字节，无论文件名是什么都会被拒绝。内置支持的列表包括 md、markdown、txt、json、jsonl、yaml、yml、toml、csv、tsv、log、xml、html、htm、css、js、jsx、mjs、cjs、ts、tsx、py、go、rs、sh、bash、sql、diff 和 patch。

注意。 COLLIE_UPLOAD_EXTRA_TYPES 仅用于添加文本类型。图片需要通过特征字节进行校验，因此无法通过这种方式添加二进制格式。

调大 COLLIE_MAX_UPLOAD_MB 会连带提高另外两个数值。桥接程序必须将整个上传内容读入内存才能测量其大小，因此较大的上限加上多个并发上传会占用等量内存。此外，运行时的请求体限制适用于所有路由而不仅是上传路由，因此较大的上限会让超大请求体到达任意处理程序，随后被该处理程序自身的限制拒绝。在满 48 小时之前不会删除任何文件，因此上传目录最多会保留两天内发送的内容。仅在确实需要时调大该数值，不要默认调大。

在 crew 中，两项设置均按机器独立配置，由存储文件的机器负责强制执行。主节点在转发之前会拒绝超大请求体以节省上行带宽，但它是根据自身的数值进行判断的。请在每个成员节点上设置相同的值，否则对端节点可能会拒绝主节点已放行的请求。

收藏和最近使用的文件夹

“新建”页面会列出您之前启动过任务的文件夹，因此您可以直接点击选择，无需手动输入路径。

在“文件夹”字段下方，列出了启动目标机器的两个列表。最近使用 包含最近启动过任务的 8 个文件夹，按时间倒序排列。它仅统计成功启动并指定了文件夹的操作，且绝不会列出您的家目录，因为留空已代表家目录。新分支专属的文件夹不会被添加，因为它是全新签出的目录，而不是您会重复返回的位置。

您也可以手动输入路径。~/projects 和 /srv/www 的含义与其标准定义一致。不以 / 或 ~ 开头的名称（例如 projects）代表家目录下的文件夹，类似于新打开 shell 中的 cd projects；在点击之前，“启动”上方的提示会显示完整路径（~/projects）。包含 .. 的路径会被拒绝。该文件夹必须已存在于执行启动操作的机器上，且必须是一个目录。如果不存在，则不会启动任何内容，“启动”上方会显示提示“此机器上不存在文件夹 …”。Collie 仅在您点击“启动”时进行检查，绝不会在输入过程中检查。在 crew 中，由您选定的机器检查其自身磁盘。

点击某一行会填入“文件夹”字段，但不会启动任何内容，因此您仍可更改上方的选项。点击行旁的星标可将其移至 收藏，最多保留 12 个，按加星标的先后顺序排列。再次点击星标可将其移回“最近使用”的顶部。

浏览 位于两个列表下方。点击它会列出字段中文件夹的子文件夹；如果字段为空，则列出 home 的子文件夹。点击文件夹即可进入，字段内容会随之更新。点击 Up 或列表上方的路径部分可返回上一层。属于 Git 仓库的文件夹会带有 git 徽标。Use this folder 会填充该字段，效果类似于点击 Recent 行。

当字段包含不存在的路径（例如 ~/src/plektra-）时，Browse 会在最近的存在文件夹（~/src）处打开，并仅列出以其余部分（plektra-）开头的名称。因此在字段中输入内容会缩小列表范围。home 之外的路径会显示“Nothing to browse here”。

Browse 仅读取 home 文件夹下的文件夹名称，受 Files 视图的限制。它会隐藏以点开头的文件夹（除非你输入点号），从不列出 .git 或 Collie 自身的状态与配置文件夹，不跟踪指向 home 之外的链接，且最多显示 200 个文件夹。它不创建任何内容，并且与 Files 一样需要配对的设备。

该列表归机器所有，而非手机所有。每台机器将其列表保存在其状态目录中的 folders.json 下，除非通过 COLLIE_STATE_DIR 更改，否则默认位于 ~/.local/state/collie/folders.json。您使用的每台设备看到的都是同一个列表，且该文件仅在某个文件夹中首次启动或首次添加星标后才会生成。相同的列表也会填充到 新建 worktree 下方的 其他目录 中，用于选择分支专属文件夹所在的上级目录。

在 crew 中，每台机器保留其自身存在的文件夹，页面显示你所选机器的列表。运行较旧版本 Collie 的机器没有列表，页面也不会为其显示任何内容。Browse 也会列出所选机器的磁盘，较旧的机器会提示需要更新。

Secret masking

Collie 在窗格文本送达手机前，对其已知的密钥模式进行脱敏。

# in your .env; the default is on
COLLIE_REDACT=off

在配置文件中该项为 [access] redact。脱敏会保留被隐藏内容的宽度，以维持镜像的排版。它仅匹配高置信度模式；限制说明见 安全性。

在 crew 中，lead 还会根据自己的设置对成员发送的文本进行脱敏。仅当 lead 和该成员都设置了 COLLIE_REDACT=off 时，成员的文本才会以未脱敏的形式送达你的手机。

报告问题

当单个窗格上连续 3 次发送因指向 Collie 的原因而失败时，回复框上方的卡片会提供报告选项。设置 → 系统 → 发送失败时提供报告 可以为该设备关闭此卡片（保存在浏览器中，默认开启）。窗格菜单的 报告问题 以及“设置”中同一卡片上的 报告问题 按钮仍可打开该工作表。

在您点击 在 GitHub 上打开 或 复制报告 之前，手机不会发出任何内容，且 Collie 不保存 GitHub token。报告包含的内容以及在发送前如何阅读报告，请参见 问题排查。

多会话

默认情况下，一个 Collie 实例会为其找到的每个 Herdr 会话提供服务。

COLLIE_MULTI_SESSION=on（默认值）会发现并提供配置根目录下所有具名的 Herdr 会话，可在页头切换。设置 COLLIE_MULTI_SESSION=off 仅提供主 Herdr 会话。所有被发现的 Herdr 会话都可以通过同一个 URL 访问，包括私有或沙箱会话。安全性 将此行为列为一个注意事项。

用量窗口

模型旁边的圆点无需配置即可显示 Claude 和 Codex 的 5 小时和 7 天额度限制。

# turn every source off
COLLIE_ACCOUNT_WINDOWS=0
# turn on opencode and grok too, or name the ones you want
COLLIE_ACCOUNT_WINDOWS=all
COLLIE_ACCOUNT_WINDOWS=claude,codex

Collie 会读取本机上的 Claude 登录文件并请求 Anthropic 的使用量端点，与 Claude Code 的 /usage 发起的调用相同；登录信息的任何内容都不会被存储或发送到别处。Collie 仅在打开该 harness 的窗格时发起请求，并会跳过他人可读的登录文件（任何权限宽松于 0600 的文件）以及已过期的登录凭据。Codex 不发送令牌：它读取自己的文件。

Collie 无法识别的 id 会被丢弃并伴有警告，仅启用其识别的 id，因此拼写错误绝不会启用你未指定的来源。在配置文件中，[bridge] account_windows 接受 true 或 false、包含相同形式的字符串或类似 ["claude", "codex"] 的数组。

每个来源读取的内容各不相同。

• —
  Claude，默认启用。 Collie 读取 ~/.claude/.credentials.json 或 $CLAUDE_CONFIG_DIR/.credentials.json，并请求 api.anthropic.com。
• —
  Codex，默认启用。 Collie 不读取登录信息，也不向任何人发起请求。在 ChatGPT 登录状态下，Codex 会将时间窗口写入其自身的会话文件（$CODEX_HOME/sessions 或 ~/.codex/sessions），Collie 会读取过去两小时内最新文件的末尾内容。使用 API 密钥的 Codex 没有可显示的时间窗口。
• —
  OpenCode Go，默认关闭。 启用后，Collie 会读取 OpenCode 登录存储中的 opencode-go 条目（~/.local/share/opencode/auth.json 或在 $XDG_DATA_HOME 下），并请求 opencode.ai。如果没有 Go 条目，则不发起请求。
• —
  Grok，默认关闭。 启用后，Collie 会读取 grok login 保存的登录信息（~/.grok/auth.json 或在 $GROK_HOME 下），并向 cli-chat-proxy.grok.com 查询你的积分。

注意。 OpenCode Go 和 Grok 遵循其他工具用于这些端点的格式，目前尚无真实账户进行验证。因此在为其指定名称之前，它们保持关闭。pi 和 OMP 目前在此处不显示窗口。

collie doctor 在其 account-windows 行中显示各个源：开启或关闭、读取的文件以及请求的主机。终端 包含 statusLine 路径。

上下文圆点无需设置。对于 pi、OMP、Codex 和 OpenCode，Collie 会从会话日志中读取上一轮次的 token 数。它会从 Codex 的日志或磁盘上 harness 自身的模型列表中读取模型窗口（pi 的 models-store.json、OMP 的 models.db、OpenCode 的 ~/.cache/opencode/models.json）。未在该列表中命名的模型不会显示上下文圆点；模型名称依然显示。当 harness 报告会话费用时，标签还会在圆点后以美元显示该费用：Claude Code 通过换行状态行报告，pi、OMP 和 OpenCode 从其日志中报告。Codex 没有费用信息，因此其标签不显示费用。

深色模式 / 浅色模式

注意。 Collie 默认跟随手机的外观设置。

若要固定它，打开 Settings → Appearance，在 主题 卡片下找到 外观 卡片，并选择 系统、浅色 或 深色。主题 卡片用于选择配色；此卡片则选择配色的浅色或深色部分。该设置存储在浏览器的 每台设备独立保存 中，而不是 bridge 上。你的手机可以保持深色模式，而笔记本电脑跟随操作系统。该偏好设置在同一设备上刷新页面或重新安装 PWA 后依然保留。

终端镜像采用了不同的设计

镜像始终在 深色底色 上渲染。浅色模式会反转整个元素，而不是对各个 span 单独重新着色。

Agent 会输出针对深色背景调优的绝对 24 位颜色代码（38;2;r;g;b），下游解析器无法可靠地对其重新映射。直接渲染到白色背景上时，大多数 agent 输出的对比度会降至 3:1 以下。反转处理可以保留原定的对比度。具体测量数据记录在 ADR 0002 中。

这种实现方式带来了两个实际影响：

• —
  保持你的 agent 配置为深色主题。 这是 Claude Code、codex、opencode 和 pi 的默认配置。如果 agent 使用了 浅色 主题，它输出的浅底深字数值在 Collie 的两种模式下都会变得难以辨认。这是由 agent 的输出导致的，而非 Collie 本身的问题。
• —
  在浅色模式下，Diff 和高亮行会渲染为深色色块。对比度保持不变，但视觉比重发生了反转。

注意。 在 iOS 上安装后，浅色模式下的状态栏文本仍为白色，可能会融入背景中。iOS 不允许 Web 应用动态更新此值。请直接在浏览器中运行 Collie 而非将其作为已安装的 PWA，以规避此限制。

Zen 模式

注意。 Zen 模式默认处于关闭状态。

在 设置 → 设备 → 禅模式 中启用此模式（按设备保存在浏览器中）。这会在窗格菜单中添加 Zen 模式 选项，位于 Find 和 History 旁的 ⋮ 下方。点击该选项会隐藏所有 Collie UI 元素：顶栏、标签页和窗格条、agent 状态行以及 composer 停靠区。界面上仅保留终端镜像。右上角的悬浮按钮或 Escape 键可恢复界面。

Zen 模式属于 非持久状态。配置会持久保存，但切换窗格或重新加载页面时，激活状态会重置。窗格始终以标准 chrome 打开。

终端镜像在 Zen 模式下会继续轮询，交互式缓冲区元素保持可用。提示按钮、"Load older" 以及 "Show entire history" 控件依然可用，因为它们属于内容流而非 chrome。

大屏

注意。 在平板电脑或展开的折叠屏设备上，窗格屏幕会并排显示多个窗格。竖屏平放的手机界面保持不变。

当屏幕宽度至少为 600 CSS 像素且高度至少为 480 像素时，窗格屏幕会启用该布局。横屏握持的手机高度不足 480 像素，因此保持手机布局。若要关闭，请打开 Settings → Appearance → Large-screen layout 并选择 关闭。默认选项 自动 会在屏幕足够大时将其开启。该选择按设备保存。

该布局包含三个部分。

• —
  侧边栏。 它列出你的窗格，与窗格切换器显示的列表相同。顶行的按钮可将其折叠为狭窄的图标栏，此选择保存在此设备上。顶行的 ColliePWA 标识可返回主页。新空间 和 设置 位于底部。
• —
  窗格行。 每个空间拥有自己的一行，该行可横向滚动。在侧边栏中点击某个窗格可将其显示。按住该窗格（使用鼠标右键单击）可选择 在此打开（替换当前所在窗格），或选择 在旁打开（将其添加到该窗格旁边）。你也可以将窗格拖入行中。从视图中移除 会将窗格从行中移除。agent 保持运行。
• —
  空间标题栏。 它包含空间名称、标签页以及用于新建标签页的 +。按住标签页（使用鼠标右键单击）可对其进行 重命名 或 关闭标签页，与手机上的操作相同。关闭当前操作的标签页会切换到其相邻标签页的窗格。点击其两个按钮或垂直滑动可切换到上方或下方的空间。

每个窗格都有一个宽度：整行的 1/2、4/5 或 全宽。窗格宽度不会小于 360 像素，因此会导致宽度小于该值的选项不会显示。当该行无法以此尺寸容纳两个窗格时，每个窗格均为 全宽 宽度，且该控制项隐藏。停止滚动时，该行会自动对齐到窗格的起始位置，向侧面滚动绝不会触发浏览器的后退页面操作。该行始终以 添加窗格 结尾。它列出了此空间中该行未显示的窗格，每个窗格均带有 在此打开（该窗格会成为行中的最后一个窗格）。它还提供 在此空间新建 agent（在对应窗格所在的机器和目录中打开 New 页面，并将该 agent 作为此空间的新标签页添加到当前所在窗格旁）以及 在新空间新建 agent。

每个窗格都有自己的控制带，但像笔记本电脑一样握持折叠屏设备时除外（见下文）。当前操作的窗格带有边框和回复框。点击另一个窗格的控制带会对该窗格执行操作并切换至该处。点击窗格本身可仅切换而不触发操作。

布局仅保存在此设备上，“后退”和共享链接的行为与之前相同。

折叠屏。 在半展开的折叠屏设备上，Chrome 和 Samsung Internet 会在折痕处分割屏幕。像笔记本电脑一样握持时，对话保持在折痕上方，控制带和更高的回复框位于折痕下方。只有当前操作的窗格保留其控制带，位于折痕下方。其他窗格仅显示 Chat。这种分割适用于任何宽度，因此对半展开的翻盖手机同样生效。键盘弹出时，布局恢复为扁平状态。像书本一样握持时，分割从 600 像素宽度起生效。有两个窗格时，两侧各显示一个窗格，侧边栏变为图标栏。只有一个窗格时，侧边栏在一侧保持打开，窗格占满另一侧。其他浏览器仅显示扁平布局。

窗格导航

无论是手机还是大屏布局，手势均可在窗格和空间之间移动。左右滑动按切换器中的顺序前往当前空间的上一窗格和下一窗格。上下滑动前往上一空间和下一空间。位于首个或末尾窗格及空间时，移动操作保持在原位。在 设置 → 外观 → 窗格导航 中选择触发方式。更改将在下次打开窗格时生效。

方框中显示你要移动至的窗格名称及其状态、所属空间和在空间中的位置，下方附有空间结构图。未滑动直接抬起第一根手指、在第二根手指未抬起时抬起第一根手指，或放下第三根手指，均会保持在原位。手指抬起时不会触发下方任何元素的点击事件。设备首次触发手势时，皮带上方会显示简短提示，说明其用法以及关闭入口。

手势保留了页面原有的触摸行为。单指按住不会触发新行为：长按仍会选中文字并打开其菜单。双指开合仍会缩放，因为在前 300 ms 内落下的第二根手指会计为缩放手势。正在滚动的单指，或从屏幕左右边缘（即手机自带返回手势区域）起跳的手指，绝不会触发该手势。从第二根手指落下到抬起第一根手指期间，页面会拦截选区和滚动，且此前创建的选区会被清除。窗格导航仅限触摸，鼠标在此处无效。启用 TalkBack 时手势不应生效，因为 TalkBack 会占用双指滑动；窗格切换器仍可用于移动。

Chat 视图

自 1.17.0 起，注意。 Chat 成为 agent 窗格的默认视图。轻按一下即可切换到 Terminal。

agent 窗格在 Chat 中打开。Chat 渲染 agent 自身的对话而不是终端：你的发言、它的回复、折叠在内的思考过程，以及每一步一张卡片。输入框、状态带和窗格菜单保持在原位。若要改为查看终端，打开窗格的 ⋮ 菜单并轻按 Terminal 视图。该选择是针对整台设备的一项设置，保存在浏览器中；已经选择终端的设备会保留该设置。同个菜单中的 Chat 视图 可以切换回来。

当你在 Claude Code 工作时排队发送消息，Chat 会将其显示在 等待发送 卡片上，卡片的 立即发送 按钮会立即将整个队列发送给正在运行的轮次。只有 Claude Code 提供该功能，因为该按钮会按下 Ctrl+Enter，即该 agent 为此定义的按键。该按钮在只读设备和已保存副本上会隐藏。

包括 OMP 和 pi 在内的大多数其他 agent，在轮次结束前都不会在日志中写入任何有关排队消息的内容。对于它们，Chat 会将 Collie 自身排队的消息绘制在同一个 等待发送 卡片上，直到 agent 的日志将各条消息显示为提示词。该卡片没有按钮。Collie 无法从 agent 的队列中取出消息，因此没有“取消”：如需取回，请停止轮次。

当 Collie 无法再判断排队消息的去向时，卡片不会直接消失，而是会显示 未确认。当 agent 连续两次处于空闲状态且输入框为空时，或者在没有运行轮次的情况下过去 30 分钟后，就会发生这种情况。它的 舍弃 按钮会移除卡片且不发送任何内容。

显示设置齿轮中包含一个 可伸缩文本回复 开关，默认关闭。开启后，聊天、完整回复卡片和历史记录会将 cc-stretch 插件生成的回复显示为其简略形式，点击短语即可展开。没有横条的 {{name}} 会显示为 name。

已知 Chat 中有一处尚不完善。Hermes 可能会在 Collie 读取日志后从中移除某一轮次，例如在执行压缩时。此时 Chat 会持续显示该轮次，直到会话被重新读取。终端从不会出现这个问题。

Chat 读取的是 agent 的会话日志，而不是屏幕输出。这意味着只有当 Collie 知道窗格正在运行哪个会话时，窗格才能使用 Chat，并且 agent 必须通知多路复用器。窗格自身无法获取这些信息。

OpenClaw 的 Chat 无需 Herdr 集成。Herdr 不会传递 OpenClaw 会话，因此 Collie 会从 openclaw tui（agent main (main) | session work | …）的页脚读取会话名称，并以只读方式打开该代理在 $OPENCLAW_STATE_DIR 或 ~/.openclaw 下的会话数据库。当状态文件夹位于其他位置时，请设置 openclaw_root。该 pane 必须向 Herdr 报告自身为代理 openclaw。Collie 绝不读取 OpenClaw 的配置文件或其 gateway token。

Kiro 同样不需要 Herdr 集成：Herdr 将 kiro-cli 窗格命名为 agent kiro，Collie 通过运行中的 Kiro 在窗格中持有的锁来识别窗格会话。Collie 读取使用 --v3 或 --agent-engine v3 启动的 Kiro V3 会话，或者在 Kiro 自身设置中将引擎设为 V3 的会话。V1 或 V2 会话没有聊天或历史记录。若 Kiro 将会话保存在其他位置，请设置 kiro_root。

herdr integration status 会显示已安装的集成。hook 在 agent 启动时读取，因此安装 hook 前就已在运行的 agent 需要重启。Oh My Pi 对应 omp 集成，而非 pi 集成：它们是两个 agent，各有一个 hook，共享同一种日志格式。

新的 agent 窗格会立即显示 Chat，甚至在有任何内容可读之前，附带一行文字：“Send a message to start”。Codex 仅在你发送第一条消息后才报告其会话，而 pi 仅在第一次回复后才写入其日志，因此两者都以此方式启动。对话一旦产生就会立即显示。

当发生 Chat 无法显示的情况时，窗格会回退到终端：agent 在有任何内容可读之前向你提问，或者其第一轮结束但仍没有会话，或没有可读的日志文件。终端随后会显示一行文字指出缺少的内容，⋮ 行会说明原因。运行了一分钟却没有任何可读内容且没有其他迹象的第一轮也会回退。首次打开时就已经处于繁忙状态且没有会话的窗格，会立即显示终端。当会话或日志稍后到达时，窗格会切回 Chat。Chat 从不隐藏该行，因此你可以区分是缺少 hook 还是缺少功能。collie doctor 在 agent-sessions 下列出这些窗格，并指明修复各项所需的集成配置行（integration-<agent>）。故障排查页面 在 窗格没有 Chat 或 History 下提供了具体步骤。

离线阅读

当无法连接到 bridge 时，手机会显示其保存的最新副本，你可以阅读但无法对其进行操作。

手机为每个窗格保留两项内容：它看到的最新终端文本，以及 Chat 渲染的最新 Chat 轮次。它从不把原始终端屏幕保留为 Chat。当你打开 Collie 且 bridge 在约 1.5 秒内未响应时，手机会立即绘制此保存的副本，并在 bridge 响应后将其替换为实时数据。

保存的副本外观与实时屏幕不同：

• —
  agent 列表呈暗淡显示，每个状态均为过去时（“was working”、“needed you”），且标头显示 截至 以及保存时间。
• —
  Chat 窗格显示“Saved copy from”和时间。更早的轮次仍保留在 bridge 中。
• —
  提示按钮、卡片和发送按钮均处于关闭状态。轻按保存的副本无法传达到 agent。

连接栏会指出三种原因之一：

类似 Tailscale 的 VPN 在飞行模式下仍会保持手机的网络标志开启，因此状态栏无法始终区分“无网络”与“bridge 已停止运行”。此时它只会提示 bridge 无响应。

应用打开期间，状态栏和保存的副本会在首次轮询无响应时出现。轮询最多等待 6 秒，比 bridge 等待多路复用器的时间长 1 秒。连续出现第二次服务器错误 (5xx) 时才会计入。屏幕上的内容保持不变，一旦收到首次实时响应，即可恢复实时视图。

刚切回应用时，首次轮询无响应不会单独计入。Tailscale 链路可能需要片刻才能恢复，因此手机会在半秒后再次请求，且仅在这轮轮询同样无响应时才显示状态栏。

设置 → 设备 中的 在此手机上保留聊天记录 用于设置 Chat 轮次在手机上的保留时长：

终端文本有其独立的 24 小时生命周期，此设置不会更改该时长。在终端视图中，唯一的离线副本即为该终端文本。

注意。 手机仅保留 bridge 已脱敏的文本，并在窗格请求密码时丢弃该窗格的副本。手机保留的内容 列出了每个项目、其大小上限及生命周期。

变更

“文件”屏幕 会在 变更 分段下显示 agent 在其工作区的 git 仓库中所做的更改。设置 → 设备 → 更改 中的两项设备级设置决定了查找仓库的深度：

有关搜索工作原理，请参见哪个文件夹以及哪些仓库。

语言

Collie 界面支持 12 种语言。可在 设置 → 外观 → 语言 下进行配置。

• —
  English
• —
  Deutsch
• —
  Español
• —
  한국어
• —
  日本語
• —
  中文
• —
  Русский
• —
  Italiano
• —
  Français
• —
  Português
• —
  Türkçe

所选设置按设备本地保存在浏览器中。终端镜像不进行翻译：它直接显示来自 agent 的原始输出，而快捷回复、菜单标签和键帽则与底层屏幕或键盘名称保持一致。

通知标题遵循相同的选择：在设置为韩语的设备上，“claude needs you”会显示为“claude 입력 대기”。下次在该设备上打开 Collie 时，设备会采用新选择，在此之前标题保持原有语言。标题下的正文是窗格自身的名称和位置，一律不进行翻译（Web Push）。