ノードの起動

「ノード」とは zqagent が動作するマシンです。本機に作業ディレクトリ、モデル設定、セッションデータを持ち、 本機だけで使うことも、ユーザーセンターに接続してリモートから管理・閲覧することもできます。

このページでは、ノードの起動、常駐、接続方法を説明します。

3 つの実行形態

形態	起動方法	適する用途
対話式 CLI	zqagent	本機で会話しながら作業。最も一般的
常駐サービスノード	zqagent serve	サーバーや常時起動のマシンでリモート管理に供する
デスクトップアプリ	デスクトップアプリをインストール	GUI が欲しい場合。常駐サービスと同じ自動起動ノードを共有

デスクトップアプリと常駐サービスノードは同じノードサービス（同じデータディレクトリとポート）で、操作画面だけが異なります。 デスクトップアプリを入れてから install.sh を実行しても 2 つ目のノードはできません。対話式 CLI はカレントディレクトリの独立したデータを使います。 3 つは必要に応じて組み合わせられます。

対話式 CLI

zqagent

対話式画面に入ったら自然言語でタスクを入力します。モデルは /connect で設定します （クイックスタート参照）。コマンド一覧は CLI の使い方 をご覧ください。

対話式 CLI は「本機で使える」ノードですが、ポートを待ち受けず、リモート管理はできません。 リモート管理が必要なら下の zqagent serve を使ってください。

常駐ノードの起動

zqagent serve は画面なしでサービスを起動し、HTTP ポートを待ち受けてバックグラウンドで動作します。

zqagent serve

起動後、ログに待受アドレス、データディレクトリ、ノード ID、デモテナント情報が出力されます （初回起動時にデモテナント demo を自動作成し、その apiKey をランダム生成して起動ログに出力します。本機のデバッグにそのまま使えます）。

引数

引数	説明	既定値
--port <n>	待受ポート。使用中なら次の空きポートに自動変更（実際のポートはデータディレクトリの server-port、ログにも表示）	8787（または環境変数 PORT）
--host <addr>	待受アドレス。0.0.0.0 で外部からアクセス可能	127.0.0.1（または HOST）
--data-dir <dir>	データディレクトリ（プロジェクト、セッション、台帳、認証情報）	./.zqagent_data（または DATA_DIR）
--hub <url>	ユーザーセンターのアドレス。--enroll-code と組み合わせて起動時に接続	—
--enroll-code <code>	1 回限りの接続コード	—
--label <name>	ノードの表示名	ホスト名

既定では 127.0.0.1 のみ待ち受け、つまり本機からのみアクセス可能で最も安全です。LAN/公衆からのアクセスが本当に必要な場合のみ --host 0.0.0.0 を設定し、ファイアウォールとアクセス制御に注意してください。

バックグラウンド常駐

フォアグラウンド実行はターミナルを閉じると終了します。長期運用ではシステムサービスとしてインストールしてください（自動起動 + クラッシュ時の自動復帰）。

Windows：systemd / launchd はありません。「タスク スケジューラ」で「ログオン時に実行」のタスクを作成し、 プログラムに zqagent.exe の絶対パス、引数に serve --port 8787 --data-dir "%APPDATA%\zqagent" を指定します。 zqagent.exe serve ... のショートカットをスタートアップフォルダ（Win+R → shell:startup）に入れてもかまいません。 停止/再起動はタスク スケジューラまたはタスク マネージャーで行います。

推奨：1 コマンド（最新の単体ファイルを自動ダウンロードし、サービスをインストールして自動更新も有効化。単体ファイルインストール参照）：

curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

インストール後：

sudo sh -s -- status        # 稼働状態
sudo sh -s -- logs          # ログを追跡
sudo sh -s -- restart       # 再起動
sudo sh -s -- rollback      # 前回の自動更新前へロールバック
sudo sh -s -- uninstall     # 停止して削除

（sudo sh -s -- <サブコマンド> と curl ... | sudo sh -s -- <サブコマンド> は同等です。 スクリプトをダウンロード済みなら sudo sh install.sh status でも可。）

リポジトリのソースからインストール（開発機 / npm インストール済みの場合）。macOS は launchd、Linux は systemd：

# リポジトリの deploy/service ディレクトリで実行
bash install.sh install     # インストールして起動（自動起動）
bash install.sh status      # 稼働状態
bash install.sh logs        # ログを追跡
bash install.sh restart     # 再起動
bash install.sh uninstall   # 停止して削除

既定のデータディレクトリ：macOS ~/Library/Application Support/zqagent、Linux ~/.zqagent_data。 ログ：macOS ~/Library/Logs/zqagent/node.log、Linux ~/.zqagent_data/node.log。 （Linux の初期バージョンは /var/lib/zqagent。既存インストールはスクリプトが元の unit のパスを引き継ぎ、移行しません。） PORT / HOST / DATA_DIR / LOG / SERVICE_NAME で上書きできます。例：

sudo PORT=9000 DATA_DIR=/data/zqagent bash install.sh install

サービスは「絶対パスの node + CLI エントリー」で起動し、nvm/volta の PATH に依存しません。 Linux の追加環境変数（LLM key、HUB_URL、SECRET_KEY など）は /etc/zqagent.env に書けます。 停止は SIGTERM で、serve は台帳を保存してから終了します（猶予は既定 3 秒、ZQAGENT_SHUTDOWN_GRACE_MS で調整）。

スクリプトは現在の CLI が serve に対応しているか検証します。古いバージョン（0.1.33 など）にはこのサブコマンドがなく、 先に npm i -g @zqagent/core@latest しないとプロセスが黙って対話セッションに入ります。

systemd unit を手書き（スクリプトを使わない場合）

# /etc/systemd/system/zqagent.service
[Unit]
Description=zqagent node
After=network-online.target

[Service]
# <ユーザー名> を実際にノードを動かすユーザーに置き換え。データはそのユーザーのホームに置き、権限は自然にそのユーザーに帰属
User=<ユーザー名>
ExecStart=/usr/local/bin/zqagent serve --port 8787 --data-dir %h/.zqagent_data
Restart=always
RestartSec=3
KillSignal=SIGTERM
TimeoutStopSec=15

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now zqagent
journalctl -u zqagent -f      # ログを表示

pm2（代替）

コマンド全体を 1 つの文字列に押し込めないでください（bash -c スクリプト扱いになり、引数が失われて対話セッションに戻ります）：

pm2 start "$(command -v zqagent)" --name zqagent -- serve --port 8787 --data-dir "$HOME/.zqagent_data"
pm2 save && pm2 startup   # 自動起動

nohup（一時的なデバッグ）

nohup zqagent serve --port 8787 --data-dir "$HOME/.zqagent_data" \
  > "$HOME/.zqagent_data/node.log" 2>&1 &

自動更新

単体ファイル（SEA）でインストールし、システムサービスに管理させると、ノードは自分でバージョンを保ちます。新しいマシンでは 単体ファイルインストールの 1 コマンドを使うのがおすすめです。バイナリとサービスを同時に用意します：

1. 起動 5 分後に 1 回チェックし、その後は 6 時間ごと（±15% のジッター）
2. 新版本があれば静かにダウンロードして SHA-256 を検証し、--version で自己チェック
3. 連続 60 秒のアイドル（実行中も承認/回答待ちもないセッションがない状態）を待ってから自身を置き換えて終了
4. systemd / launchd が新バージョンを起動し、コンソールのバージョンも自動更新

失敗してもノードの動作には影響しません。ダウンロード/検証の失敗はログに残すだけで、同じバージョンで 3 回連続失敗するとスキップします。

前提条件

自動更新は次の 3 条件がすべて満たされるときのみ有効です（1 つでも欠けると無効）：

• 単体ファイル形態（SEA 成果物から起動。node dist/cli/index.js ではない）
• systemd / launchd に管理されている（install.sh でインストール）
• 検証公開鍵 ZQAGENT_UPDATE_PUBKEY が設定されている

npm でインストールしたノードは自動置換されません。npm i -g @zqagent/core@latest でアップグレードしてください。

macOS：管理判定は Linux と同じです。サービスプロセス内ではそのまま有効です。ターミナルで手動実行する zqagent update --status/--check/--now も launchd ジョブ（pid / program）と plist の EnvironmentVariables から 管理状態、公開鍵、チャネルを自動認識するため、環境変数を source する必要はありません。 アンインストールは sudo sh -s -- uninstall。

Windows：systemd / launchd がないため、単体ファイルノードは自動更新されません（zqagent update --status は 「サービス管理 未管理（フォアグラウンド/nohup）」と表示）。アップグレードは serve プロセスを停止し、新しくダウンロードした exe で 上書きしてから再起動してください。zqagent update --now は未管理環境では拒否されます。

インストールスクリプトは既定で公開鍵を取得するため、1 コマンドでインストール + 自動更新の有効化が完了します：

curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

帯域外で保存した公開鍵で自動取得を上書きしたい場合は --pubkey "..." を付けます（明示した公開鍵が優先され、ネットワーク取得で上書きされません）。

スイッチと設定

環境変数	既定値	説明
ZQAGENT_AUTO_UPDATE	1	0 で自動更新を完全に無効化
ZQAGENT_UPDATE_PUBKEY	インストール時に自動書き込み	検証公開鍵（PEM または base64 SPKI DER）。ない場合は自動インストールしない
ZQAGENT_UPDATE_CHANNEL	stable	一覧チャネル（stable / beta）
ZQAGENT_UPDATE_URL	https://agent.cd-zq.com/downloads/zqagent/<channel>.json	一覧アドレス。社内網で上書き可能
ZQAGENT_UPDATE_INTERVAL_MS	21600000（6h）	チェック間隔
ZQAGENT_UPDATE_MIN_UPTIME_MS	600000（10min）	起動後どれだけ更新しないか
ZQAGENT_UPDATE_IDLE_MS	60000	連続アイドル何ミリ秒でインストールするか
ZQAGENT_UPDATE_INSECURE	—	1 で http 一覧を許可（社内自測のみ）

更新の有無を確認

zqagent update --check       # 新版本があるかだけ確認（ダウンロードせず即時）
zqagent update --status      # 現在のバージョン、チャネル、前回チェック、保留/失敗理由

出力例：

現在のバージョン  v0.2.1
実行形態          単体ファイル（SEA）
サービス管理      systemd
更新チャネル      stable
一覧アドレス      https://agent.cd-zq.com/downloads/zqagent/stable.json
自動更新          有効

--check は「最新バージョンです（vX）」または「新バージョン vY を発見（現在 vX）」を表示します。

手動介入

zqagent update --now         # 即時ダウンロードとインストール（アイドル待ちをスキップ。サービス再起動が必要）
zqagent update --rollback    # 前回更新前のバージョンへ戻す

サービス側のロールバック（自動再起動）：

sudo sh -s -- rollback    # 単体ファイルインストール（スクリプトをダウンロード済みなら sudo sh install.sh rollback）
sudo bash install.sh rollback        # リポジトリ内インストール

ロールバック後はそのバージョンをスキップします。自動更新がすぐに戻すことはなく、より新しいバージョンが公開されるまで待ちます。 どうしても強制インストールする場合は zqagent update --now を使います。

配布側

1 コマンドで完了します：SEA 単体ファイルをビルド → 一覧を生成して署名 → ダウンロードディレクトリへ同期。npm を経由せず、 ノード側にも Node は不要です（バイナリにランタイム内蔵）。

# 初回：署名キーペアを生成（秘密鍵は配布機または CI secret のみ、公開鍵はノードへ配布）
node packages/core/scripts/gen_update_keys.mjs --out .update-keys

# 毎回のリリース（引数はすべて既定値あり：バージョンは packages/core/package.json、秘密鍵は .update-keys/update-private.pem）
bash scripts/release_node.sh

よく使う引数：

引数	既定値	説明
--version X	packages/core/package.json のバージョン	素のバージョン番号。スクリプトが両者の一致を検証
--key FILE	.update-keys/update-private.pem	Ed25519 秘密鍵。一覧の署名に使用
--pubkey-file FILE	秘密鍵と同じディレクトリの update-public.b64	ノードの検証公開鍵。公開前に秘密鍵とのペアを検証し、ダウンロードディレクトリへ同期
--host USER@HOST	空 = 本機で配布	配布機がサイトサーバーなら不要
--dest DIR	/var/www/zqagent-downloads/zqagent	nginx の /downloads/ が実際に指すディレクトリ
--notes TEXT	本次更新内容: 例行更新	一覧に書き込み、クライアントのログで確認可能
--skip-build	—	packages/core/release/cli の既存成果物を再利用
--dry-run	—	実行するコマンドを表示するだけ

3 つの典型的な使い方：

# 1) 配布機がサイトサーバー：本機のダウンロードディレクトリへ直接書き込み
bash scripts/release_node.sh --skip-build

# 2) 別のマシンから配布：ssh + rsync でサイトサーバーへ
bash scripts/release_node.sh --host deploy@your-server --skip-build

# 3) まず何をするか確認
bash scripts/release_node.sh --dry-run

クロスプラットフォームの成果物は対応するシステム/アーキテクチャでしかビルドできません。全プラットフォーム配布は CI マトリクスで各々ビルドし、 --skip-build --host ... でまとめて配布してください。

配布後のディレクトリ構造：

/downloads/zqagent/
├── install.sh           # 1 行インストールスクリプト
├── install-node.sh      # 旧アドレス互換コピー（内容は install.sh と同じ）
├── update-public.b64    # 検証公開鍵（インストール時に --pubkey で渡す）
├── stable.json          # 更新一覧（ノードが読む）
├── stable.json.sig      # 一覧の署名
├── stable.txt           # プレーンテキスト一覧（インストールスクリプト用）
└── v0.2.2/
    └── zqagent-<platform>-<arch>

ノードは署名検証に通った後にのみバイナリをダウンロードし、一覧の SHA-256 でもう一度検証します。 配布後の自己確認：

curl -s https://agent.cd-zq.com/downloads/zqagent/stable.txt
curl -s https://agent.cd-zq.com/downloads/zqagent/stable.json | head -20

完全な配布とロールバックの手順はリポジトリの docs/release-runbook.md にあります。

ユーザーセンターへの接続（任意）

接続後はユーザーセンターでノードのオンライン状態、プロジェクト、イベントを確認できます。 2 つの方法から 1 つ選びます：

• Hub アカウント（推奨）：ユーザーセンターで登録したメール/電話番号 + パスワードをそのまま使用
• 1 回限りの接続コード：ユーザーセンターにログイン → ノード管理を作成 → 接続コードを生成（15 分有効）

稼働中のノード：ホット接続（再起動不要）

# アカウント方式：メールまたは電話番号 + パスワード
zqagent link --hub https://hub.cd-zq.com --username you@example.com --password '<パスワード>'
zqagent link --hub https://hub.cd-zq.com --username 13800000000 --password '<パスワード>'

# 電話番号 + SMS 認証コード
zqagent link --hub https://hub.cd-zq.com --username 13800000000 --sms-code <認証コード>

# または 1 回限りの接続コード
zqagent link --hub https://hub.cd-zq.com --code <接続コード>

Windows 単体ファイル：

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 は対話ウィザードに入り、Hub アドレス、ログイン方式、アカウントとパスワードを順に尋ねます （パスワードは非表示入力）。パスワードは環境変数 ZQAGENT_HUB_PASSWORD でも指定でき、コマンド履歴に残りません。

Windows の既定データディレクトリは %APPDATA%\zqagent で、link はデスクトップ版が登録した runtime\service.json から自動検出します。手動でタスクスケジューラを設定し、データディレクトリが既定位置にない場合のみ --data-dir を補う必要があります。

link はまず本機で稼働中の serve へのホット接続を試みます。Linux は /proc、macOS は ps、 Windows は PowerShell の Win32_Process でプロセスコマンドラインを逆引きするため、serve が独自の --data-dir / --port を使っていても発見できます。PowerShell が使えない場合は「fleet.json を書き、次回起動時に反映」に戻ります。

複数インスタンスが見つかった場合、link はsystemd / launchd に管理されたサービスを優先し（自動起動で再起動後も残る）、 次にコマンドラインで一時起動した serve を選びます。カレントディレクトリの .zqagent_data は最後のフォールバックで、 一時インスタンスに認証情報を奪われ「コマンドは成功したのに管理サービスはオフラインのまま」になるのを防ぎます。

ノード名

接続時に --label を指定しないノードは、既定でホスト名を表示名に使います。Hub では nodeId ではなくマシン名が見えます。 後から 2 か所で変更でき、同じレコードを更新します：

• Hub ユーザーセンター → ノード管理 → ノードの「名前変更」
• ノードのマシンで実行（本機にサービスがあればホット反映、再起動不要）：

zqagent rename ten004-dev

Hub に接続済みなら、このコマンドはノード自身の認証情報で Hub レコードを同期し、コンソールを更新すれば反映されます。 未接続なら本機の設定だけを書き、次回 serve 起動時に反映されます。

サービスが現在稼働していない場合も、link は plist / systemd unit を解析して登録されたデータディレクトリを見つけ、そこへ認証情報を書き込みます （次回サービス起動時に自動接続）。したがってデスクトップ版でも install.sh でインストールしたノードでも、ユーザーが手動で --data-dir を渡す必要はありません。

通常は --data-dir を手書きする必要はありません：上記のコマンドが本機のノードを自動発見します。「本機のノードサービスが見つかりません」と 表示されたときだけ補い、しかも現在のユーザーが書き込めるディレクトリ（各プラットフォームのインストールスクリプトの既定値）を使ってください：

プラットフォーム	既定のデータディレクトリ
macOS	$HOME/Library/Application Support/zqagent
Linux	~/.zqagent_data（現在のユーザー所有。初期バージョンは /var/lib/zqagent）
Windows	%APPDATA%\zqagent

古いチュートリアルの --data-dir /var/lib/zqagent をそのまま使わないでください。新しいインストールは既定で ~/.zqagent_data にあり、 システムディレクトリを手動指定するとかえって EACCES: permission denied に当たります。この引数は省略してください。

起動時に接続

serve に Hub アドレスとアカウント（または接続コード）を渡します：

# アカウント方式（systemd / コンテナなど非対話環境に適する）
zqagent serve --hub https://hub.cd-zq.com --username you@example.com --password '<パスワード>'

# 接続コード方式
zqagent serve --hub https://hub.cd-zq.com --enroll-code <接続コード>

環境変数でも指定できます（コンテナ / スクリプト向け）：

HUB_URL=https://hub.cd-zq.com ZQAGENT_HUB_USERNAME=you@example.com \
  ZQAGENT_HUB_PASSWORD='<パスワード>' zqagent serve

HUB_URL=https://hub.cd-zq.com HUB_ENROLL_CODE=<接続コード> zqagent serve

対話式 CLI 内での接続

zqagent の画面で直接：

/link                                # アカウント接続ウィザードを開始
/link <接続コード> [Hubアドレス]

Docker

docker 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

認証情報とネットワーク

• 接続成功後、認証情報は {DATA_DIR}/fleet.json に書き込まれ、以後の再起動ではアカウントも接続コードも不要
• ノードはゲートウェイへアウトバウンド接続（wss://、通常 443）するだけで、公衆からのインバウンドもポート開放も不要
• 付け替えや解除：ユーザーセンターのノード詳細ページで操作するか、fleet.json を削除して再接続

データディレクトリ

ノードの長期データはすべて {DATA_DIR}（既定 ./.zqagent_data、プロジェクトに従う）にあります：

パス	内容
{DATA_DIR}/admin.json	管理者キー
{DATA_DIR}/fleet.json	接続認証情報（0600）
{DATA_DIR}/usage/	使用量台帳、集計、価格表
セッションとプロジェクト	各プロジェクトが作業ディレクトリごとに保存

モデルの API Key はユーザー設定ディレクトリ（macOS / Linux ~/.config/zqagent/、 Windows %APPDATA%\zqagent\）に別途暗号化保存され、データディレクトリとは分離されています。

ノードのオンライン確認

1. ブラウザでユーザーセンターを開き、該当するノード管理に入る
2. ノード一覧に該当ノードがオンラインで表示される
3. ノードをクリックしてノードコンソールに入り、プロジェクト、セッション、使用量、イベントを確認

ノードがオフラインの場合：serve プロセスが生きているか、マシンがゲートウェイアドレス（FLEET_GATEWAY_URL）へアウトバウンド接続できるかを確認してください。

次のステップ

• ノードコンソール：GUI でノード、セッション、使用量を管理
• リモート操作の概要：スマートフォンと QQ から遠隔でタスクを依頼
• サーバー設定：環境変数、クラウド接続、公衆ネットワークの方案