從首頁開始
選擇電腦、助手、模型、模式和目錄，附上檔案後送出目標，直接開啟對話或終端機。
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 負責驅動它們，而非取代它們。
- 兩台裝置處於同一個私有網路。建議使用 Tailscale；請使用 Tailscale Serve，請勿使用 Funnel。
- 無帳號系統、無訂閱收費，中間沒有任何我們的轉送節點。
在電腦上執行安裝指令碼
指令碼會將單一執行檔安裝至 ~/.local/bin/muqun-gateway，完成初始設定，並在首次執行時自動開啟配對畫面。支援 macOS 與 Linux；目前尚未支援 Windows。install curl -fsSL https://muqun.dev/gateway.sh | sh選擇兩種執行模式之一啟動
你可以手動啟動它，也可以交由系統常駐保活。兩種方式都能啟動 Gateway，差別在於系統重新開機後的行為。二選一，請勿同時使用：安裝系統服務後，手動執行 stop 會被服務守護程序立即重新喚醒。開啟配對管理員
無論採用哪種啟動方式，這都是下一步。管理員是終端機裡的全螢幕面板，顯示配對 QR 碼、執行狀態以及目前持有存取權杖的所有裝置。安裝程式首次會自動開啟；之後你可以隨時用此指令重新開啟。pair muqun-gateway manage掃描並輸入確認短碼
在手機上的牧群中掃描 QR 碼。電腦螢幕上會顯示一組形如 XXXX-XXXX 的短碼，在 App 中輸入即可完成配對。單憑掃描無法完成配對——輸入短碼才能證明拿著手機的人就是電腦前的你。
MANUAL ADDRESS PAIRING
無法掃描？可以在 App 中手動輸入 Gateway 位址（管理員會印出目前對外發布的連線位址），然後再輸入相同的短碼。
CODE VALIDITY & RETRIES
短碼有效時間為 5 分鐘，輸錯 8 次後將作廢。在管理員中按 p 鍵可立即重新整理產生全新的 QR 碼與確認碼。
推薦私有網路
在兩台裝置上都使用 Tailscale。
我們強烈建議將手機與執行 Gateway 的電腦放入同一個 Tailscale tailnet。這樣可以免除路由器通訊埠轉發，並避免將 Gateway 暴露在公開網際網路上。Tailscale Serve 可以提供私有 HTTPS 位址；請勿為牧群使用 Tailscale Funnel。
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）
等寬字體、支援多行輸入，Enter 鍵直接換行——只有點選發送按鈕才會送出指令，避免誤觸直接執行危險指令。輸入框上方的提示文字會跟隨當前窗格狀態切換：執行終端機指令、傳送訊息或在編輯器中輸入。
歷史輸出與平滑捲動
從終端機頂部下拉可載入更多歷史捲動輸出，載入時會顯示指示符號。一旦離開螢幕底部的即時串流，點選出現的「最新」膠囊即可瞬間回到底部。閱讀上方內容時，新輸出絕不會強行把畫面拉走。
變更（Changes）
查看窗格所在目錄的 Git 變更，與 AI 助手工作階段用的是同一個面板，詳見下方「變更面板」。按鈕上的標記是變更檔案數，只有窗格位於 Git 儲存庫內、且 Gateway 能提供差異時才會出現。
檔案瀏覽器（Files）
檢視工作階段生成的所有內容——圖片、程式碼與各類文件，支援搜尋與篩選，無需離開 App 即可直接預覽閱讀。
在瀏覽器中開啟服務
輸入本機開發伺服器監聽的通訊埠，牧群會直接透過已建立的通道開啟它。完全不暴露至公網。若無法存取，通常是因為電腦上的服務僅綁定在 localhost。
快速動作（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 以 \ 加 Enter 換行。
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 及電腦上自訂的 Agent 間快速切換。
斜線指令與技能（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編碼到配對 QR 碼中的連線位址——即手機實際撥號連線的位址。建議在管理員中按 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。
在 tailnet 上
無需在路由器上做任何通訊埠轉發，這也是我們強烈推薦的原因。
兩種常駐執行模式
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
重新顯示配對 QR 碼，以新增裝置。
x
撤銷所選裝置的存取權限。
u
修改 QR 碼中編碼的連線位址；輸入 a 可自動重新偵測。
s / t
無需離開管理員，直接啟動或停止 Gateway。
m / h
新增 tmux 或 Herdr 後端；f 設為預設，d 移除後端。
e
變更傳輸加密模式（影響後續新配對的裝置）。
q
關閉管理員。關閉絕不會終止你的終端機工作階段。
舊版 Gateway 向後相容
牧群 App 會主動向 Gateway 詢問其支援的功能特性，而非僅憑版本號猜測；缺少的功能會自動隱藏而非拋出錯誤。因此舊版 Gateway 依然可以作為出色的終端機使用：你只是暫時無法使用較新的功能面板，但連線絕不會中斷。AI 助手協同工作（Agent collaboration）是唯一有額外後端要求的功能——該工作階段需要連線至 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 內不設複雜的調色工具：主題是以工程化檔案形式編寫的。牧群提供專門的主題製作 Agent 技能，你只需向 AI 助手描述你想要的視覺風格（點選「建立牧群主題」快速動作即可啟動），AI 助手便會自動產生設定檔、繪製素材並打包成可匯入的主題。
發布至社群目錄
主題目錄是一個公開的 GitHub 倉儲並接受 Pull Request：將你的 src/<id> 資料夾提交 PR，合併後 CI 會自動打包，幾分鐘內便會收錄在 muqun.dev 官方網站上。工具鏈會自動建構基礎骨架並在提交前嚴格檢查色彩對比度。
刪除與空間清理
在主題清單中滑動某一行並確認，即可從本機徹底移除該主題。「設定 → 儲存空間」中還提供「清理未使用主題」功能，一鍵清除所有目前未套用的歷史主題資源。
連線異常排解
疑難排解與速查。
絕大多數連線問題都可以歸納為四種原因之一：Gateway 未啟動、手機無法連線到位址、裝置配對權杖遺失，或電腦端的 OpenCode 服務未正常運作。
快速檢查清單
配對電腦
在自己的電腦上安裝 Gateway（支援 tmux 或 Herdr），開啟管理員面板，在手機端牧群中掃描 QR 碼，並在 App 中輸入電腦上顯示的確認碼即可完成配對。
檢查連線
確認 tmux 或 Herdr（0.7.5+）以及最新版 Gateway 正在執行。確認手機與電腦能連線到相同的私有位址，然後在牧群中重新開啟該伺服器連線。
移除裝置
在牧群首頁向左滑動刪除伺服器，即可撤銷這台手機對該 Gateway 的存取權限。你也可以在電腦端 Gateway 管理員面板中隨時撤銷任意已配對裝置。
恢復推播通知
在手機系統設定與牧群 App 設定中同時開啟通知權限。重新開啟已配對的伺服器，以便牧群將最新的裝置推播權杖重新註冊至 Gateway。
DIAGNOSTIC SOLUTIONS
無法完成配對
提示「無法連線至閘道（Could not reach the gateway）」代表 QR 碼中編碼的位址在當前手機網路環境下無法連通。在電腦上執行 muqun-gateway status 查看狀態，確認手機足以連線到該位址——例如處於同一個 Wi-Fi，或更好的是同一個 tailnet。若 Gateway 僅繫結在本機回環位址（127.0.0.1），除本機外任何外部裝置均無法存取；可在管理員中按 u 發布真實區域網路 IP，或透過儲存的 SSH 主机進行通道配對。
確認碼被拒絕或已過期
短碼由 8 個字元組成，有效時間為 5 分鐘，輸錯 8 次後將被強制作廢。在管理員中按 p 鍵可重新產生一組全新的 QR 碼與短碼。短碼字元集中已排除容易混淆的 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 會明確指出需要升級哪個元件。
電腦處於 Proxy 代理伺服器之後
與大模型提供商通訊的是你的電腦，因此如果電腦需要透過 Proxy 才能連線外網，必須在電腦端的 OpenCode 中妥善設定網路代理環境變數。牧群不會轉發也不會接觸此類流量。
終端機無法使用
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 版本號，以及問題發生前的具體操作步驟。