メインコンテンツへスキップ
エージェントファイアウォールは 2 つの方法で設定されます：コンソール経由 （あなたのセッション、ダッシュボードで使うのと同じログイン）とゲートウェイ経由 （エージェントが実行時に提示する専用のファイアウォールスコープ API キー）です。 2 つのファミリーは異なるパスプレフィックスに存在し、異なる認証を取り、異なる質問 — 「ポリシーを編集する」対「このツール呼び出しを評価する」 — に答えます。このページは 両方のルート単位のマップです。 ポリシーが何を意味するか — 判定、サーフェス、ルール、解決 — については、 ファイアウォールとファイアウォールルールから 始めてください。このページは API サーフェスのみです。

​
1. 2 つのルートファミリー

コンソール — 設定する

/api/workspace/firewall/*。あなたのセッション / アクセストークン （UserAuth）で認証され、アクティブなワークスペースにスコープされます。ポリシーを 作成し、イベントを読み、MCP サーバーを登録し、承認を解決します。すべてのアクションが ロールゲートされています。

ゲートウェイ — 強制する

/api/v1/firewall/*。ファイアウォールゲートウェイスコープのキー （is_firewall_gateway が設定されたキー）で認証されます。エージェントや MCP クライアントが実行時に呼び出すマシン間サーフェスです。通常のリレーキーはここで 403 を受け取ります。
コンソールルートは sk-orca-… リレーキーを決して取らず、ゲートウェイルートは セッショントークンを決して取りません。これらを混同するのが、ファイアウォールを 初めて配線するときの最も一般的な 401/403 です。/v1/firewall/* 呼び出しに 属する唯一の sk-orca-… キーは、is_firewall_gateway をオンにして発行されたもの です — スコープ、キー、ポリシーを 参照してください。

​
2. ロール一覧

コンソールルートはあなたのワークスペースロールを解決し、それに応じてゲートします。 ツール呼び出しの来歴を運ばない読み取りは任意のメンバーに開放されています；書き込みと、 ツール呼び出し引数を公開するものは Developer+ を必要とします。
ロールできること
Viewer / member設定、ポリシー、プリセット、Discovered tools、simulate、anomalies の読み取り。
Developer+上記すべてに加えて、すべての書き込み、events/runs/trace サーフェス、そして test ドライラン。
Admin+加えて、キーに is_firewall_gateway フラグを設定し、ゲートウェイキーの平文を読む。
この分割は意図的です：viewer はポリシーが存在することとそれが何をブロックするかを 見ることはできますが、イベントの背後にある生のツール呼び出し引数は見られません。 非開発者向けのダッシュボードを構築している場合、読み取り開放ルートが安全なセットです。

​
3. コンソールからポリシーを設定する

コンソールルートは、ポリシーを作成し検査する方法です。すべてをダッシュボード UI で 設定します — これらはそれが呼び出すのと同じエンドポイントです。

​
ポリシーと設定

メソッドとパスロール目的
GET /api/workspace/firewall/settingsMember観察モード + カウント。
PUT /api/workspace/firewall/settingsDeveloper+ワークスペースのファイアウォール設定を更新。
GET /api/workspace/firewall/policiesMemberポリシー一覧。
GET /api/workspace/firewall/policies/:idMember単一ポリシー詳細。
POST /api/workspace/firewall/policiesDeveloper+ポリシーを作成。
PUT /api/workspace/firewall/policiesDeveloper+ポリシーを更新。
DELETE /api/workspace/firewall/policies/:idDeveloper+ポリシーを削除。
POST /api/workspace/firewall/rulesDeveloper+ルールを追加。
PUT /api/workspace/firewall/rulesDeveloper+ルールを更新。
DELETE /api/workspace/firewall/rules/:idDeveloper+ルールを削除。

​
姿勢、プリセット、サンドボックス

メソッドとパスロール目的
GET /api/workspace/firewall/presetsMember組み込みルールプリセット。
GET /api/workspace/firewall/templatesMemberユースケーステンプレートギャラリー。
POST /api/workspace/firewall/templates/applyDeveloper+テンプレートを適用 → 1 ポリシー + そのルール。
POST /api/workspace/firewall/autonomyDeveloper+自律性レベルを適用（tight / balanced / permissive）。
POST /api/workspace/firewall/autonomy/undo/:audit_idDeveloper+監査スナップショットからのワンクリック取り消し。
GET /api/workspace/firewall/simulateMemberレベルが何をブロックするか（?level=）。
POST /api/workspace/firewall/testDeveloper+サンプル呼び出しに対してポリシーをドライラン。

​
可観測性

メソッドとパスロール目的
GET /api/workspace/firewall/discovered-toolsMember見たツール、covered / gap とフラグ。
GET /api/workspace/firewall/eventsDeveloper+ファイアウォールイベント一覧（フィルタ可能）。
GET /api/workspace/firewall/events/by-request/:request_idDeveloper+1 つのリクエストのイベント。
GET /api/workspace/firewall/events/aggregateDeveloper+Runs / sessions ロールアップ。
GET /api/workspace/firewall/trace/by-runDeveloper+実行のトレースノード（?run_id=）。
GET /api/workspace/firewall/anomaliesMember異常フィード。
POST /api/workspace/firewall/anomalies/snoozeDeveloper+フィードをスヌーズ（≤ 7 日）。

​
MCP サーバー

エージェントが到達する Model Context Protocol サーバーを、単一の監査済みゲートウェイの 背後で登録します。クレデンシャルは暗号化して保存され、読み取り時にはマスクされます。
メソッドとパスロール目的
GET /api/workspace/firewall/mcp_serversMember登録済みサーバー一覧。
GET /api/workspace/firewall/mcp_servers/:idMemberサーバー詳細。
POST /api/workspace/firewall/mcp_serversDeveloper+サーバーを登録（name 重複で 409）。
PUT /api/workspace/firewall/mcp_serversDeveloper+サーバーを更新。
DELETE /api/workspace/firewall/mcp_servers/:idDeveloper+サーバーを削除。
POST /api/workspace/firewall/mcp_servers/:id/probeDeveloper+到達可能性 + tools/list ハンドシェイク。
サーバーは一意の name、endpoint、auth_mode （none / bearer / oauth / basic）、そしてヘルス status （ok / degraded / down）を持ちます。フルライフサイクルとスキル隔離については ファイアウォール MCPを参照してください。

​
4. ゲートウェイで強制する

これらは、あなたのセッションではなく、ファイアウォールゲートウェイスコープのキー上で 動作します。エージェントループまたは MCP クライアントが実行時に呼び出すものです。
メソッドとパス目的
POST /api/v1/firewall/evaluate1 つのツール呼び出しに対するディスパッチ前の判定。
POST /api/v1/firewall/evaluate_planマルチステッププランの実行前チェック。
ANY /api/v1/firewall/mcp統合された MCP ゲートウェイエンドポイント。
GET /api/v1/firewall/mcp_serversワークスペースの登録済みサーバーを列挙。
GET /api/v1/firewall/approvals/:id保留された呼び出しの承認状態をポーリング。
POST /api/v1/firewall/approvals/:id/callbackHMAC 署名付き承認コールバック。

​
ひとつの具体例：ツール呼び出しを評価する

エージェントがツールをディスパッチする前に、ゲートウェイに判定を尋ねます。リレー sk-orca-… キーではなく、ファイアウォールゲートウェイスコープのキーを渡します： 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer <firewall-gateway-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" }
  }'
レスポンスは判定を運びます — allow、audit、deny、sanitize、または pending_approval。deny では呼び出しをスキップし、理由をモデルに表面化します； sanitize ではゲートウェイが返すクリーニングされた引数を転送します（sanitize は ツール呼び出しの引数のみをリダクトします — ツールが返すコンテンツは決して触りません）； pending_approval では下記の承認ループに入ります。
ゲートウェイは、それを横切る呼び出しを評価します — evaluate フック、MCP ゲートウェイ、 そしてリレーパスです。エージェントが完全にプロセス内で実行し、OrcaRouter に一度も 触れないツールは、その視界の外です。重要な呼び出し（モデル媒介のツール、MCP ディスパッチ、ネットワーク egress）をゲートウェイ経由でルーティングすれば、統制されます。

​
5. 承認ハンドシェイク（HITL）

pending_approval 判定は、呼び出しを人間のために保留します。保留中の HTTP エラーは firewall_approval_pending です。それをクリアするのは、両方のルートファミリーに またがる 3 ステップのループです：
1

レビュアーが保留を解決する

コンソールから（PATCH /api/workspace/firewall/approvals/:id、Developer+）、 あるいはあなた自身のシステムが HMAC 署名付きコールバックを POST /api/v1/firewall/approvals/:id/callback にポストします。コールバックは HMAC をインラインで検証します — 他の認証は受け付けられません。
2

エージェントが承認をポーリングする

ゲートウェイキーを使って GET /api/v1/firewall/approvals/:id を、状態が approved または rejected に変わるまでポーリングします。
3

単回使用トークンとともに再送信する

承認されると、承認 id を持つ X-OrcaRouter-Firewall-Approval ヘッダーを携えて 元の呼び出しを再発行します。ゲートウェイはそれを認識し、その 1 つの呼び出しを 通します。ヘッダーは単回使用です。
決定はファーストライタウィンかつ冪等です — 同じ保留の 2 回目の解決は no-op です。 エンドツーエンドのフローについては ファイアウォール — 人間による承認を、 判定の読み方については なぜブロックされたのか？を参照してください。

​
6. ブロックがどう見えるか

結果HTTPコード
拒否されたツール呼び出し（inbound サーフェス）400firewall_blocked
MCP ゲートウェイ経由で拒否tool errorfirewall deny: <reason>
承認のために保留400firewall_approval_pending
firewall_blocked は skip-retry とマークされています — 同一の呼び出しを再実行 しても再びブロックされるだけなので、リトライするクライアントはハンマリングする代わりに バックオフします。完全なコードリストは エラーコードにあります。

​
7. 関連リファレンス

ガードレール API

コンテンツポリシーのピア — テキストプレーンのための /api/guardrail/* ルート。

判定用語集

すべての判定と、それが呼び出しに何をするか。

Glob と JSONPath

tool_name_glob と args_match の背後にあるマッチング文法。

コンプライアンス API

パック、署名付きレポート、レジデンシー、そして消去。

​
8. FAQ

ゲートウェイルートはファイアウォールゲートウェイスコープのキー — is_firewall_gateway を設定して発行されたもの（Admin+ のアクション） — を必要とします。通常のリレーキーは、 有効なものでも 403 を受け取ります。エージェントランタイム用に専用のゲートウェイ キーを発行してください。
いいえ。events、events/aggregate、trace ルートは、レコードがツール呼び出し 引数の来歴を運ぶため Developer+ です。Viewer は設定、ポリシー、プリセット、 Discovered tools、simulate、異常フィードを読めます。
どちらでも。人間がコンソールで PATCH /api/workspace/firewall/approvals/:id（Developer+）経由で解決するか、 あなた自身のシステムが HMAC 署名付き決定を POST /api/v1/firewall/approvals/:id/callback にポストします。どのパスが解決したかに 関わらず、エージェントは GET /api/v1/firewall/approvals/:id をポーリングします。
いいえ。sanitize 判定は、ツール呼び出しの引数のみをリダクトします — ツールが 返すコンテンツは決して触りません。inbound サーフェスでは、まだ呼び出し時の引数が ないため、sanitize はブロックにエスカレートします。 ファイアウォールルールを参照してください。
これらのコントロールがガードレールおよびゲートウェイの他の部分とどう構成されるかに ついては、AI エージェントのセキュリティと ガードレール vs ファイアウォールを 参照してください。