技術的な質問（上級）

このページはコマンドラインを使う方、自前のモデルを接続する方、連携を組む方向けです。 ファイル処理を任せたいだけならよくある質問で十分です。

インストールと接続

モデルはどう設定しますか？ CLI を起動して /connect を入力し、案内に従って provider（DeepSeek / OpenAI / カスタム）を選び、 API Key を入力、モデルを選択、推論強度を設定します。設定ファイルを手書きする必要はありません。

API Key はどこに保存されますか？平文で漏れませんか？ ローカルの ~/.config/zqagent/ に暗号化して保存され、平文でディスクに書かれることはありません。

どのモデルに対応していますか？ OpenAI 互換のエンドポイントなら何でも使えます。DeepSeek、OpenAI、Ollama、自前のサービスなどです。 /connect の「カスタム」を選ぶか、OPENAI_BASE_URL を設定してください。

Required parameter(s) missing or invalid / Responses API 呼び出し失敗 というエラーが出ます。 多くの場合、選んだモデルがチャットに使えないのが原因です。ゲートウェイのモデル一覧（/models）は 「全カタログ」であることが多く、埋め込み（*-embedding）、リランク（*-rerank）、音声（*-asr / *-tts）、 リアルタイム（*-realtime）、画像（qwen-image* / wan*）、専用チャネル（cmaas-*）などのモデルも 含まれていますが、これらは通常のチャットリクエストを受け付けません。/connect はこうしたモデルを 一覧の末尾に回して ⚠️ を付け、選択後には自動セルフチェック（最小のリクエストを実際に送信）も行います。 通らなければ選び直しを促します。一覧の前方にあるチャット用モデル（qwen3.8-flash、qwen-plus、 deepseek-flash など）に切り替えてください。

セルフチェックが失敗したときの原因は 2 種類です：

表示	意味	対処
The product is not activated	この API Key / アカウントでそのモデルが有効化されていない（または未払い・枠を使い切り）	ゲートウェイのコンソールで有効化するか、有効なモデルに変更
InvalidParameter: Required parameter(s) missing or invalid	モデル名がチャット API に受け付けられない、またはそのサービスが未対応のパラメーターを送っている	チャット用モデルに変更。それでもだめなら推論強度を「既定」に

特定のモデルが使えるか手動で確認する：

curl -s <BaseURL>/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" -H "content-type: application/json" \
  -d '{"model":"<モデル名>","messages":[{"role":"user","content":"hi"}]}'

インストール時に command not found が出る、またはダウンロードが遅い。 パッケージは公開 npm にあり、通常はそのままインストールできます：

npm i -g @zqagent/core

ダウンロードが遅いのは多くの場合ネットワークの問題です。国内ミラーに一時的に切り替えられます （ミラーはリリース後に自動同期されます）：

npm i -g @zqagent/core --registry=https://registry.npmmirror.com/

その他のインストール問題はインストールを参照してください。

安定版とベータ版はどう選びますか？ 現在、公開 npm には安定版（@latest）だけが公開されており、ベータ用のタグはありません。 最新版をインストールしてください。インストールを参照。

日常の使用

実行モードはどう切り替えますか？/discuss（読み取り専用の対話）、/plan（読み取り専用の調査 + 計画）、/interactive（都度承認、既定）、 /auto（全自動、高リスク）。詳しくは CLI の使い方。

危険な操作はそのまま実行されますか？ 既定の対話モードでは実行されません。ファイル書き込みやコマンド実行など副作用のある操作は、 まず承認カードが表示され、許可するか拒否するかを選べます。

長時間動くタスクの途中で要件を変えられますか？ できます。実行中にそのまま文字を入力して Enter を押すと、次のイテレーションで補足情報として注入されます。 別のタスクを始めたい場合は先に中断してください。

タスクが止まってしまったときは？ ESC を 2 回押してください。

長い会話でモデルのコンテキストウィンドウを超えませんか？ 超えません。しきい値に達すると古い会話が自動的に圧縮され、重要な情報が保たれます。手動の操作は不要です。

セッションの保存と復元は？/sessions で保存済みセッションを一覧表示して復元できます。/clear で現在のセッションを消去します。

ノードとコンソール

zqagent を常時動かしてリモート管理もしたい。zqagent serve でノードとして常駐させるか、デスクトップアプリをインストールします。 ユーザーセンターに接続すればリモートで確認できます。 手順はノードの起動を参照。

ブラウザーでノードを管理できますか？スマートフォンは？ できます。ノード接続後、ブラウザーでユーザーセンターを開けばノードコンソールに入れます。 スマートフォンのブラウザーにも対応しています（レスポンシブ + PWA、「ホーム画面に追加」可）。

使用量とコストはどこで見ますか？ノードコンソールの使用量パネル（プロジェクトホームの token カード、またはノード詳細の 「監視 → 使用量を表示」）で、期間・モデル別の統計と CSV 書き出しができます。アカウントページでは ノード横断の集計も確認できます。

送信前の内容は消えますか？ 消えません。コンソールの入力欄の下書きは自動保存され、セッション切り替えや再読み込み後に復元されます。

セッション中に切断されたりバックグラウンドに回ったりすると内容は消えますか？ 消えません。リアルタイムのイベントストリームは切断後に自動再接続し、差分を補完します。 復元後も内容の欠落や重複はありません。

デスクトップアプリ

ウィンドウを閉じてもタスクは動き続けますか？ 動き続けます。ウィンドウを閉じてもトレイに隠れるだけで、トレイから「終了」しても バックグラウンドのノードサービスは launchd / systemd によって維持されます。

データはどこにありますか？ ノードのデータはシステムサービスのデータディレクトリ（macOS ~/Library/Application Support/zqagent/、 Linux ~/.zqagent_data/、Windows %APPDATA%\zqagent\）にあり、install.sh で入れたノードと共有されます。 デスクトップの設定は別途 ~/.config/zqagent-desktop/desktop.json に保存されます。 詳しくはデスクトップアプリ → インストールの詳細。

リモート操作

グローバル IP を持つサーバーが必要ですか？ 不要です。スマートフォンも QQ もアウトバウンド接続で、サードパーティの中継を経由します。 詳しくはリモート操作の概要。

スマートフォン / QQ から使うには？リモート接続 と QQ ボットを参照してください。

既存ツールの拡張

AI にもっとツールを持たせるには？ MCP で外部のツールサーバーに接続するか、/tool add でコマンド実行ツールを追加します。 詳しくは MCP とツール。