メニュー
日本語
テーマサポートGitHub ↗
ユーザーガイド · リファレンスマニュアル

手のひらから、いつでもマシンへ。

牧群は、スマートフォンをご自身のコンピューターやサーバーへ直接接続します。Gateway のセットアップ、端末ワークスペースの操作、コーディングエージェント（Antigravity、Claude Code、Antigravity、Claude Code、Codex、Cursor、DeepSeek Harness、FX、OpenCode、Pi、Qoder CLI CursorFXPiQoder CLI T3 Code）の設定と操作、テーマの追加、接続トラブルの診断手順を解説します。
使ってみる ↓トラブル診断 ↓問題を報告 ↗

MUQUN / 4.0.0

最初の目標から次の変更まで、ひとつのワークスペースで。

Codex、OpenCode、DeepSeek Harness、T3 Code のネイティブセッションに対応。スマホから権限承認やタスク追跡、差分確認を自分のマシン直結で行えます。

ホームから始める

パソコン、エージェント、モデル、モード、フォルダを選び、ファイルを添えて目標を送ると、会話やターミナルが開きます。

あなたを待つ作業を確認

パソコンのカードに実行中のタスク、進捗、判断待ち、最近の作業を表示。子タスクも親の作業とつながったままです。

話してから、確認する

送信を長押しして録音し、文字起こしを下書きへ。確認してから送信できます。ファイルまたはリアルタイムの文字起こしサービスを設定できます。

同じ作業場所でGitも

ChangesとLazygitを一緒に利用。対応するGatewayでは関連ワークツリーを閲覧でき、ターミナルのチェックアウトは変わりません。

ダウンロード前に更新内容を読む

互換性のある更新ではリリースノートと進捗を表示し、検証後に再起動。後でを選ぶと今回の起動中は通知を延期します。

文字だけではない返信

ネイティブ図、会話のファイル、選んだときだけ再生する音声プレビュー。プレビューを閉じるか音声入力を始めると再生は止まります。

一時ストレージを管理

Storageで削除可能なキャッシュを確認し、自動クリーンアップを設定できます。

Google PlayまたはApp Storeから更新してください。エージェント、タスク、Gitの機能はGatewayが提供する能力に応じます。古いGatewayでも対応するターミナルとOpenCodeを使えます。

muqun-gateway

Gateway をインストールし、スマートフォンとペアリングする。

牧群が通信するのは、あなたのコンピューター上で動く 1 つのプログラム「Gateway」だけです。コンピューターにインストールして起動し、スマートフォンで一度ペアリングするだけです。アカウント登録は不要で、いかなるデータも私たちのサーバーを経由しません。
PRE-FLIGHT REQUIREMENTScheck before installing
  • 自身が所有・管理する macOS または Linux マシン（Windows は現在未対応）。
  • tmux、または Herdr 0.7.5 以降がインストール済みであること（Gateway はこれらを代替するのではなく制御します）。
  • 両方のデバイスが同じプライベートネットワーク上にあること。Tailscale の利用を推奨します（Tailscale Serve を使用し、Funnel は使用しないでください）。
  • アカウント作成不要、サブスクリプションなし、外部リレーサーバー不使用。

  1. コンピューターでインストーラーを実行する

    バイナリを ~/.local/bin/muqun-gateway に配置して自動設定し、初回実行時にペアリング画面を開きます。macOS および Linux に対応（Windows は現在未対応です）。
    install
    curl -fsSL https://muqun.dev/gateway.sh | sh

  2. 2 つの方法のいずれかで起動する

    手動で直接起動するか、システムのバックグラウンドサービスに登録して自動管理させるかを選択できます。どちらでも Gateway は正常に稼働しますが、再起動時の挙動が異なります。
    OPTION A · DIRECT

    手動で直接起動

    バックグラウンドで動作し、端末を閉じても再起動するまで稼働し続けます。muqun-gateway stop で停止します。
    direct
    muqun-gateway start
    OPTION B · SERVICE

    常駐サービスとして実行

    ユーザーの初期化システム（Linux は systemd ユーザーユニット、macOS は LaunchAgent）に登録します。ログイン時に自動起動し、クラッシュや再起動後も自動で復旧します。muqun-gateway service uninstall でペアリングを維持したまま登録を解除できます。
    service
    muqun-gateway service install
    どちらか一方のみを選択してください。サービスをインストールしている場合、手動で stop しても監視プロセスによって直ちに再起動されます。

  3. ペアリングマネージャーを開く

    どちらの起動方法でも、次はマネージャーを開きます。端末内で全画面表示され、QR コード、稼働状況、現在トークンを保持している全デバイスを確認できます。初回は自動で開きますが、後からいつでもこのコマンドで再表示できます。
    pair
    muqun-gateway manage

  4. QR コードをスキャンし、コードを入力する

    牧群アプリで 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

ワークスペース、グループ、端末

3 階層で構成され、「ワークスペース · グループ.パネル」として管理されます。ワークスペースは作業フォルダ、グループは複数の端末のまとまり、端末は個々のシェルです。スマートフォンの画面分割は読みにくいため、常に 1 画面に 1 つの端末のみを最適化して表示します。

階層間の移動

上部のタイトルピルを左右にスワイプするとワークスペースが切り替わります。入力欄の上のチップをタップすると同一グループ内の端末を切り替えられます。別のグループやワークスペースへ移動するには、パネルドロワーを開いて選択します。

プロセス管理とパネル一覧

パネルドロワーには、マシン上のすべてのワークスペース、グループ、端末が一覧表示され、新しい端末を追加することもできます。行を長押しするとメニューが開き、安全にペインを閉じることができます。
TypeScript ファイルを開いた nvim ペイン。同グループ内の Claude Code、nvim、zsh タブと、入力欄の上のキーバーが表示されている。TypeScript ファイルを開いた nvim ペイン。同グループ内の Claude Code、nvim、zsh タブと、入力欄の上のキーバーが表示されている。
CONTROLS, EDITORS & DEVELOPER TOOLS

端末専用キーバー

入力欄の上にあるバーには、スマートフォンのキーボードにはない Esc、Tab、⌃C、矢印キーが並びます。さらにシェルではコマンド、Claude Code では ⇧TAB や ⌃O、nvim では :w や gg など、実行中のプログラムに応じて動的にキーが変化します。「設定 → 端末」で非表示にすることも可能です。

専用入力欄（Composer）

等幅フォント、複数行入力に対応し、改行キーはそのまま改行として機能します。意図しないコマンド実行を防ぐため、送信は専用ボタンで行います。入力欄の上には状態に応じたプロンプトが表示されます。

過去の出力を確認

端末の上部から下に引っ張ると、より過去のスクロールバックを読み込めます。リアルタイム表示から離れると「最新」ピルが表示され、タップで一瞬で戻れます。スクロールして読んでいる最中に新しい出力で画面が勝手に引っ張られることはありません。

変更履歴（Changes）

ペインのあるディレクトリの git の変更を表示します。エージェントのセッションと同じシートです——下の「変更シート」を参照。ボタンには変更ファイル数が付き、ペインが git のチェックアウト内にあり、Gateway が差分を提供できるときだけ表示されます。

ファイル閲覧（Files）

セッションで作成された画像、コード、ドキュメントを検索・プレビューできます。アプリを離れることなく内容を確認できます。

ブラウザで開く

開発サーバーのポート番号を入力すると、既存の安全な接続を通してブラウザでプレビューできます。インターネット上に公開されることはありません。

クイックアクション

よく使うコマンドやプロンプト、キー操作を保存しておけます。使用頻度の高いものが上位に表示され、カスタマイズも自由に行えます。
変更シート
ターミナルのペインとエージェントのセッションは同じ変更シートを使います。ホスト上で、ペインまたはセッションのディレクトリで git を実行します。

ツリー

変更されたファイルをフォルダのツリーで、ファイル数と行数の合計付きで表示します。長い名前は中央を省略して拡張子が見えるようにし、深いフォルダは 3 段より先はインデントしません。

範囲

上部のメニューで「未コミットの変更」と、ブランチの起点との比較を切り替えます。起点は 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
tmux set -s extended-keys ontmux set -s extended-keys-format csi-u
この 2 つはすぐに効き、tmux サーバーが終了するまで続きます。残しておくには、先頭の tmux を除いた同じ 2 行を ~/.tmux.conf に書きます。
~/.tmux.conf
set -s extended-keys onset -s extended-keys-format csi-u
●
牧群は常に安全なオブザーバーとして振る舞います。セッションを開いてもウィンドウレイアウトは崩れず、アプリを閉じてもバックグラウンドの処理が止まることはありません。

muqun-gateway agent

エージェント。

ターミナルは入力するためのシェルです。エージェントのセッションは、あなたのコンピューターで動くコーディングエージェント——Antigravity、Claude Code、Antigravity、Claude Code、Codex、Cursor、DeepSeek Harness、FX、OpenCode、Pi、Qoder CLI CursorFXPiQoder CLI T3 Code——との会話で、アプリはそれを文字の画面ではなく、メッセージ、ツールカード、質問として描きます。どちらも同じ Gateway、同じペアリングを通ります。違うのは、Gateway があなたの代わりに話す相手です。

ターミナル

ホストの tmux か Herdr。ペインに映っているものをそのまま表示し、送ったキーはそのままプログラムに届きます。だからどんなプログラムでも動き、Claude Code のようにターミナルで直接動く CLI エージェントも使えます。

エージェントのセッション

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 の取り消しはターン単位で巻き戻すため、アプリは実行前に確認します。
コマンドラインで設定する
Gateway が動いているコンピューターで実行します。muqun-gateway agent はシェルから各エージェントを確認し、状態、バージョン、アドレスと、準備ができていないものには次の手順を表示します。有効なエージェントが使えない間は 0 以外で終了するので、スクリプトからも確認できます。
すべてのエージェントの状態と、次にやること。
status
muqun-gateway agent
T3 Code をペアリングします。同じマシンでは t3 auth session issue で資格情報を発行します——T3 のデータが別の場所にあるなら --base-dir を付けます。別のホストの T3 なら、そちらで t3 pair を実行し、コードを --token CODE で渡します。
t3
muqun-gateway agent setup t3
動いている DeepSeek Harness を見つけて有効にします。ポート 3080 と 19387 を探すので、別の場所なら --endpoint URL を指定します。
deepseek
muqun-gateway agent setup deepseek
何も変更しません。Gateway が使う OpenCode のバイナリとそのバージョンを表示します——2.x が必要です。
opencode
muqun-gateway agent setup opencode
setup は config.json を書き換え、動いている Gateway に反映するために再起動が必要かどうかを伝えます。サービスとしてインストールした Gateway なら確認のうえ再起動します（--yes で確認を省略）。そうでなければ自分で再起動してください。

config.json に手で書く

CONFIG.JSON
同じ設定を自分で書きたい場合に。必要なブロックを足して Gateway を再起動します。t3 pair のコードは pairing_token に入れます。次の起動時に Gateway が一度だけ交換し、その後は不要になります。opencode.binary と codex.binary は特定のバイナリに固定したいときだけ使います。
config.json
{  "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 の状態ディレクトリ（Linux では ~/.local/share/muqun-gateway/）の t3-credential.json にあり、あなただけが読めます。T3 に取り消されたり期限が切れたりしたら、agent setup t3 をもう一度実行します。
スマホでは

エージェントごとのタイル

ホームには Gateway が報告するエージェントごとにタイルが並び、最後に使ったものが先頭に来ます。3 つを超えると残りは「その他のエージェント」に入ります。複数が準備できていれば、新しいセッションはどれを使うか尋ねます。

質問はプッシュで届く

セッション（サブエージェントのものも含む）がフォームへの入力を求めると、ペアリング済みのすべてのスマホに「入力が必要です」という通知が一度届きます。権限リクエストはこれまでどおりプッシュされます。

要設定

Gateway からエージェントは見えていますが、資格情報がありません。タイルを開くと、ホストで実行するコマンドがそのまま表示されます——T3 Code なら t3 pair。

要アップデート

エージェントが、この Gateway の知らない新しいプロトコルを話しています。そのコンピューターでインストールコマンドをもう一度実行して Gateway を更新します。

未インストール、オフライン

エージェントがホストにない、または動いていません。タイルがどちらかを示し、そのエージェント向けの起動ガイドを開きます。

古い Gateway

0.13 より前の Gateway は multi_agent を提供しないため、アプリは OpenCode だけのシングルエージェントモードのままになり、新しい Gateway が必要な機能ではその旨を伝えます。

opencode serve --service

OpenCode 自律エージェント。

端末の中に無理やり押し込めたエージェントではなく、OpenCode のために設計された専用インターフェースです。複数セッションの切り替え、Diff を直接確認できるツール呼び出しカード、タップで回答できる対話フォームを提供します。
ローカル実行 · アカウント不要

コンピューターがモデル提供元と直接通信します。

ログインは一切不要です。牧群アプリはアカウントも API キーも要求しません。なぜなら、モデルプロバイダーと対話するのはアプリではなく、あなた自身のマシン上で動く OpenCode だからです。Gateway は資格情報に一切関与しません。
動作要件
  • Gateway と同じマシンに OpenCode 2.xがインストールされていること。
  • 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 SCHEMA
JSON 形式で記述されており、セットアップ時に自動生成されます。以下のキーを変更する場合のみ手動で編集し、完了後に必ず Gateway を再起動してください（起動時のみ読み込まれるため、実行中の変更は反映されません）。macOS では ~/Library/Application Support/muqun-gateway/ に配置されます。同ディレクトリには pairing.json が置かれ、ペアリング済みデバイス、プッシュトークン、ログは ~/.local/share/muqun-gateway/ に保存されます。
linux
~/.config/muqun-gateway/config.json
CONFIGURATION 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_backends
Gateway 起動時に同時に自動起動するバックエンド。デフォルトは空（意図しない起動を防ぐため）。
rich_agent_pushes
デフォルトはオフ。有効にすると、エージェントの質問や選択肢がプッシュ通知本文に含まれるようになります（端末の文字列がロック画面や Apple / Google のサーバーを通過するため、標準ではオフになっています）。
opencode.autostart
デフォルトでオン。起動中の OpenCode が見つからない場合、Gateway が自動で起動します。"opencode": { "autostart": false } で無効化できます。
opencode.binary
起動する OpenCode のバイナリパス。省略時は ~/.opencode/bin 内またはシステム PATH から探します。常駐サービスがログインシェルの PATH を引き継げない場合に明示します。
codex
Codex コーディングエージェント。デフォルトで有効（enabled: true）。PATH 上の codex を検出し共有 daemon に接続します。codex.binary で実行ファイルの絶対パスを指定するか、enabled を false にして無効化します。
deepseek
DeepSeek Harness。enabled が true か、endpoint が指定されたときだけ接続します。Harness が必要とするなら token と secret も。Gateway がポートを探しに行くことはありません。
t3
T3 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 を実行後、再起動。

バインド先

公開アドレスがループバックの場合は 127.0.0.1、それ以外は 0.0.0.0。

tailnet 内での接続

ルーターでのポート転送は一切不要です。そのため利用を推奨しています。
2 つの常駐方法
DIRECT

手動で直接起動

起動タイミング
コマンドを手動実行したとき。
停止タイミング
muqun-gateway stop、またはマシンの再起動。
再起動後の自動復旧
なし。
解除方法
停止するのみ。
direct
muqun-gateway start
SERVICE

常駐サービスとして実行

起動タイミング
ログイン時に自動起動、クラッシュ時も自動復旧。
停止タイミング
service uninstall を実行したときのみ。
再起動後の自動復旧
あり。
解除方法
service uninstall（ペアリング情報は保持されます）。
service
muqun-gateway service install
Linux では systemd ユーザーユニット、macOS では LaunchAgent を利用します。root 権限は一切不要で、ホームディレクトリ外には一切配置されません。
OPENCODE の自動起動ロジック
  1. すでに健全に稼働している OpenCode サービスが存在するか ~/.local/state/opencode/service.json を確認します。
  2. 見つかった場合はそのプロセスに直接アタッチし、実行中の opencode serve のセッションをそのまま引き継ぎます。
  3. 見つからない場合は、Gateway 自身が opencode serve --service を起動して監視します。OpenCode が別のポートで再起動した場合も自動で追従します。
●
マシンに OpenCode が入っていない場合でも、何もアタッチされないだけで端末機能には何の影響もありません。
config.json
"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 です。
linux · サービスモード
journalctl --user -u dev.osuki.muqun-gateway

muqun.dev/themes

テーマ機能。

内蔵の標準テーマはCover Courierです。カタログ、ファイル、リンクから明暗テーマを入れ、画像とアプリ・ターミナルの色をまとめて変えられます。

標準テーマとインポート

設定 → 外観でテーマを選び、システム・ライト・ダークで表示モードを選択します。インポートしたテーマの更新は外観設定を保ちながら選択中のテーマに反映されます。

カタログをブラウズ

muqun.dev で公開されているオンラインカタログを閲覧できます。行を開くまでダウンロードは始まらず、事前にファイルサイズを確認できます。

テーマファイルの構造

.muqun-theme は theme.json と画像（PNG, JPEG, WebP）が入った assets フォルダで構成される Zip ファイルです。.muqun-theme.json は配色設定のみを含む単一のマニフェストファイルです。

カスタマイズ可能な範囲

テーマはアプリ・ターミナル・ANSIの色、画像、アイコン、不透明度を定義します。ホームの場面、全画面壁紙、ホーム入力欄の画像は別々のスロットで、スマホ・タブレット・明暗に対応できます。PNG・JPEG・WebPに対応し、外部フォント・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 が差分を提供できる新しさのときだけ表示されます。起点との比較と破棄には Gateway 0.13 以降が必要です。インストールコマンドをもう一度実行すれば更新できます。

より新しい Gateway が必要と表示される

古い Gateway でも端末機能はそのまま使えますが、新しい拡張機能が制限されます。エージェントコラボレーション機能には Herdr 0.9.0 以降が必要です。画面の案内に従って該当コンポーネントを更新してください。

ホストがプロキシ環境下にある

モデルプロバイダーと通信するのはコンピューター側です。インターネット接続にプロキシが必要な環境では、ホストの OpenCode にプロキシ設定を行ってください。牧群が通信を中継することはありません。

ターミナルを利用できません

Gateway は動いているのに、ターミナルのバックエンドが動いていません——tmux はあっても tmux サーバーがない、または Herdr が起動していない状態です。画面に Gateway のバックエンドと状態が並ぶので、どれかを起動すればターミナルは自動的に現れます。その間もエージェントのセッションは使えます。

「このターミナルには ⌃↵ を送れません」

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 Issues でご報告ください。すべてのフィードバックに目を通し、次期バージョンの改善に役立てています。
USEFUL REPORT CHECKLIST
アプリのバージョン、Gateway のバージョン、問題発生直前の操作手順を添えてお送りください。
GitHub で Issue を開く ↗
PRIVACY GUARANTEE

プライバシーと安全な報告のために

サポート対応において、アクセストークン、端末の全出力、機密ソースコード、ペアリング用 QR が必要になることは決してありません。スクリーンショットやログを添付する際は、機密情報を必ずマスキングしてください。
プライバシーポリシーを読む