opencode.jsonc 設定ガイド：コミット前の 7 つの確認

大事なのはファイルの置き場所だけではありません。opencode.jsonc は、秘密情報を含まないレビュー可能な OpenCode 設定として扱い、認証情報はリポジトリ外に置きます。グローバル設定とプロジェクト設定の合成を理解し、Provider、モデル、権限、ロールバックを確認してからチームで使います。

公式ドキュメントでは JSON と JSONC のサポートが説明されています。コメントは、設定の理由、所有者、確認日、再現コマンドを書くために使うと実務で役立ちます。

秘密情報は入れません。モデル、shell、ツール、権限、プロジェクトのパスは設定できますが、API key、token、private URL、proxy の資格情報は環境変数や Provider の認証経路に置きます。

OpenCode の設定は完全置換ではなく結合されます。グローバル設定とプロジェクト設定が同時に効くことがあり、同じキーだけが後の層で上書きされます。

個人の好みはグローバル設定、チームがレビューすべき規則はプロジェクト設定に置くのが自然です。既定モデル、無視パス、コマンド方針、MCP、権限は特にレビュー対象です。

Provider とモデル ID は、最新の公式ドキュメントか Provider 画面からコピーします。JSON として正しくても、実 ID が違えば実行時に失敗します。

主モデルと小型モデルを分ける理由は、コスト、速度、コンテキスト、ローカル利用、コンプライアンスなどに限定します。理由が変わったら設定も見直します。

権限は最も慎重に扱う部分です。編集と shell は最初 ask にして、繰り返し可能で戻しやすい低リスク操作だけを狭く allow にします。

依存追加、削除、migration、deploy、push、secret、リポジトリ外のディレクトリは deny または明示確認に残します。agent や MCP の例外は、その役割や連携の近くに置きます。

公式 Schema URL を入れると、エディタが補完と検証を行えます。これは安全審査そのものではありませんが、スペルミスや古い形を早く見つけられます。

その後、人間が各キーを確認します。秘密ではないか、プロジェクトで共有すべきか、コメントが正しいか、バージョン依存ではないかを見ます。

コミット前に、小さな安全なリポジトリで試します。OpenCode を起動し、モデル一覧、ファイル読み取り、小さな編集、想定コマンド、deny される操作を確認します。

OS、shell、Provider、モデル ID、テストコマンド、ロールバック手順を記録します。これにより設定は推測ではなく再現可能な基準になります。

1. 最小ファイルを作るSchema、モデル、確認済み権限から始めます。
2. 構文を検証するエディタの Schema または JSONC 対応ツールを使います。
3. 層を解決するグローバル、プロジェクト、カスタムパス、管理設定の優先を確認します。
4. 小さな作業を実行ファイル読み取り、軽い編集、既知コマンドを試します。
5. deny を試すブロックされる操作が実行されないことを確認します。
6. ロールバックを書く規則を外す方法や設定なし起動を記録します。

不具合時は、JSONC 構文、現在ディレクトリ、Git ルート、グローバル上書き、プロジェクト上書き、環境変数、Provider、権限の順に分けて確認します。

Windows では、設定ファイルの場所と shell の挙動を分けて考えます。統合ターミナルが環境変数を見ていない場合や shell コマンドが存在しない場合があります。