OpenHands CLI 1.16.0は、オープンソースのコディングエージェントであるOpenHands用のターミナルパッケージです。設定したモデルプロバイダーを使用して、変更の計画立案、ファイルの編集、コマンドの実行を行うことができます。OpenHands-CLIのデフォルトブランチにあるREADMEでは、新規インストール時にAgent Canvasを指向しています。

macOSまたはLinuxでOpenHands CLIをインストールするにはどうすればよいですか

公開されているパッケージには、Python 3.12（PyPI 制約は ==3.12.* ）および uv 0.11.6 以降が必要です。 uv tool install openhands --python 3.12 を実行するか、install.openhands.dev のインストールスクリプトを使用してください。Windows の場合、CLI ドキュメントではこれらのコマンドを WSL 内で実行するよう指示しています。

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

LLM_API_KEY、LLM_MODEL、およびLLM_BASE_URL は、–override-with-envs オプションを指定しない限り無視されます。この方法で適用された上書き設定は、agent_settings.json へ書き戻されません。

CIでOpenHandsをヘッドレスモードで実行するにはどうすればよいですか

openhands --headless を --task または --file とともに実行してください。ヘッドレスモードではアクションが常に承認され、 --llm-approve は利用できません。JSONLイベントのストリーミングには --json を追加してください。

CLIからOpenHandsの会話を再開するには、どうすればよいですか？

「openhands –resume」を実行すると最近のセッションの一覧が表示されます。「openhands –resume CONVERSATION_ID」を実行すると特定のIDを再開でき、「openhands –resume –last」を実行すると最新の会話を再開できます。

OpenHandsのターミナルUIに取って代わったもの

Agent Canvasは、プロジェクトのドキュメントに現在記載されているブラウザ操作インターフェースです。 npx @openhands/agent-canvas （Node.js 24以降、およびuvが必要）で起動します。 http://localhost:8000 でリッスンします。 openhands serve は引き続きポート3000でレガシーGUIを起動しますが、Agent Canvasは起動しません。

OpenHands CLI クイックスタート：インストール、フラグ、ヘッドレスモード

CLIインストール、フラグ、ヘッドレス、ローカルモデル

OpenHands は、サンドボックス内でファイルを編集し、コマンドを実行するオープンソースのコーディングエージェントです。本CLIのクイックスタートは、2026年10月26日にパッケージバージョン 1.16.0 に対して検証済みです。

PyPI に公開されているパッケージ openhands のバージョンは 1.16.0 で、2026年5月8日にアップロードされ、openhands-sdk==1.21.0 が固定されています。そのタグの README には、Python 3.12 および uv 0.11.6 以降が必須と記載されています。OpenHands-CLI リポジトリのデフォルトブランチの README には、そのリポジトリはもうアクティブにメンテナンスされていない旨が記載されており、新規インストールには Agent Canvas の利用を促しています。ヘッドレスモードおよび openhands acp は、なお 1.16.0 のコマンドセットの一部として残っています。

openhands text user interface

AI 開発者ツールガイドでは、当サイトの他のターミナルエージェントを追跡しています。このページでは、OpenHands CLI に特化しています: インストール、設定ファイル、ローカルモデルの URL、そしてスクリプトが実際にパスするフラグについてです。

CLI とは何か

AI コーディングアシスタントは通常、プロンプトからコードを生成または編集します。OpenHands はこれをエージェントループへと拡張します: 計画を立てる、ファイルの書き込みやテストの実行などのアクションを実行する、結果を観察し、処理を継続します。このプロジェクトは以前 OpenDevin と呼ばれていました。OpenHands の論文には、シェルやブラウジング機能を備えた Docker サンドボックスされたランタイムについて記述されており、これは CLI が今もラップしている実行モデルです。

リリース 1.16.0 では、このループを実行するための 5 つの方法が文書化されています。

モード	コマンド	用途
ターミナル UI	`openhands`	インタラクティブセッション。承認フラグを渡さない限り、各アクション実行前に確認します。
ヘッドレス	`openhands --headless -t "task"`	CI やスクリプト向け。`--task` または `--file` の指定が必須。アクションは常に承認されます。
ACP	`openhands acp`	Zed、JetBrains、Toad、および VS Code の ACP 拡張機能向けの Agent Client Protocol サーバー。
ブラウザ TUI	`openhands web`	ブラウザ版の同一 CLI。デフォルトのバインドは `0.0.0.0:12000` です。
レガシー GUI	`openhands serve`	CLI ランチャーから起動する Docker GUI。デフォルト URL は `http://localhost:3000` です。

プロジェクトが現在文書化しているインストール対象: Agent Canvas

2026年6月3日、OpenHands の FAQ で、ターミナル UI が 2026年10月1日まではメンテナンス体制に移行することが発表されました。また、ヘッドレスモードと ACP は完全なサポートを継続すると述べられています。ローカル GUI (openhands serve) は、Agent Canvas が分離されたエフェメラルサンドボックスを動作できるようになるまで、メンテナンス体制にとどまるとのことです。FAQ では、メンテナンスとは依存関係の更新、重大なバグ修正、および新しい LLM のサポートを指すと定義しています。主な OpenHands リポジトリは、2026年10月23日に Agent Canvas 1.33.0 をリリースしました。

agent-canvas は、現在の UI とそのバックエンドを起動します。openhands serve はレガシー GUI を起動しますが、Agent Canvas は起動しません。

Agent Canvas には Node.js 24 以降と uv が必要です。グローバルインストールなしでの初回実行の例:

npx @openhands/agent-canvas

このプロセスは http://localhost:8000 で待ち受けします。そのターミナルを閉じると、ローカルバックエンドが停止します。グローバルインストールは npm install -g @openhands/agent-canvas を実行し、その後 agent-canvas とします。npm を使用する場合、エージェントサーバーはユーザーとして実行されるため、エージェントはユーザーのアカウントの権限でローカルファイルに操作を行います。

Docker を使用する場合、ポートはローカルホストにのみ公開され、プロジェクトディレクトリがマウントされます:

mkdir -p ~/projects

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -v openhands-data:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

コンテナは UI を http://localhost:8000/canvas で配信します。名付きボリューム openhands-data は、--rm 後も設定を保持します。Linux で、~/.openhands をこのイメージにバインドマウントすると、unable to open database file エラーが発生します。これは、コンテナユーザーが UID 10001 であるのに対し、ホストディレクトリは通常、ユーザー自身の UID で所有されているためです。インストールページでは、この理由から名付きボリュームを使用しています。~/.openhands に既に存在する設定は、新しいボリュームにコピーされません。

OpenHands CLI のインストール

引き続き openhands --headless または openhands acp を使用したい場合は、CLI を使用してください。公開されているウィHEELは Python 3.12 のみでインストールできます（PyPI では ==3.12.*）。uv は 0.11.6 以降である必要があります。Windows では、インストールページのコマンドは WSL (Ubuntu) で実行すると記載されています。

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

uv tool install openhands --python 3.12
openhands

同じインタープリターピンでアップグレードします:

uv tool upgrade openhands --python 3.12

ローカルセットアップページには、uv が CLI をプロジェクトのバーチャル環境から分離し、デフォルトの MCP サーバーにはそれが必須であると記載されています。

スタンドアロンバイナリをインストール

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

macOS では、Gatekeeper ダイアログがバイナリの実行をブロックする可能性があります（「Apple が悪性ソフトウェアかどうかを確認できないため、openhands を開くことはできません」）。インストールページに記載されている対応策は、システム設定 > プライバシーとセキュリティ、そしてセキュリティセクションの「とにかく許可」を選択し、再度 openhands を実行することです。

Docker を介して CLI を実行

インストールページのコンテナは、エージェントサーバーイメージ用の AGENT_SERVER_IMAGE_TAG を設定します。コンテナ内での uv tool install openhands は PyPI 版 CLI です。このページ用に確認したタグは 1.26.0-python です。このコマンドの古いコピーは 1.12.0-python を使用していました。

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.26.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"

SANDBOX_USER_ID=$(id -u) は、サンドボックスユーザーがホストユーザーと一致するようにし、エージェントがマウントされたワークスペースに root 所有のファイルを置き去りにしないようにします。SANDBOX_VOLUMES は、エージェントがアクセス可能なディレクトリです。

OPENHANDS_VERSION は、openhands serve 用の Docker イメージバージョンを選択します。PyPI 版 CLI のバージョンは変更しません。

設定ファイル

初回起動時、CLI はモデル設定の入力を求め、それを ~/.openhands/ 配下に書き込みます。1.16.0 の README およびコマンドリファレンスでは、これらのファイルを以下の通り呼びます:

ファイル	保持される内容
`~/.openhands/agent_settings.json`	永続化されたエージェントスペック（LLM ブロックとコンデンスター設定を含む）
`~/.openhands/cli_config.json`	CLI の好み（クリチッカーの有効化を含む）
`~/.openhands/mcp.json`	MCP サーバー定義
`~/.openhands/conversations/`	会話履歴

インストールページでは、Docker ユーザーには依然として ~/.openhands/settings.json を準備するよう指示しています。CLI README と 1.16.0 ツリーの AgentStore は、エージェントスペックを agent_settings.json に永続化します。インストールページのファイル名をスキップし、agent_settings.json を書き込んだ CLI インストールは、そのソースと整合しています。

create_and_save_from_settings は、同一のモデル、API キー、ベース URL から 2 つの LLM オブジェクトを構築します: 1 つはエージェント用、もう 1 つは要約コンデンスター用です。そのため、保存ファイルには llm フィールドが重複して記録されます。任意のエディタでエージェントファイルを編集します:

nano ~/.openhands/agent_settings.json

LLM_API_KEY、LLM_MODEL、LLM_BASE_URL は、オプトインしない限り無視されます。オーバーライドは保存されません:

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

OPENHANDS_CLOUD_URL はデフォルトのクラウドサーバーを設定します。この変数が未設定の場合、cloud および login コマンドはデフォルトで https://app.all-hands.dev を使用します。

1.0.0 より古い CLI からのアップグレードでは、設定を再入力する必要があります。インストールページには、設定フォーマットが 1.0.0 で変更された旨が記載されています。

ローカルモデル

2026年5月21日付のローカル LLM ガイドでは、最初の試行対象として Qwen3.6-35B-A3B を推奨しています。量子化ビルドには最低 24GB の VRAM を備えた GPU、または最低 64GB の統一メモリを備えた Apple Silicon Mac が必要とされています。同ページでは、コンテキスト長を少なくとも 22,000 トークンに設定するよう示し、Ollama のデフォルト 4096 はシステムプロンプトに対して小さすぎると述べています。

エージェントがツールを呼び出さない場合、そのガイドではそれをモデルの制限と捉え、qwen2.5-coder-14b-instruct および qwopus3.5-27b-v3 に関するコミュニティの報告事例を挙げます。Ollama、vLLM、LM Studio、または LocalAI の選択が未確定の場合、ローカルホスティング比較は、サーバーごとの比較表を提供します。

Ollama

ガイドの Ollama 起動コマンドでは、ollama serve の前にコンテキスト長を設定します。Ollama CLI チートシートでは、その変数と並んで serve、run、ps をカバーしています。

OLLAMA_CONTEXT_LENGTH=32768 OLLAMA_HOST=0.0.0.0:11434 OLLAMA_KEEP_ALIVE=-1 ollama serve
ollama pull qwen3.6:35b-a3b

Docker で実行される OpenHands 向けに、ガイドが示す設定は、カスタムモデル openai/qwen3.6:35b-a3b、ベース URL http://host.docker.internal:11434/v1、そして任意のプレースホルダー API キーです。Ollama と同じホスト上で実行される CLI は、host.docker.internal の代わりに http://127.0.0.1:11434/v1 を使用します。Linux 版 LM Studio や他のループバック専用サーバーは、コンテナ内から 127.0.0.1 では到達できません。ガイドが示す確認方法は、ローカルネットワークでの配信を有効にし、コンテナ内で host.docker.internal を curl することです。

ターミナルページでは、その画面を Ctrl+P を押してから Settings で開きます。保存されていた CLI プロファイルでは、ollama/ 形式のモデル ID と /v1 を含まないベース URL が使用されていました:

カスタムモデル: ollama/devstral-small-2:24b
ベース URL: http://localhost:11434

openhands settings ollama mistral

その Devstral-Small-2 セッションは、何度も停止していました。エージェント LLM とコンデンスター LLM の両方に書き込まれたフィールドは以下の通りです:

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

llama.cpp と vLLM

llama.cpp は、OpenAI 互換プレフィックスと /v1 ベース URL を使用し、これもまた両方の LLM オブジェクトに設定されました:

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

llama.cpp クイックスタートでカバーされているフラグを含むサーバーコマンドは、以下の通りです:

./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

このサーバーに対して、CLI は Go による IndexNow クライアント（ソース、実行可能ファイル、および README）を完成させました。タスクテキストは 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 でした。

ローカル LLM ガイドの、より新しい Qwen3.6 モデル向けの vLLM の例は、2 GPU サーブです。vLLM クイックスタートでは、vllm serve のフラグとメモリ不足（OOM）のチェックについて説明しています。ガイドに示される対応する OpenHands モデル文字列は openai/Qwen3.6-35B-A3B で、ベース URL は http://host.docker.internal:8000/v1、サーバー起動時に使用した --api-key（例では mykey）と同一です。

vllm serve Qwen/Qwen3.6-35B-A3B \
    --host 0.0.0.0 --port 8000 \
    --api-key mykey \
    --tensor-parallel-size 2 \
    --served-model-name Qwen3.6-35B-A3B \
    --enable-prefix-caching

インタラクティブ制御

サブコマンドなしの openhands は、ターミナル UI を開きます。ターミナルページでは、以下の操作がリストされています:

操作	アクション
`Ctrl+P`	コマンドパレット。設定、MCP ステータス、履歴、計画、テーマ、終了。
`Esc`	実行中のエージェントを一時停止します。
`Ctrl+Q` または `/exit`	CLI から離れます。

コマンドリファレンスからのスラッシュコマンド: /help、/new、/history、/confirm、/condense、/skills、/feedback、/exit。パレットの Settings 項目からのモデル変更は、再起動なしで適用されます。--exit-without-confirmation は終了ダイアログをスキップします。--exp はテキスト UI を選択しますが、その UI がすでにデフォルトであるため、互換性フラグとして文書化されています。

フラグとサブコマンド

openhands [OPTIONS] [COMMAND]

1.16.0 タグの argparsers/util.py に対して承認と環境フラグを検証した、コマンドリファレンスのグローバルオプション:

オプション	効果
`-v`, `--version`	バージョンを表示して終了します。
`-t`, `--task TEXT`	このタスクで会話を開始します。
`-f`, `--file PATH`	ファイルから会話を開始します。
`--resume [ID]`	その会話を再開します。ID なしの場合、最近の会話をリストします。
`--last`	`--resume` と組み合わせて、最新の会話を再開します。
`--headless`	UI なし。`--task` または `--file` が必須。常に承認します。
`--json`	JSONL イベントストリーム。`--headless` が必須。
`--always-approve`, `--yolo`	すべてのアクションを承認します。`--llm-approve` とは互換性がありません。
`--llm-approve`	LLM セキュリティアナライザーが高リスクと判断したアクションのみ確認します。
`--override-with-envs`	`LLM_API_KEY`、`LLM_MODEL`、`LLM_BASE_URL` をこのプロセスに適用します。
`--exit-without-confirmation`	確認ダイアログなしで終了します。

--always-approve と --llm-approve は併用できません。デフォルトのインタラクティブモードでは、アクション実行前に確認します。

TUI では不十分となった場合に表示されるサブコマンド:

openhands serve は Docker でレガシー GUI を開始します。--mount-cwd は現在のディレクトリを /workspace にマウントします。--gpu は nvidia-docker をオンにします。
openhands web はブラウザで CLI を配信します。--host のデフォルトは 0.0.0.0、--port は 12000、--debug はオフです。
openhands acp は stdio で Agent Client Protocol を処理します。フラグ: --resume、--last、--always-approve、--llm-approve、--streaming。
openhands cloud -t "task" はクラウド会話を開きます。--server-url は https://app.all-hands.dev をオーバーライドします。
openhands login と openhands logout はそのクラウドアカウントを管理します。--server-url なしの logout は、保存されたすべてのサーバーからログアウトします。
openhands mcp はサーバーを管理します: add、list、get、remove、enable、disable。add は http、sse、または stdio の --transport が必要です。

1.16.0 README からの MCP サーバーの例:

openhands mcp list
openhands mcp add tavily --transport stdio \
  npx -- -y mcp-remote "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>"
openhands mcp enable tavily
openhands mcp disable tavily

使用例

インタラクティブタスク

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

タスクファイル

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

openhands -f task.txt

ヘッドレスモード（JSONL 込み）

ヘッドレスモードには --task または --file が必須です。常に always-approve として実行され、--llm-approve はそこで拒否されます。作業ディレクトリは、エージェントが自由に修正可能であるとみなしてください。

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

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

ヘッドレスページでは、--json はイベントごとに 1 つの JSON オブジェクトとして、JSONL でストリーミングされるものと説明されています。

再開（Resume）

openhands --resume
openhands --resume --last
openhands --resume abc123def456

localhost にバインドしたブラウザ TUI

openhands web のデフォルトは 0.0.0.0:12000 で、ネットワークから到達可能です。CLI ドキュメントでは、そのインターフェースが CLI の全機能を持ちうると述べられているため、ローカル専用バインドの方がより安全なデフォルトになります:

openhands web --host 127.0.0.1 --port 12000

エディター向けの ACP

IDE ページの ACP クライアントには、Zed と JetBrains（ネイティブ）、Toad（ネイティブ）、VS Code（コミュニティ拡張機能）があります。エディターは openhands acp を起動し、stdio 経由で JSON-RPC 2.0 を使用して、CLI に保存された LLM 設定を用いて通信します。

openhands acp
openhands acp --llm-approve
openhands acp --resume --last

承認、終了コード、およびローカルモデルの結果

インタラクティブセッションでは、アクション実行前に確認を行います。/confirm はセッション内のそのポリシーを変更します。--always-approve（別名 --yolo）はすべてを承認します。--llm-approve は、セキュリティアナライザーが高リスクとスコアリングしたアクションのみ確認します。ヘッドレスモードでは、実行全体が always-approve です。

openhands serve --mount-cwd は、レガシー GUI コンテナ内で現在のディレクトリを /workspace にマウントします。Docker CLI のフローでは、同じ境界のために SANDBOX_VOLUMES が使用されます。

コマンドリファレンスの終了コード:

コード	意味
0	成功
1	エラー、またはタスク失敗
2	無効な引数

Ollama 上の Devstral-Small-2 24B は、この CLI で何度も停止しました。

OpenHands with Ollama-hosted Devstral-Small-2

上記の llama.cpp セッション（70,000 トークンコンテキストの Qwen3.5-35B-A3B）は、IndexNow タスクを完了しました。同じマシン上で引き続き作業していたターミナルエージェントにとって、OpenCode クイックスタートが、インストールとプロバイダー設定の手引きになります。