リモート操作の概要
zqagent を自分の PC やサーバーで動かし、スマートフォンや QQ からリモートでタスクを依頼します。 AI はサーバー側で実行され、進捗、承認リクエスト、結果がリアルタイムに手元へ返ります。PC の前に張り付きたくないときや、 いつでも AI に作業を任せたいときに適しています。
公式クラウドを使う（推奨）
自分で broker を立てたくない場合は、すでにデプロイ済みのクラウドをそのまま使えます：
ZQAgent ユーザーセンター を開いて登録し、ログインします。
ノード管理を作成し、1 回限りの接続コードを生成します（15 分有効）。
対象デバイスでコマンドを 1 つ実行して接続します（手段はどれか 1 つ。認証情報は自動保存され、手作業の受け渡しは不要）：
既存ノード（ホット接続、再起動不要）
bashzqagent link --hub https://hub.cd-zq.com --code <接続コード>起動時に接続（ソース / ベアメタル）
bashHUB_URL=https://hub.cd-zq.com HUB_ENROLL_CODE=<接続コード> pnpm run serverDocker
bashdocker run -d -p 8787:8787 -v zqagent-data:/data \ -e HUB_URL=https://hub.cd-zq.com -e HUB_ENROLL_CODE=<接続コード> \ ghcr.io/<owner>/zqagent-serverデスクトップアプリ：コンソール上部の「クラウドに接続」で Hub アドレスと接続コードを貼り付けます。
認証情報は
{DATA_DIR}/fleet.jsonに自動保存され、以後の再起動では接続コード不要です。 ノードがオンラインになれば、ユーザーセンターまたはノードコンソール（ブラウザ / スマートフォン）で状態、プロジェクト、イベントを確認でき、 タスクの投入、承認、中断など完全なセッション操作ができます。
ノードはゲートウェイへアウトバウンド接続（wss://、通常 443）するだけで、公衆からのインバウンドもポート開放も不要です。
- 接続コードは 1 回限りで短時間のみ有効です。同じノード ID が他のノード管理に重複して取り込まれることはありません（先取り防止）。
- 自前の Hub を立てる場合、ノードへ配布するゲートウェイアドレスは Hub 側の
HUB_GATEWAY_URLで決まります。
CLI のみのマシン：ノードとして常駐
CLI だけをインストールしたマシン（ソース不要）も、管理可能なノードとして常駐できます：
zqagent serve # 本機のみで使用
zqagent serve --hub https://hub.cd-zq.com --enroll-code <接続コード> # 起動時に接続バックグラウンド常駐（nohup / pm2 / systemd）、データディレクトリ、オンライン確認などはノードの起動をご覧ください。
クイックスタート
プロジェクトディレクトリでサービスを起動します（ソース方式。CLI インストール済みの zqagent serve と同等）：
pnpm run server # 既定ポート 8787。初回起動時にデモテナント demo を自動作成（apiKey はランダム生成してログに出力）起動ログにデモテナント情報が表示されます：
zqagent server 监听 http://localhost:8787
数据目录: ./data
已创建演示租户: id=demo apiKey=zk_xxxx（随机生成） model=gpt-4o-mini詳細な設定はサーバー設定をご覧ください。
公衆ネットワークは必要？
結論：サーバー本体に公衆 IP は不要です。 「リモート操作」はすべてアウトバウンド接続で、第三者のリレーを経由します：
| 機能 | サーバーの動作 | 中継 | 公衆からのインバウンドが必要？ |
|---|---|---|---|
| リモート操作 | ゲートウェイへ接続（アウトバウンド wss） | 公衆 Rust ゲートウェイ | 不要 |
| QQ ボット | テンセントゲートウェイへ接続（アウトバウンド） | テンセント QQ オープンプラットフォーム | 不要 |
| メール / Bark / Server酱 / Webhook 通知 | 能動的に POST（アウトバウンド） | SMTP / 各プッシュサービス | 不要 |
公衆ネットワーク（または内網穿透）が必要なのは 1 つの場合だけ：外部から REST インターフェースへ直接アクセスさせたいときです。 詳しくはサーバー設定をご覧ください。