デーモンモード（qwen serve）

Qwen Code をローカル HTTP デーモンとして起動し、複数のクライアント（IDE プラグイン、Web UI、CI スクリプト、カスタム CLI）が HTTP + Server-Sent Events 経由で、それぞれサブプロセスを起動する代わりに一つのエージェントセッションを共有できます。

🚧 v0.16-alpha: qwen serve は v0.16-alpha として npm に初リリースされます。この段階ではテキストのみのチャット／コーディングとローカル専用デプロイが対象です。プロンプトパスでの画像／ファイル添付、コンテナ化デプロイ（Docker / k8s / nginx リバースプロキシ）、リモート／マルチデーモンの堅牢化は、エンタープライズパイロットが確定した後続パッチで追加されます。保留機能の全一覧は v0.16-alpha の既知の制限 を参照してください。

ステータス: Stage 1（実験的）。プロトコルサーフェスは issue #3803  の §04 ルートテーブルでロック済みです。Stage 1.5（qwen --serve フラグ — TUI が同一 HTTP サーバーを共同ホスト）および Stage 2（インプロセスリファクタ + mDNS / OpenAPI / WebSocket / Prometheus の整備）は直後にリリース予定です。

スコープの説明: Stage 1 はプロトコルサーフェスに対してクライアントをプロトタイプする開発者およびローカル単一ユーザー／小規模チームのコラボレーションを対象として設計されています。モバイルコンパニオンや 1000 件以上のチャットを処理する IM ボットなど、本番グレードのマルチクライアント／長時間稼働／ネットワーク不安定なワークロードには、このリリースに含まれない Stage 1.5+ の保証が必要です。ギャップの全一覧は Stage 1.5+ の実行時保証 を、コンバージェンスロードマップは #3803 を参照してください。

提供される機能

• 組み込みの Web Shell UI — qwen serve はデーモンルート（http://127.0.0.1:4170/）でブラウザベースの Web Shell をすぐに提供します。qwen serve --open を使用するとブラウザで自動的に開きます。API と同じオリジンで配信されるため、追加ポートやリバースプロキシは不要です。API のみのデーモンにするには --no-web を指定してください。
• 一つのエージェントプロセスで複数クライアント — デフォルトの sessionScope: 'single' では、デーモンに接続するすべてのクライアントが一つの ACP セッションを共有します。同一の会話、同一のファイル差分、同一の権限プロンプトをリアルタイムにクロスクライアントでコラボレーションできます。
• 再接続に安全なストリーミング — Last-Event-ID による再接続対応の SSE で、クライアントが切断しても（リングのリプレイウィンドウ内で）正確に中断した箇所から再開できます。
• 最初に応答した者が権限を持つ — エージェントがツールの実行許可を求めると、接続中のすべてのクライアントがリクエストを受信し、最初に応答したクライアントの回答が採用されます。
• 一つのデーモン、一つのワークスペース — 各 qwen serve プロセスは起動時にちょうど一つのワークスペースにバインドされます（#3803  §02 準拠）。マルチワークスペースデプロイでは、別々のポートで（またはオーケストレーターの背後で）ワークスペースごとに一つのデーモンを起動してください。
• リモートランタイム制御（#4175  PR 17）— セッションの承認モードを変更（POST /session/:id/approval-mode）、ワークスペース単位でツールのトグル（POST /workspace/tools/:name/enable）、空の QWEN.md のスキャフォールド（POST /workspace/init、機械的な操作のみ — モデルを呼び出しません。AI で内容を埋めるには続けて POST /session/:id/prompt を使用してください）、予算チェック付きで単一の MCP サーバーを再起動（POST /workspace/mcp/:server/restart）、またはデーモンを再起動せずに実行時に MCP サーバーを追加・削除（POST /workspace/mcp/servers、DELETE /workspace/mcp/servers/:name）できます。すべて strict-gated — 事前に --token を設定してください。
• セッション要約（#4175  フォローアップ）— アクティブなセッションの「どこで中断したか」を一文で取得（POST /session/:id/recap）。コアの generateSessionRecap を高速モデルへのサイドクエリとしてラップします。メインのチャット履歴や SSE ストリームには影響しません。Non-strict gate（/prompt と同じ姿勢）。SDK ヘルパー client.recapSession(sessionId)。
  • 既知の制限 — トークンコスト増幅: このルートは純粋なコストエンドポイントです（各呼び出しが LLM サイドクエリで、状態の利益はありません）。v1 ではデーモンにルート単位のレート制限がありません。no-token ループバックのデフォルトでは、バグのある、または悪意あるローカルクライアントがスパムしてトークンを消費する可能性があります。共有開発ホストでデーモンを公開する前に --token（および必要に応じて --require-auth）を設定してください。
  • 同時実行時の recap の安全性: 同一セッションで同時に /recap を 2 回呼び出すと、それぞれ独立したサイドクエリが実行されます。generateSessionRecap は GeminiClient.getChat().getHistory() 経由でチャット履歴のスナップショットを読み取り、別の BaseLlmClient.generateText 呼び出し（runSideQuery 経由）に渡します。セッションの GeminiChat への追記や変更は行いません。複数のクライアントから調整なしで安全に呼び出せます。

v0.16-alpha の既知の制限

qwen serve の最初の npm リリース（v0.16-alpha）は意図的に限定的なスコープになっています — 開発者が自分のマシンでデーモンを実行するためのテキストのみのチャット／コーディングです。以下のリストは保留されたサーフェスを明示し、採用者が計画を立てられるようにしています。ここに記載されたすべての項目は v0.16.x のパッチロードマップまたは近い将来のフォローアップリリースに含まれています。

製品サーフェス — テキストのみ:

• ✅ テキストプロンプトとテキストレスポンス（チャット、コーディング、ツール呼び出し、MCP 連携）
• ❌ プロンプトパスでの画像／ファイル添付 — MessageEmitter は現在テキストのみをレンダリングします。マルチモーダルエコーは画像ニーズのあるアルファターゲットが確定したときに追加されます（#4175 chiga0 #27 P0 アイテム）
• ❌ ストリーミングアップロード — マルチモーダルと同じゲーティング

デプロイサーフェス — ローカル専用:

• ✅ ループバック（127.0.0.1、デフォルト）— 認証不要、開発用ワークステーションに適しています
• ✅ systemd / launchd / nohup & / tmux 経由のローカル起動 — ローカル起動テンプレート を参照
• ✅ QWEN_SERVER_TOKEN 環境変数によるベアラートークンの持ち込み（設定方法は 認証）
• ❌ コンテナ化デプロイ — Docker / Compose / Kubernetes / TLS 終端の nginx リバースプロキシは v0.16-alpha 非対応。エンタープライズパイロットが確定後に v0.16.x で追加予定（検証者がいない状態では品質低下が避けられないため）。
• ❌ 単一ホストでのマルチデーモン調整 — 1 daemon = 1 workspace × N sessions が強制されます。クロスホストフェデレーション、インスタンスパストークンキーイング、古いトークンのクリーンアップは v0.16.x で対応予定。
• ❌ デーモントークンの自動生成 — アルファは BYO トークン（openssl rand -hex 32 一発で生成）。自動生成 + トークンストアのインフラは v0.16.x で対応予定。

堅牢化 — ローカル単一ユーザーの最低限の実行可能性:

• ✅ 起動時のセキュリティゲート（トークンなしでのループバック以外のバインドを拒否、PR 15 / #4236 ）
• ✅ ミューテーションルートの認証ゲート、セッションスコープの権限ルーティング（Wave 4 PR）
• ✅ MCP ガードレール + マルチクライアント権限調整（F2 / F3）
• ✅ プロンプト絶対デッドライン + SSE ライターアイドルタイムアウト — --prompt-deadline-ms と --writer-idle-timeout-ms でオプトイン。有効時は prompt_absolute_deadline と writer_idle_timeout でアドバタイズされます。
• ✅ HTTP レート制限 — --rate-limit とティア別しきい値でオプトイン。有効時は rate_limit でアドバタイズされます。
• ⏸️ Prometheus メトリクス + ロードテストハーネス — 30〜50 のアクティブセッションが実際のターゲットになる v0.17 F4 Phase-1 スケールインストルメンテーションで対応予定。
• ⏸️ --max-body-size CLI フラグ — デーモンはデフォルトで express.json({ limit: '10mb' }) を適用しており、テキストのみのプロンプト（モデルコンテキストウィンドウは 10 MiB の文字数を大幅に下回ります）には十分です。v0.16.x でフラグによる調整が可能になります。

Stage 1 で修正しないことの詳細な説明（単一ホストのセッション状態ミューテーションモデル + 1 つの ACP 子プロセスを共有する N 並列セッション）については、以下の Stage 1 のスコープ境界 を参照してください。

クイックスタート

1. デーモンを起動する（ループバック、認証なし）

cd your-project/
qwen serve
# → qwen serve listening on http://127.0.0.1:4170 (mode=http-bridge, workspace=/path/to/your-project)
# → qwen serve: bearer auth disabled (loopback default). Set QWEN_SERVER_TOKEN to enable.

デフォルトのバインドは 127.0.0.1:4170 です。ローカル開発がすぐに動作するよう、ループバックではベアラー認証は無効です。デーモンはカレントワーキングディレクトリにバインドします。オーバーライドするには --workspace /path/to/dir を使用してください。

Web Shell UI を開く。 http://127.0.0.1:4170/ をブラウズするか（または qwen serve --open でデーモン起動時に自動的に開く）、チャット、差分、ツール呼び出し、権限プロンプトを含むフルブラウザターミナルをご利用ください。UI はデーモンルートで API と同じオリジンから提供されます。このガイドの残りの部分では、API に対して直接スクリプトを実行できるよう生の HTTP を使用します。

2. 動作確認

curl http://127.0.0.1:4170/health
# → {"status":"ok"}
 
curl http://127.0.0.1:4170/capabilities
# → {"v":1,"mode":"http-bridge","features":["health","daemon_status","capabilities","session_create",...],"workspaceCwd":"/path/to/your-project"}
 
curl http://127.0.0.1:4170/daemon/status
# → {"v":1,"detail":"summary","status":"ok","runtime":{...}}

workspaceCwd フィールドはバインドされたワークスペースを示すため、クライアントはプリフライトチェックができ、POST /session で cwd を省略できます。 limits.maxPendingPromptsPerSession フィールドはアクティブなセッション単位のプロンプト受付上限をアドバタイズします。null は上限が無効であることを意味します。

デーモンはクライアント UI とオペレーター向けに読み取り専用のランタイムスナップショットも公開しています: GET /daemon/status、GET /workspace/mcp、 GET /workspace/skills、GET /workspace/providers、GET /workspace/env、 GET /workspace/preflight、 GET /session/:id/context、GET /session/:id/supported-commands、 GET /session/:id/tasks、GET /session/:id/lsp。

GET /session/:id/lsp はセッションごとの LSP ステータスを構造化して返します。スポーンされたエージェントセッションで LSP を有効にするには --experimental-lsp でデーモンを起動してください。無効の場合、このルートはサーバーなしで enabled: false を返します。

GET /daemon/status は統合されたトラブルシューティングスナップショットです。デフォルトの detail=summary はインメモリのデーモン状態（セッション、権限、SSE/ACP トランスポート数、レート制限拒否、プロセスメモリ、解決済み制限）のみを読み取り、ACP 子プロセスを起動しません。アクティブに問題を調査している場合は GET /daemon/status?detail=full を使用して、セッション単位の診断、ACP 接続詳細、認証デバイスフロー数、ワークスペースステータスセクションを取得してください。

GET /workspace/mcp、GET /workspace/skills、GET /workspace/providers はライブ ACP ランタイムをレポートし、アイドル時には ACP 子プロセスを起動しません。アイドル中のデーモンは空のスナップショットで initialized: false を返します。セッションがアクティブになると initialized: true に切り替わり、実際の状態を表示します。

GET /workspace/env と GET /workspace/preflight は ACP の状態に関わらず常に initialized: true で応答します。env は ACP を参照しません（デーモンプロセスの情報のみ）。preflight は process.* からデーモンレベルのセルを返し、子プロセスがアイドル中の ACP レベルセルには status: 'not_started' プレースホルダーを返します。

GET /workspace/env はデーモンプロセスのランタイム、プラットフォーム、サンドボックス、プロキシ、および OPENAI_API_KEY などのホワイトリスト済みシークレット環境変数の存在（値は返しません）をレポートします。プロキシ URL は認証情報が除去され、host:port 形式に変換されてから出力されます。このルートは常にデーモンプロセスから直接応答し、ACP 子プロセスをスポーンしません。

GET /workspace/preflight は準備状況チェックのリストを返します。デーモンレベルのセル（Node バージョン、CLI エントリ、ワークスペースディレクトリ、ripgrep、git、npm）は常にレンダリングされます。ACP レベルのセル（認証、MCP ディスカバリー、スキル、プロバイダー、ツールレジストリ、egress）にはライブの ACP 子プロセスが必要です — デーモンがアイドル中の場合、ACP を起動する代わりに status: 'not_started' プレースホルダーを返します。失敗は閉じられた errorKind 列挙型（missing_binary、auth_env_error、init_timeout、protocol_error、missing_file、parse_error、blocked_egress）にマッピングされるため、クライアント UI は構造化された修復手順をレンダリングできます。

デーモンはワークスペースファイルヘルパーも公開しています:

• GET /file はテキストファイルを読み取り、生バイトの sha256:<hex> ハッシュを返します。
• GET /file/bytes は境界付きの生バイトウィンドウを読み取り、base64 コンテンツを返します。
• POST /file/write はテキストファイルを作成または置き換えます。
• POST /file/edit は一つの正確なテキスト置換を適用します。

Write / edit は strict ミューテーションルート: ループバックでも設定済みのベアラートークンが必要で、ない場合は token_required を返します。置換と編集には GET /file（またはフルウィンドウの GET /file/bytes）からの最新の expectedHash が必要です。create は上書きしません。無視されたパスへの明示的な書き込みは許可されますが監査されます。バイナリ書き込み、削除/移動/mkdir、再帰的な親ディレクトリ作成はこのサーフェスの対象外です。

3. セッションを開く

curl -X POST http://127.0.0.1:4170/session \
  -H 'Content-Type: application/json' \
  -d '{}'
# → {"sessionId":"<uuid>","workspaceCwd":"…","attached":false}

cwd は省略できます — ルートはデーモンのバインドされたワークスペースにフォールバックします。バインドされたワークスペースと一致しない cwd を POST すると 400 workspace_mismatch が返ります（デーモンは正確に一つのワークスペースにバインドされています。別のワークスペースには別のデーモンを起動してください）。

2 番目のクライアントが /session に POST すると（一致する cwd またはなし）、"attached": true が返ります — エージェントを共有していることになります。

4. イベントストリームを購読する（最初に別のターミナルで）

SESSION_ID="<from step 3>"
curl -N http://127.0.0.1:4170/session/$SESSION_ID/events
# → id: 1
#   event: session_update
#   data: {"id":1,"v":1,"type":"session_update","data":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"…"}}}

data: 行はフルイベントエンベロープ — {id?, v, type, data, originatorClientId?} — を一行に JSON 文字列化したものです。ACP ペイロード（この例では sessionUpdate ブロック）はそのエンベロープ内の data の下に入ります。SSE レベルの id: / event: 行は EventSource クライアント向けの便宜上のもので、同じ値が JSON エンベロープ内にも含まれているため、生の fetch コンシューマーにも届きます。

プロンプトを送信する前にこれを開いてください — SSE リプレイバッファは最後の 8000 イベントを保持しているため、遅れた購読者は Last-Event-ID でキャッチアップできますが、「単一プロンプトを見る」という単純なケースでは先に購読してライブストリームを受信するのが最も簡単です。

ストリームは session_update（LLM チャンク、ツール呼び出し、使用状況）、permission_request（ツールの承認が必要）、permission_resolved（誰かが投票）、model_switched、model_switch_failed、そして終端フレーム session_died（エージェント子プロセスがクラッシュ — SSE は閉じられます）と client_evicted（キューがオーバーフロー — SSE は閉じられます）を送信します。

5. プロンプトを送信する（元のターミナルに戻って）

curl -X POST http://127.0.0.1:4170/session/$SESSION_ID/prompt \
  -H 'Content-Type: application/json' \
  -d '{"prompt":[{"type":"text","text":"What does src/main.ts do?"}]}'
# → {"stopReason":"end_turn"}

ステップ 4 の curl -N がフレームを受信次第表示します。

認証

ループバック以外では、ベアラートークンを必ず渡す必要があります:

export QWEN_SERVER_TOKEN="$(openssl rand -hex 32)"
qwen serve --hostname 0.0.0.0 --port 4170
# → boot refuses without QWEN_SERVER_TOKEN

クライアントはすべてのリクエストに Authorization: Bearer $QWEN_SERVER_TOKEN を付けて送信します。/health はポッド内でデーモンが 127.0.0.1 でリッスンしている場合（k8s/Compose のライブネスプローブが認証情報を必要としないよう）、ループバックバインドのみ免除されます。非ループバックバインド（--hostname 0.0.0.0 など）では、/health も他のすべてのルートと同様にトークンが必要です — そうしないと攻撃者がデーモンの存在を確認するために任意のアドレスを探索できてしまいます。トークンがエンドツーエンドで正しいか確認するには /capabilities を使用してください（常に認証が必要です）:

ループバックの堅牢化（--require-auth）。 デフォルトのループバックでトークンなしの動作は、単一ユーザーのノートパソコンには問題ありませんが、ローカルユーザーが curl 127.0.0.1:4170 を実行できる共有開発ホスト、CI ランナー、マルチテナントワークステーションでは安全ではありません。--require-auth を指定すると、127.0.0.1 にバインドしていても、/health や /capabilities を含むすべてのルートでベアラートークンが必須になります。トークンなしでは起動に失敗します。このフラグが有効の場合、未認証のクライアントは /capabilities で認証が必要であることを発見できません。発見サーフェスは 401 レスポンスボディ自体です。認証後は caps.features.require_auth タグがデプロイが堅牢化されていることの事後確認になります（監査/コンプライアンス UI に有用）:

qwen serve --require-auth --token "$(openssl rand -hex 32)"
# → /health, /capabilities, /session, … all require Authorization: Bearer …
curl http://127.0.0.1:4170/health
# → 401
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:4170/capabilities | jq '.features | index("require_auth")'
# → 13   (or whatever index — non-null after authenticating means the tag is present)

curl -H "Authorization: Bearer $QWEN_SERVER_TOKEN" http://your-host:4170/capabilities
# → {"v":1,"mode":"http-bridge","features":[...],"modelServices":[],"workspaceCwd":"/path/to/your-project"}
# Wrong token → 401

トークン比較は定数時間（SHA-256 + crypto.timingSafeEqual）で行われます。401 レスポンスは「ヘッダーなし」「スキームが違う」「トークンが違う」を区別しない統一された形式で、サイドチャネルによる識別を防ぎます。

CLI フラグ

負荷制御ノブのサイジング。 --max-sessions は新しい子プロセスの上限です。 負荷を制限するレイヤーは他にも 3 つあります — 高同時実行デプロイのサイジングでは、これらをまとめて調整してください:

• リスナーレベル: --max-connections / server.maxConnections=256 で生 TCP 接続を制限（遅いクライアントのバックプレッシャー）。
• セッション単位の購読者: EventBus はデフォルトでセッション単位の SSE 購読者を 64 に制限。65 番目のクライアントは terminal stream_error を受け取り閉じられます。
• セッション単位のプロンプト受付: --max-pending-prompts-per-session=5 で一つのセッションに受け付けた キューに入った + アクティブなプロンプトを制限。オーバーフローは 503（Retry-After: 5）。
• 購読者単位のバックログ: SSE クライアントあたり 256 フレームのキュー。 容量超過のクライアントは terminal client_evicted フレームを受け取り閉じられます （一つの遅いコンシューマーがデーモンを固定できません）。

これらの上限は相互作用します: --max-sessions × 64 購読者 × 256 フレーム が EventBus レイヤーでの最悪ケースのインフライトメモリで、 --max-sessions × --max-pending-prompts-per-session が受付レイヤーでの 受け付けたプロンプト作業を制限します。デフォルトのサイジングは単一ユーザー／ 小規模チームの負荷を想定しています。マルチテナントデプロイでは段階的に引き上げて （RSS を監視しながら）ください。

MCP クライアントガードレール（issue #4175  PR 14）。 mcpServers に 30 の MCP サーバーを宣言したワークスペースは、上流の上限を設定しない限り 30 のクライアントを起動します。--mcp-client-budget=N でライブ MCP クライアント数を制限します。--mcp-budget-mode={enforce,warn,off} で動作を選択します。デフォルトは予算設定時に warn（スナップショットに警告が表示されますがクライアントは拒否されません — 強制を有効にする前に実際のファンアウトを測定するのに有用）です。enforce モードで拒否されたサーバーはサーバー単位のセルに disabledReason: 'budget' が表示され、budgets[0] セルに status: 'error' + errorKind: 'budget_exhausted' が表示されます。スロット予約はサーバー名でされ、再接続／ディスカバリータイムアウトをまたいで維持されます — 拒否されたサーバーが正常なサーバーのスロットを奪うことはできません。

⚠️ v1 のスコープ: ワークスペース単位ではなくセッション単位。 デーモン内の各 ACP セッションは独自の Config/McpClientManager を持ちます（セッションごとに newSessionConfig で作成）。予算はセッション内のライブ MCP クライアントをセッション単位で制限し、ワークスペース内の全セッションにわたる集計ではありません。GET /workspace/mcp のスナップショットはブートストラップセッションのビューを反映します（セルは正直さのために scope: 'session' を持ちます）。--mcp-client-budget=10 で 5 つの同時 ACP セッションを実行すると、デーモン全体で最大 50 のライブ MCP クライアントが存在する可能性があります — 上限はセッション単位で保持されます。**Wave 5 PR 23（共有 MCP プール）**でワークスペーススコープのマネージャーが導入され、真のワークスペース単位の強制に昇格します。

qwen serve --mcp-client-budget=10 --mcp-budget-mode=warn
# later, after telemetry shows your real-world distribution:
qwen serve --mcp-client-budget=10 --mcp-budget-mode=enforce

これは claude-code の MCP_SERVER_CONNECTION_BATCH_SIZE（起動同時実行数をゲートするもの）と同じではありません。それらは直交しています。PR 23 では実際の共有 MCP プール（budgets[] にセッション単位セルと並んで scope: 'workspace' セルを追加）が追加されます。PR 14 v1 はインプロセスカウンター + 既存のセッション単位マネージャーへのソフト強制です。

プッシュイベント（issue #4175  PR 14b）。 GET /session/:id/events を購読している SDK クライアントは、予算しきい値を超えたときにタイプ付きフレームを受信します — mcp_budget_warning（合成、上方向の 75% クロスで一度発火、37.5% でヒステリシス再アーム、mcp_guardrail_events でアドバタイズ）と mcp_child_refused_batch（enforce モード下のディスカバリーパスごとに一度合体。readResource レイジースポーン拒否からの length-1）。GET /workspace/mcp のスナップショットは再接続後の状態の信頼できる情報源です。イベントは変更エッジです。ポーリングなしのリアルタイムダッシュボーディングに有用です。

デフォルトのデプロイ脅威モデル

• 127.0.0.1 のみ — ループバックバインド、認証不要。
• --hostname 0.0.0.0 はトークンが必要 — ないと起動を拒否。
• LOOPBACK_BINDS には IPv6 が含まれます — ::1 と [::1] は no-token ルールのループバックとしてカウントされます。
• Host ヘッダー許可リスト — ループバックバインドでは、デーモンは DNS リバインディングを防ぐために Host: が localhost:port / 127.0.0.1:port / [::1]:port / host.docker.internal:port（RFC 7230 §5.4 に従い大文字小文字を区別しない）と一致するか確認します。非ループバックバインド（--hostname 0.0.0.0）は Host 許可リストを意図的にバイパスします — オペレーターはサーフェスエリアを選択しているため、ベアラートークンゲートが唯一の認証レイヤーです。リバースプロキシ / SNI / クライアント証明書ピニングはオペレーターの責任です。非ループバックバインドで Host ベースの分離が必要な場合は、フロントプロキシで TLS を終端し Host を確認してください。
• CORS はデフォルトで任意のブラウザ Origin を拒否 — 403 JSON を返します。特定のブラウザオリジンを通過させるには --allow-origin <pattern>（繰り返し可能、T2.4 #4514）を指定してください。各値はリテラル *（任意のオリジン — ベアラートークンが設定されていない場合は起動を拒否。ループバックでは /health と /demo がデフォルトで認証前なので、完全な堅牢化には --require-auth が推奨）、またはカノニカル URL オリジン（<scheme>://<host>[:<port>]、末尾スラッシュ / パス / ユーザー情報なし）。一致するオリジンには適切な CORS レスポンスヘッダー（Access-Control-Allow-Origin: <echoed>、Vary: Origin、標準のメソッド / ヘッダー / max-age、公開された Retry-After）が返されます。一致しないオリジンにはデフォルトウォールと同じエンベロープで 403 が返されます。caps.features.allow_origin は SDK / webui クライアントがクロスオリジンリクエストを発行する前にデーモンがサポートしているかプリフライト確認できるよう条件付きでアドバタイズされます。例: qwen serve --allow-origin http://localhost:3000 --allow-origin http://localhost:5173。ループバックのセルフオリジン（例: /demo ページ）は影響を受けません — --allow-origin に関わらず別の Origin ストリップシムが処理します。--allow-origin が設定されていないブラウザ webui は引き続き Stage 1 と同じオプションにフォールバックします: Origin ヘッダーが送信されないようネイティブシェル（Electron/Tauri）としてパッケージするか、同一オリジンのリバースプロキシでデーモンをフロントに置く。
• スポーンされた qwen --acp 子プロセスはデーモンの環境を継承します — ただし一つの明示的なスクラブがあります: QWEN_SERVER_TOKEN は子プロセス起動前に除去されます（デーモン自身のベアラー。エージェントは不要）。それ以外 — OPENAI_API_KEY / ANTHROPIC_API_KEY / QWEN_* / DASHSCOPE_API_KEY / カスタムの modelProviders[].envKey など — はすべて引き継がれます。エージェントが LLM の認証のためにこれらを必要とするためです。これは意図的な設計であり、サンドボックスではありません。 エージェントはシェルツールアクセスを持つ同じ UID で実行されるため、~/.bashrc / ~/.aws/credentials / ~/.npmrc 内のすべてのものはプロンプトインジェクションで到達可能です。環境変数のパススルーはセキュリティ境界ではありません。ユーザーが信頼のルートです。エージェントを信頼したくない環境変数に認証情報を持つ ID で qwen serve を実行しないでください。
• 購読者単位の有界 SSE キュー — キューがオーバーフローした遅いクライアントは client_evicted ターミナルフレームを受け取り閉じられます。一つの遅いコンシューマーがデーモンを固定できません。
• セッション単位のプロンプト受付上限 — デフォルトはセッションあたり 5 つの受け付け済み未完了プロンプト。バグのあるクライアントは一つのセッションに対して無制限のプロンプト Promise や一時的な SSE 待機をエンキューできません。
• グレースフルシャットダウン — SIGINT/SIGTERM でリスナーを閉じる前にエージェント子プロセスをドレインします（子プロセスあたり 10 秒のデッドライン）。

⚠️ Stage 1 既知のギャップ — 権限はセッション単位ではなくデーモングローバル（BUy4H）。 pendingPermissions はデーモンスコープに存在します。ベアラートークンを保持する任意のクライアントが、見えるセッションの任意の requestId に投票できます（SSE permission_request イベントはペイロードに requestId を含みます）。これは、すべての認証済みクライアントが同じ人間または信頼できるコラボレーターである単一ユーザー／小規模チームの信頼モデルでは許容されます。Stage 1.5 では POST /session/:id/permission/:requestId + セッションスコープの pending マップ + クライアント単位のアイデンティティに移行します（下流レビューの必須事項 #3）。それまでは、信頼できない当事者と共有するベアラーの背後で qwen serve を実行しないでください。

⚠️ Stage 1 既知のギャップ — POST /session/:id/prompt のボディは 10 MB に制限（BUy4L）。 10 MB を超える画像 / PDF / オーディオを含むマルチモーダルプロンプトは、ルートロジックが実行される前にボディパース時に失敗します（ストリーミングなし、アップロード中断なし）。回避策: クライアント側でコンテンツを縮小するか、パス参照を渡してエージェントが readTextFile 経由でファイルを読み取るようにしてください。Stage 1.5 では /prompt で multipart/form-data またはチャンクエンコーディングを受け付け、大きなプロンプトが崖に達しないようにします。

⚠️ Stage 1 既知のギャップ — NAT の背後のファントム SSE 接続。 デーモンはハートビート（15 秒間隔）への TCP バックプレッシャーで 死んだクライアントを検出します。TCP RST なしに消えたクライアント （例: アイドルフローを無音でドロップする NAT ボックス）は、Node の keepalive プローブがタイムアウトするまで — 通常 Linux のデフォルトで 約 2 時間 — カーネルレベルのソケットを「アライブ」状態に保ちます。 このような NAT の背後にある --hostname 0.0.0.0 デプロイでは、ファントム SSE 接続が蓄積し、最終的に server.maxConnections の 256 の上限に達する 可能性があります。

--writer-idle-timeout-ms <n> （issue #4514  T2.9） を設定して、明示的なアプリケーションレベルのアイドルデッドラインでこのギャップを 埋めてください: n ms の間、書き込みが正常にフラッシュされない場合（15 秒の ハートビートも含む）、デーモンは reason: 'writer_idle_timeout' の terminal client_evicted フレームを送信し（data.errorKind にもミラー）ストリームを 閉じます。このフラグはレガシー契約を維持するためデフォルトで無効です — RST を飲み込むネットワークのオペレーターは 15 秒のハートビート間隔を 大幅に上回る値（例: 60000〜300000）を選択し、正当なアイドル接続が evict されず、真に詰まったライターが速やかに回収されるようにしてください。 SDK から caps.features.includes('writer_idle_timeout') でプリフライト確認できます。

デッドラインとライターアイドルタイムアウト

Issue #4514  T2.9 では、15 秒ハートビート + AbortSignal ではカバーできない長時間稼働／リモートデプロイのギャップを埋める 2 つのオプトインフラグが追加されました。どちらもデフォルトで無効です — 単一ユーザーのループバックワークフローはビットレベルで変更なしです。

どちらのフラグもミリ秒の正の整数を受け付けます。0、NaN、非整数、負の値は起動時に明確なエラーメッセージで拒否されます。CLI フラグは環境変数より優先。明示的な ServeOptions フィールド（埋め込み呼び出し元）は env より優先されます。SDK コンシューマーはいずれかの動作に依存する前に対応する機能タグをプリフライト確認してください — この PR 以前のデーモンはどちらのタグも省略しており、リクエストの deadlineMs フィールドは無音でドロップされます。

マルチセッション & マルチワークスペースデプロイ

#3803  §02 に従い、各 qwen serve プロセスは起動時に一つのワークスペースにバインドされます。そのワークスペース内では、エージェントのネイティブセッションマップ経由で N セッションを単一の qwen --acp 子プロセスに多重化します — セッションは子プロセス / OAuth 状態 / ファイル読み取りキャッシュ / 階層メモリパースを共有します。

複数のワークスペースをホストするには（一人のユーザーで複数のリポジトリ、または同一ホスト上の複数のユーザー）、複数のデーモンプロセスを実行してください — ワークスペースごとに一つ、それぞれ独自のポートで、systemd / docker-compose / k8s / qwen-coordinator リファレンスオーケストレーターで管理します。このトレードオフは意図的です: ワークスペースごとに一つの子プロセスを使用することで、loadSettings(cwd) / OAuth / MCP サーバースコープがバインドされたディレクトリと整合し、リクエスト間でドリフトしません。

アタッチ時に modelServiceId を POST する前に購読してください。 クライアントが modelServiceId を指定して POST /session し、ワークスペースに異なるモデルで実行中のセッションが既にある場合、デーモンは内部的に setSessionModel 呼び出しを発行します — 失敗は HTTP エラーとして伝播されません（セッションは現在のモデルで動作し続けます）。可視の失敗シグナルはセッションの SSE ストリームの model_switch_failed イベントです。POST /session を呼び出してからのみ GET /session/:id/events を開くと、失敗イベントを見逃し、間違ったモデルと静かに通信し続けることになります。最初に SSE ストリームを開くか、購読時に Last-Event-ID: 0 を渡してリングの最古のイベントをリプレイしてください。

複数のユーザー（それぞれ独自のクォータ、監査ログ、サンドボックスを持つ）を処理するため、またはプロセスの範囲を超えてスケールするため（コールドスタートバジェット、FD 数、RSS）、外部オーケストレーターの背後でユーザーごとにワークスペースごとに一つのデーモンをスポーンしてください。そのオーケストレーター（マルチテナンシー / OIDC / クォータ / 監査 / k8s）は qwen-code プロジェクトのスコープ外 です — デザインポインターについては issue #3803  の「External Reference Architecture」を参照してください。

永続化されたセッションのロードと再開

デーモンは ACP の session/load と再開フローを HTTP 経由で 2 つのルートで公開しています:

TypeScript SDK は両方を DaemonSessionClient の静的ファクトリーとして公開しています:

import { DaemonClient, DaemonSessionClient } from '@qwen-code/sdk';
 
const client = new DaemonClient({ baseUrl: 'http://127.0.0.1:4170' });
 
// Cold reconnect — daemon will replay history through SSE.
const session = await DaemonSessionClient.load(client, 'persisted-id');
 
// Or, if your UI already has the history, skip the replay:
// const session = await DaemonSessionClient.resume(client, 'persisted-id');
 
for await (const event of session.events()) {
  // First the replayed `session_update` frames (load only),
  // then live events.
}

呼び出す前に caps.features.session_load / caps.features.session_resume をプリフライト確認してください — 古いデーモンは 404 を返します。unstable_session_resume は非推奨の互換エイリアスとして引き続きアドバタイズされます。同一 id への同時同一アクション要求は合体します。クロスアクションのレース（load と resume の競合）は 409 restore_in_progress（Retry-After: 5）を返します。完全なエラーエンベロープについては プロトコルリファレンス を参照してください。

注: 履歴リプレイは SSE リング（デフォルト 8000 フレーム）に制限されます。おしゃべりなターンの長い履歴はそれを超える可能性があります — 最も古いフレームは無音でドロップされます。非常に長いセッションでは resume を優先し、クライアントのローカル永続化 UI に依存してください。

耐久性モデル

Stage 1 ではセッションはデーモンの再起動をまたいでも依然としてエフェメラルですが、ディスク上の永続化されたセッションはリロードできます:

• 子プロセスのクラッシュは session_died を発行し、デーモンのマップからライブセッションを削除します。新しいエージェント子プロセスがスポーンできれば、ディスク上の永続化されたセッションを POST /session/:id/load 経由でリロードできます。
• デーモンの再起動はすべてのインフライトのライブセッションを失います。永続化されたセッションはディスク上に残り、同じワークスペースバインディングルールのもとで新しいデーモンプロセスに対してロードできます。
• 長いクライアント切断（おしゃべりなターンで 5 分以上）は SSE リプレイリング（デフォルト 8000 フレーム）を追い越す可能性があります — Last-Event-ID での再接続は成功しますが、状態が不整合になる可能性があります。モバイル / フラッキーネットワーククライアントでは、長い切断時に SSE を再開するか POST /session/:id/load を呼び出してディスクからリプレイする計画を立ててください。
• ファイル操作（writeTextFile）はクラッシュをまたいでアトミックです（書き込み後リネーム）。デーモン再起動をまたいでアトミックではない — ファイル書き込みが完了したかどうかだけです。

統合が session/load がカバーする以上のサーバーサイドのクロス再起動耐久性（例: サーバー管理のリトライキュー）を必要とする場合、アプリケーションレベルの状態回復が依然として必要です。デーモンのセッション内に長時間稼働の再起動センシティブな状態を保持しないでください。

Stage 1.5+ の実行時保証

Stage 1 の契約はプロトタイピング用のサイズです。#3889 chiga0 下流コンシューマーレビュー  に従い、以下は Stage 1 に含まれません — 本番グレードの統合がこれらに依存するには Stage 1.5+ が必要です:

深刻な下流利用のブロッカー:

1. HTTP 経由の loadSession / unstable_resumeSession — これがないと、どの統合も子プロセスのクラッシュやデーモンの再起動を生き残れず、デーモンを調整するオーケストレーターも状態を回復できません。
2. 永続的なクライアントアイデンティティ（ペアトークン + クライアント単位の失効） — Stage 1 は共有ベアラーを 1 つ使用します。トークンが漏洩すると全員が失効し、originatorClientId はデーモンがスタンプした認証済みアイデンティティではなく、クライアントの自己申告です。

信頼性のベースライン:

3. クライアント開始のハートビートパス — #4175  PR 9 で配信済み。POST /session/:id/heartbeat はデーモンに最終確認タイムスタンプを記録します（機能タグ client_heartbeat）。SDK ヘルパーは DaemonClient.heartbeat() / DaemonSessionClient.heartbeat()。
4. 投票が最初の応答者レースに負けたときの permission_already_resolved イベント — 現在 UI は 404 から状態を推測する必要があります。
5. より大きなリプレイリング — 8000 に増加。セッション単位で設定可能なリング は未対応 — モバイル / おしゃべりなターンのワークロードにはセッション単位のオーバーライドが必要な場合があります。
6. client_evicted 前の slow_client_warning イベント — 行儀の良い遅いクライアントが終了前に自己スロットルできるソフトバックプレッシャー（レンダー深度を削減、チャンクをドロップ）。

統合の人間工学:

7. IM スタイルのコンテキスト用 POST /session/:id/_meta — 後続プロンプトに添付されるセッション単位のキーバリュー（チャット id、送信者、スレッド id）が、チャネルごとの即興を置き換えます。
8. /capabilities の実際の機能ネゴシエーション — protocol_versions: { acp: '0.14.x', daemon_envelope: 1 } でクライアントが「不明なフレーム、無視」にフォールスルーする代わりにドリフトを検出できます。
9. ファーストクラスの耐久性ドキュメント（このセクション）— 上で既に配信済み。

完全なコンバージェンスロードマップは #3803  で追跡されています。

Stage 1 のスコープ境界 — Stage 1.5 で修正しないこと

2 つの構造的な選択は Stage 1 / 1.5 / 2 のメインラインロードマップの明示的な非目標です。ユースケースがどちらかに依存する場合は、待機するのではなく回避策を計画してください。

セッション状態はローカルミューテーションのみ（LaZzyMan review #4270256721  に従い）

Stage 1.5 の計画は TUI をインプロセスの EventBus 購読者として説明しています。実際には TUI UI はワイヤープロトコルより厳密に大きい です:

• ローカルのみの UI — 約 15 の Ink ダイアログコンポーネント（ModelDialog、MemoryDialog、PermissionsDialog、SessionPicker、WelcomeBackDialog、FolderTrustDialog など）と local-jsx スラッシュコマンド（/ide、/auth、/init、/resume、/rename、/delete、/language、/arena など）はターミナル固有の Ink JSX をレンダリングします。HTTP/SSE 上のリモートクライアントは同等に Ink をレンダリングできず、これらのフローはワイヤーイベントを送信しません。
• ワイヤーイベントなしのセッション状態ミューテーション — /approval-mode、/memory add、/mcp add-server、/agents、/tools enable/disable、/auth、/init（CLAUDE.md の書き込み）はすべてエージェントの動作を変更しますが、現在 /model のみがイベント（model_switched）を発行します。

Stage 1 の選択 — レビューのオプション (A): これらのミューテーションをワイヤーイベントに昇格させない。2 つのデプロイモードで結果が異なります。

モード 1 — ヘッドレス qwen serve（この PR）

デーモン内に TUI シェルは実行されません。上記のスラッシュコマンドはこのモードには存在しません — 発行するターミナル UI がないためです。セッション状態は:

• approval-mode / memory / agents / tools 許可リスト / auth については起動時に固定 — デーモンの qwen --acp 子プロセスが起動するときに設定 + ディスクからすべて読み込まれ、セッションのライフタイム中は不変です。設定定義の MCP サーバーも同様に起動時に固定されますが、実行時に追加されたサーバー（POST /workspace/mcp/servers 経由）は再起動なしで追加または削除できます。
• POST /session/:id/model（model_switched を発行）、POST /workspace/mcp/servers / DELETE /workspace/mcp/servers/:name（mcp_server_added / mcp_server_removed を発行）、および権限投票（POST /permission/:requestId）経由で HTTP 経由でミューテーション可能。

結果: ヘッドレスモードのリモートクライアントは完全なセッション状態を見ます。追加状態を隠す TUI はなく、ドリフトは不可能です。approval-mode を変更したい場合は、新しい設定でデーモンを再起動してください。MCP サーバーはミューテーションルート（POST /workspace/mcp/servers、DELETE /workspace/mcp/servers/:name）経由で実行時に追加/削除できます — ランタイム MCP サーバー管理 を参照してください。

モード 2 — Stage 1.5 の qwen --serve 共同ホスト TUI（この PR には含まれない）

Stage 1.5 で qwen --serve（TUI プロセスが同一 HTTP サーバーを共同ホスト）が追加されると、リモートクライアントと並んで TUI が存在します。ローカルオペレーターが /approval-mode yolo や /mcp add-server を入力するとセッション状態が変更され、HTTP 上のリモートクライアントはその変更を観察するイベントを持ちません。

このモードでは、TUI は**「スーパークライアント」** — リモートクライアントが見るのと同じエージェント会話を観察し、かつリモートクライアントができないセッション状態をミューテーションできます。非対称性は:

• ✅ TUI とリモートクライアントは同じエージェントメッセージ、ツール呼び出し、ファイル差分、権限プロンプトを見ます。
• ❌ TUI のみが承認モード / メモリ / MCP サーバーリスト / エージェント / ツール許可リスト / 認証状態を見る / ミューテーションできます。

モード 2 での結果: リモートクライアント UI がセッション設定をミラーしようとすると、TUI スラッシュコマンドの後にドリフトする可能性があります。リモートクライアントはアタッチ / 再接続時に状態を再フェッチするべきです（Last-Event-ID: 0 を使用してリングの最古のイベントをリプレイし、model_switched などを取得してください）。TUI サイドのミューテーションには増分イベントに依存するべきではありません。

なぜ (A) で (B)（ミューテーションを session_state_changed イベントファミリーに昇格）ではないのか

(B) はより野心的な答えですが、Stage 1.5 を計画されているインプロセスリファクタを通じてクリーンに通過しなければならない実質的に大きなワイヤーサーフェスに縛り付けます。より小さなスコープを正直に進む方が良いと考えています。セッション状態イベントの分類作業 — どの TUI フローが設計上ローカルのみで、どれが将来のオプトイン (B) フレーバー拡張でワイヤーに昇格できる可能性があるかの列挙 — は Stage 1.5 のコードではなく #3803  に移ります。

N 並列セッションは一つの qwen --acp 子プロセスを共有する

同一ワークスペースの複数のセッションは、エージェントのネイティブマルチセッションサポート（packages/cli/src/acp-integration/acpAgent.ts:194: private sessions: Map<string, Session>）経由で一つの qwen --acp 子プロセスを共有します。ブリッジは各セッションで connection.newSession({cwd, mcpServers}) を呼び出します — エージェントはそれらをセッションマップに保存し、呼び出しごとの sessionId で逆多重化します。

N=5 セッションが同一ワークスペースにある場合の具体的なコスト:

ブリッジはデーモンあたり一つのチャネルを保持します（§02 に従いデーモンあたり一つのワークスペース）。チャネルは少なくとも一つのセッションがアクティブな間は維持されます。最後の killSession（またはチャネルレベルのクラッシュ）が子プロセスを終了させます。

MCP サーバー子プロセス は現在もセッション単位です — 各セッションの設定は異なるサーバーを指定できるため、独立してスポーンされます。Stage 1.5 のフォローアップ: (workspace, config-hash) で MCP サーバー子プロセスをリファレンスカウントし、同一の設定が共有されるようにします。この PR のスコープ外です。

ピアエージェント（Cursor / Continue / Claude Code / OpenCode / Gemini CLI）はすべて単一プロセスマルチセッションを採用しています。 qwen-code はエージェントレイヤーでそれらと一致します。この PR の Stage 1 ブリッジは同じアーキテクチャを HTTP 上で可視化します。

リモートデーモンへのログイン（issue #4175 PR 21）

デーモンがリモートポッド（共有ディスプレイなし）で実行されているとき、クライアントは HTTP 経由で OAuth デバイスフローをトリガーできます。デーモン自身が IdP をポーリングします。 ブラウザのあるデバイスで URL を開くだけです。

# 1. Start a flow. The daemon contacts the IdP, returns a code + URL.
curl -X POST http://127.0.0.1:4170/workspace/auth/device-flow \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"qwen-oauth"}'
# → 201 {
#     "deviceFlowId": "fa07c61b-…",
#     "userCode": "USER-1",
#     "verificationUri": "https://chat.qwen.ai/api/v1/oauth2/device",
#     "verificationUriComplete": "https://chat.qwen.ai/...?user_code=USER-1",
#     "expiresAt": 1700000600000,
#     "intervalMs": 5000,
#     "attached": false
#   }
 
# 2. Visit the URL on your phone / laptop, enter the user code.
# 3. Poll for completion (or subscribe to SSE for the auth_device_flow_authorized event):
curl http://127.0.0.1:4170/workspace/auth/device-flow/fa07c61b-… \
  -H "Authorization: Bearer $TOKEN"
# → status transitions: pending → authorized

TypeScript SDK は両ステップを単一のヘルパーにラップしています:

import { DaemonClient } from '@qwen-code/sdk';
 
const client = new DaemonClient({ baseUrl, token });
const flow = await client.auth.start({ providerId: 'qwen-oauth' });
console.log(`Open ${flow.verificationUri}\nCode: ${flow.userCode}`);
const result = await flow.awaitCompletion({ signal: abortCtrl.signal });
// result.status === 'authorized'

デーモンはあなたの代わりにブラウザを開きません。 ローカルで実行されていても、デーモンはパッシブのままです — URL を返し、SDK / ユーザーがどこで開くかを選択します。これは意図的です: ヘッドレスポッドのデーモンが xdg-open を呼び出すと、実際の認証サーフェスをマスクしながら静かに失敗します。クライアントで gh auth login の「Press Enter to open browser」UX をミラーしてください。

--require-auth と開発の利便性。 デバイスフローのルートはストリクトミューテーションゲート（PR 15）を使用します。つまり、トークンなしのループバックデフォルトは 401 token_required を返します。開発中のローカルでの最も簡単な回避策は qwen serve --token=dev-token です。ループバックデフォルトを堅牢化する場合でなければ --require-auth は必要ありません。

クロスデーモン制限。 oauth_creds.json はデーモン共有（~/.qwen/oauth_creds.json）なので、デーモン A でのログイン成功はデーモン B の次のトークンリフレッシュで自動的に取得されます — ただしデーモン B の SDK クライアントは auth_device_flow_authorized イベントを受信しません（イベントはデーモン単位）。

クロスクライアントのテイクオーバー。 同じデーモン上の 2 つの SDK クライアントが同じプロバイダーに対して POST /workspace/auth/device-flow を送信すると、プロバイダー単位のシングルトンを取得します: 最初の呼び出しは新しい IdP リクエストを開始し attached: false を返します。2 番目の呼び出しは attached: true で既存のインフライトエントリを返します。テイクオーバーは監査証跡に記録されます（2 番目のクライアントの X-Qwen-Client-Id の下）が、個別のイベントは発行しません — ユーザーが IdP ページを完了すると両方のクライアントが同じ auth_device_flow_authorized を受信します。UI で「自分が開始した」と「他の誰かのフローに参加した」を区別する場合は、start() が返す attached フィールドで分岐してください。

デーモンログファイル

qwen serve はプロセス単位の診断ログを以下に書き込みます:

${QWEN_RUNTIME_DIR or ~/.qwen}/debug/daemon/serve-<pid>-<workspaceHash>.log

同じディレクトリの latest シンリンクは常に現在のプロセスのログを指しているため、tail -f ~/.qwen/debug/daemon/latest で実行中のデーモンをフォローできます。

ログはライフサイクルメッセージ、ルートエラー（route= と sessionId= コンテキスト付き）、ACP 子プロセスの stderr、および QWEN_SERVE_DEBUG=1 が設定されている場合はブリッジの追加パンくずを記録します。現在 stderr に書き込まれている行は引き続き stderr に書き込まれます。ファイルログは追加的なもので、置き換えではありません。

無効化

ファイルロギングを完全にスキップするには QWEN_DAEMON_LOG_FILE=0（または false/off/no）を設定してください。stderr 出力には影響しません。

セッションデバッグログとの関係

セッションスコープのデバッグログ（~/.qwen/debug/<sessionId>.txt と ~/.qwen/debug/latest シンリンク）は独立しています。デーモンログは兄弟の daemon/ サブディレクトリに存在します。セッション単位のデバッグセマンティクスはこの機能によって変更されません。

ローテーションなし

デーモンログは無期限に追記されます。大きくなった場合は手動でローテーションしてください。将来の拡張で自動ローテーションが追加される可能性があります。#4548  のフォローアップで追跡してください。

ランタイム MCP サーバー管理（issue #4514 ）

デーモンを再起動せずに実行時に MCP サーバーを追加または削除します。ランタイムエントリは、同じ名前の設定定義サーバーをシャドウするエフェメラルオーバーレイに存在します。基礎となる settings.json / mcpServers 設定は書き込まれません。

プリフライト: いずれかのルートを呼び出す前に caps.features で mcp_server_runtime_mutation を確認してください。このタグのない古いデーモンは 404 を返します。

POST /workspace/mcp/servers — ランタイム MCP サーバーの追加

Strict-gated（ベアラートークン必須）。ライブの McpClientManager 経由でサーバーに即座に接続し、ツールを発見します。

リクエスト:

{
  "name": "my-server",
  "config": {
    "command": "npx",
    "args": ["-y", "@my-org/mcp-server"]
  }
}

name は英数字と _、- のみ使用可能（最大 256 文字）。config は settings.json の mcpServers エントリと同じ MCP サーバー設定オブジェクトです（トランスポート依存フィールド: stdio の場合 command/args、SSE/HTTP の場合 url）。セキュリティセンシティブなフィールド（trust、env、cwd、oauth、headers、authProviderType、includeTools、excludeTools、type）はデーモンによって除去され無視されます。

レスポンス（200）— 成功:

{
  "name": "my-server",
  "transport": "stdio",
  "replaced": false,
  "shadowedSettings": false,
  "toolCount": 3,
  "originatorClientId": "client-1"
}

• replaced: true — 同名のランタイムエントリが既に存在し、設定フィンガープリントが異なります。古い接続が切断され、新しい接続が確立されました。フィンガープリントが一致する場合（冪等な再追加）、replaced は false。
• shadowedSettings: true — 同名の設定定義サーバーが存在します。ランタイムエントリがそれをシャドウするようになりました。設定エントリは変更されておらず、後でランタイムエントリが削除されると再浮上します。
• toolCount — 新しく接続されたサーバーで発見されたツールの数。

レスポンス（200）— ソフト拒否（予算警告モード）:

{
  "name": "my-server",
  "skipped": true,
  "reason": "budget_warning_only"
}

--mcp-budget-mode=warn でサーバーの追加が設定済みの --mcp-client-budget を超える場合に返されます。サーバーは接続されません。呼び出し元はユーザーに予算プレッシャーを示すべきです。

エラー:

DELETE /workspace/mcp/servers/:name — ランタイム MCP サーバーの削除

Strict-gated。サーバーを切断し、ランタイムオーバーレイから削除します。冪等 — 追加されていない名前の削除はスキップレスポンスを返します（エラーではありません）。

:name パスパラメーターは URL エンコードされたサーバー名です。

レスポンス（200）— 成功:

{
  "name": "my-server",
  "removed": true,
  "wasShadowingSettings": false,
  "originatorClientId": "client-1"
}

• wasShadowingSettings: true — 削除されたランタイムエントリは同名の設定定義サーバーをシャドウしていました。その設定エントリのシャドウが外れ、次のディスカバリー/再起動で使用されます。

レスポンス（200）— 冪等スキップ:

{
  "name": "ghost",
  "skipped": true,
  "reason": "not_present"
}

名前がランタイムオーバーレイに存在しない場合に返されます（設定に存在する可能性があります — このルートで設定エントリを削除することはできません）。

エラー:

シャドウセマンティクス

ランタイムエントリは設定定義の MCP サーバーの上にエフェメラルオーバーレイを形成します:

• 追加: 設定エントリと同名のランタイムサーバーを追加するとシャドウされます — ランタイム設定が優先されます。元の設定エントリは変更されません。
• 削除: 設定エントリをシャドウしていたランタイムサーバーを削除するとシャドウが外れます — 次の接続で設定定義の設定がアクティブになります。
• デーモン再起動: すべてのランタイムエントリが失われます。再起動をまたいで生き残るのは設定定義のサーバーのみです。ランタイムサーバーはセッションのライフタイムスコープです。
• GET /workspace/mcp: マージされたビューをレポートします — 設定定義とランタイムの両方のサーバーが servers[] 配列に表示されます。現在スナップショットでは 2 つのオリジン間のワイヤーレベルの区別はありません。

イベント

両ルートはワークスペーススコープの SSE イベントを送信します（アクティブなすべてのセッションバスが受信）:

スキップレスポンス（budget_warning_only、not_present）はイベントを発行しません。

既存の mcp_guardrail_events サーフェスからの予算関連イベント（mcp_budget_warning、mcp_child_refused_batch）は、ランタイムの追加が予算しきい値を超えた場合にも発火します。

次のステップ

• 長時間稼働デーモンのセットアップ? ローカル起動テンプレート（systemd / launchd / nohup / tmux）（v0.16-alpha ローカル専用）。
• クライアントを構築する? DaemonClient TypeScript クイックスタート と HTTP プロトコルリファレンス を参照してください。
• ソースを読む? ブリッジコードは packages/cli/src/serve/ に。SDK クライアントは packages/sdk-typescript/src/daemon/ に。
• ロードマップを追跡する? Stage 1.5 / Stage 2 の進捗は issue #3803  で追跡されています。