サーバー設定
このドキュメントはサーバーの起動と設定ガイドで、3 つの問いに答えます：
- どう起動するか（ローカル / クラウド / デスクトップの 3 形態）
- 公衆ネットワークが必要か（結論：本体は不要。REST インターフェースが必要な場合のみ）
- クラウド接続をどう設定するか（Rust ゲートウェイに接続し、以後リモート管理可能に）
事前準備
| 項目 | 要件 |
|---|---|
| Node.js | ≥ 18.17（20+ 推奨） |
| モデル API Key | OpenAI 互換エンドポイント（DeepSeek / OpenAI / Ollama / カスタム） |
| （任意）クラウドアカウント | 自前の Rust ゲートウェイ + Hub、またはマネージドサービス |
| （任意）QQ オープンプラットフォームのボット | q.qq.com で登録 |
bash
# コードを取得して依存関係をインストール
pnpm install
# 対話式設定（推奨）：LLM は必須、QQ/メールは任意でスキップ可
bash scripts/configure-server.sh
# または手動：テンプレートをコピーして記入
# cp .env.example .env環境変数一覧
プロジェクトルートの .env に書くか（または起動前に export）：
| 変数 | 説明 | 既定 |
|---|---|---|
DATA_DIR | データ/テナントのルート | ./.zqagent_data |
PORT | REST 待受ポート | 8787 |
HOST | 待受アドレス（公衆公開時は 0.0.0.0） | 127.0.0.1 |
WORKSPACE | Agent の作業ディレクトリ | カレントディレクトリ |
APPROVAL_TIMEOUT_SECONDS | 承認/質問の保留タイムアウト | 900 |
MAX_ITERATIONS | 1 ターンの最大イテレーション | 800 |
OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL / OPENAI_REASONING_EFFORT | モデル設定（OPENAI_MODEL を未設定ならモデル未指定となり、コンソールで選択が必要） | — |
TENANT_ID / TENANT_API_KEY / MODEL | 初回起動時に自動作成されるデモテナント | demo / 初回起動時にランダム生成 / モデル既定 |
SECRET_KEY | 通知認証情報などを暗号化する主キー | 自動生成 |
FLEET_TOKEN / FLEET_SECRET / FLEET_GATEWAY_URL | クラウド接続（通常は登録コード接続で fleet.json に自動書き込み） | — |
QQ_BOT_APP_ID / QQ_BOT_APP_SECRET / QQ_BOT_SANDBOX | QQ ボット（設定すると有効化） | — |
CONTEXT_WINDOW / COMPACTION_THRESHOLD_PCT / COMPACTION_CAP_TOKENS | 長い会話の圧縮パラメータ | 自動 |
SECRET_KEYは一度設定したら長期固定を推奨します。テナントの署名鍵と通知チャネルの認証情報の暗号化に使うため、 変更すると旧テナントの鍵と認証情報が無効になります。
3 つのデプロイ形態
ローカル / 社内ネットワーク（最も推奨、公衆ネットワーク不要）
bash
# 最小構成（起動と会話ができるか確認）
pnpm run server
# ログ：
# zqagent server 监听 http://127.0.0.1:8787
# 已创建演示租户: id=demo apiKey=zk_xxxx（随机生成） model=...
# 完全なリモート操作（.env 設定後）：
# FLEET_GATEWAY_URL=wss://gw.example.com/ws
# QQ_BOT_APP_ID=... QQ_BOT_APP_SECRET=...
# OPENAI_API_KEY=sk-... OPENAI_MODEL=...
pnpm run server起動後にサービスが使えるか確認：
bash
# デモテナントの apiKey は初回起動時にランダム生成され起動ログに出力される。取り出して TOKEN に保存
TOKEN=<起動ログの apiKey> # zk_1f0c... の形式
curl -s http://localhost:8787/healthz # => {"status":"ok"}
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8787/api/v1/sessionsクラウドデプロイ（REST の公衆アクセスが必要な場合）
クラウドサーバーを借り、HOST=0.0.0.0 でポートを公開します。
bash
# pm2 で常駐させるのがおすすめ
npm install -g pm2
HOST=0.0.0.0 pm2 start "pnpm run server" --name zqagent-server
# セキュリティの推奨：必要な人だけに開放。REST を自分だけが使うなら公衆に直接出さず、
# 内網穿透を使うか、クラウドサーバーのファイアウォールで送信元 IP を制限する。デスクトップアプリ（macOS / Windows）
デスクトップアプリはローカルでサーバーを自動起動するため、手動起動は不要です。デスクトップアプリをご覧ください。
REST の公衆アクセスが必要な場合の 3 案
| 案 | 方法 | 適する場面 |
|---|---|---|
| A. 内網穿透（個人向け推奨） | Cloudflare Tunnel（無料）または frp/ngrok でローカルポートを公衆 HTTPS にマップ | 自宅/社内マシン。サーバーを借りたくない |
| B. クラウドサーバー | VPS に直接デプロイし HOST=0.0.0.0 | 既存サーバーがある、長期安定が必要 |
| C. REST を使わない | ゲートウェイの全経路（認証情報はコントロールプレーンが発行）を使い、REST は自分の PC のみ | ポートを一切公開したくない |
クラウド接続（Rust ゲートウェイ）
接続後は任意のデバイスからこのノードをリモート管理できます。ノードはゲートウェイへアウトバウンド接続（wss://、通常 443）するだけで、 公衆からのインバウンドもポート開放も不要で、MQTT broker も不要です。
方法 1：登録コードで接続（推奨）
ユーザーセンター（Hub）で 1 回限りの登録コードを作成し、ノードのマシンで実行します：
bash
zqagent link --hub https://hub.example.com --code <登録コード>- 本機でサービスが稼働中 → ホット接続（再起動不要）
- そうでなければ認証情報を
{DATA_DIR}/fleet.jsonに書き込み、次回zqagent serveで自動接続
方法 2：手動設定
bash
# .env
FLEET_TOKEN=<高エントロピーのランダム> # 名前空間の識別子
FLEET_SECRET=<高エントロピーのランダム> # 署名鍵（ゲートウェイ側と一致させる）
FLEET_GATEWAY_URL=wss://gw.example.com/ws
SECRET_KEY=<64 桁 hex> # 明示的な設定を強く推奨起動後に確認：
bash
curl -s -H "Authorization: Bearer $ADMIN_API_KEY" \
http://localhost:8787/api/v1/fleet/pairing
# => {"data":{"gatewayUrl":"wss://gw.example.com/ws","fleetToken":"...","fleetSecret":"...","nodeId":"..."}}起動ログに「云端接入: wss://…（节点 nodeId）」が出れば成功です。
クラウドに接続しない
FLEET_* を一切設定しなければ純ローカルノードです。ローカル機能はすべてそのまま使え、クラウドからは見えないだけです。 いつでも zqagent link で接続できます。
ゲートウェイ側のデプロイ（鍵、TLS、複数レプリカ）はリポジトリの
docs/rust-gateway-plan.mdとdeploy/k8s/gateway/をご覧ください。プロトコルの詳細はdocs/wire-protocol.md。
よくあるトラブル
| 現象 | 確認 |
|---|---|
| ノードがゲートウェイに接続できない | アドレスが wss://.../ws か。証明書が CA 発行（自己署名でない）か。ファイアウォールで 443 を許可しているか |
| ログに「未能接入网关」 | FLEET_GATEWAY_URL の到達性と、FLEET_SECRET がゲートウェイと一致するか確認 |
| サーバーが外部を待ち受けない | HOST の既定は 127.0.0.1。公衆アクセスには HOST=0.0.0.0 とポート開放が必要 |
| QQ ゲートウェイ接続失敗 | AppID/Secret を確認。intents 権限を申請したか。サンドボックスは QQ_BOT_SANDBOX=1 |
| メールが送れない | QQ メールは認証コード（ログインパスワードではない）。secure とポートの対応（465→true、587→false） |
SECRET_KEY 変更後に認証情報が無効 | SECRET_KEY は固定を推奨。変更すると旧テナントの認証情報がすべて無効になる |