OpenHands

Settings → LLM → Advancedには3つのフィールド — Custom Model、Base URL、API Key — があり、モデルIDにはopenai/プレフィックスを付け、ベースURLには/v1を残します。

# Settings → LLM → Advanced  (toggle "Advanced" on first)
Custom Model   openai/claude-sonnet-5
Base URL       https://api.kunavo.com/v1
API Key        sk-kn-...

# The "openai/" prefix is the provider, not a vendor: it tells OpenHands to
# speak the OpenAI Chat Completions protocol to the Base URL above. The model
# id after the slash is Kunavo's, and resolves at Kunavo.
#
# Keep the /v1. It belongs to the openai/ prefix — a litellm_proxy/ model
# takes the bare origin instead, which is the opposite convention.

手順

1. /app/keys でキーを作成してコピーします。キーは一度だけ表示されます。
2. Settings → LLMを開き、Advancedの切り替えをオンにします。3つのフィールドがCustom Model、Base URL、API Keyの順に表示されます。
3. モデルIDにはプレフィックスを付けて入力します。openai/claude-sonnet-5であり、claude-sonnet-5ではありません。Kunavoが提供するIDはGET /v1/modelsが返すものです。これは、カスタムIDの取得元としてOpenHandsの公式ドキュメントが案内している一覧と同じです。
4. Base URLにhttps://api.kunavo.com/v1を貼り付け、API Keyにキーを入力してから、Save Changesをクリックします。OpenHandsのドキュメントによると、ローカルプロファイルを保存するときは、まずバックエンドに対して設定を検証し、失敗した場合は保存を阻止します。そのため、ここでエラーが表示された場合は見た目だけの問題ではなく、実際に拒否されています。
5. ブラウザーから何にアクセスできるかではなく、バックエンドから何にアクセスできるかを確認してください。ベースURLはAgent Serverの実行マシンから名前解決できる必要があります。OpenHandsのドキュメントには、Agent CanvasがDockerで動作している場合、127.0.0.1はコンテナだと明記されています。Kunavoのような公開エンドポイントは簡単なケースですが、その前段に企業プロキシがある場合は異なります。
6. 新しい会話を開始し、ファイルを読み取って編集するタスクを与えます。OpenHandsによると、保存したLLMは新しい会話に適用され、既存の会話で使うには先に再起動する必要があります。また、ツールを使う実行を試すことで、挨拶だけの場合よりもこの組み合わせを詳しく確認できます。

OpenHandsのLanguage Model（LLM）設定ページで2026年9月21日に確認しました。サードパーティの設定は変更されます。ここに記載されたフィールド名が表示内容と一致しなくなった場合は、このページではなく、そのページを正しい情報源としてください。

クライアントをデバッグする前に確認すること

1回のリクエストで、失敗の原因がエンドポイント、キー、設定ファイルのどれかを特定できます。これがJSONを返すなら、同じベースURLとキーがOpenHandsで機能します。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

フィールドに入力するモデルID

すべてのテキストモデルにはモデルIDでアクセスできます。現在の一覧はGET /v1/models、価格付きのカタログはモデルページにあります。料金は100万トークンあたりのUSDで、入力 / 出力の順です。

デバッグ前に把握しておきたい3つの境界

OpenHandsには単一プロセスのCLIより多くの構成要素があり、そのうち2つはLLMエンドポイントに見えても別のものです。以下は、上記の日付時点で確認したOpenHands公式ドキュメントに基づいています。

1. サンドボックスはモデルではありません。OpenHandsはエージェントサーバーのサンドボックス内で作業を実行し、ネットワーク経由でモデルを呼び出します。これらは別々の機能であり、認証情報も別です。ここで設定するキーはモデル呼び出しに使われます。サンドボックスから何にアクセスできるかには関係なく、サンドボックスのネットワーク問題が認証エラーとして表示されることもありません。
2. ACPエージェントは完全に別枠です。Agent Canvasは、ACPエージェントとしてClaude Code、Codex、またはGemini CLIにタスクを委任できます。「Configure a Model」ページには、これらは「独自のモデルアクセスを管理する」と記載されています。そのため、LLMプロファイルを設定しても、それらのサブプロセスの接続先は変わりません。キーにリクエストが来る想定なのに何も記録されない場合は、実際にどのエージェントが動作しているか確認してください。OpenHandsとClaude Codeの比較では、この違いと、それを決める認証情報の優先順位について説明しています。
3. プロファイルと上限の10件。保存した設定はLLMプロファイルになり、最後に保存したプロファイルが新しい会話で有効になります。コンテキストを失わず会話の途中でプロファイルを切り替えられるため、1つのキーで低コストのモデルIDと高コストのモデルIDを使い分けられます。ドキュメントでは、アカウントあたりのプロファイル数は最大10件とされています。Provider Connectionにはプロバイダー、APIキー、オプションのベースURLを保存でき、複数のプロファイルで使い回せます。同じページによると、このパネルはローカルのagent-serverバックエンドでは使用でき、OpenHands Cloudバックエンドでは非表示になります。