OpenClaw Tools の設定ガイド：エージェントの権限をスマートに管理する

エージェントを開発しているとき、どのツールを使わせるかの管理に悩むことはありませんか？セキュリティのために特定の機能を制限したいけれど、設定が複雑すぎると開発のスピードが落ちてしまいます。

OpenClaw では、browser、canvas、nodes、cron といった機能を「first-class agent tools」として提供しています。これらは以前の openclaw-* skills に代わるもので、型定義がしっかりされており、シェルを介さずエージェントが直接利用できるのが特徴です。

必要なもの

openclaw.json 設定ファイル
OpenClaw の実行環境

クイックスタート

ツールの利用をコントロールするための最短ステップを紹介します。OpenClaw では、openclaw.json の tools.allow または tools.deny セクションで設定を行います。

1. 特定のツールを無効化する

特定のツールをモデルプロバイダーに送信したくない場合は、tools.deny にツール名を記述します。

{
  tools: { deny: ["browser"] },
}

設定のポイントは以下の通りです：

大文字と小文字は区別されません。
* ワイルドカードが使用可能です（"*" ですべてのツールを対象にできます）。

2. プロファイルでベース設定を適用する

tools.profile を使うと、用途に合わせたツールのセットを一括で許可できます。

minimal: session_status のみ
coding: group:fs, group:runtime, group:sessions, group:memory, image
messaging: group:messaging, sessions_list, sessions_history, sessions_send, session_status
full: 制限なし（未設定と同じ）

3. プロファイルと個別の許可・拒否を組み合わせる

プロファイルをベースにしつつ、特定のツールを追加したり除外したりできます。

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

4. エージェントごとに設定を上書きする

グローバル設定だけでなく、特定のエージェントだけに異なるプロファイルを割り当てることも可能です。

{
  tools: { profile: "coding" },
  agents: {
    list: [
      {
        id: "support",
        tools: { profile: "messaging", allow: ["slack"] },
      },
    ],
  },
}

トラブルシューティング

設定がうまくいかない場合は、以下の挙動を確認してください。

拒否設定の優先: tools.allow と tools.deny の両方に記載がある場合、deny（拒否）が優先されます。
不明なプラグインの警告: tools.allow に未知のプラグイン名やロードされていない名前だけを指定した場合、OpenClaw は警告をログに出力します。このとき、コアツールが利用可能な状態を維持するために許可リストは無視されます。

さらに詳しく知りたい場合や、設定のサポートが必要な場合は AI Setup Assistant を活用してください。

次のステップ

```mdx
---
title: Provider-specific tool policy
description: 特定の Provider や Model ごとに Tool の使用制限をカスタマイズする方法について解説します。
---

特定の LLM を使っているときに、「この Model は不安定だから、特定の Tool は使わせたくない」と感じたことはありませんか？ すべての Model に同じ Tool セットを強制すると、特定の環境でエラーが頻発する原因になります。

グローバルな設定を壊さずに、特定の Provider だけ Tool を制限したい。そんな時に役立つのが `tools.byProvider` です。

## 必要なもの

- `tools` 設定の基本構造への理解
- `agents.list` を含む設定ファイルへのアクセス権

## クイックスタート

`tools.byProvider` を使用すると、特定の Provider（または `provider/model`）に対して、Tool の利用範囲を**さらに制限**できます。

この設定の重要なポイントは、適用されるタイミングです。ベースとなる Tool profile の**後**、かつ allow/deny リストの**前**に評価されます。そのため、この設定でできるのは Tool セットを「絞り込む」ことだけで、新しく Tool を追加することはできません。

Provider の指定には、`google-antigravity` のような `provider` 名、または `openai/gpt-5.2` のような `provider/model` 形式のどちらも使用可能です。

### 設定例 1：グローバル設定を維持しつつ、特定の Provider を制限する
以下の例では、全体で `coding` プロファイルを使用していますが、Google Antigravity に対してのみ `minimal` プロファイルを適用して制限しています。

```json
{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

設定例 2：不安定な Endpoint 用に allow リストを絞り込む

特定の Model でのみ Tool の動作が不安定な場合は、その Model 専用の allow リストを定義するのがベストな方法です。

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

設定例 3：特定の Agent に対して Provider 制限をかける

Agent ごとに設定を上書きすることも可能です。特定の Provider を使う時だけ、その Agent が使える Tool を制限できます。

{
  agents: {
    list: [
      {
        id: "support",
        tools: {
          byProvider: {
            "google-antigravity": { allow: ["message", "sessions_list"] },
          },
        },
      },
    ],
  },
}

トラブルシューティング

Tool が追加されない: byProvider は Tool セットを「狭める」ためのものです。ベースのプロファイルやグローバルの allow リストに含まれていない Tool を、ここで新しく追加することはできません。
設定が反映されない: Provider キーの形式を確認してください。provider 名が正しいか、あるいは provider/model のスラッシュ区切りが正しいかチェックが必要です。

困ったときは AI Setup Assistant を活用してください。

次のステップ

開発を進めていると、ツールごとに細かく権限を設定するのが面倒に感じることがあります。特にツールの数が増えてくると、設定ファイルが長くなりすぎて管理が大変になりますよね。

セキュリティを保ちつつ、設定をスッキリさせるには「グループ化」が一番の解決策です。

## 必要なもの

- Tool policies (global, agent, または sandbox) の設定権限

## クイックスタート

最も効率的な方法は、`tools.allow` や `tools.deny` で `group:*` エントリを使用することです。これにより、複数のツールをまとめて指定できます。

利用可能なグループは以下の通りです：

- `group:runtime`: `exec`, `bash`, `process`
- `group:fs`: `read`, `write`, `edit`, `apply_patch`
- `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`
- `group:memory`: `memory_search`, `memory_get`
- `group:web`: `web_search`, `web_fetch`
- `group:ui`: `browser`, `canvas`
- `group:automation`: `cron`, `gateway`
- `group:messaging`: `message`
- `group:nodes`: `nodes`
- `group:openclaw`: すべての組み込み OpenClaw ツール（provider plugins は除外されます）

例えば、ファイル関連のツールとブラウザのみを許可したい場合は、次のように記述します。

```json
{
  tools: {
    allow: ["group:fs", "browser"],
  },
}

Plugins + tools

Plugins を導入することで、標準セット以外の 追加ツール や CLI コマンドを利用できるようになります。インストールと設定については Plugins を、ツールの使用ガイドをプロンプトに注入する方法については Skills を参照してください。

便利なオプションツールには以下のようなものがあります：

Lobster: 型定義されたワークフローランタイムで、承認の再開が可能です（Gateway ホストに Lobster CLI が必要です）。
LLM Task: 構造化された出力を得るための JSON 専用 LLM ステップです（オプションでスキーマ検証が可能です）。

トラブルシューティング

問題: Lobster ツールが正常に動作しない。
解決策: Gateway ホストに Lobster CLI がインストールされていることを確認してください。

設定についてさらに詳しく知りたい場合や、個別のケースで困ったときは AI Setup Assistant に相談してください。

次のステップ

開発を進めていると、AIエージェントに「テキストを生成するだけ」以上のことをさせたい場面がよくあります。例えば、シェルコマンドを実行して環境を構築したり、ブラウザを操作して最新のドキュメントを確認したりといった作業です。エージェントが外部環境と直接やり取りできないと、結局人間が手作業でコマンドをコピー＆ペーストすることになり、自動化のメリットが薄れてしまいます。

OpenClawには、開発者のワークフローを直接サポートするための強力なツール群が用意されています。これらのツールを適切に配置することで、エージェントはコードの実行からメッセージの送信、さらには複雑なブラウザ操作までこなせるようになります。

必要なもの

OpenClawの動作環境
Brave API key（web_search を利用する場合）
Node アプリ（カメラ、スクリーン、Canvas機能を利用する場合）
Playwright（browser ツールで高度なスナップショットを利用する場合）

クイックスタート

5分でツールを使えるようにする最小限のステップです。

exec の有効化: デフォルトで多くの環境で利用可能ですが、権限設定を確認してください。
Web検索の設定: openclaw configure --section web を実行するか、BRAVE_API_KEY を設定します。
ブラウザの準備: browser.enabled=true（デフォルト）であることを確認します。
バックグラウンド処理の管理: process ツールを使用して、長時間実行されるタスクを監視します。

Tool inventory

`apply_patch`

1つ以上のファイルに対して構造化されたパッチを適用します。複数の箇所（multi-hunk）を一度に編集する場合に使用してください。 ※実験的機能：tools.exec.applyPatch.enabled で有効化します（OpenAI モデルのみ対応）。

`exec`

ワークスペース内でシェルコマンドを実行します。

主要パラメータ:

command (必須)
yieldMs (タイムアウト後に自動でバックグラウンド実行に移行、デフォルト 10000)
background (即座にバックグラウンドで実行)
timeout (秒単位。時間を超えるとプロセスを終了、デフォルト 1800)
elevated (bool。elevated モードが許可されている場合にホスト上で実行。エージェントがサンドボックス化されている場合のみ挙動が変わります)
host (sandbox | gateway | node)
security (deny | allowlist | full)
ask (off | on-miss | always)
node (host=node の場合の node ID または名前)
pty: true: リアルな TTY が必要な場合に設定。

注意点:

バックグラウンド実行時は status: "running" と sessionId を返します。
バックグラウンドセッションのポーリング、ログ確認、書き込み、終了、クリアには process を使用します。
process が許可されていない場合、exec は同期的に実行され、yieldMs や background は無視されます。
elevated は tools.elevated と agents.list[].tools.elevated の両方で許可されている必要があります。これは host=gateway + security=full のエイリアスです。
host=node は macOS コンパニオンアプリやヘッドレスのノードホスト（openclaw node run）をターゲットにできます。
承認と allowlist については Exec approvals を参照してください。

`process`

バックグラウンドの exec セッションを管理します。

主要アクション:

list, poll, log, write, kill, clear, remove

注意点:

poll は、完了時に新しい出力と終了ステータスを返します。
log は行ベースの offset および limit をサポートします（offset を省略すると最後の N 行を取得します）。
process のスコープはエージェント単位です。他のエージェントのセッションは見えません。

`web_search`

Brave Search API を使用して Web 検索を行います。

主要パラメータ:

query (必須)
count (1–10。デフォルトは tools.web.search.maxResults から取得)

注意点:

Brave API key が必要です（openclaw configure --section web または BRAVE_API_KEY 環境変数）。
tools.web.search.enabled で有効化します。
レスポンスはキャッシュされます（デフォルト 15 分）。
詳細は Web tools を参照してください。

`web_fetch`

URL から読み取り可能なコンテンツを取得・抽出します（HTML から markdown または text へ変換）。

主要パラメータ:

url (必須)
extractMode (markdown | text)
maxChars (長いページを切り詰める制限値)

注意点:

tools.web.fetch.enabled で有効化します。
maxChars は tools.web.fetch.maxCharsCap（デフォルト 50000）によって制限されます。
レスポンスはキャッシュされます（デフォルト 15 分）。
JavaScript を多用するサイトには browser ツールの使用を推奨します。
詳細設定は Web tools を、アンチボット対策のフォールバックについては Firecrawl を参照してください。

`browser`

OpenClaw が管理する専用ブラウザを制御します。

主要アクション:

status, start, stop, tabs, open, focus, close
snapshot (aria または ai)
screenshot (画像ブロックと MEDIA:<path> を返却)
act (UI 操作: click, type, press, hover, drag, select, fill, resize, wait, evaluate)
navigate, console, pdf, upload, dialog

プロファイル管理:

profiles: すべてのブラウザプロファイルとステータスを一覧表示。
create-profile: 自動割り当てられたポート（または cdpUrl）で新しいプロファイルを作成。
delete-profile: ブラウザを停止し、ユーザーデータを削除して設定から除去（ローカルのみ）。
reset-profile: プロファイルのポート上の孤立プロセスを終了（ローカルのみ）。

共通パラメータ:

profile (任意。デフォルトは browser.defaultProfile)
target (sandbox | host | node)
node (任意。特定の node ID または名前を指定)

注意点:

browser.enabled=true が必要です。
すべてのアクションで profile パラメータを指定でき、複数インスタンスをサポートします。
プロファイル名は小文字の英数字とハイフンのみ使用可能です（最大 64 文字）。
ポート範囲は 18800-18899 です（最大約 100 プロファイル）。
リモートプロファイルはアタッチのみ可能です（start/stop/reset は不可）。
snapshot は Playwright がインストールされている場合、デフォルトで ai になります。アクセシビリティツリーが必要な場合は aria を使用してください。
act には snapshot から取得した ref（AI スナップショットの場合は 12、role スナップショットの場合は e12）が必要です。
デフォルトでの act → wait の使用は避け、UI 状態を待機できない例外的な場合にのみ使用してください。

`canvas`

node Canvas を操作します（プレゼン、評価、スナップショット、A2UI）。

主要アクション:

present, hide, navigate, eval
snapshot (画像ブロックと MEDIA:<path> を返却)
a2ui_push, a2ui_reset

注意点:

内部で gateway の node.invoke を使用します。
node が指定されない場合、デフォルト（接続されている単一ノードまたはローカルの mac ノード）が選択されます。
A2UI は v0.8 のみ対応しています。
動作確認例: openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"

`nodes`

ペアリングされたノードの検出、通知送信、カメラやスクリーンのキャプチャを行います。

主要アクション:

status, describe
pending, approve, reject (ペアリング管理)
notify (macOS の system.notify)
run (macOS の system.run)
camera_snap, camera_clip, screen_record
location_get

注意点:

カメラやスクリーンのコマンドを実行するには、ノードアプリがフォアグラウンドである必要があります。
動画は FILE:<path> (mp4) を返します。
位置情報は JSON（緯度、経度、精度、タイムスタンプ）を返します。
run パラメータには command (引数の配列)、cwd、env、タイムアウト設定などが含まれます。

run の例:

{
  "action": "run",
  "node": "office-mac",
  "command": ["echo", "Hello"],
  "env": ["FOO=bar"],
  "commandTimeoutMs": 12000,
  "invokeTimeoutMs": 45000,
  "needsScreenRecording": false
}

`image`

設定された画像モデルを使用して画像を分析します。

主要パラメータ:

image (必須。パスまたは URL)
prompt (任意。デフォルトは “Describe the image.”)
model (任意。モデルの上書き)
maxBytesMb (任意。サイズ制限)

注意点:

agents.defaults.imageModel が設定されている場合、またはデフォルトモデルから推論可能な場合に利用できます。
メインのチャットモデルとは独立して画像モデルを直接使用します。

`message`

Discord, Slack, MS Teams などの各チャンネルでメッセージ送信やアクションを行います。

主要アクション:

send (テキストとメディア。MS Teams は Adaptive Cards の card に対応)
poll (WhatsApp, Discord, MS Teams の投票)
react, read, edit, delete
thread-create, thread-list, thread-reply
channel-info, member-info, role-info

注意点:

WhatsApp の send と poll、MS Teams の poll は Gateway を経由します。その他は直接送信されます。
アクティブなチャットセッションに紐付いている場合、誤送信を防ぐため送信先がそのセッションのターゲットに制限されます。

`cron`

Gateway の cron ジョブとウェイクアップを管理します。

主要アクション:

status, list
add, update, remove, run, runs
wake (システムイベントのエンキュー)

注意点:

add には cron.add RPC と同じスキーマのジョブオブジェクトを渡します。
update は { jobId, patch } を受け取ります。

`gateway`

実行中の Gateway プロセスの再起動や設定変更を適用します。

主要アクション:

restart (インプロセスでの再起動。デフォルトは無効)
config.get, config.schema
config.apply (バリデーション、書き込み、再起動)
config.patch (部分更新と再起動)
update.run (アップデート実行と再起動)

注意点:

応答を中断しないよう、delayMs（デフォルト 2000）を使用します。
restart を有効にするには commands.restart: true の設定が必要です。

`sessions_list` / `sessions_history` / `sessions_send` / `sessions_spawn` / `session_status`

セッションの一覧表示、履歴の確認、他のセッションへの送信などを行います。

主要パラメータ:

sessions_list: kinds?, limit?, activeMinutes?
sessions_history: sessionKey (または sessionId), limit?
sessions_send: sessionKey, message, timeoutSeconds?
sessions_spawn: task, agentId?, model?
session_status: sessionKey?, model?

注意点:

main は標準的なダイレクトチャットのキーです。
sessions_spawn はサブエージェントを起動する非ブロッキング操作で、即座に status: "accepted" を返します。
sessions_send は timeoutSeconds > 0 の場合、完了まで待機します。
エージェント間のやり取り（ping-pong）は、session.agentToAgent.maxPingPongTurns（0–5）で制限されます。

`agents_list`

現在のセッションが sessions_spawn でターゲットにできるエージェント ID を一覧表示します。

注意点:

結果は agents.list[].subagents.allowAgents の allowlist によって制限されます。
["*"] が設定されている場合は、すべてのエージェントが含まれます。

トラブルシューティング

exec が同期的に実行される: process ツールが許可されているか確認してください。許可されていない場合、yieldMs や background 設定は無視されます。
ブラウザの act が動作しない: 事前に snapshot を取得し、そこから得られた正しい ref（数値または e プレフィックス付き）を使用しているか確認してください。
メッセージ送信のステータスが ok なのに届かない: status: "ok" はエージェントの実行が完了したことを意味し、相手先への配信完了を保証するものではありません。
カメラやスクリーンのキャプチャに失敗する: ターゲットとなるノード上のアプリがフォアグラウンドで動作している必要があります。

セットアップに関する詳細は AI Setup Assistant で確認できます。

次のステップ

Exec approvals - 実行承認の設定
Web tools - Web 検索と取得の詳細
Firecrawl - 高度な Web スクレイピング
Browser profiles - ブラウザプロファイルの管理

---
title: "Parameters (common) の設定と推奨ワークフロー"
description: "Gateway ツールや Browser ツールで共通して使用されるパラメータの設定方法と、エージェントを効率的に動かすための推奨フローを解説します。"
---

開発を進める中で、ツールごとに異なるパラメータ設定に頭を悩ませることはありませんか？特に複数のコンポーネントを連携させる際、認証や接続先の設定がバラバラだと、予期せぬエラーで作業が止まってしまいがちです。

共通のパラメータ仕様を正しく把握することで、ツールの動作を安定させ、デバッグの時間を大幅に短縮できます。ここでは、Gateway ツールや Browser ツールを扱う際に知っておくべき基本ルールを整理しました。

## 必要なもの

設定を始める前に、源文書で定義されている以下の要素を確認してください。

- `gatewayUrl`: Gateway への接続先 URL
- `gatewayToken`: 認証が必要な場合に使用するトークン
- `timeoutMs`: 処理のタイムアウト時間
- `profile`: Browser ツールのプロファイル設定
- `target`: 実行環境のターゲット（`sandbox` | `host` | `node`）
- `node`: 特定の Node ID または名前

## クイックスタート

まずは最小限の設定でツールを動かしてみましょう。以下の手順で進めるのが最も効率的です。

1. **Gateway 接続の確認**
   `canvas`、`nodes`、`cron` などの Gateway ツールを使用する場合、デフォルトの `gatewayUrl` は `ws://127.0.0.1:18789` です。

2. **明示的な認証設定**
   `gatewayUrl` を独自に設定する場合は、必ず `gatewayToken` もセットで記述してください。ツールは環境変数や他の設定から認証情報を引き継がないため、明示的な指定がないとエラーになります。

3. **Browser ツールの実行ターゲット選択**
   Browser ツールを使用する際は、`target` パラメータで `sandbox`、`host`、`node` のいずれかを指定します。

4. **推奨フローの適用**
   目的に応じて、以下の推奨される操作手順（フロー）をエージェントに実行させます。

### 推奨されるエージェントフロー

#### Browser automation（ブラウザ操作）:
1. `browser` → `status` または `start` で起動状態を確認
2. `snapshot` (ai または aria) で構造を把握
3. `act` (click/type/press) で操作を実行
4. 視覚的な確認が必要な場合は `screenshot` を取得

#### Canvas render（キャンバス描画）:
1. `canvas` → `present`
2. 必要に応じて `a2ui_push` を実行
3. `snapshot` で状態を保存

#### Node targeting（特定ノードの操作）:
1. `nodes` → `status` で一覧を確認
2. 選択したノードに対して `describe` を実行
3. `notify` / `run` / `camera_snap` / `screen_record` のいずれかを実施

## Safety

安全な運用のために、以下のルールを守ることを推奨します。

- `system.run` を直接使用するのは避けてください。`nodes` → `run` を使用し、必ずユーザーの明示的な同意を得るようにします。
- カメラやスクリーンキャプチャを使用する際は、ユーザーの同意を尊重してください。
- メディア関連のコマンドを呼び出す前に、`status` や `describe` を使って権限があるか確認してください。

## How tools are presented to the agent

エージェント（モデル）に対して、ツールは以下の 2 つの経路で同時に提示されます。

1. **System prompt text**: 人間が読める形式のリストとガイドライン。
2. **Tool schema**: モデル API に送信される、構造化された関数定義。

エージェントは「どのようなツールが存在するか」と「それをどう呼び出すか」の両方を認識します。ツールがシステムプロンプトまたはスキーマのいずれにも含まれていない場合、モデルはそのツールを呼び出すことができません。

## トラブルシューティング

設定中によくある問題と解決策です。

- **認証エラーが発生する**
  `gatewayUrl` を設定した際、`gatewayToken` を省略していませんか？ツールは設定や環境の認証情報を継承しないため、明示的な指定が必要です。

- **メディアコマンドが失敗する**
  事前に `status` や `describe` で権限を確認しているかチェックしてください。ユーザーの同意が得られていない場合、実行は制限されます。

不明な点がある場合は、[AI Setup Assistant](/docs/) で質問してみてください。

## 次のステップ

- [Node targeting の詳細](/docs/nodes)
- [Browser ツールの高度な設定](/docs/browser)

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。

OpenClaw Tools の設定ガイド：エージェントの権限をスマートに管理する

必要なもの

クイックスタート

1. 特定のツールを無効化する

2. プロファイルでベース設定を適用する

3. プロファイルと個別の許可・拒否を組み合わせる

4. エージェントごとに設定を上書きする

トラブルシューティング

次のステップ

設定例 2：不安定な Endpoint 用に allow リストを絞り込む

設定例 3：特定の Agent に対して Provider 制限をかける

トラブルシューティング

次のステップ

Plugins + tools

トラブルシューティング

次のステップ

必要なもの

クイックスタート

Tool inventory

apply_patch

exec

process

web_search

web_fetch

browser

canvas

nodes

image

message

cron

gateway

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

agents_list

トラブルシューティング

次のステップ

まだ解決しませんか？

`apply_patch`

`exec`

`process`

`web_search`

`web_fetch`

`browser`

`canvas`

`nodes`

`image`

`message`

`cron`

`gateway`

`sessions_list` / `sessions_history` / `sessions_send` / `sessions_spawn` / `session_status`

`agents_list`