Configurazione del gateway delle app Claude

Struttura dei file

• listen: indirizzo di binding, URL pubblico, terminazione TLS
• oidc: il vostro provider di identità (IdP), inclusi emittente, client, mappatura delle attestazioni e chi può accedere
• session: i bearer token che il gateway emette, con segreto e durata
• store: PostgreSQL, per le concessioni dei dispositivi e i contatori dei limiti di velocità
• upstreams: dove va l’inferenza, sia che si tratti di Anthropic, Amazon Bedrock, Claude Platform su AWS, Agent Platform di Google Cloud, o Microsoft Foundry

• login_notice: un avviso che gli sviluppatori vedono quando accedono
• admin: autenticazione dell’API Admin e conservazione dei limiti di spesa
• enforcement: comportamento fail-open o fail-closed dei limiti di spesa
• pricing: tariffe contrattuali e un moltiplicatore per il misuratore di spesa e per le cifre di costo che gli sviluppatori vedono
• models e auto_include_builtin_models: elenco di modelli curato dall’amministratore e ID per upstream
• managed: politiche di impostazioni gestite per gruppo IdP
• telemetry: inoltro OTLP al vostro stack di osservabilità
• access_control, limits, timeouts, rate_limits: IP allow/deny, limiti di dimensione delle richieste, tempo di primo byte upstream e limiti di accesso per IP
• load_test_mode: test di carico del gateway senza chiamare un provider di modelli

Espansione dei segreti

Sezioni obbligatorie

listen

oidc

Autenticazione del client con certificato

openssl req -x509 -newkey rsa:2048 -nodes -keyout idp-client.key -out idp-client.crt -days 365 -subj "/CN=claude-gateway"

oidc:
  issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
  client_id: <application-id>
  token_endpoint_auth_method: private_key_jwt
  client_assertion:
    private_key_pem: ${file:/etc/gateway/idp-client.key}
    certificate_pem: ${file:/etc/gateway/idp-client.crt}

[gateway] 2026-10-01T23:07:40.512Z info oidc: client authentication private_key_jwt; certificate CN=claude-gateway, SHA-1 thumbprint DE92821854EE8BAA1D98C758FAA04AABE80B9F57, expires Oct  1 23:07:31 2027 GMT

Ruotare il certificato del client

1. Carica il nuovo certificato sull’IdP accanto a quello vecchio.
2. Sostituisci i file della chiave e del certificato che gateway.yaml carica, quindi riavvia il gateway. Se esegui più repliche, un riavvio progressivo funziona, perché l’IdP ha entrambi i certificati finché non rimuovi quello vecchio.
3. Dopo che ogni replica si è riavviata, rimuovi il vecchio certificato dall’IdP.

Richieste IdP attraverso un forward proxy

Egress solo tramite proxy

export HTTPS_PROXY=http://proxy.corp.example.com:3128
export NO_PROXY=
export no_proxy=
export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

• HTTPS_PROXY o HTTP_PROXY è impostato.
• NO_PROXY e no_proxy sono vuoti. Se la tua piattaforma inietta una delle due nei pod, imposta entrambe a un valore vuoto sul container del gateway. Elencare un collettore di telemetria in NO_PROXY mantiene disattivato l’egress solo tramite proxy.
• CLAUDE_GATEWAY_ALLOW_LOOPBACK non è attivato. Un collettore o un IdP sul loopback del pod stesso non può essere combinato con l’egress solo tramite proxy, perché un indirizzo loopback consegnato al proxy sarebbe quello dell’host del proxy, quindi assegna invece a quei servizi un indirizzo che il proxy può raggiungere. Per lo stesso motivo il gateway rifiuta del tutto i nomi di tipo localhost mentre l’egress solo tramite proxy è attivo.

session

store

upstreams

Messaggi di errore dell’upstream

• Un upstream ha restituito uno stato su cui il gateway non esegue il failover: la risposta di quell’upstream. Il gateway non prova altri upstream.
• Ogni upstream provato dal gateway ha fallito in un modo su cui esegue il failover: l’ultimo 429. Quando nessuno ha restituito un 429, il gateway preferisce, in ordine, l’ultimo 401 o 403, l’ultimo 404 e l’ultimo 501. Quando nessuno ha restituito nessuno di questi, il 502 del gateway stesso, all upstreams failed (N attempted). N conta le tue voci upstreams, incluse quelle saltate, meno quelle il cui elenco groups esclude lo sviluppatore.

• 400 o 413 nell’envelope di errore standard di Anthropic: il messaggio dell’upstream stesso, come prompt is too long. Claude Platform on AWS, Agent Platform e Microsoft Foundry restituiscono questo envelope per i rifiuti dell’API del modello.
• 400 o 413 nel formato proprio del provider: un token capability_rejected:. Quando il gateway non riesce a classificare il rifiuto, upstream rejected the request su un 400 o request too large for this upstream su un 413.
• Qualsiasi altro stato: un testo generico per stato, come upstream rate limit exceeded su un 429.

API Anthropic

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}
    # OR an OAuth bearer (e.g. a Workload-Identity-Federation-exchanged token):
    #   oauth_token: ${file:/var/run/secrets/anthropic-oauth-token}
    # base_url: https://api.anthropic.com   # default; override for a forward proxy

• api_key: invia x-api-key. Ruotala nella Claude Console e aggiorna la variabile d’ambiente.
• oauth_token: invia Authorization: Bearer. Usa la forma bearer quando la tua organizzazione emette token a breve durata invece di chiavi API a lunga durata. Il bearer viene letto una volta all’avvio, quindi aggiornalo rimontando il segreto e riavviando.

upstreams:
  - provider: anthropic
    auth:
      federation_rule_id: ${ANTHROPIC_FEDERATION_RULE_ID}
      organization_id: ${ANTHROPIC_ORGANIZATION_ID}
      identity_token_file: /var/run/secrets/anthropic/id-token
      # workspace_id: wrkspc_...       # required if the rule covers >1 workspace
      # service_account_id: svac_...   # optional expected-target check

Header di identità per utente per un proxy che gestisci

upstreams:
  - provider: anthropic
    base_url: https://upstream-gateway.internal.example.com
    auth:
      api_key: ${PROXY_KEY}
    forward_user_identity: true        # default false

Amazon Bedrock

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # preferred: AWS default credential chain
    # OR explicit credentials:
    # auth:
    #   aws_access_key_id: ${AWS_AKID}
    #   aws_secret_access_key: ${AWS_SK}
    #   aws_session_token: ${AWS_ST}
    # OR a Bedrock API bearer token:
    # auth:
    #   aws_bearer_token: ${AWS_BEARER_TOKEN}
    # Override the bedrock-runtime endpoint for FIPS or VPC-endpoint deployments:
    # base_url: https://bedrock-runtime-fips.us-east-1.amazonaws.com

Applicare un guardrail di Amazon Bedrock

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123                    # guardrail ID or full ARN
      version: "1"                     # a published version number, or DRAFT
 # keep the quotes: a bare 1 fails at boot

Aggiungi i tag di input del guardrail

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123
      version: "1"
      input_tagging: user_messages

Cosa non coprono i tag di input

• Contenuto a cui il gateway non applica tag: i messaggi che il tuo valore di input_tagging esclude, le definizioni degli strumenti, gli input delle chiamate agli strumenti, le immagini e i PDF, tra gli altri. A meno che tu non imposti all_messages_and_system, anche il prompt di sistema è privo di tag.
• Risultati degli strumenti: contengono ciò che restituiscono gli strumenti di Claude, come i contenuti dei file e le pagine web. Nei test di Anthropic, un filtro di parole non li ha valutati, con o senza tag.

Registrare quale filtro del guardrail è scattato

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}
    guardrail:
      id: gr-abc123
      version: "1"
    guardrail_trace: true              # default false; beside guardrail, not inside it

Bedrock in un altro account AWS

upstreams:
  - name: bedrock-isolated
    provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
      # external_id: ${BEDROCK_ROLE_EXTERNAL_ID}   # when the role's trust policy requires one

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::111111111111:role/claude-gateway" },
    "Action": "sts:AssumeRole",
    "Condition": { "StringEquals": { "sts:ExternalId": "your-external-id" } }
  }]
}

• Se STS rifiuta o non è raggiungibile, il gateway non invia la richiesta con le credenziali proprie dell’upstream. Registra l’errore STS con ciò che occorre verificare, quindi prova l’upstream successivo che hai elencato. Messaggi di errore dell’upstream descrive ciò che riceve il client quando nessun upstream ha successo. Un upstream successivo senza assume_role servirebbe la richiesta con le proprie credenziali, quindi elencane uno solo se è ciò che desideri.
• Il gateway chiama l’endpoint STS regionale sts.<region>.amazonaws.com, che la sua rete deve poter raggiungere. Per l’endpoint FIPS, imposta AWS_USE_FIPS_ENDPOINT=true nell’ambiente del gateway anziché use_fips_endpoint in un file di configurazione AWS.
• assume_role richiede credenziali di origine SigV4: il gateway si rifiuta di avviarsi quando è impostato accanto a aws_bearer_token.
• Senza un elenco groups, ogni sviluppatore ammesso dal gateway può usare questo upstream. Per limitare i modelli che uno sviluppatore può usare, imposta availableModels in una policy managed.
• Per evitare che un modello servito tramite il ruolo venga servito anche da un altro account, assegnagli un id personalizzato la cui mappa upstream_model contenga solo il nome di questo upstream. Per un id di questo tipo il gateway salta ogni altro upstream, quindi né la richiesta né il conteggio dei token per una richiesta interrotta possono eseguire il failover su un altro account.
• Una richiesta per un nome di modello integrato può comunque raggiungere questo upstream, e il gateway la firma con lo stesso ruolo. Elenca questo upstream per ultimo a meno che il suo account non debba servire anche quei modelli.

models:
  - id: restricted-claude-opus-4-8      # a custom id, not a built-in model name
    upstream_model:
      bedrock-isolated: us.anthropic.claude-opus-4-8   # the only upstream that serves it

Attribuzione dei costi AWS per sviluppatore

upstreams:
  - provider: bedrock
    region: us-east-1
    auth: {}                           # the gateway's own role: it only calls STS
    assume_role:
      role_arn: arn:aws:iam::123456789012:role/claude-gateway-bedrock-user
      session_name: email              # or sub

Endpoint Mantle di Amazon Bedrock

upstreams:
  - provider: mantle
    region: us-east-1
    models: [claude-opus-4-7, claude-haiku-4-5]   # required
    auth: {}                           # AWS default credential chain
  - provider: bedrock
    region: us-east-1
    auth: {}

• guardrail: il gateway non applica alcun guardrail Bedrock alle richieste che invia a Mantle, quindi si rifiuta di avviarsi quando è elencato un upstream mantle mentre un qualsiasi upstream bedrock imposta guardrail.
• assume_role: impostalo sull’upstream mantle stesso. Senza di esso, le richieste servite da Mantle vengono inviate con le credenziali auth proprie dell’upstream mantle.

Claude Platform on AWS

upstreams:
  - provider: anthropicAws
    region: us-east-1
    workspace_id: wrkspc_...
    auth:
      api_key: ${ANTHROPIC_AWS_API_KEY}   # sent as x-api-key
    # OR SigV4 via the AWS default credential chain:
    # auth: {}
    # OR explicit SigV4 credentials:
    # auth:
    #   aws_access_key_id: ${AWS_ACCESS_KEY_ID}
    #   aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    # Override the derived endpoint:
    # base_url: https://aws-external-anthropic.us-east-1.api.aws

Google Cloud Agent Platform

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    auth: {}                           # preferred: Application Default Credentials
    # OR a service account key file:
    # auth: { service_account_json: /secrets/sa.json }
    # Override the aiplatform endpoint for Private Service Connect:
    # base_url: https://us-east5-aiplatform.p.googleapis.com

Microsoft Foundry

upstreams:
  - provider: foundry
    resource: example-foundry              # https://example-foundry.services.ai.azure.com
    auth: { use_azure_ad: true }        # preferred: DefaultAzureCredential / Managed Identity
    # OR an API key:
    # auth:
    #   api_key: ${FOUNDRY_API_KEY}

Header statici sulle richieste upstream

upstreams:
  - provider: vertex
    region: us-east5
    project_id: example-prod
    base_url: https://upstream-proxy.internal.example.com
    auth: {}
    headers:
      x-source: claude-apps-gateway
      x-proxy-token: ${PROXY_TOKEN}

• authorization e x-api-key
• host, content-type e user-agent
• Qualsiasi nome che inizia con anthropic-, x-goog-, x-amz- o x-amzn-

Più upstream

• L’upstream ha restituito un errore
• L’upstream non serve il modello richiesto
• L’upstream ha un elenco groups che esclude lo sviluppatore

• Upstream provider: anthropic: timeouts.upstream_ttfb_ms, 120 secondi per impostazione predefinita
• Altri provider: fino a un’ora. Per abbreviare questa attesa per le richieste in streaming, imposta timeouts.upstream_ttfb_ms sul gateway v2.1.295 o successivo. Le richieste al modello non in streaming attendono comunque fino a un’ora

upstreams:
  # Primary: provisioned throughput in your home region.
  - name: bedrock-pt
    provider: bedrock
    region: us-east-1
    auth: {}
  # Overflow: on-demand cross-region.
  - name: bedrock-od
    provider: bedrock
    region: us-west-2
    auth: {}
  # Different account: a separate Bedrock allotment via static keys.
  - name: bedrock-acct2
    provider: bedrock
    region: us-east-1
    auth:
      aws_access_key_id: ${ACCT2_AKID}
      aws_secret_access_key: ${ACCT2_SK}
  # Last resort: direct Anthropic API.
  - name: anthropic-fallback
    provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

# Per-upstream model IDs are keyed on the upstream's `name:`.
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      bedrock-pt: arn:aws:bedrock:us-east-1:111111111111:provisioned-model/abcdef
      bedrock-od: us.anthropic.claude-opus-4-8
      bedrock-acct2: us.anthropic.claude-opus-4-8
      anthropic-fallback: claude-opus-4-8

Invia ogni team al proprio upstream

upstreams:
  - name: bedrock-payments
    provider: bedrock
    region: us-east-1
    auth: {}
    assume_role:
      role_arn: arn:aws:iam::111111111111:role/claude-gateway-bedrock
    groups: [payments-eng]
  - name: bedrock-search
    provider: bedrock
    region: us-east-1
    auth: {}
    assume_role:
      role_arn: arn:aws:iam::222222222222:role/claude-gateway-bedrock
    groups: [search-eng]
  - name: bedrock-shared               # no groups: open to everyone, so listed last
    provider: bedrock
    region: us-east-1
    auth: {}

• Voci: scrivi ogni gruppo esattamente come lo invia il tuo IdP nel claim dei gruppi, che legge anche match.groups. Il gateway si rifiuta di avviarsi quando trova un elenco vuoto o una voce vuota. Non verifica una voce rispetto al tuo IdP, quindi una voce che non corrisponde a nessuno non genera alcun avviso.
• Ordine: metti per ultimo un upstream che non ha un elenco groups. Serve tutti, quindi se elencato prima prende le richieste di un team prima dell’upstream di quel team.

Cosa succede quando uno sviluppatore non appartiene a nessun gruppo elencato

API Error: 400 you aren't in a group that can use this gateway. Ask your administrator to add you to one

• oidc.allowed_groups è impostato: il gateway rifiuta l’aggiornamento e la sessione termina
• Altrimenti, un upstream non ha un elenco groups: le richieste dello sviluppatore passano a quell’upstream
• Altrimenti, ogni upstream ha un elenco groups: le richieste dello sviluppatore falliscono con quell’errore

Sezioni facoltative

login_notice

login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

admin

admin:
  # Named static API keys for the admin endpoints, sent as x-api-key.
  # The id appears in the audit log as admin-key:<id> so each key is
  # attributable. Array for rotation: add the new key, roll clients,
  # remove the old.
  write_keys:
    - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
    - { id: ci,        key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }
  read_keys:
    - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
  # IdP groups granted full admin via the normal gateway JWT (no API key).
  admin_groups: [platform-finops]
  blocked_message: request an increase at https://go.example.com/claude-limits
  # Try eng-platform's pooled budget first, then eng-all's, then any other group's.
  pooled_conflict_rule: priority_list
  pooled_priority_order: [eng-platform, eng-all]

Ordine dei budget condivisi

• default_order: prima il limite più alto e, a parità di limite, in ordine crescente di nome del gruppo
• priority_list: i budget dei gruppi in pooled_priority_order, nell’ordine dell’elenco, poi i budget degli altri gruppi per nome del gruppo

enforcement

pricing

• Claude Code v2.1.227 o successivo sul server del gateway. Le versioni precedenti rifiutano la chiave sconosciuta all’avvio.
• Un blocco admin: o, in v2.1.268 o successivo, un blocco managed: con almeno una policy. Il gateway rifiuta di avviarsi con pricing impostato e nessuno dei due blocchi, perché nulla lo leggerebbe.

pricing:
  multiplier: 0.85
  overrides:
    - upstream: bedrock-eu
      model: claude-sonnet-4-6
      input: 3.30
      output: 16.50
      cache_read: 0.33
      cache_write: 4.125

• Una riga sostituisce il prezzo di listino per le richieste che upstream, un upstreams[].name, serve per model. Questo include la tariffa più alta della modalità veloce, quindi le richieste veloci e standard vengono misurate alle stesse quattro tariffe.
• Un ID incorporato come claude-sonnet-4-6, abbinato come models[].id, copre ogni forma datata, forma regionale di Amazon Bedrock o forma di Agent Platform di Google Cloud che il misuratore prezza come quel modello. Qualsiasi altra stringa, come un alias o un ARN del profilo di inferenza, corrisponde all’ID che il client ha inviato o alla stringa inviata upstream, senza distinzione tra maiuscole e minuscole.
• Dove le righe si sovrappongono, il misuratore sceglie la riga più specifica piuttosto che la prima riga: una riga il cui model è la stringa di modello esatta inviata upstream, quindi una riga che corrisponde all’ID esatto che il client ha inviato, quindi una riga che nomina il modello incorporato.
• Un nome upstream sconosciuto fa fallire l’avvio, così come due righe per uno stesso upstream che nominano lo stesso modello, incluse due grafie di un modello incorporato. Il gateway avverte all’avvio di una riga che nessun modello richiedibile può utilizzare.
• Le richieste di ricerca web rimangono al prezzo di listino di $0.01; il moltiplicatore si applica comunque a loro.

Aumenta i prezzi

pricing:
  multiplier: 1.2

Invia le tariffe ai client che hanno effettuato l’accesso

• Cosa aggiunge il gateway: a meno che il blocco cli di una policy non imposti già modelPricing, il gateway aggiunge il multiplier e, per ogni ID modello che un client può richiedere, la riga di override del primo upstream che serve quell’ID. Una tariffa che solo un upstream di failover addebita rimane sul gateway.
• Upstream con un elenco groups: quando uno di questi è il primo upstream che serve un ID di modello, il gateway non aggiunge alcuna riga per quell’ID. Gli sviluppatori vedono quindi la tariffa di Claude Code per quell’ID, ovvero la tariffa standard del modello quando Claude Code riconosce l’ID, moltiplicata per il multiplier.
• Escludi una policy: imposta modelPricing a {} nel blocco cli di quella policy, e i suoi sviluppatori rimangono al prezzo di listino.
• Mantieni le tariffe proprie di una policy: una policy il cui blocco cli imposta modelPricing con il suo multiplier o overrides mantiene quel modelPricing intero, e il gateway non vi aggiunge tariffe proprie.

models

auto_include_builtin_models: true   # false: expose only the list below
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    # description: optional text shown in clients that surface it
    upstream_model:
      anthropic: claude-opus-4-8
      bedrock: us.anthropic.claude-opus-4-8   # or an inference-profile ARN
      foundry: your-opus-deployment-name

managed

managed:
  policies:
    # Specific groups first.
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        permissions: { deny: ["WebFetch", "WebSearch"] }
    # Default catch-all last: matches everyone who authenticated.
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        # Make the Default option in /model resolve inside each policy's
        # list. The eng-contractors policy inherits enforceAvailableModels.
        enforceAvailableModels: true

• Allowlist: availableModels e permissions.allow. L’elenco di una policy specifica sostituisce completamente quello della base.
• Elenchi di negazione e array di hook: questi prendono l’unione di base e policy:
  • permissions.deny e permissions.ask
  • disabledMcpjsonServers e deniedMcpServers
  • blockedMarketplaces e deniedModels
  • Gli array per tipo di evento di hooks
• Chiavi di tipo record: env, modelOverrides e skillOverrides. Per queste si esegue un merge superficiale, quindi un blocco env per ruolo sovrascrive le chiavi che imposta ed eredita il resto dalla base.

• Quando il valore è mancante o vuoto, il gateway rifiuta la richiesta con il messaggio model is required. Questo controllo richiede un gateway che esegue Claude Code v2.1.228 o successivo.
• Quando il valore è presente ma non è una stringa, il gateway rifiuta la richiesta con il messaggio model must be a string. Richiede un gateway che esegue Claude Code v2.1.221 o successivo.

Applicare ogni policy corrispondente

managed:
  policy_mode: layered
  policies:
    - match: { groups: [no-web] }
      cli:
        permissions: { deny: ["WebFetch"] }
    - match: { groups: [opus-users] }
      cli:
        availableModels: [opus, sonnet]
    - match: {}
      cli:
        availableModels: [sonnet]
        enforceAvailableModels: true

• Allowlist, valori singoli e blocchi come sandbox: ciascuno proviene per intero dalla prima policy corrispondente in elenco che lo imposta, quindi gli elenchi availableModels di due gruppi non si sommano.
• Elenchi di negazione e array di hook: questi si sommano su tutte le policy corrispondenti, quindi un utente in due gruppi riceve le regole di negazione di entrambi i gruppi.
• env, modelOverrides e skillOverrides: le voci vengono unite per nome, e la prima policy corrispondente in elenco che imposta un nome ne fornisce il valore.
• Chiavi di desktop: queste vengono unite secondo le regole per il blocco desktop di base.

• Un pattern !: una negazione ! in una regola Read o Edit nell’elenco permissions.deny o permissions.ask di qualsiasi policy, inclusa quella match: {}
• Un limite sugli hook al di fuori del catch-all: disableAllHooks, allowedHttpHookUrls o httpHookAllowedEnvVars in qualsiasi policy diversa da match: {}

Avvia le sessioni su un modello consentito dalla policy

• Un alias come sonnet, o un ID incorporato come claude-sonnet-4-6: le sessioni si avviano su uno di quei modelli, e l’opzione Default in /model si risolve in esso
• Nessun alias né ID incorporato nell’elenco: le sessioni possono continuare ad avviarsi sul modello predefinito incorporato, quindi imposta anche model su uno degli ID elencati nel blocco cli di quella policy

managed:
  policies:
    - match: { groups: [restricted-projects] }
      cli:
        availableModels: [restricted-claude-opus-4-8]
        enforceAvailableModels: true
        model: restricted-claude-opus-4-8
        env:
          ANTHROPIC_DEFAULT_OPUS_MODEL: restricted-claude-opus-4-8   # opus and Default resolve to the ID too

Valori dei matcher che arrestano il gateway all’avvio

• Un elenco groups vuoto
• Una voce vuota in groups o in admin_groups
• Un email_domain vuoto
• Un email_domain che contiene @, spazi bianchi o una virgola. Il gateway rimuove gli spazi dal valore e toglie un @ iniziale prima di questo controllo. Scrivi un solo dominio semplice, come example.com.

• Un email_domain vuoto: il gateway saltava il controllo del dominio, quindi una policy con un email_domain vuoto e nessun elenco groups corrispondeva a ogni utente autenticato
• Un elenco groups vuoto: la policy non corrispondeva a nessuno
• Un email_domain contenente @, spazi bianchi o una virgola: la policy non corrispondeva a nessuno
• Una voce vuota in groups o in admin_groups: la voce corrispondeva a un utente solo quando anche il claim groups dell’IdP di quell’utente conteneva una voce vuota. In admin_groups, quella corrispondenza concedeva l’accesso da amministratore. Se il tuo elenco admin_groups non ha mai contenuto una voce vuota, nessuno ha ottenuto l’accesso da amministratore in questo modo.

Scegliere cli o code

• cli: il terminale, le estensioni VS Code e JetBrains e l’Agent SDK. Con cli, la scheda Code di Claude Desktop riceve le impostazioni derivate, quindi una regola con ambito come Read(./.env) non blocca un utente lì.
• code: gli stessi ambiti, e può essere coperta anche la scheda Code di Claude Desktop.

managed:
  policies:
    - match: {}
      code:
        permissions: { deny: ["Read(./.env)"] }
      desktop: {}

• Per coprire la scheda Code: passa a code, una volta che le macchine degli utenti soddisfano le condizioni in Applicare le impostazioni code nella scheda Code
• Per restare su cli: imposta serve_to_desktop: false accanto a cli in una policy per silenziare l’avviso

Cosa va in cli

managed:
  policies:
    - match: {}
      cli:
        # Model access (also enforced server-side at /v1/messages)
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        enforceAvailableModels: true              # Default resolves inside the list

        # Permission policy
        permissions:
          deny:
            - "WebFetch"
            - "Read(./.env)"
            - "Read(./secrets/**)"
          disableBypassPermissionsMode: disable   # blocks --dangerously-skip-permissions
        allowManagedPermissionRulesOnly: true     # ignore user/project permission rules

        # Environment pushed into the CLI process. DISABLE_UPDATES blocks
        # background and manual updates; DISABLE_AUTOUPDATER stops only
        # background updates.
        env:
          DISABLE_UPDATES: "1"                    # pin versions via your own distribution

        # Org-wide hooks. Hook commands run on developer machines, not the
        # gateway, so the path must exist on every client OS in the policy.
        hooks:
          PostToolUse:
            - matcher: "Edit|Write"
              hooks:
                - { type: command, command: /usr/local/bin/audit-edit.sh }

• hooks
• variabili env che richiedono l’approvazione dello sviluppatore, come le variabili di proxy e di base URL
• impostazioni di esecuzione della shell come apiKeyHelper e statusLine
• le impostazioni dei binari della sandbox sandbox.bwrapPath, sandbox.socatPath e sandbox.ripgrep
• Impostazioni della sandbox che intercettano il traffico, iniettano credenziali o indeboliscono l’isolamento, come sandbox.network.tlsTerminate e le impostazioni della porta del proxy. Finestre di dialogo di approvazione di sicurezza le elenca tutte.

Testa una policy prima del deploy

Finestra di contesto nelle sessioni da terminale

managed:
  policies:
    - match: {}
      cli:
        env:
          CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"

Cache del prompt di un’ora

managed:
  policies:
    - match: {}
      cli:
        promptCacheTtl: 1h
        subagentPromptCacheTtl: 1h

Server MCP in una policy

Overlay di Claude Desktop

Impostazioni che il gateway deriva per Claude Desktop

• L’elenco dei modelli, da availableModels. L’elenco esclude i modelli che la policy blocca con deniedModels o availableModelsMatch: exact. Questo filtro richiede Claude Code v2.1.299 o successiva sul server del gateway. Contesto esteso in Claude Desktop tratta l’opzione di contesto da 1M di ciascun modello
• Gli strumenti disabilitati, dalle voci permissions.deny con il solo nome dello strumento. Se imposti disabledBuiltinTools nel blocco desktop della policy, il gateway serve l’unione del tuo valore e dell’elenco derivato, quindi puoi disabilitare più strumenti in questo modo ma non puoi riabilitarne uno che hai disabilitato tramite permissions.deny
• L’allowlist in uscita, da sandbox.network.allowedDomains. Se imposti coworkEgressAllowedHosts nel blocco desktop della policy, il gateway usa quel valore al posto dell’elenco derivato. Se l’allowlist servita dal gateway include * e il gateway non serve anche allowedWorkspaceFolders di Claude Desktop, Claude Desktop non attiva la sandbox di Bash nella scheda Code
• Un endpoint OTLP che punta al gateway stesso, e gli attributi di identità dell’utente che ha effettuato l’accesso. Il gateway inoltra le esportazioni che riceve su quell’endpoint alle tue destinazioni forward_to. Include l’endpoint e gli attributi quando imposti sia telemetry.forward_to che listen.public_url. Claude Desktop esporta ogni segnale con un’unica codifica: http/protobuf, oppure http/json quando imposti OTEL_EXPORTER_OTLP_PROTOCOL o una delle sue varianti per segnale a http/json nell’env della policy. Prima di Claude Code v2.1.261 sul server del gateway, la risposta impostava comunque http/json, quindi un collettore che accetta solo protobuf rifiutava le esportazioni di Claude Desktop

Applicare le impostazioni code nella scheda Code

• La policy ha anche una chiave desktop, e un desktop: {} vuoto conta
• Claude Desktop è alla versione 2.9939.2 o successiva
• Le impostazioni gestite di Claude Code sulla macchina nominano questo gateway
• Quella macchina raggiunge il gateway tramite HTTPS su una rete privata

• Tramite HTTPS, se Claude Desktop include Claude Code v2.1.296 o successiva: la scheda Code non si avvia, e la risposta al prompt dell’utente spiega il motivo
• Tramite HTTPS, se Claude Desktop include una versione precedente: la scheda Code si avvia senza le tue impostazioni code, e nulla nella sessione lo segnala
• Tramite HTTP semplice: la scheda Code si avvia senza le tue impostazioni code, qualunque sia la versione inclusa in Claude Desktop

Imposta direttamente le impostazioni di Claude Desktop

managed:
  policies:
    - match: { groups: [eng-contractors] }
      cli:
        availableModels: [claude-sonnet-4-6]
        enforceAvailableModels: true
      desktop:
        isLocalDevMcpEnabled: false
        disableAutoUpdates: true
        banner: { text: "Contractor build: internal use only" }

Cosa rifiuta il gateway all’avvio

• Una chiave riconosciuta il cui valore Claude Desktop rifiuterebbe o scarterebbe silenziosamente, come un valore vuoto.
• Una chiave che il gateway calcola da solo: la connessione di inferenza, l’elenco dei modelli e l’inoltro OTLP. Configurali tramite upstreams, models e il forward_to della sezione telemetry.
• Un alias legacy di una chiave attuale. Nell’errore di avvio, il gateway nomina la chiave canonica da scrivere.
• Da v2.1.300, qualsiasi chiave il cui nome inizia con selfHosted, come le chiavi per un host di sessioni self-hosted. Rimuovi queste chiavi prima di aggiornare il gateway a v2.1.300 o successiva.

Chiavi che il gateway non conosce

• Una nuova scelta nell’elenco fisso di valori di una chiave nota.
• Un probabile errore di battitura di una chiave che puoi impostare in un blocco desktop, come disable_auto_updates per disableAutoUpdates. L’errore suggerisce un nome.

Chiavi che richiedono una versione più recente del gateway o di Claude Desktop

Come una policy per ruolo eredita il blocco desktop della base

• disabledBuiltinTools: il gateway usa l’unione dell’elenco della base e dell’elenco della policy
• builtinToolPolicy: se imposti uno strumento a un valore diverso da allow nella base, il gateway mantiene quel valore anche se imposti allow per lo stesso strumento in una policy per ruolo

Quando una modifica della policy raggiunge Claude Desktop

• Chiuso: Claude Desktop recupera la risposta di bootstrap all’avvio, quindi la modifica si applica dal prossimo avvio
• Aperto: Claude Desktop verifica la presenza di una risposta modificata ogni 10 minuti per impostazione predefinita e applica alcune impostazioni senza riavvio. Per le altre, come skillCreationEnabled, l’utente vede una scheda Relaunch Claude Desktop nella barra laterale e mantiene la configurazione precedente finché non riavvia l’app. Dopo 24 ore per impostazione predefinita, Claude Desktop mostra una finestra di dialogo di riavvio e si riavvia da solo dopo 2 minuti di inattività

Contesto esteso in Claude Desktop

• Un upstream che può servire la voce la mappa a un modello senza supporto 1M, incluso un upstream che il gateway raggiunge solo in caso di failover
• Né il suo id né alcuno dei suoi valori upstream_model nomina un modello Claude, come un alias personalizzato instradato verso l’ARN di un profilo di inferenza dell’applicazione

• Avvia gli utenti sull’opzione 1M: imposta modelPrefer1mContext: true nel blocco desktop della policy. Gli utenti che non hanno ancora scelto un modello iniziano con l’opzione 1M quando il primo modello elencato ne ha una. Gli utenti che hanno già scelto un modello mantengono la loro scelta.
• Offri l’opzione manualmente: fallo se il server del gateway esegue una versione precedente a v2.1.284, o se una voce non nomina alcun modello Claude. Elenca il modello due volte in models, una volta con il suo ID semplice e una volta con [1m] aggiunto, entrambe con la stessa mappa upstream_model. Claude Desktop mostra la coppia come un unico modello con un’opzione 1M. Il gateway serve una voce [1m] senza controllarla, quindi aggiungine una solo per un modello che i tuoi upstream servono a 1M.

models:
  - id: corp-sonnet
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod
  - id: corp-sonnet[1m]
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-5-prod

managed:
  policies:
    - match: {}
      desktop:
        modelPrefer1mContext: true

Rimuovi l’opzione 1M

Precedenza rispetto ad altre fonti gestite

telemetry

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      # Per-signal opt-in. Default: metrics only.
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

• http://localhost:<port> supera la convalida della configurazione, ma la protezione SSRF blocca ogni esportazione con ECONNREFUSED_SSRF a meno che non imposti CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 nell’ambiente del gateway
• http://127.0.0.1:<port> o http://[::1]:<port> fa fallire l’avvio a meno che quella variabile non sia impostata

• CLAUDE_CODE_ENABLE_TELEMETRY=1
• OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER e OTEL_TRACES_EXPORTER, ognuna impostata a otlp se almeno una destinazione forward_to abilita quel segnale e a none altrimenti
• OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
• OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

• Variabili impostate localmente: Claude Code applica le variabili inviate al livello gestito, quindi ognuna sovrascrive il valore che uno sviluppatore imposta localmente per essa.
• Endpoint configurati localmente: con l’esportazione OTLP/HTTP abilitata, la CLI ignora qualsiasi endpoint configurato localmente, indipendentemente dal fatto che il gateway abbia inviato le variabili di telemetria. Le sue esportazioni vanno al gateway a meno che una policy non nomini il tuo collettore come endpoint.

Inviare metriche cumulative

• Sessioni del terminale: nel blocco env sotto la chiave cli o code di una policy
• Sessioni Cowork che vengono eseguite sulla macchina dell’utente: nel blocco env delle impostazioni gestite lato client su quella macchina
• Sessioni della scheda Code con una policy code: nel blocco env della policy, una volta soddisfatte le condizioni per l’applicazione delle impostazioni code
• Sessioni della scheda Code con una policy cli: nel blocco env delle impostazioni gestite lato client sulla macchina che esegue la sessione. Tramite SSH, è l’host remoto.

Aggiungi le tue etichette

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
  resource_attributes:
    service.namespace: claude
    deployment.environment.name: prod

• I nomi usano solo lettere, cifre, ., _ e -
• I nomi non sono riservati. Confrontati senza distinzione tra maiuscole e minuscole, i nomi riservati sono tutti quelli che iniziano con user., enduser. o identity., più service.name, service.version, claude.deployment_mode, host.arch, os.type, os.version e wsl.version
• I valori sono ASCII stampabile non vuoto, senza spazi e senza nessuno tra , ; = \ " %
• I valori sono lunghi al massimo 255 caratteri secondo il conteggio del gateway dopo la codifica in percentuale, quindi /, : e @ contano ciascuno come tre
• I valori sono testo, quindi metti tra virgolette un numero, true o false

Modifiche ai gruppi durante una sessione aperta

processors:
  resource/drop-user-groups:
    attributes:
      - key: user.groups
        action: delete

Esporta direttamente al tuo collettore

• L’endpoint proviene dal gateway stesso. Se imposti la stessa variabile in un profilo MDM o in un managed-settings.json locale, le esportazioni rimangono sull’inoltro.
• L’URL usa https://, oppure http:// verso un indirizzo loopback
• L’URL si risolve in un percorso che termina con /v1/<signal>, senza query né frammento. Claude Code costruisce da solo quel percorso a partire dalla variabile generica. Usa una variabile per segnale come OTEL_EXPORTER_OTLP_METRICS_ENDPOINT così come è scritta, quindi lì includi il percorso completo.
• L’URL non è l’host del gateway stesso. Un endpoint indirizzato al gateway mantiene il percorso di inoltro e il suo token di sessione.
• Né tu né lo sviluppatore avete configurato otelHeadersHelper in alcuna fonte di impostazioni. Con un helper configurato, ogni segnale rimane sull’inoltro.

• Se il gateway invia già le variabili di telemetria, queste coprono l’abilitazione, i selettori e il protocollo, e il tuo endpoint esplicito sovrascrive il valore <public_url> inviato. Imposta tu stesso un selettore OTEL_*_EXPORTER a otlp solo per un segnale che nessuna destinazione forward_to abilita.
• Se non lo fa, imposta anche CLAUDE_CODE_ENABLE_TELEMETRY=1, i selettori OTEL_*_EXPORTER e OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

Quando una destinazione fallisce

Ottimizzazione HTTP

• All’avvio: un avviso nel log operativo consiglia di consentire solo gli intervalli privati 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10, 127.0.0.0/8, ::1/128 e fc00::/7, più qualsiasi altro intervallo interno da cui si connettono i tuoi sviluppatori. Se associ il gateway a un indirizzo loopback e non imposti né trusted_proxies né public_url, come nello sviluppo locale, l’avviso non appare.
• In fase di esecuzione: la prima volta che una richiesta arriva da un indirizzo al di fuori di quegli intervalli privati, il gateway registra un avviso ed emette un evento di audit access.public_client contenente l’IP del client. Entrambi si attivano una volta per processo. Gli indirizzi link-local, 169.254.0.0/16 e fe80::/10, non contano come pubblici. Il gateway risponde a /healthz e /readyz prima che questo controllo venga eseguito, quindi i probe di salute da intervalli pubblici non lo attivano.

load_test_mode

load_test_mode:
  enabled: true
  reply_tokens: 750     # roughly how many tokens of text each canned reply carries
  reply_seconds: 9.5    # how long a streamed reply takes

Esempio completo

# Run with:
#   claude gateway --config gateway.yaml
#
# Operational log verbosity is controlled by the CLAUDE_GATEWAY_LOG_LEVEL
# environment variable (debug | info | warn | error; default info). debug
# also logs the claim names in each id_token, for groups_claim diagnosis.
# It does not affect audit events, which are always emitted.
# Set CLAUDE_GATEWAY_LOG_FORMAT=json to write operational log lines as JSON
# objects with severity, time, and message.

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  # Omit the tls block when running behind a TLS-terminating ingress.
  # tls:
  #   cert: /certs/gateway.crt
  #   key: /certs/gateway.key
  # trusted_proxies:
  #   - 10.0.0.0/8

oidc:
  issuer: https://example.okta.com
  client_id: 0oa1example2
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains:
    - example.com
  # Required when the issuer is the Okta org server, whose id_tokens
  # can omit email and groups; the gateway fills them from /userinfo.
  userinfo_fallback: true
  # allowed_groups: [claude-code-users]
  # Okta emits groups only when the `groups` scope is requested and the
  # app's groups claim filter allows them. The contractors policy below
  # matches on groups, so the scope is requested here.
  scopes: [openid, profile, email, offline_access, groups]
  # extra_auth_params: { access_type: offline, prompt: consent }  # Google
  # groups_claim: groups          # Entra app roles: use `roles`
  # email_claim: email

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}   # openssl rand -base64 32
  # ttl_hours: 1

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}
  # max_connections: 5
  # connect_timeout_seconds: 5
  # readiness_grace_seconds: 300   # keep passing the readiness check through a database failover

# Notice shown at sign-in. Anyone who can reach the gateway can read it.
# login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

# Enables /v1/organizations/spend_limits (mirrors the Anthropic Admin API)
# and per-developer spend enforcement on /v1/messages. Omit to disable.
# Caps themselves are set via the admin API, not here.
# admin:
#   write_keys:
#     - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }
#   read_keys:
#     - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }
#   admin_groups: [platform-finops]
#   blocked_message: request an increase at https://go.example.com/claude-limits
#   # audit_retention_days: 365
#   # spend_retention_months: 13
#   # identity_retention_days: 90
#   # group_limit_mode: min
#   # pooled_conflict_rule: priority_list
#   # pooled_priority_order: [eng-platform, eng-all]

# enforcement:
#   fail_closed_on_error: false

# Load test this deployment without calling a model provider. Never on a
# gateway that developers use: every request gets a canned reply.
# load_test_mode:
#   enabled: true
#   # reply_tokens: 750
#   # reply_seconds: 9.5

# Meter at contracted rates instead of USD list price. Requires admin: or a
# managed: policy. With managed:, the same rates also go to signed-in clients.
# Rates below are placeholders, not real contract prices.
# pricing:
#   multiplier: 0.85
#   overrides:
#     - { upstream: anthropic, model: claude-sonnet-4-6, input: 3.30, output: 16.50, cache_read: 0.33, cache_write: 4.125 }

upstreams:
  - provider: anthropic
    auth:
      api_key: ${ANTHROPIC_API_KEY}

  # - provider: bedrock
  #   region: us-east-1
  #   auth: {}

  # - provider: mantle
  #   region: us-east-1
  #   models: [claude-opus-4-8, claude-opus-4-7, claude-haiku-4-5]
  #   auth: {}

  # - provider: anthropicAws
  #   region: us-east-1
  #   workspace_id: wrkspc_...
  #   auth:
  #     api_key: ${ANTHROPIC_AWS_API_KEY}

  # - provider: vertex
  #   region: us-east5
  #   project_id: example-prod
  #   auth: {}

  # - provider: foundry
  #   resource: example-foundry
  #   auth: { use_azure_ad: true }

auto_include_builtin_models: true
models:
  - id: claude-opus-4-8
    label: Claude Opus 4.8
    upstream_model:
      anthropic: claude-opus-4-8
      # bedrock: us.anthropic.claude-opus-4-8
      # mantle: anthropic.claude-opus-4-8
      # anthropicAws: claude-opus-4-8
      # vertex: claude-opus-4-8
      # foundry: <your-opus-deployment-name>
  - id: claude-sonnet-4-6
    label: Claude Sonnet 4.6
    upstream_model:
      anthropic: claude-sonnet-4-6
  - id: claude-haiku-4-5
    label: Claude Haiku 4.5
    upstream_model:
      anthropic: claude-haiku-4-5

managed:
  policies:
    - match: { groups: [contractors] }
      cli:
        availableModels: [claude-haiku-4-5]
        # allow auto-approves these tools; it does not block the rest.
        # Add deny rules to restrict tools.
        permissions: { allow: [Read, Grep] }
    - match: {}
      cli:
        availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]
        # Constrain the Default picker option to each policy's availableModels
        # instead of the built-in default, so no role gets a 400 on Default.
        # The contractors policy inherits this key.
        enforceAvailableModels: true
        permissions:
          allow: [Read, Grep, Edit]
          deny: ["WebFetch"]
        env: { HTTP_PROXY: http://proxy.example.com:8080 }

telemetry:
  forward_to:
    - url: https://otel.internal.example.com:4318
      headers:
        Authorization: Bearer ${OTEL_TOKEN}

Impostazioni gestite lato client

{
  "forceLoginMethod": "gateway",
  "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com",
  "parentSettingsBehavior": "merge"
}

Correlati

• Panoramica del gateway delle app Claude: guida rapida e connessione dello sviluppatore
• Guida alla distribuzione: configurazione IdP, immagine del contenitore, Kubernetes e Cloud Run e operazioni
• Limiti di spesa: cap per sviluppatore e API Admin