OpenHands CLI のセットアップ：API Key、Base URL、モデル

環境変数を使って OpenHands CLI を BetterToken に接続します。GPT モデルを使った macOS のテストでは、OpenHands CLI 1.16.0 が /v1/responses 経由でヘッドレスのテキストリクエストとファイル読み取りのツール呼び出しを完了しました。

主な設定

項目	値
API Key	LLM_API_KEY に設定する BetterToken API Key
Base URL	LLM_BASE_URL に設定する https://bettertoken.ai/v1
モデル	LLM_MODEL に設定する openai/YOUR_MODEL_ID
設定の上書き	--override-with-envs

前提条件

• uv と Python 3.12 以降
• BetterToken API Key：登録して取得
• モデル広場からコピーした Model ID

インストール

公式インストールガイドに記載されたパッケージ名とコマンドを使います。

uv tool install openhands --python 3.12
openhands --version

手動設定

YOUR_API_KEY と YOUR_MODEL_ID を置き換えます。LLM_MODEL の openai/ プレフィックスは残してください。

export LLM_MODEL="openai/YOUR_MODEL_ID"
export LLM_API_KEY="YOUR_API_KEY"
export LLM_BASE_URL="https://bettertoken.ai/v1"

OpenHands の起動時に --override-with-envs を指定すると、これらの変数が保存済みの設定を上書きします。上書きはその実行中だけ有効で、設定には保存されません。

接続の確認

openhands --headless --json --override-with-envs -t "Reply with only: OK"

JSONL 出力の最終回答が OK であることを確認します。ファイルアクセスを個別に確認するには、プロジェクトから実行して OpenHands に既知のファイルを読み取るよう依頼し、ツール結果と最終回答の両方を確認してください。

モデルの切り替え

LLM_MODEL を openai/ に続けて別の正確な Model ID に変更します。--override-with-envs を指定して再実行します。

よくあるエラー

症状	確認事項
環境設定が反映されない	コマンドに --override-with-envs を含めます。
認証に失敗する	OpenHands を実行しているターミナルで LLM_API_KEY を確認します。
エンドポイントが違う	LLM_BASE_URL に https://bettertoken.ai/v1 を使い、/responses や /chat/completions を付けないでください。
モデルが見つからない	openai/ プレフィックスを残し、LLM_MODEL の残りの値をモデル広場から正確にコピーします。

関連ガイド

• 対応ツールを比較
• API エラーとレート制限
• OpenHands CLI コマンドリファレンス

技術情報

OpenHands CLI 1.16.0 はテストしたテキストとファイル読み取りのリクエストを /v1/responses に送信しました。Base URL は /v1 のままにしてください。リクエストパスはクライアントが追加します。