从首页开始
选择电脑、助手、模型、模式和目录，附上文件，再发送目标，直接打开会话或终端。
MUQUN / 4.0.0
从第一个目标到下一次改动，都在同一工作区。
原生接入 Codex 与 OpenCode 等 AI 助手会话。在手机上完成权限审批、跟进任务与实时 Diff，直连你自己的电脑。
看见需要你的工作
电脑卡片呈现活动任务、进度、待决定事项与最近工作；子任务保持在父任务的工作脉络中。
说出来，再检查
长按发送录音，把转写插入草稿，检查后再发送。可配置文件转写或实时转写服务。
Git，就在工作区里
改动与 Lazygit 在一起。Gateway 支持时可浏览关联工作树，不会切换当前终端所在的检出目录。
下载前先看更新内容
兼容的应用更新展示说明和下载进度，验证完成后重启。选择稍后可在本次启动中暂缓提示。
回复不止文字
阅读原生图表、预览会话文件，需要时播放内嵌音频。关闭预览或开始听写时，音频会停止。
管理临时存储
在存储设置中查看可回收缓存，并配置自动清理。
通过 Google Play 或 App Store 更新。助手、任务与 Git 功能取决于所连 Gateway 提供的能力；旧版仍可使用其支持的终端与 OpenCode。
muqun-gateway
安装 Gateway，配对你的手机。
牧群仅与你自己电脑上的一个程序通信：Gateway。在电脑上安装并启动它，然后用手机完成一次配对。无需注册任何账号，你的任何数据都不会途经我们的服务器。
PRE-FLIGHT REQUIREMENTScheck before installing
- macOS 或 Linux，必须是你拥有控制权的电脑。目前暂不支持 Windows。
- 已预先安装 tmux 或 Herdr（0.7.5 或更新版本）——Gateway 负责驱动它们，而非取代它们。
- 两台设备处于同一个私有网络（例如连接同一个 Wi-Fi 或局域网）。
- 无账号系统、无订阅收费，中间没有任何我们的中继节点。
在电脑上运行安装脚本
脚本会将单一二进制文件安装至 ~/.local/bin/muqun-gateway，完成初始配置，并在首次运行时自动打开配对界面。支持 macOS 与 Linux；暂不支持 Windows。install curl -fsSL https://muqun.dev/gateway.sh | sh选择两种运行模式之一启动
你可以手动启动它，也可以将其交由系统托管保活。两种方式都能启动 Gateway，区别在于系统重启后的行为。二选一，切勿同时使用：安装系统服务后，手动执行 stop 会被服务守护进程立即拉起。打开配对管理器
无论采用哪种启动方式，这都是下一步。管理器是终端里的全屏面板，显示配对二维码、运行状态以及当前持有访问凭证的所有设备。安装脚本首次会自动打开；后续你可以随时用此命令重新打开。pair muqun-gateway manage扫码并输入确认短码
在手机上的牧群中扫描二维码。电脑屏幕上会显示一组形如 XXXX-XXXX 的短码，在 App 中输入即可完成配对。单凭扫码无法完成配对——输入短码才能证明拿着手机的人就是电脑前的你。
MANUAL ADDRESS PAIRING
无法扫码？可以在 App 中手动输入 Gateway 地址（管理器会打印当前发布的连接地址），然后再输入相同的短码。
CODE VALIDITY & RETRIES
短码有效期为 5 分钟，输错 8 次后将作废。在管理器中按 p 键可立即刷新生成全新的二维码和确认码。
workspace · group.panel
真实终端体验。
这是你机器上的真实终端，而不是截屏或日志重放。Gateway 在你的电脑上驱动 tmux 或 Herdr，手机端直接渲染其内容——桌前留下的工作，在手机上原封不动接续，关闭 App 也不会对终端会话产生任何干扰。
WORKSPACE ARCHITECTURE
工作区、分组与终端
三个层级，定位格式为 工作区 · 分组.面板。工作区是你的项目工作目录，分组是其中的一组终端，终端就是单个 Shell。牧群在手机上一屏只显示一个终端而不切分小屏：在手机上分出多个窗格根本无法看清。
层级间快速切换
左右滑动顶部标题胶囊可切换工作区。输入框上方的标签芯片可切换当前分组内的各个终端。如需跨分组或跨工作区跳转，展开面板抽屉即可点击直达。
运行进程与面板抽屉
面板抽屉列出电脑上的所有工作区、分组与终端，也是新建终端的入口。长按某一行可弹出操作菜单，包括关闭窗格——关闭操作绝不会因误触而发生。
CONTROLS, EDITORS & DEVELOPER TOOLS
终端专属按键行
输入框上方的一排按键提供了终端必需但手机键盘缺失的关键按键：Esc、Tab、⌃C、方向键，并能根据窗格当前运行的程序智能动态变换——Shell 下显示常用指令，Claude Code 下显示 ⇧TAB 与 ⌃O，nvim 下显示 :w 与 gg。nvim 插入模式下自动以 Esc 居首。点击键盘按钮可唤出完整虚拟按键面板。如果不需要，可在“设置 → 终端”中随时关闭该按键行。
独立输入框（Composer）
等宽字体、支持多行输入，回车键直接换行——只有点击发送按钮才会执行命令，避免误触直接执行危险指令。输入框上方的提示文本会跟随当前窗格状态切换：执行终端命令、发送消息或在编辑器中输入。
历史输出与平滑滚动
从终端顶部下拉可加载更多历史回滚输出，加载时会显示指示图标。一旦离开屏幕底部的实时流，点击出现的“最新”胶囊即可瞬时回底。正在阅读上方内容时，新输出绝不会强行把屏幕拽走。
代码变更（Changes）
查看窗格所在目录的 Git 改动，和 AI 助手会话用的是同一个面板，详见下方“代码变更面板”。按钮上的角标是改动文件数，只有窗格在 Git 仓库里、且 Gateway 能提供差异时才会出现。
文件浏览器（Files）
查看会话生成的所有内容——图片、代码与各类文档，支持搜索与筛选，无需离开 App 即可直接预览阅读。
在浏览器中打开服务
输入本地开发服务监听的端口号，牧群会直接复用已有的连接通道打开它。完全不暴露至公网。若无法访问，通常是因为电脑上的服务仅绑定在了 127.0.0.1。
快捷指令（Quick actions）
保存常用命令、常用 Prompt 与快捷键组合，最常用的操作排在最前。支持自由添加与编辑默认指令。
代码变更面板
终端窗格和 AI 助手会话共用同一个代码变更面板。它在电脑上、在窗格或会话所在的目录里运行 git。
目录树
改动的文件按目录树排列，附文件数和增删行数。过长的名字从中间省略，保证扩展名可见；目录超过三层后不再继续缩进。
比较范围
顶部菜单在“未提交的改动”和“与分支基点比较”之间切换。基点是与 origin/HEAD 的合并基点，没有时用 main 或 master。
打开文件时才加载补丁
列表本身不带差异内容，所以改动再大也打开得快。“显示更多上下文”可以展开你正在看的补丁。
丢弃改动
在文件的 … 菜单里，确认后执行：已跟踪的文件恢复原状，未跟踪的文件直接删除。仓库就是你的主目录时，Gateway 会拒绝；任何指向仓库之外的路径也会被拒绝，包括指向外部的符号链接。
旧版 Gateway
终端里的“与基点比较”和“丢弃改动”需要提供 pane_vcs_files 的 Gateway。没有它，终端面板只显示同样的未提交改动目录树。
PAD 键盘与扩展按键
在平板上，屏幕键盘是一整套键盘：可隐藏的功能键行、数字行、可粘滞的 ctrl、alt、shift（双击锁定），方向键上方还有 Home、End、Page Up、Page Down。经典组合之外的按键——Ctrl+Enter、Shift+Enter、Ctrl+方向键、Alt+字母、F 键——只有在 Gateway 表示能送达时才会发送。
送不出去的键
Gateway 送达不了的键会显示为灰色，按下时会说明原因。按住修饰键时，这个组合够不到的键会变暗；被拒绝的组合同样会消耗掉单次修饰键。
Herdr
所有组合键都能送达，无需设置。
tmux
需要 tmux 3.2 或更新版本，并开启 extended-keys，窗格里的程序也要主动请求扩展按键。Ctrl+Enter 和 Shift+Enter 还需要 extended-keys-format csi-u。
Codex 与 Claude Code
tmux 里的 Codex 收不到 Shift+Enter，换行请用 ⌃J。Claude Code 用 \ 加回车换行。
tmux set -s extended-keys ontmux set -s extended-keys-format csi-u这两条命令立即生效，直到 tmux 服务器退出为止。想长期保留，把同样两行去掉开头的 tmux，写进 ~/.tmux.conf。
set -s extended-keys onset -s extended-keys-format csi-u●
牧群始终只作为观察者：打开会话绝不会打乱你的窗口布局，关闭手机 App 也绝不会终止任何后台任务。
muqun-gateway agent
AI 助手。
终端是你敲命令的 shell。AI 助手会话则是和电脑上运行的编程助手——Antigravity、Claude Code、Codex、Cursor、DeepSeek Harness、FX、OpenCode、Pi、Qoder CLI 或 T3 Code——的一段对话，App 把它画成消息、工具卡片和提问，而不是一屏文字。两者走的是同一台 Gateway、同一次配对，区别只在于 Gateway 替你和谁说话。
终端
电脑上的 tmux 或 Herdr。窗格里有什么，App 就显示什么；你发出的按键，就是程序收到的按键。所以任何程序都能用，包括跑在终端里的命令行助手，比如 Claude Code。
AI 助手会话
Gateway 通过助手自己的 API 与它对话。每个会话属于一个助手，也总会回到这个助手。工作台——模式、模型、斜杠命令、技能、附件、撤销、压缩、后台任务——只显示这个助手支持的部分。
4.0 支持的助手
codex
Codex
Codex 默认启用。Gateway 会自动发现 PATH 上的 codex 并接入其常驻 daemon（必要时自动启动）；直接复用本机的 ~/.codex 凭据，支持原生的助手会话、工具卡片与差异展示。
opencode
OpenCode
OpenCode 无需设置。Gateway 会接管已经在运行的 OpenCode 服务，没有就自己启动一个；需要 OpenCode 2。工作台的所有功能它都支持。
deepseek
DeepSeek Harness
DeepSeek Harness 默认关闭，需要你手动开启。先在电脑上启动 Harness，再让 Gateway 指向它。它的模式来自 Harness 自带的预设，在新建会话时选定；附件会以电脑上的文件路径交给它。
t3
T3 Code
T3 Code 在 Gateway 拿到凭据之前不会启用。Gateway 与 T3 配对一次，之后一直保存这份凭据。它支持附件、权限审批和撤销——T3 的撤销会整轮回滚，所以 App 会先确认再执行。
用命令行接入
在运行 Gateway 的电脑上执行。muqun-gateway agent 会从当前 shell 逐个检查助手，列出状态、版本和地址，没就绪的会写明下一步该做什么。只要有已启用的助手不可用，它就以非零状态退出，脚本也能拿来检查。
每个助手的状态，以及下一步该做什么。
muqun-gateway agent接入 T3 Code。T3 在同一台电脑上时，它会用 t3 auth session issue 签发凭据——T3 的数据不在默认位置时加上 --base-dir。T3 在另一台电脑上时，先在那台电脑运行 t3 pair，再用 --token CODE 传入配对码。
muqun-gateway agent setup t3找到正在运行的 DeepSeek Harness 并启用它。默认查找 3080 和 19387 端口；不在这两个端口时，用 --endpoint URL 指定。
muqun-gateway agent setup deepseek不做任何修改，只显示 Gateway 会使用哪个 OpenCode 程序及其版本——需要 2.x。
muqun-gateway agent setup opencodesetup 会写入 config.json，并告诉你正在运行的 Gateway 是否需要重启才能生效。如果 Gateway 以服务方式安装，确认后会替你重启（加 --yes 跳过确认）；否则请自己重启。
手动写入 config.json
CONFIG.JSON同样的设置，适合想自己动手的人。加上需要的配置块，然后重启 Gateway。t3 pair 给出的配对码填在 pairing_token；Gateway 下次启动时会兑换一次，之后不再需要它。opencode.binary 与 codex.binary 只在你想固定使用某个程序路径时才用。
{ "opencode": { "binary": "/usr/local/bin/opencode" }, "codex": { "enabled": true }, "deepseek": { "enabled": true, "endpoint": "http://127.0.0.1:3080" }, "t3": { "enabled": true, "url": "http://127.0.0.1:3773", "pairing_token": "CODE-FROM-T3-PAIR" }}●
T3 的凭据保存在 Gateway 状态目录下的 t3-credential.json 里（Linux 上是 ~/.local/share/muqun-gateway/），只有你本人可读。T3 吊销了它或它过期时，重新运行 agent setup t3 即可。
在手机上
每个助手一个入口
首页为 Gateway 报告的每个助手显示一个入口，上次用过的排在最前。超过三个时，其余的收进“更多助手”。有不止一个助手就绪时，新建会话会先问你用哪个。
提问会推送到手机
任何会话（包括子助手的会话）需要你填写表单时，所有已配对的手机都会收到一条“需要你的输入”的通知。权限请求照旧推送。
需要设置
Gateway 能看到这个助手，但还没有它的凭据。点开入口会显示要在电脑上运行的确切命令——T3 Code 是 t3 pair。
需要更新
助手使用的协议比这台 Gateway 认识的更新。在那台电脑上重新运行安装命令，更新 Gateway 即可。
未安装、离线
电脑上没有这个助手，或者它没在运行。入口会说明是哪种情况，并打开为这个助手写的启动指南。
旧版 Gateway
0.13 之前的 Gateway 不提供 multi_agent，App 会停留在只连 OpenCode 的单助手模式，并在某个功能需要新版 Gateway 时告诉你。
opencode serve --service
OpenCode 自主AI助手。
专为 OpenCode 打造的专属界面，而非局促在终端里的简单字符交互：自由切换会话、以可视化卡片展示内联 Diff 的工具调用，AI助手的问题以交互式表单呈现，轻轻一点即可确认。
本地运行时 · 零账号依赖
你的电脑直连模型服务商。
全程无需注册登录。牧群不提供账号体系，也不要求你填写 API 密钥，因为与大模型通信的不是手机 App，而是你自己电脑上的 OpenCode。你在电脑上配置好 Provider、模型、AI助手与技能，Gateway 绝不会中转传递任何凭据数据。
使用前提
- 在运行 Gateway 的电脑上安装 OpenCode 2.x。
- 在 OpenCode 中至少配置好一个模型服务商。支持配置各类免费模型，模型选择器内置“仅免费”过滤筛选项。
- OpenCode 服务正常运行。Gateway 默认会自动为你拉起该服务，也会自动挂载你手动启动的现有服务。
- Gateway 版本足够新并支持 AI助手 界面。如果版本过旧，OpenCode 按钮会自动隐藏，终端功能完全不受影响。
AGENT CAPABILITIES & WORKFLOW
会话与子AI助手
每个会话都是拥有独立上下文的对话，支持按项目或全局汇总展示。当一个任务衍生出子AI助手（Subagent）时，会以缩进卡片形式挂载在父会话下，复杂分工脉络依然一目了然。
项目切换
随时切换AI助手的工作目录，或手动输入路径开辟新项目。选定项目会直接恢复其最近一次的会话，无需每次从头开新对话。
模型与AI助手身份
“选择模型”面板列出已配置服务商实际提供的可用模型列表，标明各模型上下文窗口大小，并在免费模型上标注 Free 角标。“选择AI助手”可在 Build、Plan、Explore 及电脑上配置的自定义 AI 助手间快速切换。
斜杠命令与技能（Skills）
在输入框中输入 / 即可呼出指令菜单。部分指令由手机端直接响应（/new、/models、/compact、/undo、/export），其余指令透传至电脑端执行。电脑端配置的技能也会一并显示在列表中，执行时会在会话记录中清晰标出。
附件发送与文件引用
支持发送照片、相册图片或任意文件。图片在发送时会自动重新编码，抹除 EXIF 等隐私元数据。在输入框输入 @ 可直接模糊搜索并引用项目中的文件，省去手工描述的繁琐。
权限确认与问题回答
当AI助手需要执行命令、修改文件或读取项目外的文件时，会弹出确认卡片展示路径与细节，提供“允许”、“始终允许”与“拒绝”三个选项——与系统通知按钮文字完全一致，在锁屏界面即可直接审批。AI助手提问时会呈现为小表单供你填写。也支持开启“自动批准所有操作”以供近距观察，但极具破坏性的危险命令即便在此模式下依然会被强行拦截。
后台任务与排队执行
耗时较长的工具调用可以一键脱离至后台运行，在顶部托盘中实时观察进度。当当前回合正在运行时，你新输入的内容可选择立即插入引导，或是在本轮结束后排队执行；排队中的消息在发送前支持随时撤回。
上下文占用与自动压缩
上下文抽屉实时展示当前模型上下文窗口使用百分比、本次会话消耗的 Token 数量以及预估费用。当对话过长时会自动执行历史压缩，并在时间线中明确标记压缩发生的节点与是否为自动触发。
版本回滚（Undo）
输入 /undo 可将项目文件状态瞬时回滚到你上一条消息发出之前；输入 /redo 可取消尚未定稿的回滚。故意设计为显式命令而非单触按钮，杜绝意外误操作。
●
所有工具调用均以卡片呈现：文件修改卡片内嵌标准 Unified Diff 代码差异对比，与 Changes 审查视图保持完全一致。
config.json
配置 Gateway。
大多数人无需手动修改配置。仅在特定需求下需要调整：更换端口、随系统开机自启、或 OpenCode 安装在非标准路径等。
配置文件结构
JSON SCHEMA配置采用 JSON 格式，Gateway 在安装配置时会自动生成。只有在需要调整下列键值时才需手动编辑，编辑后必须重启 Gateway——配置仅在启动时读取，运行中的 Gateway 不会自动检测文件变动。在 macOS 上该文件位于 ~/Library/Application Support/muqun-gateway/；同级目录下存放 pairing.json；已配对设备、推送凭证及运行日志存放在状态目录 ~/.local/share/muqun-gateway/。
~/.config/muqun-gateway/config.jsonCONFIGURATION KEYS REFERENCE
labelApp 中为这台电脑显示的自定义名称。
listen监听的 Socket 地址（主机与端口）。默认为 0.0.0.0:23847；如果对外发布的地址是回环地址，则绑定到 127.0.0.1。
public_url编码到配对二维码中的连接地址——即手机实际拨号访问的地址。建议在管理器中按 u 修改，而非手动编辑。
transport_encryption传输加密配置，默认必选（required）。已配对设备会保持配对时的加密模式，修改此项仅影响后续新配对的设备。
sessions此 Gateway 挂载的终端后端（tmux、Herdr，或两者同时）。可通过 muqun-gateway backend 进行管理。
autostart_backends随 Gateway 启动自动拉起的终端后端。默认为空：启动终端服务必须由用户显式开启。
rich_agent_pushes默认关闭。开启后，AI助手的问题及选项会直接嵌入到通知消息体中——这意味着终端文本会显示在锁屏并经过系统推送服务器，因此默认关闭。
opencode.autostart默认开启：当 Gateway 检测到没有运行中的 OpenCode 服务时，会自动拉起。设置 "opencode": { "autostart": false } 可关闭自动拉起。
opencode.binary指定启动的 OpenCode 二进制路径。未指定时，Gateway 会使用 ~/.opencode/bin 中的路径或系统 PATH。当后台服务无法继承登录 Shell 的 PATH 时，可用此项固定路径。
codexCodex 编程助手。默认开启（enabled: true），自动寻找 PATH 上的 codex 并接入常驻 daemon；可用 codex.binary 指定可执行文件绝对路径，或将 enabled 设为 false 关闭。
deepseekDeepSeek Harness。只有 enabled 为 true 或填了 endpoint 时才会接入；Harness 需要时再填 token 和 secret。Gateway 不会扫描端口去找它。
t3T3 Code。enabled、url（默认 http://127.0.0.1:3773），再加上 t3 pair 给出的 pairing_token 或你已有的 token。runtime_mode 决定它的权限策略，默认 full-access。
端口与绑定
默认端口
单个 TCP 端口，23847。
修改端口
运行 muqun-gateway setup --port N，然后重启 Gateway。
监听地址
当发布的地址为回环地址时监听 127.0.0.1，否则监听 0.0.0.0。
私有网络
在同一个局域网或私有内网中通信，无需在路由器上做任何端口转发。
两种后台保活方式
DIRECT
手动后台启动
何时启动
手动执行命令时。
何时停止
执行 muqun-gateway stop，或电脑重启后。
重启后自启
否。
如何卸载
无需卸载，直接 stop。
muqun-gateway startSERVICE
作为系统服务
何时启动
用户登录时自动启动，崩溃后自动拉起。
何时停止
仅在执行 service uninstall 时停止。
重启后自启
是。
如何卸载
运行 service uninstall，已配对设备不受影响。
muqun-gateway service installLinux 下为 systemd 用户单元，macOS 下为 LaunchAgent。绝不使用 root 权限，绝不超出用户主目录。
OPENCODE AI助手拉起机制
- Gateway 首先检查是否存在已健康运行的 OpenCode 服务，读取其发布在 ~/.local/state/opencode/service.json 中的地址。
- 若已存在，则直接挂载附加，你原本运行的 opencode serve 会话得以完整保留。
- 若未发现，Gateway 会自动执行 opencode serve --service 并加以监控。在运行过程中会持续监测状态文件，当 OpenCode 在新端口重启时能自动重新识别。
●
电脑上未安装 OpenCode？Gateway 不会附加任何内容，仅手机端的 AI助手 面板会提示离线，终端功能完全不受任何影响。
"opencode": { "autostart": false }配对管理面板
运行 muqun-gateway manage 即可打开。面板内列出当前运行状态及所有已授权设备，支持以下快捷键：
p
重新显示配对二维码，以便添加新设备。
x
撤销选定设备的访问授权。
u
修改二维码中编码的连接地址；输入 a 可自动重新检测。
s / t
无需退出管理器，直接启动或停止 Gateway。
m / h
添加 tmux 或 Herdr 后端；f 设为默认，d 移除后端。
e
切换传输加密模式（影响后续新配对的设备）。
q
退出管理器。退出绝不会关闭你的终端会话。
旧版 Gateway 向上兼容
牧群 App 会主动向 Gateway 询问其支持的能力特性，而非仅凭版本号猜测；缺少的能力会自动隐去而非抛出异常。因此旧版 Gateway 依然可以作为完美的终端使用：你只是暂时无法使用较新的特性面板，但连接绝不会中断。多AI助手协同（Subagent）是唯一有额外后端要求的特性——该会话需要连接 Herdr 0.9.0 或更新版本，tmux 会话暂不支持。缺少对应能力时，App 会明确提示需要升级哪个组件。
版本升级
再次运行安装命令即可完成更新。它会直接原地替换二进制文件，并完整保留你的服务器身份密钥、连接地址、配置文件以及手机配对关系。若之前安装了系统服务，升级后请再执行一次 service install：服务单元包含子进程生命周期规则，重新刷新才能避免 Gateway 重启时意外连带终止终端会话。
查看运行日志
DIAGNOSTICS直接启动模式下，Gateway 的日志写入 ~/.local/share/muqun-gateway/gateway.log，macOS LaunchAgent 亦同。Linux systemd 模式下日志写入系统日志中。若需更详尽信息，启动前可设置环境变量 MUQUN_LOG=debug（或 RUST_LOG=debug）；默认日志级别为 info。
journalctl --user -u dev.osuki.muqun-gatewaymuqun.dev/themes
主题系统。
Cover Courier 是内置默认主题。可以从目录、文件或链接安装明暗主题，一起改变图片、界面配色和终端配色。
默认与导入主题
在设置 → 外观中选择主题；跟随系统、明亮与暗色决定其颜色模式。导入主题更新后会刷新当前主题，并保留你的外观偏好。
在线浏览主题目录
点击“浏览主题”可直接访问 muqun.dev 上的主题目录。只有当你点开某一款主题时才会发起下载，行内会预先标注包体积大小。
主题包的文件构成
一个 .muqun-theme 文件本质上是一个 Zip 压缩包，内部包含一个 theme.json 配置文件及存放 PNG、JPEG 或 WebP 图片的 assets 资源文件夹——不允许包含其他任何文件。.muqun-theme.json 则是纯色主题的独立清单文件，不附带图片资源。
主题清单涵盖的范围
主题定义界面、终端和 ANSI 配色、图片、图标及透明度。首页场景、整页壁纸与首页输入框插图各有独立槽位，可分别适配手机、Pad 和明暗模式。图片支持 PNG、JPEG 或 WebP，不支持外部字体、SVG 或动画文件。
包体积与规格限制
清单文件体积上限为 256 KiB，最多包含 32 张图片且单张不超过 8 MiB，打包后的主题总大小上限为 25 MiB。
从本地文件安装
通过文件管理器、AirDrop 或系统分享面板打开 .muqun-theme 文件，牧群会自动弹出导入提示，也可在主题抽屉中点击“导入文件”。若文件校验不通过会被整体拒绝，绝不会发生半生不熟的错误加载。
从网络链接安装
“导入链接”支持输入公开主题 URL 或 GitHub 仓库地址（目前唯一支持的仓库托管源）。你可以指定分支、Commit 哈希，若清单不在根目录还可指定文件路径。在下载任何资源之前，审查卡片会明确告知图片资源的托管域名。
在终端中一键安装
点击终端输出中出现的 .muqun-theme 文件路径，App 会弹出预览卡片：在你主动确认应用前，不会对现有环境产生任何影响。
应用前全屏实时预览
无论通过哪种途径安装，流程均一致：主题下载、解压并处理好资源后，整个 App 会临时换装供你四处巡览体验。在你点击“应用主题”之前，现行主题完全不受影响。
背景透明度微调
自定义主题提供两个独立滑块：“界面背景透明度”（仅调节彩色底色，不影响文字、图标与插画）与“终端背景透明度”（让 App 底图透射到终端文字后方）。两个滑块均支持全量程滑动，低于建议阈值时 App 会发出文字可读性警告，但绝不会强行阻止你。内置主题不提供透明度调节。
亲手制作一款主题
App 内不设繁杂的调色器：主题是以工程化文件形式编写的。牧群提供专门的主题制作技能，你只需向AI助手描述你想要的视觉风格（点击“创建牧群主题”快捷指令即可唤起），AI助手便会自动产出配置文件、绘制素材并打包成可导入的主题。
发布到社区目录
主题目录是一个公开的 GitHub 仓库并接收 Pull Request：将你的 src/<id> 目录提交 PR，合并后 CI 会自动打包，几分钟内便会收录在 muqun.dev 官网上。工具链会自动构建脚手架并在提交前严格校验色彩对比度。
删除与空间清理
在主题列表中轻扫某一行并确认，即可从本机彻底移除该主题。“设置 → 存储空间”中还提供“清理未使用主题”功能，一键清除所有当前未穿戴的历史主题资源。
连接异常排查
故障排查与速查。
绝大多数连接问题都可以归结为四种原因之一：Gateway 未启动、手机无法访问其地址、设备配对凭证丢失，或电脑端的 OpenCode 服务未正常运行。
快速检查清单
配对电脑
在自己的电脑上安装 Gateway（支持 tmux 或 Herdr），打开管理面板，在手机端牧群中扫描二维码，并在 App 中输入电脑上显示的确认码即可完成配对。
排查连接
检查 tmux 或 Herdr（0.7.5+）以及最新版 Gateway 是否正在运行。确认手机与电脑处于同一个局域网络，然后在牧群中重新打开该服务器连接。
移除设备
在牧群首页向左滑动删除服务器，即可撤销这台手机对该 Gateway 的授权。你也可以在电脑端 Gateway 管理面板中随时撤销任意已配对设备。
恢复通知
在手机系统设置与牧群 App 设置中同时开启通知权限。重新打开已配对的服务器，以便牧群将最新的设备推送 Token 重新注册到 Gateway。
DIAGNOSTIC SOLUTIONS
无法完成配对
提示“无法连接到网关（Could not reach the gateway）”意味着二维码中编码的地址在当前手机网络环境下无法连通。在电脑上运行 muqun-gateway status 查看状态，确认手机能够访问该 IP 地址——例如处于同一个 Wi-Fi 或局域网络中。若 Gateway 仅绑定在本地回环地址（127.0.0.1），除本机外任何外部设备均无法直接访问；可在管理面板中按 u 绑定发布真实局域网 IP，或通过保存的 SSH 主机进行隧道连接配对。
确认码被拒绝或已过期
短码由 8 位字符组成，有效期为 5 分钟，输错 8 次后将被强制废弃。在管理面板中按 p 键可重新生成一组全新的二维码与短码。短码字母表中已剔除了容易混淆的 0、1、I、L 和 O，若看到长相相似的字符请仔细甄别。
状态指示圆点的含义
实心圆点表示 App 已经完成探测并拿到了明确响应：显示为绿色代表 ONLINE 在线，显示为灰色代表 OFFLINE 离线。空心圆环并标注 NOT CONNECTED 表示尚未发起探测——这并不是故障报错，点击打开服务器即可立即建立连接。
提示需要重新配对
说明此手机对应的设备令牌在 Gateway 端已不存在——可能是在管理面板中手动撤销了授权，或是 Gateway 状态目录重建导致凭据丢失。重新完成一次扫码配对即可，手机上的其他配置与数据完全不受影响。
未能找到 OpenCode 服务
AI助手界面提示 OpenCode service offline，并提示你在电脑上运行 opencode serve --service。在电脑上执行该命令，然后点击手机上的“重新检查”。如果电脑上已经在运行但依然提示找不到，通常是因为 Gateway 探测到的二进制路径与你手动运行的不同：在 config.json 中显式指定 opencode.binary 为完整绝对路径后重启 Gateway。
模型显示为灰色，或没有免费模型
提示“需要在电脑端配置”意味着该服务商尚未在 OpenCode 中完成配置——在电脑端完成配置后重新打开选择器即可。“此主机无可用免费模型”说明“仅免费”过滤筛选项过滤掉了所有模型，并非系统故障；关闭该筛选项即可查看服务商提供的全部模型。牧群会在界面上展示每次会话的预估花销，但自身绝不收取任何模型费用，也不插手你与服务商之间的通信。
AI助手请求访问项目之外的路径
提示“读取项目外内容”或“写入项目外内容”正如其字面意思，弹出的卡片上会清晰标出涉及的具体绝对路径。点击“允许”授权本次，“始终允许”记住该路径，“拒绝”则拦截本次操作。安全防护机制正在尽职尽责——审批前请务必仔细核对目标路径。
找不到“代码变更（Changes）”按钮
只有终端位于 Git 仓库内，且 Gateway 版本足以提供差异时，这个按钮才会出现。“与基点比较”和“丢弃改动”需要 Gateway 0.13 或更新版本。重新运行安装命令即可升级。
部分特性提示需要更新 Gateway
牧群会主动探测 Gateway 的功能支持集，旧版 Gateway 只是无法使用新特性，终端核心连接完全不受影响。将任务指派给子AI助手这一特性额外需要会话后端为 Herdr 0.9.0 或更高版本（tmux 会话暂不支持），当缺少时 App 会明确指出需要升级哪个组件。
终端不可用
Gateway 在运行，但没有终端后端在运行——装了 tmux 却没有 tmux 服务器，或者 Herdr 没启动。屏幕上会列出 Gateway 的各个后端及其状态；启动其中一个，终端就会自动出现。AI 助手会话不受影响。
“此终端无法发送 ⌃↵”
Gateway 拒绝了这个组合键。用 tmux 时运行 tmux set -s extended-keys on；要用 Ctrl+Enter，再运行 tmux set -s extended-keys-format csi-u。提示下方会转述 Gateway 自己给出的说明。
助手入口显示“需要设置”或“需要更新”
在电脑上运行 muqun-gateway agent，它会写明每个助手的下一步。“需要更新”表示这台 Gateway 比助手的协议旧——重新运行安装命令即可。
github · issues
仍未解决？
前往 GitHub 提交 Issue。每一次功能迭代与缺陷修复都来源于此，每一条反馈都会被认真审阅。
USEFUL REPORT CHECKLIST
请附上 App 版本号、Gateway 版本号，以及问题发生前的具体操作步骤。