OpenHandsを自己ホストできるAIコーディングエージェントとして見ると、最初に気になるのは「Claude CodeやCodexの代わりになるか」かもしれません。ただ、実務導入で先に決めるべきなのは、性能比較よりも権限境界です。
OpenHandsは、コマンドを実行し、ファイルを編集し、開発サーバーを起動し、LLMや外部サービスとつながる前提のツールです。便利なぶん、実行環境、workspace mount、APIキー、ネットワーク、Skills/AGENTS.md、SDK組み込みの境界を曖昧にしたまま入れると、あとから「どこまで許していたのか」が見えなくなります。
この記事では、公式情報を2026年6月7日に確認したうえで、OpenHandsを自己ホストまたはローカル導入する前の許可設計を整理します。OpenHands全体の導入像は、既存記事の<a href="https://ai-dev.blog.mo-gmo.com/openhands-docker-sandbox-sdk-microagents-self-hosted-agent/">OpenHandsをself-hosted agentとして使う前に</a>で扱っています。この記事ではそこから一段狭く、権限境界と許可マトリクスに集中します。
3行まとめ
Docker、Process、Remoteを安全か危険かで決めず、hostとの距離、secret、監査ログ、運用責任で分けます。
AGENTS.mdやSkillsは権限管理そのものではなく、agentに読ませる作業ルールとして設計します。
ファイル操作、コマンド実行、ネットワーク、外部API、LLM/APIキーの許可範囲を最初に決めます。
OpenHandsを使えるかではなく、どの条件なら使ってよいかを先に決めると判断しやすくなります。
- OpenHands導入前は、Docker sandbox、Process sandbox、Remote sandboxを「安全か危険か」ではなく、hostとの距離、secretの渡し方、監査ログ、運用責任で分ける。
- SkillsやAGENTS.mdは権限管理そのものではなく、エージェントに読ませる行動ルールです。実際の防御はmount、network、token scope、人間承認、review gateで設計する。
- 自己ホストで使うなら、最初に「ファイル操作」「コマンド実行」「ネットワーク」「外部API」「LLM/APIキー」の許可マトリクスを作り、チームpilotから本番隣接運用へ段階的に広げる。
この記事でわかること
Docker sandbox、Process sandbox、Remote sandboxを、作業範囲と運用責任で比較します。
OpenHandsのDocker sandboxとDocker社のDocker Sandboxesを別の話として整理します。
指示ファイルに書く内容と、権限設定側で止める内容を分けます。
Software Agent SDKを使うと、tool許可、ログ、停止条件、APIキー管理がアプリ側の責任になります。
個人検証、チームpilot、本番隣接運用で、許可、保留、禁止を切り分けます。
機能紹介にとどめず、AIコーディングエージェントに渡す権限境界を決めるための整理です。
- OpenHandsのDocker sandbox、Process sandbox、Remote sandboxをどう選び分けるか。
- OpenHandsの「Docker sandbox」とDocker社の「Docker Sandboxes」を混同しないための見方。
- Skills/AGENTS.mdに何を書き、何を権限設定側で止めるべきか。
- Software Agent SDKでOpenHandsを組み込むと、アプリ側にどの責任が移るか。
- 個人検証、チームpilot、本番隣接運用で、どの操作を許可、保留、禁止にするか。
前提知識
Docker、Process、Remoteのどこでagent serverを動かすかを決めます。
どのdirectoryを読める、書ける、消せる状態にするかを決めます。
install、test、build、server起動、migration、deployをどこまで許すかを決めます。
接続先、API、credential、token scopeを作業単位で分けます。
Skills、AGENTS.md、SDK、agent serverの責任を混ぜずに扱います。
この5つを分けると、導入判断を機能の有無ではなく条件の設計として扱えます。
OpenHandsは、AI-driven development向けのコミュニティ/プロダクト群として、Agent Canvas、Cloud、Enterprise、CLI、Software Agent SDKなど複数の使い方を持っています。公式Introductionでは、SDKはOpenHandsのagentic techを含むPython libraryで、エージェントをコードで定義し、ローカル実行やクラウドでのスケールに使えると説明されています。
見落としたくないのは、OpenHandsを単なるチャットUIとして見ないことです。AIコーディングエージェントは、コードを読むだけではなく、shell command、file edit、server起動、外部API、GitHub連携を扱います。導入判断は、次の5つを分けるところから始まります。
| 境界 | 決めること | 先に起きやすい誤解 |
|---|---|---|
| 実行環境 | Docker、Process、Remoteのどこでagent serverを動かすか | Dockerなら自動的にすべて安全だと思う |
| ファイル操作 | どのdirectoryを読める、書ける、消せる状態にするか | repoを渡したらrepo外には触れないと思う |
| コマンド実行 | install、test、build、server、migration、deployを許すか | テストだけのつもりで状態変更を許す |
| ネットワークとsecret | どのdomain、API、credentialを渡すか | AGENTS.mdに禁止を書けば漏れないと思う |
| 指示とSDK | Skills/AGENTS.md、SDK、agent serverの責任を分けるか | 指示ファイルを権限管理機能として扱う |
この5つを分けると、OpenHandsを「使えるか」ではなく、「どの条件なら使ってよいか」で判断できます。
結果: 最初はDocker sandboxを基準にし、Process sandboxは例外扱いにする
Docker sandboxを選んでも、read-writeでmountしたworkspaceはagentが変更できるため、mount設計は必ずレビュー対象です。
OpenHands公式のsandbox overviewでは、OpenHands V1のsandboxを、エージェントがコマンド実行、ファイル編集、server起動を行う環境として説明しています。選択肢はDocker sandbox、Process sandbox、Remote sandboxです。
実務導入の初期判断としては、Docker sandboxを基準にし、Process sandboxは短期の個人検証やDockerが使えない環境の例外に置くのが扱いやすいです。理由は単純で、Process sandboxはhost上の通常プロセスとしてagent serverを動かすため、公式ドキュメントでも隔離がないと説明されているからです。
Docker、Process、Remoteの比較
根拠
| sandbox | 公式情報上の位置づけ | 向いている場面 | 先に決めること |
|---|---|---|---|
| Docker sandbox | OpenHandsをローカルで動かす推奨候補。agent serverをDocker container内で動かす | 個人検証、チームpilot、外部repoの検証 | mount範囲、write権限、network、secret注入、port公開 |
| Process sandbox | host上の通常プロセスとしてagent serverを動かす。隔離はない | Dockerが使えない短期検証、再現確認、debug | hostのcredential、shell profile、未commit変更、破壊的command |
| Remote sandbox | remote environmentでagent serverを動かす | 管理された環境、チームでの再現性、ローカル汚染回避 | credential管理、ログ保存、社内network接続、ユーザー分離 |
Docker sandboxを選んでも、AIが編集できるworkspaceを広くmountすれば、その中のファイルは変更されます。公式Docker sandboxページでも、read-writeでmountしたworkspaceはagentに変更され得ることが説明されています。ここを読み落とすと、Dockerを使ったのに意図しない差分が出る、という失敗につながります。
まず決める最小方針
確認項目
最初のpilotでは、次のように切るとレビューしやすくなります。
| 項目 | 初回の推奨 | 広げる条件 |
|---|---|---|
| repository | 検証repo、public repo、または小さなprivate repo | AGENTS.mdとreview gateが整った後 |
| workspace | 作業対象directoryだけ | package全体やmonorepoへ広げる時はownerを決める |
| secret | 渡さない | read-only tokenから始め、scopeとログを確認する |
| network | 公式docs、package registry、LLM providerなど最小限 | MCP serverや社内APIは別レビュー |
| command | test、lint、buildまで | migration、deploy、sudo、git pushは人間承認 |
この方針は、OpenHands固有というよりAIコーディングエージェント全般の初期設定です。チームでAGENTS.mdを整える場合は、<a href="https://ai-dev.blog.mo-gmo.com/team-agents-md-template-codex-claude-code-cursor-permissions-tests/">チーム向けAGENTS.mdテンプレート</a>の記事も合わせて見ると、禁止操作やテスト手順の書き方をそろえやすくなります。
Docker sandboxを基本候補にする理由と限界
- 1agent server
OpenHandsのagent serverをDocker container内で動かし、host上の通常プロセスから距離を取ります。
- 2workspace mount
作業対象をworkspaceとして渡します。read-writeで渡したpathは変更され得ます。
- 3network
外部接続を広く許すと、package取得やAPI連携だけでなく情報流出の経路も広がります。
- 4secret
環境変数やtokenを渡した場合、そのtaskの実行環境に入る前提で扱います。
- 5Docker daemon
hostのDocker socketを渡す設計は強い権限につながるため、別の隔離層として見ます。
OpenHandsのDocker sandboxとDocker社のDocker Sandboxesは別物として読み、どの隔離層を使っているかを確認します。
OpenHandsのDocker sandboxは、agent serverをDocker container内で動かす構成です。公式ドキュメントでは、Docker sandboxがローカル実行の推奨候補であり、Dockerがdefaultであること、openhands serve --mount-cwdで現在のdirectoryをsandbox workspaceにmountできることが説明されています。
ここで注意したいのは、OpenHandsのDocker sandboxと、Docker社が提供する「Docker Sandboxes」は別物として読む必要がある点です。
OpenHandsのDocker sandbox
根拠
OpenHandsのDocker sandboxは、OpenHandsのagent server実行環境の話です。ポイントは、hostから距離を取りつつ、作業対象をworkspaceとして渡すことです。
確認用のコマンド例は次のような形になります。
openhands serve --mount-cwdまた、環境によっては SANDBOX_VOLUMES でmountを指定できます。
export SANDBOX_VOLUMES="$PWD:/workspace:rw"この例で重要なのは、rw で渡したworkspaceはagentが変更できるという点です。Dockerを使っていても、workspace内の削除、rename、大量生成、設定ファイル変更は起こり得ます。したがって「Dockerに入れたから安全」ではなく、「どのpathをread-writeで渡したか」をレビュー対象にします。
Docker社のDocker Sandboxes
注意点
Docker公式のDocker Sandboxesは、AI coding agentをisolated microVM sandboxで動かす製品/機能として説明されています。各sandboxが独自のDocker daemon、filesystem、networkを持ち、host systemに触れずにcontainer buildやpackage installを実行できる、という位置づけです。
Dockerのisolation layersでは、hypervisor、network、Docker Engine、workspace、credential proxyなどの層が説明されています。特に、agentにhostのDocker socketを渡すのではなく、sandbox内のDocker Engineを使わせる考え方は、AI agent運用では重要です。host Docker daemonに触れる権限は、実質的にhost全体へ強い影響を持つからです。
ただし、Docker SandboxesはDockerの提供機能であり、OpenHandsの標準Docker sandboxと同一ではありません。記事や社内メモで「Docker sandbox」とだけ書くと、どちらを指しているのか曖昧になります。導入設計書では、次のように名前を分けて書くのが安全です。
| 表記 | 指すもの | レビュー観点 |
|---|---|---|
| OpenHands Docker sandbox | OpenHandsのagent serverをDocker containerで動かす構成 | mount、container image、port、env、workspace |
| Docker Sandboxes | Docker社のAI agent向けmicroVM sandbox機能 | microVM、policy、credential proxy、network、subscription |
| Remote sandbox | OpenHands側でremote environmentを使う構成 | tenant分離、ログ、secret、network、運用責任 |
Dockerだけでは防げない範囲
残るリスク
Dockerを使っても、次のリスクは残ります。
- read-writeでmountしたworkspaceは変更される。
- agentに渡した環境変数やAPIキーは、agentの行動範囲に入る。
- package installやweb参照を許すと、外部networkへ出る。
- container内で生成された成果物がレビューなしに採用されると、意図しない依存や設定が混じる。
- Docker socket、host volume、privileged実行を許すと、隔離の前提が崩れる。
つまりDockerは、最初の境界を作る手段です。運用上の安全は、mount、token、network、command、reviewを合わせて設計して初めて近づきます。
Process sandboxを選ぶなら何を許しているのか
Process sandboxは短期検証や再現確認には使えますが、チーム標準にする前にhost側の未commit変更とcredentialを確認します。
Process sandboxは、OpenHandsのagent serverをhost上の通常プロセスとして動かす構成です。公式ドキュメントでは、Dockerが使えないlocal development、一部のCI、container外でしか再現しないdebugなどで使う場面が挙げられています。
問題は、便利な代わりにhostとの距離が近いことです。agentは、あなたのuser accountがアクセスできるfile、command、credential、認証済みCLIに近い場所で動きます。
Process sandboxで増えるリスク
比較基準
| 観点 | Docker sandbox | Process sandbox |
|---|---|---|
| file access | mountしたworkspaceが中心 | user accountが触れる範囲に近づきやすい |
| env | containerに渡したものが中心 | shell profileやlocal envの影響を受けやすい |
| CLI credential | 明示的に入れたものが中心 | gh、cloud CLI、package registryなど認証済み状態に近い |
| command | container内で実行 | host上のcommandとして実行され得る |
| rollback | container破棄で戻せる部分がある | host上の変更は個別に戻す必要がある |
Process sandboxを絶対に使ってはいけない、という話ではありません。Dockerが使えない環境で短く挙動を見る、trusted repoで小さな修正を試す、container外でだけ出る不具合を確認する、といった使い方はあります。ただし、チーム導入の標準にする前には、次のチェックを通した方がよいです。
git status --short
git diff --stat
git diff --name-onlyこの3つは、OpenHandsに限らず、AI agentに作業を渡す前の最低限の確認です。未commit変更、secretを含むファイル、生成物、lockfile、環境固有ファイルが混ざっている場合は、agentに渡す前に作業treeを分けます。
Process sandboxの最低ルール
確認項目
Process sandboxを使うなら、AGENTS.mdやチームルールに次のような条件を入れます。
AI agent execution rules:
- Do not edit files outside the repository root.
- Do not read or print secrets, tokens, private keys, or local credential files.
- Do not run deployment, migration, destructive cleanup, or git push commands.
- Before changing files, summarize the planned files and commands.
- After changes, report git diff --stat and test results.
- Stop when authentication, billing, production data, or customer data is required.このルールは防御の最後の層ではありません。あくまでagentの行動を揃える文脈です。実際には、secretを置かない、権限の強いCLIを無効にする、networkを絞る、作業用userを分ける、といった制御が必要になります。
SkillsとAGENTS.mdは権限ではなく行動ルールとして設計する
自然文のルールは必要ですが、実際の防御はmount、network、token scope、人間承認、review gateで設計します。
OpenHandsのSkillsは、domain-specific knowledge、expert guidance、automated task handlingを追加するための仕組みとして説明されています。公式Skills Overviewでは、常時注入されるcontextとしてAGENTS.mdが示され、on-demand skillはkeywordやagent判断で読み込まれるものとして扱われています。
ここで混同しやすいのは、SkillsやAGENTS.mdを「権限管理」として見てしまうことです。この見方は避けたいところです。
Always-on contextとon-demand skillを分ける
使い分け
| 種類 | 使う目的 | 書くべき内容 | 書かないもの |
|---|---|---|---|
| AGENTS.md | repo全体で常に守るルール | repo目的、編集範囲、禁止操作、テスト手順、review基準 | APIキー、private token、個人情報 |
| General Skills | 特定domainの作業ガイド | setup、用語、設計原則、よくある失敗 | secret、社内限定URLの無制限な列挙 |
| Keyword-triggered Skills | 特定taskで呼ぶ手順 | migration手順、review手順、release手順 | 人間承認なしのdeploy手順 |
| task prompt | 今回だけの依頼 | 対象issue、制約、完了条件 | 長期ルール、秘密情報 |
AGENTS.mdに「秘密情報を読まない」と書くのは必要です。ただし、それだけでは安全になりません。agentがそのfileを読める場所にsecretを置いていれば、ミスやprompt injectionで触れる可能性は残ります。AIコーディングエージェントのprompt injection対策は、<a href="https://ai-dev.blog.mo-gmo.com/ai-coding-agent-prompt-injection-issues-docs-mcp-guardrails/">Issue・Docs・MCPを読ませる前に決めること</a>でも扱っていますが、自然文の指示と実際の権限は分けて考えるべきです。
AGENTS.mdに入れる実務項目
確認項目
OpenHands向けにAGENTS.mdを整えるなら、最初は次の7項目で十分です。
- repositoryの目的と主要directory。
- 編集してよい範囲と触ってはいけない範囲。
- 禁止するcommand。
- test、lint、typecheck、buildの実行順。
- secret、credential、個人情報の扱い。
- PRやdiffで人間が確認する観点。
- 失敗時に停止する条件。
たとえば、次のような短いルールから始めます。
Permission boundary:
- Read and edit only files under src/, tests/, docs/, and package metadata needed for the task.
- Do not edit .env, credential files, deployment manifests, or production config without explicit approval.
- Do not run migration, deploy, git push, or destructive cleanup commands.
- Prefer read-only inspection before changing files.
- If external API access is required, stop and ask for human confirmation.この内容は、OpenHandsだけでなくCodex、Claude Code、Cursor、OpenCodeにも転用できます。ツールごとに指示ファイル名や読み込み方は違っても、repo側に置く運用ルールは共通化できます。
Software Agent SDKで責任がどこへ移るか
- 1user input
外部から入る依頼文、issue、PR、社内データをどこまでagentに読ませるかを決めます。
- 2tool許可
file edit、command、browser、GitHub、外部APIの許可範囲をアプリ側で持ちます。
- 3agent lifecycle
開始、停止、timeout、失敗時の中断、再試行、workspace削除を設計します。
- 4APIキー
model provider keyやGitHub tokenを用途別にscope分離し、必要なtaskにだけ渡します。
- 5ログとrate limit
diff、command、失敗ログ、tool call、token usageを監査できる形で残します。
SDKではagentの便利さだけでなく、停止条件、監査、token scope、tenant分離をアプリ側が持つ前提になります。
OpenHands Software Agent SDKは、PythonとREST APIでcode work向けagentを作るためのSDKです。GitHub READMEでは、one-off task、dependency update、multi-agentが必要なrefactorやrewriteなどに使えると説明されています。また、agentはlocal machineをworkspaceにできるだけでなく、Agent Serverを使ってDockerやKubernetesなどのephemeral workspaceでも動かせるとされています。
SDKを使うと、OpenHandsを単に使う側から、自分のアプリやworkflowに組み込む側へ移ります。すると責任も変わります。
UI利用とSDK組み込みの違い
責任分界
| 使い方 | 主な責任 | 見落としやすい点 |
|---|---|---|
| Local GUI / CLI | 作業repo、sandbox、モデル、prompt、review | local credentialや未commit変更 |
| Agent Canvas / Cloud | account、integration、RBAC、予算、共有 | 組織権限とログ保存 |
| SDK組み込み | user input、tool許可、agent lifecycle、APIキー、ログ、rate limit | アプリ側が失敗時停止と監査を持つ |
| Remote Agent Server | workspace生成、tenant分離、network、credential | ユーザーごとの隔離と削除ポリシー |
SDK組み込みで特に重要なのは、LLM/APIキーの置き場所です。model provider key、GitHub token、package registry token、SaaS API key、社内API tokenは、まとめて1つのenvとして渡さない方がよいです。用途別にscopeを切り、agentが必要な時だけ渡し、ログに残る情報を最小化します。
SDKのDocker sandboxで確認すること
評価基準
SDKのDocker sandbox guideでは、DockerWorkspaceを使ってDocker container内でagent serverを動かし、workspace lifecycleをcontext managerで扱う例が示されています。VS Codeやbrowser toolをDocker環境で扱う例もあります。
ここで確認すべきなのは、サンプルが動くかだけではありません。チームで組み込む場合は、次の項目がreview対象です。
| 項目 | 確認質問 |
|---|---|
| image | どのbase imageを使い、追加toolを誰が管理するか |
| workspace | userごと、taskごとに分離されるか |
| lifecycle | task完了後にcontainerやvolumeを消すか、残すか |
| network | docs、package registry、LLM provider以外に出られるか |
| secret | keyをcontainer envに入れるか、proxyやvaultで渡すか |
| logs | command、diff、token usage、errorをどこまで保存するか |
| failure | auth、billing、production dataが必要な時に停止するか |
OpenHands SDK releasesは2026年6月7日時点でGitHub Releases上の更新が続いており、Software Agent SDKのlatestとしてv1.26.0が表示されていました。具体的なversion番号を運用ドキュメントに入れる場合は、公開時点のrelease notesを再確認し、固定するversionと更新手順をセットで書くのが安全です。
自己ホスト前の許可マトリクスを作る
何を許したかをチームで共有できていない状態では、sandbox設定より先に運用事故が起きやすくなります。
OpenHands導入の失敗は、設定が難しいことよりも、「何を許したか」をチームで共有していないことから起きます。そこで、最初に許可マトリクスを作ります。
ファイル操作
評価基準
| 操作 | 個人検証 | チームpilot | 本番隣接 |
|---|---|---|---|
| repo内のread | 許可 | 許可 | 許可。ただしsecret fileは除外 |
src/やtests/のedit | 許可 | 許可 | PR review必須 |
| config edit | 保留 | 承認付き | 承認付き、owner review必須 |
.envや秘密鍵のread | 禁止 | 禁止 | 禁止 |
| repo外file access | 禁止 | 禁止 | 原則禁止 |
| delete / rename | 小さな範囲のみ | 承認付き | 承認付き、rollback確認 |
コマンド実行
評価基準
| command種別 | 個人検証 | チームpilot | 本番隣接 |
|---|---|---|---|
| test / lint / typecheck | 許可 | 許可 | 許可 |
| build | 許可 | 許可 | 許可。ただし生成物の扱いを明記 |
| package install | 保留 | 承認付き | lockfile review必須 |
| local server起動 | 許可 | 許可 | portとnetworkを確認 |
| migration | 禁止 | 承認付き | 原則人間が実行 |
| deploy | 禁止 | 禁止 | 人間承認と別workflow |
| sudo / privileged command | 禁止 | 禁止 | 禁止 |
| git push | 禁止 | 禁止 | 原則禁止。PR作成workflowに限定 |
ネットワークと外部API
確認項目
| 接続先 | 初期方針 | 広げる条件 |
|---|---|---|
| 公式docs | 許可 | allowlistにする |
| package registry | 必要時のみ | lockfileとinstall logを確認 |
| LLM provider | 必須範囲だけ | keyとbudgetを分ける |
| GitHub API | read-onlyから | issue/PR writeは承認付き |
| MCP server | read-only toolから | tool allowlistとログを必須にする |
| 社内API | 初期は禁止 | sandbox、test data、token scopeを分ける |
| billing / payment API | 禁止 | 本番操作は人間承認workflowへ分離 |
MCPを併用する場合は、tool、resource、promptの違いも権限設計に影響します。基礎を整理したい場合は、<a href="https://ai-dev.blog.mo-gmo.com/mcp-tools-resources-prompts-permission-design/">MCPとは何か</a>の記事を先に読むと、OpenHandsに外部toolを渡す時の境界を説明しやすくなります。
導入パターン別の落としどころ
- 個人検証
Docker sandbox、secretなし、小さなrepo、manual reviewありで始め、差分がレビューしやすいかを見ます。
- チームpilot
AGENTS.md、許可マトリクス、review owner、token scope、ログ保存をそろえます。
- 共通ルール化
OpenHandsだけでなく、Codex、Claude Code、Cursorなどにも使えるrepoルールとして整えます。
- 本番隣接運用
本番データやdeployに近い操作は、承認、監査ログ、rollback、owner reviewを前提に扱います。
最初のpilot issueは、受け入れ条件、test command、変更範囲、rollbackが明確なものから選びます。
OpenHandsを導入する時は、一気に全権限を渡さず、段階を分けます。
個人検証
条件
個人検証では、Docker sandboxを基本にし、secretなし、小さなrepo、manual reviewありで始めます。目的は、OpenHandsが自分の開発taskに合うかを見ることです。
この段階で見るべき結果は、完成度よりも「差分がレビューしやすいか」です。AI agentが速く書けても、変更理由、実行command、失敗ログ、残タスクが見えなければチーム導入には向きません。
チームpilot
確認項目
チームpilotでは、AGENTS.md、許可マトリクス、review owner、token scope、ログ保存をそろえます。OpenHands用のルールだけを作るのではなく、Codex、Claude Code、Cursorなど他のAI coding toolにも共通するrepoルールとして作る方が運用しやすいです。
最初のpilot issueには、次の条件を置くと評価しやすくなります。
- 受け入れ条件が明確。
- test commandが明確。
- secretや本番dataが不要。
- 変更範囲が小さい。
- rollbackが簡単。
- reviewで品質を判断できる。
本番隣接運用
注意点
本番隣接運用では、OpenHandsの設定だけでは足りません。private repo、customer data、deployment、billing API、社内API、package registry tokenが関わる場合は、AI agent導入ではなく、社内権限設計のレビューとして扱います。
この段階で必要なのは、次のような運用項目です。
- userごとのagent実行権限。
- taskごとのworkspace分離。
- GitHub tokenやSaaS tokenのscope管理。
- command logとdiff logの保存。
- secretが出た時の検知と停止。
- 失敗時のrollback手順。
- 人間承認なしで実行してよいoperationの一覧。
失敗点: Docker sandboxとSkillsを安全装置として過信する
hostとの距離は作れますが、read-write mount、渡したsecret、広いnetwork、container imageのリスクは残ります。
agentに読ませるルールであり、権限を物理的に止める機能ではありません。
外部docs、issue、PR、生成コードを読むagentには、自然文の禁止だけでは届かないリスクがあります。
diff、command、失敗ログ、残タスクを人間が確認できる状態にしてから運用を広げます。
repo内にsecretが混在し、local CLIが本番へ認証済みで、review担当やrollbackが決まっていない場合は権限設計を先に直します。
過信が起きる理由
根拠
OpenHands導入で避けたいのは、「Docker sandboxを使っている」「AGENTS.mdに禁止を書いた」という2つを安全の根拠にしてしまうことです。
Docker sandboxは、hostとの距離を作ります。しかし、read-writeでmountしたworkspaceは変更できます。環境変数で渡したsecretはagentの実行環境に入ります。networkを広く許せば、外部サービスへ情報が出る可能性があります。
SkillsやAGENTS.mdは、agentに読ませるルールです。しかし、権限を物理的に止める機能ではありません。prompt injection、曖昧なtask、誤ったtool選択、未レビューのgenerated codeに対して、自然文のルールだけで守り切るのは現実的ではありません。
導入しない方がよい条件
確認項目
次の条件がそろっている場合は、OpenHandsの導入前に権限設計をやり直した方がよいです。
- repo内に
.env、private key、credential fileが混在している。 - 開発者のlocal CLIが本番環境へ認証済みになっている。
- migrationやdeployを日常的にlocal commandで実行している。
- AGENTS.mdやreviewルールがない。
- AI agentの変更を誰がreviewするか決まっていない。
- 失敗時に戻す手順がない。
- network allowlistやtoken scopeを管理できない。
この状態でAI agentを入れると、便利さよりも監査不能な操作が増えます。まずrepo構成、credential、CI、review gateを整える方が近道です。
実務で使うなら
- 1日目
検証repoでDocker sandboxを使い、差分とcommand logを確認します。
- 2日目
AGENTS.mdを追加し、禁止操作、test command、停止条件を書きます。
- 3日目
read-only tokenだけを試し、GitHub issueやPR情報の取得に限定します。
- 4日目
小さなbugfixを任せ、reviewで変更品質と説明の十分さを見ます。
- 5日目
許可マトリクスを更新し、チームpilotへ進むか判断します。
OpenHandsがworkflowに合うかだけでなく、どの権限を渡すと危ないかも同時に見ます。
最初の1週間の評価基準
条件
実務でOpenHandsを使うなら、最初の1週間は「成果を出す」より「許可境界を測る」期間にします。
1日目は、検証repoでDocker sandboxを使い、差分とcommand logを確認します。2日目はAGENTS.mdを追加し、禁止操作、test command、停止条件を書きます。3日目はread-only tokenだけを試し、GitHub issueやPR情報の取得に限定します。4日目は小さなbugfixを任せ、reviewで変更品質を見ます。5日目は許可マトリクスを更新し、チームpilotへ進むか判断します。
この流れなら、OpenHandsがチームのworkflowに合うかだけでなく、どの権限を渡すと危ないかも見えます。
チーム向けの最小チェックリスト
確認項目
- OpenHandsの実行環境をDocker、Process、Remoteのどれにするか決めた。
- workspace mountのpathとread/writeを明記した。
.env、credential、private keyをagentから見えない場所へ移した。- AGENTS.mdに禁止操作、テスト手順、停止条件を書いた。
- package install、migration、deploy、git pushをどう扱うか決めた。
- GitHub tokenやSaaS tokenをread-onlyから始めた。
- network allowlistまたは接続先レビューを用意した。
- agentのdiff、command、失敗ログを残す場所を決めた。
- review ownerとrollback手順を決めた。
セキュリティ・コスト注意
model provider key、GitHub token、package registry token、SaaS API key、社内API tokenを同じ環境変数群で渡さないようにします。
必要なtokenを、必要なtaskに、最小scopeで渡し、ログに残る情報を最小化します。
OpenHands本体、OpenHands Cloud/Enterprise、LLM provider、Docker Sandboxesの費用を分けて見ます。
Software Agent SDKでagentを長く動かす場合、token usage、tool call、retry、failed runのコストが積み上がります。
この記事は公式docs、GitHub Releases、Docker docsを確認し、導入判断に必要な範囲を整理しています。
セキュリティ面では、OpenHandsのsandbox選択よりも、secretを渡す設計の方が事故に直結します。model provider key、GitHub token、package registry token、SaaS API key、社内API tokenを同じ環境変数群で渡すのは避けます。必要なtokenを、必要なtaskに、最小scopeで渡します。
コスト面では、OpenHands自体、OpenHands Cloud/Enterprise、LLM provider、Docker Sandboxesを分けて見ます。OpenHands公式のcontributing pageではMIT Licenseとenterprise directoryの別licenseが説明されています。一方で、OpenHands CloudやEnterprise、Docker Sandboxes、LLM API利用には別の契約や費用が発生し得ます。特にSoftware Agent SDKで長時間agentを動かす場合、token usage、tool call、retry、failed runのコストが積み上がります。
この記事にはスポンサー、アフィリエイト、無償提供、検証環境提供はありません。公式docs、GitHub Releases、Docker docsを確認し、導入判断に必要な範囲だけを整理しています。
FAQ
言い切れません。mount、token、network、human reviewを合わせて安全性を判断します。
禁止ではありません。短期検証やdebugには使えますが、secretを含むrepoやチーム標準では慎重に扱います。
書きません。行動ルール、setup手順、test command、禁止操作、review基準を書く場所として扱います。
併用できますが、repo側のルール、worktree、branch、review基準を整理してから同時利用します。
複数のagentを使うほど、toolごとの設定よりrepo共通の権限ルールが重要になります。
Docker sandboxなら安全と言えますか
言い切れません。OpenHandsのDocker sandboxはhostとの距離を取りやすい初期候補ですが、read-writeでmountしたworkspace、渡したsecret、network、container image、Docker設定のリスクは残ります。安全性は、Dockerだけでなく、mount、token、network、human reviewを合わせて決まります。
Process sandboxは使ってはいけませんか
禁止ではありません。Dockerが使えない環境での短期検証や、container外でしか再現しないdebugには使えます。ただし、host上のfile、env、認証済みCLIに近い場所で動くため、チーム標準やsecretを含むrepoでは慎重に扱うべきです。
SkillsやAGENTS.mdに秘密情報を書いてよいですか
書かないでください。AGENTS.mdやSkillsには、行動ルール、setup手順、test command、禁止操作、review基準を書きます。APIキー、private token、customer data、個人情報は書かず、権限分離されたsecret管理で扱います。
OpenHandsとCodexやClaude Codeを併用できますか
併用自体は可能ですが、repo側のルールが分かれていると混乱します。AGENTS.md、CLAUDE.md、tool設定、MCP設定、review基準を整理し、同じrepoで複数agentが同時に触る場合はworktreeやbranchも分けます。併用設計は<a href="https://ai-dev.blog.mo-gmo.com/codex-claude-code-dual-agent-workflow-permissions-review-cost/">CodexとClaude Codeを同じリポジトリで併用する前に決めること</a>も参考になります。
次に読むなら
権限設計やMCP設計レビューをチームで整理したい場合は、<a href="https://ai-dev.blog.mo-gmo.com/contact/">お問い合わせ</a>から相談できます。AIコーディングエージェント、MCP、sandbox運用の更新を追いたい場合は、<a href="https://ai-dev.blog.mo-gmo.com/newsletter/">ニュースレター</a>も利用できます。
更新履歴
- 2026-06-07
OpenHands公式Docs、OpenHands Software Agent SDK GitHub Releases、Docker Sandboxes公式Docsを確認しました。
- 2026-06-07
OpenHands自己ホスト前の権限境界として、sandbox、Skills/AGENTS.md、SDK、許可マトリクスを整理しました。
- 2026-06-07
X/Twitterのtracked accountsは本文の技術的根拠に使わず、公式一次情報に基づいて執筆しました。
公開後も公式docsやSDK releasesの更新に合わせて、sandboxとSDKの説明は見直し対象になります。
- 2026-06-07: OpenHands公式Docs、OpenHands Software Agent SDK GitHub Releases、Docker Sandboxes公式Docsを確認し、OpenHands自己ホスト前の権限境界として整理しました。
- 2026-06-07: X/Twitterのtracked accountsについて、公開検索では直近72時間の確証ある需要シグナルを取得できませんでした。本文の技術的根拠には使わず、公式一次情報に基づいて執筆しました。
参照した主な情報源
- OpenHands Introduction: https://docs.openhands.dev/overview/introduction
- OpenHands Sandbox Overview: https://docs.openhands.dev/openhands/usage/sandboxes/overview
- OpenHands Docker Sandbox: https://docs.openhands.dev/openhands/usage/sandboxes/docker
- OpenHands Process Sandbox: https://docs.openhands.dev/openhands/usage/sandboxes/process
- OpenHands Skills Overview: https://docs.openhands.dev/overview/skills
- OpenHands General Skills: https://docs.openhands.dev/overview/skills/repo
- OpenHands SDK Docker Sandbox: https://docs.openhands.dev/sdk/guides/agent-server/docker-sandbox
- OpenHands Software Agent SDK Releases: https://github.com/OpenHands/software-agent-sdk/releases
- OpenHands contributing and license note: https://docs.openhands.dev/overview/contributing
- Docker Sandboxes: https://docs.docker.com/ai/sandboxes/
- Docker Sandboxes isolation layers: https://docs.docker.com/ai/sandboxes/security/isolation/