Saltar para o conteúdo principal
Você pode vincular um guardrail a uma única chave de API, mas a maioria dos times quer um piso: uma política de conteúdo que se aplica a cada chave do workspace, a menos que uma chave opte por outra coisa. Esse piso é o padrão do workspace — um guardrail, marcado is_default, ao qual o gateway cai sempre que uma chave não tem vínculo explícito. Esta página cobre o guardrail de IA padrão: como defini-lo, como a resolução funciona, e a única invariante que vale memorizar — um padrão por workspace. Para a referência completa do motor, veja a referência de Guardrails.
Tudo aqui é uma ação de console no gateway hospedado (api.orcarouter.ai), executada sob sua própria sessão. Apenas a chamada /v1/* final usa uma chave de relay sk-orca-.... Promover ou rebaixar um guardrail padrão exige Developer+ no workspace.

​
1. Por que definir um guardrail de IA padrão

O vínculo por chave é preciso mas fácil de esquecer — emita uma nova chave, pule o menu, e essa chave entra em produção com zero filtragem. Um padrão de workspace fecha essa lacuna:

Chaves sem vínculo o herdam

Qualquer chave cujo guardrail_id esteja não definido (0/null) é filtrada pelo padrão automaticamente — incluindo chaves criadas depois de você defini-lo.

Edite uma vez, desloque o workspace inteiro

O padrão vive no gateway, não em cada chave. Edite-o e toda chave que o herda se desloca na próxima chamada — sem redeploy, sem mudança de SDK.
Um padrão comum: faça um PII Shield conservador ser o padrão do workspace para que nada vaze por acidente, depois deixe chaves específicas vincularem uma política mais estrita ou mais frouxa quando precisarem.

​
2. Promova um guardrail ao padrão

No console, abra Guardrails, edite o guardrail que você quer como piso e ligue Set as workspace default. Salve.
1

Crie ou escolha um guardrail

Escreva uma política como de costume — ex.: o preset PII Shield, uma única regra pii que mascara no estágio both.
2

Marque como padrão e salve

Ligue Set as workspace default e salve. A flag is_default do guardrail liga.
3

Deixe as chaves sem vínculo

Qualquer chave sem guardrail explícito agora herda esta. Chaves que já apontam para um guardrail diferente mantêm seu vínculo.
O padrão também precisa estar habilitado para entrar em vigor. Um guardrail marcado is_default mas desabilitado resolve para sem enforcement — o toggle e o estado habilitado são interruptores independentes.

​
3. Um padrão por workspace — a promoção é atômica

Esta é a invariante: no máximo um guardrail por workspace carrega is_default. Você nunca precisa desmarcar manualmente o antigo. Quando você promove um novo guardrail a padrão, o gateway rebaixa o padrão anterior na mesma transação — a promoção e o rebaixamento ou ambos acontecem ou nenhum. Nunca há uma janela em que dois guardrails sejam o padrão, e nunca uma janela em que nenhum seja. 
Before:   billing-pii   ← is_default ✓
          legal-redact

Promote "legal-redact" to default
          (single transaction)
          ┌─────────────────────────────────────────┐
          │  legal-redact  → is_default = true       │
          │  billing-pii   → is_default = false       │
          └─────────────────────────────────────────┘

After:    billing-pii
          legal-redact  ← is_default ✓
Você não precisa rebaixar primeiro. Apenas promova o novo — o padrão antigo é limpo para você, atomicamente. O guardrail rebaixado ainda existe e continua habilitado; ele simplesmente não age mais como o fallback. Chaves vinculadas explicitamente a ele não são afetadas.
A mesma troca atômica se aplica quer você promova na criação (marcar um guardrail novinho como padrão) quer na edição (ligar a flag em um existente).

​
4. Como a resolução usa o padrão

Para qualquer requisição, o gateway resolve exatamente um guardrail (ou nenhum) nesta ordem fixa:
OrdemO que se aplica
1O guardrail_id explícito da chave — se existe e está habilitado.
2O guardrail is_default habilitado do workspace (a chave não tinha vínculo).
3Nenhum — a requisição é byte-idêntica à de um workspace sem política.
Um vínculo explícito de chave nunca cai silenciosamente para o padrão. Se uma chave aponta para um guardrail e esse guardrail está desabilitado, a chave resolve para sem enforcement — não para o padrão do workspace. Desabilitar um guardrail vinculado é o botão de desligar para essa chave. (As políticas de firewall se comportam diferente aqui — uma política de firewall vinculada e desabilitada cai sim para o padrão do workspace. Veja Guardrails vs. firewall.)
Então o padrão é o fallback apenas para chaves sem vínculo. Ele nunca sobrepõe uma chave que fez uma escolha explícita.
Fail-open por design. Se a resolução de padrão encontrar um erro transitório, o gateway degrada para sem enforcement em vez de falhar a requisição. A segurança degrada; a disponibilidade é preservada.

​
5. Exemplo prático

Digamos que seu workspace tem dois guardrails e três chaves:
  • pii-shield — marcado como padrão do workspace, habilitado.
  • strict-block — bloqueia cartões de crédito, não é padrão.
  • Chave A — sem vínculo. Chave B — vinculada a strict-block. Chave C — vinculada a um guardrail que você desabilitou depois.
Uma requisição que menciona um email resolve assim:
guardrail_id está não definido, então a resolução cai para o guardrail is_default habilitado pii-shield. O email é mascarado para [EMAIL] antes de o modelo ver.
O vínculo explícito vence. strict-block se aplica; o padrão nunca é consultado.
O vínculo existe mas seu guardrail está desabilitado, então a resolução retorna nenhum — ela não cai para pii-shield. A requisição não é filtrada.
Agora promova strict-block a padrão e salve. Em uma transação strict-block.is_default vira true e pii-shield.is_default vira false. A chave A imediatamente herda strict-block na próxima chamada — sem nenhuma mudança na própria chave.

​
6. Confirmando que a requisição atinge o padrão

Envie uma requisição com uma chave sem vínculo e verifique o Feed de matches — um match registrado sob seu guardrail padrão confirma que o fallback disparou: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Reply to jane@acme.com please"}
    ]
  }'
Se o padrão é uma política de PII com mascaramento, o gateway reescreve o email para [EMAIL] antes de encaminhar. Se ele bloqueia, a chamada retorna HTTP 400 guardrail_blocked — que não custa cota e é marcada como skip-retry. Veja o erro guardrail_blocked para o formato completo da resposta.
Quer provar o comportamento do padrão antes de qualquer chave depender dele? Abra a aba Test no editor do guardrail e rode uma amostra no estágio input — sem chamada upstream, sem cota. Veja Teste e eval.

​
7. Para onde ir a seguir

Vincular a uma única chave

Quando uma chave precisa de uma política diferente do piso do workspace.

Crie seu primeiro guardrail

O loop de ponta a ponta — criar, testar, vincular, enviar.

Resolução e escopo

Como chaves, políticas e workspaces se compõem.

Versionamento

Cada promoção escreve uma linha de histórico — diff e revert.
Promover ou rebaixar o padrão é em si uma mudança versionada — abra History no guardrail para ver quando is_default mudou e quem o fez. Para o motor completo, leia a referência de Guardrails.