메인 콘텐츠로 건너뛰기
요청이 HTTP 400을 반환하고 에이전트가 멈췄습니다. 코드를 변경하기 전에, 게이트웨이는 이미 무슨 일이 일어났는지 알려주었습니다: 오류 코드가 어떤 컨트롤이 발동했는지를 명시하고, 두 피드 중 하나가 정확한 규칙을 명시합니다. 이 페이지는 조회-및-추적 흐름입니다 — 코드를 읽고, 올바른 피드를 열고, 규칙을 찾으세요. 한 가지만 기억한다면: 보안 컨트롤로부터의 400은 프롬프트의 버그가 아닙니다. 정책이 제 일을 하는 것입니다. 여러분의 일은 어떤 정책인지를 찾고, 그 다음 호출을 고칠지 규칙을 완화할지 결정하는 것입니다.

​
1. 내 llm 요청이 왜 차단되었나요? — 오류 코드에서 시작하세요

호스팅된 게이트웨이의 모든 보안 차단은 OpenAI 형태의 오류 본문 안에 머신 판독 가능한 code와 함께 HTTP 400을 반환합니다. 그 코드가 길의 첫 갈림길입니다 — 어떤 제어 평면을 디버그할지와 어떤 피드를 열지를 알려줍니다. 
{
  "error": {
    "message": "tool \"shell.exec\" blocked by firewall: destructive shell command",
    "code": "firewall_blocked",
    "type": "invalid_request_error"
  }
}

guardrail_blocked

Guardrail 콘텐츠 규칙이 요청 입력 또는 모델 출력에 발동했습니다. Matches 피드에서 추적하세요. §2 참조.

firewall_blocked

Firewall 규칙이 툴 호출을 거부했습니다. Events 피드에서 추적하세요. §3 참조.

firewall_approval_pending

툴 호출이 사람 승인을 위해 보류됨 — 거부된 것이 아닙니다. 디버그하지 말고 해결하세요. §4 참조.
세 코드 모두 skip-retry입니다: 동일한 호출을 다시 실행하면 동일한 정책으로 라우팅되어 다시 차단됩니다. 재시도는 낭비된 지연입니다 — 대신 입력 또는 규칙을 고치세요. 전체 코드 표는 오류 코드에 있습니다.

​
2. guardrail_blocked — Matches에서 규칙 찾기

guardrail_blocked는 여러분의 키(또는 워크스페이스 기본값)에 연결된 콘텐츠 정책이 요청 입력 또는 모델 출력에 대해 block 액션을 실행했음을 의미합니다. 차단 메시지는 guardrail과 규칙을 명시하며, 요청은 쿼터를 소모하지 않습니다 — 입력 차단은 미터링 전에 발동하고; 출력 차단은 사전 소비된 쿼터를 환불합니다. 추적 방법:
1

Matches 피드를 연다

콘솔에서 Guardrails 페이지의 Matches 탭으로 갑니다 (GET /api/guardrail/match, Member). 발동하는 모든 규칙이 여기에 내려앉습니다 — 그 RuleType, Action, Stage, 그리고 pii: email, phone이나 matched 3 keyword(s) 같은 Detail 문자열.
2

차단으로 필터한다

action = block과 요청 시각으로 필터하세요. 매치된 행은 규칙 유형 (pii, regex, keyword, max_chars, llm_judge, grounding, external)과 그것이 input 또는 output 단계에 발동했는지를 알려줍니다.
3

실제로 무엇이 매치되었는지 본다

기본적으로 피드는 규칙이 발동했다는 사실과 그 Detail 메타 문자열을 기록합니다 — 매치된 부분 문자열은 아닙니다. 그 guardrail에서 Log raw content를 켜서(기본 꺼짐, 프라이버시 보수적 자세) 트리아지를 위해 문제의 문자열을 캡처하세요. 이 토글은 비소급적입니다.
잘못되었다고 생각하는 차단이 있나요? 매치를 열고 거짓 양성으로 표시하세요 (POST /api/guardrail/match/:id/mark-fp, Admin). 출시 전에 수정을 증명하려면, 규칙을 편집하고 guardrail 편집기의 Test 탭에서 샘플을 다시 실행하세요 — 업스트림 호출 없음, 쿼터 없음.

​
한 가지 구체적 예시

고객 SSN이 담긴 지원 답변을 보냅니다. 여러분의 pii-shield guardrail은 ssn에 대해 차단하는 entity_actions 오버라이드를 가지고 있습니다: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "ssn"],
  "entity_actions": { "ssn": "block" }
}
게이트웨이는 400 guardrail_blocked를 반환합니다. Matches 피드는 RuleType: pii, Action: block, Stage: input, Detail: pii: ssn을 보여줍니다. 수정은 코드 변경이 아니라 제품 결정입니다: 오버라이드를 mask로 완화하거나(모델은 SSN을 결코 보지 않고, 호출은 통과), 차단을 유지하고 업스트림에서 SSN을 제거하세요. 전체 규칙 유형 및 PII 엔티티 레퍼런스는 Guardrails를 참조하세요.

​
3. firewall_blocked — Events에서 판정 찾기

firewall_blocked는 Firewall 정책이 툴 호출을 거부했음을 의미합니다. inbound 표면에서는 400으로 표면화되고; MCP 게이트웨이를 통해서는 모델이 크래시 대신 반응할 수 있도록 툴 오류 (firewall deny: <reason>)로 표면화됩니다. 오류 metadata는 이유 코드, 위험 요인, 점수를 담습니다. Events 피드에서 추적하세요(GET /api/workspace/firewall/events, Developer+) — 모든 평가 뒤의 원시 레코드. 각 이벤트는 판정과 그것이 관측된 표면을 담습니다:
Verdict여러분의 차단에 대해 무엇을 의미하는가
deny규칙(또는 default_verdict)이 호출을 차단했습니다. 이것이 여러분의 firewall_blocked입니다.
audit허용되었지만 로깅됨 — 정책이 shadow mode에 있으면 [shadow] “would deny” 포함.
cap_cost실행의 누적 지출이 규칙별 센트 상한을 넘었습니다; deny로 해석됩니다.
1

Events를 거부로 필터한다

verdict=deny로 필터한 뒤, tool, run_id, 또는 session_id로 정확한 호출을 분리하세요. 이벤트는 매치된 규칙과 표면 — inbound, response, mcp, 또는 egress — 을 명시합니다.
2

매치된 규칙의 이유를 읽는다

이유 문자열(예: destructive shell command, egress host not allowed)은 규칙이 툴 이름, args_match 절, 또는 egress 목적지에 매치되었는지를 알려줍니다. 판정 용어집과 glob 및 JSONPath 레퍼런스가 매칭을 해독합니다.
3

Test 샌드박스로 확인한다

Firewall Test 탭(POST /api/workspace/firewall/test, Developer+)에서 동일한 툴 호출을 재생하여 판정, 매치된 규칙, 이유를 보세요 — 아무것도 디스패치되지 않고 아무것도 로깅되지 않습니다.
cap_cost 거부는 규칙 오발이 아닙니다 — 에이전트 실행이 여러분이 설정한 지출 한도에 도달한 것입니다. 실행이 루핑 중이거나(Runs 롤업과 이상 피드에서 retry_loop 확인) 또는 상한이 작업에 비해 정말로 너무 낮은 것입니다. 그저 재시도하지 말고, 상한을 신중하게 올리세요.

​
4. firewall_approval_pending — 보류됨, 거부 아님

firewall_approval_pending은 차단으로 취급하지 말아야 하는 유일한 400입니다. pending_approval 판정이 툴 호출을 사람을 위해 보류했고; 오류 본문은 승인 id를 담습니다. 호출은 실패하지 않았습니다 — 기다리고 있습니다.
  1. 검토자가 해결합니다 — 콘솔에서(Developer+) 또는 여러분 자신의 HMAC 웹훅 콜백(POST /api/v1/firewall/approvals/:id/callback)을 통해.
  2. 에이전트가 오류에서 받은 id에 대해 GET /api/v1/firewall/approvals/:id(게이트웨이 토큰)를 폴링합니다.
  3. 일단 승인되면, 일회용 X-OrcaRouter-Firewall-Approval 헤더와 함께 원래 호출을 재제출하고, 게이트웨이는 그 한 번 통과시킵니다.
전체 HITL 루프는 Firewall → Human approval을 참조하세요.

​
5. 보안 차단이 아닌가요? 먼저 키를 배제하세요

모든 400이 guardrail 또는 firewall 판정인 것은 아닙니다. 피드를 뒤지기 전에, 키 제약을 배제하세요 — 이들은 어떤 정책이 실행되기 전에 거부하며 위의 보안 코드를 담지 않습니다:
키의 model_limits 허용 목록이 요청된 모델을 포함하지 않습니다. 목록 밖의 모델에 대한 요청은 사전에 거부됩니다. 모델을 키에 추가하거나 허용된 모델을 호출하세요.
키가 allow_ips 허용 목록을 가지고 있고 요청이 그 밖의 주소에서 왔습니다. 호출자의 IP / CIDR을 추가하거나 허용된 네트워크에서 호출하세요.
키의 credit_limit_usd 한도가 소진되었습니다(0은 무제한). 상한을 올리거나 여유가 있는 키로 교체하세요.
게이트웨이 훅(evaluate, MCP 디스패치)은 is_firewall_gateway=true인 키를 요구합니다. 일반 릴레이 키는 403을 받습니다. 그 라우트들을 위해 firewall-gateway-scoped 키를 발급하세요.

​
6. 2분 트리아지 흐름

프롬프트 또는 응답 텍스트에 대한 차단

코드가 guardrail_blocked → Matches를 열고, action=block으로 필터하고, Stage + Detail을 읽으세요. 콘텐츠 또는 규칙을 고치고; guardrail Test 탭에서 증명하세요.

툴 호출에 대한 차단

코드가 firewall_blocked → Events를 열고, verdict=deny로 필터하고, 표면 + 이유를 읽으세요. 호출 또는 규칙을 고치고; firewall Test 탭에서 증명하세요.

호출이 보류됨

코드가 firewall_approval_pending → 승인 id를 폴링하고 승인 헤더와 함께 재제출하세요. 디버그할 것 없음.

위 어느 것도 아님

보안 코드 없음 → 키를 확인하세요: model_limits, allow_ips, credit_limit_usd, 또는 누락된 게이트웨이 스코프에 대한 403.

​
7. 관련 레퍼런스

오류 코드

전체 코드 표 — 게이트웨이가 반환할 수 있는 모든 차단, 보류, 거부.

판정 용어집

각 firewall 판정이 무엇을 의미하고 언제 deny로 해석되는지.

Glob 및 JSONPath

여러분의 호출에 매치된 tool_name_glob과 args_match를 해독하세요.

Guardrails vs Firewall

어느 평면이 발동했는지 — 텍스트 스크리닝 또는 액션 거버넌스.
컨트롤 자체는 Guardrails와 Firewall을; 그들이 멈추는 위협은 위협 모델에서 시작하세요.