OpenHands + JoinGonka Gateway: カスタムエンドポイント上のエージェント

現在プロジェクトには複数のインターフェースがあり、どれが起動しているかによってモデル設定の場所が異なります。値自体はどこでも同じですが、そこに至るパスが異なります。

Agent CanvasにはNode.jsとuvが必要です（エージェントのローカルサーバーがこれで動作します。詳細はインストールガイドを参照）。ガイドではNode.js 22.12以降を推奨していますが、バージョン1.17以降のパッケージ自体はNode.js 24以降を宣言しているため、バージョン不一致の警告を避けるために24をインストールしてください。コンテナ版もあり、ghcr.io/openhands/agent-canvasイメージはhttp://localhost:8000/canvasでインターフェースを提供し、マウントされたディレクトリのみを参照できます。

JoinGonkaキー。 gate.joingonka.ai/registerに登録し、メールを確認後、「API Keys」セクションでjg-で始まるキーを作成してください。1つのキーと1つの残高がネットワーク内のすべてのモデルで有効です。インストーラーのツールリストにOpenHands用の@joingonka/setupは存在しませんが、これは不足ではありません。その設定は外部から直接書き込めるテキスト設定ファイルではなく、インターフェースおよびバックエンドの保護されたストレージ内に存在するからです。

ステップ 1. Agent Canvas を起動し、Settings > LLM を開きます。初回起動時のウィザードで OpenHands 独自のプロバイダー設定が表示されますが、このステップはスキップ可能です。設定には後から簡単に戻れます。

ステップ 2. Add LLM Profile をクリックし、Advanced タブに切り替えます（Basic タブでは組み込みリスト内のプロバイダーとモデルしか選択できないためです）。

ステップ 3. 次の3つのフィールドに入力します：

ステップ 4. プロファイルを保存します。保存前、Canvas はバックエンドへのリクエストを通じて設定を検証します。キーが拒否された場合やモデルが利用不可の場合は保存されず、エラーメッセージが表示されます。

ステップ 5. 新しい会話を開始し、短いメッセージを送信してください。既存の会話は、開始時のモデルを引き続き使用します。

なぜ openai/ なのか。 LiteLLM はモデルのプレフィックスでプロバイダーを判別します。openai/ プレフィックスは「OpenAIのモデル」を意味するのではなく、「OpenAI Chat Completions プロトコルでサーバーと通信する」ことを意味します。最初のセグメントのみが削除されるため、ゲートウェイには正しい識別子 deepseek-ai/DeepSeek-V4-Flash-0731 が到達します。OpenHands のドキュメントでは、openai/qwen/qwen3.6-35b-a3b を例にして同じ仕組みが示されています。プレフィックスがないと、LiteLLM は LLM Provider NOT provided というメッセージを返し動作しません。

なぜ /v1 だけで終わるのか。 LiteLLM は公式の OpenAI クライアント経由でサーバーへアクセスし、クライアントが自動的に /chat/completions を末尾に付与します。そのため、アドレスは /v1 で終わる必要があります。サフィックスがないとリクエストは API に到達せず、余計な文字列があると存在しないパスへ送信されてしまいます。もう一つの Canvas の要件として、アドレスはブラウザからだけでなく、バックエンドからもアクセス可能である必要があります。ゲートウェイは公開された HTTPS アドレスであり、Docker コンテナからもホスト側と同じように見えます。host.docker.internal のような設定は、自分のマシン上のモデルを使用する場合にのみ必要です。

3つのモデルすべてにプロファイルを作成。 ネットワーク内の各モデルに対してプロファイルを1つずつ作成し、deepseek、glm、minimax などの短い名前を付けてください（ドキュメントには10プロファイルまでの制限が記載されています）。会話中にコンテキストを失うことなく、入力フィールドのプロファイル選択ボタンや /model glm コマンドで切り替え可能です。引数なしの /model でリストが表示されます。すべてのプロファイルにキーを入力する手間を省くには、Provider Connections ブロックに一度保存してください。これはローカルバックエンドで利用可能です。

Docker の旧インターフェース。 フィールドは同じです：Settings → LLM タブ → Advanced を有効化 → Custom Model、Base URL、API Key を入力 → Save Changes。

CLI は uv を使った1つのコマンドでインストールでき、初回起動時にモデル設定のウィザードが自動で開きます。後から設定に戻るには Ctrl+P → Settings です：

uv tool install openhands --python 3.12
openhands

スクリプトでは環境変数の方が便利です。重要な点：デフォルトでは CLI は環境変数を無視し、--override-with-envs フラグを付けたときだけ適用します。1回の実行限りで、何も保存されません：

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

同じセットはインターフェースなしでも動作します — CI やバッチタスク向けです：

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

ヘッドレスモードではエージェントは常に自動承認で動作するため、何でも許可できる場所 — 専用ディレクトリやコンテナ内で実行してください。--json フラグは出力を JSONL イベントストリームに変換し、パイプラインでの解析に便利です。まさにこの方法で、私たちは 2026年9月21日に CLI 1.16.0 でこの組み合わせを検証しました：CLI のヘッダーに Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731 と表示され、その後エージェントがファイルを読み込み、本質的な回答を返します。

CLI の保存済み設定は ~/.openhands/agent_settings.json にあります。モデルを変更するには llm ブロックの3つのフィールド — model、api_key、base_url — を編集します。ファイルをゼロから作るのは避けてください：初回起動のウィザードがそこに他のエージェント設定も書き込むからです。履歴圧縮もその1つで、これがないと長い会話はコンテキストウィンドウに突き当たります。

エージェントを自分のコードに組み込む場合、同じ3つの値は OpenHands SDK でも受け取ります：

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

ネットワークモデルの価格は一律であるため、選択肢はモデルの挙動に基づきます。自律型エージェントにとって重要な数値は2つあります。コンテキストウィンドウ：各ステップで履歴が再送信されるため、ウィンドウが長いほど、エージェントは損失なく長時間動作できます。応答上限（Output Limit）：エージェントが大きなファイルを一度に書き出すステップは、1回の応答に収まる必要があります。以下の表は、OpenHands CLI 1.16.0およびSDK 1.21.0を使用して、同一タスク（ファイルの読み取りとエラーの特定）を実行した際の結果です。

長期タスクのワークフローとして推奨されるのは、OpenHandsのドキュメントにある通り、計画立案用と実行用でモデルを使い分けることです。まずglmプロファイルで会話を開始し、ファイル修正を行わずにプランを作成するよう依頼します。次に/model deepseekと入力し、実行コマンドを出します。切り替え時も履歴、ファイル、タスクの状態は保持されます。3つ目のプロファイルとしてminimaxを保持しておくと、ラッシュアワーで他のモデルの容量が足りなくなった際の切り替え先として便利です。また、Settings > Applicationで会話タイトルの生成を割り当てることも可能です。

履歴の圧縮。 数十万トークンのウィンドウであっても、長時間のタスクでは有限です。OpenHandsには「コンデンサー」機能があり、古いイベントを要約することで、ドキュメントによると長時間の会話におけるレイテンシとトークン消費を抑えます。Agent CanvasではSettings > Condenserから設定可能で、今回のCLI実行では80イベントの閾値で自動的に有効化されました。

モデルの制限。 OpenHandsはコンテキストウィンドウと応答上限をLiteLLMの参照用データベースから取得しますが、そこにはGonkaネットワークの識別子が含まれていないため（LiteLLM 1.81で確認済み）、エージェントはこれらのモデルに対して独自の値を持ちません。しかし、動作には支障ありません。上記の表に基づき、ゲートウェイ自体が応答上限を適用するためです。制限を明示的に設定したい場合は、SDKではmax_input_tokensおよびmax_output_tokensフィールドを使用し、CanvasではAllタブからプロファイルの全フィールドにアクセスできます。デフォルトモデルの詳細については、DeepSeek V4 Flashの概要をご覧ください。

リクエストがゲートウェイを通過しているかどうかは、両側から確認できます。OpenHands側からは、新しい会話を開始し、「READMEを読んで、一文で要約して」のような短いタスクを与えます。エージェントがツールを呼び出して回答すれば成功です。ゲートウェイ側からは、管理画面の「使用量（Usage）」セクションを確認します。リクエストが「モデル別（By Model）」の内訳に表示され、「キー別（By Keys）」ブロックで最終リクエスト時間が更新されていれば正常です。空の場合は別のプロファイルで会話が行われている可能性があるため、どれがアクティブになっているか確認してください。

OpenHandsのドキュメントによると、429発生時の再試行回数と待機時間は LLM_NUM_RETRIES、 LLM_RETRY_MIN_WAIT、 LLM_RETRY_MAX_WAIT 変数で設定可能です。ドキュメントとSDKのデフォルト値は異なる場合があるため、実際の設定を確認してください。CLI 1.16.0の会話状態で、8秒から64秒の待機を伴う5回の再試行を確認しています。

JoinGonka Gateway経由のトークン単価は、入力100万トークンあたり $0.0069、出力100万トークンあたり $0.021 です。この価格はネットワーク上のすべてのモデルで共通であり、このページでライブソースから自動的に反映されます。

右列の概算は2026年9月の価格に基づいています。エージェント経済の仕組みについては、AIエージェント向けの最も安価なAPIに関する記事で詳しく解説しています。

消費制限。 OpenHandsは支出制限の設定を推奨していますが、当ゲートウェイには支払いモデル自体に制限が組み込まれています。残高はプリペイド方式であり、アカウント残高を超えてエージェントが消費することはありません。残高と日次消費額は管理画面で確認可能です。CIやバックグラウンド自動化には個別のキーを作成し、メインアカウントと消費を分けてください。日次制限付きのサブキーについては、Management Keysに関する記事を参照してください。

信頼境界。 npm経由で実行されるAgent Canvasは、ユーザーの権限で動作し、ファイルシステム全体にアクセスできます。信頼できないコードに対してはDocker版を使用してください。エージェントはマウントされたディレクトリのみを参照します。これはOpenHands自体の特性であり、モデルプロバイダーには依存しません。

チャット履歴の管理。 OpenHandsは会話履歴を自身の ~/.openhands に保持し、各ステップでモデルに送信しますが、ゲートウェイは履歴を保存しません。回答後、プロンプトやコードがゲートウェイ側に残ることはありません。

画像（インターフェースのスクリーンショットや図など）を含むタスクの場合は、visionモデル用のプロファイルを別途作成してください。Gonkaネットワークのモデルはテキストベースです。コード、コマンド、ファイルに関しては制限ではありません。