OpenHands CLI は、設定したモデルプロバイダーを使用して変更を計画し、ファイルを編集し、コマンドを実行できるオープンソースの AI コーディングエージェント向けのターミナルインターフェースです。

macOS および Linux に OpenHands CLI をインストールする方法

uv を使用して Python 3.12 以上でインストールするか、公式インストールスクリプトを使用し、その後 openhands コマンドを実行してプロンプトに従い、モデルプロバイダーと API キーを設定してください。

OpenHands モデルを構成する環境変数

LLM_API_KEY でプロバイダーのキーを設定し、LLM_MODEL および LLM_BASE_URL を使用することで、 override with envs オプションを指定して openhands を実行する際に保存された設定を上書きできます。

CI において OpenHands をヘッドレスモードで実行する方法は何ですか？

headless フラグを指定して openhands を実行し、タスクまたはファイルを指定します。さらにオプションで JSON 出力を有効化し、ログ記録や自動化用に機械可読なイベントをストリーミング出力できます。

CLI から OpenHands の会話を再開する方法は？

resume フラグを指定して openhands を実行すると直近のセッションがリスト表示され、ID を指定して再開するか、last フラグを指定して最も最近の会話継続可能です。

OpenHands コーディングアシスタントのクイックスタート：インストール、CLI フラグ、例

OpenHands CLI を数分でクイックスタート

OpenHands は、AI 駆動のソフトウェア開発エージェントのためのオープンソースでモデル非依存のプラットフォームです。単なる自動補完ツールではなく、エージェントがコーディングパートナーのように振る舞うことを可能にします。

ファイルの操作、サンドボックス環境でのコマンド実行、必要に応じて Web ブラウジングを行うことができます。

このクイックスタートではOpenHands CLIに焦点を当てています。これはターミナルから最も早く生産性を発揮できる方法であり、スクリプトや CI 実行などの自動化パターンにきれいにマッピングされるからです。より広い視点については、AI 開発者ツール：AI 活用開発の完全ガイドをご覧ください。

openhands text user interface

OpenHands の概要と特異点

AI コーディングアシスタントは一般的に、言語モデルを使用してコードの生成や編集を支援します。OpenHands は、このアイデアを「エージェント型」ワークフローに拡張します。システムは反復的に計画を立て、アクション（ファイルの作成やテスト実行など）を実行し、結果を観察し、タスクが完了するまで継続します。

OpenHands は以前OpenDevinと呼ばれていたプロジェクトとしても広く知られており、CLI、ローカル Web GUI、クラウドホスト UI、SDK など、複数の使用方法を備えたコミュニティ主導のプラットフォームへと成長しました。

エンジニアリングの観点から、最大の違い点は、OpenHands が実行環境（サンドボックス）を基盤に構築されていることです。これにより、エージェントはテキストを生成するだけでなく、安全にコマンドやツールを実行できます。OpenHands の論文では、現実的な開発者のようなインタラクションパターンを支援するために、シェルとブラウジング機能を備えた Docker によるサンドボックス化されたランタイム環境について説明しています。

OpenHands CLI のインストール

OpenHands は複数のインストール方法をサポートしています。多くの開発者にとって、まずはローカル CLI のインストール（高速な反復）から始め、後で実行の厳格な分離が必要になった際に Docker ベースのワークフローをオプションで追加するのが最適です。

uv を使用してインストール

現在の OpenHands CLI ドキュメントでは、uvを使用したインストールを推奨しており、**Python 3.12+**が必要です。

uv tool install openhands --python 3.12
openhands

アップグレードも同様に簡単です。

uv tool upgrade openhands --python 3.12

実際の運用において uv が重要な理由: uv は、現在のプロジェクト環境からのより良い分離を提供し、デフォルトの MCP サーバーに必要です。

スタンダローンの CLI バイナリをインストールする

「1 コマンド」でインストールするフローを望む場合、OpenHands はインストールスクリプトを提供しています。

curl -fsSL https://install.openhands.dev/install.sh | sh
openhands

macOS では、実行する前にプライバシーとセキュリティ設定でバイナリを明示的に許可する必要がある場合があります。

分離のために Docker で実行する

インストールを限定して行いたい場合、CLI ドキュメントには Docker ベースのフローも示されています。このアプローチでは、OpenHands がアクセスするディレクトリをマウントし、マウントされたワークスペースに root 所有のファイルを作成しないようユーザー ID を渡すことに依存しています。

export SANDBOX_VOLUMES="$PWD:/workspace"

docker run -it \
  --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.12.0-python \
  -e SANDBOX_USER_ID=$(id -u) \
  -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/root/.openhands \
  --add-host host.docker.internal:host-gateway \
  --name openhands-cli-$(date +%Y%m%d%H%M%S) \
  python:3.12-slim \
  bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands"

初回実行の設定と設定ファイルの保存場所

初回実行時、CLI は必須の LLM 設定の構成をガイドし、それらを将来のセッションのために保存します。 CLI ドキュメントでは、設定は ~/.openhands/settings.json 下に保存され、会話履歴は ~/.openhands/conversations に保存されると明記されていますが、私が最近 OpenHands をインストールした際の設定は ~/.openhands/agent_settings.json に保存されたため、ドキュメントは少し正確ではないようです。

より深い構成とツール統合については、OpenHands は追加の設定ファイルもドキュメント化しています。例えば、~/.openhands/agent_settings.json（エージェントと LLM の設定）、~/.openhands/cli_config.json（CLI の設定）、~/.openhands/mcp.json（MCP サーバー）などです。

ローカル Ollama と llama.cpp を使用した OpenHands の設定

OpenHands は、Ollama、LocalAI、llama.cpp などの OpenAI 互換のローカルバックエンドであれば何でも動作します。使用するものを決定できない場合は、Ollama vs vLLM vs LM Studio: ローカルで LLM を実行する最善の方法を比較してください。

OpenHands を初めて起動すると設定ページが表示されます。すでにこの初回ステップを過ぎている場合、/settings を入力し、その後 ctrl+j を押すことでこのページを再度開くことができます。次に、

Custom Model フィールドに: ollama/devstral-small-2:24b、または他の好きなローカルモデルを入力し、
Base Url フィールドに: http://localhost:11434 を入力します。

openhands settings ollama mistral

Ollama コマンドの簡易参照については、Ollama CLI チートシート：serve、run、ps、およびモデル管理をご覧ください。

OpenHands の設定ファイルを手動で編集したい場合（設定ページの見た目が好きでない場合など）は、以下を実行します。

nano ~/.openhands/agent_settings.json

または、より GUI 的なエディターを好む場合は:

gedit GUI ~/.openhands/agent_settings.json

llm プロパティは2 箇所に存在するため、これらを ollama への設定とするために以下のように設定しました。

"llm":{"model":"ollama/devstral-small-2:24b","api_key":"aaa","base_url":"http://localhost:11434"

OpenHands をローカル llama.cpp インスタンスに接続する場合も同様で、2 箇所に設定します。

"llm":{"model":"openai/devstral-small-2:24b","api_key":"aaa","base_url":"http://localhost:11434"

llama.cpp に接続するために、以下を設定しました。

“model”:“openai/Qwen3.5-35B-A3B-UD-IQ3_S.gguf”
“base_url”:“http://localhost:8080/v1”

そして、llama.cpp を以下のコマンドで起動しました（フラグの詳細については llama.cpp クイックスタート：CLI と Server を参照）:

./llama.cpp/llama-server \
    -m /mnt/ggufs/Qwen3.5-35B-A3B-UD-IQ3_S.gguf \
    --ctx-size 70000 \
    -ngl 40 \
    --temp 0.6 \
    --top-p 0.95 \
    --top-k 20 \
    --min-p 0.00

OpenHands は私のテストリクエスト create for me a cli tool in Go, that would call bing and other search engines' indexnow endpoints to notify about changes on my website に問題なく接続し、ソースコード、実行ファイル、README.md を含む形で成功しました。

実際の運用における OpenHands CLI の仕組み

デフォルトの openhands コマンドは、インタラクティブなターミナル体験を起動します。OpenHands はコマンドパレットとセッション内のコマンドを提供するため、エージェントが作業している間も素早く指示を出すことができます。

早期に覚えておくべき有用なインタラクティブ操作には、コマンドパレットのオープン、エージェントの一時停止、アプリの終了があります。

Ctrl+P: コマンドパレットを開きます。
Esc: 実行中のエージェントを一時停止します。
Ctrl+Q または /exit: CLI から退出します。

CLI 内では、OpenHands は /help、/new、/condense などのスラッシュプレフィックスコマンドもサポートしています。これにより、再起動せずに長い会話を管理する際に有益です。

OpenHands はターミナル UI だけでなく、さまざまな開発者ワークフローに適合する複数のインターフェースを CLI に含んでいます。

ヘッドレスモード: 自動化と CI 用。
Web インターフェース: ブラウザで CLI 体験を実行。
GUI サーバー: Docker を経由して起動される完全なローカル Web アプリケーション用。
IDE 統合: ACP を経由したエディターベースのワークフロー用。

実際に使用する主なコマンドラインパラメータ

大まかな形状は以下の通りです。

openhands [OPTIONS] [COMMAND]

これには、グローバルオプション（タスク、再開、ヘッドレスなど）とサブコマンド（serve、web、cloud、acp、mcp、login、logout）が含まれます。

日常的な作業のためのコアオプション

最も一般的に使用されるグローバルオプションは以下の通りです。

-t, --task: 会話に初期タスクをシードするために使用。
-f, --file: ファイルからシードするために使用。バージョン管理にコミットされたタスクを扱う際に便利です。
--resume [ID] および --last: 以前のランを継続するために使用。
--headless: インタラクティブな実行を伴わない（自動化時などに使用）。
--json: 機械解析用ヘッドレスモードで JSONL 出力をストリーミング。

安全性と承認も第一級に扱われます。

--always-approve: プロンプトなしにアクションを自動承認。
--llm-approve: LLM ベースのセキュリティ分析器を使用してアクションを承認。

環境変数によるモデルとプロバイダーの設定

OpenHands はモデル設定のために環境変数をサポートしています。

LLM_API_KEY: プロバイダーの API キーを設定。
LLM_MODEL と LLM_BASE_URL: openhands --override-with-envs を実行する際にオーバーライドとして適用可能。

オーバーライドフローの例:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="your-api-key"
openhands --override-with-envs

OpenHands は明示的に、--override-with-envs で適用されたオーバーライドは永続化されないと注記しています。

知っておくべきサブコマンド

最初からすべてのサブコマンドが必要ではありませんが、これらはすぐに頻繁に使われるものです。

openhands serve: Docker を使用して完全なGUI サーバーを起動します。通常 http://localhost:3000 でアクセス可能で、--mount-cwd や --gpu などのオプションがあります。
openhands web: CLI をブラウザからアクセス可能な Web アプリケーションとして起動します。デフォルトはポート 12000。
openhands login: OpenHands Cloud と認証し、設定を取得します。
openhands cloud: CLI から OpenHands Cloud で新しい会話を作成します。

すぐに使えるコピー＆ペースト例

OpenHands から価値を得る最も速い方法は、それをタスク駆動型のコーディングエージェントとして扱うことです。タスクは簡潔に、ファイル名を含め、必要に応じてテストや検証を求めてください。

初期タスク付きのインタラクティブコーディングセッションを開始する

これは「デフォルトの開発者体験」であり、最も一般的なパターンの一つです。

openhands -t "Fix the bug in auth.py and add a regression test"

OpenHands CLI ドキュメントでは、まさにこの -t を使用してセッションをブートストラップするアイデアを示しています。

ファイルからタスクをシードする

ファイルを繰り返す、チームレビュー、CI での再利用を目的とする際に役立ちます。

cat > task.txt << 'EOF'
Refactor the database connection module.
Add unit tests and ensure the test suite passes.
EOF

openhands -f task.txt

CLI クイックスタートでは、-f を使用してタスクファイルから開始することを明示的にサポートしています。

CI や自動化のためにヘッドレスモードで実行する

ヘッドレスモードはインタラクティブ UI なく実行され、CI パイプラインや自動化スクリプト向けに設計されています。

openhands --headless -t "Add unit tests for auth.py and run them"

ここでの 2 つの重要なエンジニアリング現実:

ヘッドレスモードには --task または --file が必要です。
ヘッドレスモードは常に自動承認モードで動作し、変更できません。また、--llm-approve はヘッドレスモードでは利用できません。強力な自動化として扱い、制御された環境で実行してください。

ログ解析や他のツールとの統合のために、JSONL 出力を有効化します。

openhands --headless --json -t "Create a simple Flask app with healthcheck endpoint" > openhands-output.jsonl

OpenHands は --json をヘッドレスモードでの JSONL イベントストリーミングとしてドキュメント化し、出力をファイルにリダイレクトする例を示しています。

コンテキストを失わずに作業を再開する

OpenHands を非自明な変更のために使い始めると、再開は重要です。

最近の会話をリスト表示:

openhands --resume

最も最近のものを再開:

openhands --resume --last

または特定の会話 ID を再開:

openhands --resume abc123def456

これらのフローは CLI コマンド参照と「会話の再開」ガイドでドキュメント化されています。

必要な時にブラウザで CLI を実行する

openhands web は Web アクセス可能な CLI を起動します（デフォルトポート 12000）。

openhands web

ローカルで実行している場合、localhost へのバインドのみが合理的なデフォルトです。

openhands web --host 127.0.0.1 --port 12000

OpenHands は、Web インターフェスをネットワークに公開するには適切なセキュリティ対策が必要であると警告しています。なぜなら、OpenHands の機能に完全なアクセスを提供するからです。

セキュリティ、トラブルシューティング、および注意点

OpenHands CLI において最も重要な安全性のレバーは承認です。

インタラクティブ CLI は、機密アクションの前に確認をプロンプトでき、セッション内で確認設定を構成できます。
--always-approve は摩擦を取り除きますが、安全対策も取り除きます。
--llm-approve は承認のために LLM ベースの分析器を追加します。
ヘッドレスモードは常に承認するため、制御された環境での自動化に限定してください。

ローカルコードを扱う際には、明示的で最小権限のアクセスパターンを優先してください。

GUI サーバーの場合、openhands serve --mount-cwd は現在のディレクトリを /workspace にマウントし、エージェントがプロジェクトファイルを读取および修正できるようにします。
Docker ベースの CLI 実行の場合、SANDBOX_VOLUMES を使用して OpenHands がアクセスできるディレクトリを正確に定義します。

古い OpenHands 状態ディレクトリがある場合、OpenHands はローカルセットアップドキュメントとトラブルシューティングガイドラインで、~/.openhands-state から ~/.openhands への移行パスについて注記しています。

最後に、OpenHands をスクリプトに統合する場合、終了コードは以下のようにドキュメント化されています。

0: 成功
1: エラーまたはタスク失敗
2: 無効な引数

私の OpenHands 利用体験

私にとって OpenHands はうまく機能しましたが、常にではありませんでした… Ollama でホストされた Devstral-Small-2 と動作させるように試みたところ、常に停止していました。

OpenHands with Ollama-hosted Devstral-Small-2

しかし、ローカルでホストされた llama.cpp Qwen 3.5 35b とはうまく機能しました。現時点では、私にとって OpenCode ははるかに信頼性が高いです。