ワークスペース、グループ、端末
3 階層で構成され、「ワークスペース · グループ.パネル」として管理されます。ワークスペースは作業フォルダ、グループは複数の端末のまとまり、端末は個々のシェルです。スマートフォンの画面分割は読みにくいため、常に 1 画面に 1 つの端末のみを最適化して表示します。
muqun-gateway
Gateway をインストールし、スマートフォンとペアリングする。
牧群が通信するのは、あなたのコンピューター上で動く 1 つのプログラム「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 | sh2 つの方法のいずれかで起動する
手動で直接起動するか、システムのバックグラウンドサービスに登録して自動管理させるかを選択できます。どちらでも Gateway は正常に稼働しますが、再起動時の挙動が異なります。どちらか一方のみを選択してください。サービスをインストールしている場合、手動で stop しても監視プロセスによって直ちに再起動されます。ペアリングマネージャーを開く
どちらの起動方法でも、次はマネージャーを開きます。端末内で全画面表示され、QR コード、稼働状況、現在トークンを保持している全デバイスを確認できます。初回は自動で開きますが、後からいつでもこのコマンドで再表示できます。pair muqun-gateway manageQR コードをスキャンし、コードを入力する
牧群アプリで QR コードをスキャンします。コンピューター画面に XXXX-XXXX 形式の短い確認コードが表示されるので、アプリに入力してペアリングを完了します。スキャンだけでは完了しません。コード入力によって操作しているのがあなた自身であることを証明します。
MANUAL ADDRESS PAIRING
カメラでスキャンできませんか？アプリで手動で Gateway のアドレスを入力（マネージャー画面に公開アドレスが表示されます）し、同じ確認コードを入力してください。
CODE VALIDITY & RETRIES
確認コードの有効期限は 5 分間で、8 回誤入力すると無効化されます。マネージャーで p キーを押すと新しい QR コードと確認コードが再生成されます。
推奨プライベートネットワーク
両方のデバイスで Tailscale を使用する。
スマートフォンと Gateway が動くコンピューターを同じ Tailscale tailnet に参加させることを強くお勧めします。ルーターのポート転送が不要になり、Gateway を公衆インターネットに公開せずに済みます。Tailscale Serve でプライベート HTTPS アドレスを追加できます（牧群では Tailscale Funnel を使用しないでください）。
workspace · group.panel
本物の端末を、そのまま。
画面のスクリーンショットでもログの再生でもなく、マシン上で動いている本物の端末です。Gateway が tmux や Herdr を制御し、アプリがそれをリアルタイムに描画します。机の上で残したセッションの続きを、そのまま手の中で操作できます。
WORKSPACE ARCHITECTURE
階層間の移動
上部のタイトルピルを左右にスワイプするとワークスペースが切り替わります。入力欄の上のチップをタップすると同一グループ内の端末を切り替えられます。別のグループやワークスペースへ移動するには、パネルドロワーを開いて選択します。
プロセス管理とパネル一覧
パネルドロワーには、マシン上のすべてのワークスペース、グループ、端末が一覧表示され、新しい端末を追加することもできます。行を長押しするとメニューが開き、安全にペインを閉じることができます。
CONTROLS, EDITORS & DEVELOPER TOOLS
端末専用キーバー
入力欄の上にあるバーには、スマートフォンのキーボードにはない Esc、Tab、⌃C、矢印キーが並びます。さらにシェルではコマンド、Claude Code では ⇧TAB や ⌃O、nvim では :w や gg など、実行中のプログラムに応じて動的にキーが変化します。「設定 → 端末」で非表示にすることも可能です。
専用入力欄（Composer）
等幅フォント、複数行入力に対応し、改行キーはそのまま改行として機能します。意図しないコマンド実行を防ぐため、送信は専用ボタンで行います。入力欄の上には状態に応じたプロンプトが表示されます。
過去の出力を確認
端末の上部から下に引っ張ると、より過去のスクロールバックを読み込めます。リアルタイム表示から離れると「最新」ピルが表示され、タップで一瞬で戻れます。スクロールして読んでいる最中に新しい出力で画面が勝手に引っ張られることはありません。
変更履歴（Changes）
ペインのディレクトリの Git 状態を確認できます。変更されたファイル数、ステージ済み / 未ステージの絞り込み、Diff のインライン表示が可能です。Git 管理下かつ Gateway が対応している場合のみ表示されます。
ファイル閲覧（Files）
セッションで作成された画像、コード、ドキュメントを検索・プレビューできます。アプリを離れることなく内容を確認できます。
ブラウザで開く
開発サーバーのポート番号を入力すると、既存の安全な接続を通してブラウザでプレビューできます。インターネット上に公開されることはありません。
クイックアクション
よく使うコマンドやプロンプト、キー操作を保存しておけます。使用頻度の高いものが上位に表示され、カスタマイズも自由に行えます。
●
牧群は常に安全なオブザーバーとして振る舞います。セッションを開いてもウィンドウレイアウトは崩れず、アプリを閉じてもバックグラウンドの処理が止まることはありません。
opencode serve --service
OpenCode 自律エージェント。
端末の中に無理やり押し込めたエージェントではなく、OpenCode のために設計された専用インターフェースです。複数セッションの切り替え、Diff を直接確認できるツール呼び出しカード、タップで回答できる対話フォームを提供します。
ローカル実行 · アカウント不要
コンピューターがモデル提供元と直接通信します。
ログインは一切不要です。牧群アプリはアカウントも API キーも要求しません。なぜなら、モデルプロバイダーと対話するのはアプリではなく、あなた自身のマシン上で動く OpenCode だからです。Gateway は資格情報に一切関与しません。
動作要件
- Gateway と同じマシンに OpenCode 2.0.1 以降がインストールされていること。
- OpenCode 内で少なくとも 1 つのモデルプロバイダーが設定されていること（無料モデルのみの絞り込みにも対応）。
- OpenCode サービスが稼働していること（Gateway が自動起動するか、手動起動したプロセスに自動アタッチします）。
- エージェント画面に対応した Gateway バージョンであること（古い場合はボタンが非表示になり、端末機能のみが動作します）。
AGENT CAPABILITIES & WORKFLOW
セッションとサブエージェント
セッションごとに独立したコンテキストを保持します。サブエージェントが生成された場合は親セッションの下にインデントされてぶら下がり、並列タスクの進行状況を整理して把握できます。
プロジェクトの切り替え
エージェントの作業ディレクトリを切り替えるか、新しいパスを指定します。プロジェクトを選ぶと、毎回新しく作り直すのではなく直前のセッションが自動で再開されます。
モデルとエージェントの選択
プロバイダーごとに利用可能なモデルがコンテキスト長とともに一覧表示されます。無料モデルには Free バッジが付きます。エージェントは Build、Plan、Explore やカスタムエージェントから選べます。
スラッシュコマンドとスキル
入力欄に / と入力するとコマンド一覧が表示されます。/new、/models、/compact、/undo、/export などはアプリが即座に応答し、その他のコマンドやスキルはホスト側の OpenCode で実行されます。
添付ファイルと @ メンション
写真やファイルをエージェントに直接送信できます。画像は送信時に再エンコードされ、EXIF などのメタデータは自動削除されます。@ を入力するとプロジェクト内のファイルを補完選択できます。
権限リクエストと確認
エージェントがコマンドを実行したり、ファイルを変更したり、プロジェクト外を読み込もうとすると承認カードが表示されます。「許可」「常に許可」「拒否」から選択でき、ロック画面の通知からも直接ワンタップで応答できます。
バックグラウンド実行とキューイング
時間のかかるツール呼び出しはバックグラウンドに切り離してトレイから進行を見守ることができます。実行中に新しい指示を入力した場合、即座に介入するか、完了後にキューとして順番に実行するかを選択できます。
コンテキスト消費と自動要約
モデルのコンテキストウィンドウの消費率、消費トークン数、推定コストをリアルタイムで確認できます。履歴が長くなると自動要約（コンパクション）が行われ、タイムライン上に明記されます。
アンドゥ機能（Undo）
/undo と入力すると、直前のメッセージ送信前の状態にプロジェクトをロールバックできます。/redo で取り消しも可能です。誤操作を防ぐため、ボタンではなくあえてコマンドとして設計されています。
●
ツール呼び出しはカードとして届きます。ファイルの変更は Changes ビューと同様、インラインの Unified Diff で確認できます。
config.json
Gateway の設定。
通常は設定ファイルを直接変更する必要はありません。別のポートを使用したい場合や、再起動後も自動で常駐させたい場合、OpenCode を特殊なパスに配置している場合などに調整します。
設定ファイル
JSON SCHEMAJSON 形式で記述されており、セットアップ時に自動生成されます。以下のキーを変更する場合のみ手動で編集し、完了後に必ず Gateway を再起動してください（起動時のみ読み込まれるため、実行中の変更は反映されません）。macOS では ~/Library/Application Support/muqun-gateway/ に配置されます。同ディレクトリには pairing.json が置かれ、ペアリング済みデバイス、プッシュトークン、ログは ~/.local/share/muqun-gateway/ に保存されます。
~/.config/muqun-gateway/config.jsonCONFIGURATION KEYS REFERENCE
labelアプリ上でこのコンピューターに対して表示される表示名。
listenバインドするソケット（ホストとポート）。デフォルトは 0.0.0.0:23847（公開アドレスがループバックの場合は 127.0.0.1）。
public_urlペアリング QR に埋め込まれる接続先アドレス。手動編集ではなく、マネージャー画面で u キーを押して変更することを推奨します。
transport_encryption通信暗号化設定。デフォルトは安全な required（必須）。各デバイスはペアリング時の暗号化設定を保持するため、変更は以降新しくペアリングするデバイスにのみ適用されます。
sessionsこの Gateway がマウントする端末バックエンド（tmux、Herdr、またはその両方）。muqun-gateway backend で管理します。
autostart_backendsGateway 起動時に同時に自動起動するバックエンド。デフォルトは空（意図しない起動を防ぐため）。
rich_agent_pushesデフォルトはオフ。有効にすると、エージェントの質問や選択肢がプッシュ通知本文に含まれるようになります（端末の文字列がロック画面や Apple / Google のサーバーを通過するため、標準ではオフになっています）。
opencode.autostartデフォルトでオン。起動中の OpenCode が見つからない場合、Gateway が自動で起動します。"opencode": { "autostart": false } で無効化できます。
opencode.binary起動する OpenCode のバイナリパス。省略時は ~/.opencode/bin 内またはシステム PATH から探します。常駐サービスがログインシェルの PATH を引き継げない場合に明示します。
ポートと接続
デフォルト
単一の TCP ポート、23847。
ポート変更
muqun-gateway setup --port N を実行後、再起動。
バインド先
公開アドレスがループバックの場合は 127.0.0.1、それ以外は 0.0.0.0。
tailnet 内での接続
ルーターでのポート転送は一切不要です。そのため利用を推奨しています。
2 つの常駐方法
DIRECT
手動で直接起動
起動タイミング
コマンドを手動実行したとき。
停止タイミング
muqun-gateway stop、またはマシンの再起動。
再起動後の自動復旧
なし。
解除方法
停止するのみ。
muqun-gateway startSERVICE
常駐サービスとして実行
起動タイミング
ログイン時に自動起動、クラッシュ時も自動復旧。
停止タイミング
service uninstall を実行したときのみ。
再起動後の自動復旧
あり。
解除方法
service uninstall（ペアリング情報は保持されます）。
muqun-gateway service installLinux では systemd ユーザーユニット、macOS では LaunchAgent を利用します。root 権限は一切不要で、ホームディレクトリ外には一切配置されません。
OPENCODE の自動起動ロジック
- すでに健全に稼働している OpenCode サービスが存在するか ~/.local/state/opencode/service.json を確認します。
- 見つかった場合はそのプロセスに直接アタッチし、実行中の opencode serve のセッションをそのまま引き継ぎます。
- 見つからない場合は、Gateway 自身が opencode serve --service を起動して監視します。OpenCode が別のポートで再起動した場合も自動で追従します。
●
マシンに OpenCode が入っていない場合でも、何もアタッチされないだけで端末機能には何の影響もありません。
"opencode": { "autostart": false }ペアリングマネージャー
muqun-gateway manage で開きます。稼働中のプロセスや認証済み端末が一覧表示され、以下のキー操作に対応しています。
p
新しいデバイスを追加するための QR コードを再表示。
x
指定したデバイスのアクセス権限を取り消し。
u
QR に含まれる接続先アドレスを編集（a で自動再検出）。
s / t
マネージャーを閉じずに Gateway を起動または停止。
m / h
tmux または Herdr バックエンドを追加（f でデフォルト設定、d で削除）。
e
今後ペアリングするデバイスの通信暗号化設定を変更。
q
マネージャーを閉じる（端末セッションは一切停止しません）。
古い Gateway との下位互換性
牧群アプリはバージョン番号だけで判断するのではなく、Gateway に対応機能を問い合わせ、未対応の機能はエラーにするのではなく自然に非表示にします。そのため古い Gateway でも優れた端末としてそのまま機能します。エージェントコラボレーション機能のみ、接続中の Herdr 0.9.0 以降が必要となります（tmux セッションでは非対応）。要件を満たさない場合は、どのコンポーネントをアップデートすべきか具体的に案内されます。
アップグレード手順
インストール時と同じコマンドを再度実行してください。バイナリのみが置き換えられ、サーバー識別子、接続アドレス、設定、ペアリング済みスマートフォンはすべてそのまま保持されます。サービスとして登録していた場合は、アップデート後に再度 service install を実行してください。
ログの確認
DIAGNOSTICS直接起動モードおよび macOS LaunchAgent では ~/.local/share/muqun-gateway/gateway.log に出力されます。Linux の systemd では journalctl に記録されます。詳細な情報が必要な場合は起動前に環境変数 MUQUN_LOG=debug（または RUST_LOG=debug）を設定してください。通常は info です。
journalctl --user -u dev.osuki.muqun-gatewaymuqun.dev/themes
テーマ機能。
アプリと端末の配色を統一して美しく彩ります。すべてのテーマパックにライト用とダーク用の 2 つのパレットが用意されています。24 種類がプリセットされており、コミュニティカタログから自由に追加できます。
標準同梱の 24 パック
「設定 → 外観 → テーマ」から選択できます。Catppuccin、Gruvbox、Kanagawa、Rosé Pine、Tokyo Night、Everforest などを収録。カラーモード（自動、ライト、ダーク）でどちらの明暗パレットを適用するかを切り替えます。
カタログをブラウズ
muqun.dev で公開されているオンラインカタログを閲覧できます。行を開くまでダウンロードは始まらず、事前にファイルサイズを確認できます。
テーマファイルの構造
.muqun-theme は theme.json と画像（PNG, JPEG, WebP）が入った assets フォルダで構成される Zip ファイルです。.muqun-theme.json は配色設定のみを含む単一のマニフェストファイルです。
カスタマイズ可能な範囲
各モード 17 種類のインターフェースカラー、端末の背景・文字・カーソル・リンク・選択色、全 16 色の ANSI カラー、11 箇所の背景アートワーク、3 つのカスタムアイコン（戻る、送信、添付）、初期不透明度などが指定できます。フォントや SVG、アニメーションは含まれません。
ファイル制限
マニフェストは最大 256 KiB、画像は 1 枚あたり最大 8 MiB（最大 32 枚）、パッケージ全体で最大 25 MiB までとなっています。
ファイルからインストール
ファイルアプリや AirDrop、共有シートから .muqun-theme を開くか、テーマ画面の「ファイルをインポート」を使用します。不正な形式のファイルは安全に拒絶されます。
リンクからインストール
「リンクをインポート」から公開 URL または GitHub リポジトリ（ブランチやコミットの指定も可能）を指定して読み込めます。ダウンロード前に画像の取得先ドメインが表示されます。
端末出力から直接追加
端末に出力された .muqun-theme のパスをタップするとプレビューカードが表示され、手軽に試すことができます。
適用前のリアルタイムプレビュー
ダウンロード後、アプリ全体に一時的にテーマが適用され、自由に歩き回って確認できます。「テーマを適用」を押すまでは現在のテーマが変更されることはありません。
背景の不透明度スライダー
カスタムテーマでは「インターフェース背景の不透明度」と「端末背景の不透明度」を調整できます。文字やアートワークの視認性を保ちながら背景を透かすことができます。
テーマの自作
テーマはテキストファイルとして記述します。牧群にはテーマ作成用の専用エージェントスキルが用意されており、作りたいイメージを伝えるだけでマニフェストと素材を自動生成できます。
カタログへの公開
カタログは GitHub 上で管理されており、Pull Request で追加できます。マージされると CI がパッケージ化し、数分で muqun.dev に掲載されます。
不要なテーマの削除
テーマ一覧からスワイプして簡単に削除できます。「設定 → ストレージ」から現在使用していないテーマを一括整理することもできます。
when it does not connect
トラブルシューティング。
接続トラブルの多くは「Gateway が動いていない」「アドレスに届かない」「ペアリング情報が消えた」「OpenCode が起動していない」の 4 つのいずれかです。
クイックチェック
コンピューターをペアリングする
コンピューターに Gateway を導入し（tmux または Herdr に対応）、マネージャー画面を開いて牧群アプリから QR をスキャン、表示された確認コードを入力してください。
接続を修復する
tmux または Herdr（0.7.5 以降）と最新の Gateway が起動していることを確認してください。両機器が同一のプライベートアドレスに接続できることを確認し、アプリでサーバーを再度開きます。
デバイスを削除する
牧群のホーム画面でサーバーを削除すると、その Gateway からスマートフォンの登録が解除されます。コンピューターのマネージャー画面から解除することも可能です。
通知を再登録する
スマホのシステム設定および牧群の設定で通知を許可してください。ペアリング済みサーバーを開き直すことで、最新のプッシュトークンが Gateway に再登録されます。
DIAGNOSTIC SOLUTIONS
ペアリングできない
「Could not reach the gateway」と表示される場合、QR コード内のアドレスにスマホから到達できていません。コンピューターで muqun-gateway status を確認し、同じ Wi-Fi または Tailscale 等の tailnet に接続されているか確認してください。ループバック（127.0.0.1）にバインドされている場合は外部から届きません。マネージャーで u を押して実アドレスを指定するか、SSH ホスト経由でペアリングしてください。
コードが拒否される・期限が切れた
確認コードは 8 文字で有効期間は 5 分です。8 回間違うと無効化されます。マネージャー画面で p キーを押して新しい QR とコードを発行してください。誤認を防ぐため 0、1、I、L、O は含まれていません。
ステータスドットの意味
塗りつぶされた丸は応答が得られた状態（緑は ONLINE、グレーは OFFLINE）です。白抜きの円で NOT CONNECTED と表示されている場合はまだ確認を行っていない状態です。サーバーをタップして開けば接続されます。
再度ペアリングを求められる
Gateway 側の端末トークンが失われています（マネージャーで取り消されたか、Gateway の状態ディレクトリが再作成されたなど）。もう一度 QR をスキャンしてペアリングしてください。
OpenCode が見つからない
エージェント画面に OpenCode service offline と表示される場合は、ホスト側で opencode serve --service を実行し、「再確認」をタップしてください。すでに実行中の場合は、config.json 内の opencode.binary にフルパスを指定して Gateway を再起動してください。
モデルがグレーアウトしている、または無料モデルがない
「ホスト側で設定が必要」と出る場合は、OpenCode 側でプロバイダー設定を行ってください。「無料モデルがありません」と出る場合は、無料フィルターを解除すると利用可能なすべてのモデルが表示されます。牧群が独自に料金を請求することはありません。
エージェントがプロジェクト外へのアクセスを求めている
「プロジェクト外の読み込み」「プロジェクト外への書き込み」の通知には対象パスが明記されています。「許可」「常に許可」「拒否」から選択してください。安全のため、パスをよく確認してから承認してください。
「Changes」ボタンが表示されない
端末のカレントディレクトリが Git 管理下にあり、かつ Gateway が Diff 機能に対応している場合のみ表示されます。最新のインストーラーを実行して Gateway を更新してください。
より新しい Gateway が必要と表示される
古い Gateway でも端末機能はそのまま使えますが、新しい拡張機能が制限されます。エージェントコラボレーション機能には Herdr 0.9.0 以降が必要です。画面の案内に従って該当コンポーネントを更新してください。
ホストがプロキシ環境下にある
モデルプロバイダーと通信するのはコンピューター側です。インターネット接続にプロキシが必要な環境では、ホストの OpenCode にプロキシ設定を行ってください。牧群が通信を中継することはありません。
github · issues
問題が解決しませんか？
GitHub Issues でご報告ください。すべてのフィードバックに目を通し、次期バージョンの改善に役立てています。
USEFUL REPORT CHECKLIST
アプリのバージョン、Gateway のバージョン、問題発生直前の操作手順を添えてお送りください。
PRIVACY GUARANTEE
プライバシーと安全な報告のために
サポート対応において、アクセストークン、端末の全出力、機密ソースコード、ペアリング用 QR が必要になることは決してありません。スクリーンショットやログを添付する際は、機密情報を必ずマスキングしてください。