防火牆 API 參考

代理防火牆以兩種方式設定：透過控制台（你的工作階段，與你用於儀表板的相同登入）和透過閘道（你的代理在執行期出示的專用防火牆範圍化 API 金鑰）。這兩個家族位於不同的路徑前綴、採用不同的驗證，並回答不同的問題——「編輯政策」對「評估這個工具呼叫」。本頁是兩者的逐路由地圖。關於政策意味著什麼——裁決、表面、規則、解析——從防火牆和防火牆規則開始。本頁僅是 API 表面。

1. 兩個路由家族

控制台 — 設定

/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 / 成員	讀取設定、政策、預設值、已發現工具、模擬、異常。
Developer+	以上全部，加上每次寫入、`events`/`runs`/`trace` 表面，以及 `test` 試執行。
Admin+	此外，在金鑰上設定 `is_firewall_gateway` 旗標並讀取閘道金鑰的明文。

這個切分是刻意的：viewer 可以看見政策存在以及它會封鎖什麼，但看不到事件背後的原始工具呼叫引數。如果你正在為非開發者建構儀表板，讀取開放的路由是安全的集合。

3. 從控制台設定政策

控制台路由是你撰寫和檢視政策的方式。你在儀表板 UI 中設定一切——這些就是它呼叫的相同端點。

政策與設定

方法與路徑	角色	用途
`GET /api/workspace/firewall/settings`	Member	觀察模式 + 計數。
`PUT /api/workspace/firewall/settings`	Developer+	更新工作區防火牆設定。
`GET /api/workspace/firewall/policies`	Member	列出政策。
`GET /api/workspace/firewall/policies/:id`	Member	單一政策詳情。
`POST /api/workspace/firewall/policies`	Developer+	建立政策。
`PUT /api/workspace/firewall/policies`	Developer+	更新政策。
`DELETE /api/workspace/firewall/policies/:id`	Developer+	刪除政策。
`POST /api/workspace/firewall/rules`	Developer+	新增規則。
`PUT /api/workspace/firewall/rules`	Developer+	更新規則。
`DELETE /api/workspace/firewall/rules/:id`	Developer+	刪除規則。

姿態、預設值與沙箱

方法與路徑	角色	用途
`GET /api/workspace/firewall/presets`	Member	內建規則預設值。
`GET /api/workspace/firewall/templates`	Member	使用情境範本庫。
`POST /api/workspace/firewall/templates/apply`	Developer+	套用範本 → 一個政策 + 其規則。
`POST /api/workspace/firewall/autonomy`	Developer+	套用自主等級（`tight` / `balanced` / `permissive`）。
`POST /api/workspace/firewall/autonomy/undo/:audit_id`	Developer+	從稽核快照一鍵還原。
`GET /api/workspace/firewall/simulate`	Member	某個等級會封鎖什麼（`?level=`）。
`POST /api/workspace/firewall/test`	Developer+	對樣本呼叫試執行政策。

可觀測性

方法與路徑	角色	用途
`GET /api/workspace/firewall/discovered-tools`	Member	所見工具，標記為已覆蓋／缺口。
`GET /api/workspace/firewall/events`	Developer+	列出防火牆事件（可過濾）。
`GET /api/workspace/firewall/events/by-request/:request_id`	Developer+	一個請求的事件。
`GET /api/workspace/firewall/events/aggregate`	Developer+	執行／工作階段彙整。
`GET /api/workspace/firewall/trace/by-run`	Developer+	一次執行的追蹤節點（`?run_id=`）。
`GET /api/workspace/firewall/anomalies`	Member	異常動態。
`POST /api/workspace/firewall/anomalies/snooze`	Developer+	暫緩動態（≤ 7 天）。

MCP 伺服器

在一個受稽核的閘道後方登錄你的代理觸及的 Model Context Protocol 伺服器。憑證以加密儲存並在讀取時遮罩。

方法與路徑	角色	用途
`GET /api/workspace/firewall/mcp_servers`	Member	列出已登錄的伺服器。
`GET /api/workspace/firewall/mcp_servers/:id`	Member	伺服器詳情。
`POST /api/workspace/firewall/mcp_servers`	Developer+	登錄一個伺服器（重複 `name` 時 `409`）。
`PUT /api/workspace/firewall/mcp_servers`	Developer+	更新伺服器。
`DELETE /api/workspace/firewall/mcp_servers/:id`	Developer+	移除伺服器。
`POST /api/workspace/firewall/mcp_servers/:id/probe`	Developer+	可達性 + `tools/list` 握手。

一個伺服器攜帶一個唯一的 name、一個 endpoint、一個 auth_mode （none / bearer / oauth / basic），以及一個健康 status （ok / degraded / down）。完整生命週期和技能隔離參見防火牆 MCP。

4. 在閘道強制執行

這些在防火牆閘道範圍化的金鑰上執行，而非你的工作階段。它們是你的代理迴圈或 MCP 客戶端在執行期呼叫的內容。

方法與路徑	用途
`POST /api/v1/firewall/evaluate`	對一個工具呼叫的派發前裁決。
`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/callback`	HMAC 簽署的審批回呼。

一個具體範例：評估一個工具呼叫

在你的代理派發工具之前，向閘道請求裁決。傳遞防火牆閘道範圍化的金鑰——而非你的中繼 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 派發、網路外向請求）路由經過閘道，它們就受治理。

5. 審批握手（HITL）

pending_approval 裁決將呼叫保留供人工審查。保留期間的 HTTP 錯誤是 firewall_approval_pending。清除它是一個跨兩個路由家族切分的三步迴圈：

審查者解析保留

從控制台（PATCH /api/workspace/firewall/approvals/:id， Developer+），或你自己的系統向 POST /api/v1/firewall/approvals/:id/callback 發送一個 HMAC 簽署的回呼。回呼內聯驗證 HMAC——不接受其他驗證。

你的代理輪詢審批

用閘道金鑰呼叫 GET /api/v1/firewall/approvals/:id，直到狀態翻轉為核准或拒絕。

帶著單次使用權杖重新提交

一旦核准，重新發出原始呼叫，攜帶帶有審批 id 的 X-OrcaRouter-Firewall-Approval 標頭。閘道辨識它並讓那一個呼叫通過。該標頭是單次使用的。

決定是先寫入者勝出且冪等的——對同一個保留的第二次解析是無操作。端到端流程參見防火牆 — 人工審批，讀取裁決參見為何被攔下？。

6. 封鎖看起來會是什麼樣子

結果	HTTP	代碼
被拒絕的工具呼叫（inbound 表面）	`400`	`firewall_blocked`
透過 MCP 閘道拒絕	工具錯誤	`firewall deny: <reason>`
保留待審批	`400`	`firewall_approval_pending`

firewall_blocked 標記為 skip-retry——重新執行完全相同的呼叫只會再次封鎖，所以重試的客戶端會退避而非猛打。完整代碼清單位於錯誤代碼。

7. 相關參考

防護欄 API

內容政策的對等項——文字平面的 /api/guardrail/* 路由。

裁決詞彙表

每個裁決及其對呼叫的作用。

Glob 與 JSONPath

tool_name_glob 和 args_match 背後的匹配語法。

合規性 API

包、簽署報告、居住地和抹除。

8. FAQ

為何我的中繼金鑰在 /api/v1/firewall/evaluate 上得到 403？

閘道路由需要一個防火牆閘道範圍化金鑰——一個設定了 is_firewall_gateway 鑄造的金鑰（一個 Admin+ 動作）。普通中繼金鑰，即使有效，也得到 403。為你的代理執行期鑄造一個專用的閘道金鑰。

viewer 可以讀取防火牆事件嗎？

不行。events、events/aggregate 和 trace 路由是 Developer+ 因為這些記錄攜帶工具呼叫引數來源。Viewer 可以讀取設定、政策、預設值、已發現工具、模擬和異常動態。

我在哪裡解析被保留的審批——控制台還是閘道？

都可以。人工從控制台透過 PATCH /api/workspace/firewall/approvals/:id（Developer+）解析它，或你自己的系統向 POST /api/v1/firewall/approvals/:id/callback 發送 HMAC 簽署的決定。無論哪條路徑解析，代理都輪詢 GET /api/v1/firewall/approvals/:id。

sanitize 會清理工具返回的內容嗎？

不會。sanitize 裁決只修訂工具呼叫引數——絕不修訂工具返回的內容。在 inbound 表面上，那裡還沒有呼叫時引數，sanitize 升級為封鎖。參見防火牆規則。

關於這些控制如何與防護欄及閘道其餘部分組合，參見保護 AI 代理和防護欄與防火牆。

​1. 兩個路由家族

控制台 — 設定

閘道 — 強制執行

​2. 角色一覽

​3. 從控制台設定政策

​政策與設定

​姿態、預設值與沙箱

​可觀測性

​MCP 伺服器

​4. 在閘道強制執行

​一個具體範例：評估一個工具呼叫

​5. 審批握手（HITL）

​6. 封鎖看起來會是什麼樣子

​7. 相關參考

防護欄 API

裁決詞彙表

Glob 與 JSONPath

合規性 API

​8. FAQ

1. 兩個路由家族

2. 角色一覽

3. 從控制台設定政策

政策與設定

姿態、預設值與沙箱

可觀測性

MCP 伺服器

4. 在閘道強制執行

一個具體範例：評估一個工具呼叫

5. 審批握手（HITL）

6. 封鎖看起來會是什麼樣子

7. 相關參考

8. FAQ