インストール

zqagent には コマンドラインツール（CLI） と デスクトップアプリ の 2 つの形態があります。このページでは CLI のインストール、アップグレード、アンインストールを説明します。

コマンドラインを使いたくない場合はデスクトップアプリをご覧ください。インストーラーをダウンロードすれば GUI で使えます。

最短：1 行インストール（Linux / macOS）

curl -fsSL https://agent.cd-zq.com/install.sh | sh
# サーバーでは root で実行すると自動起動サービスとしてインストールできます
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

スクリプトは公式のバージョン一覧を読み、該当アーキテクチャの単体実行ファイルをダウンロードし、SHA-256 を検証して PATH にインストールします。 Node を事前にインストールする必要はありません。既定では /usr/local/bin（書き込み可能な場合）または ~/.local/bin にインストールします。 Linux（x64 / arm64）と macOS（Intel x64 / Apple Silicon arm64）に対応します。

インストール後は自動起動サービスとして登録され（Linux systemd / macOS launchd、クラッシュ時は自動復帰）、 現在の状態と 3 つの使い方を表示します：

用途	方法
グラフィカル画面	ブラウザで http://127.0.0.1:8787 を開く
コマンドライン	zqagent（/connect でモデルを設定）
リモート管理	Hub アカウントで直接接続：zqagent link --hub https://hub.cd-zq.com --username <メール/電話番号> --password '<パスワード>'（接続コードも可）

ターミナルのあるマシンでは、インストール末尾に Hub へ接続するか尋ねられます。Hub に登録したメール/電話番号とパスワードを入力するだけです （パスワードは表示されません）。自動化する場合はインストールコマンドにアカウントを直接渡せます（パスワードは環境変数で渡すのがおすすめ）：

# パスワードを隠して入力（表示されず、シェル履歴にも残らない）
read -rsp 'Hub パスワード：' ZQAGENT_HUB_PASSWORD; echo
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- \
  --username you@example.com --password "$ZQAGENT_HUB_PASSWORD"

# または 1 回限りの接続コード（15 分有効）
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --code <接続コード>

インストール時に接続したくない場合は --no-enroll を付け、後から zqagent link で補完できます。

非 root で実行した場合やコンテナ内に systemd がない場合はサービス化をスキップし、フォアグラウンド起動コマンドを提示します。 純粋な CLI だけが必要なら --no-service を付けます。

繰り返し実行できます：インストール済みで最新版なら再ダウンロードせず、現在の状態 （バージョン、サービス稼働、ローカルアドレスの到達性、Hub 接続、自動更新チャネル）を報告します。 新しいバージョンがあれば自動でアップグレードし、サービスを再起動します。

よく使う引数（sh -s -- で渡す）：

# ポート / 待受アドレス / データディレクトリを変更
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --port 9000 --host 0.0.0.0

# カスタムディレクトリにインストール
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --bin-dir ~/bin

# CLI のみ、自動起動サービスは入れない
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --no-service

# インストール後に Hub アカウントで接続（--code <接続コード> も可）
read -rsp 'Hub パスワード：' ZQAGENT_HUB_PASSWORD; echo
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- \
  --username you@example.com --password "$ZQAGENT_HUB_PASSWORD"

# インストール末尾の接続確認をスキップ
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --no-enroll

# インストール済みでも強制的に再ダウンロードして上書き
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --force

# 強制的に npm を使う
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --npm

# 匿名インストール統計を送信しない
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --no-telemetry

1 行スクリプトは macOS / Linux 向けです。Windows は単体ファイル exe （対象機に Node 不要）をダウンロードするか、下の npm 方式でインストールしてください。

インストール統計について：インストール成功後、自前の統計サービスへ匿名レコードを 1 件送信します （バージョン、プラットフォーム、アーキテクチャ、インストール方法のみ）。各プラットフォームの実際の利用状況を把握するためです。 ユーザー名、インストールパス、IP、身元を特定できる情報は含まず、Cookie も使用しません。 不要な場合は --no-telemetry を付けるか ZQAGENT_NO_TELEMETRY=1 を設定すれば完全に無効化できます。

macOS について

• チップアーキテクチャ：Intel（macos-x64）と Apple Silicon（macos-arm64）でそれぞれ対応する成果物をダウンロードします。
• 自動起動：root でインストールすると LaunchDaemon として登録 （/Library/LaunchDaemons/com.zqagent.node.plist、起動時に開始）。 通常ユーザーでインストールすると LaunchAgent として登録（~/Library/LaunchAgents/、ログイン後に開始）。 plist には KeepAlive があり、プロセス終了時は launchd が即座に再起動します。
• 自動更新：Linux と同じ。サービス内で静かにダウンロードし一覧で署名検証、アイドル時にバイナリを置き換えて終了し、 launchd が新バージョンを起動します。zqagent update --status で管理状態と前回チェック時刻を確認できます。
• アンインストール：sudo sh -s -- uninstall。システムレベルの Daemon と、sudo を実行したユーザーの Agent を同時に削除します。 データディレクトリとバイナリは残り、繰り返し実行してもエラーになりません。
• 単一インスタンス：root で再インストールする際は、そのユーザーの LaunchAgent を先に削除し、システムレベルとユーザーレベルの 2 インスタンスが同じポートを奪い合うのを防ぎます。

既定のデータディレクトリ：通常ユーザーは ~/Library/Application Support/zqagent、 root でインストールした場合は /var/root/Library/Application Support/zqagent。

macOS の 2 アーキテクチャの単体ファイルは各バージョンとともに公開され、インストール時に Node を事前に入れる必要はありません。 ある一覧に現在のアーキテクチャの成果物がない場合、スクリプトは自動で npm にフォールバックします（Node ≥ 18.17 が必要）。 npm のグローバルディレクトリに書き込めない場合は ~/.local にインストールし、案内を表示します。

ポートが使用中なら自動で変更

既定ポート 8787 は開発機で他のサービスに使われていることがよくあります。インストールスクリプトはサービス登録前にポートを確認し、 使用中なら 8788、8789…と順に増やし、各試行を表示して、最終的なポートでサービス設定を生成します：

→ ポート 8787 が使用可能か確認 ...
! ポート 8787 は他のプロセスが使用中
→ ポート 8788 を試行 ...
! ポート 8788 に自動変更しました（予定の 8787 が使用中）
  ローカルコンソール：http://127.0.0.1:8788

ノードプロセス自体にも同じ保護があります：サービス起動時にポートが使用中なら自動で次の空きポートに切り替えてログに説明し、 実際のポートをデータディレクトリの server-port ファイルに書き込みます。インストールスクリプトと zqagent update --status はそれを基にアドレスを報告します。

ポートをこのノード自身が使用している場合（サービスが稼働中）、スクリプトはそのポートを引き継ぎ、2 つ目のインスタンスを起動しません。 固定したい場合は --port <ポート> を使います。開始ポートから連続 20 個が使用中ならエラー終了します。

Windows 単体ファイル（Node 不要）

Windows の成果物は単一の zqagent.exe で、対象機に Node/npm は不要です。

システム要件：Windows 10 / Server 2016 以降（64 ビット x64 または ARM64 のみ）。 Windows 7、8、8.1 と Server 2008 R2 / 2012 は実行できません。不足しているのはシステム API で、 C++ ランタイムをインストールしても解決しません。詳しくは Windows 対応バージョン をご覧ください。

1. アーキテクチャに合う成果物をダウンロード（対象機に Node/npm は不要）：

   アーキテクチャ	対象	ダウンロード
   x64	ほとんどの Windows	zqagent-windows-x64

   ファイル名にはバージョンとビルド日時が入ります。リンクはサイトのビルド時に現在のリリースへ自動で向きます。完全な一覧は https://agent.cd-zq.com/downloads/zqagent/stable.json（binaries.windows-x64.url）にあります。 Windows ARM64 の成果物は現在ありません。x64 版を使用してください（Windows がエミュレーションで実行します）。

2. 任意のディレクトリ（例 %LOCALAPPDATA%\zqagent\）に置き、PowerShell または cmd で実行：

   .\zqagent-windows-x64-v<バージョン>-<ビルド時間>.exe

   初回起動後に /connect でモデルを設定すれば使えます。

3. zqagent と直接入力したい場合：そのディレクトリをユーザーの PATH に追加し（「システムのプロパティ → 環境変数」）、 ファイル名を zqagent.exe に変更します。コマンドラインの場合（setx は長すぎる PATH を切り詰めます）：

   setx PATH "%PATH%;%LOCALAPPDATA%\zqagent"

リモート管理可能なノードとして常駐：

zqagent.exe serve --port 8787 --data-dir "%APPDATA%\zqagent"

自動起動が必要な場合は「タスク スケジューラ」で「ログオン時に実行」のタスクを作成します。プログラムには exe の絶対パス、 引数には serve --port 8787 --data-dir "%APPDATA%\zqagent" を指定します。

• Windows には systemd / launchd がないため、単体ファイルでは自動更新が無効です（自身を置き換えても サービス管理が起動し直せません）。アップグレード方法：プロセス停止 → 新しい exe をダウンロードして上書き → 再起動。
• 成果物には Authenticode 署名がありません（SEA を注入すると node.exe の署名が壊れます）。初回実行時に SmartScreen の警告が出る場合があります。正式配布前に signtool で再署名してください。
• CLI には ripgrep が内蔵されているため、rg を別途インストールする必要はありません。

システム要件

項目	要件
OS	macOS / Linux / Windows。Windows は 10 / Server 2016 以上（デスクトップアプリは 10 1709+）。詳しくは Windows 対応バージョン
Node.js	≥ 18.17（npm インストールのみ必要。Linux / macOS / Windows の単体ファイルはランタイム内蔵）
ネットワーク	agent.cd-zq.com（単体ファイル）または公共 npm registry.npmjs.org（npm）へアクセスできること

サブコマンド：インストール済みノードの管理

install.sh は管理ツールでもあります。インストール以外に status / logs / restart / rollback / print-config サブコマンドに対応します（sudo が必要な場合は付ける）：

sudo sh -s -- status        # バージョン、サービス、ローカルアドレス、リモート接続、自動更新
sudo sh -s -- logs          # ノードログを追跡
sudo sh -s -- restart       # サービスを再起動
sudo sh -s -- rollback      # 前回の自動更新前のバージョンへ戻す
sudo sh -s -- print-config  # 使用する設定を表示するだけで、何も実行しない
sudo sh -s -- uninstall     # サービスを削除（データディレクトリとバイナリは残す）

パイプで実行する場合、サブコマンドは sh -s -- の後に置きます：

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

スクリプトをダウンロード済みなら引数として直接渡せます：sudo sh install.sh status。

インストールスクリプトは次を行います：

1. 公式一覧から最新バージョンを読み、プラットフォーム/アーキテクチャに応じたバイナリをダウンロード
2. SHA-256 とバージョンを検証
3. 検証用公開鍵を自動取得（--pubkey で明示指定も可）
4. /usr/local/bin/zqagent（または ~/.local/bin）へインストール
5. サービスとして登録：Linux は systemd、macOS は launchd

つまり1 コマンドで完了し、公開鍵を手動で探す必要はありません。

設定付きインストール（ポート、データディレクトリ）

curl -fsSLO https://agent.cd-zq.com/install.sh
sudo sh install.sh --port 8787 --data-dir /srv/zqagent

公開鍵を自分で指定（任意）

--pubkey を渡さない場合、スクリプトは $BASE_URL/update-public.b64 から自動取得します。このファイルは更新一覧と同源のため、 この既定の信頼は「サイトの HTTPS とドメインが突破されていないこと」に依存します。より強い保証が必要なら、帯域外で保存した 公開鍵をインストール時に明示的に渡してください：

sudo sh install.sh --pubkey "$(cat /path/to/update-public.b64)"

明示した公開鍵が優先され、スクリプトがネットワークで上書きすることはありません。形式が不正ならエラー終了します。

引数	説明	既定
--port <n>	待受ポート	8787
--host <addr>	待受アドレス	127.0.0.1
--data-dir <dir>	データディレクトリ	Linux ~/.zqagent_data、macOS ~/Library/Application Support/zqagent（ログも追従）
--pubkey <key>	自動更新の検証公開鍵	$BASE_URL/update-public.b64 から自動取得
--service-name <n>	systemd unit 名	zqagent
--label <name>	launchd ジョブ名	com.zqagent.node
--channel <name>	更新チャネル	stable
--version <x.y.z>	バージョン指定	一覧の最新版
--no-service	バイナリのみインストール	—

Windows はデスクトップアプリを使用してください。WSL 内なら上記の Linux 方式でインストールできます。

リモートサーバーへのインストール

先にサーバーへログインする必要はなく、手元から SSH でインストール処理を送れます。サーバーに curl と sudo があれば十分で、 Node/npm は不要です。ダウンロードするのはランタイム内蔵の単体バイナリです。

ssh deploy@your-server \
  'curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh'

ポートやデータディレクトリを指定する場合は、先にダウンロードしてから実行します（パイプ方式では引数を渡せません）：

ssh deploy@your-server '
  curl -fsSLO https://agent.cd-zq.com/install.sh &&
  sudo sh install.sh --port 8787 --data-dir /srv/zqagent
'

インストール後は同じく install.sh status|logs|restart|rollback のサブコマンドが使え、以降のアップグレードはノードが 一覧に従って自動で行います（次節参照）。

統合前に公開された install-node.sh の URL（/downloads/zqagent/install-node.sh）にも同じ内容のコピーが 引き続き同期されます。既存スクリプトは変更不要ですが、新しいスクリプトは install.sh に統一することをおすすめします。

単体ファイルインストールのアップグレード

単体ファイルでインストールしたノードは自動更新します。新しいバージョンを静かにダウンロードし、実行中のタスクがなくなったら 自身を置き換えて再起動します。詳しくはノードの起動 · 自動更新をご覧ください。

手動で確認する場合：

zqagent update --check     # 新しいバージョンがあるか
zqagent update --status    # 現在のバージョン、チャネル、前回チェック

ソフトウェアソース

@zqagent シリーズのパッケージは公共 npm（https://registry.npmjs.org/）に公開されており、登録やアカウント申請は不要で、 npm の既定ソースでそのままインストールできます。

本機の npm が国内ミラー（registry.npmmirror.com など）を既定にしていても問題なくインストールできます。ミラーは公開後に自動同期されます。 どちらの場合も @zqagent 用にスコープを別途設定する必要はありません。

npm インストール（開発者 / Node を使っている場合）

開発機でいつでも zqagent を使いたい場合に適します。自動更新の管理外で、アップグレードは npm で行います。

# 本機の既定ソースを使用（推奨）
npm i -g @zqagent/core

# または一時的に公共 npm を指定
npm i -g @zqagent/core --registry=https://registry.npmjs.org/

バージョンチャネル

公共 npm は現在安定版（latest タグ）のみを公開しています：

チャネル	インストールコマンド	説明
安定版（既定）	npm i -g @zqagent/core@latest	リリースごとに latest を更新。日常利用に適する

バージョンを指定しない場合は @latest と同じです。以前のドキュメントにあった @dev テストチャネルはまだ公開されておらず、 npm i -g @zqagent/core@dev はバージョンが見つからないエラーになるため使用しないでください。

インストールの確認

zqagent link --help       # macOS / Linux（PATH に追加済み）

.\zqagent-windows-x64-v<バージョン>-<ビルド時間>.exe link --help    :: Windows 単体ファイル（PATH 未追加）

その後 zqagent を実行して対話式 CLI に入り、/connect でモデルを設定すれば始められます。 詳しくはクイックスタートをご覧ください。

アップグレードとアンインストール

Windows 単体ファイル

:: アップグレード：実行中の serve を停止し、新しい exe で旧ファイルを上書き
:: （ファイル名は変えないので、タスクスケジューラ / ショートカットの変更は不要）
copy /Y zqagent-windows-x64.exe "%LOCALAPPDATA%\zqagent\zqagent.exe"

:: アンインストール：プロセス停止後に exe とデータディレクトリを削除
rmdir /S /Q "%LOCALAPPDATA%\zqagent"

単体ファイルインストール（install.sh、macOS / Linux）

# アップグレード：インストールスクリプトを再実行するだけ。最新なら状態を報告するのみ
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

# サービスを削除（データディレクトリとバイナリは残す）
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- uninstall

# 完全削除（Linux。データは既定で実行ユーザーのホーム）
sudo rm -rf ~/.zqagent_data /usr/local/bin/zqagent

# 完全削除（macOS。通常ユーザーインストール時はデータが ~/Library/Application Support/zqagent）
sudo rm -rf "/var/root/Library/Application Support/zqagent" /usr/local/bin/zqagent

インストールとアンインストールは繰り返し実行できます：インストール済みで再実行しても再ダウンロードせず現在の状態を報告するだけです。 サービスがない状態で uninstall を実行してもエラーになりません。アンインストール後に再インストールすると、残されたバイナリとデータディレクトリを再利用し、 接続済みの Hub 認証情報やモデル設定もそのまま残ります。

npm インストール

# 最新の安定版へアップグレード
npm i -g @zqagent/core@latest

# アンインストール
npm uninstall -g @zqagent/core

アップグレードはプログラム本体のみを置き換え、モデル設定やセッションデータには触れません （設定は ~/.config/zqagent/、セッションとプロジェクトデータは各データディレクトリ。ノードの起動参照）。

よくある質問

zqagent: command not found と出る？ グローバルの bin ディレクトリが PATH にありません。確認して PATH に追加します：

Windows の単体ファイルは完全なパスか .\zqagent.exe で実行します。PATH への追加方法は Windows 単体ファイルをご覧ください。

npm prefix -g        # npm のグローバルプレフィックスを出力。bin はその中（Windows は同ディレクトリ）
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc   # macOS/Linux

インストール時に EACCES 権限エラーが出る？ npm のグローバルディレクトリが root 所有になっています。sudo npm i -g は使わず、 バージョン管理ツール（nvm/fnm）を使うか、npm のグローバルプレフィックスをユーザーディレクトリに変更してください：

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

インストールが遅い、タイムアウトする？https://registry.npmjs.org/（または設定したミラー）にアクセスできるか確認してください。社内ネットワークでは HTTP プロキシを設定できます：

npm config set proxy http://<host>:<port>
npm config set https-proxy http://<host>:<port>

別のマシンでは再設定が必要？~/.npmrc と ~/.config/zqagent/ はユーザーディレクトリにあるため、マシンを変えるとソースの再設定が必要です。 モデルの API Key は /connect で再接続できます。

次のステップ

• クイックスタート：モデルに接続して最初のタスクを完了
• ノードの起動：zqagent をリモート管理可能なノードとして常駐
• ノードコンソール：GUI でノード、セッション、使用量を管理