Documentation 2026-07-28 23:57 UTC to 2026-07-29 19:02 UTC

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Gateway de aplicativos Claude para Amazon Bedrock, Claude Platform on AWS, Google Cloud e Microsoft Foundry

6 

7> Execute Claude Code através do Amazon Bedrock, Claude Platform on AWS, Google Cloud ou Microsoft Foundry atrás de um gateway auto-hospedado com sign-in SSO, acesso a modelos por grupo e telemetria OTLP.

8 

9<Note>

10 O gateway de aplicativos Claude foi projetado para organizações que devem — ou preferem — rotear inferência através de seu próprio provedor de nuvem, por exemplo para atender aos requisitos de [residência de dados](/docs/pt/claude-apps-gateway-deploy#compliance-posture). Se você não tem esse requisito e deseja acesso a outros recursos como provisionamento SCIM ou Claude Code na web e mobile, Claude Enterprise pode ser uma opção melhor. Consulte a página de [disponibilidade de recursos](/docs/pt/feature-availability) para uma comparação completa de todos os métodos de implantação.

11</Note>

12 

13Claude apps gateway é um serviço auto-hospedado que fica entre os clientes Claude Code dos seus desenvolvedores e seu provedor de modelo. Os desenvolvedores fazem login com seu provedor de identidade corporativo (IdP) em vez de manter chaves de API ou credenciais de nuvem. O gateway mantém a credencial upstream, aplica acesso a modelos e [configurações gerenciadas](/docs/pt/permissions#managed-settings) por grupo IdP, e retransmite telemetria de uso para sua própria pilha de observabilidade.

14 

15Está incluído no binário `claude`, então o mesmo executável que executa Claude Code em um laptop executa o servidor gateway com `claude gateway --config gateway.yaml`.

16 

17Esta página cobre:

18 

19* [Por que Claude apps gateway](#why-claude-apps-gateway), o que adiciona em relação a executar o seu próprio, e quando algo mais se encaixa melhor

20* Um [guia de início rápido](#quickstart) com [pré-requisitos](#prerequisites) que leva um gateway de zero a um desenvolvedor conectado

21* [Conectando desenvolvedores](#connect-developers), incluindo definir a URL do gateway através de configurações gerenciadas

22* [Disponibilidade e limitações](#availability-and-limitations) cobrindo quais recursos do Claude Code funcionam através do gateway e o que o servidor suporta

23 

24As páginas complementares vão mais fundo. A [referência de configuração](/docs/pt/claude-apps-gateway-config) cobre todas as opções no arquivo YAML que o guia de início rápido escreve, e o [guia de implantação](/docs/pt/claude-apps-gateway-deploy) cobre configuração por IdP, implantação em Kubernetes e Cloud Run, e operações.

25 

26<h2 id="why-claude-apps-gateway">

27 Por que Claude apps gateway

28</h2>

29 

30A [visão geral do gateway](/docs/pt/gateways) cobre o que um gateway faz e por que você executaria um. Claude apps gateway é o próprio gateway da Anthropic, integrado ao binário `claude` e testado junto com cada lançamento do Claude Code, então encaminha os cabeçalhos e campos de solicitação que Claude Code envia sem operadores mantendo uma lista de permissões separada. Uma vez implantado, ele oferece:

31 

32* **Credenciais**: a chave de API upstream ou credencial de nuvem vive apenas em sua infraestrutura. Os desenvolvedores se autenticam com SSO corporativo e recebem tokens de portador de curta duração, então o offboarding acontece em seu IdP. Desprovisione um usuário e seu acesso ao gateway expira dentro do tempo de vida da sessão, uma hora por padrão.

33* **Controle de acesso**: seus grupos IdP mapeiam para listas de permissões de modelos e políticas de [configurações gerenciadas](/docs/pt/permissions#managed-settings). O gateway aplica acesso a modelos no lado do servidor, rejeitando solicitações para modelos não concedidos, e seleciona a política de configurações gerenciadas de cada grupo, que a CLI aplica no [nível de configurações gerenciadas](/docs/pt/settings#settings-precedence). Diferentes equipes obtêm diferentes modelos, ferramentas e permissões, e um desenvolvedor não pode substituir o que sua política bloqueia.

34* **Entrega de configurações**: o gateway entrega configurações gerenciadas para clientes conectados, assumindo o lugar das [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) do console administrativo claude.ai.

35* **Telemetria**: cada destino configurado, como Datadog, Splunk ou ClickHouse, recebe [métricas do OpenTelemetry Protocol (OTLP)](/docs/pt/monitoring-usage) com contagens de tokens, modelo, identidade do usuário e latência por padrão, com logs e rastreamentos como opt-ins por destino.

36* **Roteamento upstream**: os clientes falam a API de Mensagens Anthropic para o gateway, e o gateway traduz para cada upstream, seja Amazon Bedrock, [Claude Platform on AWS](/docs/pt/claude-platform-on-aws), Agent Platform do Google Cloud, Microsoft Foundry ou a API Anthropic, com failover entre eles. Você pode alterar regiões, provedores ou ordem de failover sem que os desenvolvedores notem ou reconfiguram.

37 

38<Frame>

39 <img src="https://mintcdn.com/claude-code/st9_ZQOFsZa3cKFl/images/claude-gateway-architecture.svg?fit=max&auto=format&n=st9_ZQOFsZa3cKFl&q=85&s=560770d8f49bbd6f1ca7090ed1f13c03" alt="Diagrama mostrando clientes Claude Code conectando via HTTPS com tokens de portador a um gateway de aplicativos Claude auto-hospedado dentro de sua infraestrutura, que faz login dos usuários contra seu IdP, armazena estado de autenticação em PostgreSQL, retransmite telemetria para seu coletor OTLP, e encaminha inferência para Amazon Bedrock, Claude Platform on AWS, Google Cloud, Microsoft Foundry ou a API Anthropic" width="760" height="320" data-path="images/claude-gateway-architecture.svg" />

40</Frame>

41 

42<Note>

43 O plano de dados do próprio gateway não envia nada para a infraestrutura Anthropic a menos que a API Anthropic seja um upstream configurado. Você controla para onde a telemetria, logs de auditoria, configurações gerenciadas e a identidade IdP dos seus desenvolvedores vão, e o gateway não envia nenhum deles para Anthropic. Para o tráfego restante que o processo CLI pode enviar e como fechá-lo, consulte [Postura de conformidade](/docs/pt/claude-apps-gateway-deploy#compliance-posture).

44</Note>

45 

46Para quais recursos do Claude Code funcionam através do gateway e o que o próprio servidor suporta, consulte [Disponibilidade e limitações](#availability-and-limitations) abaixo. Para decisões como custo, bypass, executar múltiplos gateways e plataformas sem servidor, consulte o [guia de implantação](/docs/pt/claude-apps-gateway-deploy#deployment).

47 

48<h3 id="other-gateway-implementations">

49 Outras implementações de gateway

50</h3>

51 

52Se você já executa um gateway LLM ou gateway de API que atende às suas necessidades, continue usando-o; [Outros gateways LLM](/docs/pt/llm-gateway) cobre a configuração do Claude Code contra ele.

53 

54A [referência do protocolo de gateway](/docs/pt/llm-gateway-protocol) documenta o contrato que Claude Code espera de qualquer gateway: os endpoints que chama, os cabeçalhos e campos de corpo para encaminhar, e o que para de funcionar quando são removidos. Um gateway de aplicativos Claude em execução serve um superconjunto desse contrato em `GET /protocol`, adicionando os endpoints específicos do gateway de aplicativos Claude para sign-in SSO, entrega de configurações gerenciadas e telemetria. Busque-o com `curl https://claude-gateway.internal.example.com/protocol` de qualquer gateway implantado, como o que o [guia de início rápido](#quickstart) abaixo produz.

55 

56Mudanças significativas no protocolo são anunciadas com antecedência, mas compatibilidade retroativa indefinida não é garantida.

57 

58<h2 id="quickstart">

59 Guia de início rápido

60</h2>

61 

62Este guia de início rápido percorre o caminho mínimo: registre um cliente OAuth em seu IdP, escreva um `gateway.yaml`, execute o gateway junto com Postgres usando Docker Compose, e verifique o sign-in de ponta a ponta. Usa um upstream Amazon Bedrock; Claude Platform on AWS, Agent Platform do Google Cloud, Microsoft Foundry e a API Anthropic são igualmente suportados trocando o bloco `upstreams` conforme mostrado na [referência de configuração](/docs/pt/claude-apps-gateway-config#upstreams). No final você tem um gateway que um desenvolvedor pode fazer `/login`.

63 

64<Note>

65 **Implante em sua rede privada.** Claude Code só se conecta a um gateway cujo endereço é privado. Esta é uma proteção de segurança, porque um gateway confiável pode enviar configurações que executam comandos em máquinas de desenvolvedores. Coloque o gateway atrás de um balanceador de carga interno ou VPN e dê a ele um nome de host que resolve apenas para IPs privados.

66 

67 Os endpoints de gateway público operados pela Anthropic são a exceção: `/login` os aceita via `https://`. Estes são um pequeno conjunto fixo de gateways que a própria Anthropic opera; não são uma opção de implantação que você pode selecionar ou configurar. A lista é compilada no Claude Code, portanto nenhuma configuração pode adicionar um nome de host a ela e nenhum gateway que você hospeda se qualifica para a isenção. {/* min-version: 2.1.206 */}Antes da v2.1.206, `/login` rejeitava esses endpoints como qualquer outro endereço público.

68</Note>

69 

70<h3 id="prerequisites">

71 Pré-requisitos

72</h3>

73 

74Tenha estes em vigor antes de começar:

75 

76| Você precisa | Detalhes |

77| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

78| Claude Code v2.1.195 ou posterior | O subcomando `claude gateway` e o fluxo de sign-in do gateway são enviados na v2.1.195. Compilações públicas anteriores não as incluem. Tanto a máquina executando o servidor gateway quanto a máquina de cada desenvolvedor devem estar na v2.1.195 ou posterior; execute `claude update` para obter a versão mais recente. {/* min-version: 2.1.198 */}O [upstream Claude Platform on AWS](/docs/pt/claude-apps-gateway-config#claude-platform-on-aws) requer Claude Code v2.1.198 ou posterior no servidor gateway. |

79| Provedor de identidade OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak ou Dex, ou qualquer outro IdP compatível com OIDC, como PingFederate. O gateway executa descoberta OIDC padrão e o fluxo de código de autorização contra ele. SAML e LDAP não são suportados. |

80| PostgreSQL 14 ou posterior | Faz backup do fluxo de sign-in do dispositivo, onde o callback do navegador escreve e a CLI de polling lê, além de contadores de limite de taxa. Qualquer Postgres gerenciado funciona, incluindo o menor nível. Sem limites de gastos configurados, o gateway armazena alguns KB de estado de autenticação de curta duração; com [limites de gastos](/docs/pt/claude-apps-gateway-spend-limits), também mantém tabelas de gastos, auditoria e identidade duráveis que devem ser feitas backup. TLS via `?sslmode=require` é recomendado. |

81| Upstream de modelo | Credenciais do Amazon Bedrock, credenciais do Claude Platform on AWS, credenciais do Google Cloud, um recurso Microsoft Foundry ou uma chave de API Anthropic. Múltiplos upstreams são suportados com failover. |

82| HTTPS | O gateway deve ser acessível via `https://` de laptops de desenvolvedores e de qualquer navegador usado para sign-in; o gateway serve a página de verificação do dispositivo no mesmo listener. Forneça um certificado TLS via `listen.tls` ou execute atrás de um ingress que termina TLS e defina `listen.public_url`. Uma origem `http://` simples é aceita apenas em loopback, para desenvolvimento local. |

83| Endereço de rede privada | Em `/login`, Claude Code requer que o nome de host ou endereço IP do gateway resolva apenas para endereços privados: RFC 1918, CGNAT `100.64.0.0/10`, ULA IPv6 `fc00::/7` ou loopback para desenvolvimento local. A verificação é executada em cada IP resolvido, então se qualquer endereço para o qual o nome resolve for público, `/login` rejeita a URL. Se máquinas de desenvolvedores rotear HTTPS através de um proxy corporativo, o sign-in também requer que o host proxy resolva para endereços privados; se não resolver, adicione o host do gateway a `NO_PROXY` para que a CLI se conecte diretamente. {/* min-version: 2.1.206 */}Os endpoints de gateway público operados pela Anthropic estão isentos das verificações de endereço privado e proxy: `/login` os aceita via `https://` por correspondência exata de nome de host, portanto o requisito de rede privada se aplica apenas a um gateway que você hospeda. Antes da v2.1.206, `/login` rejeitava um endpoint operado pela Anthropic como qualquer outro endereço público. |

84| Runtime Linux | O servidor gateway é executado apenas no binário Linux nativo. macOS funciona para desenvolvimento local. Windows não é suportado como plataforma de servidor. |

85 

86O servidor gateway requer o binário `claude` nativo; baixe uma versão fixada conforme descrito em [Instalar Claude Code](/docs/pt/setup). O servidor usa recursos de runtime que não estão disponíveis quando Claude Code é executado sob Node. Se você vir `requires the native binary` na inicialização, mude para um dos métodos de instalação autônomos.

87 

88<h3 id="steps">

89 Etapas

90</h3>

91 

92<Steps>

93 <Step title="Registre um cliente OAuth em seu IdP">

94 Decida o nome de host do gateway primeiro, porque o URI de redirecionamento deve corresponder a ele. Crie um novo aplicativo web OIDC e defina o URI de redirecionamento para `https://claude-gateway.<seu-domínio>/oauth/callback`, onde o host é o mesmo valor que você define como [`listen.public_url`](/docs/pt/claude-apps-gateway-config#listen) na etapa 3. Anote o `client_id` e `client_secret`. As instruções por IdP estão em [Configuração do provedor de identidade](/docs/pt/claude-apps-gateway-deploy#identity-provider-setup).

95 </Step>

96 

97 <Step title="Provisione um banco de dados PostgreSQL">

98 Qualquer Postgres 14 ou posterior funciona, incluindo o menor nível gerenciado. O gateway executa suas próprias migrações de esquema na inicialização, então o usuário do banco de dados precisa de permissão `CREATE TABLE`. Se sua política de segurança proíbe DDL de funções de aplicação, pré-crie o esquema em vez disso; consulte [`store`](/docs/pt/claude-apps-gateway-config#store).

99 </Step>

100 

101 <Step title="Escreva gateway.yaml">

102 Os segredos são lidos via expansão `${ENV_VAR}` para que o arquivo em si possa viver no controle de versão. Use um nome de host `public_url` que resolva para um IP privado em sua rede, porque `/login` rejeita endereços públicos. A configuração mínima tem cinco seções, e todos os outros campos têm um padrão:

103 

104 ```yaml gateway.yaml theme={null}

105 listen:

106 host: 0.0.0.0

107 port: 8080

108 # Obrigatório atrás de qualquer proxy que termina TLS. Usado para o IdP

109 # redirect_uri e o documento de descoberta.

110 public_url: https://claude-gateway.internal.example.com

111 

112 oidc:

113 issuer: https://login.example.com # deve servir /.well-known/openid-configuration

114 client_id: 0oa1example2

115 client_secret: ${OIDC_CLIENT_SECRET}

116 allowed_email_domains: [example.com] # rejeitar id_tokens fora de sua organização

117 userinfo_fallback: true # para IdPs cujo id_token omite email/grupos; inofensivo caso contrário

118 

119 session:

120 jwt_secret: ${GATEWAY_JWT_SECRET} # openssl rand -base64 32

121 ttl_hours: 1 # também limita a latência de revogação no desprovisionamento de IdP

122 

123 store:

124 postgres_url: ${GATEWAY_POSTGRES_URL} # adicione ?sslmode=require para Postgres gerenciado

125 

126 upstreams:

127 - provider: bedrock

128 region: us-east-1

129 auth: {} # vazio: cadeia de credencial padrão da AWS

130 # (IRSA, função de tarefa EC2/ECS, variáveis de ambiente, ~/.aws)

131 

132 # Os modelos são traduzidos por upstream automaticamente. O catálogo integrado

133 # mapeia claude-opus-4-8 para us.anthropic.claude-opus-4-8 e assim por diante para cada

134 # modelo Claude suportado pelo Bedrock. Defina como false e adicione uma lista `models:` para

135 # expor apenas modelos específicos.

136 auto_include_builtin_models: true

137 ```

138 

139 Esta configuração é suficiente para um loop de sign-in funcionando com o catálogo de modelos Bedrock padrão. Uma vez em execução, adicione RBAC por grupo e configurações gerenciadas via [`managed.policies`](/docs/pt/claude-apps-gateway-config#managed), fan-out de telemetria via [`telemetry`](/docs/pt/claude-apps-gateway-config#telemetry), e failover multi-upstream, ARNs de throughput provisionado ou regiões não-US via [`models`](/docs/pt/claude-apps-gateway-config#models).

140 

141 <Note>

142 O upstream Bedrock precisa de um principal AWS com `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` nos ARNs `inference-profile/us.anthropic.*` e nos ARNs `foundation-model/anthropic.*` subjacentes, e acesso a modelos habilitado no console Bedrock para os modelos Claude que você deseja. Forneça a credencial com IRSA no EKS, uma função de tarefa ECS ou um perfil de instância EC2 em vez de chaves estáticas. A [referência `upstreams`](/docs/pt/claude-apps-gateway-config#upstreams) tem os detalhes completos do IAM, a matriz de credencial entre nuvens e os blocos `auth` para os outros provedores.

143 </Note>

144 </Step>

145 

146 <Step title="Execute-o">

147 Construa uma imagem de contêiner em torno do binário `claude` que atenda aos [requisitos de imagem](/docs/pt/claude-apps-gateway-deploy#container-image), então execute-a junto com Postgres:

148 

149 ```yaml docker-compose.yaml theme={null}

150 services:

151 gateway:

152 image: <seu-registro>/claude-gateway:<versão>

153 ports: ["8080:8080"]

154 volumes: ["./gateway.yaml:/etc/claude/gateway.yaml:ro"]

155 environment:

156 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}

157 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}

158 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway

159 # Credenciais AWS: em produção, omita estas e use uma função de instância.

160 # Para teste local do Compose, passe as suas próprias:

161 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}

162 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}

163 AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN}

164 depends_on:

165 postgres:

166 condition: service_healthy

167 postgres:

168 image: postgres:16-alpine

169 environment: { POSTGRES_USER: gw, POSTGRES_PASSWORD: pw, POSTGRES_DB: gateway }

170 healthcheck:

171 test: ["CMD-SHELL", "pg_isready -U gw"]

172 interval: 5s

173 volumes: ["pgdata:/var/lib/postgresql/data"]

174 volumes: { pgdata: }

175 ```

176 

177 O gateway é um único binário Linux que lê a configuração, executa descoberta OIDC contra seu IdP, aplica suas migrações de esquema Postgres, constrói clientes upstream e começa a escutar. A inicialização é fail-closed para a configuração, a conexão Postgres com um tempo limite de 5 segundos, descoberta OIDC e construção de cliente upstream. Se qualquer um desses for inacessível ou mal configurado, o gateway sai com um erro em vez de servir tráfego em um estado degradado.

178 

179 Uma inicialização bem-sucedida não valida o caminho de inferência, porque credenciais de instância Bedrock e Agent Platform resolvem na primeira solicitação, não na inicialização.

180 

181 Observe stderr para a sequência de inicialização. As linhas de log usam o formato `[gateway] <timestamp> <level> <message>`, eventos de auditoria são JSON de linha única com um campo `evt`, e um banner de inicialização, omitido abaixo, é impresso entre as linhas de migração e escuta. Você deve ver, em ordem:

182 

183 ```text theme={null}

184 {"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}

185 [gateway] 2026-06-10T17:03:21.408Z info migration 1 applied

186 [gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

187 ```

188 

189 Se a inicialização sair antes da linha `claude gateway listening on`, a última linha de stderr nomeia o problema:

190 

191 * um Postgres inacessível

192 * uma função Postgres sem permissão DDL

193 * um documento de descoberta OIDC inacessível ou inválido

194 * uma violação de esquema de configuração com o caminho de campo ofensivo

195 

196 Corrija-o e reinicie.

197 

198 Se você já tem um ingress que termina TLS, pule o Compose e execute o binário diretamente com `claude gateway --config gateway.yaml`. Defina `public_url` para a origem do ingress e vincule `listen` a um endereço loopback ou interno do cluster.

199 </Step>

200 

201 <Step title="Verifique a superfície de autenticação">

202 Três verificações confirmam que o gateway pode autenticar um usuário real antes de entregá-lo a um desenvolvedor.

203 

204 Os exemplos usam a URL pública do gateway; para a configuração local do Compose sem um ingress, substitua `http://localhost:8080` nas duas primeiras verificações. A terceira verificação abre `verification_uri_complete`, que é construída a partir de `public_url`, então para Compose local defina `public_url: http://localhost:8080` em `gateway.yaml` e adicione `http://localhost:8080/oauth/callback` como um segundo URI de redirecionamento no cliente OAuth da etapa 1, porque o gateway constrói o `redirect_uri` do IdP a partir de `public_url`. O link de verificação então abre em seu navegador local.

205 

206 No Windows PowerShell, execute `curl.exe`; o `curl` simples é um alias para `Invoke-WebRequest` e rejeita esses sinalizadores.

207 

208 Primeiro, busque o documento de descoberta, que confirma que o gateway está ativo, a configuração é válida e todas as verificações de inicialização passaram:

209 

210 ```bash theme={null}

211 curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq

212 ```

213 

214 ```json theme={null}

215 {

216 "issuer": "https://claude-gateway.internal.example.com",

217 "device_authorization_endpoint": "…/oauth/device_authorization",

218 "token_endpoint": "…/oauth/token",

219 "grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code", "refresh_token"]

220 }

221 ```

222 

223 A resposta inclui campos adicionais, como `response_types_supported` e `scopes_supported`.

224 

225 Segundo, solicite uma autorização de dispositivo, que confirma que o fluxo de sign-in do dispositivo funciona e Postgres é acessível e gravável:

226 

227 ```bash theme={null}

228 curl -s -X POST https://claude-gateway.internal.example.com/oauth/device_authorization | jq

229 ```

230 

231 ```json theme={null}

232 {

233 "device_code": "…",

234 "user_code": "WDJB-MJHT",

235 "verification_uri": "https://claude-gateway.internal.example.com/device",

236 "verification_uri_complete": "https://claude-gateway.internal.example.com/device?user_code=WDJB-MJHT",

237 "expires_in": 600,

238 "interval": 5

239 }

240 ```

241 

242 Terceiro, teste a perna do navegador abrindo `verification_uri_complete` em um navegador e confirmando o código. Você deve ser redirecionado para a página de sign-in do seu IdP e, após fazer login, voltar ao gateway com uma confirmação de sign-in.

243 

244 Use a primeira verificação que falha para localizar o problema:

245 

246 * **Primeira verificação falha**: a inicialização não foi concluída; verifique stderr

247 * **Segunda verificação falha**: Postgres não é acessível do gateway ou a função não pode escrever; verifique a string de conexão e as concessões

248 * **Terceira verificação não alcança o IdP**: verifique que o URI de redirecionamento do IdP corresponde exatamente a `https://<gateway>/oauth/callback`

249 * **Terceira verificação alcança o IdP mas volta com um erro**: leia o log de auditoria do gateway, que registra cada rejeição de autenticação com o motivo, como `email domain not allowed`

250 </Step>

251 

252 <Step title="Faça login de um desenvolvedor">

253 Esta última etapa acontece em uma máquina de desenvolvedor, não no servidor. Defina `forceLoginMethod` como `"gateway"` e `forceLoginGatewayUrl` como a `public_url` do seu gateway no [arquivo de configurações gerenciadas](/docs/pt/settings#settings-files) dessa máquina, então execute `/login`, pressione Enter na tela **Cloud gateway** e conclua o sign-in do navegador. [Defina a URL do gateway](#set-the-gateway-url) abaixo cobre a distribuição de ambas as chaves em escala.

254 </Step>

255</Steps>

256 

257<h2 id="connect-developers">

258 Conectar desenvolvedores

259</h2>

260 

261Os desenvolvedores se conectam de seus próprios laptops com um sign-in de navegador, usando sua conta de trabalho corporativa. Eles não precisam de uma conta claude.ai, uma chave de API ou uma assinatura, porque as solicitações para o modelo passam pelo gateway usando a credencial upstream da organização. A conexão é orientada pelas [configurações gerenciadas no lado do cliente](/docs/pt/claude-apps-gateway-config#client-side-managed-settings) que você envia via MDM, então não há configuração manual no lado do desenvolvedor; esta seção cobre o que o administrador configura.

262 

263A CLI coloca a impressão digital do certificado TLS folha do gateway na primeira conexão e a fixa por nome de host. Publique a impressão digital SHA-256 esperada junto com a URL do gateway para que os desenvolvedores tenham algo para comparar. Obtenha a impressão digital do arquivo de certificado com `openssl x509 -noout -fingerprint -sha256 -in cert.pem`; o prompt `/login` mostra os primeiros 16 caracteres do resumo como hexadecimal minúsculo sem separadores.

264 

265Quando o certificado é rotacionado, cada desenvolvedor vê o prompt de confiança novamente, então trate rotações como um evento planejado e republique a impressão digital.

266 

267Uma vez conectado, o [seletor de modelo](/docs/pt/model-config) mostra os modelos na lista de permissões `availableModels` do desenvolvedor, as configurações gerenciadas se aplicam na inicialização e atualizam a cada hora, e a telemetria é roteada para seu coletor. As sessões são atualizadas silenciosamente antes da expiração de `ttl_hours`, e uma atualização falhada após desprovisionamento de IdP solicita um novo login.

268 

269<h3 id="set-the-gateway-url">

270 Defina a URL do gateway

271</h3>

272 

273Defina ambas as chaves no arquivo de [configurações gerenciadas](/docs/pt/settings#settings-files) por SO que você implanta via MDM ou diretamente no disco, e `/login` abre diretamente na tela **Cloud gateway** com a URL preenchida:

274 

275```json theme={null}

276{

277 "forceLoginMethod": "gateway",

278 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"

279}

280```

281 

282O desenvolvedor pressiona Enter para se conectar. O prompt de impressão digital TLS de primeira conexão ainda aparece.

283 

284Não há opção de gateway no seletor de login para um desenvolvedor selecionar manualmente, e `forceLoginGatewayUrl` é ignorado nos arquivos de configurações próprias de um desenvolvedor. `forceLoginMethod` sozinho, sem uma URL, deixa o desenvolvedor em uma mensagem "Entre em contato com seu administrador de TI". Ambas as chaves pertencem ao arquivo que você envia para máquinas, não ao bloco `managed.policies[].cli` do gateway, que só alcança clientes que já estão conectados.

285 

286<h3 id="ci-pipelines-and-remote-machines">

287 Pipelines de CI e máquinas remotas

288</h3>

289 

290Não há fluxo de token de serviço para pipelines não supervisionados. O sign-in do gateway sempre executa o fluxo de dispositivo do navegador, então um trabalho de CI sem um desenvolvedor para aprovar o sign-in não pode se autenticar; configure aqueles contra seu provedor diretamente.

291 

292Uma vez que um desenvolvedor tenha feito login, cada invocação do Claude Code nessa máquina usa a sessão do gateway, incluindo execuções não interativas `claude -p` e sessões iniciadas pelo Agent SDK, e a [política do gateway se aplica a todas elas](/docs/pt/claude-apps-gateway-config#managed).

293 

294O fluxo de dispositivo separa a CLI de polling do navegador aprovador, então uma caixa de desenvolvimento remota sem exibição ainda funciona: o desenvolvedor executa `/login` via SSH na máquina remota e abre o link de verificação no navegador em seu laptop.

295 

296<h3 id="what’s-enforced-on-developers">

297 O que é aplicado aos desenvolvedores

298</h3>

299 

300Estas garantias se aplicam a cada sessão de gateway conectada.

301 

302* **Acesso a modelos**: solicitações para modelos que a política não concede retornam 400, e o seletor `/model` é filtrado para a lista de permissões `availableModels` da política. Defina [`enforceAvailableModels: true`](/docs/pt/model-config#default-model-behavior) na política para que a opção Padrão resolva para um modelo dentro de `availableModels` em vez de para o padrão integrado do Claude Code; sem isso, Padrão permanece selecionável e é rejeitado no tempo de solicitação se esse modelo não for concedido.

303* **Destino de telemetria**: quando [encaminhamento de telemetria](/docs/pt/claude-apps-gateway-config#telemetry) é configurado, o endpoint de exportação OTLP é fixado ao gateway, e a configuração enviada pelo gateway substitui variáveis `OTEL_*` definidas localmente.

304* **Credenciais**: o token do gateway é a única credencial da sessão. `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, `apiKeyHelper` e qualquer login anterior de claude.ai são ignorados enquanto conectado, então os desenvolvedores não precisam fazer logout de claude.ai primeiro.

305* **Configurações gerenciadas**: chaves bloqueadas não podem ser substituídas localmente. A CLI aplica a política na inicialização e em cada sondagem horária.

306* **Inicialização**: sessões conectadas saem na inicialização com um erro após cerca de 10 segundos quando o gateway é inacessível, em vez de iniciar sem suas configurações.

307* **Desprovisionamento**: uma sessão cujo usuário é desabilitado no IdP expira dentro de `ttl_hours` quando a próxima atualização falha.

308 

309<h3 id="what-the-organization-can-see">

310 O que a organização pode ver

311</h3>

312 

313A telemetria de uso carrega a identidade do desenvolvedor, contagens de tokens, modelo e latência para o coletor da organização. O gateway não registra ou armazena conteúdo de prompt ou conclusão. Se telemetria mais rica, como logs e rastreamentos, é coletada, que pode incluir comandos e caminhos de arquivo, é a [escolha por destino](/docs/pt/claude-apps-gateway-config#telemetry) da organização.

314 

315<h2 id="availability-and-limitations">

316 Disponibilidade e limitações

317</h2>

318 

319A tabela cobre quais recursos do Claude Code funcionam quando os desenvolvedores se conectam através do gateway e o que o próprio servidor gateway suporta. Onde algo não é suportado, a coluna Notas fornece a alternativa.

320 

321O gateway entrega os valores [`anthropic-beta`](https://platform.claude.com/docs/en/api/beta-headers) que a CLI envia para cada upstream, então operadores não mantêm uma lista de permissões beta. Para Amazon Bedrock, que ignora o cabeçalho, o gateway move os valores para o campo `anthropic_beta` do corpo da solicitação; os outros upstreams recebem o cabeçalho conforme enviado.

322 

323O conjunto beta de sessão de gateway da CLI omite betas apenas de primeira parte e a beta de ttl de cache estendido, é por isso que essas linhas abaixo mostram como não disponíveis.

324 

325| Recurso | Status | Notas |

326| ----------------------------------------------------------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

327| Encaminhamento de inferência (Amazon Bedrock, Claude Platform on AWS, Agent Platform do Google Cloud, Microsoft Foundry, Anthropic) | Disponível | Com tradução de modelo por upstream e failover. O upstream Amazon Bedrock usa o endpoint `bedrock-runtime` e a cadeia de credencial padrão da AWS; o [endpoint Mantle](/docs/pt/amazon-bedrock#use-the-mantle-endpoint) do Amazon Bedrock não é um upstream suportado. O [upstream Claude Platform on AWS](/docs/pt/claude-apps-gateway-config#claude-platform-on-aws) requer Claude Code v2.1.198 ou posterior no servidor gateway. |

328| Acesso a modelos e configurações gerenciadas por grupo IdP | Disponível | O acesso a modelos é aplicado no lado do servidor; as configurações gerenciadas são entregues por grupo IdP e aplicadas pela CLI no [nível de configurações gerenciadas](/docs/pt/settings#settings-precedence) |

329| Fan-out de telemetria (OTLP/HTTP) | Disponível | Identidade-marcada por exportação; ambas as codificações protobuf e JSON |

330| Provedores de identidade OIDC | Disponível | Qualquer IdP compatível com OIDC; o gateway executa descoberta OIDC padrão e o fluxo de código de autorização. Consulte [Configuração do provedor de identidade](/docs/pt/claude-apps-gateway-deploy#identity-provider-setup) para configuração por IdP |

331| Limites de gastos por usuário e por grupo | Disponível | Consulte [Limites de gastos](/docs/pt/claude-apps-gateway-spend-limits) |

332| Busca na web no lado do servidor | Não disponível | A CLI não pode ver qual provedor upstream o gateway roteia, então não pode verificar o suporte de busca na web e desabilita WebSearch em sessões de gateway |

333| Cache de prompt padrão | Disponível | Os pontos de interrupção `cache_control` são encaminhados para cada upstream |

334| TTL de cache de 1 hora | Não disponível | A CLI omite a beta de ttl de cache estendido em sessões de gateway, porque nem todo upstream que o gateway pode rotear suporta o TTL de 1 hora, então o cache de prompt através do gateway usa o TTL de 5 minutos; consulte a nota de cabeçalho beta acima |

335| Modo automático | Disponível | Segue as [regras do provedor de terceiros](/docs/pt/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry): apenas os modelos elegíveis em provedores de terceiros podem usá-lo. {/* min-version: 2.1.207 */}Antes da v2.1.207, o modo automático em sessões de gateway exigia a definição de `CLAUDE_CODE_ENABLE_AUTO_MODE=1`, entregável através do bloco `env` da política gerenciada |

336| Otimizações apenas de primeira parte, como escopo de cache global e ferramentas eficientes em tokens | Não disponível | A CLI não as habilita em sessões de gateway; consulte a nota de cabeçalho beta acima |

337| OTLP/gRPC | Não suportado | OTLP sobre HTTP apenas |

338| SAML, LDAP e outras autenticações não-OIDC | Não suportado | OIDC apenas. Coloque na frente com uma ponte OIDC se necessário |

339| Multi-tenant (múltiplos emissores OIDC) | Não suportado | Um emissor por gateway. Execute instâncias separadas |

340| Servidor Windows | Não suportado | Implante no Linux. macOS apenas para desenvolvimento local |

341| Gráfico Helm | Não disponível | O gateway é executado como um Deployment sem estado padrão; consulte o [guia de implantação](/docs/pt/claude-apps-gateway-deploy#kubernetes) |

342| Interface do usuário de administração | Não disponível | A configuração é o arquivo YAML; reimplante para alterá-la |

343 

344<h2 id="next-steps">

345 Próximas etapas

346</h2>

347 

348O guia de início rápido deixa você com uma configuração mínima em execução sob Docker Compose. Para ir além:

349 

350* Expanda `gateway.yaml` além da configuração mínima, por exemplo para adicionar RBAC por grupo, failover multi-upstream ou destinos de telemetria. A [referência de configuração](/docs/pt/claude-apps-gateway-config) cobre todas as opções.

351* Mude do Compose para uma implantação de produção em Kubernetes ou Cloud Run, configure seu IdP adequadamente e revise o modelo de segurança. O [guia de implantação e operações](/docs/pt/claude-apps-gateway-deploy) cobre configuração por IdP, requisitos de imagem de contêiner, sondas de saúde e solução de problemas.

352* Coloque limites de gastos em desenvolvedores individuais ou grupos para que uma carga de trabalho descontrolada não possa consumir todo o seu compromisso. [Limites de gastos](/docs/pt/claude-apps-gateway-spend-limits) cobre a API de administração e como a aplicação funciona.

353* Para um exemplo completo trabalhado no Google Cloud, com Cloud Run, Cloud SQL e Secret Manager, consulte [Implante no Google Cloud](/docs/pt/claude-apps-gateway-on-gcp).

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Executar Claude Code atrás de um launcher corporativo

6 

7> Rotear os processos que Claude Code inicia a partir de seu próprio binário, incluindo o serviço de fundo e cada sessão de visualização de agente, através de um launcher obrigatório com CLAUDE_CODE_PROCESS_WRAPPER.

8 

9Algumas organizações exigem que cada processo em uma estação de trabalho seja iniciado através de um launcher obrigatório. O launcher aplica a sandbox, controles de rede ou injeção de credenciais das quais a postura de segurança da empresa depende, e um binário que inicia sem isso é uma violação de política.

10 

11`CLAUDE_CODE_PROCESS_WRAPPER` inicia cada processo que Claude Code lança a partir de seu próprio binário através do seu launcher: o serviço de fundo, cada sessão que hospeda em [agent view](/docs/pt/agent-view), e os relançamentos do Claude Code após uma atualização. Defina-o como o caminho absoluto do seu launcher, e Claude Code executa o launcher com o comando Claude Code como seus argumentos.

12 

13Um launcher que envolve o comando `claude` no seu `PATH` não consegue alcançar esses processos, porque eles iniciam a partir do caminho direto do binário sem consultar `claude`.

14 

15<Note>

16 `CLAUDE_CODE_PROCESS_WRAPPER` requer Claude Code v2.1.208 ou posterior. Versões anteriores ignoram a variável e iniciam cada processo sem envolvimento.

17</Note>

18 

19<h2 id="what-the-launcher-covers">

20 O que o launcher cobre

21</h2>

22 

23Com `CLAUDE_CODE_PROCESS_WRAPPER` definido, Claude Code inicia cada um dos seguintes processos através do seu launcher:

24 

25* O serviço de fundo que `claude agents` e sessões de fundo iniciam sob demanda.

26* O host do terminal e a sessão Claude Code dentro de cada linha de agent view, incluindo as sessões de espera quente que o serviço mantém prontas.

27* Sessões que o serviço reinicia após uma atualização ou falha.

28* O relançamento que Claude Code realiza de si mesmo para terminar de instalar uma atualização, incluindo a ação restart-for-update do agent view.

29 

30No Windows, a variável é ignorada: o contrato do launcher depende de `exec`, que Windows não suporta. Uma máquina Windows com a variável definida executa cada processo sem envolvimento e continua funcionando, e o único sinal é um aviso no [debug log](/docs/pt/troubleshooting). Se sua política de launcher cobre Windows, a variável não a satisfaz lá: conte máquinas Windows como sem envolvimento quando você planejar o lançamento.

31 

32<h3 id="processes-that-start-outside-the-launcher">

33 Processos que iniciam fora do launcher

34</h3>

35 

36Três processos nunca iniciam através do launcher:

37 

38* Um [serviço de fundo instalado](/docs/pt/agent-view#the-supervisor-process): `launchd` ou `systemd` inicia esse processo a partir de seu arquivo de unidade. `/status` e `claude daemon status` avisam quando isso se aplica, e as sessões que o serviço gera ainda iniciam através do launcher uma vez que o serviço reinicia com a variável em suas configurações.

39* Uma sessão que você inicia você mesmo em um terminal, que executa da forma como você a invocou. Para cobrir essas sessões, coloque um script chamado `claude` em um diretório anterior no `PATH` que executa seu launcher com o binário real; não substitua o symlink gerenciado. Self-spawns não consultam `PATH`, então os dois launchers nunca se empilham.

40* O primeiro processo de um deep link `claude-cli://`, que o manipulador de protocolo do sistema operacional inicia diretamente. Tudo que essa sessão inicia em segundo plano depois executa através do launcher. Para fechar esse caminho completamente, [impeça o registro do manipulador](/docs/pt/deep-links#registration-and-supported-platforms) com a configuração `disableDeepLinkRegistration`.

41 

42<h3 id="helper-process-names-in-process-monitors">

43 Nomes de processos auxiliares em monitores de processos

44</h3>

45 

46Com um launcher configurado, `ps` e Activity Monitor mostram o nome do binário versionado para os processos auxiliares de fundo em vez dos rótulos `claude bg-pty-host` e `claude bg-spare` do Claude Code, porque o `exec` do launcher reconstrói a lista de argumentos. A renomeação é um efeito colateral, não ocultação: os processos são de outra forma inalterados, e Claude Code identifica seus próprios processos pelo caminho do binário, nunca pelo nome de exibição.

47 

48<h2 id="set-up-the-launcher">

49 Configure o launcher

50</h2>

51 

52<Steps>

53 <Step title="Escreva o script do launcher">

54 Crie um script executável em um caminho absoluto, como `/opt/corp/launcher`. Claude Code o executa com o comando Claude Code completo como seus argumentos, e o script deve terminar chamando `exec "$@"` para que se substitua pelo Claude Code:

55 

56 ```bash theme={null}

57 #!/bin/sh

58 # Configuração da sua organização: entre na sandbox, aplique

59 # controles de rede ou injete credenciais.

60 exec "$@"

61 ```

62 

63 Torne-o executável com `chmod +x`. A porção de configuração é o que seu launcher deve fazer antes de Claude Code executar; [o contrato do launcher](#the-launcher-contract) abaixo lista as regras que o script deve seguir.

64 

65 <Note>

66 Se você substituiu anteriormente o symlink `~/.local/bin/claude` pelo seu launcher, restaure o symlink original na mesma mudança. Um symlink substituído faz a primeira sessão envolvida iniciar o serviço de fundo através de ambos os launchers de uma vez, e coloca a instalação em um estado gerenciado externamente: `/doctor` relata isso, auto-update deixa o arquivo no lugar, e limpeza de versões antigas permanece desabilitada até que o instalador gerencie esse caminho novamente.

67 </Note>

68 </Step>

69 

70 <Step title="Defina CLAUDE_CODE_PROCESS_WRAPPER nas configurações">

71 Defina a variável no bloco `env` de um arquivo de configurações para que o serviço de fundo desanexado a herde. Um `export` de shell não é suficiente: o serviço de fundo inicia sob demanda, sobrevive ao seu shell, e nunca relê perfis de shell.

72 

73 Para uma máquina, adicione-o a `~/.claude/settings.json`. Para implantá-lo em cada máquina da sua organização, coloque o mesmo bloco em [managed settings](/docs/pt/permissions#managed-settings):

74 

75 ```json theme={null}

76 {

77 "env": {

78 "CLAUDE_CODE_PROCESS_WRAPPER": "/opt/corp/launcher"

79 }

80 }

81 ```

82 

83 Quando mais de uma fonte define a variável, o valor de managed settings substitui tanto `~/.claude/settings.json` quanto um valor exportado no shell, para que os usuários não possam apontar self-spawns para um launcher diferente.

84 

85 Configurações de projeto e local não podem definir essa variável. Um arquivo confirmado em um repositório não deve ser capaz de colocar um binário na frente de cada processo Claude Code na máquina, então `CLAUDE_CODE_PROCESS_WRAPPER` em `.claude/settings.json` ou `.claude/settings.local.json` é ignorado, com um aviso no [debug log](/docs/pt/troubleshooting).

86 </Step>

87 

88 <Step title="Reinicie o serviço de fundo e suas sessões">

89 Um serviço de fundo em execução e quaisquer sessões `claude` abertas leem a variável uma vez na inicialização, então continuam lançando processos sem envolvimento até serem reiniciados. Execute `claude daemon stop --any` para parar o serviço sob demanda; o próximo comando que o necessita, como `claude agents`, inicia um envolvido. Um [serviço instalado](/docs/pt/agent-view#the-supervisor-process) leva `claude daemon stop` sem `--any`. Então reinicie suas sessões `claude` abertas.

90 

91 Em máquinas que você não pode reiniciar manualmente, a primeira sessão iniciada após o push de configurações aposenta um serviço sob demanda sem envolvimento restante automaticamente. Uma máquina onde nenhuma nova sessão inicia mantém seu serviço sem envolvimento até que uma o faça, e um serviço instalado sempre precisa do reinício nesta etapa.

92 </Step>

93 

94 <Step title="Verifique">

95 Execute `/status` em uma sessão: a entrada Self-exec mostra o comando de lançamento resolvido e avisa quando o serviço de fundo em execução não corresponde a ele. `claude daemon status` imprime as mesmas informações do shell, incluindo depois que você desdefine a variável, quando `/status` não mostra mais a entrada.

96 </Step>

97</Steps>

98 

99<h2 id="the-launcher-contract">

100 O contrato do launcher

101</h2>

102 

103Quando o launcher não consegue executar, Claude Code recusa iniciar o processo em vez de iniciá-lo sem envolvimento. No Windows, [a variável é ignorada](#what-the-launcher-covers) e os processos iniciam sem envolvimento. Claude Code mantém o script a essas regras:

104 

105* **Termine com `exec "$@"`**. Um launcher que bifurca um filho e sai deixa um processo Claude Code órfão que o serviço de fundo não consegue rastrear. Agent view marca tal sessão como falha com uma mensagem nomeando o launcher, e o serviço colhe o que o launcher deixou para trás.

106* **Não reordene, absorva ou antecipe argumentos.** O primeiro argumento é o binário Claude Code e tudo depois dele é seu argv.

107* **Passe cada variável de ambiente herdada através para `exec`.** Adicionar variáveis, como credenciais injetadas, é bom; descartar as herdadas não é.

108 * Os tokens de autenticação por sessão, a seleção de modelo e provedor, e `CLAUDE_CODE_PROCESS_WRAPPER` em si viajam no ambiente herdado, então um launcher que o reconstrói a partir de uma lista de permissões quebra as sessões que inicia, e `/status` relata uma incompatibilidade de launcher.

109 * Se o launcher deve entrar em um namespace ou sandbox que redefine o ambiente, re-exporte o ambiente herdado dentro dele verbatim.

110* **Alcance `exec` dentro de cerca de três segundos cada vez que o launcher executa.** Uma expedição de fundo fria executa o launcher duas vezes em série antes do primeiro byte de saída, então faça trabalho lento como uma troca de single sign-on preguiçosamente ou a partir de um cache.

111 * Um launcher que executa muito além do orçamento é tratado como um início travado e reiniciado.

112* **Tolere ser invocado de dentro de si mesmo.** Claude Code aplica o launcher a cada self-spawn aninhado, então um launcher que adquire um recurso exclusivo deve detectar que já o mantém.

113* **Não escreva no terminal antes de Claude Code iniciar.** Qualquer coisa impressa antes do `exec` é relatada como a causa do crash se a sessão morrer antes de inicializar.

114 

115<h3 id="format-of-the-claude_code_process_wrapper-value">

116 Formato do valor `CLAUDE_CODE_PROCESS_WRAPPER`

117</h3>

118 

119Para a maioria dos launchers, o valor é apenas o caminho absoluto do script, como `/opt/corp/launcher`.

120 

121Para passar argumentos do seu launcher, escreva-os após o caminho. Claude Code analisa o valor como uma lista de argumentos, não um comando de shell:

122 

123* Espaço em branco separa tokens, e aspas duplas agrupam um token que contém espaços.

124* Um valor que começa com `[` é lido como um array de string JSON, como `["/opt/corp/launcher", "--profile", "cc"]`.

125* Sintaxe de shell não funciona: não há expansão de variável ou globbing, e um operador sem aspas como `;`, `|`, `&`, ou `$(` é rejeitado como um erro de configuração em vez de reinterpretado.

126 

127Quando o valor não pode ser usado, Claude Code recusa iniciar o processo afetado e [relata o motivo](/docs/pt/errors#claude_code_process_wrapper-launcher-errors).

128 

129<h2 id="relationship-to-claude_code_shell_prefix">

130 Relação com `CLAUDE_CODE_SHELL_PREFIX`

131</h2>

132 

133`CLAUDE_CODE_PROCESS_WRAPPER` envolve os próprios processos do Claude Code e passa o comando através como tokens argv separados para o launcher fazer `exec`. [`CLAUDE_CODE_SHELL_PREFIX`](/docs/pt/env-vars) envolve os comandos de shell que Claude Code executa em seu nome, como chamadas de ferramenta Bash, hooks, e os comandos que iniciam servidores MCP stdio, e passa cada um como uma única string com aspas de shell em `$1` para o wrapper reavaliar. Um launcher escrito para um não funciona como o outro.

134 

135<h2 id="related-resources">

136 Recursos relacionados

137</h2>

138 

139* [Agent view](/docs/pt/agent-view): as sessões de fundo e processo supervisor que o launcher cobre

140* [Environment variables](/docs/pt/env-vars): a entrada de referência `CLAUDE_CODE_PROCESS_WRAPPER`

141* [Managed settings](/docs/pt/permissions#managed-settings): entregar o bloco `env` em toda uma frota

142* [Launcher error reference](/docs/pt/errors#claude_code_process_wrapper-launcher-errors): as mensagens de recusa e como se recuperar

12 12 

13<Warning>13<Warning>

14 Embora o dev container forneça proteções substanciais, nenhum sistema é completamente imune a todos os ataques.14 Embora o dev container forneça proteções substanciais, nenhum sistema é completamente imune a todos os ataques.

15 Quando executado com `--dangerously-skip-permissions`, dev containers não impedem que um projeto malicioso exfiltre qualquer coisa acessível dentro do contêiner, incluindo as credenciais do Claude Code armazenadas em [`~/.claude`](/pt/claude-directory).15 Quando executado com `--dangerously-skip-permissions`, dev containers não impedem que um projeto malicioso exfiltre qualquer coisa acessível dentro do contêiner, incluindo as credenciais do Claude Code armazenadas em [`~/.claude`](/docs/pt/claude-directory).

16 Use dev containers apenas ao desenvolver com repositórios confiáveis e monitore as atividades do Claude.16 Use dev containers apenas ao desenvolver com repositórios confiáveis e monitore as atividades do Claude.

17 Evite montar segredos do host como `~/.ssh` ou arquivos de credenciais de nuvem no contêiner; prefira tokens com escopo de repositório ou de curta duração.17 Evite montar segredos do host como `~/.ssh` ou arquivos de credenciais de nuvem no contêiner; prefira tokens com escopo de repositório ou de curta duração.

18</Warning>18</Warning>

20<Accordion title="Como dev containers funcionam com seu editor">20<Accordion title="Como dev containers funcionam com seu editor">

21 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="Diagrama mostrando um editor no host conectando a um contêiner dev Docker. Claude Code, o terminal e ferramentas de compilação executam dentro do contêiner. O repositório do host é bind-mounted no contêiner como o workspace." width="640" height="300" data-path="images/devcontainer-architecture.svg" />21 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=9017b1d16a446c6cc37ba562f35b9aae" className="dark:hidden" alt="Diagrama mostrando um editor no host conectando a um contêiner dev Docker. Claude Code, o terminal e ferramentas de compilação executam dentro do contêiner. O repositório do host é bind-mounted no contêiner como o workspace." width="640" height="300" data-path="images/devcontainer-architecture.svg" />

22 22 

23 <img src="https://mintcdn.com/claude-code/YvJyjZfd9yMihr0i/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=YvJyjZfd9yMihr0i&q=85&s=ef00c8e25b1ea7a3a152895f1488831b" className="hidden dark:block" alt="Diagrama mostrando um editor no host conectando a um contêiner dev Docker. Claude Code, o terminal e ferramentas de compilação executam dentro do contêiner. O repositório do host é bind-mounted no contêiner como o workspace." width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />23 <img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/devcontainer-architecture-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=a0a340b1f2afc6a590696102c8acaaca" className="hidden dark:block" alt="Diagrama mostrando um editor no host conectando a um contêiner dev Docker. Claude Code, o terminal e ferramentas de compilação executam dentro do contêiner. O repositório do host é bind-mounted no contêiner como o workspace." width="640" height="300" data-path="images/devcontainer-architecture-dark.svg" />

24 24 

25 Um dev container é executado como um contêiner Docker, seja na sua máquina ou em um host de nuvem como GitHub Codespaces. Um editor que suporta a especificação Dev Containers, como VS Code, GitHub Codespaces, um IDE JetBrains ou Cursor, se conecta a esse contêiner: você navega e edita arquivos no editor como de costume, mas o terminal integrado, servidores de linguagem e ferramentas de compilação todos executam dentro do contêiner em vez de no seu host. Editores sem suporte a dev container, como Vim simples, não fazem parte deste fluxo de trabalho.25 Um dev container é executado como um contêiner Docker, seja na sua máquina ou em um host de nuvem como GitHub Codespaces. Um editor que suporta a especificação Dev Containers, como VS Code, GitHub Codespaces, um IDE JetBrains ou Cursor, se conecta a esse contêiner: você navega e edita arquivos no editor como de costume, mas o terminal integrado, servidores de linguagem e ferramentas de compilação todos executam dentro do contêiner em vez de no seu host. Editores sem suporte a dev container, como Vim simples, não fazem parte deste fluxo de trabalho.

26 26 

27 Claude Code é executado dentro do contêiner, então ele vê os mesmos arquivos, dependências e ferramentas que o resto da cadeia de ferramentas do seu projeto. No VS Code você pode usar o [painel de extensão Claude Code](/pt/vs-code) ou executar `claude` no terminal integrado; ambos executam dentro do contêiner e compartilham a mesma configuração `~/.claude`.27 Claude Code é executado dentro do contêiner, então ele vê os mesmos arquivos, dependências e ferramentas que o resto da cadeia de ferramentas do seu projeto. No VS Code você pode usar o [painel de extensão Claude Code](/docs/pt/vs-code) ou executar `claude` no terminal integrado; ambos executam dentro do contêiner e compartilham a mesma configuração `~/.claude`.

28</Accordion>28</Accordion>

29 29 

30<h2 id="add-claude-code-to-your-dev-container">30<h2 id="add-claude-code-to-your-dev-container">

75O que você vê no prompt de autenticação depende do seu provedor:75O que você vê no prompt de autenticação depende do seu provedor:

76 76 

77* **Anthropic**: entre através de um navegador com sua conta Claude ou Anthropic Console77* **Anthropic**: entre através de um navegador com sua conta Claude ou Anthropic Console

78* **[Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry](/pt/third-party-integrations)**: Claude Code usa suas credenciais do provedor de nuvem, sem prompt de navegador78* **[Amazon Bedrock, Google Cloud's Agent Platform ou Microsoft Foundry](/docs/pt/third-party-integrations)**: Claude Code usa suas credenciais do provedor de nuvem, sem prompt de navegador

79 79 

80Para provedores de nuvem, passe credenciais para o contêiner como variáveis de ambiente através de `containerEnv`, um segredo do Codespaces, ou a identidade de carga de trabalho da sua nuvem em vez de montar arquivos de credenciais do host. Veja [Amazon Bedrock](/pt/amazon-bedrock), [Google Cloud's Agent Platform](/pt/google-vertex-ai) ou [Microsoft Foundry](/pt/microsoft-foundry) para a cadeia de credenciais que Claude Code lê.80Para provedores de nuvem, passe credenciais para o contêiner como variáveis de ambiente através de `containerEnv`, um segredo do Codespaces, ou a identidade de carga de trabalho da sua nuvem em vez de montar arquivos de credenciais do host. Veja [Amazon Bedrock](/docs/pt/amazon-bedrock), [Google Cloud's Agent Platform](/docs/pt/google-vertex-ai) ou [Microsoft Foundry](/docs/pt/microsoft-foundry) para a cadeia de credenciais que Claude Code lê.

81 81 

82Veja [Escolha seu provedor de API](/pt/admin-setup#choose-your-api-provider) para decidir qual caminho se adequa à sua organização.82Veja [Escolha seu provedor de API](/docs/pt/admin-setup#choose-your-api-provider) para decidir qual caminho se adequa à sua organização.

83 83 

84<Note>84<Note>

85 Se a entrada do navegador for concluída mas o callback nunca chegar ao contêiner, copie o código mostrado no navegador e cole-o no prompt `Paste code here if prompted` no terminal. Isso pode acontecer quando o encaminhamento de porta do editor não roteia o callback localhost.85 Se a entrada do navegador for concluída mas o callback nunca chegar ao contêiner, copie o código mostrado no navegador e cole-o no prompt `Paste code here if prompted` no terminal. Isso pode acontecer quando o encaminhamento de porta do editor não roteia o callback localhost.

89 Persistir autenticação e configurações entre reconstruções89 Persistir autenticação e configurações entre reconstruções

90</h2>90</h2>

91 91 

92Por padrão, o diretório home do contêiner é descartado na reconstrução, então os engenheiros devem entrar novamente a cada vez. Claude Code armazena seu token de autenticação, configurações do usuário e histórico de sessão em [`~/.claude`](/pt/claude-directory). Monte um volume nomeado nesse caminho para manter esse estado entre reconstruções.92Por padrão, o diretório home do contêiner é descartado na reconstrução, então os engenheiros devem entrar novamente a cada vez. Claude Code armazena seu token de autenticação, configurações do usuário e histórico de sessão em [`~/.claude`](/docs/pt/claude-directory). Monte um volume nomeado nesse caminho para manter esse estado entre reconstruções.

93 93 

94O exemplo a seguir monta um volume no diretório home do usuário `node`:94O exemplo a seguir monta um volume no diretório home do usuário `node`:

95 95 

99]99]

100```100```

101 101 

102Substitua `/home/node` pelo diretório home do `remoteUser` do seu contêiner. Se você montar o volume em algum lugar diferente de `~/.claude`, defina [`CLAUDE_CONFIG_DIR`](/pt/env-vars) para o caminho de montagem para que Claude Code leia e escreva lá.102Substitua `/home/node` pelo diretório home do `remoteUser` do seu contêiner. Se você montar o volume em algum lugar diferente de `~/.claude`, defina [`CLAUDE_CONFIG_DIR`](/docs/pt/env-vars) para o caminho de montagem para que Claude Code leia e escreva lá.

103 103 

104Para isolar o estado por projeto em vez de compartilhar um volume em todos os repositórios, inclua a variável `${devcontainerId}` no nome da fonte. A [configuração de referência](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json) usa `source=claude-code-config-${devcontainerId}` para esse propósito.104Para isolar o estado por projeto em vez de compartilhar um volume em todos os repositórios, inclua a variável `${devcontainerId}` no nome da fonte. A [configuração de referência](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json) usa `source=claude-code-config-${devcontainerId}` para esse propósito.

105 105 

106No GitHub Codespaces, `~/.claude` persiste entre parar e iniciar um codespace, mas ainda é limpo quando você reconstrói o contêiner, então a montagem de volume acima se aplica lá também. Para levar autenticação entre codespaces, armazene `ANTHROPIC_API_KEY` ou um `CLAUDE_CODE_OAUTH_TOKEN` de [`claude setup-token`](/pt/authentication#generate-a-long-lived-token) como um [segredo do Codespaces](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces); Codespaces disponibiliza segredos como variáveis de ambiente dentro do contêiner automaticamente.106No GitHub Codespaces, `~/.claude` persiste entre parar e iniciar um codespace, mas ainda é limpo quando você reconstrói o contêiner, então a montagem de volume acima se aplica lá também. Para levar autenticação entre codespaces, armazene `ANTHROPIC_API_KEY` ou um `CLAUDE_CODE_OAUTH_TOKEN` de [`claude setup-token`](/docs/pt/authentication#generate-a-long-lived-token) como um [segredo do Codespaces](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces); Codespaces disponibiliza segredos como variáveis de ambiente dentro do contêiner automaticamente.

107 107 

108<h2 id="enforce-organization-policy">108<h2 id="enforce-organization-policy">

109 Aplicar política organizacional109 Aplicar política organizacional

111 111 

112Um dev container é um lugar conveniente para aplicar política organizacional, porque a mesma imagem e configuração executam na máquina de cada engenheiro.112Um dev container é um lugar conveniente para aplicar política organizacional, porque a mesma imagem e configuração executam na máquina de cada engenheiro.

113 113 

114Claude Code lê `/etc/claude-code/managed-settings.json` no Linux e a aplica com a precedência mais alta na [hierarquia de configurações](/pt/settings#how-scopes-interact), então valores lá substituem qualquer coisa que um engenheiro defina em `~/.claude` ou no diretório `.claude/` do projeto. Copie o arquivo para o lugar certo a partir do seu Dockerfile:114Claude Code lê `/etc/claude-code/managed-settings.json` no Linux e a aplica com a precedência mais alta na [hierarquia de configurações](/docs/pt/settings#how-scopes-interact), então valores lá substituem qualquer coisa que um engenheiro defina em `~/.claude` ou no diretório `.claude/` do projeto. Copie o arquivo para o lugar certo a partir do seu Dockerfile:

115 115 

116```dockerfile Dockerfile theme={null}116```dockerfile Dockerfile theme={null}

117RUN mkdir -p /etc/claude-code117RUN mkdir -p /etc/claude-code

118COPY managed-settings.json /etc/claude-code/managed-settings.json118COPY managed-settings.json /etc/claude-code/managed-settings.json

119```119```

120 120 

121Como o Dockerfile fica no repositório, qualquer pessoa com acesso de escrita pode alterar ou remover essa etapa. Para política que engenheiros não possam contornar editando arquivos do repositório, entregue configurações gerenciadas através de [configurações gerenciadas pelo servidor](/pt/server-managed-settings) ou seu MDM em vez disso. Veja [arquivos de configurações gerenciadas](/pt/settings#settings-files) para as chaves disponíveis e os outros caminhos de entrega.121Como o Dockerfile fica no repositório, qualquer pessoa com acesso de escrita pode alterar ou remover essa etapa. Para política que engenheiros não possam contornar editando arquivos do repositório, entregue configurações gerenciadas através de [configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings) ou seu MDM em vez disso. Veja [arquivos de configurações gerenciadas](/docs/pt/settings#settings-files) para as chaves disponíveis e os outros caminhos de entrega.

122 122 

123Para definir [variáveis de ambiente](/pt/env-vars) que se apliquem a cada sessão do Claude Code no contêiner, adicione-as a `containerEnv` no seu `devcontainer.json`. O exemplo a seguir desativa telemetria e relatório de erros e impede que Claude Code se atualize automaticamente após a instalação:123Para definir [variáveis de ambiente](/docs/pt/env-vars) que se apliquem a cada sessão do Claude Code no contêiner, adicione-as a `containerEnv` no seu `devcontainer.json`. O exemplo a seguir desativa telemetria e relatório de erros e impede que Claude Code se atualize automaticamente após a instalação:

124 124 

125```json devcontainer.json theme={null}125```json devcontainer.json theme={null}

126"containerEnv": {126"containerEnv": {

131 131 

132O Dev Container Feature sempre instala a versão mais recente do Claude Code. Para fixar uma versão específica do Claude Code para compilações reproduzíveis, instale-o a partir do seu Dockerfile com `npm install -g @anthropic-ai/claude-code@X.Y.Z` em vez de usar o feature, e defina `DISABLE_AUTOUPDATER` como mostrado acima.132O Dev Container Feature sempre instala a versão mais recente do Claude Code. Para fixar uma versão específica do Claude Code para compilações reproduzíveis, instale-o a partir do seu Dockerfile com `npm install -g @anthropic-ai/claude-code@X.Y.Z` em vez de usar o feature, e defina `DISABLE_AUTOUPDATER` como mostrado acima.

133 133 

134Para a lista completa de controles de política incluindo regras de permissão, restrições de ferramentas e listas de permissão de servidores MCP, veja [Configure Claude Code para sua organização](/pt/admin-setup).134Para a lista completa de controles de política incluindo regras de permissão, restrições de ferramentas e listas de permissão de servidores MCP, veja [Configure Claude Code para sua organização](/docs/pt/admin-setup).

135 135 

136Para disponibilizar [servidores MCP](/pt/mcp) dentro do contêiner, defina-os no [escopo do projeto](/pt/mcp#mcp-installation-scopes) em um arquivo `.mcp.json` na raiz do repositório para que sejam verificados junto com sua configuração de dev container. Instale quaisquer binários dos quais servidores stdio locais dependem no seu Dockerfile, e adicione domínios de servidor remoto à sua lista de permissão de rede.136Para disponibilizar [servidores MCP](/docs/pt/mcp) dentro do contêiner, defina-os no [escopo do projeto](/docs/pt/mcp#mcp-installation-scopes) em um arquivo `.mcp.json` na raiz do repositório para que sejam verificados junto com sua configuração de dev container. Instale quaisquer binários dos quais servidores stdio locais dependem no seu Dockerfile, e adicione domínios de servidor remoto à sua lista de permissão de rede.

137 137 

138<h2 id="restrict-network-egress">138<h2 id="restrict-network-egress">

139 Restringir saída de rede139 Restringir saída de rede

140</h2>140</h2>

141 141 

142Você pode limitar o tráfego de saída do contêiner apenas aos domínios que Claude Code precisa. Veja [Requisitos de acesso à rede](/pt/network-config#network-access-requirements) para os domínios de inferência e autenticação, e [Serviços de telemetria](/pt/data-usage#telemetry-services) para as conexões opcionais de telemetria e relatório de erros e como desabilitá-las.142Você pode limitar o tráfego de saída do contêiner apenas aos domínios que Claude Code precisa. Veja [Requisitos de acesso à rede](/docs/pt/network-config#network-access-requirements) para os domínios de inferência e autenticação, e [Serviços de telemetria](/docs/pt/data-usage#telemetry-services) para as conexões opcionais de telemetria e relatório de erros e como desabilitá-las.

143 143 

144O contêiner de referência inclui um script [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) que bloqueia todo o tráfego de saída exceto os domínios que Claude Code e suas ferramentas de desenvolvimento precisam. Executar um firewall dentro de um contêiner requer permissões extras, então a referência adiciona as capacidades `NET_ADMIN` e `NET_RAW` através de `runArgs`. O script de firewall e essas capacidades não são necessários para o próprio Claude Code: você pode deixá-los de fora e confiar em seus próprios controles de rede em vez disso.144O contêiner de referência inclui um script [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) que bloqueia todo o tráfego de saída exceto os domínios que Claude Code e suas ferramentas de desenvolvimento precisam. Executar um firewall dentro de um contêiner requer permissões extras, então a referência adiciona as capacidades `NET_ADMIN` e `NET_RAW` através de `runArgs`. O script de firewall e essas capacidades não são necessários para o próprio Claude Code: você pode deixá-los de fora e confiar em seus próprios controles de rede em vez disso.

145 145 

151 151 

152Pular prompts de permissão remove sua oportunidade de revisar chamadas de ferramentas antes de serem executadas. Claude ainda pode modificar qualquer arquivo no workspace bind-mounted, que aparece diretamente no seu host, e alcançar qualquer coisa que a política de rede do contêiner permite. Combine essa flag com as [restrições de saída de rede](#restrict-network-egress) acima para limitar o que uma sessão contornada pode alcançar.152Pular prompts de permissão remove sua oportunidade de revisar chamadas de ferramentas antes de serem executadas. Claude ainda pode modificar qualquer arquivo no workspace bind-mounted, que aparece diretamente no seu host, e alcançar qualquer coisa que a política de rede do contêiner permite. Combine essa flag com as [restrições de saída de rede](#restrict-network-egress) acima para limitar o que uma sessão contornada pode alcançar.

153 153 

154Se você quer menos prompts sem desabilitar verificações de segurança, considere [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) em vez disso, que tem um classificador revisando ações antes de serem executadas. Para impedir que engenheiros usem `--dangerously-skip-permissions` completamente, defina `permissions.disableBypassPermissionsMode` para `"disable"` em [configurações gerenciadas](/pt/settings#permission-settings).154Se você quer menos prompts sem desabilitar verificações de segurança, considere [modo automático](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) em vez disso, que tem um classificador revisando ações antes de serem executadas. Para impedir que engenheiros usem `--dangerously-skip-permissions` completamente, defina `permissions.disableBypassPermissionsMode` para `"disable"` em [configurações gerenciadas](/docs/pt/settings#permission-settings).

155 155 

156<h2 id="try-the-reference-container">156<h2 id="try-the-reference-container">

157 Experimente o contêiner de referência157 Experimente o contêiner de referência

193 193 

194Assim que Claude Code estiver executando no seu dev container, as páginas abaixo cobrem o resto de um rollout organizacional: escolher um caminho de autenticação, entregar política gerenciada fora do repositório, monitorar uso e entender o que Claude Code armazena e envia.194Assim que Claude Code estiver executando no seu dev container, as páginas abaixo cobrem o resto de um rollout organizacional: escolher um caminho de autenticação, entregar política gerenciada fora do repositório, monitorar uso e entender o que Claude Code armazena e envia.

195 195 

196* [Configure Claude Code para sua organização](/pt/admin-setup): escolha um provedor de autenticação, decida como a política chega aos dispositivos e planeje o rollout196* [Configure Claude Code para sua organização](/docs/pt/admin-setup): escolha um provedor de autenticação, decida como a política chega aos dispositivos e planeje o rollout

197* [Configurações gerenciadas pelo servidor](/pt/server-managed-settings): entregue política gerenciada do console de administrador Claude.ai para que engenheiros não possam contorná-la editando arquivos do repositório197* [Configurações gerenciadas pelo servidor](/docs/pt/server-managed-settings): entregue política gerenciada do console de administrador Claude.ai para que engenheiros não possam contorná-la editando arquivos do repositório

198* [Monitore uso e atividade de auditoria](/pt/monitoring-usage): exporte métricas OpenTelemetry e revise o que sua equipe está executando198* [Monitore uso e atividade de auditoria](/docs/pt/monitoring-usage): exporte métricas OpenTelemetry e revise o que sua equipe está executando

199* [Requisitos de acesso à rede](/pt/network-config#network-access-requirements): a lista completa de domínios para proxies e firewalls199* [Requisitos de acesso à rede](/docs/pt/network-config#network-access-requirements): a lista completa de domínios para proxies e firewalls

200* [Serviços de telemetria e opt-out](/pt/data-usage#telemetry-services): o que Claude Code envia por padrão e as variáveis de ambiente que desabilitam200* [Serviços de telemetria e opt-out](/docs/pt/data-usage#telemetry-services): o que Claude Code envia por padrão e as variáveis de ambiente que desabilitam

201* [Explore o diretório `.claude`](/pt/claude-directory): o que a montagem de volume contém, incluindo credenciais, configurações e histórico de sessão201* [Explore o diretório `.claude`](/docs/pt/claude-directory): o que a montagem de volume contém, incluindo credenciais, configurações e histórico de sessão

202* [Ambientes sandbox](/pt/sandbox-environments): compare dev containers com o sandbox Bash integrado, containers personalizados e VMs202* [Ambientes sandbox](/docs/pt/sandbox-environments): compare dev containers com o sandbox Bash integrado, containers personalizados e VMs

203* [Modelo de segurança](/pt/security): como o sistema de permissões do Claude Code, sandboxing e proteções contra injeção de prompt se encaixam203* [Modelo de segurança](/docs/pt/security): como o sistema de permissões do Claude Code, sandboxing e proteções contra injeção de prompt se encaixam

204* [Modos de permissão](/pt/permission-modes): a gama completa de modo de plano para modo automático para contorno, e quando usar cada um204* [Modos de permissão](/docs/pt/permission-modes): a gama completa de modo de plano para modo automático para contorno, e quando usar cada um

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Outros gateways LLM

6 

7> Rotear Claude Code através de um gateway LLM que sua organização já executa. Abrange conectar Claude Code a um gateway, implantar um para sua organização e o que Claude Code envia a um gateway.

8 

9Esta seção aborda o uso de um produto gateway que sua organização já executa, em vez de [gateway de aplicativos Claude](/docs/pt/claude-apps-gateway). Para saber o que é um gateway, como ele fica entre Claude Code e seu provedor, e como escolher entre gateway de aplicativos Claude e outro produto, consulte a [visão geral de gateway](/docs/pt/gateways).

10 

11<Note>

12 * Se você é um desenvolvedor conectando a um gateway existente: [conectar Claude Code ao seu gateway](/docs/pt/llm-gateway-connect)

13 * Se você é um administrador implantando um gateway para sua organização: [implantar e distribuir um gateway](/docs/pt/llm-gateway-rollout)

14 * Se você está configurando um produto gateway: a [referência de protocolo de gateway](/docs/pt/llm-gateway-protocol)

15</Note>

16 

17Qualquer gateway que exponha um [formato de API suportado](/docs/pt/llm-gateway-protocol#api-formats) funciona. Anthropic não endossa, mantém ou audita produtos gateway de terceiros, e não oferece suporte ao roteamento de Claude Code para modelos não-Claude através de nenhum gateway. Implante o gateway seguindo sua própria documentação, depois complete o lado Claude Code com as [etapas de rollout abaixo](#roll-out-a-gateway).

18 

19<h2 id="what-a-gateway-provides">

20 O que um gateway fornece

21</h2>

22 

23Um gateway oferece à sua organização um único lugar para gerenciar:

24 

25* **Credenciais**: a chave do provedor fica no lado do servidor; desenvolvedores mantêm credenciais de gateway em vez disso

26* **Rastreamento de uso**: atribua uso por desenvolvedor ou equipe, independentemente de qual provedor atende a solicitação

27* **Controles de custo**: aplique orçamentos e limites de taxa em um único lugar

28* **Registro de auditoria**: registre cada solicitação de modelo para conformidade

29* **Alternância de provedor**: altere o provedor na configuração do gateway, sem tocar nas máquinas dos desenvolvedores

30 

31Todos esses, exceto alternância de provedor, se aplicam se o upstream é a API da Anthropic ou um [provedor de nuvem](/docs/pt/third-party-integrations). A alternância de provedor sem reconfigurar máquinas de desenvolvedores também depende do gateway expor um único [endpoint em formato Anthropic](/docs/pt/llm-gateway-protocol#api-formats) independentemente do upstream; um gateway que expõe o próprio formato de um provedor vincula a configuração do cliente a esse provedor.

32 

33O tradeoff é que o gateway se torna infraestrutura que sua organização opera. Claude Code adiciona capacidades com cada lançamento, e um gateway que não as encaminha quebra os recursos correspondentes, então o produto gateway precisa ser mantido atualizado conforme Claude Code evolui. A [referência de protocolo de gateway](/docs/pt/llm-gateway-protocol) aborda o que encaminhar.

34 

35<h2 id="roll-out-a-gateway">

36 Implantar um gateway

37</h2>

38 

39Quando você estiver pronto para implantar um gateway LLM para sua organização, a sequência é a mesma qualquer que seja o produto gateway que você escolha:

40 

411. Implante o gateway e dê a ele sua credencial de provedor, para que ele possa autenticar as solicitações que encaminha.

422. Emita a cada desenvolvedor uma credencial de gateway, para que o uso seja atribuído ao desenvolvedor e o offboarding revogue uma credencial.

433. Distribua a configuração através de um [arquivo de configurações gerenciadas](/docs/pt/settings#settings-files) e sua ferramenta de segredos, para que cada máquina receba a URL base e uma credencial. Quando ambos forem distribuídos, os desenvolvedores não configuram nada. Se você não tiver distribuição de configurações em vigor, os desenvolvedores seguem a [página de conexão](/docs/pt/llm-gateway-connect) para definir as variáveis eles mesmos.

444. Faça cada desenvolvedor [verificar a configuração no Claude Code](/docs/pt/llm-gateway-connect#check-for-an-existing-configuration), para que problemas de distribuição apareçam antes de dependerem do gateway.

45 

46[Implantar um gateway LLM para sua organização](/docs/pt/llm-gateway-rollout) percorre cada etapa e mostra os arquivos de configuração para distribuir em cada uma. O gateway é uma parte da configuração da organização; para aplicação de política, visibilidade de uso e decisões de tratamento de dados, consulte [Configurar Claude Code para sua organização](/docs/pt/admin-setup).

47 

48<h2 id="subscriptions-and-gateways">

49 Assinaturas e gateways

50</h2>

51 

52Enquanto uma [variável de credencial de gateway](/docs/pt/llm-gateway-connect#set-the-credential-variable) ou `apiKeyHelper` está ativa, a assinatura claude.ai de um desenvolvedor não é usada: a credencial substitui o login da assinatura para essa sessão, e os limites de uso da assinatura não se aplicam. Esse tráfego é cobrado por token para quem quer que possua a credencial que o gateway encaminha, como sua conta Anthropic Console da organização, ou sua conta Amazon Bedrock, Google Cloud's Agent Platform, ou Microsoft Foundry quando o gateway roteia para lá.

53 

54[`ANTHROPIC_BASE_URL`](/docs/pt/llm-gateway-connect#set-the-base-url-and-credential) é a variável que aponta Claude Code para o gateway. Definir apenas essa variável, sem uma credencial de gateway, não substitui a assinatura. As solicitações ainda roteiam através do gateway, mas um login claude.ai salvo permanece como a credencial ativa, então seus limites de uso e cobrança se aplicam. Gateways que passam esse tráfego para Anthropic devem encaminhar a capacidade OAuth em `anthropic-beta`; consulte a [referência de cabeçalhos de solicitação](/docs/pt/llm-gateway-protocol#request-headers).

55 

56<h2 id="related-pages">

57 Páginas relacionadas

58</h2>

59 

60* [Visão geral de gateway](/docs/pt/gateways): como um gateway funciona e como escolher entre gateway de aplicativos Claude e outro produto

61* [Gateway de aplicativos Claude](/docs/pt/claude-apps-gateway): gateway auto-hospedado da Anthropic com entrada SSO e telemetria OTLP

62* [Conectar Claude Code a um gateway LLM](/docs/pt/llm-gateway-connect): defina a URL base e credencial em sua própria máquina, com configuração por superfície e uma tabela de solução de problemas

63* [Implantar um gateway LLM para sua organização](/docs/pt/llm-gateway-rollout): a lista de verificação do administrador para implantar um gateway, emitir credenciais de desenvolvedor e distribuir configurações gerenciadas

64* [Referência de protocolo de gateway](/docs/pt/llm-gateway-protocol): o que Claude Code envia a um gateway, para operadores configurando um, abrangendo endpoints, cabeçalhos para encaminhar e passagem de recursos

20 20 

21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="Quatro turnos mostrados como barras horizontais crescentes. A solicitação de cada turno contém tudo do turno anterior mais a troca mais recente anexada ao final. Nos turnos dois e três, o prefixo inalterado é lido do cache e apenas a nova troca é processada. No turno quatro, o prompt do sistema mudou, então o prefixo não corresponde mais e toda a solicitação é reprocessada e escrita." width="720" height="454" data-path="images/prompt-caching-prefix.svg" />21<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=f2e8f0b8298a50305fe428ca3f1d1594" className="dark:hidden" alt="Quatro turnos mostrados como barras horizontais crescentes. A solicitação de cada turno contém tudo do turno anterior mais a troca mais recente anexada ao final. Nos turnos dois e três, o prefixo inalterado é lido do cache e apenas a nova troca é processada. No turno quatro, o prompt do sistema mudou, então o prefixo não corresponde mais e toda a solicitação é reprocessada e escrita." width="720" height="454" data-path="images/prompt-caching-prefix.svg" />

22 22 

23<img src="https://mintcdn.com/claude-code/VbDJw--l6T9a9Wvm/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=VbDJw--l6T9a9Wvm&q=85&s=7434a04e08187edd26ec6c3dd332f624" className="hidden dark:block" alt="Quatro turnos mostrados como barras horizontais crescentes. A solicitação de cada turno contém tudo do turno anterior mais a troca mais recente anexada ao final. Nos turnos dois e três, o prefixo inalterado é lido do cache e apenas a nova troca é processada. No turno quatro, o prompt do sistema mudou, então o prefixo não corresponde mais e toda a solicitação é reprocessada e escrita." width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/prompt-caching-prefix-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=297dc1c639f0915cae858d0c4b6f3be5" className="hidden dark:block" alt="Quatro turnos mostrados como barras horizontais crescentes. A solicitação de cada turno contém tudo do turno anterior mais a troca mais recente anexada ao final. Nos turnos dois e três, o prefixo inalterado é lido do cache e apenas a nova troca é processada. No turno quatro, o prompt do sistema mudou, então o prefixo não corresponde mais e toda a solicitação é reprocessada e escrita." width="720" height="454" data-path="images/prompt-caching-prefix-dark.svg" />

24 24 

25Para aproveitar ao máximo a correspondência de prefixo, Claude Code ordena cada solicitação para que o conteúdo que raramente muda entre turnos venha primeiro:25Para aproveitar ao máximo a correspondência de prefixo, Claude Code ordena cada solicitação para que o conteúdo que raramente muda entre turnos venha primeiro:

26 26 

32 32 

33Uma mudança na camada de conversa deixa o prompt do sistema e o contexto do projeto em cache. Uma mudança no prompt do sistema invalida tudo, porque todo o conteúdo posterior agora fica atrás de um prefixo diferente. A terceira coluna fornece gatilhos comuns em vez de uma lista exaustiva, e as seções abaixo cobrem o conjunto completo, incluindo conteúdo como estilo de saída que é fixado no início da sessão.33Uma mudança na camada de conversa deixa o prompt do sistema e o contexto do projeto em cache. Uma mudança no prompt do sistema invalida tudo, porque todo o conteúdo posterior agora fica atrás de um prefixo diferente. A terceira coluna fornece gatilhos comuns em vez de uma lista exaustiva, e as seções abaixo cobrem o conjunto completo, incluindo conteúdo como estilo de saída que é fixado no início da sessão.

34 34 

35A regra de correspondência de prefixo explica a maioria dos comportamentos nesta página. [Plan Mode](/pt/permission-modes#analyze-before-you-edit-with-plan-mode) e [carregamento de skills](/pt/skills), por exemplo, anexam suas instruções como mensagens de conversa, então o prefixo em cache permanece intacto.35A regra de correspondência de prefixo explica a maioria dos comportamentos nesta página. [Plan Mode](/docs/pt/permission-modes#analyze-before-you-edit-with-plan-mode) e [carregamento de skills](/docs/pt/skills), por exemplo, anexam suas instruções como mensagens de conversa, então o prefixo em cache permanece intacto.

36 36 

37Duas configurações não fazem parte do texto do prompt, então não aparecem na tabela de camadas, mas ambas fazem parte da chave de cache:37Duas configurações não fazem parte do texto do prompt, então não aparecem na tabela de camadas, mas ambas fazem parte da chave de cache:

38 38 

49 49 

50O caching acontece no lado do servidor, na infraestrutura que serve seu modelo. Onde fica depende de como você se autentica:50O caching acontece no lado do servidor, na infraestrutura que serve seu modelo. Onde fica depende de como você se autentica:

51 51 

52* **Chave de API, assinatura Claude ou [Claude Platform on AWS](/pt/claude-platform-on-aws)**: o cache reside na infraestrutura da Anthropic, acessado através da [Claude API](https://platform.claude.com/docs)52* **Chave de API, assinatura Claude ou [Claude Platform on AWS](/docs/pt/claude-platform-on-aws)**: o cache reside na infraestrutura da Anthropic, acessado através da [Claude API](https://platform.claude.com/docs)

53* **Amazon Bedrock ou Google Cloud's Agent Platform**: o cache reside na infraestrutura de serviço do seu provedor de nuvem53* **Amazon Bedrock ou Google Cloud's Agent Platform**: o cache reside na infraestrutura de serviço do seu provedor de nuvem

54* **Microsoft Foundry**: as solicitações são roteadas para a infraestrutura da Anthropic54* **Microsoft Foundry**: as solicitações são roteadas para a infraestrutura da Anthropic

55* **`ANTHROPIC_BASE_URL` personalizado ou [LLM gateway](/pt/llm-gateway)**: o cache reside onde suas solicitações são encaminhadas, e se o caching funciona depende do gateway55* **`ANTHROPIC_BASE_URL` personalizado ou [LLM gateway](/docs/pt/llm-gateway)**: o cache reside onde suas solicitações são encaminhadas, e se o caching funciona depende do gateway

56 56 

57Para o que cada provedor armazena e processa, veja [uso de dados](/pt/data-usage). Onde quer que o cache resida, as entradas expiram após um período de inatividade, e [Cache lifetime](#cache-lifetime) abaixo cobre o TTL e como estendê-lo.57Para o que cada provedor armazena e processa, veja [uso de dados](/docs/pt/data-usage). Onde quer que o cache resida, as entradas expiram após um período de inatividade, e [Cache lifetime](#cache-lifetime) abaixo cobre o TTL e como estendê-lo.

58 58 

59<h2 id="actions-that-invalidate-the-cache">59<h2 id="actions-that-invalidate-the-cache">

60 Ações que invalidam o cache60 Ações que invalidam o cache

75 Trocar modelos75 Trocar modelos

76</h3>76</h3>

77 77 

78Cada modelo tem seu próprio cache. Trocar com [`/model`](/pt/model-config#setting-your-model) significa que a próxima solicitação lê todo o histórico de conversa sem acertos de cache, mesmo que o conteúdo seja idêntico.78Cada modelo tem seu próprio cache. Trocar com [`/model`](/docs/pt/model-config#setting-your-model) significa que a próxima solicitação lê todo o histórico de conversa sem acertos de cache, mesmo que o conteúdo seja idêntico.

79 79 

80A [configuração de modelo `opusplan`](/pt/model-config#opusplan-model-setting) resolve para Opus durante o modo de plano e Sonnet durante a execução, então cada alternância de modo de plano é uma mudança de modelo e inicia um cache novo.80A [configuração de modelo `opusplan`](/docs/pt/model-config#opusplan-model-setting) resolve para Opus durante o modo de plano e Sonnet durante a execução, então cada alternância de modo de plano é uma mudança de modelo e inicia um cache novo.

81 81 

82[Fallback automático de modelo](/pt/model-config#automatic-model-fallback) no Fable 5 também é uma mudança de modelo. Quando um classificador de segurança sinaliza uma solicitação, Claude Code a executa novamente no modelo Opus padrão e a sessão continua lá.82[Fallback automático de modelo](/docs/pt/model-config#automatic-model-fallback) no Fable 5 também é uma mudança de modelo. Quando um classificador de segurança sinaliza uma solicitação, Claude Code a executa novamente no modelo Opus padrão e a sessão continua lá.

83 83 

84<h3 id="changing-effort-level">84<h3 id="changing-effort-level">

85 Alterar nível de esforço85 Alterar nível de esforço

86</h3>86</h3>

87 87 

88O cache é codificado por [nível de esforço](/pt/model-config#adjust-effort-level) bem como modelo, então trocar com `/effort` significa que a próxima solicitação lê todo o histórico de conversa sem acertos de cache. Uma vez que uma conversa começou, Claude Code mostra um diálogo de confirmação antes de aplicar uma mudança de esforço que invalidaria o cache. Uma mudança que resolve para o mesmo nível já em vigor, como definir o padrão do modelo explicitamente, pula o diálogo e mantém o cache.88O cache é codificado por [nível de esforço](/docs/pt/model-config#adjust-effort-level) bem como modelo, então trocar com `/effort` significa que a próxima solicitação lê todo o histórico de conversa sem acertos de cache. Uma vez que uma conversa começou, Claude Code mostra um diálogo de confirmação antes de aplicar uma mudança de esforço que invalidaria o cache. Uma mudança que resolve para o mesmo nível já em vigor, como definir o padrão do modelo explicitamente, pula o diálogo e mantém o cache.

89 89 

90<h3 id="turning-on-fast-mode">90<h3 id="turning-on-fast-mode">

91 Ativar modo rápido91 Ativar modo rápido

92</h3>92</h3>

93 93 

94Ativar [modo rápido](/pt/fast-mode) adiciona um cabeçalho de solicitação que faz parte da chave de cache, então a próxima solicitação lê todo o histórico de conversa sem acertos de cache. Esses tokens de entrada sem cache são cobrados com [taxas de modo rápido](/pt/fast-mode#understand-the-cost-tradeoff), e é por isso que ativá-lo no início de uma sessão custa menos do que ativá-lo profundamente em uma longa. Ativar modo rápido a partir de um modelo que não é Opus também [muda seu modelo](#switching-models), o que inicia um cache novo por conta própria.94Ativar [modo rápido](/docs/pt/fast-mode) adiciona um cabeçalho de solicitação que faz parte da chave de cache, então a próxima solicitação lê todo o histórico de conversa sem acertos de cache. Esses tokens de entrada sem cache são cobrados com [taxas de modo rápido](/docs/pt/fast-mode#understand-the-cost-tradeoff), e é por isso que ativá-lo no início de uma sessão custa menos do que ativá-lo profundamente em uma longa. Ativar modo rápido a partir de um modelo que não é Opus também [muda seu modelo](#switching-models), o que inicia um cache novo por conta própria.

95 95 

96O custo se aplica uma vez por conversa. Após o primeiro turno de modo rápido, Claude Code continua enviando o cabeçalho e varia apenas a configuração de velocidade da solicitação, que não faz parte da chave de cache. Desativar modo rápido, o [fallback automático para velocidade padrão](/pt/fast-mode#handle-rate-limits) após um limite de taxa e ativá-lo novamente mais tarde mantêm o cache. `/clear` e `/compact` redefinem isso, já que reconstruem o cache nesses pontos de qualquer forma.96O custo se aplica uma vez por conversa. Após o primeiro turno de modo rápido, Claude Code continua enviando o cabeçalho e varia apenas a configuração de velocidade da solicitação, que não faz parte da chave de cache. Desativar modo rápido, o [fallback automático para velocidade padrão](/docs/pt/fast-mode#handle-rate-limits) após um limite de taxa e ativá-lo novamente mais tarde mantêm o cache. `/clear` e `/compact` redefinem isso, já que reconstruem o cache nesses pontos de qualquer forma.

97 97 

98<h3 id="connecting-or-disconnecting-an-mcp-server">98<h3 id="connecting-or-disconnecting-an-mcp-server">

99 Conectar ou desconectar um servidor MCP99 Conectar ou desconectar um servidor MCP

100</h3>100</h3>

101 101 

102As definições de ferramentas ficam na camada de prompt do sistema, então o cache se invalida quando o conjunto de definições de ferramentas na solicitação muda entre turnos. Alternar a [ferramenta advisor](/pt/advisor) é uma exceção: sua definição fica após o ponto de quebra do cache, então ativar ou desativar `/advisor` mantém o prefixo em cache intacto. Se uma mudança de [servidor MCP](/pt/mcp) faz isso depende se suas ferramentas são adiadas por [busca de ferramentas](/pt/mcp#scale-with-mcp-tool-search) ou carregadas no prefixo:102As definições de ferramentas ficam na camada de prompt do sistema, então o cache se invalida quando o conjunto de definições de ferramentas na solicitação muda entre turnos. Alternar a [ferramenta advisor](/docs/pt/advisor) é uma exceção: sua definição fica após o ponto de quebra do cache, então ativar ou desativar `/advisor` mantém o prefixo em cache intacto. Se uma mudança de [servidor MCP](/docs/pt/mcp) faz isso depende se suas ferramentas são adiadas por [busca de ferramentas](/docs/pt/mcp#scale-with-mcp-tool-search) ou carregadas no prefixo:

103 103 

104* **Ferramentas adiadas**, o padrão em modelos suportados: um servidor se conectando, desconectando ou alterando sua lista de ferramentas apenas anexa novo conteúdo e não perturba nada já armazenado em cache.104* **Ferramentas adiadas**, o padrão em modelos suportados: um servidor se conectando, desconectando ou alterando sua lista de ferramentas apenas anexa novo conteúdo e não perturba nada já armazenado em cache.

105* **Ferramentas carregadas no prefixo**: qualquer mudança nelas invalida o cache. Isso acontece quando [a busca de ferramentas não está disponível ou está desativada](/pt/mcp#configure-tool-search), como em modelos Haiku, no Vertex AI ou com um gateway `ANTHROPIC_BASE_URL` customizado. Também acontece para um servidor ou ferramenta marcada [`alwaysLoad`](/pt/mcp#exempt-a-server-from-deferral) e para definições mantidas na frente por [carregamento baseado em limite](/pt/mcp#configure-tool-search).105* **Ferramentas carregadas no prefixo**: qualquer mudança nelas invalida o cache. Isso acontece quando [a busca de ferramentas não está disponível ou está desativada](/docs/pt/mcp#configure-tool-search), como em modelos Haiku, no Vertex AI ou com um gateway `ANTHROPIC_BASE_URL` customizado. Também acontece para um servidor ou ferramenta marcada [`alwaysLoad`](/docs/pt/mcp#exempt-a-server-from-deferral) e para definições mantidas na frente por [carregamento baseado em limite](/docs/pt/mcp#configure-tool-search).

106 106 

107Quando as ferramentas carregam no prefixo, a causa mais comum de uma invalidação é um servidor se conectando ou desconectando no meio da sessão, o que pode acontecer sem nenhuma ação da sua parte: o processo de um servidor stdio sai, uma sessão HTTP expira ou um servidor [se reconecta automaticamente após uma falha transitória](/pt/mcp#automatic-reconnection). Um servidor conectado também pode enviar uma [atualização de ferramenta dinâmica](/pt/mcp#dynamic-tool-updates) que muda sua lista de ferramentas.107Quando as ferramentas carregam no prefixo, a causa mais comum de uma invalidação é um servidor se conectando ou desconectando no meio da sessão, o que pode acontecer sem nenhuma ação da sua parte: o processo de um servidor stdio sai, uma sessão HTTP expira ou um servidor [se reconecta automaticamente após uma falha transitória](/docs/pt/mcp#automatic-reconnection). Um servidor conectado também pode enviar uma [atualização de ferramenta dinâmica](/docs/pt/mcp#dynamic-tool-updates) que muda sua lista de ferramentas.

108 108 

109Editar sua configuração de MCP não muda o cache por si só. A nova configuração entra em vigor apenas após uma reinicialização, que é quando o servidor se conecta ou desconecta.109Editar sua configuração de MCP não muda o cache por si só. A nova configuração entra em vigor apenas após uma reinicialização, que é quando o servidor se conecta ou desconecta.

110 110 

112 Ativar ou desativar um plugin112 Ativar ou desativar um plugin

113</h3>113</h3>

114 114 

115[Plugins](/pt/plugins) agrupam vários tipos de componentes, e o custo de uma mudança depende de quais componentes o plugin fornece. Skills, comandos, agentes, hooks, servidores LSP, monitores e temas nunca invalidam o cache: qualquer coisa que eles adicionem à solicitação é anexada após a conversa existente, então a próxima solicitação paga pelo novo conteúdo mas ainda lê tudo antes dele do cache.115[Plugins](/docs/pt/plugins) agrupam vários tipos de componentes, e o custo de uma mudança depende de quais componentes o plugin fornece. Skills, comandos, agentes, hooks, servidores LSP, monitores e temas nunca invalidam o cache: qualquer coisa que eles adicionem à solicitação é anexada após a conversa existente, então a próxima solicitação paga pelo novo conteúdo mas ainda lê tudo antes dele do cache.

116 116 

117A exceção é um plugin que fornece [servidores MCP](/pt/plugins-reference#mcp-servers). Ativar ou desativar um segue as mesmas regras que [conectar ou desconectar um servidor MCP](#connecting-or-disconnecting-an-mcp-server): o cache sobrevive quando as ferramentas do servidor são adiadas, e a próxima solicitação relê toda a conversa quando elas carregam no prefixo.117A exceção é um plugin que fornece [servidores MCP](/docs/pt/plugins-reference#mcp-servers). Ativar ou desativar um segue as mesmas regras que [conectar ou desconectar um servidor MCP](#connecting-or-disconnecting-an-mcp-server): o cache sobrevive quando as ferramentas do servidor são adiadas, e a próxima solicitação relê toda a conversa quando elas carregam no prefixo.

118 118 

119As mudanças de plugin se aplicam quando você executa [`/reload-plugins`](/pt/discover-plugins#apply-plugin-changes-without-restarting) ou inicia uma nova sessão. O custo, seja anúncios anexados ou uma releitura completa, aparece no primeiro turno após o recarregamento, não quando você executa `/plugin install`, `/plugin enable` ou `/plugin disable`. {/* min-version: 2.1.163 */}A partir da v2.1.163, quando um recarregamento acionaria a releitura completa, `/reload-plugins` mostra um aviso e não aplica o recarregamento. Passe `--force` para aplicar mesmo assim.119As mudanças de plugin se aplicam quando você executa [`/reload-plugins`](/docs/pt/discover-plugins#apply-plugin-changes-without-restarting) ou inicia uma nova sessão. O custo, seja anúncios anexados ou uma releitura completa, aparece no primeiro turno após o recarregamento, não quando você executa `/plugin install`, `/plugin enable` ou `/plugin disable`. {/* min-version: 2.1.163 */}A partir da v2.1.163, quando um recarregamento acionaria a releitura completa, `/reload-plugins` mostra um aviso e não aplica o recarregamento. Passe `--force` para aplicar mesmo assim.

120 120 

121Desativar um plugin que você ativou anteriormente na sessão restaura a forma de solicitação anterior. Se esse prefixo ainda estiver dentro de seu [tempo de vida do cache](#cache-lifetime), a próxima solicitação lê a entrada de cache mais antiga em vez de reconstruir.121Desativar um plugin que você ativou anteriormente na sessão restaura a forma de solicitação anterior. Se esse prefixo ainda estiver dentro de seu [tempo de vida do cache](#cache-lifetime), a próxima solicitação lê a entrada de cache mais antiga em vez de reconstruir.

122 122 

124 Negar uma ferramenta inteira124 Negar uma ferramenta inteira

125</h3>125</h3>

126 126 

127Adicionar um nome de ferramenta simples como `Bash` ou `WebFetch` como uma [regra de negação](/pt/permissions#manage-permissions) remove essa ferramenta do contexto de Claude completamente. As definições de ferramentas integradas carregam na camada de prompt do sistema, então adicionar ou remover uma dessas regras no meio da sessão invalida o cache. A mudança entra em vigor no próximo turno, quer você a adicione através de `/permissions` ou [editando um arquivo de configurações diretamente](/pt/settings#when-edits-take-effect).127Adicionar um nome de ferramenta simples como `Bash` ou `WebFetch` como uma [regra de negação](/docs/pt/permissions#manage-permissions) remove essa ferramenta do contexto de Claude completamente. As definições de ferramentas integradas carregam na camada de prompt do sistema, então adicionar ou remover uma dessas regras no meio da sessão invalida o cache. A mudança entra em vigor no próximo turno, quer você a adicione através de `/permissions` ou [editando um arquivo de configurações diretamente](/docs/pt/settings#when-edits-take-effect).

128 128 

129Apenas uma regra de negação que corresponde na posição do nome da ferramenta tem esse efeito: um nome de ferramenta simples, a forma equivalente `Bash(*)`, ou um [glob de nome de ferramenta](/pt/permissions#tool-name-wildcards) como `"*"`. Um glob que corresponde apenas a ferramentas MCP, como `"mcp__*"`, remove essas ferramentas da mesma forma mas deixa o cache intacto quando as ferramentas correspondidas são [adiadas](#connecting-or-disconnecting-an-mcp-server), o padrão, já que definições adiadas nunca estiveram no prefixo em cache. Regras de negação com escopo como `Bash(rm *)` e todas as regras de permissão e pergunta não mudam quais ferramentas Claude vê. Claude Code as verifica quando Claude tenta fazer uma chamada, deixando o prefixo intacto.129Apenas uma regra de negação que corresponde na posição do nome da ferramenta tem esse efeito: um nome de ferramenta simples, a forma equivalente `Bash(*)`, ou um [glob de nome de ferramenta](/docs/pt/permissions#tool-name-wildcards) como `"*"`. Um glob que corresponde apenas a ferramentas MCP, como `"mcp__*"`, remove essas ferramentas da mesma forma mas deixa o cache intacto quando as ferramentas correspondidas são [adiadas](#connecting-or-disconnecting-an-mcp-server), o padrão, já que definições adiadas nunca estiveram no prefixo em cache. Regras de negação com escopo como `Bash(rm *)` e todas as regras de permissão e pergunta não mudam quais ferramentas Claude vê. Claude Code as verifica quando Claude tenta fazer uma chamada, deixando o prefixo intacto.

130 130 

131<h3 id="compacting-the-conversation">131<h3 id="compacting-the-conversation">

132 Compactar a conversa132 Compactar a conversa

133</h3>133</h3>

134 134 

135[Compactação](/pt/context-window#what-survives-compaction) substitui seu histórico de mensagens por um resumo. Por design, isso invalida a camada de conversa, já que a próxima solicitação tem um histórico novo e mais curto que não compartilha um prefixo com o antigo. Claude Code reutiliza a camada de prompt do sistema e recarrega o contexto do projeto do disco, que acerta o cache apenas se CLAUDE.md e memória não mudaram desde o início da sessão.135[Compactação](/docs/pt/context-window#what-survives-compaction) substitui seu histórico de mensagens por um resumo. Por design, isso invalida a camada de conversa, já que a próxima solicitação tem um histórico novo e mais curto que não compartilha um prefixo com o antigo. Claude Code reutiliza a camada de prompt do sistema e recarrega o contexto do projeto do disco, que acerta o cache apenas se CLAUDE.md e memória não mudaram desde o início da sessão.

136 136 

137Para produzir o resumo, Claude Code envia uma solicitação única com o mesmo prompt do sistema, ferramentas e histórico que sua conversa, mais uma instrução de resumo anexada como uma mensagem de usuário final. Como compartilha seu prefixo, essa solicitação lê o cache existente em vez de reprocessar o histórico completo. A maior parte do tempo de compactação vai para gerar o resumo, não para uma perda de cache. O turno que se segue reconstrói o cache de conversa apenas para o resumo muito mais curto, então o turno pós-compactação não é a parte lenta.137Para produzir o resumo, Claude Code envia uma solicitação única com o mesmo prompt do sistema, ferramentas e histórico que sua conversa, mais uma instrução de resumo anexada como uma mensagem de usuário final. Como compartilha seu prefixo, essa solicitação lê o cache existente em vez de reprocessar o histórico completo. A maior parte do tempo de compactação vai para gerar o resumo, não para uma perda de cache. O turno que se segue reconstrói o cache de conversa apenas para o resumo muito mais curto, então o turno pós-compactação não é a parte lenta.

138 138 

144 Atualizar Claude Code144 Atualizar Claude Code

145</h3>145</h3>

146 146 

147Uma nova versão de Claude Code normalmente atualiza o prompt do sistema ou definições de ferramentas, então a primeira solicitação após uma atualização reconstrói o cache do início. [Auto-update](/pt/setup#auto-updates) baixa novas versões em segundo plano, mas as aplica no próximo lançamento, nunca no meio da sessão, então você vê isso como um primeiro turno sem cache após reiniciar em vez de uma surpresa durante uma sessão. Defina `DISABLE_AUTOUPDATER=1` para controlar quando as atualizações se aplicam.147Uma nova versão de Claude Code normalmente atualiza o prompt do sistema ou definições de ferramentas, então a primeira solicitação após uma atualização reconstrói o cache do início. [Auto-update](/docs/pt/setup#auto-updates) baixa novas versões em segundo plano, mas as aplica no próximo lançamento, nunca no meio da sessão, então você vê isso como um primeiro turno sem cache após reiniciar em vez de uma surpresa durante uma sessão. Defina `DISABLE_AUTOUPDATER=1` para controlar quando as atualizações se aplicam.

148 148 

149<Note>149<Note>

150 [Retomar uma sessão](/pt/sessions#resume-a-session) após uma atualização reprocessa todo o histórico de conversa sem acertos de cache, já que o histórico agora fica atrás de um prompt do sistema diferente. O custo escala com o comprimento da conversa retomada, então o primeiro turno de volta para uma sessão longa pode ser a solicitação mais cara que você envia.150 [Retomar uma sessão](/docs/pt/sessions#resume-a-session) após uma atualização reprocessa todo o histórico de conversa sem acertos de cache, já que o histórico agora fica atrás de um prompt do sistema diferente. O custo escala com o comprimento da conversa retomada, então o primeiro turno de volta para uma sessão longa pode ser a solicitação mais cara que você envia.

151</Note>151</Note>

152 152 

153<h2 id="actions-that-keep-the-cache">153<h2 id="actions-that-keep-the-cache">

177 177 

178Seus arquivos CLAUDE.md de raiz de projeto e nível de usuário são lidos uma vez no início da sessão e mantidos na memória. Editá-los no meio da sessão não invalida o cache, mas a edição também não se aplica. Claude continua trabalhando com a versão que foi carregada no início da sessão. O novo conteúdo carrega no próximo `/clear`, `/compact` ou reinicialização.178Seus arquivos CLAUDE.md de raiz de projeto e nível de usuário são lidos uma vez no início da sessão e mantidos na memória. Editá-los no meio da sessão não invalida o cache, mas a edição também não se aplica. Claude continua trabalhando com a versão que foi carregada no início da sessão. O novo conteúdo carrega no próximo `/clear`, `/compact` ou reinicialização.

179 179 

180[Arquivos CLAUDE.md aninhados em subdiretórios](/pt/memory) e [regras com frontmatter `paths:`](/pt/memory#path-specific-rules) carregam depois, quando Claude primeiro lê um arquivo correspondente. Editar um antes de carregar tem efeito. Depois de carregar, o conteúdo faz parte do histórico de conversa, então uma edição no meio da sessão não muda retroativamente.180[Arquivos CLAUDE.md aninhados em subdiretórios](/docs/pt/memory) e [regras com frontmatter `paths:`](/docs/pt/memory#path-specific-rules) carregam depois, quando Claude primeiro lê um arquivo correspondente. Editar um antes de carregar tem efeito. Depois de carregar, o conteúdo faz parte do histórico de conversa, então uma edição no meio da sessão não muda retroativamente.

181 181 

182<h3 id="changing-output-style">182<h3 id="changing-output-style">

183 Alterar estilo de saída183 Alterar estilo de saída

184</h3>184</h3>

185 185 

186[Estilo de saída](/pt/output-styles) faz parte do prompt do sistema, que Claude Code lê uma vez no início da sessão. Alterá-lo via `/config` ou a configuração `outputStyle` no meio da sessão não invalida o cache, mas a mudança também não se aplica. Claude continua usando o estilo que foi carregado no início da sessão. O novo estilo carrega no próximo `/clear` ou reinicialização.186[Estilo de saída](/docs/pt/output-styles) faz parte do prompt do sistema, que Claude Code lê uma vez no início da sessão. Alterá-lo via `/config` ou a configuração `outputStyle` no meio da sessão não invalida o cache, mas a mudança também não se aplica. Claude continua usando o estilo que foi carregado no início da sessão. O novo estilo carrega no próximo `/clear` ou reinicialização.

187 187 

188<h3 id="changing-permission-mode">188<h3 id="changing-permission-mode">

189 Alterar modo de permissão189 Alterar modo de permissão

190</h3>190</h3>

191 191 

192Alternar entre [modos de permissão](/pt/permission-modes), como de padrão para aceitar edições, não muda o prompt do sistema ou definições de ferramentas, então mudanças de modo são seguras para cache. A exceção é o modo de plano com a configuração de modelo [`opusplan`](/pt/model-config#opusplan-model-setting), que alterna o modelo entre Opus e Sonnet conforme você entra ou sai do modo de plano. Isso torna a alternância de modo uma [mudança de modelo](#switching-models).192Alternar entre [modos de permissão](/docs/pt/permission-modes), como de padrão para aceitar edições, não muda o prompt do sistema ou definições de ferramentas, então mudanças de modo são seguras para cache. A exceção é o modo de plano com a configuração de modelo [`opusplan`](/docs/pt/model-config#opusplan-model-setting), que alterna o modelo entre Opus e Sonnet conforme você entra ou sai do modo de plano. Isso torna a alternância de modo uma [mudança de modelo](#switching-models).

193 193 

194<h3 id="invoking-skills-and-commands">194<h3 id="invoking-skills-and-commands">

195 Invocar skills e comandos195 Invocar skills e comandos

196</h3>196</h3>

197 197 

198[Skills](/pt/skills) e [comandos](/pt/commands) injetam suas instruções como mensagens de usuário no ponto de invocação. Nada anterior na conversa muda.198[Skills](/docs/pt/skills) e [comandos](/docs/pt/commands) injetam suas instruções como mensagens de usuário no ponto de invocação. Nada anterior na conversa muda.

199 199 

200<h3 id="running-/recap">200<h3 id="running-/recap">

201 Executar `/recap`201 Executar `/recap`

202</h3>202</h3>

203 203 

204[`/recap`](/pt/interactive-mode#session-recap) gera um resumo para exibição em seu terminal. Ao contrário de `/compact`, ele anexa o resumo como saída de comando em vez de substituir seu histórico de mensagens, então o prefixo em cache permanece intacto.204[`/recap`](/docs/pt/interactive-mode#session-recap) gera um resumo para exibição em seu terminal. Ao contrário de `/compact`, ele anexa o resumo como saída de comando em vez de substituir seu histórico de mensagens, então o prefixo em cache permanece intacto.

205 205 

206<h3 id="rewinding-the-conversation">206<h3 id="rewinding-the-conversation">

207 Rewind da conversa207 Rewind da conversa

208</h3>208</h3>

209 209 

210[`/rewind`](/pt/checkpointing) trunca sua conversa de volta para um turno anterior. O histórico restante é o mesmo conteúdo do qual o cache foi construído naquele ponto, e as camadas de prompt do sistema e contexto do projeto não mudam, então a próxima solicitação acerta a entrada de cache anterior. Cada turno desde então leu através desse prefixo, que manteve a entrada aquecida mesmo se o turno original foi há mais tempo do que o TTL.210[`/rewind`](/docs/pt/checkpointing) trunca sua conversa de volta para um turno anterior. O histórico restante é o mesmo conteúdo do qual o cache foi construído naquele ponto, e as camadas de prompt do sistema e contexto do projeto não mudam, então a próxima solicitação acerta a entrada de cache anterior. Cada turno desde então leu através desse prefixo, que manteve a entrada aquecida mesmo se o turno original foi há mais tempo do que o TTL.

211 211 

212Restaurar checkpoints de arquivo junto com a conversa não tem efeito separado no cache. O conteúdo do arquivo entra em contexto apenas quando Claude o lê, o mesmo que [editar arquivos em seu repositório](#editing-files-in-your-repository).212Restaurar checkpoints de arquivo junto com a conversa não tem efeito separado no cache. O conteúdo do arquivo entra em contexto apenas quando Claude o lê, o mesmo que [editar arquivos em seu repositório](#editing-files-in-your-repository).

213 213 

239 Substituir o TTL239 Substituir o TTL

240</h3>240</h3>

241 241 

242Defina `FORCE_PROMPT_CACHING_5M=1` para forçar o TTL de cinco minutos independentemente da autenticação. Isso é útil quando você está depurando o comportamento do cache, comparando os dois TTLs ou substituindo um `ENABLE_PROMPT_CACHING_1H` definido em [configurações gerenciadas](/pt/settings#settings-files).242Defina `FORCE_PROMPT_CACHING_5M=1` para forçar o TTL de cinco minutos independentemente da autenticação. Isso é útil quando você está depurando o comportamento do cache, comparando os dois TTLs ou substituindo um `ENABLE_PROMPT_CACHING_1H` definido em [configurações gerenciadas](/docs/pt/settings#settings-files).

243 243 

244<h2 id="cache-scope">244<h2 id="cache-scope">

245 Escopo do cache245 Escopo do cache

249 249 

250Sessões que você executa em paralelo no mesmo diretório constroem prefixos correspondentes e leem o cache uma da outra. Sessões sequenciais compartilham o prefixo apenas quando o snapshot de status git na inicialização corresponde, já que o prompt do sistema também captura branch e commits recentes.250Sessões que você executa em paralelo no mesmo diretório constroem prefixos correspondentes e leem o cache uma da outra. Sessões sequenciais compartilham o prefixo apenas quando o snapshot de status git na inicialização corresponde, já que o prompt do sistema também captura branch e commits recentes.

251 251 

252O cache de API subjacente é mais amplo. Os caches são isolados entre organizações e, em alguns provedores, [entre workspaces dentro de uma organização](https://platform.claude.com/docs/pt/build-with-claude/prompt-caching#cache-storage-and-sharing). Dentro desses limites, quaisquer duas solicitações com o mesmo modelo e prefixo leem o mesmo cache. Para chamadores do Agent SDK executando frotas de processos automatizados, veja [melhorar prompt caching entre usuários e máquinas](/pt/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) para suprimir as seções por máquina do prompt do sistema e compartilhar o cache entre máquinas.252O cache de API subjacente é mais amplo. Os caches são isolados entre organizações e, em alguns provedores, [entre workspaces dentro de uma organização](https://platform.claude.com/docs/pt/build-with-claude/prompt-caching#cache-storage-and-sharing). Dentro desses limites, quaisquer duas solicitações com o mesmo modelo e prefixo leem o mesmo cache. Para chamadores do Agent SDK executando frotas de processos automatizados, veja [melhorar prompt caching entre usuários e máquinas](/docs/pt/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) para suprimir as seções por máquina do prompt do sistema e compartilhar o cache entre máquinas.

253 253 

254<h2 id="check-cache-performance">254<h2 id="check-cache-performance">

255 Verificar desempenho do cache255 Verificar desempenho do cache

256</h2>256</h2>

257 257 

258O desempenho do cache aparece como duas contagens de tokens que a API relata em cada resposta. A forma mais direta de observá-los ao vivo é um [script de statusline](/pt/statusline) que lê o objeto `current_usage`:258O desempenho do cache aparece como duas contagens de tokens que a API relata em cada resposta. A forma mais direta de observá-los ao vivo é um [script de statusline](/docs/pt/statusline) que lê o objeto `current_usage`:

259 259 

260| Campo | Significado |260| Campo | Significado |

261| ----------------------------- | ----------------------------------------------------------------------------------------------- |261| ----------------------------- | ----------------------------------------------------------------------------------------------- |

264 264 

265Uma alta proporção de leitura para criação significa que o caching está funcionando bem. Se a criação permanecer alta turno após turno, algo está mudando em seu prefixo. A seção [ações que invalidam o cache](#actions-that-invalidate-the-cache) lista as causas usuais.265Uma alta proporção de leitura para criação significa que o caching está funcionando bem. Se a criação permanecer alta turno após turno, algo está mudando em seu prefixo. A seção [ações que invalidam o cache](#actions-that-invalidate-the-cache) lista as causas usuais.

266 266 

267Para visibilidade em toda uma organização, o exportador OpenTelemetry relata tokens de leitura e criação de cache por usuário e sessão. Veja [Monitorar uso](/pt/monitoring-usage) para a referência de métrica e atributo de evento.267Para visibilidade em toda uma organização, o exportador OpenTelemetry relata tokens de leitura e criação de cache por usuário e sessão. Veja [Monitorar uso](/docs/pt/monitoring-usage) para a referência de métrica e atributo de evento.

268 268 

269<h2 id="subagents-and-the-cache">269<h2 id="subagents-and-the-cache">

270 Subagents e o cache270 Subagents e o cache

271</h2>271</h2>

272 272 

273Um [subagent](/pt/sub-agents) inicia sua própria conversa com seu próprio prompt do sistema e conjunto de ferramentas, separado do pai. Ele constrói seu próprio cache, começando sem acertos de cache em sua primeira chamada e aquecendo através de seus próprios turnos. Subagents usam o TTL de cinco minutos mesmo em uma assinatura, já que o TTL automático de uma hora se aplica à conversa principal.273Um [subagent](/docs/pt/sub-agents) inicia sua própria conversa com seu próprio prompt do sistema e conjunto de ferramentas, separado do pai. Ele constrói seu próprio cache, começando sem acertos de cache em sua primeira chamada e aquecendo através de seus próprios turnos. Subagents usam o TTL de cinco minutos mesmo em uma assinatura, já que o TTL automático de uma hora se aplica à conversa principal.

274 274 

275O cache do pai não é afetado. Do lado do pai, a chamada e resultado do subagent se anexam à conversa, deixando o prefixo do pai intacto.275O cache do pai não é afetado. Do lado do pai, a chamada e resultado do subagent se anexam à conversa, deixando o prefixo do pai intacto.

276 276 

277Um [fork](/pt/sub-agents#fork-the-current-conversation), por contraste, herda o prompt do sistema, ferramentas e histórico de conversa do pai exatamente, então sua primeira solicitação lê o cache do pai. A chamada de resumo de compactação descrita em [Compactar a conversa](#compacting-the-conversation) usa a mesma abordagem de compartilhamento de prefixo.277Um [fork](/docs/pt/sub-agents#fork-the-current-conversation), por contraste, herda o prompt do sistema, ferramentas e histórico de conversa do pai exatamente, então sua primeira solicitação lê o cache do pai. A chamada de resumo de compactação descrita em [Compactar a conversa](#compacting-the-conversation) usa a mesma abordagem de compartilhamento de prefixo.

278 278 

279<h2 id="disable-prompt-caching">279<h2 id="disable-prompt-caching">

280 Desabilitar prompt caching280 Desabilitar prompt caching

290| `DISABLE_PROMPT_CACHING_OPUS` | Desabilitar para Opus apenas |290| `DISABLE_PROMPT_CACHING_OPUS` | Desabilitar para Opus apenas |

291| `DISABLE_PROMPT_CACHING_FABLE` | Desabilitar para Fable apenas |291| `DISABLE_PROMPT_CACHING_FABLE` | Desabilitar para Fable apenas |

292 292 

293Para definir a política de caching em toda uma organização, coloque qualquer uma dessas ou as [variáveis de TTL](#cache-lifetime) no bloco `env` de [configurações gerenciadas](/pt/settings#settings-files). Para uso normal, deixe o caching habilitado.293Para definir a política de caching em toda uma organização, coloque qualquer uma dessas ou as [variáveis de TTL](#cache-lifetime) no bloco `env` de [configurações gerenciadas](/docs/pt/settings#settings-files). Para uso normal, deixe o caching habilitado.

294 294 

295<h2 id="related-resources">295<h2 id="related-resources">

296 Recursos relacionados296 Recursos relacionados

297</h2>297</h2>

298 298 

299* [Lições de construir Claude Code: Prompt caching é tudo](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything): a lógica de design para modo de plano, carregamento de ferramentas adiado e compactação299* [Lições de construir Claude Code: Prompt caching é tudo](https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything): a lógica de design para modo de plano, carregamento de ferramentas adiado e compactação

300* [Explorar a janela de contexto](/pt/context-window): o que carrega em contexto e quando300* [Explorar a janela de contexto](/docs/pt/context-window): o que carrega em contexto e quando

301* [Reduzir uso de tokens](/pt/costs#reduce-token-usage): estratégias além de caching para gerenciar tamanho de contexto301* [Reduzir uso de tokens](/docs/pt/costs#reduce-token-usage): estratégias além de caching para gerenciar tamanho de contexto

302* [Rastrear e reduzir custos](/pt/agent-sdk/cost-tracking): rastreamento de tokens de cache e configuração de TTL para chamadores do Agent SDK302* [Rastrear e reduzir custos](/docs/pt/agent-sdk/cost-tracking): rastreamento de tokens de cache e configuração de TTL para chamadores do Agent SDK

303* [Prompt caching](https://platform.claude.com/docs/pt/build-with-claude/prompt-caching): o mecanismo de API subjacente, breakpoints e preços303* [Prompt caching](https://platform.claude.com/docs/pt/build-with-claude/prompt-caching): o mecanismo de API subjacente, breakpoints e preços