ここ 1 年、 AI プログラミングで最も価値が高かったのは「おしゃべり相手」ではなく「実際に手を動かす」方向だった。
Issue を 1 つ渡す。 リポジトリを読み、 問題を見つけ、 ファイルを修正し、 テストを走らせ、 PR を出す。 この一連の流れが回ってこそ、 「ソフトウェアエンジニア Agent」の名に値する。
Devin はクローズドソース。 AutoGPT はまだ実験プロジェクトの域を出ない。 OpenHands は高い注目度、 ちゃんとしたエンジニアリング、 そして実際に PR を出すところまで揃っている数少ないオープンソースの選択肢だ。
GitHub のメインリポジトリは現時点で 84,555 stars。 旧名は OpenDevin で、 後に OpenHands に改称された。 構成は TypeScript と Python の混合で、 Web フロントエンドとインタラクション層は TypeScript、 Agent・Runtime・Controller といったバックエンドの中核は Python が担当する。
解決したい課題
一般的なコード補完が答えるのは「このコードをどう書くか」だけだ。 Agent が扱うのはもっと範囲が広い:
- Issue とリポジトリのコンテキストを読み込む
- 修正計画を立てる
- コードを検索する
- ファイルを編集する
- シェルコマンドを実行する
- テストと lint を回す
- diff を確認する
- commit や PR を作成する
難所は 1 回のコード生成ではない。
各ステップで必ずどこかが失敗する。 テストが通らない、 ネットワークが切れる、 ファイルを間違える、 といったことだ。 Agent は結果を観察し、 次の手を自分で判断できるのか。 ここが本質になる。
OpenHands がやっているのは、 ターミナル・ファイルシステム・ブラウザを Agent から呼び出せるツールに変えることだ。 コードを生成するだけでなく、 実行と検証まで担う。
Cursor Agent や Copilot との違いはそこにある。 後者は基本的にエディタ中心の設計だ。 OpenHands のゴールはもっと直接的: モデルに、 起動でき・分離でき・観察できる開発環境を丸ごと渡してしまうこと。
Devin との比較では、 これがオープンソースである点が大きい。
AutoGPT との比較では、 Runtime・Controller・イベントバス・SDK・Docker デプロイ経路がそろっており、 工業レベルに達していると言っていい。
使い方
もっとも手軽なのは、 ローカルで OpenHands を起動する方法だ:
docker run -d \
-p 3000:3000 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v ~/.openhands:/root/.openhands \
--name openhands \
ghcr.io/openhands/openhands:latest
起動後、 http://localhost:3000 を開く。
ホスト側は Web UI、 API、 Agent 制御を受け持つ。 実際にコマンドを実行するコードはデフォルトで別コンテナ (Docker サンドボックス) 内で動く。
もう 1 つ、 自動化タスク向けに Python SDK を使う方法もある。 以下は SDK 呼び出しの基本形だ:
from openhands import OpenHandsAgent
agent = OpenHandsAgent(
llm_model="claude-3-5-sonnet",
workspace="./demo-project",
runtime="docker"
)
task = "src/main.py のゼロ除算バグを修正し、tests/ 配下のテストを全部通す"
result = agent.run(task, max_steps=20)
print("ステータス:", result.status)
print("変更ファイル:", result.modified_files)
print("テスト出力:", result.test_output)
このコードは 3 つのことを示している:
workspaceで操作対象のリポジトリを指定する。runtime="docker"で実行環境を指定する。max_steps=20で Agent の行動上限を設けて無限ループを防ぐ。
SDK の価値は「コードと対話する」だけにとどまらない。 バッチ処理、 CI 補助、 社内タスクキューにも組み込める。
モデル設定のデフォルトは Anthropic または OpenAI のクラウド API。 クラウド API を使わない構成では、 Ollama や vLLM に切り替えてローカルでモデルを動かすこともできる。
バージョン差異には注意してほしい。 モデル名も SDK の API もプロジェクト更新とともに変わる。 デプロイ前に必ず、その時点の README・サンプル・インストール後のインターフェース定義を確認すること。 古い記事のモデル名をそのままコピーしない方がいい。
アーキテクチャ
OpenHands の中核は 3 層に分解できる。
Runtime: Agent の手足
Runtime は実際の実行環境だ。
主要コードは openhands/runtime/ にある。 デフォルトは Docker 分離 をベースに、 Agent に 3 種類の基本能力を提供する:
- シェルコマンドの実行
- ファイルの読み書きと編集
- ブラウザの操作
この 3 つのプリミティブだけでも、 大半の開発タスクはカバーできる。 依存パッケージのインストール、 コード修正、 サービス起動、 ページのエラー確認などを組み合わせて完結できる。
Runtime には多言語拡張の余地もあり、 Python、 Node.js、 Go などのプロジェクトに対応できる。 実際に使える能力は Runtime 種別とプラグイン構成に依存する。
この層で最も重要な設計は分離だ。 モデルから見えるのは制限されたワークスペースだけ。 ホスト本体を Agent に直接晒してはいけない。
Agent: 次の一手を決める
Agent コントローラはタスク状態・計画・記憶・ツール呼び出しを管理する。
主要コードは openhands/controller/agent/ にある。
プロンプトを受け取って即座に答えを出すのではなく、 アクションの連鎖を保持する:
- 現在のリポジトリとタスク状態を観察する
- ツールを 1 つ選ぶ
- 引数を渡して実行する
- コマンド出力やエラーを読む
- 計画を更新して次のステップへ進む
典型的な Agent ループは ReAct に近い。 Reasoning と Acting が交互に走る。 アクションの前には必ず判断し、 アクションの後は必ずフィードバックを読む。
ここが、 Agent とスクリプトジェネレータの本質的な違いだ。 スクリプトジェネレータはテキストを出すだけ。 Agent はツールが返してきた現実の結果を消費する。
OpenHands は Action Space のカスタマイズにも対応している。 開発者は新ツールを登録し、 引数・返り値・実行方法を定義したうえで Agent に渡せる。
たとえば「社内 API ドキュメントを検索する」ツールや「本番のエラーログを引く」アクションを追加できる。 ツールの境界が明確になって初めて、 Agent は本物のシステムを触る資格を得る。
LLM: 推論だけを担当
3 層目が LLM だ。
LLM は Issue を理解し、 diff を分析し、 どのツールを呼ぶかを決める。 ただし、 コマンド実行・ファイル書き込み・ブラウザ操作はモデルサーバ側では起きず、 Runtime 側で実行される。
この分離は重要だ。
シェル・エディタ・ブラウザを全部プロンプトに詰め込むと、 権限の境界が曖昧になる。 OpenHands はこれらを制御されたツールとして実装する。 モデルは登録済みのアクションしか選べず、 Runtime がそれを実行する。
イベントバス: プロセスを可視化する
Agent の各アクションと結果はイベントとして流れる。 フロントエンドは WebSocket で更新を受け取る。
次のような情報が見える:
- 今どのファイルを読んでいるか
- どんなコマンドを実行したか
- コマンドが失敗したかどうか
- どのファイルを編集したか
- テスト出力の内容
- 現在が計画・実装・検証のどの段階か
この可視性はデモ目的だけではない。 Agent が本当に問題を修復しているのか、 それともループにハマったのかを開発者が判断する手がかりになる。
強みと弱み
OpenHands の強みは明快だ。
第 1 に、 完全オープンソースである点。
プロジェクトは MIT ライセンス で、 商用利用・改変・セルフホストが可能。 Cursor や Copilot に縛られたくない小規模チームにとって、 社内の Agent インフラ基盤の候補になる。
第 2 に、 サンドボックス分離が比較的しっかりしている点。
コマンド・ファイル編集・ブラウザ操作はすべて Runtime に閉じ込められる。 モデルがホスト本体に勝手に触れることはない。
第 3 に、 Action Space を拡張できる点。
社内ビルドシステム、 コード検索サービス、 DB クエリツールなどを、 制御されたインターフェースで接続できる。
第 4 に、 評価基盤がある点。
OpenHands は SWE-bench Verified でも、 オープンソースプロジェクトの中で長い間トップグループを維持してきた。 2024 年の大半は、 オープンソース系 Agent のリードポジションにいた。 具体的なスコアはモデル・コミットバージョン・評価構成で変わるため、 別日の結果を単純に比べても意味はない。
課題も現実的だ。
ローカルデプロイはリソースを食う。 サービス本体、 モデル、 サンドボックスを全部動かすため、 CPU・メモリ・ディスクともに軽くない。 デフォルト環境でも 8GB 以上のメモリを用意しておくと安心だ。
クラウド API が依然として主流の経路だ。 Ollama や vLLM も使えるが、 小さなモデルはリポジトリ全体の理解・ツール選択・失敗からの復旧で性能が落ちやすい。
中国系モデルへの適応はまだ発展途上だ。 OpenHands の公式設定は通常、 Anthropic や OpenAI などのサービスを優先している。 中国のネットワーク環境下では、 DeepSeek や Qwen (通義千問) などを使った方が安定することが多い。
複数ファイルにまたがる複雑なリファクタリングもループに陥りやすい。 ファイルを連続で間違える、 テストが外部サービスに依存する、 コマンドが何度もタイムアウトする、 といったケースだ。 max_steps は被害を抑止できるだけ で、 誤った計画を自動回復する仕組みではない。
試してみた
わざとバグを仕込んだ Python プロジェクトで小さなテストを行った。 ゴールはシンプルで、 ゼロ除算を直して tests/ 配下のテストを全部通すこと。
手順は次のとおり:
- Docker で OpenHands を起動する
- Claude 3.5 Sonnet を接続する
- リポジトリをワークスペースにマウントする
- 「ゼロ除算バグを特定し、 修正してテストを実行する」を投げる
Agent はまず src/main.py を検索し、 除数がゼロになる分岐を特定した。
そのまま commit はせず、 修正後に pytest を実行。 テストが通ったのを確認し、 diff も確認した。
設定したステップ上限は 20 だが、 実際には使い切らなかった。
途中で requests をインストールしようとした。 サンドボックスから外向きのネットワークを開放していなかったためインストールに失敗。 Agent はエラーを読んだうえで再試行せず、 Python 標準ライブラリの urllib に切り替えた。 最終的にテストは通り、 ローカル commit も生成された。
同じタスクを DeepSeek-V3 でも試した。
結論は 3 点:
- 完了できる。 単なるコードサンプルではない。
- 速度は明確に遅い。 同じタスクで、 体感で約 40% ほど時間がかかった。
- 簡単な修正では失敗しない。 複雑なリファクタリングでは、 Claude や GPT-4o に比べてモデルの安定性がまだ落ちる。
これは厳密なベンチマークではなく、 同じコンテナ・同じタスク・同じステップ上限という条件下での体験比較にすぎない。 接続方式として機能することは示せるが、 モデルランキングとして読むのは誤りだ。
中国圏ユーザーがよく踏む落とし穴
1 つ目の落とし穴は、 Docker イメージのプルが遅いことだ。
ghcr.io のイメージサイズは大きく、 ネットワークが不安定だと簡単に詰まる。 事前に固定バージョンをプルしておき、 Docker Hub のミラーを設定し、 OpenHands イメージには明示的なタグを付けておきたい。
あいまいな latest を常用するのは避けるべきだ。 アップグレードによって Runtime の挙動・API パラメータ・ツール出力が変わる可能性がある。
2 つ目の落とし穴はモデル API だ。
Anthropic、 OpenAI のサービスは、 中国の一部ネットワーク環境で遅延が大きく、 接続も不安定になりがちだ。 実測では DeepSeek や Qwen (通義千問) に切り替えた方が安定する。
モデル名は雰囲気で書かないこと。 必ずそのバージョンのモデル設定画面とコードを基準にする。 旧モデルの中にはすでに提供終了しているものもあり、 一部サービスでは個別のパラメータ互換対応が必要になる。
3 つ目の落とし穴は権限だ。
Docker Runtime を使うため、 一般的な起動方式ではホストの Docker ソケットをコンテナにマウントする。 便利だが権限が大きすぎる。
本番環境で開発設定を丸ごとコピーしないこと。 コンテナの権限を絞り、 リモート Runtime に切り替え、 社内サービスには短期の認証情報を割り当てるべきだ。
4 つ目の落とし穴はワークスペースの永続化だ。
デフォルトのサンドボックスは永続ワークスペースではない。 コンテナの再生成やサービス再起動の後には、 一時ファイルが失われる可能性がある。
コードを保持したい場合は永続ボリュームをマウントする。 commit・PR・タスク履歴まで残したい場合は、 外部の Git サービスやオブジェクトストレージを併用する。
どんな人に向くか
OpenHands は次の 3 タイプに合う。
小規模チーム。 社内向け AI コーディングアシスタントを構築したいが、 Cursor や Copilot に依存したくないケース。 Docker・モデル・社内ツールの保守をできる人がいる前提。
Agent エンジニア。 Runtime・Controller・ツールプロトコル・イベントフローのソースを読みたい人。 OpenHands のコードは多くのデモプロジェクトよりはるかに本番システムに近い。
評価研究者。 SWE-bench 系のタスクを回したい、 もしくはモデルごとのリポジトリ単位の修復能力を比較したい場合。 Runtime・Action Space・イベントログはすべて実験に使える。
逆に、 次の 3 タイプにはあまり向かない。
設定ファイルを一切書きたくないユーザー。 数行の補完だけでいいなら Cursor や Copilot の方が手っ取り早い。
完全オフラインを強く求める人。 ローカル推論には GPU・モデル適応・潤沢なメモリが要る。 中国製ハードウェア上でのツール呼び出しの安定性には、 個別のチューニングがまだ必要だ。
機密性の高いコードを扱い、 隔離設定をやりたくない人。 サンドボックス・ボリューム・ネットワークポリシー・認証情報の管理は自分たちで担保する必要がある。 デフォルトで安全というだけで、 デプロイ環境を疎かにしてよいわけではい。
「AI がリポジトリを編集できるか」だけで見れば、 OpenHands はすでに実現可能だと証明している。
実際の効果を左右するのは結局 3 つの要素だ。 モデルがきちんと計画を立てられるか、 Runtime が十分に制御可能か、 ツールの出力が Agent のエラー訂正に役立つか。
無監視で本番クリティカルな業務に投入する段階にはまだない。 しかし、 改造可能で・観察可能で・社内ツールに接続できるエンジニアリング Agent を組みたいなら、 OpenHands はオープンソース界隈でいまなお分解して眺める価値のあるプロジェクトだ。