【2026年4月】OpenHands完全ガイド｜OSSコーディングAgent実装

Devinが登場した2024年春、「AIがソフトウェアエンジニアを代替する」という議論が世界中で巻き起こった。しかしDevinは月額500ドル（現在は20ドル〜）の商用SaaSだ。その3か月後にGitHubに現れたのがOpenDevin（現：OpenHands）だった。

OSSで、自分のLLMキーで動き、Dockerで隔離されたサンドボックス環境で自律的にコードを書く。2026年4月現在、同プロジェクトはAll-Hands-AI組織のもとでGitHub stars 70K+、コントリビューター500名近くまで成長している。バージョン1.6では Planning Mode と Kubernetes サポートが追加され、個人開発者から企業のCI/CD組み込みまで対応できる成熟度に達した。

本記事では、ローカルセットアップからPython SDKを使った高度な自動化、Devin・Claude Codeとの実践的な比較まで、必要なものをすべてまとめた。

OpenHandsとは何か — 旧OpenDevinから現在まで

OpenHandsは、AIエージェントがコードを書き、ターミナルコマンドを実行し、ウェブを閲覧し、GitHubにPRを送るまでを完全自律で行うOSSプラットフォームだ。コアコンセプトは「人間のソフトウェアエンジニアがやることを全部やる」こと。

元々は2024年3月にOpenDevinとして公開され、同年後半にAll-Hands-AIが法人化、プロジェクト名をOpenHandsに変更した。現在のリポジトリは github.com/OpenHands/OpenHands（旧 All-Hands-AI/OpenHands）で、Dockerイメージは docker.openhands.dev でホストされている。

アーキテクチャの概要

コンポーネント	役割	実装
Runtime Sandbox	コード実行の隔離環境	Docker コンテナ（DockerOutsideDocker構成）
Agent	LLMに基づく意思決定ループ	CodeActAgent（デフォルト）
LLM Bridge	任意のLLMへの接続	LiteLLM経由（100+モデル対応）
Microagents	ドメイン特化の知識注入	Markdownファイル（repo内 .openhands/）
Event Stream	エージェント行動の記録・再現	JSONLファイル or DB

重要なのはCodeActAgentという設計だ。LLMが単にコードを「提案」するのではなく、実際にシェルコマンドを実行し、その結果を受け取り、次のアクションを決める。このループが閉じていることで、自律的な問題解決が可能になる。

5分セットアップ — ローカル環境で動かす3つの方法

公式が推奨する順序はuv → pip → Dockerの3択だ。以下にそれぞれのコマンドを示す。

方法1：uv（最推奨・最速）

# 動作環境: macOS / Ubuntu 22.04+ / WSL2
# 前提: Python 3.12+, uv 0.11.6+

# uvのインストール（未インストールの場合）
curl -LsSf https://astral.sh/uv/install.sh | sh

# OpenHandsをインストールしてサーブ
uv tool install openhands --python 3.12
openhands serve

# GPUサポートが必要な場合
openhands serve --gpu

# 現在のディレクトリをマウントする場合
openhands serve --mount-cwd

コマンド実行後、http://localhost:3000 を開き、Settings からLLMプロバイダー（Claude / OpenAI 等）とAPIキーを設定する。

方法2：pip

# 動作環境: Python 3.12+, Docker起動済み
pip install openhands
openhands serve

方法3：Docker直接実行（インフラチーム向け）

# Docker Desktop が起動していることを確認
# macOS: 設定 → Advanced → "Allow the default Docker socket to be used" を有効化

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.15.0-python \
  -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.openhands.dev/openhands/openhands:1.6

どの方法でも http://localhost:3000 でUIが立ち上がる。Dockerはポータビリティが高く、チーム共有やCI環境への組み込みに向いている。

Python SDK で自動化する — 実装サンプル集

UIだけでなく、PythonコードからOpenHandsエージェントを呼び出せる。これがOpenHandsをパイプラインに組み込む際の核心だ。

基本パターン：タスクをエージェントに投げる

# 動作環境: Python 3.12+, pip install openhands
# 必要な環境変数: LLM_API_KEY (Anthropic / OpenAI など)

import os
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.task_tracker import TaskTrackerTool
from openhands.tools.terminal import TerminalTool

# LLMの設定 — LiteLLM形式でモデルを指定
llm = LLM(
    model="anthropic/claude-sonnet-4-5-20250929",
    api_key=os.getenv("LLM_API_KEY"),
)

# エージェントの初期化
agent = Agent(
    llm=llm,
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
        Tool(name=TaskTrackerTool.name),
    ],
)

# 会話（= タスクセッション）を作成して実行
cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)
conversation.send_message("auth.py の単体テストをpytestで書いてください。")
conversation.run()

CLIのヘッドレスモード：CI/CDパイプラインへの組み込み

# 動作環境: openhands CLI インストール済み
# LLM_API_KEY 環境変数が必要

# 単一タスクをヘッドレスで実行
openhands --headless -t "リポジトリのREADMEを日本語に翻訳してください"

# 複数のタスク指示をファイルから読み込む
openhands --headless -f tasks/sprint-tasks.md

# JSON形式で出力（CI/CDからのパース用）
openhands --headless --json -t "依存パッケージを最新版に更新してください"

Microagentによるリポジトリ固有の知識注入

# .openhands/microagents/repo.md
---
name: my-project-context
type: repo
---

このリポジトリは Django + PostgreSQL で構築された SaaS 製品です。
- テストは `pytest` で実行します: `pytest tests/ -v`
- マイグレーションは必ず `python manage.py makemigrations` の後に `migrate` します
- コードスタイル: `black` と `isort` を必ず通してください
- PRを作る前に `mypy src/` でタイプチェックしてください

このMarkdownファイルをリポジトリの .openhands/microagents/ に置くだけで、OpenHandsが自動的に読み込みプロジェクト固有のルールに従って動作する。Devinの「Playbooks」機能と同等だが、完全にOSSかつバージョン管理できる。

GitHub Actions連携：PR自動レビュー

# .github/workflows/openhands-review.yml
name: OpenHands PR Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  agent-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run OpenHands Agent
        run: |
          pip install openhands
          openhands --headless --json \
            -t "このPRの変更を確認し、バグ・セキュリティ問題・パフォーマンス問題があればコメントしてください" \
            > review_output.json
        env:
          LLM_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Post Review Comment
        run: |
          python scripts/post_github_comment.py review_output.json
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

OpenHands vs Claude Code vs Devin — 実践比較

「どれを使えばいいか」が最も多い質問だ。結論から言えば、ユースケースと運用体制で使い分けるのが正解だ。

スペック比較表

項目	OpenHands	Claude Code	Devin
ライセンス	MIT（完全OSSe）	クローズドSaaS	クローズドSaaS
料金	LLM APIコストのみ	Max $100/月 or API従量	$20/月 + $2.25/ACU
1タスクコスト目安	$0.15〜$0.60	$0.10〜$0.80	$2〜$9（15〜60分タスク）
動作環境	セルフホスト	ローカルターミナル	クラウドSaaS
SWE-bench Verified	53%+（Claude 4.5時）	未公開（比較困難）	約55%（公式発表）
UIの有無	ブラウザUI + CLI	CLIのみ	ブラウザUI
カスタム知識注入	Microagents（MD）	CLAUDE.md	Playbooks
データプライバシー	完全自社管理可	Anthropic送信あり	Cognition送信
GitHub PR作成	ネイティブ対応	対応（要gh CLIe）	ネイティブ対応
CI/CD統合	Docker/K8s対応	Actions対応	限定的

※料金は2026年4月時点。SWE-bench Verifiedスコアはモデルバージョン・プロンプト設計によって変動する。

ユースケース別のおすすめ

状況	推奨	理由
データが社外に出せないエンタープライズ	OpenHands	完全セルフホスト、監査ログ残る
個人開発者・スタートアップ	Claude Code	セットアップ0分、ターミナル統合が自然
非技術者チームのタスク依頼	Devin	ブラウザUIが直感的、Playbooksで運用定型化
大量タスクをCI/CDで自動化	OpenHands	Docker/K8sスケール、コスト予測しやすい
即座にコードを書いてほしい（対話型）	Claude Code	ターミナルで即レスポンス

コスト試算 — 月100タスク運用した場合

「OpenHandsは本当に安いのか」を具体的に試算する。前提条件：1タスク＝中規模のバグ修正・機能追加（約30分相当の作業）。

ツール	月100タスクのコスト試算	内訳
OpenHands + Claude Sonnet 4	$15〜$60	LLM APIコストのみ（$0.15〜$0.60/タスク）
OpenHands + GPT-4o	$20〜$80	LLM APIコストのみ
Devin	$245〜$920	基本料金$20 + $2.25 × 100ACU〜400ACU
Claude Code (Maxプラン)	$100〜	Maxプラン固定費 + 超過時の従量

注意点：OpenHandsのコストにはインフラ費用（EC2/GCE等の実行環境）が含まれていない。セルフホストの場合、サーバー代が別途かかる。また、設定・メンテナンスの人件費も「隠れコスト」として考慮が必要だ。

Dockerコンテナをクラウドで常時起動する場合のインフラコスト目安

# AWS EC2 t3.medium (2vCPU, 4GB) — OpenHands推奨最小スペック
# 東京リージョン オンデマンド: 約$0.052/時間 = 約$38/月

# GCP e2-standard-2 (2vCPU, 8GB)
# 東京リージョン: 約$0.067/時間 = 約$49/月

# 月100タスクの総コスト（OpenHands + Claude Sonnet 4 + EC2 t3.medium）
# LLM: $15〜$60 + インフラ: $38 = 計$53〜$98/月
# Devinと比べると: Devin $245〜$920 vs OpenHands $53〜$98

よくある失敗パターンと回避策

失敗1：Dockerソケットのパーミッション問題

OpenHandsはDocker-outside-Docker構成で動く。Dockerソケット(/var/run/docker.sock)へのアクセス権がないと起動しない。

❌ よくある間違い：Dockerを起動せずに openhands serve を実行する

⭕ 正しいアプローチ：

# Dockerの起動確認
docker ps

# macOSの場合: Docker Desktop → 設定 → Advanced
# "Allow the default Docker socket to be used" を有効化

# Linuxの場合: ユーザーをdockerグループに追加
sudo usermod -aG docker $USER
newgrp docker

失敗2：LLMのコンテキスト超過によるタスク失敗

❌ よくある間違い：大規模リポジトリ全体の解析を1タスクで依頼する

⭕ 正しいアプローチ：タスクを分割し、Microagentで必要なコンテキストのみ注入する

# .openhands/microagents/scope.md
---
name: scope-limiter
type: repo
---

タスクを実行する際は以下のディレクトリのみを対象にしてください:
- src/api/ — APIエンドポイント
- src/models/ — データモデル
- tests/unit/ — ユニットテスト

src/legacy/ や docs/ は変更しないでください。

失敗3：Planning Modeを使わずに複雑タスクを実行する

v1.5.0で追加されたPlanning Modeを使わずに、複数ファイルにまたがる大きな機能追加を依頼すると、エージェントが迷走して途中でループする。

❌ よくある間違い：「認証機能を丸ごと実装してください」と1発で投げる

⭕ 正しいアプローチ：Planning Modeをオンにしてタスク計画を先に作らせる

# UIの場合: Settings → Agent → "Enable Planning Mode" をオン
# CLIの場合:
openhands --headless --planning-mode \
  -t "JWTベースの認証機能を実装してください。まず計画を立ててから実行してください"

FAQ

Q: OpenHandsはどのLLMでも動きますか？
A: LiteLLM経由で100以上のモデルに対応している。Claude (Anthropic)、GPT-4o (OpenAI)、Gemini (Google)、Qwen、ローカルのOllamaモデルも使える。パフォーマンスはモデルによって大きく異なり、SWE-bench Verifiedで53%+を出すにはClaude 4.5やGPT-4o相当の高性能モデルが必要だ。

Q: Devinからの移行は難しいですか？
A: DevinのPlaybooksに相当する機能がOpenHandsのMicroagentsだ。Playbooksの内容を .openhands/microagents/ 以下のMarkdownに書き直すだけで移行できる。UIの学習コストは1〜2時間程度。

Q: セキュリティ上の懸念はありますか？
A: エージェントはDockerコンテナ内で動くため、ホストシステムへの直接アクセスはない。ただし、エージェントがシェルコマンドを実行する権限を持つため、機密リポジトリで使う際は実行前の確認ステップを設けることを推奨する。Microagentの require_human_approval: true フラグでデプロイ等の破壊的操作に承認ステップを追加できる。

Q: OpenHands Cloudとセルフホストの違いは？
A: OpenHands Cloudは openhands.dev で提供されるマネージドサービスで、インフラを自分で用意しなくていい。ただし2026年4月時点ではベータ扱い（2025年11月にベータ公開発表）。セルフホストはデータを自社管理できるが、メンテナンス責任が発生する。

Q: Claude CodeとOpenHandsを使い分けるコツは？
A: インタラクティブなコーディング（リアルタイムでAIと対話しながら書く）はClaude Code、バッチ処理や夜間の自動タスク実行はOpenHandsという使い分けが実用的だ。両者は競合というより補完関係にある。

参考・出典

• OpenHands GitHubリポジトリ（All-Hands-AI, 2026年4月確認）
• OpenHands ローカルセットアップ公式ドキュメント（docs.openhands.dev, 2026年4月確認）
• OpenHands Software Agent SDK ドキュメント（docs.openhands.dev, 2026年4月確認）
• OpenHands v1.6.0 リリースノート（GitHub, 2026年3月30日）
• Introducing the OpenHands Index（openhands.dev, 2026年1月28日）
• SWE-bench Leaderboard（swebench.com, 2026年4月確認）

まとめ：今日から始める3つのアクション

1. 今日：uv tool install openhands --python 3.12 && openhands serve を実行して、http://localhost:3000 を開く。ClaudeかOpenAIのAPIキーを設定し、小さなバグ修正タスクを1つ投げてみる
2. 今週中：リポジトリに .openhands/microagents/repo.md を作成し、プロジェクト固有のルール（テストの実行方法、コーディング規約）を記述する。エージェントの挙動が格段に改善する
3. 今月中：GitHub Actionsに組み込み、PRのレビューを自動化する。月100タスク規模になったらコスト試算を見直し、Devin・Claude Codeとのハイブリッド運用を検討する

あわせて読みたい：Pipecat完全ガイド｜音声AIエージェント実装 / OpenAI Agents SDK完全ガイド｜実装とコスト試算 / E2B・Daytona・Modal完全比較｜AI実行環境選定

---