配置

默认情况下，Collie 运行在开放的单用户模式下：tailnet 上任何能访问该 URL 的人都有完全控制权。这会触发 TRUSTED_USER 警告。限制访问权限：

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

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

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

COLLIE_ALLOWED_ORIGINS=https://collie.example.com

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

自定义斜杠命令

将特定于机器的命令（例如 Herdr 插件 /fork-in-herdr 或自定义 /deploy）放入 commands.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"

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

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

自定义按键预设

您可以在 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、修饰键、数字、F1–F12）是固定的。

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

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

自定义快捷回复

您可以在 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）。

使用此文件以其他语言运行，或向特定测试环境发送类似 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

点击后在何处打开取决于你在哪里点击，而不是取决于行本身。在 仪表盘 中点击会创建一个以该行命名的新 Space。在 pane（向上滑动呼出的切换浮层）中点击会在其旁边打开一个新的 该窗格所在 Space 中的标签页。

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

cwd 是新 Space 或标签页打开的位置。固定一个路径（如上文中的 htop），无论你在何处点击该行，都会以固定路径优先。

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

此文件即为允许列表。POST /api/launch 仅接受与此处某行完全匹配的 command，因此手机无法启动该文件之外的任何内容。修改无需重启立即生效，但已打开的标签页仅在下次加载时重新读取各行。

你定义的行会出现在两个位置：仪表盘上的 Launch 部分（可像 Spaces 和 Recent 一样折叠），以及切换浮层中的 Launch 部分（从窗格向上滑动）。固定的行会显示其文件夹（主目录下的路径会被缩短）；没有 cwd 的行在切换器中会显示为 "here"（仪表盘默认即为主目录，因此在那里不显示任何内容）。如果不声明任何行，这两个部分都不会出现。

在 pack（多台机器，一个面向手机的主控节点）上，每台机器读取各自的该文件副本。点击行时，它会在你发起点击的机器仪表盘或窗格上启动，而不是在主控节点上启动。

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

自定义字体

界面字体属于每设备设置。在 Settings → Typeface 下，您可以在 System、Space Grotesk（默认）和 Aldrich 之间进行选择。您可以在第四个配置文件 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 查看。

附件

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

# 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 小时之前不会删除任何文件，因此上传目录最多会保留两天内发送的内容。仅在确实需要时调大该数值，不要默认调大。

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

多会话

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

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

深色模式 / 浅色模式

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

如需固定外观，打开 Settings → Appearance 并选择 系统、浅色 或 深色。该设置保存在浏览器的 每台设备独立保存 中，而不是在桥接程序上。你的手机可以保持深色模式，而笔记本电脑则跟随操作系统。该偏好设置在同一设备上的重新加载和 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 模式默认处于关闭状态。

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

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

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

语言

Collie 界面支持六种语言。在 Settings → Language 下进行配置。

• —
  English
• —
  Deutsch
• —
  Español
• —
  한국어
• —
  日本語
• —
  中文

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