Factory Droid + JoinGonka Gateway: GonkaネットワークモデルでのBYOK

ステップ1：Droidをインストールする。Factoryのドキュメントに記載された公式の方法：

# macOS and Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# via npm
npm install -g droid

スクリプトはバイナリを~/.local/binに配置し、このディレクトリをPATHに追加する方法を案内します。Linuxではドキュメントでxdg-utilsパッケージの追加インストールが求められています。確認はdroid --versionで行えます。

ステップ2：キーを取得する。gate.joingonka.ai/registerで登録し、アドレスを確認して、「APIキー」セクションでjg-プレフィックスのキーを作成してください。1つのキーと1つの残高がネットワーク上のすべてのモデルで有効です。

ステップ3：インストーラーを実行する。

npx @joingonka/setup --tool droid

インストーラーがキーの入力を求めます。コマンドライン引数では渡されません。シェルの履歴に残らないようにするためです。そして4つの処理を行います：

• ~/.factory/settings.json（Windowsでは%USERPROFILE%\.factory\settings.json）のcustomModels配列に、ネットワーク上の各モデルごとにエントリを追加します：ゲートウェイのアドレス、プロバイダータイプgeneric-chat-completion-api、リテラルとしてのキー、実際のコンテキストウィンドウと応答上限。ファイルには600の権限が設定されます。
• デフォルトモデル（sessionDefaultSettings.model）をDeepSeek V4 Flashに設定します。ただし、未選択の場合、またはネットワークから削除されたモデルを指している場合のみです。Factoryのカタログのモデルや他のBYOKエントリは上書きせず、切り替え方法を案内します。
• 以前のファイルのコピーを保存し、customModels内の他のエントリ、その他の設定、コメントはそのまま残します。解析できないファイルは上書きせず、修正すべき点を伝えます。
• 最後にゲートウェイに実際のリクエストを送信し、キー、アドレス、モデルが受け入れられたかどうかを明確に伝えます。

別のデフォルトモデルは--modelフラグで指定します。省略形はdeepseek、glm、minimaxです。明示的に指定されたモデルは常に書き込まれます。ドットファイルやサーバー向けには対話なしモードがあり、キーは環境変数から取得されます：

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool droid --model glm --non-interactive

Droidを再起動する必要はありません。settings.jsonの変更は自動的に検出されます。最後に! Could not verify right nowというメッセージと429レスポンスが表示される場合、設定エラーではなくモデルが混雑していることを意味します。構成はすでに書き込まれています。

インストーラーがやっていることは、すべて手書きで再現できます。Droidのユーザー設定は~/.factory/settings.jsonに保存され、ファイルがなければ初回起動時にDroidが作成します。GonkaネットワークにはcustomModels配列とデフォルトモデルが必要です：

{
  "customModels": [
    {
      "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
      "id": "custom:deepseek-ai/DeepSeek-V4-Flash-0731",
      "displayName": "DeepSeek V4 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32768,
      "maxContextLimit": 380000,
      "noImageSupport": true
    },
    {
      "model": "zai-org/GLM-5.3-Flash",
      "id": "custom:zai-org/GLM-5.3-Flash",
      "displayName": "GLM 5.3 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 390000,
      "noImageSupport": true
    },
    {
      "model": "MiniMaxAI/MiniMax-M2.7",
      "id": "custom:MiniMaxAI/MiniMax-M2.7",
      "displayName": "MiniMax M2.7 (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 200000,
      "noImageSupport": true
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:deepseek-ai/DeepSeek-V4-Flash-0731"
  }
}

デフォルトモデルはsessionDefaultSettings.modelに保存され、エントリをidで参照します。Factoryのドキュメントにはファイルルートのmodelキーも記載されていますが、こちらの検証では-mフラグなしのdroid execはsessionDefaultSettingsからモデルを取得し、値を変更した後も同様でした。

キーはファイル内に平文で保存されます。chmod 600 ~/.factory/settings.jsonでファイルを保護し、キーを含むエントリをプロジェクトの.factory/settings.jsonに移さないでください。通常リポジトリにコミットされてしまいます。また、Droid起動後にファイルの見た目が変わっていても問題ありません。設定を保存するたびにDroidはファイル全体を書き直し、キーを並べ替え、エントリにindexフィールドを追加し、コメントは保存しません。パーミッション600は維持され、インストーラーはそうしたエントリも問題なく更新します。

Droidは自身のモデル登録をカタログとは別に表示します。ドキュメントによれば、インタラクティブモードでは/modelコマンドがCustom modelsセクションにそれらを一覧表示し、Ctrl+Nは入力フィールド上で直接モデルを切り替えます。ワンショットモードではモデルを-mフラグで指定し、値はidフィールドから取ります。スラッシュはそのまま記述します：droid exec -m custom:zai-org/GLM-5.3-Flash "…"。

名前を間違えると、DroidはInvalid modelと応答し、認識しているすべてのモデルを列挙します。自身のモデルはcustom:… (display name)の形式で表示されるため、登録が読み込まれたことも確認できます。Factoryのドキュメント形式の名前（ラベルと番号によるcustom:DeepSeek-V4-Flash-(Gonka)-0）は、明示的なidがある場合には機能しません。私たちの実行では、同じくInvalid modelが返りました。

Factoryアカウントが必要な場面。自身のモデルを使えばトークン課金の問題は解決しますが、製品へのログイン自体は不要にはなりません。アカウント未ログインでDroid 0.225.1を実行した結果は以下の通りです：

インターフェースで作業するにはFactoryアカウントを作成し、ブラウザ経由でログインしてください。Login項目または/loginコマンドを使います。ブラウザのないマシンでは、ドキュメントはアカウント設定から取得したキーをFACTORY_API_KEY環境変数に設定する方法を提案しています。ログインなしでのdroid execの動作は試用には便利ですが、公式には文書化されていないため、CIで依存しないでください。Factoryの料金ページによれば、BYOKは無料枠付きのすべての個人プランに含まれており、無料枠を超えたBYOKの利用はプランの条件に従って課金されます。最新の条件はfactory.ai/pricingをご覧ください。ネットワークモデルのトークンは別途、JoinGonkaの残高から支払われます。

どのモデルを選ぶか。ネットワーク上のすべてのモデルの価格は同じなので、選択の基準は挙動です。1つのタスク（ファイルを読み込んでエラーを見つける）でdroid execを実行した結果は以下の通りです：

-rフラグ（推論レベル）は、FactoryのドキュメントによればBYOKモデルには適用されません。デフォルトでDeepSeek V4 Flashが選ばれている理由はモデルレビューで解説しています。

空のディレクトリに、明らかなバグを含む calc.py ファイルを置いてください。たとえば、長方形の面積を求める際に辺の長さを掛けずに足してしまうコードなどです。そして、Droid にそのバグを見つけるよう依頼します：

droid exec "Read the file calc.py in the current project directory and tell me in one sentence whether it has a bug."

フラグを付けない場合、droid exec は読み取り専用モードで動作します。ファイルの閲覧はできますが、変更はできません。エージェントは自ら読み取りツールを呼び出し、問題のある式を明示して本質的な回答を返します。-o json フラグを付けると、回答は単一のオブジェクトとして返され、スクリプトでの解析に便利です（出力は省略されています）：

{"type":"result","subtype":"success","is_error":false,"duration_ms":2239,"num_turns":2,
 "result":"Yes, the file has a bug: the rectangle area is computed as the sum of the side lengths, but it should be their product (width * height). …",
 "usage":{"input_tokens":19016,"output_tokens":146,"factory_credits":0,"ttft_ms":747}}

factory_credits: 0 フィールドは、処理が Factory のクレジットではなく、お客様のモデル上で行われたことを示しています。エージェントがファイルを編集できるようにするには、自律レベルを追加します：droid exec --auto low "Fix the bug in calc.py and change nothing else." — 私たちの実行では、DeepSeek V4 Flash がファイルを読み込み、加算を乗算に置き換え、12 が出力されることを確認するために自らスクリプトを実行しました。

3番目の確認はゲートウェイ側です：管理画面の「使用状況」セクションで、リクエストは「モデル別」の内訳に表示され、「キー別」ブロックでは最終リクエスト時刻が更新されます。

何か問題が発生した場合、Droid の特性に注意してください：コンソールでは droid exec は Error during droid execution: Exec failed のみを出力し（JSON では "result":"Exec failed"）、本当の原因はログに残ります。それは次のコマンドで取得できます：

grep agent_error_count ~/.factory/logs/droid-log-single.log | grep -o '"errorMessage":"[^,]*' | tail -1

エージェントツールはチャットとは異なる方法でトークンを消費します。Droidは各フレーズに対してシステムプロンプト、ツール定義、作業ディレクトリのスナップショットを追加するため、タスクの完了には数ターンを要します。我々の検証では、ユーザーの質問が届く前の段階で、各ターンごとに約9,500トークンの入力トークンが発生しました。「ファイルを読み込んでエラーを見つける」タスクでは2ターン（約1万9千トークン）、「修正して検証する」タスクでは4ターン（約4万4千トークン）を消費しました。そのため、ここでのトークン単価が重要になります。

JoinGonka Gateway経由の場合、トークン単価は入力100万トークンあたり$0.0069、出力100万トークンあたり$0.021です。この価格はネットワーク内の全モデルで共通であり、このページのライブソースから動的に読み込まれます。

右列の概算は2026年9月時点の価格に基づいています。参考として、Droidでモデル料金を支払う主な方法は以下の通りです：

Droidインターフェースの /cost コマンドでセッション統計を表示でき、BYOKモデルの正確な消費量と残高は、ゲートウェイ管理画面の「Usage（使用量）」および「Billing（課金）」セクションで確認可能です。Droid用に個別のキーを作成すると、トラフィックを個別の行として識別できます。

自律性。 ワンショットモードでは、Droid はデフォルトで読み取りのみを行い、権限はレベルによって拡張されます：--auto low — ファイルの編集、--auto medium — さらに依存関係のインストール、ビルド、テスト、ローカルコミット、--auto high — push やデプロイまで。フラグ --skip-permissions-unsafe はすべてのチェックを解除します — 使い捨てコンテナ専用です。インタラクティブモードでは、レベルは Ctrl+L で切り替え、開始レベルは sessionDefaultSettings.autonomyLevel で設定します。デフォルトは off です — すべて確認付きです。

コミットへの署名。 設定 includeCoAuthoredByDroid はデフォルトで有効になっています：Droid はコミットメッセージに共同作成者の行を追加します。不要な場合は、settings.json に "includeCoAuthoredByDroid": false と記述してください。

セッションの保存場所。 アカウントにログインすると、Droid はデフォルトで CLI セッションを Factory のウェブ版にミラーリングします — これは cloudSessionSync が担当します。BYOK キーはドキュメントによるとローカルに留まります。会話もマシン上に留めたい場合は、"cloudSessionSync": false に設定してください。ゲートウェイ側はプロンプトや回答の内容を保存しません — 統計には使用量の集計のみが残ります。

更新。 スクリプトによるインストールは自動的に更新されます。バージョンを固定するには、変数 FACTORY_DROID_AUTO_UPDATE_ENABLED=false またはコマンド droid update --version <version> を使用します。npm からのビルドは自動的に更新されません。更新後、droid exec を1回実行して、ネットワークのモデルが揃っていることを確認してください。

画像。 ネットワークのモデルはテキストベースです。スクリーンショット用には、視覚機能を持つモデルのエントリを別のプロバイダーで用意してください。

ベンダーアカウントなしでの作業が必須の場合。 同じネットワークのモデルは、ログインが不要なオープンなターミナルエージェントにも接続できます — たとえば、OpenCode に同じインストーラーで、フラグ --tool opencode を付けて接続します。