OpenHands CLI 完全ガイド

## 概要

OpenHands CLIは、AIパワードな開発エージェントをターミナルから直接利用できる強力なコマンドラインインターフェースです。WebUIを使わずに、コマンドラインでAIアシスタントと対話し、コード作成、バグ修正、リファクタリングなどの開発作業を効率化できます。

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

## 特徴

### 主要機能
- **リアルタイム対話**: ターミナル内でOpenHandsエージェントとリアルタイムで対話できます
- **自然言語タスク入力**: 日本語や英語で開発タスクを指示可能
- **インタラクティブコマンド**: 豊富な内蔵コマンドで効率的な操作
- **即座のフィードバック**: AIエージェントからの迅速な応答

### 開発者向け機能
- **コード生成**: プログラムの作成、修正、リファクタリング
- **バグ修正**: エラーの特定と修正提案
- **ファイルシステム操作**: プロジェクトファイルへの直接アクセス
- **コマンド実行**: ターミナルコマンドの実行
- **Web閲覧とAPI呼び出し**: 外部リソースの利用

## インストールと初期設定

### 前提条件
- **Python**: バージョン3.12以上（3.14は現在サポート外）
- **Docker**: ローカル環境での実行に必要
- **LLM API key**: OpenAI、Anthropic、その他のプロバイダー

### インストール方法

#### 1. Python環境での実行
```bash
uvx --python 3.12 --from openhands-ai openhands
```

#### 2. Docker環境での実行
```bash
# 環境変数の設定
export SANDBOX_VOLUMES="/path/to/your/workspace"
export LLM_MODEL="anthropic/claude-sonnet-4-20250514"
export LLM_API_KEY="your-api-key"

# Dockerコンテナでの起動
docker run -it \
  --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.44-nikolaik \
  -e SANDBOX_USER_ID=$(id -u) \
  -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
  -e LLM_API_KEY=$LLM_API_KEY \
  -e LLM_MODEL=$LLM_MODEL \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app-$(date +%Y%m%d%H%M%S) \
  docker.all-hands.dev/all-hands-ai/openhands:0.44 \
  python -m openhands.cli.main --override-cli-mode true
```

### 推奨モデル
Anthropic Claude Sonnet 4（anthropic/claude-sonnet-4-20250514）が最適ですが、多くの選択肢があります。

## 基本的な使い方

### 起動と初期画面
CLIを起動すると、歓迎メッセージとプロンプト（`>`）が表示されます。最初のタスクを入力するか、コマンドを入力して会話を開始します。

### 基本操作の流れ
1. **タスクの入力**: 自然言語でやりたいことを入力
2. **AIの応答**: エージェントが作業を実行し、結果を表示
3. **反復改善**: フィードバックに基づいて修正や改善を指示

### 使用例
```
> hello.shという簡単なスクリプトを作成して実行してください

> hello.shを修正して、第一引数として名前を受け取れるようにして、デフォルトは"world"にしてください

> hello.shをRubyスクリプトに変換して実行してください
```

## 利用可能なコマンド

### 基本コマンド一覧

| コマンド | 説明 |
|---------|------|
| `/help` | 利用可能なコマンドとその説明を表示 |
| `/exit` | アプリケーションを終了 |
| `/init` | 新しいリポジトリの初期化（エージェント用） |
| `/status` | 会話の詳細と使用状況メトリクスを表示 |
| `/new` | 新しい会話を開始 |
| `/settings` | LLMとエージェントの設定を表示・変更 |
| `/resume` | 一時停止したエージェントを再開 |

### 設定管理（/settings）
`/settings`コマンドを使用して、モデル、APIキー、エージェント、その他の設定を対話的に更新できます。プロンプトに従って操作します。

#### 基本設定
- モデル/プロバイダーの選択
- APIキーの入力

#### 高度な設定
- カスタムエンドポイントの設定
- 確認モードの有効/無効
- メモリ圧縮の設定

### プロジェクト初期化（/init）
`/init`コマンドは、プロジェクトの詳細と構造を含む`.openhands/microagents/repo.md`ファイルを作成し、エージェントがプロジェクトを理解できるようにします。新しいコードベースにエージェントを導入する際に使用します。

### エージェントの一時停止と再開
- **一時停止**: `Ctrl-P`を押す
- **再開**: `/resume`コマンドを入力

## 実践的な使用例

### 1. Hello Worldから始める
```
> 簡単なhello worldプログラムを作成してください
```
シンプルな「hello world」の例から始めましょう。見た目より難しいかもしれません！エージェントはスクリプトを作成し、適切な権限を設定し、実行して出力を確認します。

### 2. 既存コードベースへの機能追加
```
> このリポジトリにコードをリントするGitHub Actionを追加してください

> ./backend/api/routes.jsを修正して、すべてのタスクのリストを返す新しいルートを追加してください
```

### 3. バグ修正
```
> /subscribeエンドポイントのemailフィールドが.ioドメインを拒否している問題を修正してください

> ./app.pyのsearch_widgets関数が大文字小文字を区別している問題を修正してください
```

### 4. テスト駆動開発
```
> hello関数が空文字列でクラッシュするバグを再現するテストを書いて、コードを修正してテストが通るようにしてください
```

## ベストプラクティス

### タスクの効果的な指示方法
OpenHandsはほぼすべてのコーディングタスクを支援できますが、最良の結果を得るには練習が必要です。以下のヒントを心に留めておいてください：

1. **小さなタスクに分割**: 複雑な作業は小さな単位に分ける
2. **具体的な指示**: 曖昧な表現を避け、明確に要求を伝える
3. **十分なコンテキスト**: 関連情報を事前に提供
4. **頻繁なコミット**: 作業の進捗を定期的に保存

### 効果的なワークフロー
1. **シンプルな開始**: 基本的な機能から始める
2. **反復改善**: 小さな改善を重ねる
3. **段階的な複雑化**: 徐々に機能を拡張

### コンテキストの提供
一部のタスクには、より多くのコンテキストが必要です。OpenHandsは`ls`や`grep`などのコマンドを使用して検索できますが、事前にコンテキストを提供することで処理時間を短縮し、トークン使用量を削減できます。

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

### よくある問題と解決策

#### 権限エラー
- ワークスペースディレクトリが信頼できることを確認
- 必要な環境変数が正しく設定されていることを確認

#### 確認モードでの操作
確認モードが有効になっている場合、CLIは重要な操作の前にプロンプトを表示します。最初の確認プロンプトで`a`または`always`と入力すると、現在の会話の後続のアクションを自動的に確認できます。

#### 新しい会話の開始
やり直したい場合は、`/new`を使用してCLIを再起動することなく新しい会話を開始できます。

### 設定ファイル
設定は`config.toml`ファイルでも管理可能です。

## 高度な機能

### ヘッドレスモードとの違い

このモードは、非対話的でスクリプト作成により適したヘッドレスモードとは異なります。CLIモードは対話型、ヘッドレスモードはスクリプト向けです。

### GitHub Actionとの統合

OpenHandsはGitHub Actionとしても利用でき、タグ付きissueに対して自動的に作業を実行できます。

https://docs.all-hands.dev/usage/how-to/github-action

## まとめ

OpenHands CLIは、開発者の生産性を大幅に向上させる強力なツールです。自然言語でタスクを指示し、AIエージェントがコード作成からデバッグまで幅広い作業を支援します。効果的に利用するためには、明確で具体的な指示と、適切なコンテキストの提供が重要です。

## 関連リンク

- [OpenHands公式ドキュメント](https://docs.all-hands.dev/)
- [GitHub リポジトリ](https://github.com/All-Hands-AI/OpenHands)
- [OpenHands Cloud](https://app.all-hands.dev)
- [コミュニティSlack](https://join.slack.com/t/openhandsai/shared_invite/)