CLI の使い方
起動すると対話式 CLI に入り、自然言語でタスクを入力できます。プロンプトは [モード][agent名] > の形式で現在の状態を表示します（例：[plan][code] > ）。
組み込みコマンド
| コマンド | 説明 |
|---|---|
/plan | 計画モードに切り替え（読み取り専用の調査 + 計画提案） |
/interactive | 対話式承認モードに切り替え（既定） |
/auto | 全自動モードに切り替え（承認不要、高リスク） |
/discuss | ディスカッションモードに切り替え（読み取り専用の対話） |
/mode | 現在のモードを表示 |
/connect | LLM に接続（provider 選択 → key → モデル一覧更新 → 推論強度） |
/connect rm | 接続設定をクリア（環境変数に戻す） |
/providers | 設定済み LLM プロバイダーを一覧表示（▶ が現在有効） |
/use <番号|id> | 現在有効なプロバイダーを切り替え |
/rm <番号|id> | 指定プロバイダーを削除 |
/link | アカウント接続ウィザードを開始（Hub アドレス + メール/電話番号 + パスワードまたは SMS 認証コード） |
/link <接続コード> [Hubアドレス] | 1 回限りの接続コードで本機ノードをユーザーセンターに接続 |
/sessions | 保存済みセッションを一覧し復元（切り替え後に最近のメッセージを表示） |
/history | 現在のセッションのユーザー指示を一覧表示 |
/model <id> | LLM モデルを切り替え |
/agent <name> | agent を切り替え（Prompt + 任意のモデルを同期） |
/agents | すべての agent を一覧表示（現在を強調） |
/agent add <name> <prompt...> | カスタム agent を追加 |
/agent edit <name> <prompt...> | agent の Prompt を変更（現在の agent は即時ホットリロード） |
/agent rm <name> | agent を削除 |
/agent show [name] | agent の詳細を表示 |
/mcp | MCP サーバーと接続状態を一覧表示 |
/mcp add <name> stdio <cmd...>|http <url> | MCP サーバーを追加して接続（ツールを自動注入） |
/mcp rm|enable|disable|refresh [name] | 削除 / 有効化 / 無効化 / ツール一覧の更新 |
/tools | すべてのツールを一覧表示（出所、リスク、無効状態） |
/tool add <name> <cmd...> | コマンドツールを追加（shell コマンドを実行） |
/tool rm|disable|enable <name> | ツールを削除 / 無効化 / 有効化 |
/clear | 現在のセッションを消去 |
quit / exit | 終了 |
reset | セッションをリセット |
| 実行中に入力 + Enter | 現在のタスクに補足情報を送る（次のイテレーションで反映） |
| 実行中に ESC を 2 回 | 現在のタスクを中断 |
よくあるタスク例
自然言語でそのまま入力します。例：
> カレントディレクトリに TypeScript プロジェクトを初期化して
> src/ のコードを読んで、潜在的な問題を指摘して
> logs/ のすべての .json ファイルを .json.bak にリネームして
> テストを実行して失敗したケースを修正してファイル変更やコマンド実行が必要なとき、対話モードでは承認カードが表示され、確認を待ちます。
実行モード
| モード | 動作 |
|---|---|
discuss | 読み取り専用。書き込みと実行をすべて禁止 |
plan | 読み取り専用。書き込みと実行をすべて禁止。計画提案向け |
interactive | 副作用のある操作はユーザーが都度承認（既定） |
auto | 副作用のある操作をすべて許可（高リスク、自己責任） |
承認カード
対話モードでは、承認カードで次を選べます：
Y今回だけ許可Aこのツールを常に許可D拒否run_shellは追加でCこのコマンドを常に許可（コマンド単位の許可リスト。ツール全体を許可するより安全）
実行中の補足情報（steering）
タスク実行中でも、完了を待たずに指示を追加できます。文字を入力して Enter を押すと、次の イテレーションの合間に user メッセージとして現在のタスクに注入され、agent は続行時にその補足情報を取り込みます。
別のタスクを始める場合は、現在のタスクの終了を待つか ESC を 2 回押して中断してください。 （承認/質問の保留中は、入力は優先的に承認の回答または質問への回答として扱われます。）
セッション管理
/sessionsは保存済みセッションを一覧し、選んで復元します。切り替え後に最近のメッセージを表示するので、中断した作業を再開しやすくなります。/clearは現在のセッションを消去します。resetはセッション状態をリセットします。/historyは現在のセッションのユーザー指示を一覧し、文脈を素早く振り返れます。
複数プロバイダーの管理
複数の LLM 接続（異なるベンダーや Key）を保存し、いつでも切り替えられます：
/providers # すべてのプロバイダーを一覧（▶ が現在有効）
/use 2 # 番号で切り替え（/use <id> も可）
/rm 3 # プロバイダーを削除新しいプロバイダーは /connect で追加します。切り替えは即時反映され、再起動は不要です。
コマンドラインサブコマンド
zqagent で対話セッションに入る以外に、4 つのサブコマンドがあります：
zqagent serve [--port <n>] [--host <addr>] [--data-dir <dir>] # ヘッドレス常駐サービス
zqagent link --hub <url> --username <メール/電話番号> --password '<パスワード>' # アカウント接続（再起動不要）
zqagent link --hub <url> --code <接続コード> # 1 回限りの接続コードで接続（再起動不要）
zqagent rename <名前> # Hub に表示されるノード名を変更
zqagent update [--status|--check|--now|--rollback] # ノードの自動更新の確認/実行、ロールバックzqagent は --resume <セッションID> で前回のセッションを復元し、--debug で起動診断ログを出力できます。
serve は起動時に直接接続することもできます：--hub <url> --enroll-code <コード> --label <名前>、 またはアカウント方式 --hub <url> --username <メール/電話番号> --password <パスワード>。
Windows 単体ファイルでは zqagent を zqagent.exe に置き換えます（PATH にない場合は .\zqagent.exe）：
zqagent.exe serve --port 8787 --data-dir "%APPDATA%\zqagent"
zqagent.exe link --hub https://hub.cd-zq.com --username you@example.com --password <パスワード>
zqagent.exe link --hub https://hub.cd-zq.com --code <接続コード>zqagent link を認証情報なしで実行すると対話ウィザードに入ります。パスワードは ZQAGENT_HUB_PASSWORD でも指定できます。
Windows の link もデスクトップ版がインストールしたノードサービスを自動検出するため、通常 --data-dir は不要です。 手動でタスクスケジューラを設定し、データディレクトリが既定位置にない場合のみ明示的に指定します。
詳しくはノードの起動をご覧ください。
起動診断（--debug）
「起動直後に終了し、コンソールに何も出ない」といった問題では、--debug で診断を有効にします：
zqagent --debug # 単体実行ファイル（macOS / Linux）
node bin/zqagent --debug # npm インストールのエントリーzqagent.exe --debug :: Windows 単体ファイル
set ZQAGENT_DEBUG=1 :: Windows cmd、同等の書き方export ZQAGENT_DEBUG=1 # bash/zsh診断ログは同期的にディスクへ書き込み（stdout のバッファを経由しないため、プロセスがクラッシュしても即終了しても失われません）、同時に stderr にも出力します。 ログのパスは次の順で解決されます：
| 環境変数 | 意味 |
|---|---|
ZQAGENT_DEBUG_LOG | ログファイルの完全なパス（優先） |
ZQAGENT_DEBUG_DIR | ログディレクトリ。ファイル名は固定で zqagent-debug.log |
| いずれも未設定 | システムの一時ディレクトリ（os.tmpdir()）下の zqagent-debug.log |
ログには環境スナップショット、起動各段階、クラッシュスタックが含まれます（OPENAI_API_KEY などの認証情報は「設定有無 + 長さ」のみ記録し、 平文は出力しません）。ログが止まった行が失敗位置です。 --debug を外せば完全に無効化され、ファイルも書かず ハンドラーも登録しません。
対照プローブ：どの層の問題か判断する
単体ファイルの成果物 = 公式 node ベース + 注入された SEA blob + その中の業務コード。起動直後に終了する場合、 最小サンプルで 3 層を切り分ける方が、業務コードを推測するより速いです：
| サンプル | 生成方法 | 動かない場合の意味 |
|---|---|---|
_node-base-<ver>-<platform>-<arch> | 公式 node、無改修 | システム/セキュリティソフト/ローダー層で止まっており、パッケージングとは無関係 |
_sea-minimal-probe-<platform>-<arch> | 最小 SEA プローブ、useCodeCache: false | SEA 注入またはロードの失敗（終了コードを見る。例 0xC0000005） |
_sea-cc-probe-<platform>-<arch> | 同上だが useCodeCache: true | クロスビルドがビルド機の V8 code cache を持ち込んでいる |
zqagent-windows-x64.exe | 実際の成果物 | 前 3 つが正常なら業務コードの初期化問題。--debug で続行 |
pnpm run probes:sea # win32-x64（既定）
pnpm run probes:sea -- --arch arm64 # win32-arm64
pnpm run probes:sea -- --platform linux --arch x64 # Linux 上で linux プローブを生成（本機で実行可能）
pnpm run probes:sea -- --platform darwin --arch arm64 # macOS 上で macos プローブを生成（本機で実行可能）プローブは stdout への出力に加え、一時ディレクトリに zqagent-probe.log を書き出します。「コンソールに出力が見えない」場合でも、 ディスク上のログで JS が実際に実行されたかを証明できます。
注入後の成果物の sha256 はビルドごとに変わります（blob にビルド機上の main スクリプトの絶対パスが記録されるため）。 そのためベース
_node-base-*のハッシュだけを「ファイルが完全/一致しているか」の根拠にしてください。
macOS で生成/使用する際の注意：SEA には Node ≥ 20 が必要です。
darwinの成果物は注入前にcodesign --remove-signature、注入後にcodesign --sign - --forceで一時署名が必要です（本機で macos プローブを生成するスクリプトが自動処理します）。arm64 カーネルは未署名バイナリの実行を拒否します。Windows 向け成果物の生成は 純粋なクロスアセンブリ（postject はファイルを書くだけで実行しない）なので、macOS/Linux 上でも.exeを直接生成できます。
Windows では一式を同じディレクトリに置いて release/cli/diagnose.cmd を実行します。node -e、2 つのプローブ、 zqagent --debug を順に実行し、各サンプルの終了コード、診断ログ、プローブの書き出しログを表示します。 画面のテキストを丸ごとコピーして送れば特定できます。