跳轉到主要內容
要從模型中繼之外把工具呼叫透過代理防火牆執行——你自己的代理迴圈 呼叫 evaluate hook,或一個 MCP 客戶端連接到 MCP 閘道——你會 用一個專用的防火牆閘道範圍金鑰驗證,而非一個普通的 sk-orca-… 中繼金鑰。一般金鑰在權杖驗證的防火牆閘道路由上會得到 403（審批 回呼是唯一的例外——它是 HMAC 簽署的,而非權杖把關的）。 本頁涵蓋一個防火牆閘道 API 金鑰是什麼、如何鑄造一個,以及為何該 範圍把關到 Admin+。關於引擎本身,參見 防火牆總覽與 防火牆中的深入參考。

​
1. 一個防火牆閘道 API 金鑰是什麼

你工作區中的每個權杖（API 金鑰）都攜帶一個 is_firewall_gateway 旗標。當它是 true 時,該金鑰被允許觸及防火牆閘道介面：
路由它做什麼
POST /api/v1/firewall/evaluate對一次工具呼叫的派發前裁決。
POST /api/v1/firewall/evaluate_plan對一個多步驟計畫的執行前檢查。
ANY /api/v1/firewall/mcp統一的 MCP 閘道端點。
GET /api/v1/firewall/mcp_servers列舉工作區已註冊的 MCP 伺服器（傳回解密的上游 auth）。
GET /api/v1/firewall/approvals/:id輪詢一個被保留呼叫的審批狀態。
一個 is_firewall_gateway = false（預設）的金鑰是一個正常的中繼 金鑰——它服務 /v1/* 模型流量,而且如果你已透過 firewall_policy_id 綁定一個政策,它的工具呼叫會被內聯治理。但它無法呼叫上面的閘道 路由。
兩個不同的金鑰,兩個不同的工作。 你的中繼金鑰（綁定了 firewall_policy_id）是你的代理用來與模型交談的——防火牆自動治理 它的工具呼叫。一個防火牆閘道金鑰是你的代理執行期用來直接向防火牆 索取一個裁決,或透過閘道代理 MCP tools/call 的。大多數工作區只在 採用 evaluate hook 或 MCP 閘道後才需要一個閘道金鑰。

​
2. 為何一般金鑰會得到 403

閘道範圍解鎖兩個對密鑰敏感的能力,所以它刻意與一般金鑰隔開：
  • /evaluate 接受一個呼叫者提供的 request_id,它流入防火牆 事件與審批記錄。任何模型金鑰若能偽造稽核事件或靜默地探測政策 結果,都會破壞那條軌跡。
  • /mcp_servers 傳回解密的上游憑證,讓 SDK 的代理能派發到你 已註冊的 MCP 伺服器。那是一次憑證 讀取,而非一次模型呼叫。
因此,處理器會檢查所出示權杖的 is_firewall_gateway 旗標,並在它 缺席時傳回 HTTP 403： 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
不要把一個高流量的中繼金鑰重用作一個閘道金鑰,也不要把一個閘道 金鑰重用於中繼流量。把動作平面的金鑰分開,讓它的波及範圍與輪替 獨立於你的模型金鑰。

​
3. 鑄造一個——角色把關到 Admin+

設定 is_firewall_gateway = true 需要工作區 Admin 或以上。一個 Developer 可以建立並編輯一般金鑰,但無法鑄造一個閘道範圍的——該旗標 是一個密鑰管理的事,所以它坐落在一般權杖寫入角色之上。 你在主控台中於你的工作區 API 金鑰下設定金鑰。要鑄造一個閘道 金鑰：
1

以 Admin 身分開啟 API 金鑰

以一個工作區 Admin（或更高）登入,並在主控台中開啟 API 金鑰 頁面。
2

建立一個帶有閘道範圍的金鑰

建立一個新金鑰並啟用它的防火牆閘道範圍 （is_firewall_gateway）。一個 Developer 角色的工作階段不會看見 該範圍生效——伺服器對非 admin 把該旗標保持為 false。
3

複製金鑰一次

在建立時複製完整的金鑰值。之後主控台在顯示時會遮罩它,而讀回 一個閘道金鑰的明文本身就是 Admin+——非 admin 在一個「取得我的 金鑰」回應中會看見閘道列被省略。
降低該旗標比提高它更寬鬆:清除 is_firewall_gateway（把一個閘道 金鑰降級回一個正常金鑰）對任何能編輯該金鑰的角色開放。只有提高 它到 true 是 Admin+。

​
角色閘門一覽

動作角色
建立/編輯一個一般金鑰Developer+
設定 is_firewall_gateway = trueAdmin+
讀回一個閘道金鑰的明文Admin+
清除 is_firewall_gateway（降級）任何金鑰編輯者

​
4. 一個具體範例

你正在執行一個代理迴圈,並想在派發一次工具呼叫之前檢查它。作為 一個 Admin,在主控台中鑄造一個閘道金鑰,然後用那個金鑰從你的執行期 呼叫 evaluate hook： 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer sk-orca-GATEWAY-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" },
    "request_id": "run-42-step-3"
  }'
防火牆會解析你工作區的作用中政策並傳回 裁決——allow、audit、deny、 sanitize、pending_approval,或一個 cap_cost 解析。你的代理依此 行動:在 allow 時派發、在 deny 時跳過、在 pending_approval 時輪詢 審批 id。同一個閘道金鑰驗證 審批輪詢與 MCP 路由。
把一個 MCP 客戶端（Claude Desktop、Cursor、一個代理框架）指向 https://api.orcarouter.ai/api/v1/firewall/mcp？把閘道金鑰用作它的 bearer 權杖。每一次 tools/call 接著會在它被轉送上游之前於 mcp 介面上被評估。

​
5. 這如何契合

一個閘道金鑰驗證閘道路由。它不取代你用來撰寫政策的主控台 工作階段:建立政策、編輯規則、註冊 MCP 伺服器,以及解決審批全都在 你自己的工作階段下於 /api/workspace/firewall/* 上執行（設定、政策, 與 discovered-tool 讀取對每個成員開放;乾跑的測試沙盒與所有寫入需要 Developer+）。閘道金鑰只攜帶來自你機器對機器執行期的裁決請求與 MCP 派發。

範圍：金鑰、政策、工作區

一個金鑰的 firewall_policy_id 與一個閘道範圍如何與工作區邊界相關。

審批

你的閘道金鑰輪詢並重新提交的被保留呼叫流程。

審批 webhook

頻道外解決一個被保留呼叫的 HMAC 簽署回呼。

MCP 伺服器

在閘道端點後方註冊並治理 MCP 伺服器。

​
6. FAQ

把 is_firewall_gateway 提高到 true 是 Admin+。一個設定該 旗標的 Developer 角色寫入會被靜默地保持在 false（這樣同一個 請求上一個不相關的改名或配額編輯仍會成功）——該金鑰只是不會 攜帶該範圍。以一個 Admin 重新建立或編輯它。
出示的金鑰不是閘道範圍的。確認它由一個 Admin 以 is_firewall_gateway = true 鑄造——一個正常的中繼金鑰在這些路由 上總是得到 403。參見 §2。
技術上一個閘道範圍的金鑰也能服務 /v1/* 中繼流量,但把它們分開: 一個中繼金鑰（綁定了 firewall_policy_id）給模型,一個閘道金鑰給 evaluate/MCP/審批路由。獨立輪替、更小的波及範圍。
金鑰在建立後被遮罩,而讀取一個閘道金鑰的明文是 Admin+。如果你在 鑄造時沒有複製它,建立一個新的閘道金鑰並退役舊的那個。