OpenHands CLIの使い方｜1.16.0の導入（Windows・Docker）・ローカルLLM・CI実行と保守終了後の移行先

OpenHands CLIは、オープンソースのコーディングエージェントOpenHandsをターミナルから動かすツールです。uv tool install openhands --python 3.12 で入り、openhands と打てば対話画面が開きます。ただし最終リリースは2026年5月8日の1.16.0で、8月11日にはGitHubリポジトリに「This project is no longer actively maintained.」と掲示されました。公式が対話画面（TUI）の保守を約束していた10月1日も過ぎ、新しい版は出ていません。

この記事では、1.16.0をmacOS上のuvxとDockerコンテナ（python:3.12-slim）で実行して確かめた挙動と、同版および同梱SDK 1.21.0のソースをもとに、導入からCIでのヘッドレス実行までを整理し、後継のAgent Canvasへ移るべきかの判断基準を示します。ローカルLLMとGitHub Actionsでの通し実行は未検証で、公式ドキュメントの記載に基づきます。OpenHands全体の仕組みや料金はOpenHandsの解説記事で扱っています。

まとめ：OpenHands CLIの現状と使い方の要点

• 最新版は1.16.0（2026年5月8日）のまま。8月11日に積極的な保守の終了が表明され、TUIの保守期限とされた10月1日を過ぎても新しい版は出ていない。公式の推奨はAgent Canvas
• 導入は uv tool install openhands --python 3.12。Python 3.12系が必須で、WindowsはWSL上で動かす
• 設定は ~/.openhands/agent_settings.json に保存される。リポジトリの AGENTS.md や .agents/skills/ は起動時に自動で読まれる
• エージェントはホストのカレントディレクトリで直接動く。隔離したいならコンテナに入れるが、公式ドキュメントのDocker手順はそのままでは openhands: command not found で止まる
• --headless は設定が無くてもLLMに接続できなくても終了コード0で終わる。CIでは --json の出力からエラーイベントを拾って失敗にする
• ローカルLLMはコンテキスト22,000トークン以上が要る。Ollamaは既定値がVRAM量で変わるので ollama ps で確かめる

OpenHands CLIの開発状況：1.16.0で更新停止、10月1日の保守期限も経過

OpenHands CLIは、GUI版とは別のリポジトリ OpenHands/OpenHands-CLI（MITライセンス）で開発されてきました。2026年に入ってからの動きは次のとおりです。

6月3日付のコミュニティFAQは、TUIだけを保守モード（依存更新・重大なバグ修正・新しいLLMへの対応）に入れ、期限を「少なくとも3か月、2026年10月1日まで」とし、headlessとACPは「無期限で完全サポート」としていました。ところが8月11日のREADME更新はモードを区別せず、プロジェクト全体の積極的な保守終了を表明しています。FAQのissueは7月27日を最後に更新がなく、10月1日以降の扱いに公式の追加説明はありません。

リポジトリはアーカイブされておらず、10月にも修正の提案（PR #834〜#836、#839）が出ていますが、10月19日時点でmainに入ったのは、放置されたissueを自動で閉じる仕組みの削除（#837）だけです。1.16.0が固定する同梱SDKはv1.21.0で、SDK本体はPyPIで1.55.1（2026年10月16日）まで進んでいます。

後継のAgent Canvasは、ブラウザ画面から複数のバックエンド（ローカル、Docker、VM、OpenHands Cloud）上のエージェントを操作するアプリです。npmの @openhands/agent-canvas は1.27.1（2026年10月12日）まで更新が続いており、Node.js 24以上とuvが要ります。OpenHands本体のほか、Claude Code・Codex・Gemini CLIなどACP対応のエージェントも呼べます。

OpenHands CLIのインストール手順（uv・WSL・Docker）

uvでの導入とアップグレード（Python 3.12）

公式の推奨はuvです。以下はuvを導入済みの環境向けで、公式READMEの要件はuv 0.11.6以上です。PyPIの openhands 1.16.0は requires_python ==3.12.* で、3.13や3.11の環境には入りません。--python 3.12 を付ければuvが3.12を自動で取ってくるので、手元のPythonの版は気にしなくて済みます。

uv tool install openhands --python 3.12
openhands --version        # OpenHands CLI 1.16.0
uv tool upgrade openhands --python 3.12

インストールせずに一度だけ試すなら uvx --python 3.12 --from openhands==1.16.0 openhands でも起動できます。Pythonを入れたくない環境向けには単一バイナリもあり、curl -fsSL https://install.openhands.dev/install.sh | sh で入ります。macOSで「開発元を確認できない」と出たら、システム設定の「プライバシーとセキュリティ」で許可します。

Windowsでの導入はWSL前提

公式のQuick Startは「Native Windows is not officially supported」と明記しています。PowerShellで wsl --install を実行してUbuntuを入れ、Ubuntuのターミナルの中で上のuvの手順を実行します。エージェントが触るのもWSL側のファイルシステムなので、プロジェクトは /mnt/c/ 配下ではなくWSLのホーム以下に置くと、Windows側のファイルシステムをまたぐ操作の遅さを抑えられます。改行コードは保存場所だけでは統一されないため、Gitやエディタの設定を別途そろえてください。

WSLを入れたくない場合は、CLIではなくAgent Canvasを選ぶ手があります。Agent Canvasのインストール手順は対象環境を「macOS, Linux, Windows with PowerShell, or Windows with WSL2」としており、PowerShellから npm install -g @openhands/agent-canvas で入れられます。

Dockerコンテナの中で動かす手順と公式コマンドの不具合

CLIはホスト上で直接コマンドを実行するので、手元のファイルから切り離したいときはコンテナの中で動かします。公式ドキュメントのInstallationページにもDockerでの手順がありますが、末尾の bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands" は、python:3.12-slimイメージで実行すると openhands: command not found（終了コード127）で止まりました。uvは /root/.local/bin にコマンドを置きますが、このイメージのPATHにそこが含まれていないためです。

同じ手順はプロジェクトを SANDBOX_VOLUMES で渡す前提ですが、1.16.0と同梱SDKのコードでこの変数を読むのは openhands serve の起動処理だけでした。CLIの作業場所はカレントディレクトリ（環境変数 OPENHANDS_WORK_DIR があればそちら）で、コンテナの既定は / です。次のようにプロジェクトを -v でマウントし、-w で作業ディレクトリにすれば、1.16.0が /workspace を作業ディレクトリとして起動します。ただし、この指定はアクセス制限ではなく、コンテナ内のほかのディレクトリにも権限の範囲でアクセスできます。

docker run -it --rm \
  -v "$PWD":/workspace -w /workspace \
  -v ~/.openhands:/root/.openhands \
  -e PATH=/root/.local/bin:/usr/local/bin:/usr/bin:/bin \
  python:3.12-slim \
  bash -c "pip install uv && uv tool install openhands==1.16.0 --python 3.12 && openhands"

この例でホストと読み書きを共有するのは、マウントした2つのディレクトリです。ここは隔離されず、/workspace への変更はそのままホストに反映され、~/.openhands に入っているAPIキーもエージェントから読めます。エージェントの実行環境を丸ごとクラウドの使い捨て環境に分ける方法は、Docker Cloud Sandboxesの解説で扱っています。

旧パッケージ openhands-ai との違いと1.0未満からの移行

2025年ごろの解説では uvx --python 3.12 --from openhands-ai openhands という起動方法が紹介されていました。openhands-ai はGUI版を含む旧パッケージで、現行CLIは openhands パッケージです。openhands-cli という名前のパッケージはPyPIに存在しません。1.0.0より前のCLIから上げる場合は設定形式が変わっているため、初回起動時に設定をやり直す必要があります。

初回設定と~/.openhandsの保存ファイル

初めて openhands を起動すると、LLMのプロバイダー・モデル・APIキーを聞かれます。入力内容は次のファイルに保存されます。

公式ドキュメントのInstallationページには ~/.openhands/settings.json と書かれていますが、1.16.0のソース（openhands_cli/locations.py）が読むのは agent_settings.json です。ドキュメントのほうが古いので、設定を手で編集するときはこちらを開いてください。

APIキーを環境変数で渡したい場合は注意が要ります。LLM_API_KEY・LLM_MODEL・LLM_BASE_URL は既定では無視され、--override-with-envs を付けたときだけ保存済みの設定を上書きします。上書きはその実行限りで、ファイルには書き戻されません。OPENHANDS_API_KEY のような変数は存在しません。保存先そのものは OPENHANDS_PERSISTENCE_DIR で変えられます。

AGENTS.mdとskillsの読み込み対象・優先順位

テストの実行方法やコーディング規約など、リポジトリ固有の決まりは、毎回プロンプトに書かずにファイルで渡せます。1.16.0は起動時に作業ディレクトリのスキルを読み込み、同梱SDK 1.21.0の load_project_skills が次の場所を探します。作業ディレクトリがGitリポジトリのサブディレクトリなら、リポジトリのルートも探索対象になり、同じ名前が両方にあれば作業ディレクトリ側が優先されます。

Gitリポジトリのルートに AGENTS.md と CLAUDE.md を置き、サブディレクトリから1.16.0のヘッドレスを起動したところ、両方の中身がシステムプロンプトに入りました。Claude CodeやGemini CLI向けに書いた指示ファイルが既にあれば、OpenHandsにもそのまま効きます。ほかにCLIは公開スキル集の OpenHands/extensions も読み込む設定になっており、読み込まれた一覧は対話画面の /skills で確認できます。

リポジトリ内の指示ファイルは、第三者が書いた内容がエージェントの行動を左右する経路でもあります。同梱SDKのリスク判定プロンプトは、AGENTS.md・.cursorrules・.agents/skills/ に由来する操作のうち、パッケージマネージャー設定の書き換え、独自レジストリの追加、curl | bash 型の実行などを高リスクに格上げするよう指示しています。この判定が効くのは下の --llm-approve を使ったときだけで、--yolo やヘッドレスでは確認なしで実行されます。他人のリポジトリを自動承認で触らせないでください。

起動モードとコマンド・オプション一覧

5つの起動モードとサブコマンド

ほかに mcp（MCP設定）、cloud（OpenHands Cloudで会話を作る）、login / logout（OAuthデバイスフローでCloudに認証）、view（会話の軌跡を表示）があります。タスクは -t で文字列、-f でファイルから渡し、前回の続きは --resume --last、ID指定なら --resume <ID> です。

TUI内のスラッシュコマンドとキー操作

対話画面で使えるスラッシュコマンドは1.16.0で次の9個です。

/help      コマンド一覧
/new       新しい会話を始める
/history   会話履歴の表示切替
/settings  LLM設定を開く
/confirm   確認モードの変更
/condense  会話履歴を要約して圧縮
/skills    読み込まれたスキル・フック・MCPの確認
/feedback  匿名フィードバック送信
/exit      終了

キー操作は、Ctrl+P でコマンドパレット、Esc で実行中のエージェントを一時停止、Ctrl+Q で終了です。エージェントが見当違いの方向に進んだら、Esc で止めて指示を足すのが手戻りの少ない使い方です。

確認モード3種と自動承認の危険範囲

既定はすべての操作で確認を求めるalways-askです。--llm-approve はLLMが高リスクと判定した操作だけ確認し、--always-approve（別名 --yolo）は一切確認しません。

押さえておくべきなのは、CLIがコンテナの中ではなく、ホストのカレントディレクトリでコマンドを実行する点です。1.16.0は作業場所を Workspace(working_dir=...) で作っており、SDK側ではこれがローカル実行の LocalWorkspace になります。--yolo で動かすと、エージェントはあなたのユーザー権限で届くファイルすべてに手を出せます。ホームディレクトリ直下で自動承認を使うのは避け、使うなら上のDockerの手順でコンテナに入れてください。

ローカルLLM（Ollama・LM Studio）へ接続する設定

公式ドキュメントは2026年5月21日から、ローカルで最初に試すモデルとしてQwen3.6-35B-A3Bを推奨しています。公式の機材目安は、量子化版ならVRAM 24GB以上のGPU、またはユニファイドメモリ64GB以上のApple Silicon Macです。つまずきやすいのはコンテキスト長で、OpenHandsはシステムプロンプトとツール定義だけで数千トークンを使うため、22,000トークン以上（推奨32,768）が必要です。Ollamaの既定値はVRAM量で変わり、24GiB未満なら4k、24〜48GiBなら32kです。4kで動いていると、ツール呼び出しが失敗し続けたり、普通のチャットのように応答したりしやすくなります。

Ollamaがすでにサービスとして動いている場合は、いったん止めてから環境変数付きで起動し直します。起動中のサーバーには後から設定が反映されないためです。モデルを読み込んだあと ollama ps のCONTEXT列で実際の値を確かめてください。

OLLAMA_CONTEXT_LENGTH=32768 ollama serve &
ollama pull qwen3.6:35b-a3b
ollama run qwen3.6:35b-a3b "こんにちは"
ollama ps        # CONTEXT が 32768 になっているか確認

CLIでは /settings を開き、詳細設定（advanced）に切り替えて次の3項目を入れます。advancedではCustom ModelとBase URLの両方が必須です。

公式ドキュメントのBase URLが host.docker.internal になっているのは、GUI版をDockerで動かす前提だからです。CLIはホスト上で動くので localhost で届きます。逆にDockerの中でCLIを動かすときや openhands serve を使うときは host.docker.internal に戻し、Linuxでは docker run に --add-host host.docker.internal:host-gateway を足したうえで、OLLAMA_HOST=0.0.0.0:11434 やLM Studioの「Serve on Local Network」でループバック以外からの接続を許可します。モデル名に openai/ を付けるのは、OpenAI互換APIとして呼ぶ指定です。Ollamaのモデルをほかのコーディングエージェントで使う場合の設定は、Copilot CLIでOllamaのローカルモデルを使う方法と比べると違いが分かります。

ヘッドレスモードでCI・GitHub Actionsから実行する手順

ヘッドレス実行で終了コード0になる失敗条件

--headless は画面を出さずにタスクを最後まで実行するモードで、常に自動承認になり --llm-approve は使えません。CIに組み込む前に知っておくべきなのは、失敗しても終了コードが0になる場面があることです。1.16.0で確かめた結果は次のとおりです。

設定ファイルが無い場合、「openhands to configure your settings before using –headless」と案内して何もせずに終わりますが、終了コードは0でした。CIのジョブは成功扱いになります。LLMに接続できない場合は、同梱SDKが待ち時間を広げながら再試行を続け、開始から約2分18秒後に LLMServiceUnavailableError のエラーイベントを出し、172秒で終了しました。こちらも終了コードは0です。

CIでは、まず --override-with-envs を付けて設定を環境変数から渡します。変数が欠けていれば終了コード1で止まるので、設定漏れが成功扱いになる経路をふさげます。そのうえで --json の出力を確かめます。1.16.0は終了時の案内や会話ID、システムプロンプトの表示など、JSONでない行も同じ標準出力に出すため、出力は生ログとして保存し、{ で始まる行だけを取り出します。会話が途中で止まったときは "kind": "ConversationErrorEvent" の行が出るので、これがあればジョブを失敗にします。

GitHub Actionsのワークフロー例

次の例は手動実行用で、事前にリポジトリへタスクを書いた .github/openhands-task.md を置き、Secretsに LLM_API_KEY を登録しておく前提です。

name: openhands-task
on: workflow_dispatch
permissions:
  contents: read
jobs:
  run:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/[email protected]
      - run: uv tool install openhands==1.16.0 --python 3.12
      - name: Run OpenHands headless
        env:
          LLM_MODEL: anthropic/claude-sonnet-4-6
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: |
          openhands --headless --json --override-with-envs \
            -f .github/openhands-task.md > openhands.log
      - name: Fail on error events
        run: |
          grep '^{' openhands.log > events.jsonl || true
          if [ ! -s events.jsonl ] || grep -q '"kind": "ConversationErrorEvent"' events.jsonl; then
            exit 1
          fi

最後のステップは、イベントが1行も無いか、エラーイベントがあればジョブを失敗にします。ただし、タスクの完了や生成コードの正しさまでは判定しないため、対象プロジェクトのテストや成果物の検査も後続ステップで実行してください。接続先を間違えると上のとおり数分待たされるので、timeout-minutes も必ず付けてください。

モデル名はLiteLLMの形式（プロバイダー/モデルID）で書きます。1.16.0に同梱されたSDKの検証済みモデル一覧（verified_models.py）は、Anthropicならclaude-opus-4-7とclaude-sonnet-4-6、OpenAIならgpt-5.5までです。それより新しいモデルも指定はできますが、OpenHands側で動作確認されていない組み合わせになります。

GitHubホストランナーは使い捨てのVMですが、ジョブに渡したAPIキーやトークンが漏れた場合の被害はジョブ終了後も続きます。LLMのAPIキーには利用上限を設定し、GITHUB_TOKEN は読み取り権限に絞ってください。セルフホストランナーでは同じマシンの他のリポジトリにも届くため、コンテナの中で実行します。なお ==1.16.0 で固定できるのはCLI本体だけで、LiteLLMなど依存パッケージの一部はインストールのたびに新しい版が入りえます。

MCPサーバーの追加とIDE連携（ACP）

openhands mcp add の書式と保存先

MCPサーバーはサブコマンドで追加し、定義は ~/.openhands/mcp.json に保存されます。トランスポートは http・sse・stdio の3種類から選び、HTTP系は --header、stdioは --env で認証情報を渡します。

openhands mcp add my-api --transport http \
  --header "Authorization: Bearer $TOKEN" https://api.example.com/mcp
openhands mcp add local --transport stdio python -- -m my_server
openhands mcp list
openhands mcp disable my-api

読み込まれたかどうかは、対話画面の /skills か Ctrl+P のMCP項目で確認できます。公式ドキュメントのプラグインのページには openhands --plugin <パス> での読み込みが書かれていますが、1.16.0にこのオプションは無く、実行すると引数エラー（終了コード2）になります。2026年10月14日にissue #840として報告されています。

Zed・JetBrains・VS CodeからACPで呼ぶ構成

openhands acp は、エディタとエージェントをJSON-RPC 2.0でつなぐAgent Client Protocolのサーバーとして起動します。IDEがこのコマンドを子プロセスとして立ち上げ、CLIの保存済み設定をそのまま使います。公式が挙げる対応先は、ACPをネイティブに持つZed・Toad・JetBrains系IDEと、コミュニティ拡張経由のVS Codeです。ドキュメント自身がACP連携を「experimental」としている点と、不具合の報告先が保守を終えたOpenHands-CLIリポジトリになっている点は、採用前に知っておくべきです。

openhands serveとDocker・Podmanの関係

CLI本体（TUI・headless・acp・web）はコンテナを使わないので、DockerもPodmanも要りません。Dockerが必要になるのは、GUI版をローカルで立ち上げる openhands serve だけです。1.16.0のserveは docker コマンドがPATHにあるかと docker info の成否を確かめたうえで、docker.openhands.dev/openhands/openhands:latest を起動し、http://localhost:3000 で公開します。--mount-cwd でカレントディレクトリを、--gpu でGPUを渡せます。

Podmanについては公式手順に記載がありません。serveは docker という名前のコマンドを直接呼ぶ作りなので、Podmanしか無い環境では起動前のチェックで止まります。GUIを使いたいだけなら、serveを経由せず後継のAgent Canvasを入れるほうが素直です。Agent Canvasはnpm版ならDocker不要で、Docker版は ghcr.io/openhands/agent-canvas イメージを起動し、http://localhost:8000/canvas で開きます。

今からOpenHands CLIを採用するかの判断基準

結論から言うと、新しく導入するならOpenHands CLIのTUIは選びません。公式FAQがTUIの保守を約束した期限は2026年10月1日で既に過ぎ、その前の8月にはリポジトリ全体の積極的な保守終了が表明されています。同梱SDKはv1.21.0に固定されたままで、新しいLLMへの対応が今後入る保証はありません。ターミナルで対話しながら使うエージェントが欲しいなら、開発が続いている他のCLIを比べたほうが長く使えます。選び方はコーディングエージェントの型と主要ツールの比較にまとめています。

一方、すでにheadlessでCIに組み込んでいる場合は、今のタスクが定期実行で通り続けている限り、慌てて外す必要はありません。ただし上で見たとおり、終了コードだけを見ているジョブは、LLMの接続先が変わって失敗しても成功と表示します。まずエラーイベントの検出を足し、それが落ち始めた時点を移行の合図にしてください。移行先は用途で分かれます。

• ブラウザから会話したい、Windowsでネイティブに動かしたい、複数マシンのエージェントをまとめて扱いたい：Agent Canvas。公式FAQはGUI版（Local GUI）の ~/.openhands の設定と会話の多くを引き継げるとしていますが、CLIからの移行については明記がないため、設定と会話履歴は手元で引き継げるか確かめてください
• CIやスクリプトから呼びたい：開発が続いているSoftware Agent SDK（openhands-sdk）をPythonから直接呼ぶ
• OpenHands自体にこだわらない：Claude Code・Codexなど、Agent CanvasからACPで呼べるエージェントに乗り換える

避けるべきなのは、保守終了を知らずに2025年の記事どおり openhands-ai パッケージで旧CLIを入れ、そのまま --yolo で自分のホームディレクトリを触らせる使い方です。古い版、ホスト実行、自動承認の3つが重なると、誤った操作を止める手段がありません。社内でコーディングエージェントの導入範囲や権限の設計から決める段階なら、生成AI導入支援で検証環境づくりから相談できます。

よくある質問

OpenHands CLIとGUI版のOpenHandsは何が違いますか？

GUI版は、エージェントの実行環境をDockerコンテナ（サンドボックス）として立て、ブラウザから操作する構成です。CLIはターミナルから操作し、コマンドはホスト上のカレントディレクトリで直接実行されます。セットアップが軽い反面、隔離はありません。CLIの openhands serve を使うとGUI版をDockerで起動できます。

OpenHands CLIは無料で使えますか？

CLI自体はMITライセンスのオープンソースで無料です。費用がかかるのはLLMのAPI利用料で、AnthropicやOpenAIのAPIキーを使えばそれぞれの従量課金になります。OllamaやLM Studioでローカルモデルを動かせばAPI料金はかかりませんが、公式推奨のQwen3.6-35B-A3Bの機材目安は、量子化版でVRAM 24GB以上のGPUかユニファイドメモリ64GB以上のApple Silicon Macです。openhands login でOpenHands Cloudに接続して使う方法もあります。

OpenHands CLIはWindowsで動きますか？

Windowsネイティブは公式に非対応で、WSL2のUbuntu上で動かします。PowerShellから直接使いたい場合は、PowerShellを対象環境に含むAgent Canvasを選びます。CLIはWSL側のファイルシステムで作業するので、プロジェクトもWSLのホーム以下に置いてください。

OpenHands CLIのGitHubと公式ドキュメントはどこですか？

ソースコードはGitHubのOpenHands/OpenHands-CLI、公式ドキュメントはdocs.openhands.devのCLIの章です。2026年10月時点でリポジトリには積極的な保守を終えた旨の表示があります。ドキュメントには実装と合わない記述が残っており、設定ファイル名の settings.json（実体は agent_settings.json）、Dockerでの起動コマンド、--plugin オプションがその例です。オプションの有無は openhands --help で、ファイルの保存先や永続化の挙動は1.16.0タグのソース（openhands_cli/locations.py など）で確かめるのが確実です。

Claude CodeやAiderとどう使い分けますか？

OpenHands CLIの強みは、LLMを自由に選べて、ローカルモデルでも動くことでした。同じ条件のツールには、VS Code拡張とCLIを持つClineや、git連携を軸にしたAiderがあります。ただしAiderも2026年2月の0.86.2以降リリースが止まっています。Claude Codeはモデルを自社のClaudeに絞る代わりに更新が速く、Agent CanvasからACP経由で呼ぶこともできます。

関連記事

• OpenHandsとは？自律型AIコーディングエージェントの仕組み・使い方・料金【2026年版】
• Coding Agent（コーディングエージェント）とは？仕組み・3つの型と主要ツールの選び方【2026年9月】
• Aiderの使い方｜インストール・git連携・対応LLMと開発状況【2026年9月】
• Clineとは？VS Code拡張とCLIの使い方・料金・自動承認設定を実装目線で解説
• Cursor CLIの使い方｜agentコマンドの導入・非対話実行とCI連携の手順