OpenCode 2の権限設定：V1から移行し、プロジェクト外へのアクセス確認を戻す

OpenCode 2への更新後に外部ディレクトリへのアクセス確認を戻すには、external_directoryルールにeffect: "ask"を明示します。2026-10-31時点の公式移行ガイドでは、V2の既定値はallowで、V1のaskとは異なります。対応するV1設定は、権限ルールをV2の順序付きpermissions配列に変換する準備ができるまで維持できます。

この記事では、対話形式でコードを書くための基本設定と、OpenCode v2.2.0を基準にした検証手順を示します。期待される結果は、文書とバージョンタグ付きのソースコードに基づきます。実際にクライアントを起動して得たテスト結果ではありません。

一致するルールがなければaskになるのに、なぜV2は外部パスを許可するのですか？

組み込みルールも照合対象になるため、自分でルールを設定していないことと、一致するルールがないことは別です。

公式のV2 Defaultsの説明では、各エージェントの初期ルールに、ワイルドカードを使った許可ルールがあります。その内容はaction: "*"、resource: "*"、effect: "allow"です。その後の基本ルールでは、*.envと*.env.*の読み取りに承認を求め、続いて*.env.exampleの読み取りを許可します。付属のエージェントには追加の制限がある場合もあります。

そのため、通常の読み取り、編集、シェルコマンド、外部ディレクトリの確認には、既に一致する基本ルールがあります。どのルールにも一致しない場合のaskは、評価対象のルール全体に一致がないときだけ適用されます。自分でreadやeditを指定していないからといって、承認が必要になるとは考えないでください。

外部ディレクトリの承認と、ファイル操作の承認は別々に確認されます。判定対象は、現在のLocationとプロジェクトの作業ツリーです。ただし、作業ツリーがファイルシステムのルートを指す場合は、その作業ツリーを判定対象にしません。両方の外側にあるパスでは、OpenCodeはreadやeditより先にexternal_directoryを確認します。ここでLocationは、現在の作業場所を意味します。外部ファイルは境界の確認を通過しても、読み取りや編集の制限を受ける場合があります。

この順序はディレクトリ確認の仕組みで決まります。配列内で、名前の異なるアクションをどの位置に置くかで決まるわけではありません。external_directoryのルールをreadより上に移動しても、それによって確認の順序が決まるわけではありません。

V1設定は残せますか？どの名前が変わりますか？

はい。V2固有の形式への変換は任意です。対応するV1設定は読み込み時に内部形式へ変換されるため、元のファイルを書き直す必要はありません。移行手順では、すべてを変換する前に、既存のモデル、認証情報、エージェント、権限、MCPサーバーを確認するよう案内しています。

V1では、ツールごとに権限の判断をまとめます。

{
  "permission": {
    "bash": {
      "git push *": "ask"
    },
    "edit": "allow"
  },
  "tools": {
    "websearch": false
  }
}

文書に記載されたV2への変換では、これらの明示的な設定を順序付きルールで表します。

{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

各ルールには、文字列のaction、resource、effectが必要です。allowは確認なしで続行し、denyは操作を拒否し、askはクライアントでの判断を待ちます。

この例は、示した設定を変換しただけです。後で紹介する推奨の基本設定ではありません。編集は引き続き許可され、外部ディレクトリへのアクセス確認も戻りません。

アクション名はbash → shell、task → subagent、write/patch → editに変わります。V2のeditは、edit、write、patchの各操作が対象とするパスを制御します。subagentはエージェントIDと照合し、shellはスキャナーが生成したコマンド文字列と照合します。アクション一覧では、doom_loopとlspは現在のV2 Coreの権限アクションに含まれないことも示されています。

最上位の設定、エージェント定義、設定を生成するスクリプトを確認してください。無関係なファイルまで一括置換しないでください。変換を行った後は、競合するV1とV2の権限定義を残さないようにします。

承認を求めるV2の基本設定を使います

対話形式で開発する場合は、外部アクセス、シェルコマンド、編集の前に承認を求めます。通常のGit確認操作は許可し、該当するpushコマンドと、例示用を除く環境設定ファイルの読み取りは拒否します。

リポジトリ固有の設定には、プロジェクト直下のopencode.jsoncを使います。ユーザー全体の設定には~/.config/opencode/opencode.jsoncを使います。OpenCodeは.json形式のファイルも受け付けます。対応する配置場所は設定リファレンスで確認できます。

次の配列を既存の設定に組み込んでください。ファイル全体を置き換えず、プロバイダー設定、エージェント定義、既存の制限を維持します。

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "edit", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" }
  ]
}

.env.exampleの例外は、読み取りを拒否する両方のルールより後に置いています。この例外は、秘密情報を含まない例示用ファイルだけに使ってください。

指定しないアクションには、そのアクションに有効な既定の設定が引き継がれます。この基本設定は、すべてのMCPツールを拒否するものではありません。あらゆる方法でのpushを防いだり、ホストのファイルシステムを隔離したりするものでもありません。readの制限だけでは、シェルコマンドによる同じファイルの読み取りを禁止できません。

OpenCodeのシェルに関する注意事項では、シェルコマンドはホストユーザーの権限で動くと説明されています。アクセス先ディレクトリの推定は、すべてを検出できるとは限りません。承認前にコマンドを確認してください。ファイル操作のルールだけでは不十分な場合は、シェルにも別の制限を設けます。

別のクライアントについては、Claude Codeで秘密情報とGit操作を守る権限設定を参照してください。OpenCodeの設定構文をそのまま流用しないでください。

例外は上書きするルールより後に置きます

順序が重要なのは、同じアクションとリソースに一致するルール同士です。後から一致したルールが、それ以前の判断を置き換えます。アクションにワイルドカードを使うと、複数のアクション名に一致する場合があります。

基本設定では、まずshell: "*"が承認を求めます。その後のgit status *とgit diff *が、それぞれのコマンドを許可します。git push *は、一致するpushコマンドを拒否します。

末尾が *のシェルパターンは、引数のないコマンドにも一致します。そのため、git status *はgit statusとgit status --shortの両方に一致します。

照合ルールの説明では、ワイルドカードをリソース値全体と照合します。*は/を含む0文字以上、?は1文字に一致します。パスの区切りはスラッシュに統一され、Windowsでは大文字と小文字を区別しません。

複数のリソースを扱う操作には、追加の判断が必要です。まず、各リソースに最後に一致するルールを決めます。その結果に拒否があれば操作全体を拒否し、拒否がなくても承認要求があれば確認を求めます。複合シェルコマンドからは複数のリソースが生成される場合があります。1つのGitコマンドが許可されても、複合コマンド全体が許可されたことにはなりません。

信頼できる外部ディレクトリは慎重に追加します

信頼できるディレクトリへの境界を越える許可と、そこでのファイル操作は別々に設定します。次の任意のルールは基本設定への追加用であり、設定全体を置き換えるものではありません。

[
  { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" },
  { "action": "edit", "resource": "~/projects/reference/*", "effect": "deny" }
]

外部ディレクトリの許可は、全体を対象にしたexternal_directoryのaskより後に置きます。読み取りの許可は、環境設定ファイルの拒否ルールより前に置き、読み取り制限を残します。編集の拒否は、全体を対象にした編集のaskより後に置きます。

ディレクトリのルールでは、これらのパス用アクションで、先頭の~/などのホームディレクトリ表記を使用できます。シェルのリソースは元のコマンド文字列のままで、設定の読み込み時にこの展開は行われません。

編集の拒否は、writeやpatchツールを含む、editが管理する操作を拒否します。シェル経由でそのディレクトリを変更する操作は拒否しません。シェルには別の制限を維持し、対象ファイルを変更し得る承認要求を確認してください。

設定を移行し、無害なテスト用ファイルで検証します

実際に使っているファイルをバックアップし、変更案を確認してから、使い捨てのプロジェクトで適用後の設定を検証します。開始前に、V2クライアントがインストールされ、プロバイダーとモデルへの接続が動作していることを確認してください。

移行案を適用する前に確認します

グローバル設定とプロジェクト設定をバックアップします。.opencode/agents/内のエージェント定義も対象です。公式のエージェント配置場所の説明には、ユーザー全体の定義を置く~/.config/opencode/agents/も記載されています。

プラグイン、サーバーAPIとの連携、ターミナル設定は別々に扱います。移行ガイドでは、これらに互換性を保たない変更があると説明されています。

次のプロンプトをOpenCodeに渡します。先に変更案を確認し、承認までファイルを変更させない内容です。

Read the official OpenCode V1 migration and V2 permissions documentation.

Inspect my global, project, and agent permission configuration.
Do not modify any files yet.

Propose native V2 permissions rules.
Preserve unrelated settings and existing restrictions.
Map bash to shell, task to subagent, and write and patch to edit where applicable.
Identify unsupported fields and competing V1/V2 definitions.
Restore external_directory approval without weakening existing deny rules.
Use the baseline's shell and edit approval rules unless existing rules are stricter.
Put environment-file denies before the .env.example exception.
Show the complete proposed diff and explain every behavior change.
Wait for approval before applying it.

プロジェクトのファイルだけでなく、結合後の設定を確認してください。エージェント固有の権限は、解決済みの最上位ルールより後に適用されます。そのため、後にあるエージェントの許可が、最上位の通常の拒否を上書きする場合があります。

組織が強制する制限については、OpenCodeのポリシーを参照してください。ポリシーは、エージェントの権限と保存済み承認の評価後にも、操作を強制的に拒否できます。通常の権限配列は、管理者が強制する制限の代わりにはなりません。

変更案を受け入れたら、opencode reloadで設定を再読み込みします。このコマンドはCLIリファレンスに記載されています。先へ進む前に、設定に関する警告を確認してください。

一通りの検証を行います

次の期待結果は、v2.2.0と組み込みのbuildエージェントを基準にしています。基本設定が有効で、競合するエージェントルール、保存済み承認、追加ポリシーがないことを前提とします。

Bashで、秘密情報を含まないテスト用ファイルを作成します。

lab=$(mktemp -d)
mkdir -p "$lab/project" "$lab/outside"
git -C "$lab/project" init -q
printf 'ordinary fixture\n' > "$lab/project/README.md"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env"
printf 'EXAMPLE_VALUE=local-test\n' > "$lab/project/.env.example"
printf 'outside fixture\n' > "$lab/outside/fixture.txt"
cd "$lab/project"

このプロジェクトのopencode.jsoncに基本設定を保存し、opencodeを起動します。ターミナル画面のガイドに従い、/agentsからbuildを選択します。

指定したツールを通じて、各操作を個別に試すようエージェントに依頼します。自分でターミナルから実行したコマンドを、エージェントの権限確認の代わりにしないでください。

エージェントの操作	期待される権限の判断
readでREADME.mdを読む	基本の読み取りルールで許可されます
readで../outside/fixture.txtを読む	外部ディレクトリへの承認を求め、承認後は通常の読み取りが許可されます
readで.envを読む	拒否されます
readで.env.exampleを読む	許可されます
edit、write、patchでREADME.mdを変更する	editによる承認を求めます
shellでgit status、git status --short、git diffを実行する	許可されます
shellでgit pushを実行する	一致するシェルルールで拒否されます
shellでpwdを実行する	承認を求めます

pushの確認前に、自分でgit remoteを実行し、名前が何も表示されないことを確認します。リモートは追加しないでください。リモートがないというGitのエラーは、権限ルールによる拒否が成功した証拠にはなりません。

承認のテストでは、Allow alwaysではなくAllow onceを選び、今回だけ許可します。保存済み承認はプロジェクトに保存され、以降の確認を省略することがあります。ただし、設定済みの拒否は上書きしません。自動承認は無効にしておきます。

実際のツール要求、権限の判断、ファイルの変更を確認してください。モデルが「pushしない」「ファイルを読まない」と回答しても、権限の仕組みが操作を拒否した証拠にはなりません。

ルールを緩める前に、期待と異なる理由を調べます

まず、読み込まれた設定と選択中のエージェントを確認します。CLIのデバッグコマンドには、opencode debug configとopencode debug agentsがあります。出力は手元で確認し、認証情報や機密性のある設定を共有しないでください。

外部アクセスの確認が出ない場合は、対象がLocationとプロジェクトの作業ツリーの両方の外側にあるか確認します。次に、保存済み承認と自動承認を確認します。ファイル読み取りの結果が想定と異なる場合は、エージェントがshellではなくreadを使ったか確認します。

Gitコマンドが拒否された場合は、スキャナーが生成したリソースと、追加のサブコマンドを確認します。.env.exampleが拒否される場合は、後にある*.env.*ルールや追加ポリシーが例外を上書きしていないか調べます。

既存のプロバイダー、モデルID、認証、Base URLも別途確認してください。BetterTokenのOpenCode連携手順では、https://www.bettertoken.ai/v1を使うカスタムのOpenAI互換接続を説明しています。この接続は、OpenCodeの権限設定の代わりにはなりません。

移行に伴ってツール自体を選び直す場合は、CursorとOpenCodeの設定と接続方法の比較を参照してください。別のターミナル開発手順を評価する場合は、GitプロジェクトでのAiderとOpenCodeの比較に沿って、同じテスト用タスクを試します。

v2.2.0のファイルシステム修正は何を変えますか？

この修正は、外部ディレクトリの確認時にプロジェクトのファイルを特定する方法を変えます。承認ルールを明示するという推奨は変わりません。

v2.2.0のリリースノートには、プロジェクトのファイルシステムを使う変更が記載されています。PR #59089では、リモートやメモリ内のプロジェクトでも、以前はホストマシンのディスクを参照していたと説明しています。PRの作成者によると、通常のローカルプロジェクトには影響しません。

リモートプロジェクトでは、そのプロジェクトが実際に使うファイルシステムで外部ディレクトリの確認をやり直してください。2026-10-31時点で文書化されたV2の既定設定では、境界を制限するために、external_directoryのaskまたはdenyを明示する必要があります。