OpenClaw Agent設定完全ガイド：作成、設定 & 管理

OpenClawをまだインストールしていませんか？ワンラインインストールコマンドはこちら

macOS / Linux PowerShell CMD

curl -fsSL https://openclaw.ai/install.sh | bash

iwr -useb https://openclaw.ai/install.ps1 | iex

curl -fsSL https://openclaw.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

パソコンへの影響が心配ですか？ ClawTank ならクラウド上で動作し、インストール不要で誤削除のリスクもありません

主要な知見

OpenClaw Agentは独自のアイデンティティ、スキル、隔離されたワークスペースを持つ自律的なユニットであり、従来のチャットボットとは根本的に異なる——エージェントは自律的に計画を立て、ツールを呼び出し、タスク状態を継続的に追跡できる^[1]
openclaw agents addコマンドにより、開発者は30秒で新しいエージェントを作成し、すぐにモデル、アイデンティティ設定、ワークスペースを割り当てることができる^[5]
各エージェントのagent.mdアイデンティティファイルは、システムプロンプト、パーソナリティ特性、動作境界を定義しており、OpenClawエージェント設計における最も重要な設定レイヤーである^[2]
モデル設定はPrimary / Fallbackの二層メカニズムをサポートし、Per-Agentオーバーライドと組み合わせることで、コストと品質のきめ細かなバランスが可能^[3]
Workspace隔離メカニズムにより、各エージェントは認可されたファイルとディレクトリのみにアクセスでき、OpenClawのセキュリティモデルの礎となっている^[7]

OpenClawの世界では、「Agent」は単なる質問に答えるチャットインターフェースではない——それは独自のアイデンティティ、専門的なスキルセット、隔離されたワークスペースを持つ自律的なエンティティである。^[6] エージェントを専門のチームメンバーとして考えてほしい。自分が誰であるか、何が得意か、何が許可されているか、どの環境で作業するかを知っている。

この記事はOpenClawシリーズの第20回であり、OpenClawエージェントの作成、設定、管理に特化している。初めてOpenClawに出会う新規ユーザーであれ、既に本番環境で複数のエージェントを運用している上級ユーザーであれ、このガイドはゼロから一までの完全なパスを提供する。agents addの最初のステップから始まり、agent.mdアイデンティティ設定、モデル選択とFallback戦略、Workspaceセキュリティ設定、高度な権限制御とマルチエージェント管理テクニックへと段階的に深掘りする。

1. OpenClaw Agentとは

設定プロセスに入る前に、OpenClawエージェントの本質を明確にしておく必要がある——従来のチャットボットとの違いは、ほとんどの人が想像する以上に大きい。

1.1 Agent vs. チャットボット：根本的な違い

従来のチャットボットは受動的である。メッセージを受信し、メッセージで返信し、次の入力を待つ。メモリがない（または限定的なセッションメモリのみ）、アクションを主体的に計画できない、外部ツールを使用できない。チャットボットは本質的に「Q&Aマシン」である。

OpenClawエージェントは根本的に異なる。完全なOpenClaw Agentは以下の5つのコア特性を備えている。^[1]

アイデンティティ：agent.mdを通じて定義されたシステムプロンプトが、エージェントに役割定義、パーソナリティ特性、動作規範を与える
自律的計画：複雑なタスクに直面した際、エージェントは独立してステップを分解し実行順序を決定でき、ユーザーがステップバイステップでガイドする必要がない
ツール使用：エージェントはファイルシステム操作、Shellコマンド、APIリクエスト、ブラウザ制御などのツールを呼び出してタスクを遂行できる
メモリと状態追跡：エージェントは単一会話内で完全なコンテキストメモリを維持し、Workspace内のファイルを通じてクロスセッションの知識永続化を実現できる
セキュリティ境界：各エージェントのWorkspaceと権限は独立しており——あるエージェントは別のエージェントの制限されたリソースにアクセスできない

つまり、チャットボットは「応答者」であり、OpenClawエージェントは「実行者」である。エージェントに「このモジュールをリファクタリングしてテストを書いて」と伝えると、独立してコードを読み、構造を分析し、修正を加え、テストを実行し、結果を報告する——すべてステップバイステップの指示なしに。^[4]

1.2 OpenClaw Agentアーキテクチャ概要

OpenClawのアーキテクチャにおいて、エージェントは最も基本的な動作ユニットである。各エージェントは4つのレイヤーで構成される。

アイデンティティレイヤー：agent.mdにより定義され、エージェントの役割、動作境界、システム指示を決定する
モデルレイヤー：エージェントが推論に使用する大規模言語モデルを決定し、PrimaryとFallbackの設定を含む
Skillsレイヤー：エージェントが呼び出しを許可されたツールと機能のセット（ファイル操作、Shell実行、ネットワークリクエストなど）
Workspaceレイヤー：エージェントのファイルシステム境界——どのディレクトリの読み書きが可能か、どのリソースにアクセスできるか

これら4つのレイヤーを理解することが重要である。後続のすべての設定操作は、本質的にこれら4つの次元を設定するものだからである。^[1]

1.3 カスタムエージェントが必要になる場面

OpenClawインストール後には、デフォルトエージェントが付属している。一般的なタスク——コードQ&A、ドキュメント照会、シンプルなスクリプト作成——にはデフォルトエージェントで通常十分である。しかし、以下のシナリオではカスタムエージェントの作成が推奨される。

専門化のニーズ：データベース管理専用のエージェント、コードレビュー専用のエージェント、技術ドキュメント作成専用のエージェントが必要
セキュリティ隔離：異なるプロジェクトのエージェントが異なる機密データにアクセスする必要があり、クロスアクセスを防止するためにWorkspace隔離が必要
モデル最適化：一部のタスクには高性能モデル（Claude Opus 4.6など）の深い推論能力が必要であり、他のタスクには軽量モデル（Claude Haikuなど）の高速応答のみで十分
チーム協業：複数人のチームで、異なるメンバーが異なる設定のエージェントを必要とする、または特定のエージェント設定テンプレートを共有する必要がある

2. 最初のエージェントを作成する

それでは実践に入りましょう。openclaw agents addコマンドを使用して、OpenClawエージェントをゼロから作成します。^[5]

2.1 前提条件

エージェントを作成する前に、以下の条件が満たされていることを確認してください。

OpenClawがインストールされ、初期化が完了していること（openclaw onboardが実行済み）^[4]
少なくとも1つのモデルプロバイダーの認証が設定されていること（例：Anthropic APIキー）
メイン設定ファイル~/.openclaw/openclaw.jsonが存在し、適切にフォーマットされていること

以下のコマンドで環境の準備状況を素早く確認できます。

openclaw doctor

すべてのチェックがパス（緑のチェックマークが表示）すれば、エージェントの作成を開始できます。

2.2 agents addコマンドの使用

新しいエージェントを作成するコアコマンドはopenclaw agents addです。最もシンプルな使い方では、エージェント名のみが必要です。^[5]

openclaw agents add code-reviewer

実行すると、OpenClawは以下のアクションを実行します。

~/.openclaw/agents/ディレクトリ配下にcode-reviewer/フォルダを作成
デフォルトのagent.mdアイデンティティファイルを自動生成
グローバルデフォルトモデル設定（agents.defaults.model.primary）を継承
openclaw.jsonのエージェントリストにエージェントを登録

作成時にモデルと作業ディレクトリを指定したい場合は、フルパラメータを使用できます。

openclaw agents add code-reviewer \
  --model claude-opus-4-6 \
  --workspace ~/projects/my-app \
  --description "コードレビュー専用AIエージェント"

この単一コマンドでエージェントの作成、モデルバインディング、ワークスペースセットアップが一度に完了します。

2.3 インタラクティブ作成フロー

ガイド付き操作を好む場合は、パラメータなしでagents addを実行できます。

openclaw agents add

システムはインタラクティブモードに入り、以下の情報をステップバイステップで尋ねます。

エージェント名：一意である必要がある。小文字英語とハイフンの使用を推奨（例：data-analyst、doc-writer）
説明：後でエージェントの目的を識別するための簡単な説明
モデル選択：認証済みモデルのリストから選択するか、カスタムモデル識別子を入力
Workspace：エージェントのデフォルト作業ディレクトリを指定するか、グローバルデフォルトを使用

インタラクティブフローは特に初心者に適しています。各ステップでシステムがデフォルト値と説明テキストを提供し、設定エラーのリスクを軽減します。

2.4 エージェント作成の確認

エージェント作成後、以下のコマンドで正しく登録されたことを確認します。

openclaw agents list

以下のような出力が表示されるはずです。

Name             Model               Workspace          Status
─────────────────────────────────────────────────────────────────
default          claude-opus-4-6     ~/                 active
code-reviewer    claude-opus-4-6     ~/projects/my-app  ready
data-analyst     claude-sonnet-4-6   ~/data             ready

activeは現在アクティブなエージェントを示し、readyはエージェントが設定済みだがまだ起動されていないことを示します。^[5]

3. agent.mdアイデンティティ設定

agents addがエージェントの「誕生」だとすれば、agent.mdはエージェントの「魂」である。このMarkdown形式のアイデンティティファイルは、エージェントが自身の役割をどのように理解し、ユーザーとどのように対話し、どの境界内で動作するかを定義する。^[2]

3.1 agent.mdの場所と構造

各エージェントのagent.mdは専用ディレクトリに格納されます。

~/.openclaw/agents/code-reviewer/agent.md

典型的なagent.mdには以下のセクションが含まれます。

# Code Reviewer Agent

## Role
You are a senior software engineer specializing in code quality review.
Your review scope covers: program logic, security vulnerabilities,
performance bottlenecks, maintainability, and naming conventions.

## Behavior Guidelines
- Provide specific, actionable improvement suggestions rather than vague criticism
- Label the severity of each finding: Critical / Warning / Info
- Cite industry best practices (such as OWASP, Clean Code) as supporting evidence
- Provide a summary and overall score (1-10) after the review is complete

## Constraints
- Do not modify the original source code; only provide suggestions
- Do not execute any commands that could affect the production environment
- Review scope is limited to files within the Workspace

## Output Format
Present findings using a Markdown table with columns:
File Path, Line Number, Severity, Issue Description, Improvement Suggestion

3.2 効果的なシステムプロンプトの書き方

agent.mdの内容はエージェントのシステムプロンプトとして注入されるため、記述の品質がエージェントの動作に直接影響する。以下にいくつかの重要な原則を示す。^[2]

役割定義を具体的にする：「あなたはアシスタントです」ではなく、「あなたは10年の経験を持つDevOpsエンジニアで、KubernetesとCI/CDパイプライン設計を専門としています」と書く
動作ガイドラインを定量化する：「回答を簡潔に」ではなく、「ユーザーが詳細な説明を明示的に要求しない限り、各応答を300語以内に抑える」と書く
制約を明示する：エージェントがすべきでないことを明確にリストアップする方が、すべきことを漠然と記述するよりも効果的
出力フォーマットを標準化する：一貫した出力フォーマットにより、エージェントの応答が予測可能になり、下流の統合が容易になる

3.3 動的変数とテンプレート構文

OpenClawのagent.mdは動的変数の注入をサポートしており、アイデンティティ設定内でランタイム環境情報を参照できます。

# Data Analyst Agent

## Context
Current date: {{current_date}}
Working directory: {{workspace_path}}
Agent name: {{agent_name}}

## Role
You are a data analyst responsible for analyzing all data files
in the {{workspace_path}} directory. Analysis results should use
the current date ({{current_date}}) as the report timestamp.

これらの変数はエージェント起動時に実際の値に自動的に置き換えられ、同じagent.mdテンプレートを異なる環境で再利用できます。^[2]

3.4 多言語アイデンティティ設定

OpenClawのエージェントアイデンティティ設定は完全に多言語をサポートしています。ユースケースが主に日本語を扱う場合、agent.mdを直接日本語で記述できます。

# 技術文書ライターエージェント

## 役割定義
あなたはMeta Intelligenceの技術文書スペシャリストです。
エンジニアリングチームの技術実装を、明確で構造化された
技術文書に変換する責任があります。

## 動作規範
- 標準的な技術用語を使用する
- 技術用語は初出時に英語の原語を併記する
- コードブロックは原語のまま保持し、変数名を翻訳しない
- すべての文書には目次、要約、参考文献を含める

エージェントのターゲット言語でアイデンティティ設定を記述することで、モデルがより自然で文脈に適した出力を生成するように効果的にガイドできます。

4. モデル設定

モデルはエージェントの「脳」である。適切なモデルの選択は、エージェントのパフォーマンス、コスト、応答品質に決定的な影響を与える。OpenClawはグローバルデフォルトからPer-Agentオーバーライドまでの3層モデル設定メカニズムを提供し、最大限の柔軟性を保証する。^[3]

4.1 グローバルデフォルトモデル

グローバルデフォルトモデルはagents.defaults.model.primaryを通じて設定され、個別にモデルが指定されていないすべてのエージェントに適用されます。

openclaw config set agents.defaults.model.primary claude-opus-4-6

これは最も基本的な設定です。--modelパラメータを指定せずに新しいエージェントを作成すると、エージェントは自動的にこのグローバルデフォルトを継承します。^[3]

4.2 Fallbackバックアップモデル

本番環境では、単一モデルに依存するのはリスクがある。APIレート制限、サービス障害、プロバイダーのメンテナンスウィンドウはすべてエージェントの突然の停止を引き起こす可能性がある。Fallbackメカニズムがこの問題を解決する。

openclaw config set agents.defaults.model.fallbacks \
  '["claude-sonnet-4-6", "gpt-4o", "gemini-2.5-pro"]'

Primaryモデルが利用不可の場合、システムはFallbackリスト内のモデルを順番に試し、最初に利用可能なものを見つける。切り替えプロセス全体はユーザーに対して透過的であり、エージェントの会話は中断されない。^[3]

4.3 Per-Agentモデルオーバーライド

異なるエージェントは大きく異なるモデル要件を持つ場合がある。深いコード分析を行うエージェントには最も強力な推論能力が必要であり、フォーマットチェックのみを行うエージェントには軽量モデルで十分である。OpenClawでは各エージェントのモデル設定を個別にオーバーライドできる。

openclaw config set agents.code-reviewer.model.primary claude-opus-4-6
openclaw config set agents.format-checker.model.primary claude-haiku-4

Per-Agent設定はグローバルデフォルトよりも優先される。つまり、code-reviewerエージェントが独自のmodel.primaryを持っている場合、agents.defaults.model.primaryの値は無視される。

完全なモデル設定をopenclaw.jsonにJSON5形式で直接記述することもできます。

{
  agents: {
    defaults: {
      model: {
        primary: "claude-opus-4-6",
        fallbacks: ["claude-sonnet-4-6", "gpt-4o"]
      }
    },
    "code-reviewer": {
      model: {
        primary: "claude-opus-4-6",
        // コードレビューには最高の推論能力が必要、ダウングレードなし
        fallbacks: ["claude-opus-4-6"]
      }
    },
    "quick-helper": {
      model: {
        primary: "claude-haiku-4",
        fallbacks: ["gpt-4o-mini"]
      }
    }
  }
}

4.4 実践的なモデル選択アドバイス

タスクタイプに基づいて適切なモデルを選択することは、OpenClawエージェント設定において最も商業的価値のある最適化である。以下はフィールドテスト済みの設定推奨事項である。

深い推論タスク（コードレビュー、アーキテクチャ設計、複雑な分析）：Claude Opus 4.6または同等をPrimaryとし、同ティアの代替をFallbackに
一般的なタスク（ドキュメント作成、データ整理、日常的なQ&A）：Claude Sonnet 4.6またはGPT-4oをPrimaryとして、最高のコストパフォーマンス比
高頻度・低複雑度タスク（フォーマットチェック、分類ラベリング、シンプルなルーティング）：Claude Haiku 4またはGPT-4o-miniをPrimaryとし、コストを大幅に削減

効果的な経験則：2つのモデル間の出力品質の差が10%以下であれば、より低コストのモデルを選択する。^[3]

5. Workspace

WorkspaceはOpenClawのエージェントセキュリティモデルの中核である。エージェントがアクセスできるファイルシステムのスコープを定義し、不正なエージェント操作に対する第一の防衛線となる。^[7]

5.1 デフォルトWorkspace

エージェントにWorkspaceが指定されていない場合、OpenClawはグローバルデフォルトを使用します。

openclaw config set agents.defaults.workspace "~/"

デフォルトWorkspaceをユーザーのホームディレクトリ（~/）に設定すると、エージェントはホームディレクトリ下のすべてのファイルにアクセスできる。個人開発マシンでは通常許容範囲だが、共有サーバーではスコープを狭めるべきである。

5.2 Per-Agent Workspace

各エージェントに独立したWorkspaceを設定するのがベストプラクティスです。^[1]

openclaw config set agents.code-reviewer.workspace "~/projects/my-app"
openclaw config set agents.data-analyst.workspace "~/data/analytics"

これにより、code-reviewerエージェントは~/projects/my-appディレクトリ配下のファイルのみにアクセスでき、~/data/analytics内のデータを読み取ることはできない——会話中にユーザーがそうするよう求めた場合でも。

5.3 Workspaceのセキュリティ上の意味

Workspaceのセキュリティ上の意味は過小評価すべきではない。CrowdStrikeの調査レポートは、AIエージェントのファイルシステムアクセス権限を最も一般的なセキュリティリスクの一つとして特定している。^[7]以下の点に特に注意が必要である。

最小権限の原則：各エージェントのWorkspaceには、タスクの完了に必要な最小限のファイルセットのみを含めるべき
シークレットの隔離：APIキー、パスワード、その他のシークレットを含むファイル（.envなど）は、どのエージェントのWorkspaceにも含めるべきではない
書き込み制限：データの読み取りのみが必要なエージェントには、Workspaceを読み取り専用モードに設定することを検討する
定期レビュー：プロジェクトの進化に伴い、以前は妥当だったWorkspaceのスコープに調整が必要になる場合がある——四半期ごとのレビューを推奨

5.4 複数Workspace設定

一部の高度なシナリオでは、エージェントが隣接しない複数のディレクトリにアクセスする必要がある場合がある。OpenClawは単一エージェントに複数のWorkspaceパスを設定することをサポートしている。

{
  agents: {
    "full-stack-dev": {
      workspace: [
        "~/projects/frontend",
        "~/projects/backend",
        "~/projects/shared-libs"
      ]
    }
  }
}

エージェントはリストされたすべてのディレクトリにアクセスできるが、リストに含まれていないパスにはアクセスできない。これはフルスタック開発シナリオで特に有用であり、フロントエンド、バックエンド、共有ライブラリは通常異なるディレクトリ構造にある。

6. エージェント管理コマンド

OpenClawはエージェントのライフサイクルを管理するための完全なCLIコマンドセットを提供する。^[5]

6.1 全エージェントのリスト表示

openclaw agents list

このコマンドは、名前、モデル、Workspace、ステータスを含むすべての登録済みエージェントを表示する。より詳細な情報には--verboseフラグも使用できる。

openclaw agents list --verbose

Verboseモードでは、各エージェントのFallbackモデルリスト、最終アクティビティ時刻、累積トークン消費量などの追加情報が表示される。

6.2 エージェントアイデンティティ管理

エージェントの表示名、テーマカラー、絵文字などのアイデンティティ情報を変更するには、set-identityコマンドを使用する。

openclaw agents set-identity code-reviewer

システムはインタラクティブモードに入り、エージェントのアイデンティティ属性を設定できる。エージェントルーティング（どのエージェントがどのメッセージを処理するか）はチャネルバインディングメカニズムを通じて管理される。

6.3 エージェントの削除

不要になったエージェントを削除する。

openclaw agents delete code-reviewer

システムは確認を求め、削除前にagent.mdと関連設定のバックアップが必要かどうかを確認する。削除操作はopenclaw.jsonからエージェントの登録レコードを削除し、専用ディレクトリを削除する。

注意：デフォルトエージェント（default）は削除できない——これはシステムが常に少なくとも1つの使用可能なエージェントを持つことを保証するOpenClawの安全設計である。^[5]

6.4 エージェント設定の共有

チーム協業シナリオでは、エージェント設定を他のメンバーと共有する必要がある場合がある。現在、OpenClawにはビルトインのエクスポート/インポート機能はなく、推奨されるアプローチはエージェントの設定ディレクトリを直接コピーすることである。

# エージェントのagent.mdと関連設定をコピー
cp -r ~/.openclaw/agents/code-reviewer/ ~/shared-configs/

# 別のマシンで、まずエージェントを作成してからagent.mdを上書き
openclaw agents add code-reviewer --model claude-opus-4-6
cp ~/shared-configs/code-reviewer/agent.md ~/.openclaw/agents/code-reviewer/

注意：共有設定には認証情報（APIキー）を含めるべきではない。設定を共有する際にシークレットが漏洩しないことを確認すること。

7. 高度な設定

OpenClawエージェントの基本設定はほとんどのユースケースを満たすことができる。しかし、本番環境や高いセキュリティ要件のシナリオでは、より詳細な制御が必要となる。^[1]

7.1 タイムアウト設定

エージェントが長時間実行タスク（大規模コードベース分析、複雑なマルチステップワークフローなど）を実行する際、タイムアウトの問題に遭遇する場合がある。OpenClawではグローバルレベルとPer-Agentレベルの両方でタイムアウトを設定できる。

// グローバルタイムアウト（秒単位）
openclaw config set agents.defaults.timeout 300

// Per-Agentタイムアウト
openclaw config set agents.code-reviewer.timeout 600

大規模プロジェクトを処理する必要があるエージェントには、タイムアウトを10分（600秒）以上に設定することを推奨する。デフォルト値は通常120秒で、シンプルなタスクには十分だが、深い分析タスクには不十分な場合がある。

7.2 AllowlistとBlocklist

AllowlistとBlocklistを使用して、エージェントが実行できる操作のタイプを精密に制御できる。^[7]

{
  agents: {
    "code-reviewer": {
      permissions: {
        // ファイルの読み取りとgitコマンドの実行のみを許可
        allowlist: [
          "file:read",
          "shell:git *"
        ],
        // 書き込みと削除を明示的に禁止
        blocklist: [
          "file:write",
          "file:delete",
          "shell:rm *",
          "shell:sudo *"
        ]
      }
    }
  }
}

BlocklistはAllowlistよりも優先される。つまり、ある操作がAllowlistに含まれていても、Blocklistにも含まれている場合はブロックされる。この「デフォルト拒否、明示的許可」の設計パターンは、セキュリティ設定の業界ベストプラクティスである。

7.3 自動承認設定

デフォルトでは、エージェントは機密操作（Shellコマンドやファイル書き込みなど）を実行する前にユーザーの確認を求める。信頼された環境では、特定のエージェントに対して自動承認を有効化して効率を向上させることができる。

openclaw config set agents.code-reviewer.autoApprove '["file:read", "shell:git diff *"]'

この設定により、code-reviewerエージェントはファイルの読み取りやgit diffコマンドの実行時にユーザーの確認を必要としないが、他の操作は依然として手動承認が必要である。

セキュリティ警告：Auto-Approveのリスクを十分に理解していない限り、書き込み操作やShell実行の自動承認を有効化することは推奨しない。プロンプトインジェクション攻撃の影響を受けたエージェントが自動承認された書き込み権限を持っている場合、深刻なセキュリティインシデントを引き起こす可能性がある。^[7]

7.4 実行権限とセキュリティサンドボックス

OpenClawは複数レイヤーの実行権限制御を提供する。

Shell実行制限：shell.allowlistを使用してエージェントが実行可能なShellコマンドプレフィックスを制限（例：git、npm、pythonのみ許可）
ネットワークアクセス制御：network.allowlistを使用してエージェントがアクセスできるネットワークドメインを制限し、データ流出を防止
サンドボックスモード：サンドボックスモードでは、エージェントのすべてのファイル操作が一時的な隔離環境内で実行される。会話終了後、変更は破棄するか元のWorkspaceにマージできる

{
  agents: {
    "untrusted-agent": {
      sandbox: true,
      shell: {
        allowlist: ["git", "npm test", "python -m pytest"]
      },
      network: {
        allowlist: ["api.github.com", "registry.npmjs.org"]
      }
    }
  }
}

8. モデルFallback戦略

モデルFallbackは単なる「バックアップ」メカニズムではない——適切に設計されたFallback戦略により、コスト、レイテンシ、信頼性の最適なバランスを実現できる。^[3]

8.1 Fallbackチェーンの仕組み

エージェントが推論リクエストを送信すると、OpenClawのモデルルーターは以下の順序で処理する。

ステップ1：Primaryモデルを試す。15秒以内に正常に応答すれば、この結果を使用
ステップ2：PrimaryモデルがHTTP 429（レート制限）または5xx（サーバーエラー）を返した場合、Fallbackリストの最初のモデルに切り替え
ステップ3：Fallbackリスト内の各モデルを順番に試し、成功するかリストが尽きるまで続ける
ステップ4：すべてのモデルが利用不可の場合、ユーザーにエラーを報告し、後で再試行するよう提案

注意：Fallbackの切り替えはモデルレベルのエラー（API利用不可など）でのみ発生する。Primaryモデルが正常に応答したがコンテンツ品質が低い場合、Fallbackはトリガーされない——品質制御は他のメカニズム（Evaluation Hooksなど）で処理する必要がある。

8.2 コスト最適化戦略

Fallbackチェーン内のモデル順序はコストに直接影響する。一般的な戦略は「最強から最弱へ」の順に並べることである。

// 戦略A：品質優先
{
  model: {
    primary: "claude-opus-4-6",        // 最強の推論
    fallbacks: ["claude-sonnet-4-6", "gpt-4o"]  // 段階的ダウングレード
  }
}

// 戦略B：コスト優先
{
  model: {
    primary: "claude-sonnet-4-6",      // 最高のコストパフォーマンス
    fallbacks: ["gpt-4o", "claude-haiku-4"]  // 段階的にコスト削減
  }
}

本番環境では、ほとんどのチームが戦略Bを選択する——中位モデルをPrimaryとし、高性能モデルの予算を深い推論が真に必要なエージェントに確保する。実データに基づくと、この設定により全体のトークンコストを35〜50%削減でき、出力品質の低下は通常5〜8%を超えない。^[3]

8.3 レイテンシに関する考慮事項

Fallbackの切り替えは瞬時ではない——各切り替えに少なくとも1回のフルAPIラウンドトリップレイテンシ（通常1〜3秒）が発生する。Fallbackチェーンが長い場合（例：4〜5のバックアップモデル）、最悪のケースではユーザーが応答を10〜15秒待つ可能性がある。

レイテンシを制御するため、以下を推奨する。

Fallbackリストは2〜3モデルに留める
Primaryモデルと同じリージョンのバックアップモデルを選択し、ネットワークレイテンシを削減
レイテンシに敏感なアプリケーションシナリオでは、fallbackTimeoutを設定して各バックアップモデルの待機時間を制限することを検討

openclaw config set agents.defaults.model.fallbackTimeout 10

この設定は、各Fallbackモデルが最大10秒待った後、次のモデルに移ることを意味する。

8.4 クロスプロバイダーFallback

OpenClawの主要な優位性の一つがモデルアグノスティックであること。Fallbackチェーン内で異なるプロバイダーのモデルを混在させ、プロバイダーレベルの耐障害性を実現できる。

{
  model: {
    primary: "claude-opus-4-6",          // Anthropic
    fallbacks: [
      "gpt-4o",                          // OpenAI
      "gemini-2.5-pro",                  // Google
      "claude-sonnet-4-6"               // Anthropic（異なるモデル）
    ]
  }
}

これにより、プロバイダー全体のサービスがダウンしても、エージェントは他のプロバイダーのモデルを通じて動作を継続できる。ミッションクリティカルなビジネスアプリケーションでは、クロスプロバイダーFallbackは必須の設定である。^[3]

9. 実践例：完全なエージェント設定ワークフロー

これまでのすべての概念を結びつけるため、完全な実践例を示す——ソフトウェア開発チーム向けに3つの専門エージェントを設定する。

9.1 シナリオ説明

あなたのチームはフルスタックウェブアプリケーションを開発しており、3つの役割が必要である。

アーキテクトエージェント：システム設計判断と技術選定を担当
開発者エージェント：コード記述と実装を担当
レビュワーエージェント：コード品質レビューとセキュリティスキャンを担当

9.2 ステップバイステップセットアップ

まず、3つのエージェントを作成する。

openclaw agents add architect \
  --model claude-opus-4-6 \
  --workspace ~/projects/my-app \
  --description "システムアーキテクト——設計判断と技術選定を担当"

openclaw agents add developer \
  --model claude-sonnet-4-6 \
  --workspace ~/projects/my-app \
  --description "フルスタック開発者——コード実装を担当"

openclaw agents add reviewer \
  --model claude-opus-4-6 \
  --workspace ~/projects/my-app \
  --description "コードレビュワー——品質保証とセキュリティスキャンを担当"

次に、レビュワーエージェントに権限制限を設定し、コードを直接修正しないことを保証する。

openclaw config set agents.reviewer.permissions.blocklist \
  '["file:write", "file:delete", "shell:rm *"]'

最後に、開発者エージェントの一般的な操作に自動承認を設定して開発効率を向上させる。

openclaw config set agents.developer.autoApprove \
  '["file:read", "file:write", "shell:npm *", "shell:git *"]'

9.3 完全なopenclaw.json設定

上記のセットアップ完了後、openclaw.jsonのエージェント関連セクションは以下のようになる。

{
  agents: {
    defaults: {
      model: {
        primary: "claude-sonnet-4-6",
        fallbacks: ["gpt-4o", "claude-haiku-4"]
      },
      workspace: "~/",
      timeout: 180
    },
    architect: {
      model: {
        primary: "claude-opus-4-6",
        fallbacks: ["gpt-4o", "gemini-2.5-pro"]
      },
      workspace: "~/projects/my-app",
      timeout: 600
    },
    developer: {
      model: {
        primary: "claude-sonnet-4-6",
        fallbacks: ["gpt-4o"]
      },
      workspace: "~/projects/my-app",
      autoApprove: ["file:read", "file:write", "shell:npm *", "shell:git *"]
    },
    reviewer: {
      model: {
        primary: "claude-opus-4-6",
        fallbacks: ["claude-opus-4-6"]
      },
      workspace: "~/projects/my-app",
      permissions: {
        blocklist: ["file:write", "file:delete", "shell:rm *"]
      }
    }
  }
}

10. よくある質問（FAQ）

Q1：作成後にエージェント名を変更できますか？

はい。openclaw agents set-identity <agent-name>コマンドを使用して、エージェントの表示名やその他のアイデンティティ属性を更新できます。完全な再構築が必要な場合は、削除して新しい名前で再作成できます。^[5]

Q2：エージェント数に制限はありますか？

OpenClaw自体にはエージェント数のハードリミットはありません。ただし、各エージェントはディスクスペース（主にagent.mdと履歴記録）を占有し、多すぎるエージェントの管理は認知的オーバーヘッドを増大させます。実践的には、単一ユーザーが10〜15以上のアクティブエージェントを維持しないことを推奨します。この数を超える場合は、Agent Teamsによるグループ管理を検討してください。^[1]

Q3：エージェント間でagent.mdテンプレートをどう共有しますか？

現在、OpenClawにはビルトインのテンプレート共有メカニズムはありません。推奨されるアプローチは、よく使うagent.mdテンプレートをバージョン管理システム（Gitなど）に保存し、新しいエージェント作成後に手動でコピーするかagents importでインポートすることです。コミュニティの開発者の中には、直接参照できる公開agent.mdテンプレートリポジトリを作成した方もいます。

Q4：Per-Agentモデル設定がグローバルデフォルトをオーバーライドする場合、Fallbackもオーバーライドされますか？

はい。Per-Agentモデル設定は「マージ」ではなく「完全オーバーライド」です。特定のエージェントにmodel.primaryを設定しmodel.fallbacksを設定しない場合、そのエージェントにはFallbackモデルがありません（グローバルデフォルトのFallbackリストは継承されません）。そのため、モデル設定をオーバーライドする際にはPrimaryとFallbackの両方を設定することを推奨します。^[3]

Q5：Workspaceをネットワークパス（NFSマウントポイントなど）に設定できますか？

技術的には可能ですが、推奨しません。OpenClawのファイル操作はローカルファイルシステムのレイテンシ特性を前提としており、ネットワークファイルシステムでは予期しないタイムアウトやパフォーマンスの問題が発生する可能性があります。ネットワークストレージを使用する必要がある場合は、タイムアウト値を適切に増やし、agent.md内でエージェントに頻繁な小ファイルの読み書き操作を避けるよう指示することを推奨します。

Q6：エージェント削除後に会話履歴を復元できますか？

できません。openclaw agents deleteは会話履歴を含むエージェントのすべてのデータを削除します。これらの記録が必要になる可能性がある場合は、削除前に~/.openclaw/agents/<agent-name>/ディレクトリを手動でバックアップしてください。^[5]

Q7：エージェント起動時に特定のコンテキストファイルを自動読み込みする方法は？

agent.md内で{{file:path/to/context.md}}構文を使用して外部ファイルの内容をインクルードできます。これらのファイルはエージェント起動時に読み取られ、システムプロンプトに注入されます。インクルードされるファイルパスはエージェントのWorkspaceルートディレクトリからの相対パスであることに注意してください。^[2]

Q8：OpenClawはどのモデルプロバイダーをサポートしていますか？

2026年2月時点で、OpenClawはAnthropic（Claudeシリーズ）、OpenAI（GPTシリーズ）、Google（Geminiシリーズ）、Mistral、Cohereなどの主要プロバイダーを公式にサポートしています。さらに、OpenAI互換APIフォーマットを通じて、自己ホスティングのオープンソースモデル（Llama、Qwenなど）にも接続できます。^[3]

Q9：autoApprove設定は正規表現をサポートしていますか？

現在、globスタイルのパターンマッチング（例：shell:git *）がサポートされていますが、完全な正規表現はサポートされていません。より複雑なマッチングロジックが必要な場合は、Blocklistによる逆制御を使用することを推奨します——まず広いカテゴリの操作を許可し、次にBlocklistで特定の危険な操作を除外します。

Q10：エージェントのトークン消費量をどう監視しますか？

openclaw gateway usage-costを使用してGatewayレベルの使用コスト統計を確認できます。より詳細な監視には、OpenClawのWebhook機能を組み合わせてトークン消費イベントを外部監視プラットフォーム（GrafanaやDatadogなど）に送信することを推奨します。^[1]