OpenHands CLIでカスタムOpenAI互換モデル（Litellm）を設定する方法

OpenHandsでは、OpenAI、Anthropic、その他のLLMプロバイダーだけでなく、カスタムのOpenAI互換APIエンドポイントも使用できます。この記事では、CLIの`/settings`コマンドを使用してLitellmのカスタムモデルを設定する手順を詳しく説明します。

https://x.com/hAru_mAki_ch/status/1936053115721334995

## 前提条件

- Python 3.12以上がインストールされていること
- OpenAI互換のAPIエンドポイントが利用可能であること（Litellm）
- APIキーまたは認証情報があること

## OpenHandsのインストールと起動

https://hamaruki.com/openhands-cli-guide/

### 1. OpenHandsのインストール

```bash
# pipを使用してインストール
pip install openhands-ai

# または、uvxを使用（推奨）
uvx --python 3.12 --from openhands-ai openhands
```

### 2. OpenHandsの起動

```bash
# 通常の起動
openhands

# または、uvxを使用
uvx --python 3.12 --from openhands-ai openhands
```

起動すると、以下のようなプロンプトが表示されます：

```
Welcome to OpenHands CLI!
Type '/help' for available commands.
>
```

## カスタムモデルの設定手順

### 1. 設定メニューにアクセス

プロンプトで`/settings`コマンドを入力します：

```bash
> /settings
```

### 2. 基本設定の入力

設定メニューが表示されたら、以下の情報を入力します：

#### モデル名の設定
```
Enter your LLM Model name: claude-sonnet-4-20250514
```

**重要なポイント：**
- OpenAI互換APIの場合、プロバイダー名/モデル名の形式で入力
- 例：`claude-sonnet-4-20250514`、`openai/gpt-4`など

#### APIキーの設定
```
Enter your API key: sk-xxxxx
```

### 3. 詳細設定（Advanced Options）

基本設定が完了したら、詳細設定に進みます：

```
Do you want to configure advanced options? (y/n): y
```

#### Base URLの設定
```
Enter LLM Base URL (leave blank for default): http://192.168.0.121:4001
```

**設定例：**
- ローカルサーバー: `http://localhost:8000/v1`
- カスタムエンドポイント(Litellm): `http://192.168.0.121:4001`
- LM Studio: `http://localhost:1234/v1`

#### その他の詳細設定

必要に応じて以下の設定も調整できます：

- **Temperature**: モデルの創造性を制御（0.0-1.0）
- **Top P**: 応答の多様性を制御
- **Max Tokens**: 最大出力トークン数
- **Timeout**: APIリクエストのタイムアウト

### 4. 設定の確認

設定が完了したら、再度`/settings`コマンドで設定内容を確認できます：

```bash
> /settings
Current settings:
- Model: claude-sonnet-4-20250514
- API Key: sk-***************************cg (masked)
- Base URL: http://192.168.0.121:4001
- Agent: CodeActAgent
- Confirmation Mode: true
```

## 設定例集

### 例1: LM Studioでローカルモデルを使用

```bash
> /settings
Enter your LLM Model name: lm_studio/llama-2-7b-chat
Enter your API key: dummy
Do you want to configure advanced options? (y/n): y
Enter LLM Base URL: http://localhost:1234/v1
```

### 例2: Ollamaサーバーを使用

```bash
> /settings
Enter your LLM Model name: ollama/codellama
Enter your API key: dummy
Do you want to configure advanced options? (y/n): y
Enter LLM Base URL: http://localhost:11434/v1
```

### 例3: カスタムAPIプロキシを使用

```bash
> /settings
Enter your LLM Model name: claude-sonnet-4-20250514
Enter your API key: sk-your-api-key
Do you want to configure advanced options? (y/n): y
Enter LLM Base URL: http://your-proxy-server.com:4001
```

## トラブルシューティング

### 接続エラーの対処法

**問題**: APIエンドポイントに接続できない
```
Error: Connection failed to http://192.168.0.121:4001
```

**解決方法**：
1. Base URLが正しいことを確認
2. APIサーバーが起動していることを確認
3. ファイアウォール設定を確認
4. `/settings`で設定を再確認

### 認証エラーの対処法

**問題**: APIキーが無効
```
Error: 401 Unauthorized - Invalid API key
```

**解決方法**：
1. APIキーが正しいことを確認
2. APIキーの有効期限を確認
3. `/settings`でAPIキーを再設定

### モデル名エラーの対処法

**問題**: モデルが見つからない
```
Error: Model 'custom/model' not found
```

**解決方法**：
1. モデル名が正しいことを確認
2. APIサーバーでモデルが利用可能か確認
3. プロバイダー名/モデル名の形式を確認

## 設定の永続化

設定は以下の場所に自動保存されます：

```bash
# 設定ファイルの場所
~/.openhands/config.toml
```

設定ファイルの内容例：
```toml
[llm]
model = "claude-sonnet-4-20250514"
api_key = "sk-xxxxx"
base_url = "http://192.168.0.121:4001"
temperature = 0.0
```

## 便利なコマンド

### 設定のリセット
```bash
> /new
# 新しい会話を開始（設定は保持）
```

### ヘルプの表示
```bash
> /help
Available commands:
/help    - Show this help message
/settings - Configure LLM settings
/new     - Start a new conversation
/exit    - Exit the application
```

### 設定の確認
```bash
> /status
Conversation ID: abc123
Model: claude-sonnet-4-20250514
Total messages: 5
```

## まとめ

OpenHands CLIの`/settings`コマンドを使用することで、簡単にカスタムOpenAI互換モデルを設定できます。主要なポイント：

1. **モデル名**: プロバイダー/モデル形式で指定
2. **Base URL**: カスタムエンドポイントのURLを指定
3. **APIキー**: 認証に必要なキーを設定
4. **設定は永続化**: 次回起動時も設定が保持される

この方法により、OpenAI、Anthropic以外のカスタムモデルも柔軟に利用できるようになります。