(最終更新日: 2026年09月08日)
OpenClawを導入したものの、「openclaw.jsonがどこにあるかわからない」「設定項目が多くてどこを触ればいいか迷う」といった壁にぶつかっていませんか?
英語の公式ドキュメントだけでは、具体的な記述ルールや推奨設定を細部まで把握するのはなかなか大変な作業ですよね。
本記事では、OpenClawの挙動を制御する核となる設定ファイルの書き方を、基礎からセキュリティ対策まで徹底解説します。
この記事を読めば、設定ミスによるエラーを解消し、あなたの用途に合わせた最適なAIエージェント環境をスムーズに構築できるようになります。
JSON5形式の利点や各パラメータの意味、秘匿情報の守り方まで、記事の構成に沿って平易な言葉で詳しくまとめました。
AIツールの活用に精通したSaiteki AIが、エンジニアやビジネスパーソンの目線で実践的なポイントを分かりやすくお届けします。
さあ、OpenClawの可能性を最大限に引き出すための設定術を、一緒にマスターしていきましょう!
OpenClaw設定の基礎知識 – openclaw.jsonの役割とJSON5の採用理由
当セクションでは、OpenClawの挙動を支配する設定ファイル「openclaw.json」の基本概念と、その記述形式にJSON5が選ばれた理由について解説します。
OpenClawを正しく運用するためには、単なるパラメータの書き方だけでなく、その背後にあるアーキテクチャや設計思想を理解することが、将来的な拡張性や安全性の確保に直結するからです。
- エージェントの司令塔「openclaw.json」のアーキテクチャ
- なぜJSON5なのか?記述の柔軟性と保守性のメリット
- 全体構造を規定する「Two-Bucket Rule(2つのバケット原則)」
エージェントの司令塔「openclaw.json」のアーキテクチャ
openclaw.jsonは、OpenClawシステムの全レイヤーを統括する中枢神経系のような役割を果たしています。
このファイル一つでLLMの選定からツールの実行権限、接続するチャットアプリの設定までを一元管理できるため、複雑なエージェントの挙動を宣言的に制御可能です。
設定の適用範囲は、通信を仲介するGateway、思考を司るAgent Runtime、各OSリソースを扱うNode、そしてSlack等の外部基盤と繋ぐChannelsの4層にまで及びます。
プロセスが起動すると、Zodライブラリによって厳密なスキーマ検証が行われ、設定ミスがあれば即座に起動を停止してシステムの完全性を維持します。
したがって、まずはこのファイルが各コンポーネントにどのように作用するかを把握することが、高度な自動化への第一歩となります。
詳細なプロセスの挙動については、OpenClaw Gateway完全解説の記事も併せて参照してください。
なぜJSON5なのか?記述の柔軟性と保守性のメリット
設定ファイルのフォーマットにJSON5を採用した最大の理由は、開発者が人間にとって読みやすく書きやすい形式を維持するためです。
標準的なJSONでは不可能な「行コメント」や「末尾のカンマ」が許容されることで、設定値の意図をソース内に直接メモとして残せるようになります。
例えば、特定のモデルに切り替えた背景や一時的に無効化したツールの説明をコメントアウトで記述でき、チーム開発における情報共有のコストが大幅に下がります。
| 機能 | 標準JSON | JSON5 |
|---|---|---|
| 行コメント (//) | 不可 | 可能 |
| 末尾のカンマ | 不可 | 可能 |
| キー名のクォート省略 | 不可 | 可能 |
柔軟な構文を持つJSON5のおかげで、設定ファイルは単なるデータ定義を超え、生きた運用ドキュメントとしての価値を持つに至っています。
保守性を高めるこの選択は、頻繁なアップデートが繰り返されるAIエージェントの運用において非常に合理的といえるでしょう(参考: OpenClaw Docs)。
全体構造を規定する「Two-Bucket Rule(2つのバケット原則)」
OpenClawの設定は、インフラと個別の論理を切り分けるTwo-Bucket Ruleという独自の思想に基づいて階層化されています。
全エージェントに共通するネットワーク等の基盤設定を「gateway」に、エージェント個別の振る舞いを「agents」に分離することで、大規模な運用でも設定が煩雑になりません。
具体的には「agents.defaults」で共通のルールを定め、特定の「agents.entries」だけでLLMのモデル名や権限を上書きするといった階層的な制御が可能です。
共通ルールを親として継承しながら必要箇所のみを変更できるこの仕組みは、設定の重複を防ぎ、ミスを最小限に抑える効果があります。
この二つのバケットによる分離構造を正しく理解しておけば、セキュアでメンテナンス性の高いエージェント環境をスムーズに構築できるはずです。
さらに実践的なリスク管理や組織での運用について学びたい方は、生成AI活用の最前線といった資料も非常に参考になります。
導入準備と検証 – 設定ファイルの作成とCLIツールによる環境構築
当セクションでは、OpenClawの動作を支える設定ファイルの作成手順と、CLIツールを用いた効率的な検証環境の構築方法について詳しく解説します。
正確なパスへの配置とスキーマに基づいた妥当性確認を最初に行うことで、後の複雑なカスタマイズにおける致命的な起動エラーを未然に防ぐことができるためです。
- 設定ファイルの初期化と配置場所の確認
- openclaw config validateによる構文チェックの自動化
- IDEでの開発体験を向上させるJSON Schemaの活用
設定ファイルの初期化と配置場所の確認
OpenClawの挙動を制御するコア・アーキテクチャである設定ファイルは、各OSのユーザーホームディレクトリ直下にある特定の隠しフォルダ内に配置するのが基本ルールです。
システム起動時に「Gateway」プロセスがこのパスを自動的に走査して読み込むため、正しい位置への作成は安定稼働のための絶対条件となります。
以下の表を参考に、自身の利用しているOSにおける適切な作成場所を確認してください。
| OSタイプ | デフォルトの配置ディレクトリ | パス確認・移動コマンド |
|---|---|---|
| macOS / Linux | ~/.openclaw/ |
cd ~/.openclaw |
| Windows | %USERPROFILE%\.openclaw\ |
cd %USERPROFILE%\.openclaw |
新規導入時にはコマンドラインからopenclaw initを実行し、ベースとなるテンプレートファイルを生成することから始めましょう。
詳しい初期セットアップの手順については、OpenClawインストール完全ガイドでも詳しく紹介しています。
初期化が完了すると「openclaw.json」という名称でファイルが作成され、自律型エージェントの基盤が整います。
openclaw config validateによる構文チェックの自動化
設定ファイルをテキストエディタで手動編集した後は、必ずCLIツールによる構文チェックを実行するワークフローを習慣化しましょう。
OpenClawの設定はJSON5形式を採用しており柔軟性が高い反面、末尾のカンマ不足や型の指定ミスが1箇所でもあるとシステム全体が正常に起動しなくなります。
保存直後にターミナルで
openclaw config validate --strict-json
を叩くことで、内部のバリデーションライブラリが即座にエラーを特定してくれます。
検証中に「Expected string, received number」などのメッセージが表示された場合は、設定値の型が不適切であることを示しているため該当行を修正してください。
このように厳密な自動検証プロセスを挟むことで、試行錯誤の時間を最小限に抑え、信頼性の高いエージェント運用が可能になります。
環境構築の自動化や効率化に興味がある方は、生成AI 最速仕事術を参考に、ツールの最適な組み合わせを学ぶことも非常に有効です。
IDEでの開発体験を向上させるJSON Schemaの活用
VS Codeなどの高性能なエディタを使用している場合、公式が提供するJSON Schemaを紐付けることで設定効率を劇的に引き上げることが可能です。
スキーマを読み込ませることで、設定項目(キー)の自動補完や、マウスホバー時に各項目の機能説明を表示するツールチップが有効になります。
まずは
openclaw config schema --json > myschema.json
コマンドを実行し、現在のバージョンに適合した最新の定義ファイルを出力しましょう。
次に、VS Codeのsettings.jsonにおいて、自身の「openclaw.json」と出力したスキーマファイルを関連付ける記述を追加します。
インテリセンスによるリアルタイム支援を受けながら編集することで、ドキュメントを何度も往復する手間が省け、ミスも劇的に減少します。
高度な開発環境の構築からAIの仕組みまで深く理解したいエンジニアの方は、専門の学習コースも検討してみてください。
核心設定の詳細解説 – Gateway、Agents、Modelsの主要パラメータ
当セクションでは、OpenClawの構成ファイルにおいて中核をなす「Gateway」「Agents」「Models」の3つの主要セクションについて詳しく解説します。
これらのパラメータを最適化することで、システムの安定性向上、セキュリティの確保、そして運用コストの劇的な削減を同時に実現できるからです。
- Gatewayセクション:通信とリロードの挙動制御
- Agentsセクション:自律性とワークスペースの定義
- Modelsセクション:動的マルチモデルルーティングの設定
Gatewayセクション:通信とリロードの挙動制御
Gatewayセクションの設定は、システムの外部接点とメンテナンスの柔軟性を左右する極めて重要な基盤となります。
待受ポートや認証トークンの定義に加えて、設定の反映方式が運用効率に直結するためです。
たとえば「reload.mode: “hybrid”」を指定すれば、Gatewayを停止させずに設定変更を即時反映できるホットリロードが可能となり、無停止での微調整が実現します。
ただし、VPSなどの公開サーバーで運用する場合、bind設定を”all”にすると外部からの不正アクセスのリスクが生じるため、セキュリティの観点から推奨されません(参考: OpenClaw Docs)。
安全な通信環境を構築するための詳細は、OpenClaw Gateway完全解説の記事も併せてご確認ください。
適切なアクセス制限とリロード設定を組み合わせることで、堅牢かつ管理しやすいエージェント基盤が整います。
Agentsセクション:自律性とワークスペースの定義
エージェントの自律性を最大限に引き出すためには、作業環境とリソース消費の制限を適切に定義しなければなりません。
ツールが動作する「workspace」の指定や画像解析の解像度制御が、業務効率とAPIコストの双方に直接影響を及ぼすからです。
具体的には「imageMaxDimensionPx」の値を調整することで、不要なトークン消費を抑えつつ、必要な視覚情報を正確にエージェントへ渡すバランスを保つことが可能になります。
以下の図は、解像度設定と処理コスト、精度の相関関係を示したものです。
業務要件に応じてこれらのパラメータを使い分けることが、プロフェッショナルなエージェント運用の鍵と言えるでしょう。
AIの基礎体力を高め、こうしたツールをより高度に使いこなしたい方には、生成AI 最速仕事術が非常に役立ちます。
Modelsセクション:動的マルチモデルルーティングの設定
コストパフォーマンスに優れた運用を実現する秘訣は、動的なマルチモデルルーティングを賢く活用することにあります。
思考力の高いメインモデルと安価な予備モデルを適材適所で使い分けることで、API費用を大幅に削減しつつタスク完遂率を維持できるためです。
具体的には、primaryモデルに高性能なClaudeを指定しつつ、エラー時や単純な作業用にfallbacks配列へ軽量モデルを定義する手法が推奨されます。
以下に、APIコストを最大70%削減するための典型的なルーティング設定例を示します。
{
"models": {
"primary": "anthropic/claude-3-5-sonnet",
"fallbacks": [
"openai/gpt-4o-mini",
"ollama/llama3.1"
],
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434"
}
}
}
}
より詳細なプロバイダ設定やコスト削減術については、OpenClaw API 完全ガイド 2026で詳しく解説しています。
自社専用の推論サーバーやOllama等のローカル環境を統合することで、プライバシー保護と低コスト化を究極のレベルまで高めることが可能です。
自律型AI運用のスペシャリストを目指し、実践的なスキルを習得したい方は、AI CONNECTでのリスキリングも検討してみてください。
セキュリティとガバナンス – SecretRefとサンドボックスの高度な設定
当セクションでは、OpenClawの安全性を最大化するための「SecretRef」と「サンドボックス」の設定方法を深掘りします。
自律型AIエージェントは非常に強力なツール実行権限を持つため、適切なガバナンス設定が欠落していると、機密情報の漏洩やシステムへの不正操作を招く危険性があるからです。
- SecretRefによる機密情報保護の実装手順
- sandbox.modeの使い分けとツールの実行制限
- エンタープライズ向けNVIDIA NemoClawとの統合
SecretRefによる機密情報保護の実装手順
OpenClawの安全性を担保する上で、APIキーなどの機密情報を設定ファイルへ直接書き込まない運用は欠かせません。
エージェント自身が設定ファイルを読み取ることが可能な設計になっているため、平文での記載はプロンプトインジェクションによる外部流出を招く恐れがあります。
そこで活用したいのが「SecretRef」という参照構造であり、取得元として環境変数や外部のシークレットマネージャーを柔軟に指定できます。
例えば `${env.API_KEY}` のように記述すれば、GitHub等のリポジトリに設定を公開しても実データが漏れる心配はなくなるでしょう。
| 取得元 (source) | 主な用途 | 特徴 |
|---|---|---|
| env | OS環境変数からの取得 | 最も簡便で、CI/CD環境との親和性が高い |
| store | 暗号化SQLiteからの取得 | ローカル環境でセキュアに永続化したい場合に適する |
| exec | VaultやSOPS等の外部ツール実行 | エンタープライズレベルの厳格な鍵管理が可能 |
情報の取得経路を抽象化することで、エージェントが自身の構成を閲覧した場合でも秘密鍵の漏洩を防ぐことが可能です。
詳しい管理方法については、OpenClaw Gateway完全解説も併せて参考にしてください。
この仕組みを導入し、開発環境と本番環境の認証情報を安全に分離して管理することを強く推奨します。
sandbox.modeの使い分けとツールの実行制限
外部のリソースを自律的に操作するAIエージェントにとって、サンドボックスによる実行環境の隔離は防衛の要です。
外部サイトやメールに仕込まれた「間接プロンプトインジェクション」攻撃が発生した場合、隔離環境がなければホストOSのファイルが破壊されるリスクが生じます。
`sandbox.mode` を「all」に指定し、Dockerコンテナ技術を併用することで、エージェントの全アクションをホストから物理的に遮断しましょう。
あわせて `tools` セクションの `deny` リストに `rm` や `curl` などの高リスクコマンドを登録し、実行可能な操作を最小限に絞り込むのが賢明です。
コンテナを活用した詳細な構築手順については、OpenClawをDockerで構築する完全ガイドで詳しく解説しています。
厳格な境界線を引く設定を施すことにより、AIの自律性を活かしつつ組織の安全性を守り抜くことが可能です。
エンタープライズ向けNVIDIA NemoClawとの統合
より強固なデータガバナンスが求められる法人利用では、NVIDIA NemoClawとの統合が究極の選択肢となります。
アプリケーション層の設定だけでは不具合によるバイパスのリスクが残りますが、NemoClawはOSカーネルレベルでの強制的な分離制御を提供するためです。
Landlock LSMやseccompを活用した隔離技術により、エージェントがアクセスできるファイルシステムやネットワーク範囲を物理的に制限できます。
機密データは社内のNemotronでローカル処理し、公開情報はクラウドへ自動で振り分けるプライバシールーター機能も非常に強力です(参考: NVIDIA)。
| 機能 | 標準OpenClaw | NVIDIA NemoClaw |
|---|---|---|
| 分離レベル | アプリ層による判定 | OSカーネルレベルでの分離 |
| ネットワーク | デフォルト全許可 | デフォルト全遮断(許可制) |
| APIキー秘匿 | 環境変数等に保持 | ゲートウェイが代理付与(不可視) |
企業でのAI導入におけるリスク管理の全体像については、生成AI活用の最前線で体系的に学ぶことができます。
組織全体でのAI活用を加速させるためには、こうしたインフラレベルでの多層防御を構築することが成功の鍵となります。
実践的ユースケース – MCP連携とスキルシステムによる機能拡張
当セクションでは、OpenClawを単なるチャットボットから強力な「行動型エージェント」へと進化させるための、実践的な外部連携と拡張設定について詳しく解説します。
openclaw.jsonの真価は、外部ツールとの接続規格であるMCPや、独自スキルを定義する仕組みを統合することで、ユーザー固有の複雑な業務プロセスを完全に自動化できる点にあるからです。
- Model Context Protocol (MCP) による外部SaaS連携
- 「SKILL.md」による独自業務の自動化定義
- マルチプレイヤーワークスペースの共有設定
Model Context Protocol (MCP) による外部SaaS連携
mcp.serversセクションを適切に構成することで、NotionやSlack、GitHubといった外部SaaSとエージェントをシームレスに同期させることが可能になります。
これはOpenClawがAnthropic社の提唱する「Model Context Protocol(MCP)」をネイティブサポートしており、個別のAPI連携コードを書かずとも標準規格でツールを統合できるためです。
具体的な設定方法は、mcp.jsonの解説記事でも触れている通り、通信方式や実行コマンドをJSON形式で定義するだけの極めてシンプルなものです。
"mcp": {
"servers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
}
}
}
エージェントがこれらの外部サーバーを自在に操作できるようになれば、社内ドキュメントの検索からコードのコミットまでを一貫して代行させることができます。
外部ツールとの接続性を最大化するこの機能は、OpenClawを単なるチャットツールから真の業務実行プラットフォームへと昇華させる重要な鍵となります。
「SKILL.md」による独自業務の自動化定義
ディレクトリ単位でSKILL.mdというファイルを配置するスキルシステムを利用すれば、プログラミングの知識がなくても独自の業務フローを自動化できます。
OpenClawはワークスペース内のドキュメントを読み取り、そこに記載された手順や制約を自身の「遂行可能なスキル」として動的に学習する特性を備えているからです。
実際に、毎朝の未読メールから重要事項を抽出してSlackへ要約投稿する手順を記述したスキルを作成したところ、エージェントは自律的にツールを選択してタスクを完遂しました。
詳細はOpenClaw Hubの活用ガイドでも紹介されていますが、定型業務を言語化してファイルに保存するだけで、エージェントの能力は無限に拡張されます。
自分だけのノウハウをAIに授けるこの手法は、パーソナルアシスタントとしてのOpenClawの魅力を最も引き出す方法の一つです。
マルチプレイヤーワークスペースの共有設定
OpenClaw 2.0で導入されたマルチプレイヤー設定を定義することで、チーム内での安全なリソース共有とガバナンスが実現します。
各チャンネル設定内のallowFromやdmPolicyを構成すれば、特定のユーザーIDのみに実行権限を限定し、不正なアクセスやリソース消費を物理的に防ぐことが可能だからです。
ホワイトリスト方式で運用メンバーを適切に管理するこの手法は、家庭内や開発チームで共有の計算リソースを安全に利用するために欠かせません。
組織におけるAIエージェントの本格的な導入を検討されている場合は、生成AI活用の最前線といった専門資料を参考に、セキュリティ設計を深めることを推奨します。
管理者による厳格な権限制御こそが、複数のユーザーが介在する環境でOpenClawを安定稼働させるための強固な土台となります。
トラブルシューティングとFAQ – 設定エラーの解決策
当セクションでは、OpenClawの設定中に遭遇しやすいエラーの具体的な解決策について説明します。
高度な自律性を実現するために設定ファイルの検証が厳密化されており、わずかな記述ミスがシステム全体の停止を招く可能性があるため、正しい対処法を知ることが重要だからです。
- 「Zod validation error」の読み解き方と修正方法
- openclaw doctorによる設定ファイルの自動修復
- セキュリティ監査コマンドでの安全確認
「Zod validation error」の読み解き方と修正方法
Zodバリデーションエラーは、設定ファイルの構造が公式に定義されたスキーマから外れていることを示す重要な警告です。
OpenClawは内部でTypeScriptベースの強力なバリデーションライブラリを採用しており、データの型不一致や必須項目の欠損を厳密にチェックしています。
不慣れなユーザーが陥りやすいポイントとして、数値を期待する箇所に引用符付きの文字列を記述したり、カンマを忘れたりするケースが多く見受けられます。
以下の対比表を参考に、エラーが発生した際の記述内容を見直してみるのが解決への近道となるでしょう。
| エラーの内容 | 修正前の誤った記述例 | 修正後の正しい記述例 |
|---|---|---|
| 数値型の不一致 | "port": "18789" |
"port": 18789 |
| 必須キーの欠落 | "gateway": { "bind": "loopback" } |
"gateway": { "port": 18789, "bind": "loopback" } |
| SecretRefの形式誤り | "auth.token": "my-token" |
"auth.token": { "source": "env", "id": "OPENCLAW_TOKEN" } |
エラーメッセージに表示される「path」の項目を丁寧に辿ることで、迅速に修正箇所を特定し、システムを正常な待機状態へ復元できます。
openclaw doctorによる設定ファイルの自動修復
バージョンアップに伴って生じる設定ファイルの不整合は、専用の診断ツールである openclaw doctor コマンドでスマートに解決可能です。
特にOpenClaw 2.0への移行では多くの設定キーが刷新されましたが、このコマンドは古い記述を自動的に検知して現行スキーマへ変換する役割を担います。
ターミナルで以下のコマンドを実行するだけで、非推奨となったキーが安全に上書きされ、手動での修正作業を大幅に削減できます。
openclaw doctor --fix
主要な変更点として以下の項目が挙げられますので、あらかじめ新旧の対応関係を把握しておくとスムーズです。
| 対象カテゴリ | 旧バージョン(v1.x系) | 新バージョン(v2.0以降) |
|---|---|---|
| メインモデル指定 | agents.defaults.model |
agents.defaults.model.primary |
| サンドボックス設定 | sandbox: true |
sandbox: { "mode": "all" } |
手動での記述ミスによる起動失敗を防ぐためにも、アップデート直後にはまずこの修復コマンドを試す習慣をつけましょう。
セキュリティ監査コマンドでの安全確認
自律型エージェントの運用において、安全性を永続的に確保するためには定期的なセキュリティ監査の実施が推奨されます。
OpenClawはOSやネットワークへの強力なアクセス権を持つため、設定の不備がそのままシステムの脆弱性に繋がりかねないからです。
公式が提供する openclaw security audit --deep コマンドを使用すれば、Gatewayポートの公開設定やツール実行権限の妥当性を一括で診断できます。
監査で満点を獲得し、強固な防壁を築くための必須チェックリストは以下の通りです。
bind設定が外部に露出しない”loopback”になっているかsandbox.modeが”all”に設定され、全実行が隔離されているかauth.tokenが推測困難な十分に長い文字列であるか- 特権昇格(
elevated.enabled)が不必要に有効化されていないか
詳細な防御策については、OpenClaw Gateway完全解説の記事も併せて参照してください。
監査スコアを100点に保つ運用を徹底することで、外部からの不正侵入リスクを物理的に遮断した安全なAI環境を実現できます。
AIのポテンシャルを最大限に引き出すためには、ツールを使いこなすための思考法を学ぶことも重要です。
生成AI 最速仕事術では、OpenClawのようなエージェントを動かす基礎となるプロンプトの型が詳しく解説されています。
まとめ:OpenClawで自律型AIエージェントの可能性を最大限に引き出そう
本記事では、OpenClawの心臓部である「openclaw.json」の設定方法について、基礎知識からセキュリティ対策、実践的な外部連携まで網羅的に解説してきました。
特に重要なポイントは、GatewayやAgentsによる柔軟な挙動制御、SecretRefを用いた機密情報の保護、そしてMCP連携による無限の機能拡張という3点です。
これらの設定を正しく理解して適用することで、あなたのAIエージェントは単なる対話ツールを超え、複雑な業務を自律的に完遂する強力なビジネスパートナーへと進化します。
設定が完了した今、あなたは次世代のAI活用を自在に操るための第一歩を確実に踏み出しました。自律型エージェントがもたらす生産性の向上は、あなたのワークスタイルに劇的な変革をもたらすはずです。
OpenClawの設定が完了したら、次は実際にエージェントを動かしてみましょう!詳細な活用事例や、さらに高度なプロンプトエンジニアリングの手法については、以下の「実践編ガイド」をご覧ください。
OpenClaw実践活用ガイド:業務を自動化するスキルの作り方
また、エージェントを使いこなすためのAI活用の基礎体力を高めたい方には、プロンプトの型を学べる『生成AI 最速仕事術』が非常におすすめです。
さらに、AIの仕組みを根本から理解し、業務自動化のスペシャリストを目指すなら、オンラインスクールの『Aidemy』で専門技術を磨くことも、あなたのキャリアを飛躍させる近道となるでしょう。


