OpenHandsの使い方｜OSSの自律コーディングエージェントを2026年最新版で解説

OpenHandsの使い方を、2026年最新版で初心者向けに体系化した。OpenHandsは、タスクを渡すと自分でコードを書き・コマンドを実行し・テストまで回すOSS（MITライセンス）の自律コーディングエージェントだ。本記事では導入から基本操作、アーキテクチャ、SWE-Benchでの実力、他ツールとの比較、本番運用までを公式の一次情報をもとに通しで解説する。

商用の自律エージェントといえばDevinが有名だが、OpenHandsは「中身を全部見せて、自分のサーバーで動かせる」という正反対の立ち位置でそれに肉薄している。GitHubスター数は76,000を超え、OSSのコーディングエージェントとしては事実上の標準的存在になりつつある。

AIエージェントそのものの仕組みや種類から押さえたい方は AIエージェントとは？仕組み・種類・代表的OSSフレームワークを初心者向けに解説【2026年版】 をご覧ください。

30秒で理解するOpenHandsの使い方

まず要点だけ先に押さえる。細部はこのあとのセクションで順に掘り下げる。

・OpenHandsは、タスクを渡すと計画・コード編集・コマンド実行・ブラウザ操作まで自律的にこなすOSSの自律コーディングエージェント（旧称OpenDevin）
・ライセンスはMIT。自分のマシンやサーバーにDockerで立てて動かせるため、コードを外部に出さずに自律エージェントを試せる
・使い方のルートは大きく4つ。CLI（ターミナル常駐）/ Local GUI（ブラウザUI）/ Cloud（app.all-hands.dev）/ SDK（Pythonライブラリ）
・エージェントの頭脳はLLM。Claude Opus・GPT・Gemini・GLMなどを差し替えられ、強いモデルほどSWE-Benchのスコアが上がる
・SWE-Bench Verifiedで70%超の水準に達し、OSSとしては商用エージェント（Devin等）と肩を並べている

OpenHandsとは（前OpenDevin、SWE-Bench高スコアで話題）

OpenHandsとは、自然言語でタスクを渡すと、人間のエンジニアのようにコードを読み書きし、ターミナルでコマンドを叩き、必要ならブラウザで調べながら、目的を達成しようとするAIソフトウェアエンジニアだ。1行のコード補完を返すツールではなく、「Issueを解決して」「このバグを直して」といったタスク単位の依頼を丸ごと引き受ける点が最大の特徴になる。

もともとは2024年に「OpenDevin」という名前で始まったプロジェクトで、商用エージェントDevinのオープンソース版という位置づけで一気に注目を集めた。その後、商標上の配慮から「OpenHands」へ改称され、現在はAll-Hands-AIコミュニティを中心に開発が続いている。検索で「OpenDevin 使い方」を探している人も、行き着く先は同じこのOpenHandsだ。

なぜここまで話題になったのか。理由はSWE-Benchという評価指標にある。SWE-Benchは、実際のGitHubリポジトリのIssueをエージェントに渡し、自力でパッチを書いて修正できるかを測るベンチマークだ。OpenHandsはこのSWE-Bench Verifiedで70%超のスコアを叩き出し、クローズドな商用エージェントと遜色ない水準をOSSで達成した。「中身を監査できて、自分のインフラで動かせて、商用級の性能」という三拍子が、エンジニアコミュニティに刺さった。

できることを大きく分けると次の4つになる。これがOpenHandsの使い方の骨格だ。

・コード生成・修正——リポジトリを読み、複数ファイルにまたがる変更を自分で書く
・コマンド実行——テスト・ビルド・lint・git操作などをサンドボックス内で自律的に走らせる
・ブラウザ操作——ドキュメントやAPI仕様を自分で調べ、結果をコードに反映する
・反復改善——テストが落ちたら原因を読み、修正して再実行するループを自分で回す

アーキテクチャ｜OpenHandsを構成する5つの要素

OpenHandsの使い方を理解するうえで、内部アーキテクチャを押さえておくと挙動の予測がしやすくなる。OpenHandsはエージェント本体（頭脳）と、それが操作する実行環境（手足）を明確に分離した設計になっている。

中核となるのがCodeActAgentだ。CodeActは「エージェントの行動をすべて実行可能なコードとして表現する」という考え方で、ファイル編集もコマンド実行もブラウザ操作も、すべて一貫したアクション空間で扱う。これがSWE-Benchでの高スコアを支える設計思想になっている。

エージェントが実際に手を動かす先は、Dockerで隔離されたRuntime（サンドボックス）だ。ここにBash（シェル実行）、Editor（ファイル編集）、Browser（Webアクセス）といった具体的なツールがぶら下がる。ホストOSと切り離されているため、エージェントが暴走してもホスト環境を直接壊すリスクを抑えられる。

この「Agent → Runtime → 各ツール → 観測 → Agent」というループが、OpenHandsの動作の本質だ。エージェントは行動の結果（テストの成否、コマンド出力、ページ内容）を観測し、それを次の判断材料にして行動を繰り返す。人間が試行錯誤するのと同じサイクルを自動化していると考えるとわかりやすい。

・Agent——LLMを使って次に何をするかを決める頭脳。デフォルトはCodeActAgent
・Runtime——エージェントの行動を実行するサンドボックス環境の管理役
・Bash——テスト・ビルド・git等のコマンドを実行する手
・Editor——コードファイルを読み書きする手
・Browser——公式ドキュメントやAPI仕様を自分で調べる目

導入手順（CLI / Docker / Cloud）

OpenHandsの使い方を実際に始めるルートは複数ある。手軽さ順に、Cloud → CLI → Docker（GUI）で紹介する。どれを選んでもエージェント本体の挙動は同じだ。

ルート1: OpenHands Cloud（最速・環境構築不要）

とにかく挙動を見たいだけなら、ブラウザで app.all-hands.dev にアクセスし、GitHubまたはGitLabアカウントでサインインするのが最短だ。Dockerもインストールも不要で、無料クレジットの範囲でエージェントにタスクを渡せる。GitHubリポジトリと連携すれば、Issueを指定して「これを直して」と頼み、PRまで作らせる流れをそのまま試せる。

ルート2: CLI（ターミナルで使う）

自分のマシンで使うなら、CLI版が軽量で扱いやすい。uv（Pythonの高速パッケージマネージャ）でインストールするのが推奨ルートだ。

# uv でCLIをインストール（Python 3.12を指定）
uv tool install openhands --python 3.12

# 起動（初回はLLMの設定ウィザードが立ち上がる）
openhands

インストールスクリプトでネイティブバイナリを入れることもできる。

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

初回起動時に、使うLLMプロバイダ・モデル・APIキーを対話形式で設定する。設定は ~/.openhands/settings.json に保存され、次回以降は再入力不要だ。あとはターミナルでタスクを日本語または英語で書けば、エージェントが作業を始める。

ルート3: Docker（Local GUIで使う）

ブラウザのGUIをフル機能で使いたい場合は、Docker経由でGUIサーバーを起動する。CLIを入れているなら、最も簡単なのは serve サブコマンドだ。

# GUIサーバーを起動（裏でDockerイメージをpullしてコンテナを立てる）
openhands serve

起動後、ブラウザで http://localhost:3000 を開けばGUIにアクセスできる。設定とデータは ~/.openhands に保存され、必要なディスクは概ね2GB程度だ。

Dockerコマンドを直接叩きたい場合は、ランタイムイメージとアプリイメージを指定して起動する。バージョンタグは利用時点の最新（例: 1.7系）を公式リポジトリで確認してほしい。

docker run -it --rm --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:latest \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.all-hands.dev/all-hands-ai/openhands:latest

-v /var/run/docker.sock:/var/run/docker.sock は、OpenHandsがサンドボックス用のコンテナをホストのDockerで起動するために必要なマウントだ。ここを忘れるとランタイムが立ち上がらない。

基本操作｜タスクの渡し方とモデル設定

導入できたら、次は基本操作だ。OpenHandsの使い方は「タスクを書いて渡す→エージェントの行動を観察する→必要なら介入する」のサイクルが基本になる。

タスクの書き方

エージェントへの指示は、具体的であるほど精度が上がる。曖昧な「いい感じにして」より、「src/auth.py のログイン処理にレート制限を追加し、既存のテストが通ることを確認して」のように、対象ファイル・やること・完了条件を明示する。

# 良いタスク例
docs/ 配下のリンク切れを検出するスクリプトを scripts/check_links.py に作成し、
pytest で動作確認できる最小のテストも書いてください。実行して結果を見せてください。

GUIでの基本的な流れ

GUI（http://localhost:3000）を使う場合、画面は大きく3つに分かれる。左にチャット欄、中央にエージェントの作業状況、右にファイルツリーやターミナルの実況だ。流れはシンプルで、チャット欄にタスクを書いて送信すると、エージェントが「何を考え」「どのコマンドを実行し」「何を観測したか」をリアルタイムで表示しながら進む。

ここで重要なのが、エージェントの一手一手が可視化される点だ。商用のクローズドエージェントと違い、OpenHandsは「いま pytest を実行した」「テストが2件落ちた」「utils.py の23行目を修正した」といった行動ログを全部見せる。意図しない方向に進み始めたら途中で停止して指示を上書きできるので、暴走を早期に止められる。

実際のタスク実行例

たとえば既存のPythonプロジェクトでバグ修正を依頼する場合、次のように具体的なタスクを書く。

tests/test_parser.py が失敗しています。
pytest tests/test_parser.py を実行して原因を特定し、
src/parser.py を修正して全テストを通してください。
修正後に差分を要約してください。

エージェントはまずテストを実行して失敗内容を読み、関連ファイルを開いて原因箇所を特定し、修正を当て、再度テストを走らせて緑になるまでループする。人間がやる「再現→原因特定→修正→検証」のサイクルを、そのまま自動で回すイメージだ。完了後は変更差分の要約を返してくれるので、レビューしてからコミットすればよい。

モデル（LLM）の選び方

OpenHandsの性能は、接続するLLMでほぼ決まる。公式はOpenHands Index（独自の総合評価）で各モデルをランク付けしており、2026年6月時点の目安は次のとおりだ。

・最強クラス: anthropic/claude-opus-4-7（Claude Opus 4.7）——長時間・高難度タスク向け
・GPT系: openai/gpt-5.5——バランス型の有力候補
・Gemini系: gemini/gemini-3.1-pro-preview——コスト効率重視
・オープンウェイト: GLM-5.1 / Kimi-K2.6——自前ホスト派向け
・ローカル: Qwen3.6系の中型モデル——GPUで完結させたい場合

設定はGUIのSettings画面、またはCLIの初回ウィザードで「Provider / Model / API Key」を指定するだけだ。高度な設定（Base URLやAPIバージョン）は config.toml または環境変数で渡せる。実務では「計画・デバッグ・レビューは強いモデル、ルーチンな編集は安いモデル」と使い分けるとコストを抑えられる。

実践Tips｜OpenHandsを使いこなす勘所

基本操作に慣れたら、精度と安全性を上げる実践的な使い方を押さえる。

・マイクロタスクに分割する——「アプリ全体を作って」より、機能単位で区切ったほうが成功率が高い。大きなタスクは自分で計画→小タスクに分けて投げる
・完了条件をテストで定義する——「テストが通ったら完了」と書くと、エージェントが自己検証ループを回してくれる。曖昧な完了条件は迷走の原因になる
・リポジトリにルールファイルを置く——プロジェクト固有の規約（命名・ディレクトリ構造・禁止事項）をMarkdownで用意しておくと、エージェントがそれを参照して品質が安定する
・ブランチを切らせる——本番ブランチに直接書かせず、作業ブランチ＋PRを前提にする。レビューの余地を残すのが鉄則
・コストを監視する——強いモデルで長時間タスクを回すとトークン費用がかさむ。まずは小さなタスクで挙動を確認してからスケールする

SWE-Bench スコアで見るOpenHandsの実力

OpenHandsが評価される最大の根拠がSWE-Benchだ。SWE-Bench Verifiedは、人手で検証済みの実リポジトリIssueをエージェントに解かせ、正しくパッチを当てられた割合を測る。2026年時点の主要な数値を比較すると、OSSのOpenHandsが商用・他OSSと互角以上に戦えていることがわかる。

ポイントは、SWE-Benchのスコアが「エージェントの設計（スキャフォールド）」と「使うLLM」の掛け算で決まることだ。同じClaude Opusを使っても、CodeActのような優れたスキャフォールドを持つOpenHandsのほうが、素朴なエージェントより高いスコアを出す。逆に言えば、OpenHandsの実力を引き出すには強いモデルを与える必要がある。

ここで効いてくるのが、OpenHandsがOSSであることの意味だ。研究者やコミュニティが新しいスキャフォールドやプロンプト戦略を提案すると、それがそのままリポジトリに反映され、誰でも追試できる。クローズドな商用エージェントではスコアの再現や検証ができないのに対し、OpenHandsは「どういう設定で何点出たか」を第三者が確認できる。SWE-Benchの数値が信頼できる根拠になっているのは、この透明性によるところが大きい。

なお、SWE-Benchには通常のVerifiedのほかに、より難度の高いSWE-Bench Proなどの派生ベンチマークもある。Proでは最上位でも数値が大きく下がり、現実の複雑なリポジトリではエージェントの能力にまだ伸びしろがあることを示している。OpenHandsを導入する際も、「Verifiedの高スコア＝どんなタスクも解ける」ではなく、「定型的なバグ修正やIssue対応は高い確率で自動化できるが、難所は人間のレビューが要る」という現実的な期待値で運用するのがよい。

Claude Code・Cursor・Cline・Aider・Codex CLIとの比較

OpenHandsの立ち位置を、人気のAIコーディングツールと並べて整理する。判断軸は「自律度（どこまで丸投げできるか）」「自己ホスト性」「主な使い方」の3つだ。

ざっくり言うと、OpenHandsは「サーバーに常駐させ、タスクを丸ごと自律でこなさせる」方向に最も振り切っている。VS Code内でのエージェント体験を重視するならCline、エディタそのものの快適さならCursor、ターミナルでの軽量なgit連携編集ならAiderが向く。

・Claude Code——ターミナルでClaudeに最適化された対話的開発。手元の作業を会話で進めるのに強い
・Cursor——VS Codeフォークのエディタ。Tab補完の体感速度と統合体験が魅力
・Cline——VS Code拡張として動くOSSエージェント。エディタを離れずに自律実行できる
・Aider——軽量なOSS CLI。gitコミット単位での編集に強く、ローカル完結志向
・Codex CLI——ターミナル常駐のエージェント。OpenAI系モデルとの親和性が高い

エディタ内でのエージェント運用を比べたい場合は Cline（クライン）の使い方 が参考になる。商用ツール側の最新動向は GitHub Copilotがネイティブアプリ化、デフォルトモデルもPolarisへ を併せて読むと、OSSと商用の進化の方向性が見えてくる。

実務では排他ではなく併用が現実的だ。日常の細かい編集はCursorやClaude Code、まとまったタスクの自動化や監査が要る社内基盤はOpenHands、という役割分担が噛み合う。

本番運用（Self-hostedとEnterprise）

OpenHandsの使い方をチームや業務に広げるなら、Self-hostedとEnterpriseの2段階を理解しておく。

Self-hosted（自己ホスト）

OSS本体をそのまま自社サーバーやクラウドVMに立てれば、コードを外部に出さずに自律エージェントを運用できる。Dockerサンドボックスでエージェントの実行環境が隔離されるため、ホストへの影響を抑えやすい。個人〜小規模チームなら、この構成で十分実用になる。

# サーバー上でGUIサーバーを常駐させる例（systemd等で管理する想定）
openhands serve --host 0.0.0.0 --port 3000

公開ネットワークに晒す場合は、リバースプロキシ＋認証を前に置き、docker.sock をマウントするコンテナの権限管理に注意する。エージェントは任意コマンドを実行しうるため、ネットワーク到達範囲とシークレットの渡し方を絞るのが前提だ。

Enterprise（大規模運用）

組織横断で使うなら、リポジトリ内の enterprise 提供物が対象になる。Kubernetes上でのマルチユーザー運用、RBAC（ロールベースアクセス制御）、Slack・Jira・Linearとの統合などが用意されており、「IssueをSlackから振って、エージェントがPRを返す」といった業務フローを組める。エンタープライズ部分はコア（MIT）とは別ライセンスのため、商用利用の条件は公式で確認してほしい。

・Self-hosted——OSS本体をDockerで自己ホスト。個人〜小規模向け、コード非流出が要件のとき
・Enterprise——K8s＋RBAC＋業務ツール統合。組織横断・マルチユーザー運用向け
・Cloud——All-Hands-AI管理のホスト版。運用負荷をかけたくないとき

CI/CDやGitHub連携に組み込む

OpenHandsの強みは、人がGUIを操作する使い方だけでなく、自動化パイプラインに組み込める点にもある。SDK（Pythonライブラリ）を使えば、エージェントの起動・タスク投入・結果取得をコードから制御でき、CIのジョブとして「Issueが立ったら自動で初期パッチを起票する」「Dependabotの更新でテストが落ちたら自動修正を試みる」といったワークフローを構築できる。

ただし自動化の度合いを上げるほど、人間のレビューが抜けるリスクも上がる。実務では「エージェントはPRのドラフトまで作る、マージは必ず人間が判断する」というガードレールを置くのが定石だ。エージェントの行動ログが全部残るOpenHandsは、こうした「自動化と人間の承認の境界線」を引きやすい点でも、業務適用に向いている。

よくある落とし穴

OpenHandsを使い始めた人がつまずきやすいポイントを先に潰しておく。

・Dockerソケットのマウント忘れ——-v /var/run/docker.sock:... を付けないとランタイムが立ち上がらない。GUI起動失敗の定番原因
・弱いモデルで期待しすぎる——ローカルの小型モデルでSWE-Bench級の精度を期待すると失望する。実力検証はまず強いモデルで
・巨大タスクを一発で投げる——「アプリ全体を作って」は迷走しやすい。機能単位に割って渡すと成功率が上がる
・本番ブランチに直接書かせる——作業ブランチ＋PR前提にしないと、想定外の変更がそのまま入るリスクがある
・コスト無監視で長時間タスク——強いモデル×長時間でトークン費用が膨らむ。小タスクで挙動を確認してからスケールする
・シークレットの渡しすぎ——本番の認証情報を丸ごと渡すと、ログや実行過程で露出しうる。最小権限のトークンに絞る

まとめ｜OpenHandsはOSS自律エージェントの最初の選択肢

OpenHandsの使い方を、導入・基本操作・アーキテクチャ・SWE-Benchでの実力・他ツール比較・本番運用まで通しで見てきた。要点は3つだ。

第一に、OpenHandsは「タスクを丸ごと渡して自律で完遂させる」OSSエージェントであり、1行補完のツールとは設計思想が異なる。第二に、MITライセンスで自己ホストできるため、コードを外部に出せない組織や挙動を監査したい開発者に向く。第三に、SWE-Bench Verifiedで70%超という商用級の性能を、使うLLM次第で引き出せる。

まずはCloudの無料クレジットか使い捨てリポジトリで小さなタスクを投げ、挙動の癖を掴むところから始めるとよい。そこから自己ホスト、そしてチーム運用へと段階的に広げるのが、失敗の少ない進め方だ。AIエージェント全体の地図を先に押さえたい場合は、関連記事の入門ピラーも併せて読んでほしい。

参考リンク

・All-Hands-AI/OpenHands — GitHub公式リポジトリ
・OpenHands公式ドキュメント（docs.openhands.dev）
・OpenHands Cloud（app.all-hands.dev）
・SWE-bench 公式リーダーボード