SpyBara
Go Premium

Documentation 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

110 files changed +6,548 −1,131. View all changes and history on the product overview
2026
Thu 18 02:02 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

admin-setup.md +5 −4

Details

46 Decida como as configurações chegam aos dispositivos46 Decida como as configurações chegam aos dispositivos

47</h2>47</h2>

48 48 

49As configurações gerenciadas definem a política que tem precedência sobre a configuração local do desenvolvedor. Claude Code procura por elas em quatro lugares e usa a primeira que encontra em um determinado dispositivo.49As configurações gerenciadas definem a política que tem precedência sobre a configuração local do desenvolvedor. Claude Code verifica as quatro fontes abaixo em ordem de prioridade e aplica a primeira que retorna uma configuração não vazia.

50 50 

51| Mecanismo | Entrega | Prioridade | Plataformas |51| Mecanismo | Entrega | Prioridade | Plataformas |

52| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- | :------------- |52| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- | :------------- |


55| File-based managed | macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`<br />Linux e WSL: `/etc/claude-code/managed-settings.json`<br />Windows: `C:\Program Files\ClaudeCode\managed-settings.json` | Média | Todas |55| File-based managed | macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`<br />Linux e WSL: `/etc/claude-code/managed-settings.json`<br />Windows: `C:\Program Files\ClaudeCode\managed-settings.json` | Média | Todas |

56| Windows user registry | `HKCU\SOFTWARE\Policies\ClaudeCode` | Mais baixa | Apenas Windows |56| Windows user registry | `HKCU\SOFTWARE\Policies\ClaudeCode` | Mais baixa | Apenas Windows |

57 57 

58As configurações gerenciadas pelo servidor chegam aos dispositivos no momento da autenticação e são atualizadas a cada hora durante sessões ativas, sem infraestrutura de endpoint. Eles exigem um plano Claude for Teams ou Enterprise, portanto, implantações em outros provedores precisam de um dos mecanismos baseados em arquivo ou de nível do SO.58As configurações gerenciadas pelo servidor chegam aos dispositivos no momento da autenticação e são atualizadas a cada hora durante sessões ativas, sem infraestrutura de endpoint. Elas exigem um plano Claude for Teams ou Enterprise, portanto, implantações em outros provedores precisam de um dos mecanismos baseados em arquivo ou de nível do SO.

59 59 

60Se sua organização mistura provedores, configure [configurações gerenciadas pelo servidor](/pt/server-managed-settings) para usuários Claude.ai mais um [fallback baseado em arquivo ou plist/registry](/pt/settings#settings-files) para que outros usuários ainda recebam política gerenciada.60Se sua organização mistura provedores, configure [configurações gerenciadas pelo servidor](/pt/server-managed-settings) para usuários Claude.ai mais um [fallback baseado em arquivo ou plist/registry](/pt/settings#settings-files) para que outros usuários ainda recebam política gerenciada.

61 61 


74As configurações gerenciadas podem bloquear ferramentas, execução de sandbox, restringir servidores MCP e fontes de plugins, e controlar quais hooks são executados. Cada linha é uma superfície de controle com as chaves de configuração que a controlam.74As configurações gerenciadas podem bloquear ferramentas, execução de sandbox, restringir servidores MCP e fontes de plugins, e controlar quais hooks são executados. Cada linha é uma superfície de controle com as chaves de configuração que a controlam.

75 75 

76| Controle | O que faz | Configurações-chave |76| Controle | O que faz | Configurações-chave |

77| :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |77| :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |

78| [Permission rules](/pt/permissions) | Permitir, perguntar ou negar ferramentas e comandos específicos | `permissions.allow`, `permissions.deny` |78| [Permission rules](/pt/permissions) | Permitir, perguntar ou negar ferramentas e comandos específicos | `permissions.allow`, `permissions.deny` |

79| [Permission lockdown](/pt/permissions#managed-only-settings) | Apenas regras de permissão gerenciadas se aplicam; desabilitar `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`, `permissions.disableBypassPermissionsMode` |79| [Permission lockdown](/pt/permissions#managed-only-settings) | Apenas regras de permissão gerenciadas se aplicam; desabilitar `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`, `permissions.disableBypassPermissionsMode` |

80| [Sandboxing](/pt/sandboxing) | Isolamento de sistema de arquivos e rede de nível do SO com listas de permissão de domínio | `sandbox.enabled`, `sandbox.network.allowedDomains` |80| [Sandboxing](/pt/sandboxing) | Isolamento de sistema de arquivos e rede de nível do SO com listas de permissão de domínio | `sandbox.enabled`, `sandbox.network.allowedDomains` |


85| [Hook restrictions](/pt/settings#hook-configuration) | Apenas hooks gerenciados são carregados; restringir URLs de hook HTTP | `allowManagedHooksOnly`, `allowedHttpHookUrls` |85| [Hook restrictions](/pt/settings#hook-configuration) | Apenas hooks gerenciados são carregados; restringir URLs de hook HTTP | `allowManagedHooksOnly`, `allowedHttpHookUrls` |

86| [Disable agent view](/pt/agent-view#how-background-sessions-are-hosted) | Desativar `claude agents`, `--bg`, `/background` e o supervisor sob demanda | `disableAgentView` |86| [Disable agent view](/pt/agent-view#how-background-sessions-are-hosted) | Desativar `claude agents`, `--bg`, `/background` e o supervisor sob demanda | `disableAgentView` |

87| [Version floor](/pt/settings) | Impedir que a atualização automática instale abaixo de um mínimo em toda a organização | `minimumVersion` |87| [Version floor](/pt/settings) | Impedir que a atualização automática instale abaixo de um mínimo em toda a organização | `minimumVersion` |

88| [Required version range](/pt/settings) | Recusar iniciar completamente quando a versão em execução está fora de um intervalo aprovado pela organização. Mais forte que `minimumVersion`, que apenas bloqueia downgrades | `requiredMinimumVersion`, `requiredMaximumVersion` |

88 89 

89As regras de permissão e sandboxing cobrem camadas diferentes. Negar WebFetch bloqueia a ferramenta de busca do Claude, mas se Bash for permitido, `curl` e `wget` ainda podem alcançar qualquer URL. O sandboxing fecha essa lacuna com uma lista de permissão de domínio de rede aplicada no nível do SO.90As regras de permissão e sandboxing cobrem camadas diferentes. Negar WebFetch bloqueia a ferramenta de busca do Claude, mas se Bash for permitido, `curl` e `wget` ainda podem alcançar qualquer URL. O sandboxing fecha essa lacuna com uma lista de permissão de domínio de rede aplicada no nível do SO.

90 91 


122 Verifique e integre123 Verifique e integre

123</h2>124</h2>

124 125 

125Após configurar as configurações gerenciadas, peça a um desenvolvedor para executar `/status` dentro de Claude Code. A saída inclui uma linha começando com `Enterprise managed settings` seguida pela fonte entre parênteses, uma de `(remote)`, `(plist)`, `(HKLM)`, `(HKCU)` ou `(file)`. Consulte [Verificar configurações ativas](/pt/settings#verify-active-settings).126Após configurar as configurações gerenciadas, peça a um desenvolvedor para executar `/status` dentro de Claude Code. Na aba **Status**, a linha `Setting sources` mostra `Enterprise managed settings` seguida pela fonte entre parênteses, uma de `(remote)`, `(plist)`, `(HKLM)`, `(HKCU)` ou `(file)`. Consulte [Verificar configurações ativas](/pt/settings#verify-active-settings).

126 127 

127Compartilhe esses recursos para ajudar os desenvolvedores a começar:128Compartilhe esses recursos para ajudar os desenvolvedores a começar:

128 129 

advisor.md +198 −0 created

Details

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# Escale decisões difíceis com a ferramenta advisor

6 

7> Combine seu modelo principal com um modelo advisor mais forte que Claude consulta em momentos-chave durante uma tarefa.

8 

9{/* plan-availability: feature=advisor providers=anthropic */}

10 

11<Note>

12 A ferramenta advisor é experimental e requer Claude Code v2.1.98 ou posterior com a API Anthropic. Não está disponível no Amazon Bedrock, Google Vertex AI ou Microsoft Foundry. O comportamento, preços e disponibilidade podem mudar.

13</Note>

14 

15A ferramenta advisor permite que Claude consulte um segundo modelo, tipicamente mais forte, em momentos-chave durante uma tarefa, como antes de se comprometer com uma abordagem, quando preso em um erro recorrente, ou antes de declarar uma tarefa concluída. O advisor recebe a conversa completa, incluindo cada chamada de ferramenta e resultado, e retorna orientação que Claude aplica antes de continuar.

16 

17O advisor é executado no servidor na infraestrutura da Anthropic como uma [server tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool), disponível para contas de assinatura e faturadas por API. Você escolhe qual modelo atua como advisor, e Claude decide quando chamá-lo.

18 

19Esta página cobre como ativar o advisor, quais emparelhamentos de modelos são aceitos, o que Claude mostra durante uma consulta, e como o uso do advisor é faturado.

20 

21<h2 id="when-to-use-the-advisor">

22 Quando usar o advisor

23</h2>

24 

25O advisor é adequado para tarefas longas e com múltiplas etapas onde a maioria dos turnos é rotineira, mas a qualidade do plano determina o resultado. Exemplos incluem grandes refatorações, sessões de depuração onde um erro continua recorrendo, e tarefas que você deseja verificadas independentemente antes de Claude declarar que estão concluídas.

26 

27Adiciona menos valor em tarefas curtas onde há pouco a planejar, ou em trabalho onde cada turno precisa do modelo mais forte. Para esses casos, [mude o modelo principal](/pt/model-config#setting-your-model) em vez disso, ou veja [como o advisor se compara com opusplan e subagents](#compare-with-related-features) para outras formas de obter uma segunda opinião.

28 

29<h2 id="enable-the-advisor">

30 Ativar o advisor

31</h2>

32 

33Você pode definir o modelo advisor de três formas:

34 

35* **Comando `/advisor`**: defina ou altere o advisor no meio da sessão e salve-o como seu padrão

36* **Configuração `advisorModel`**: configure um padrão persistente em seu [arquivo de configurações](/pt/settings)

37* **Flag `--advisor`**: defina o advisor para uma única sessão no lançamento

38 

39Se qualquer uma dessas opções definir um modelo advisor, o advisor será ativado para sessões cujo modelo principal [o suporta](#choose-an-advisor-model). Para parar de usá-lo, veja [Desativar o advisor](#turn-the-advisor-off).

40 

41<Note>

42 Para usar Fable 5 como o advisor, você precisa de Claude Code v2.1.170 ou posterior e [acesso a Fable 5](/pt/model-config#work-with-fable-5) para sua organização.

43</Note>

44 

45<h3 id="use-the-/advisor-command">

46 Use o comando `/advisor`

47</h3>

48 

49Execute `/advisor` sem argumentos para abrir um seletor listando os modelos advisor disponíveis, ou passe o modelo diretamente:

50 

51```

52/advisor opus

53```

54 

55Sua seleção é salva em `advisorModel` nas configurações do usuário e persiste entre sessões. Se seu modelo principal atual não suportar o advisor, a seleção ainda é salva e ativada quando você muda para um [modelo principal compatível](#choose-an-advisor-model) com [`/model`](/pt/model-config#setting-your-model).

56 

57<h3 id="set-advisormodel-in-settings">

58 Defina `advisorModel` nas configurações

59</h3>

60 

61Para configurar o advisor como padrão sem abrir uma sessão, defina-o em seu arquivo de configurações:

62 

63```json theme={null}

64{

65 "advisorModel": "opus"

66}

67```

68 

69<h3 id="use-the-advisor-flag">

70 Use a flag `--advisor`

71</h3>

72 

73Para definir o advisor para uma única sessão sem alterar sua configuração salva, inicie com a flag:

74 

75```bash theme={null}

76claude --advisor opus

77```

78 

79A flag tem precedência sobre a configuração `advisorModel` para essa sessão. Diferentemente de `/advisor`, que salva uma seleção inativa, a flag sai com um erro se o modelo principal da sessão não suportar o advisor.

80 

81<h2 id="choose-an-advisor-model">

82 Escolha um modelo advisor

83</h2>

84 

85O advisor deve ser pelo menos tão capaz quanto o modelo principal. Os advisors aceitos para cada modelo principal são:

86 

87| Modelo principal | Advisors aceitos | Notas |

88| ----------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |

89| Haiku 4.5 | Fable, Opus, Sonnet | Haiku pode chamar o advisor, mas não pode atuar como um |

90| Sonnet 4.6 | Fable, Opus, Sonnet | |

91| Opus 4.6 ou posterior | Fable, Opus na versão do modelo principal ou acima | Um Opus 4.7 principal com um advisor Opus 4.6 é rejeitado |

92| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Um advisor Opus ou Sonnet é rejeitado |

93 

94Fable 5 requer Claude Code v2.1.170 ou posterior e acesso a Fable 5, seja atuando como modelo principal ou advisor.

95 

96Defina o advisor como `opus`, `sonnet`, ou `fable`. Esses aliases resolvem para a versão mais recente de cada modelo. Você também pode passar um ID de modelo completo como `claude-opus-4-8`.

97 

98Subagentes herdam o advisor configurado e aplicam a mesma verificação de emparelhamento contra seu próprio modelo.

99 

100Claude Code valida o emparelhamento antes de enviar uma solicitação:

101 

102* Se o advisor for menos capaz que o modelo principal, o advisor não será anexado às solicitações do modelo principal. A saída do comando `/advisor` e uma notificação mostram isso. Subagentes cujo próprio modelo satisfaz o emparelhamento ainda podem usar o advisor.

103* Se o modelo principal ou o advisor for um modelo que Claude Code não reconhece, o advisor não será anexado.

104 

105<h3 id="common-model-pairings">

106 Emparelhamentos de modelos comuns

107</h3>

108 

109Qualquer emparelhamento aceito funciona. Essas combinações equilibram custo contra capacidade de diferentes formas:

110 

111| Emparelhamento | Quando usar |

112| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

113| Sonnet principal + advisor Opus | Sonnet lida com trabalho rotineiro e escala planejamento, falhas ambíguas e verificações de conclusão para Opus |

114| Sonnet principal + advisor Fable | Orientação Fable 5 em pontos de decisão sem executar Fable 5 em toda parte. Requer v2.1.170 ou posterior e acesso a Fable 5 |

115| Haiku principal + advisor Opus | Modelo principal de menor custo com planejamento forte. Espere custo mais alto que Haiku sozinho, mas menor que mudar o modelo principal para Sonnet ou Opus |

116| Opus principal + advisor Opus | Um segundo Opus revisa o primeiro. Útil para tarefas de alto risco onde uma verificação independente importa mais que o custo |

117| Fable principal + advisor Fable | Emparelhamento de maior capacidade quando Fable 5 está disponível (v2.1.170+). Fable é um nível superior a Opus e Sonnet, então é o único advisor aceito para um modelo principal Fable |

118| Sonnet principal + advisor Sonnet | Uma segunda opinião de menor custo para capturar oversights rotineiros |

119 

120<h2 id="when-claude-consults-the-advisor">

121 Quando Claude consulta o advisor

122</h2>

123 

124Claude decide quando chamar o advisor. Tende a consultar antes de se comprometer com uma abordagem, quando um erro continua recorrendo, e antes de declarar uma tarefa concluída, mas o tempo é orientado pelo modelo em vez de baseado em regras.

125 

126Você pode pedir uma consulta em seu prompt da mesma forma que solicitaria qualquer ferramenta, por exemplo `consult the advisor before you continue`. Não há configuração para limitar ou forçar chamadas do advisor; se você quiser que Claude consulte mais ou menos frequentemente durante uma tarefa, diga isso em suas instruções.

127 

128<h2 id="what-you-see-during-a-session">

129 O que você vê durante uma sessão

130</h2>

131 

132Quando Claude chama o advisor, a transcrição mostra uma linha `Advising` com o nome do modelo advisor enquanto a chamada está em andamento. Quando o resultado retorna, a linha confirma que o advisor revisou a conversa. Pressione `Ctrl+O` para expandi-la e ler a orientação completa do advisor.

133 

134Claude geralmente segue a orientação do advisor, mas se adapta quando sua própria evidência contradiz uma afirmação específica: se uma etapa recomendada falha quando tentada, ou o conteúdo do arquivo contradiz o conselho, Claude expõe o conflito em vez de seguir a orientação incondicionalmente.

135 

136O advisor sempre recebe a conversa completa, e Claude controla o tempo. Para mais controle ou uma configuração diferente, veja [como o advisor se compara com subagents e opusplan](#compare-with-related-features).

137 

138<h2 id="cost">

139 Custo

140</h2>

141 

142Cada chamada do advisor envia a conversa para o modelo advisor, então consome tokens nas taxas do modelo advisor além do uso do seu modelo principal. Com faturamento por API, tokens do advisor são cobrados nas taxas de entrada e saída do modelo advisor. Em planos de assinatura, o uso do advisor conta para os limites de uso do seu plano.

143 

144Claude chama o advisor em pontos de decisão em vez de em cada turno, então emparelhar um modelo principal mais rápido com um advisor mais forte tipicamente custa menos que executar o modelo mais forte em toda parte. O uso do advisor conta para os totais da sessão mostrados por [`/usage`](/pt/costs#track-your-costs).

145 

146Para como tokens do advisor são reportados em respostas da API, veja [Usage and billing](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#usage-and-billing) na documentação da API Claude.

147 

148<h2 id="impact-on-prompt-caching">

149 Impacto no prompt caching

150</h2>

151 

152Ativar ou desativar o advisor no meio da sessão não invalida o [prompt cache](/pt/prompt-caching) do seu modelo principal. Diferentemente de [mudar modelo ou nível de esforço](/pt/prompt-caching#actions-that-invalidate-the-cache), alternar `/advisor` mantém o prefixo em cache intacto, e a orientação retornada pelo advisor é armazenada em cache como parte da transcrição em turnos posteriores.

153 

154A própria leitura do advisor da conversa não é armazenada em cache. Cada chamada do advisor processa a transcrição completa novamente, sem reutilização entre chamadas.

155 

156<h2 id="requirements">

157 Requisitos

158</h2>

159 

160A ferramenta advisor requer todos os seguintes:

161 

162* **Claude Code v2.1.98 ou posterior**: execute `claude update` para atualizar.

163* **Apenas API Anthropic**: o advisor é uma ferramenta executada no servidor. Não está disponível no Amazon Bedrock, Google Vertex AI ou Microsoft Foundry. Através de um [LLM gateway](/pt/llm-gateway) configurado com `ANTHROPIC_BASE_URL`, a disponibilidade depende se o gateway encaminha a solicitação intacta para a API Anthropic.

164* **Modelo principal suportado**: Opus 4.6 ou posterior, Sonnet 4.6, ou Haiku 4.5. {/* min-version: 2.1.170 */}Fable 5 também se qualifica no Claude Code v2.1.170 ou posterior.

165 

166<h2 id="turn-the-advisor-off">

167 Desativar o advisor

168</h2>

169 

170Para parar de usar o advisor e limpar seu `advisorModel` salvo, execute `/advisor off` ou escolha **No advisor** no seletor `/advisor`:

171 

172```

173/advisor off

174```

175 

176Para desativar a ferramenta advisor inteiramente, incluindo o comando `/advisor` e a flag `--advisor`, defina `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`. Veja [Environment variables](/pt/env-vars).

177 

178<h2 id="compare-with-related-features">

179 Compare com recursos relacionados

180</h2>

181 

182O advisor é uma das várias formas de combinar forças de modelos. Escolha com base em quando você quer um segundo modelo envolvido.

183 

184| Abordagem | Quando o modelo mais forte é executado | Como começa |

185| --------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------- |

186| Ferramenta Advisor | Em pontos de decisão no meio da tarefa | Claude a chama quando precisa de orientação |

187| [`opusplan`](/pt/model-config#opusplan-model-setting) | Durante plan mode, depois muda para Sonnet para execução | Você entra em plan mode |

188| [Subagents](/pt/sub-agents#choose-a-model) com `model` definido | Para toda a subtarefa delegada | Claude delega, ou você invoca o subagent |

189| [`/model`](/pt/model-config#setting-your-model) | Para todos os turnos subsequentes | Você muda de modelos |

190 

191<h2 id="see-also">

192 Veja também

193</h2>

194 

195* [Model configuration](/pt/model-config): mude modelos, defina níveis de esforço, e use `opusplan`

196* [Manage costs effectively](/pt/costs): rastreie o uso de tokens entre modelos

197* [Advisor tool in the Claude API](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool): entenda a ferramenta de servidor subjacente, ou use-a diretamente da Messages API

198* [The advisor strategy](https://claude.com/blog/the-advisor-strategy): por que emparelhar um modelo principal rápido com um advisor mais forte funciona

Details

16 16 

17Cada sessão de agente segue o mesmo ciclo:17Cada sessão de agente segue o mesmo ciclo:

18 18 

19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-loop-diagram.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=1c6e8f28d80dba14a7287419656f1237" alt="Agent loop: prompt entra, Claude avalia, ramifica para chamadas de ferramentas ou resposta final" width="720" height="212" data-path="images/agent-loop-diagram.svg" />19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-loop-diagram.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=1c6e8f28d80dba14a7287419656f1237" alt="Diagrama do loop do agente: seu prompt entra no loop agentic, onde Claude avalia e solicita chamadas de ferramentas, cujos resultados retornam para outra avaliação, ou retorna a resposta final" width="720" height="212" data-path="images/agent-loop-diagram.svg" />

20 20 

211. **Receber prompt.** Claude recebe seu prompt, junto com o prompt do sistema, definições de ferramentas e histórico de conversa. O SDK produz uma [`SystemMessage`](#message-types) com subtipo `"init"` contendo metadados da sessão.211. **Receber prompt.** Claude recebe seu prompt, junto com o prompt do sistema, definições de ferramentas e histórico de conversa. O SDK produz uma [`SystemMessage`](#message-types) com subtipo `"init"` contendo metadados da sessão.

222. **Avaliar e responder.** Claude avalia o estado atual e determina como proceder. Pode responder com texto, solicitar uma ou mais chamadas de ferramentas, ou ambos. O SDK produz uma [`AssistantMessage`](#message-types) contendo o texto e quaisquer solicitações de chamadas de ferramentas.222. **Avaliar e responder.** Claude avalia o estado atual e determina como proceder. Pode responder com texto, solicitar uma ou mais chamadas de ferramentas, ou ambos. O SDK produz uma [`AssistantMessage`](#message-types) contendo o texto e quaisquer solicitações de chamadas de ferramentas.


53 53 

54Conforme o loop é executado, o SDK produz um fluxo de mensagens. Cada mensagem carrega um tipo que informa em qual estágio do loop ela veio. Os cinco tipos principais são:54Conforme o loop é executado, o SDK produz um fluxo de mensagens. Cada mensagem carrega um tipo que informa em qual estágio do loop ela veio. Os cinco tipos principais são:

55 55 

56* **`SystemMessage`:** eventos do ciclo de vida da sessão. O campo `subtype` os distingue: `"init"` é a primeira mensagem (metadados da sessão), e `"compact_boundary"` dispara após [compactação](#automatic-compaction). Em TypeScript, o limite de compactação é seu próprio tipo [`SDKCompactBoundaryMessage`](/pt/agent-sdk/typescript#sdkcompactboundarymessage) em vez de um subtipo de `SDKSystemMessage`.56* **`SystemMessage`:** eventos do ciclo de vida da sessão. O campo `subtype` os distingue:

57 

58 * `"init"`: a primeira mensagem com metadados da sessão

59 * `"compact_boundary"`: dispara após [compactação](#automatic-compaction)

60 * `"informational"`: banners de status em texto simples do loop

61 * `"worker_shutting_down"`: o loop terminará após a volta atual porque o host está saindo ou Remote Control foi desconectado

62 

63 Em TypeScript, cada subtipo diferente de `"init"` é seu próprio tipo na união [`SDKMessage`](/pt/agent-sdk/typescript#sdkmessage) em vez de um subtipo de `SDKSystemMessage`.

57* **`AssistantMessage`:** emitida após cada resposta do Claude, incluindo a final apenas com texto. Contém blocos de conteúdo de texto e blocos de chamadas de ferramentas dessa volta.64* **`AssistantMessage`:** emitida após cada resposta do Claude, incluindo a final apenas com texto. Contém blocos de conteúdo de texto e blocos de chamadas de ferramentas dessa volta.

58* **`UserMessage`:** emitida após cada execução de ferramenta com o conteúdo do resultado da ferramenta enviado de volta para Claude. Também emitida para quaisquer entradas do usuário que você transmita no meio do loop.65* **`UserMessage`:** emitida após cada execução de ferramenta com o conteúdo do resultado da ferramenta enviado de volta para Claude. Também emitida para quaisquer entradas do usuário que você transmita no meio do loop.

59* **`StreamEvent`:** emitida apenas quando mensagens parciais estão habilitadas. Contém eventos brutos de streaming da API (deltas de texto, pedaços de entrada de ferramentas). Veja [Respostas de streaming](/pt/agent-sdk/streaming-output).66* **`StreamEvent`:** emitida apenas quando mensagens parciais estão habilitadas. Contém eventos brutos de streaming da API (deltas de texto, pedaços de entrada de ferramentas). Veja [Respostas de streaming](/pt/agent-sdk/streaming-output).


183A opção `effort` controla quanto raciocínio Claude aplica. Níveis de esforço mais baixos usam menos tokens por volta e reduzem custo. Nem todos os modelos suportam o parâmetro de esforço. Veja [Esforço](https://platform.claude.com/docs/en/build-with-claude/effort) para quais modelos o suportam.190A opção `effort` controla quanto raciocínio Claude aplica. Níveis de esforço mais baixos usam menos tokens por volta e reduzem custo. Nem todos os modelos suportam o parâmetro de esforço. Veja [Esforço](https://platform.claude.com/docs/en/build-with-claude/effort) para quais modelos o suportam.

184 191 

185| Nível | Comportamento | Bom para |192| Nível | Comportamento | Bom para |

186| :--------- | :----------------------------------- | :-------------------------------------------------------- |193| :--------- | :----------------------------------- | :------------------------------------------------------------------- |

187| `"low"` | Raciocínio mínimo, respostas rápidas | Buscas de arquivo, listagem de diretórios |194| `"low"` | Raciocínio mínimo, respostas rápidas | Buscas de arquivo, listagem de diretórios |

188| `"medium"` | Raciocínio equilibrado | Edições rotineiras, tarefas padrão |195| `"medium"` | Raciocínio equilibrado | Edições rotineiras, tarefas padrão |

189| `"high"` | Análise completa | Refatorações, depuração |196| `"high"` | Análise completa | Refatorações, depuração |

190| `"xhigh"` | Profundidade de raciocínio estendida | Tarefas de codificação e agentes; recomendado em Opus 4.7 |197| `"xhigh"` | Profundidade de raciocínio estendida | Tarefas de codificação e agentes; recomendado em Fable 5 e Opus 4.7+ |

191| `"max"` | Profundidade máxima de raciocínio | Problemas multi-etapas que exigem análise profunda |198| `"max"` | Profundidade máxima de raciocínio | Problemas multi-etapas que exigem análise profunda |

192 199 

193Se você não definir `effort`, o SDK Python deixa o parâmetro indefinido e defere para o comportamento padrão do modelo. O SDK TypeScript padrão é `"high"`.200Se você não definir `effort`, ambos os SDKs deixam o parâmetro indefinido e deferem para o comportamento padrão do modelo.

194 201 

195<Note>202<Note>

196 `effort` negocia latência e custo de token por profundidade de raciocínio dentro de cada resposta. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) é um recurso separado que produz blocos de cadeia de pensamento visíveis na saída. Eles são independentes: você pode definir `effort: "low"` com extended thinking habilitado, ou `effort: "max"` sem ele.203 `effort` negocia latência e custo de token por profundidade de raciocínio dentro de cada resposta. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) é um recurso separado que produz blocos de cadeia de pensamento visíveis na saída. Eles são independentes: você pode definir `effort: "low"` com extended thinking habilitado, ou `effort: "max"` sem ele.


205A opção de modo de permissão (`permission_mode` em Python, `permissionMode` em TypeScript) controla se o agente pede aprovação antes de usar ferramentas:212A opção de modo de permissão (`permission_mode` em Python, `permissionMode` em TypeScript) controla se o agente pede aprovação antes de usar ferramentas:

206 213 

207| Modo | Comportamento |214| Modo | Comportamento |

208| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |215| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

209| `"default"` | Ferramentas não cobertas por regras de permissão acionam seu callback de aprovação; sem callback significa negar |216| `"default"` | Ferramentas não cobertas por regras de permissão acionam seu callback de aprovação; sem callback significa negar |

210| `"acceptEdits"` | Aprova automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.); outros comandos Bash seguem regras padrão |217| `"acceptEdits"` | Aprova automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.); outros comandos Bash seguem regras padrão |

211| `"plan"` | Ferramentas somente leitura são executadas; Claude explora e produz um plano sem editar seus arquivos de origem |218| `"plan"` | Claude explora e planeja sem editar seus arquivos de origem; edições de arquivo nunca são aprovadas automaticamente e solicitam através de seu callback `canUseTool` |

212| `"dontAsk"` | Nunca avisa. Ferramentas pré-aprovadas por [regras de permissão](/pt/settings#permission-settings) são executadas, tudo mais é negado |219| `"dontAsk"` | Nunca avisa. Ferramentas pré-aprovadas por [regras de permissão](/pt/settings#permission-settings) são executadas, tudo mais é negado |

213| `"auto"` (apenas TypeScript) | Usa um classificador de modelo para aprovar ou negar cada chamada de ferramenta. Veja [Modo Auto](/pt/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidade e comportamento |220| `"auto"` (apenas TypeScript) | Usa um classificador de modelo para aprovar ou negar cada chamada de ferramenta. Veja [Modo Auto](/pt/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidade e comportamento |

214| `"bypassPermissions"` | Executa todas as ferramentas permitidas sem avisar. Não pode ser usado ao executar como root em Unix. Use apenas em ambientes isolados onde as ações do agente não podem afetar sistemas que você se importa |221| `"bypassPermissions"` | Executa todas as ferramentas permitidas sem avisar, a menos que uma regra [`ask`](/pt/settings#permission-settings) explícita corresponda; veja [Como as permissões são avaliadas](/pt/agent-sdk/permissions#how-permissions-are-evaluated) para onde as regras ask se situam na ordem de precedência. Não pode ser usado ao executar como root em Unix. Use apenas em ambientes isolados onde as ações do agente não podem afetar sistemas que você se importa |

215 222 

216Para aplicações interativas, use `"default"` com um callback de aprovação de ferramenta para exibir avisos de aprovação. Para agentes autônomos em uma máquina de desenvolvimento, `"acceptEdits"` aprova automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.) enquanto ainda controla outros comandos `Bash` atrás de regras de permissão. Reserve `"bypassPermissions"` para CI, contêineres ou outros ambientes isolados. Veja [Permissões](/pt/agent-sdk/permissions) para detalhes completos.223Para aplicações interativas, use `"default"` com um callback de aprovação de ferramenta para exibir avisos de aprovação. Para agentes autônomos em uma máquina de desenvolvimento, `"acceptEdits"` aprova automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.) enquanto ainda controla outros comandos `Bash` atrás de regras de permissão. Reserve `"bypassPermissions"` para CI, contêineres ou outros ambientes isolados. Veja [Permissões](/pt/agent-sdk/permissions) para detalhes completos.

217 224 


305Quando o loop termina, a `ResultMessage` informa o que aconteceu e fornece a saída. O campo `subtype` (disponível em ambos os SDKs) é a forma principal de verificar o estado de término.312Quando o loop termina, a `ResultMessage` informa o que aconteceu e fornece a saída. O campo `subtype` (disponível em ambos os SDKs) é a forma principal de verificar o estado de término.

306 313 

307| Subtipo de resultado | O que aconteceu | Campo `result` disponível? |314| Subtipo de resultado | O que aconteceu | Campo `result` disponível? |

308| :------------------------------------ | :----------------------------------------------------------------------------- | :------------------------: |315| :------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------: |

309| `success` | Claude terminou a tarefa normalmente | Sim |316| `success` | Claude terminou a tarefa normalmente | Sim |

310| `error_max_turns` | Atingiu o limite de `maxTurns` antes de terminar | Não |317| `error_max_turns` | Atingiu o limite de `maxTurns` antes de terminar | Não |

311| `error_max_budget_usd` | Atingiu o limite de `maxBudgetUsd` antes de terminar | Não |318| `error_max_budget_usd` | Atingiu o limite de `maxBudgetUsd` antes de terminar | Não |

312| `error_during_execution` | Um erro interrompeu o loop (por exemplo, falha de API ou requisição cancelada) | Não |319| `error_during_execution` | Um erro interrompeu o loop (por exemplo, falha de API ou requisição cancelada) | Não |

313| `error_max_structured_output_retries` | Validação de saída estruturada falhou após o limite de tentativas configurado | Não |320| `error_max_structured_output_retries` | Nenhuma saída estruturada válida foi produzida dentro do limite de tentativas configurado: todas as tentativas falharam na validação, ou um fallback de modelo retratou a saída concluída sem nenhuma tentativa bem-sucedida | Não |

314 321 

315O campo `result` (a saída de texto final) está presente apenas na variante `success`, então sempre verifique o subtipo antes de lê-lo. Todos os subtipos de resultado carregam `total_cost_usd`, `usage`, `num_turns` e `session_id` para que você possa rastrear custo e retomar mesmo após erros. Em Python, `total_cost_usd` e `usage` são digitados como opcionais e podem ser `None` em alguns caminhos de erro, então proteja antes de formatá-los. Veja [Rastreamento de custos e uso](/pt/agent-sdk/cost-tracking) para detalhes sobre interpretação dos campos `usage`.322O campo `result` (a saída de texto final) está presente apenas na variante `success`, então sempre verifique o subtipo antes de lê-lo. Todos os subtipos de resultado carregam `total_cost_usd`, `usage`, `num_turns` e `session_id` para que você possa rastrear custo e retomar mesmo após erros. Em Python, `total_cost_usd` e `usage` são digitados como opcionais e podem ser `None` em alguns caminhos de erro, então proteja antes de formatá-los. Veja [Rastreamento de custos e uso](/pt/agent-sdk/cost-tracking) para detalhes sobre interpretação dos campos `usage`.

316 323 

Details

305Cada recurso que você habilita adiciona à janela de contexto do seu agente. Para custos por recurso e como esses recursos se sobrepõem, veja [Extend Claude Code](/pt/features-overview#understand-context-costs).305Cada recurso que você habilita adiciona à janela de contexto do seu agente. Para custos por recurso e como esses recursos se sobrepõem, veja [Extend Claude Code](/pt/features-overview#understand-context-costs).

306 306 

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

308 Related resources308 Recursos relacionados

309</h2>309</h2>

310 310 

311* [Extend Claude Code](/pt/features-overview): Visão geral conceitual de todos os recursos de extensão, com tabelas de comparação e análise de custo de contexto311* [Extend Claude Code](/pt/features-overview): Visão geral conceitual de todos os recursos de extensão, com tabelas de comparação e análise de custo de contexto

Details

257 257 

258<CodeGroup>258<CodeGroup>

259 ```python Python theme={null}259 ```python Python theme={null}

260 from claude_agent_sdk import ClaudeAgentOptions, query

261 import asyncio

262 

263 

264 async def main():

260 options = ClaudeAgentOptions(265 options = ClaudeAgentOptions(

261 env={266 env={

262 "CLAUDE_CODE_USE_BEDROCK": "1",267 "CLAUDE_CODE_USE_BEDROCK": "1",

263 "ENABLE_PROMPT_CACHING_1H": "1",268 "ENABLE_PROMPT_CACHING_1H": "1",

264 },269 },

265 )270 )

271 

272 async for message in query(prompt="Summarize this project", options=options):

273 print(message)

274 

275 

276 asyncio.run(main())

266 ```277 ```

267 278 

268 ```typescript TypeScript theme={null}279 ```typescript TypeScript theme={null}

280 import { query } from "@anthropic-ai/claude-agent-sdk";

281 

269 const options = {282 const options = {

270 env: {283 env: {

271 ...process.env,284 ...process.env,


273 ENABLE_PROMPT_CACHING_1H: "1",286 ENABLE_PROMPT_CACHING_1H: "1",

274 },287 },

275 };288 };

289 

290 for await (const message of query({ prompt: "Summarize this project", options })) {

291 console.log(message);

292 }

276 ```293 ```

277</CodeGroup>294</CodeGroup>

278 295 

Details

36* **Descrição:** o que a ferramenta faz. Claude lê isto para decidir quando chamá-la.36* **Descrição:** o que a ferramenta faz. Claude lê isto para decidir quando chamá-la.

37* **Esquema de entrada:** os argumentos que Claude deve fornecer. Em TypeScript isto é sempre um [esquema Zod](https://zod.dev/), e os `args` do manipulador são tipados automaticamente a partir dele. Em Python isto é um dict mapeando nomes para tipos, como `{"latitude": float}`, que o SDK converte para JSON Schema para você. O decorador Python também aceita um dict completo de [JSON Schema](https://json-schema.org/understanding-json-schema/about) diretamente quando você precisa de enums, intervalos, campos opcionais ou objetos aninhados.37* **Esquema de entrada:** os argumentos que Claude deve fornecer. Em TypeScript isto é sempre um [esquema Zod](https://zod.dev/), e os `args` do manipulador são tipados automaticamente a partir dele. Em Python isto é um dict mapeando nomes para tipos, como `{"latitude": float}`, que o SDK converte para JSON Schema para você. O decorador Python também aceita um dict completo de [JSON Schema](https://json-schema.org/understanding-json-schema/about) diretamente quando você precisa de enums, intervalos, campos opcionais ou objetos aninhados.

38* **Manipulador:** a função assíncrona que executa quando Claude chama a ferramenta. Ela recebe os argumentos validados e deve retornar um objeto com:38* **Manipulador:** a função assíncrona que executa quando Claude chama a ferramenta. Ela recebe os argumentos validados e deve retornar um objeto com:

39 * `content` (obrigatório): um array de blocos de resultado, cada um com um `type` de `"text"`, `"image"` ou `"resource"`. Veja [Retornar imagens e recursos](#return-images-and-resources) para blocos não-texto.39 * `content` (obrigatório): um array de blocos de resultado, cada um com um `type` de `"text"`, `"image"`, `"audio"`, `"resource"` ou `"resource_link"`. Veja [Retornar imagens e recursos](#return-images-and-resources) para blocos não-texto.

40 * `structuredContent` (opcional): um objeto JSON contendo o resultado como dados legíveis por máquina, retornado junto com `content`. Veja [Retornar dados estruturados](#return-structured-data).40 * `structuredContent` (opcional): um objeto JSON contendo o resultado como dados legíveis por máquina, retornado junto com `content`. Veja [Retornar dados estruturados](#return-structured-data).

41 * `isError` (opcional): defina como `true` para sinalizar uma falha de ferramenta para que Claude possa reagir a ela. Veja [Tratar erros](#handle-errors).41 * `isError` (opcional): defina como `true` para sinalizar uma falha de ferramenta para que Claude possa reagir a ela. Veja [Tratar erros](#handle-errors).

42 42 


461 Retornar imagens e recursos461 Retornar imagens e recursos

462</h2>462</h2>

463 463 

464O array `content` em um resultado de ferramenta aceita blocos `text`, `image` e `resource`. Você pode misturá-los na mesma resposta.464O array `content` em um resultado de ferramenta aceita blocos `text`, `image`, `audio`, `resource` e `resource_link`. Você pode misturá-los na mesma resposta. Blocos de áudio são salvos em disco e Claude recebe um bloco de texto com o caminho do arquivo salvo. Blocos de link de recurso são convertidos em um bloco de texto contendo o nome do link, URI e descrição.

465 465 

466<h3 id="images">466<h3 id="images">

467 Imagens467 Imagens

Details

729* **Python**: `pip install --upgrade claude-agent-sdk`729* **Python**: `pip install --upgrade claude-agent-sdk`

730* **TypeScript**: `npm install @anthropic-ai/claude-agent-sdk@latest`730* **TypeScript**: `npm install @anthropic-ai/claude-agent-sdk@latest`

731 731 

732<h3 id="user-messages-don-t-have-uuids">732<h3 id="user-messages-dont-have-uuids">

733 Mensagens do usuário não têm UUIDs733 Mensagens do usuário não têm UUIDs

734</h3>734</h3>

735 735 

agent-sdk/mcp.md +79 −27

Details

14 Esta página abrange a configuração de MCP para o Agent SDK. Para adicionar servidores MCP ao Claude Code CLI para que sejam carregados em cada projeto, consulte [escopos de instalação de MCP](/pt/mcp#mcp-installation-scopes).14 Esta página abrange a configuração de MCP para o Agent SDK. Para adicionar servidores MCP ao Claude Code CLI para que sejam carregados em cada projeto, consulte [escopos de instalação de MCP](/pt/mcp#mcp-installation-scopes).

15</Note>15</Note>

16 16 

17## Início rápido17<h2 id="quickstart">

18 Início rápido

19</h2>

18 20 

19Este exemplo conecta ao servidor MCP de [documentação do Claude Code](https://code.claude.com/docs) usando [transporte HTTP](#httpsse-servers) e usa [`allowedTools`](#allow-mcp-tools) com um curinga para permitir todas as ferramentas do servidor.21Este exemplo conecta ao servidor MCP de [documentação do Claude Code](https://code.claude.com/docs) usando [transporte HTTP](#http%2Fsse-servers) e usa [`allowedTools`](#allow-mcp-tools) com um curinga para permitir todas as ferramentas do servidor.

20 22 

21<CodeGroup>23<CodeGroup>

22 ```typescript TypeScript theme={null}24 ```typescript TypeScript theme={null}


70 72 

71O agente conecta ao servidor de documentação, busca informações sobre hooks e retorna os resultados.73O agente conecta ao servidor de documentação, busca informações sobre hooks e retorna os resultados.

72 74 

73## Adicionar um servidor MCP75<h2 id="add-an-mcp-server">

76 Adicionar um servidor MCP

77</h2>

74 78 

75Você pode configurar servidores MCP em código ao chamar `query()`, ou em um arquivo `.mcp.json` carregado via [`settingSources`](#from-a-config-file).79Você pode configurar servidores MCP em código ao chamar `query()`, ou em um arquivo `.mcp.json` carregado via [`settingSources`](#from-a-config-file).

76 80 

77### Em código81<h3 id="in-code">

82 Em código

83</h3>

78 84 

79Passe servidores MCP diretamente na opção `mcpServers`:85Passe servidores MCP diretamente na opção `mcpServers`:

80 86 


129 ```135 ```

130</CodeGroup>136</CodeGroup>

131 137 

132### De um arquivo de configuração138<h3 id="from-a-config-file">

139 De um arquivo de configuração

140</h3>

133 141 

134Crie um arquivo `.mcp.json` na raiz do seu projeto. O arquivo é detectado quando a fonte de configuração `project` está habilitada, o que é padrão para as opções `query()`. Se você definir `settingSources` explicitamente, inclua `"project"` para que este arquivo seja carregado:142Crie um arquivo `.mcp.json` na raiz do seu projeto. O arquivo é detectado quando a fonte de configuração `project` está habilitada, o que é padrão para as opções `query()`. Se você definir `settingSources` explicitamente, inclua `"project"` para que este arquivo seja carregado:

135 143 


144}152}

145```153```

146 154 

147## Permitir ferramentas MCP155<h2 id="allow-mcp-tools">

156 Permitir ferramentas MCP

157</h2>

148 158 

149As ferramentas MCP requerem permissão explícita antes que Claude possa usá-las. Sem permissão, Claude verá que as ferramentas estão disponíveis, mas não poderá chamá-las.159As ferramentas MCP requerem permissão explícita antes que Claude possa usá-las. Sem permissão, Claude verá que as ferramentas estão disponíveis, mas não poderá chamá-las.

150 160 

151### Convenção de nomenclatura de ferramentas161<h3 id="tool-naming-convention">

162 Convenção de nomenclatura de ferramentas

163</h3>

152 164 

153As ferramentas MCP seguem o padrão de nomenclatura `mcp__<server-name>__<tool-name>`. Por exemplo, um servidor GitHub nomeado `"github"` com uma ferramenta `list_issues` se torna `mcp__github__list_issues`.165As ferramentas MCP seguem o padrão de nomenclatura `mcp__<server-name>__<tool-name>`. Por exemplo, um servidor GitHub nomeado `"github"` com uma ferramenta `list_issues` se torna `mcp__github__list_issues`.

154 166 

155### Aprovação automática com allowedTools167<h3 id="auto-approve-with-allowedtools">

168 Aprovação automática com allowedTools

169</h3>

156 170 

157Use `allowedTools` para aprovar automaticamente ferramentas MCP específicas para que Claude possa usá-las sem um prompt de permissão:171Use `allowedTools` para aprovar automaticamente ferramentas MCP específicas para que Claude possa usá-las sem um prompt de permissão:

158 172 


177 **Prefira `allowedTools` em vez de modos de permissão para acesso MCP.** `permissionMode: "acceptEdits"` não aprova automaticamente ferramentas MCP (apenas edições de arquivo e comandos Bash do sistema de arquivos). `permissionMode: "bypassPermissions"` aprova automaticamente ferramentas MCP, mas também desabilita todos os outros prompts de segurança, o que é mais amplo do que necessário. Um curinga em `allowedTools` concede exatamente o servidor MCP que você deseja e nada mais. Consulte [Modos de permissão](/pt/agent-sdk/permissions#permission-modes) para uma comparação completa.191 **Prefira `allowedTools` em vez de modos de permissão para acesso MCP.** `permissionMode: "acceptEdits"` não aprova automaticamente ferramentas MCP (apenas edições de arquivo e comandos Bash do sistema de arquivos). `permissionMode: "bypassPermissions"` aprova automaticamente ferramentas MCP, mas também desabilita todos os outros prompts de segurança, o que é mais amplo do que necessário. Um curinga em `allowedTools` concede exatamente o servidor MCP que você deseja e nada mais. Consulte [Modos de permissão](/pt/agent-sdk/permissions#permission-modes) para uma comparação completa.

178</Note>192</Note>

179 193 

180### Descobrir ferramentas disponíveis194<h3 id="discover-available-tools">

195 Descobrir ferramentas disponíveis

196</h3>

181 197 

182Para ver quais ferramentas um servidor MCP fornece, verifique a documentação do servidor ou conecte ao servidor e inspecione a mensagem de inicialização `system`:198Para ver quais ferramentas um servidor MCP fornece, verifique a documentação do servidor ou conecte ao servidor e inspecione a mensagem de inicialização `system`:

183 199 


189}205}

190```206```

191 207 

192## Tipos de transporte208<h2 id="transport-types">

209 Tipos de transporte

210</h2>

193 211 

194Os servidores MCP se comunicam com seu agente usando diferentes protocolos de transporte. Verifique a documentação do servidor para ver qual transporte ele suporta:212Os servidores MCP se comunicam com seu agente usando diferentes protocolos de transporte. Verifique a documentação do servidor para ver qual transporte ele suporta:

195 213 


197* Se a documentação fornecer uma **URL**, use HTTP ou SSE215* Se a documentação fornecer uma **URL**, use HTTP ou SSE

198* Se você estiver construindo suas próprias ferramentas em código, use um servidor MCP SDK216* Se você estiver construindo suas próprias ferramentas em código, use um servidor MCP SDK

199 217 

200### Servidores stdio218<h3 id="stdio-servers">

219 Servidores stdio

220</h3>

201 221 

202Processos locais que se comunicam via stdin/stdout. Use isso para servidores MCP que você executa na mesma máquina:222Processos locais que se comunicam via stdin/stdout. Use isso para servidores MCP que você executa na mesma máquina:

203 223 


253 </Tab>273 </Tab>

254</Tabs>274</Tabs>

255 275 

256### Servidores HTTP/SSE276<h3 id="http/sse-servers">

277 Servidores HTTP/SSE

278</h3>

257 279 

258Use HTTP ou SSE para servidores MCP hospedados em nuvem e APIs remotas:280Use HTTP ou SSE para servidores MCP hospedados em nuvem e APIs remotas:

259 281 


311 333 

312Para o transporte HTTP em fluxo contínuo, use `"type": "http"` em vez disso. Em `.mcp.json` e outros arquivos de configuração JSON, `"streamable-http"` é aceito como um alias para `"http"`. A opção programática `mcpServers` aceita apenas `"http"`.334Para o transporte HTTP em fluxo contínuo, use `"type": "http"` em vez disso. Em `.mcp.json` e outros arquivos de configuração JSON, `"streamable-http"` é aceito como um alias para `"http"`. A opção programática `mcpServers` aceita apenas `"http"`.

313 335 

314### Servidores MCP SDK336<h3 id="sdk-mcp-servers">

337 Servidores MCP SDK

338</h3>

315 339 

316Defina ferramentas personalizadas diretamente no código da sua aplicação em vez de executar um processo de servidor separado. Consulte o [guia de ferramentas personalizadas](/pt/agent-sdk/custom-tools) para detalhes de implementação.340Defina ferramentas personalizadas diretamente no código da sua aplicação em vez de executar um processo de servidor separado. Consulte o [guia de ferramentas personalizadas](/pt/agent-sdk/custom-tools) para detalhes de implementação.

317 341 

318## Busca de ferramentas MCP342<h2 id="mcp-tool-search">

343 Busca de ferramentas MCP

344</h2>

319 345 

320Quando você tem muitas ferramentas MCP configuradas, as definições de ferramentas podem consumir uma porção significativa de sua janela de contexto. A busca de ferramentas resolve isso retendo as definições de ferramentas do contexto e carregando apenas as que Claude precisa para cada turno.346Quando você tem muitas ferramentas MCP configuradas, as definições de ferramentas podem consumir uma porção significativa de sua janela de contexto. A busca de ferramentas resolve isso retendo as definições de ferramentas do contexto e carregando apenas as que Claude precisa para cada turno.

321 347 


323 349 

324Para mais detalhes, incluindo melhores práticas e uso de busca de ferramentas com ferramentas SDK personalizadas, consulte o [guia de busca de ferramentas](/pt/agent-sdk/tool-search).350Para mais detalhes, incluindo melhores práticas e uso de busca de ferramentas com ferramentas SDK personalizadas, consulte o [guia de busca de ferramentas](/pt/agent-sdk/tool-search).

325 351 

326## Autenticação352<h2 id="authentication">

353 Autenticação

354</h2>

327 355 

328A maioria dos servidores MCP requer autenticação para acessar serviços externos. Passe credenciais através de variáveis de ambiente na configuração do servidor.356A maioria dos servidores MCP requer autenticação para acessar serviços externos. Passe credenciais através de variáveis de ambiente na configuração do servidor.

329 357 

330### Passar credenciais via variáveis de ambiente358<h3 id="pass-credentials-via-environment-variables">

359 Passar credenciais via variáveis de ambiente

360</h3>

331 361 

332Use o campo `env` para passar chaves de API, tokens e outras credenciais para o servidor MCP:362Use o campo `env` para passar chaves de API, tokens e outras credenciais para o servidor MCP:

333 363 


387 417 

388Consulte [Listar problemas de um repositório](#list-issues-from-a-repository) para um exemplo completo e funcional com registro de depuração.418Consulte [Listar problemas de um repositório](#list-issues-from-a-repository) para um exemplo completo e funcional com registro de depuração.

389 419 

390### Cabeçalhos HTTP para servidores remotos420<h3 id="http-headers-for-remote-servers">

421 Cabeçalhos HTTP para servidores remotos

422</h3>

391 423 

392Para servidores HTTP e SSE, passe cabeçalhos de autenticação diretamente na configuração do servidor:424Para servidores HTTP e SSE, passe cabeçalhos de autenticação diretamente na configuração do servidor:

393 425 


445 </Tab>477 </Tab>

446</Tabs>478</Tabs>

447 479 

448### Autenticação OAuth2480<h3 id="oauth2-authentication">

481 Autenticação OAuth2

482</h3>

449 483 

450A [especificação MCP suporta OAuth 2.1](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) para autorização. O SDK não trata fluxos OAuth automaticamente, mas você pode passar tokens de acesso via cabeçalhos após completar o fluxo OAuth em sua aplicação:484A [especificação MCP suporta OAuth 2.1](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) para autorização. O SDK não trata fluxos OAuth automaticamente, mas você pode passar tokens de acesso via cabeçalhos após completar o fluxo OAuth em sua aplicação:

451 485 


485 ```519 ```

486</CodeGroup>520</CodeGroup>

487 521 

488## Exemplos522<h2 id="examples">

523 Exemplos

524</h2>

489 525 

490### Listar problemas de um repositório526<h3 id="list-issues-from-a-repository">

527 Listar problemas de um repositório

528</h3>

491 529 

492Este exemplo conecta ao [servidor GitHub MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/github) para listar problemas recentes. O exemplo inclui registro de depuração para verificar a conexão MCP e chamadas de ferramentas.530Este exemplo conecta ao [servidor GitHub MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/github) para listar problemas recentes. O exemplo inclui registro de depuração para verificar a conexão MCP e chamadas de ferramentas.

493 531 


584 ```622 ```

585</CodeGroup>623</CodeGroup>

586 624 

587### Consultar um banco de dados625<h3 id="query-a-database">

626 Consultar um banco de dados

627</h3>

588 628 

589Este exemplo usa o [servidor Postgres MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) para consultar um banco de dados. A string de conexão é passada como um argumento para o servidor. O agente descobre automaticamente o esquema do banco de dados, escreve a consulta SQL e retorna os resultados:629Este exemplo usa o [servidor Postgres MCP](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) para consultar um banco de dados. A string de conexão é passada como um argumento para o servidor. O agente descobre automaticamente o esquema do banco de dados, escreve a consulta SQL e retorna os resultados:

590 630 


655 ```695 ```

656</CodeGroup>696</CodeGroup>

657 697 

658## Tratamento de erros698<h2 id="error-handling">

699 Tratamento de erros

700</h2>

659 701 

660Os servidores MCP podem falhar ao conectar por vários motivos: o processo do servidor pode não estar instalado, as credenciais podem ser inválidas ou um servidor remoto pode estar inacessível.702Os servidores MCP podem falhar ao conectar por vários motivos: o processo do servidor pode não estar instalado, as credenciais podem ser inválidas ou um servidor remoto pode estar inacessível.

661 703 


717 ```759 ```

718</CodeGroup>760</CodeGroup>

719 761 

720## Solução de problemas762<h2 id="troubleshooting">

763 Solução de problemas

764</h2>

721 765 

722### Servidor mostra status "failed"766<h3 id="server-shows-failed-status">

767 Servidor mostra status "failed"

768</h3>

723 769 

724Verifique a mensagem `init` para ver quais servidores falharam ao conectar:770Verifique a mensagem `init` para ver quais servidores falharam ao conectar:

725 771 


740* **String de conexão inválida**: Para servidores de banco de dados, verifique o formato da string de conexão e se o banco de dados está acessível.786* **String de conexão inválida**: Para servidores de banco de dados, verifique o formato da string de conexão e se o banco de dados está acessível.

741* **Problemas de rede**: Para servidores HTTP/SSE remotos, verifique se a URL está acessível e se algum firewall permite a conexão.787* **Problemas de rede**: Para servidores HTTP/SSE remotos, verifique se a URL está acessível e se algum firewall permite a conexão.

742 788 

743### Ferramentas não sendo chamadas789<h3 id="tools-not-being-called">

790 Ferramentas não sendo chamadas

791</h3>

744 792 

745Se Claude vê ferramentas mas não as usa, verifique se você concedeu permissão com `allowedTools`:793Se Claude vê ferramentas mas não as usa, verifique se você concedeu permissão com `allowedTools`:

746 794 


755};803};

756```804```

757 805 

758### Tempos limite de conexão806<h3 id="connection-timeouts">

807 Tempos limite de conexão

808</h3>

759 809 

760O SDK MCP tem um tempo limite padrão de 60 segundos para conexões de servidor. Se seu servidor levar mais tempo para iniciar, a conexão falhará. Para servidores que precisam de mais tempo de inicialização, considere:810O SDK MCP tem um tempo limite padrão de 60 segundos para conexões de servidor. Se seu servidor levar mais tempo para iniciar, a conexão falhará. Para servidores que precisam de mais tempo de inicialização, considere:

761 811 


763* Pré-aquecer o servidor antes de iniciar seu agente813* Pré-aquecer o servidor antes de iniciar seu agente

764* Verificar logs do servidor para causas de inicialização lenta814* Verificar logs do servidor para causas de inicialização lenta

765 815 

766## Recursos relacionados816<h2 id="related-resources">

817 Recursos relacionados

818</h2>

767 819 

768* **[Guia de ferramentas personalizadas](/pt/agent-sdk/custom-tools)**: Construa seu próprio servidor MCP que é executado em processo com sua aplicação SDK820* **[Guia de ferramentas personalizadas](/pt/agent-sdk/custom-tools)**: Construa seu próprio servidor MCP que é executado em processo com sua aplicação SDK

769* **[Permissões](/pt/agent-sdk/permissions)**: Controle quais ferramentas MCP seu agente pode usar com `allowedTools` e `disallowedTools`821* **[Permissões](/pt/agent-sdk/permissions)**: Controle quais ferramentas MCP seu agente pode usar com `allowedTools` e `disallowedTools`

Details

12 12 

13O Claude Code SDK foi renomeado para o **Claude Agent SDK** e sua documentação foi reorganizada. Esta mudança reflete as capacidades mais amplas do SDK para construir agentes de IA além de apenas tarefas de codificação.13O Claude Code SDK foi renomeado para o **Claude Agent SDK** e sua documentação foi reorganizada. Esta mudança reflete as capacidades mais amplas do SDK para construir agentes de IA além de apenas tarefas de codificação.

14 14 

15<h2 id="what-s-changed">15<h2 id="whats-changed">

16 O Que Mudou16 O Que Mudou

17</h2>17</h2>

18 18 


82}82}

83```83```

84 84 

85Pronto! Nenhuma outra alteração de código é necessária.85**5. Revise [mudanças significativas](#breaking-changes)**

86 

87Faça as alterações de código necessárias para concluir a migração.

86 88 

87<h3 id="for-python-projects">89<h3 id="for-python-projects">

88 Para Projetos Python90 Para Projetos Python


172 174 

173<CodeGroup>175<CodeGroup>

174 ```typescript TypeScript theme={null}176 ```typescript TypeScript theme={null}

177 import { query } from "@anthropic-ai/claude-agent-sdk";

178 

175 // ANTES (v0.0.x) - Usava o prompt do sistema do Claude Code por padrão179 // ANTES (v0.0.x) - Usava o prompt do sistema do Claude Code por padrão

176 const result = query({ prompt: "Hello" });180 const before = query({ prompt: "Hello" });

177 181 

178 // DEPOIS (v0.1.0) - Usa prompt do sistema mínimo por padrão182 // DEPOIS (v0.1.0) - Usa prompt do sistema mínimo por padrão

179 // Para obter o comportamento antigo, solicite explicitamente a predefinição do Claude Code:183 // Para obter o comportamento antigo, solicite explicitamente a predefinição do Claude Code:

180 const result = query({184 const presetResult = query({

181 prompt: "Hello",185 prompt: "Hello",

182 options: {186 options: {

183 systemPrompt: { type: "preset", preset: "claude_code" }187 systemPrompt: { type: "preset", preset: "claude_code" }


185 });189 });

186 190 

187 // Ou use um prompt do sistema personalizado:191 // Ou use um prompt do sistema personalizado:

188 const result = query({192 const customResult = query({

189 prompt: "Hello",193 prompt: "Hello",

190 options: {194 options: {

191 systemPrompt: "You are a helpful coding assistant"195 systemPrompt: "You are a helpful coding assistant"


233 237 

234<CodeGroup>238<CodeGroup>

235 ```typescript TypeScript theme={null}239 ```typescript TypeScript theme={null}

236 const result = query({240 import { query } from "@anthropic-ai/claude-agent-sdk";

241 

242 const isolatedResult = query({

237 prompt: "Hello",243 prompt: "Hello",

238 options: {244 options: {

239 settingSources: [] // Nenhuma configuração do sistema de arquivos carregada245 settingSources: [] // Nenhuma configuração do sistema de arquivos carregada


241 });247 });

242 248 

243 // Ou carregue apenas fontes específicas:249 // Ou carregue apenas fontes específicas:

244 const result = query({250 const projectOnlyResult = query({

245 prompt: "Hello",251 prompt: "Hello",

246 options: {252 options: {

247 settingSources: ["project"] // Apenas configurações do projeto253 settingSources: ["project"] // Apenas configurações do projeto

Details

199 ...process.env,199 ...process.env,

200 // ... exporter configuration ...200 // ... exporter configuration ...

201 OTEL_SERVICE_NAME: "support-triage-agent",201 OTEL_SERVICE_NAME: "support-triage-agent",

202 OTEL_RESOURCE_ATTRIBUTES:202 OTEL_RESOURCE_ATTRIBUTES":

203 "service.version=1.4.0,deployment.environment=production",203 "service.version=1.4.0,deployment.environment=production",

204 },204 },

205 };205 };

Details

27 Verifique as regras `deny` (de `disallowed_tools` e [settings.json](/pt/settings#permission-settings)). Se uma regra de negação corresponder, a ferramenta é bloqueada, mesmo no modo `bypassPermissions`. Entradas com nome simples como `Bash` removem a ferramenta do contexto do Claude antes desta avaliação começar, portanto apenas regras com escopo como `Bash(rm *)` são verificadas neste passo.27 Verifique as regras `deny` (de `disallowed_tools` e [settings.json](/pt/settings#permission-settings)). Se uma regra de negação corresponder, a ferramenta é bloqueada, mesmo no modo `bypassPermissions`. Entradas com nome simples como `Bash` removem a ferramenta do contexto do Claude antes desta avaliação começar, portanto apenas regras com escopo como `Bash(rm *)` são verificadas neste passo.

28 </Step>28 </Step>

29 29 

30 <Step title="Regras de pergunta">

31 Verifique as regras `ask` de [settings.json](/pt/settings#permission-settings). Se uma regra de pergunta corresponder, a chamada passa para seu callback [`canUseTool`](/pt/agent-sdk/user-input) para confirmação, mesmo no modo `bypassPermissions`. No modo `dontAsk`, uma regra de pergunta correspondente é negada, porque esse modo nunca solicita.

32 </Step>

33 

30 <Step title="Modo de permissão">34 <Step title="Modo de permissão">

31 Aplique o [modo de permissão](#permission-modes) ativo. `bypassPermissions` aprova tudo que chega a este passo. `acceptEdits` aprova operações de arquivo. Outros modos passam adiante.35 Aplique o [modo de permissão](#permission-modes) ativo. `bypassPermissions` aprova tudo que chega a este passo. `acceptEdits` aprova operações de arquivo. `plan` roteia ferramentas de edição de arquivo e escrita de shell para seu callback `canUseTool` independentemente das regras de permitir, portanto operações de escrita não podem ser aprovadas automaticamente durante o planejamento. Outros modos passam adiante.

32 </Step>36 </Step>

33 37 

34 <Step title="Regras de permissão">38 <Step title="Regras de permissão">


40 </Step>44 </Step>

41</Steps>45</Steps>

42 46 

43<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=cc94220087262cd48c9b64a14c4e1c2c" alt="Diagrama de fluxo de avaliação de permissões" width="1024" height="260" data-path="images/agent-sdk/permissions-flow.svg" />47<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=cc94220087262cd48c9b64a14c4e1c2c" alt="Diagrama do fluxo de avaliação de permissões em cinco etapas correspondendo aos passos acima: uma solicitação de ferramenta passa por hooks, regras de negação, modo de permissão, regras de permissão e canUseTool. Hooks, regras de negação e canUseTool podem rotear para Bloqueado; bypass de modo de permissão, regras de permissão e canUseTool podem rotear para Executar." width="1024" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

44 48 

45Esta página se concentra em **regras de permitir e negar** e **modos de permissão**. Para os outros passos:49Esta página se concentra em **regras de permitir e negar** e **modos de permissão**. Para os outros passos:

46 50 


54`allowed_tools` e `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) adicionam entradas às listas de regras de permitir e negar no fluxo de avaliação acima. Regras de permitir afetam apenas a aprovação: uma ferramenta não listada em `allowed_tools` ainda está disponível para Claude e passa para o modo de permissão. Regras de negar se comportam de forma diferente dependendo se nomeiam uma ferramenta ou definem um padrão dentro de uma.58`allowed_tools` e `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) adicionam entradas às listas de regras de permitir e negar no fluxo de avaliação acima. Regras de permitir afetam apenas a aprovação: uma ferramenta não listada em `allowed_tools` ainda está disponível para Claude e passa para o modo de permissão. Regras de negar se comportam de forma diferente dependendo se nomeiam uma ferramenta ou definem um padrão dentro de uma.

55 59 

56| Opção | Efeito |60| Opção | Efeito |

57| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |61| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

58| `allowed_tools=["Read", "Grep"]` | `Read` e `Grep` são auto-aprovadas. Ferramentas não listadas aqui ainda existem e passam para o modo de permissão e `canUseTool`. |62| `allowed_tools=["Read", "Grep"]` | `Read` e `Grep` são auto-aprovadas. Ferramentas não listadas aqui ainda existem e passam para o modo de permissão e `canUseTool`. |

59| `disallowed_tools=["Bash"]` | A definição da ferramenta `Bash` é removida da solicitação. Claude não vê a ferramenta e não pode tentar usá-la. |63| `disallowed_tools=["Bash"]` | A definição da ferramenta `Bash` é removida da solicitação. Claude não vê a ferramenta e não pode tentar usá-la. |

60| `disallowed_tools=["Bash(rm *)"]` | `Bash` permanece disponível. Chamadas correspondentes a `rm *` são negadas em todos os modos de permissão, incluindo `bypassPermissions`. Outras chamadas de `Bash` passam para o modo de permissão. |64| `disallowed_tools=["Bash(rm *)"]` | `Bash` permanece disponível. Chamadas correspondentes a `rm *` são negadas em todos os modos de permissão, incluindo `bypassPermissions`. Outras chamadas de `Bash` passam para o modo de permissão. |

65| `disallowed_tools=["*"]` | Toda definição de ferramenta é removida da solicitação. Globs de nome de ferramenta são suportados em regras de negar: `"*"` corresponde a todas as ferramentas e `"mcp__*"` corresponde a todas as ferramentas MCP em todos os servidores. |

66 

67Regras de permitir aceitam globs de nome de ferramenta apenas após um prefixo literal `mcp__<server>__`. O segmento do servidor deve estar livre de glob para que a regra nomeie um servidor específico que você configurou: `mcp__puppeteer__*` corresponde a todas as ferramentas do servidor `puppeteer`, e `mcp__github__get_*` corresponde às suas ferramentas `get_`. Uma entrada não ancorada como `allowed_tools=["*"]` ou `allowed_tools=["mcp__*"]` é ignorada com um aviso de inicialização e não auto-aprova nada.

61 68 

62Para um agente bloqueado, combine `allowedTools` com `permissionMode: "dontAsk"`. Ferramentas listadas são aprovadas; qualquer outra coisa é negada completamente em vez de solicitar:69Para um agente bloqueado, combine `allowedTools` com `permissionMode: "dontAsk"`. Ferramentas listadas são aprovadas; qualquer outra coisa é negada completamente em vez de solicitar:

63 70 


87O SDK suporta estes modos de permissão:94O SDK suporta estes modos de permissão:

88 95 

89| Modo | Descrição | Comportamento da ferramenta |96| Modo | Descrição | Comportamento da ferramenta |

90| :------------------------- | :----------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |97| :------------------------- | :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

91| `default` | Comportamento de permissão padrão | Sem auto-aprovações; ferramentas não correspondidas acionam seu callback `canUseTool` |98| `default` | Comportamento de permissão padrão | Sem auto-aprovações; ferramentas não correspondidas acionam seu callback `canUseTool` |

92| `dontAsk` | Negar em vez de solicitar | Qualquer coisa não pré-aprovada por `allowed_tools` ou regras é negada; `canUseTool` nunca é chamado |99| `dontAsk` | Negar em vez de solicitar | Qualquer coisa não pré-aprovada por `allowed_tools` ou regras é negada; `canUseTool` nunca é chamado |

93| `acceptEdits` | Auto-aceitar edições de arquivo | Edições de arquivo e [operações de sistema de arquivos](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) são automaticamente aprovadas |100| `acceptEdits` | Auto-aceitar edições de arquivo | Edições de arquivo e [operações de sistema de arquivos](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) são automaticamente aprovadas |

94| `bypassPermissions` | Ignorar todas as verificações de permissão | Todas as ferramentas são executadas sem solicitações de permissão (use com cuidado) |101| `bypassPermissions` | Ignorar verificações de permissão | As ferramentas são executadas sem solicitações de permissão, a menos que uma regra [`ask`](#how-permissions-are-evaluated) explícita corresponda (use com cuidado) |

95| `plan` | Modo de planejamento | Ferramentas somente leitura são executadas; Claude analisa e planeja sem editar seus arquivos de origem |102| `plan` | Modo de planejamento | Claude explora e planeja sem editar seus arquivos de origem; edições de arquivo nunca são auto-aprovadas e solicitam através de seu callback `canUseTool` |

96| `auto` (Apenas TypeScript) | Aprovações classificadas por modelo | Um classificador de modelo aprova ou nega cada chamada de ferramenta. Consulte [Modo Auto](/pt/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidade |103| `auto` (Apenas TypeScript) | Aprovações classificadas por modelo | Um classificador de modelo aprova ou nega cada chamada de ferramenta. Consulte [Modo Auto](/pt/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidade |

97 104 

98<Warning>105<Warning>

99 **Herança de subagentos:** Quando o pai usa `bypassPermissions`, `acceptEdits` ou `auto`, todos os subagentos herdam esse modo e ele não pode ser substituído por subagentos. Subagentos podem ter prompts de sistema diferentes e comportamento menos restrito do que seu agente principal, portanto herdar `bypassPermissions` concede a eles acesso completo e autônomo ao sistema sem nenhum prompt de aprovação.106 **Herança de subagentos:** Quando o pai usa `bypassPermissions`, `acceptEdits` ou `auto`, todos os subagentos herdam esse modo e ele não pode ser substituído por subagentos. Subagentos podem ter prompts de sistema diferentes e comportamento menos restrito do que seu agente principal, portanto herdar `bypassPermissions` concede a eles acesso completo e autônomo ao sistema. Uma regra [`ask`](#how-permissions-are-evaluated) explícita ainda força uma solicitação.

100</Warning>107</Warning>

101 108 

102<h3 id="set-permission-mode">109<h3 id="set-permission-mode">


226 233 

227**Use quando:** você confia nas edições de Claude e quer iteração mais rápida, como durante prototipagem ou ao trabalhar em um diretório isolado.234**Use quando:** você confia nas edições de Claude e quer iteração mais rápida, como durante prototipagem ou ao trabalhar em um diretório isolado.

228 235 

229<h4 id="don-t-ask-mode-dontask">236<h4 id="dont-ask-mode-dontask">

230 Modo não perguntar (`dontAsk`)237 Modo não perguntar (`dontAsk`)

231</h4>238</h4>

232 239 


250 Modo plano (`plan`)257 Modo plano (`plan`)

251</h4>258</h4>

252 259 

253Restringe Claude a ferramentas somente leitura. Claude pode ler arquivos e executar comandos shell somente leitura para explorar a base de código, mas não edita seus arquivos de origem. Claude pode usar `AskUserQuestion` para esclarecer requisitos antes de finalizar o plano. Consulte [Lidar com aprovações e entrada do usuário](/pt/agent-sdk/user-input#handle-clarifying-questions) para lidar com essas solicitações.260Claude explora a base de código e produz um plano sem editar seus arquivos de origem. Ferramentas somente leitura são executadas como no modo padrão. Edições de arquivo nunca são auto-aprovadas no modo plano, mesmo quando uma regra de permitir corresponde. Elas solicitam através de seu callback `canUseTool` em vez disso. Claude pode usar `AskUserQuestion` para esclarecer requisitos antes de finalizar o plano. Consulte [Lidar com aprovações e entrada do usuário](/pt/agent-sdk/user-input#handle-clarifying-questions) para lidar com essas solicitações.

254 261 

255**Use quando:** você quer que Claude proponha mudanças sem executá-las, como durante revisão de código ou quando você precisa aprovar mudanças antes que sejam feitas.262**Use quando:** você quer que Claude proponha mudanças sem executá-las, como durante revisão de código ou quando você precisa aprovar mudanças antes que sejam feitas.

256 263 

Details

132) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]132) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

133```133```

134 134 

135<h4 id="parameters">135<h4 id="parameters-1">

136 Parâmetros136 Parâmetros

137</h4>137</h4>

138 138 


165 }165 }

166 ```166 ```

167 167 

168<h4 id="returns">168<h4 id="returns-1">

169 Retorna169 Retorna

170</h4>170</h4>

171 171 


228) -> McpSdkServerConfig228) -> McpSdkServerConfig

229```229```

230 230 

231<h4 id="parameters">231<h4 id="parameters-2">

232 Parâmetros232 Parâmetros

233</h4>233</h4>

234 234 


238| `version` | `str` | `"1.0.0"` | String de versão do servidor |238| `version` | `str` | `"1.0.0"` | String de versão do servidor |

239| `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | Lista de funções de ferramenta criadas com decorador `@tool` |239| `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | Lista de funções de ferramenta criadas com decorador `@tool` |

240 240 

241<h4 id="returns">241<h4 id="returns-2">

242 Retorna242 Retorna

243</h4>243</h4>

244 244 

245Retorna um objeto `McpSdkServerConfig` que pode ser passado para `ClaudeAgentOptions.mcp_servers`.245Retorna um objeto `McpSdkServerConfig` que pode ser passado para `ClaudeAgentOptions.mcp_servers`.

246 246 

247<h4 id="example">247<h4 id="example-1">

248 Exemplo248 Exemplo

249</h4>249</h4>

250 250 


289) -> list[SDKSessionInfo]289) -> list[SDKSessionInfo]

290```290```

291 291 

292<h4 id="parameters">292<h4 id="parameters-3">

293 Parâmetros293 Parâmetros

294</h4>294</h4>

295 295 


316| `tag` | `str \| None` | Tag de sessão definida pelo usuário (veja [`tag_session()`](#tag_session)) |316| `tag` | `str \| None` | Tag de sessão definida pelo usuário (veja [`tag_session()`](#tag_session)) |

317| `created_at` | `int \| None` | Hora de criação da sessão em milissegundos desde a época |317| `created_at` | `int \| None` | Hora de criação da sessão em milissegundos desde a época |

318 318 

319<h4 id="example">319<h4 id="example-2">

320 Exemplo320 Exemplo

321</h4>321</h4>

322 322 


344) -> list[SessionMessage]344) -> list[SessionMessage]

345```345```

346 346 

347<h4 id="parameters">347<h4 id="parameters-4">

348 Parâmetros348 Parâmetros

349</h4>349</h4>

350 350 


367| `message` | `Any` | Conteúdo bruto da mensagem |367| `message` | `Any` | Conteúdo bruto da mensagem |

368| `parent_tool_use_id` | `None` | Reservado para uso futuro |368| `parent_tool_use_id` | `None` | Reservado para uso futuro |

369 369 

370<h4 id="example">370<h4 id="example-3">

371 Exemplo371 Exemplo

372</h4>372</h4>

373 373 


394) -> SDKSessionInfo | None394) -> SDKSessionInfo | None

395```395```

396 396 

397<h4 id="parameters">397<h4 id="parameters-5">

398 Parâmetros398 Parâmetros

399</h4>399</h4>

400 400 


405 405 

406Retorna [`SDKSessionInfo`](#return-type-sdksessioninfo), ou `None` se a sessão não for encontrada.406Retorna [`SDKSessionInfo`](#return-type-sdksessioninfo), ou `None` se a sessão não for encontrada.

407 407 

408<h4 id="example">408<h4 id="example-4">

409 Exemplo409 Exemplo

410</h4>410</h4>

411 411 


433) -> None433) -> None

434```434```

435 435 

436<h4 id="parameters">436<h4 id="parameters-6">

437 Parâmetros437 Parâmetros

438</h4>438</h4>

439 439 


445 445 

446Lança `ValueError` se `session_id` não for um UUID válido ou `title` estiver vazio; `FileNotFoundError` se a sessão não puder ser encontrada.446Lança `ValueError` se `session_id` não for um UUID válido ou `title` estiver vazio; `FileNotFoundError` se a sessão não puder ser encontrada.

447 447 

448<h4 id="example">448<h4 id="example-5">

449 Exemplo449 Exemplo

450</h4>450</h4>

451 451 


473) -> None473) -> None

474```474```

475 475 

476<h4 id="parameters">476<h4 id="parameters-7">

477 Parâmetros477 Parâmetros

478</h4>478</h4>

479 479 


485 485 

486Lança `ValueError` se `session_id` não for um UUID válido ou `tag` estiver vazio após sanitização; `FileNotFoundError` se a sessão não puder ser encontrada.486Lança `ValueError` se `session_id` não for um UUID válido ou `tag` estiver vazio após sanitização; `FileNotFoundError` se a sessão não puder ser encontrada.

487 487 

488<h4 id="example">488<h4 id="example-6">

489 Exemplo489 Exemplo

490</h4>490</h4>

491 491 


910| `max_budget_usd` | `float \| None` | `None` | Para a consulta quando a estimativa de custo do lado do cliente atinge este valor em USD. Comparado com a mesma estimativa que `total_cost_usd`; veja [Track cost and usage](/pt/agent-sdk/cost-tracking) para ressalvas de precisão |910| `max_budget_usd` | `float \| None` | `None` | Para a consulta quando a estimativa de custo do lado do cliente atinge este valor em USD. Comparado com a mesma estimativa que `total_cost_usd`; veja [Track cost and usage](/pt/agent-sdk/cost-tracking) para ressalvas de precisão |

911| `disallowed_tools` | `list[str]` | `[]` | Ferramentas para negar. Um nome simples como `"Bash"` remove a ferramenta do contexto do Claude. Uma regra com escopo como `"Bash(rm *)"` deixa a ferramenta disponível e nega chamadas correspondentes em todos os modos de permissão, incluindo `bypassPermissions`. Veja [Permissions](/pt/agent-sdk/permissions#allow-and-deny-rules) |911| `disallowed_tools` | `list[str]` | `[]` | Ferramentas para negar. Um nome simples como `"Bash"` remove a ferramenta do contexto do Claude. Uma regra com escopo como `"Bash(rm *)"` deixa a ferramenta disponível e nega chamadas correspondentes em todos os modos de permissão, incluindo `bypassPermissions`. Veja [Permissions](/pt/agent-sdk/permissions#allow-and-deny-rules) |

912| `enable_file_checkpointing` | `bool` | `False` | Ativa rastreamento de mudança de arquivo para retrocesso. Veja [File checkpointing](/pt/agent-sdk/file-checkpointing) |912| `enable_file_checkpointing` | `bool` | `False` | Ativa rastreamento de mudança de arquivo para retrocesso. Veja [File checkpointing](/pt/agent-sdk/file-checkpointing) |

913| `model` | `str \| None` | `None` | Modelo Claude a usar |913| `model` | `str \| None` | `None` | Alias de modelo Claude ou nome de modelo completo. Veja [valores aceitos e IDs específicos do provedor](/pt/model-config#available-models) |

914| `fallback_model` | `str \| None` | `None` | Modelo de fallback a usar se o modelo primário falhar |914| `fallback_model` | `str \| None` | `None` | Modelo de fallback a usar se o modelo primário falhar |

915| `betas` | `list[SdkBeta]` | `[]` | Recursos beta para ativar. Veja [`SdkBeta`](#sdkbeta) para opções disponíveis |915| `betas` | `list[SdkBeta]` | `[]` | Recursos beta para ativar. Veja [`SdkBeta`](#sdkbeta) para opções disponíveis |

916| `output_format` | `dict[str, Any] \| None` | `None` | Formato de saída para respostas estruturadas (por exemplo, `{"type": "json_schema", "schema": {...}}`). Veja [Structured outputs](/pt/agent-sdk/structured-outputs) para detalhes |916| `output_format` | `dict[str, Any] \| None` | `None` | Formato de saída para respostas estruturadas (por exemplo, `{"type": "json_schema", "schema": {...}}`). Veja [Structured outputs](/pt/agent-sdk/structured-outputs) para detalhes |


937| `skills` | `list[str] \| Literal["all"] \| None` | `None` | Skills disponíveis para a sessão. Passe `"all"` para ativar cada skill descoberto, ou uma lista de nomes de skills. Quando definido, o SDK ativa a ferramenta Skill automaticamente sem listá-la em `allowed_tools`. Veja [Skills](/pt/agent-sdk/skills) |937| `skills` | `list[str] \| Literal["all"] \| None` | `None` | Skills disponíveis para a sessão. Passe `"all"` para ativar cada skill descoberto, ou uma lista de nomes de skills. Quando definido, o SDK ativa a ferramenta Skill automaticamente sem listá-la em `allowed_tools`. Veja [Skills](/pt/agent-sdk/skills) |

938| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - Tokens máximos para blocos de pensamento. Use `thinking` em vez disso |938| `max_thinking_tokens` | `int \| None` | `None` | *Deprecated* - Tokens máximos para blocos de pensamento. Use `thinking` em vez disso |

939| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | Controla o comportamento de pensamento estendido. Tem precedência sobre `max_thinking_tokens` |939| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | Controla o comportamento de pensamento estendido. Tem precedência sobre `max_thinking_tokens` |

940| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | Nível de esforço para profundidade de pensamento |940| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | Nível de esforço para profundidade de pensamento. Veja [ajustar o nível de esforço](/pt/model-config#adjust-effort-level) |

941| `session_store` | [`SessionStore`](/pt/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Espelhe transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |941| `session_store` | [`SessionStore`](/pt/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Espelhe transcrições de sessão para um backend externo para que qualquer host possa retomá-las. Veja [Persist sessions to external storage](/pt/agent-sdk/session-storage) |

942| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Quando fazer flush das entradas de transcrição espelhadas para `session_store`. `"batched"` faz flush uma vez por turno ou quando o buffer enche; `"eager"` dispara um flush de fundo após cada frame. Ignorado quando `session_store` é `None` |942| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Quando fazer flush das entradas de transcrição espelhadas para `session_store`. `"batched"` faz flush uma vez por turno ou quando o buffer enche; `"eager"` dispara um flush de fundo após cada frame. Ignorado quando `session_store` é `None` |

943 943 


960* `API_TIMEOUT_MS`: timeout por solicitação no cliente Anthropic, em milissegundos. Padrão `600000`. Aplica-se ao loop principal e a todos os subagentes.960* `API_TIMEOUT_MS`: timeout por solicitação no cliente Anthropic, em milissegundos. Padrão `600000`. Aplica-se ao loop principal e a todos os subagentes.

961* `CLAUDE_CODE_MAX_RETRIES`: máximo de tentativas de API. Padrão `10`. Cada tentativa obtém sua própria janela `API_TIMEOUT_MS`, então o tempo de parede no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais backoff.961* `CLAUDE_CODE_MAX_RETRIES`: máximo de tentativas de API. Padrão `10`. Cada tentativa obtém sua própria janela `API_TIMEOUT_MS`, então o tempo de parede no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais backoff.

962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes lançados com `run_in_background`. Padrão `600000`. Redefine em cada evento de stream; em caso de travamento, aborta o subagente, marca a tarefa como falha e expõe o erro ao pai com qualquer resultado parcial. Não se aplica a subagentes síncronos.962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes lançados com `run_in_background`. Padrão `600000`. Redefine em cada evento de stream; em caso de travamento, aborta o subagente, marca a tarefa como falha e expõe o erro ao pai com qualquer resultado parcial. Não se aplica a subagentes síncronos.

963* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. Desativado por padrão. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. A solicitação abortada passa pelo caminho de tentativa normal.963* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. Quando `CLAUDE_ENABLE_STREAM_WATCHDOG` não está definido, o padrão é controlado pelo servidor na API Anthropic direta e desativado em outros provedores. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. A solicitação abortada passa pelo caminho de tentativa normal.

964 964 

965<h3 id="outputformat">965<h3 id="outputformat">

966 `OutputFormat`966 `OutputFormat`


996```996```

997 997 

998| Campo | Obrigatório | Descrição |998| Campo | Obrigatório | Descrição |

999| :------------------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |999| :------------------------- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1000| `type` | Sim | Deve ser `"preset"` para usar um prompt do sistema preset |1000| `type` | Sim | Deve ser `"preset"` para usar um prompt do sistema preset |

1001| `preset` | Sim | Deve ser `"claude_code"` para usar o prompt do sistema do Claude Code |1001| `preset` | Sim | Deve ser `"claude_code"` para usar o prompt do sistema do Claude Code |

1002| `append` | Não | Instruções adicionais para anexar ao prompt do sistema preset |1002| `append` | Não | Instruções adicionais para anexar ao prompt do sistema preset |

1003| `exclude_dynamic_sections` | Não | Mova contexto por sessão como diretório de trabalho, status git e caminhos de memória da prompt do sistema para a primeira mensagem do usuário. Melhora a reutilização de cache de prompt entre usuários e máquinas. Veja [Modify system prompts](/pt/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |1003| `exclude_dynamic_sections` | Não | Mova contexto por sessão como diretório de trabalho, sinalizador git-repo e caminhos de memória automática do prompt do sistema para a primeira mensagem do usuário. Melhora a reutilização de cache de prompt entre usuários e máquinas. Veja [Modify system prompts](/pt/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

1004 1004 

1005<h3 id="settingsource">1005<h3 id="settingsource">

1006 `SettingSource`1006 `SettingSource`


1016| :---------- | :--------------------------------------------------------------- | :---------------------------- |1016| :---------- | :--------------------------------------------------------------- | :---------------------------- |

1017| `"user"` | Configurações globais do usuário | `~/.claude/settings.json` |1017| `"user"` | Configurações globais do usuário | `~/.claude/settings.json` |

1018| `"project"` | Configurações de projeto compartilhadas (controladas por versão) | `.claude/settings.json` |1018| `"project"` | Configurações de projeto compartilhadas (controladas por versão) | `.claude/settings.json` |

1019| `"local"` | Configurações de projeto local (gitignored) | `.claude/settings.local.json` |1019| `"local"` | Configurações de projeto local (não controladas por versão) | `.claude/settings.local.json` |

1020 1020 

1021<h4 id="default-behavior">1021<h4 id="default-behavior">

1022 Comportamento padrão1022 Comportamento padrão


1160```1160```

1161 1161 

1162| Campo | Obrigatório | Descrição |1162| Campo | Obrigatório | Descrição |

1163| :---------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1163| :---------------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1164| `description` | Sim | Descrição em linguagem natural de quando usar este agente |1164| `description` | Sim | Descrição em linguagem natural de quando usar este agente |

1165| `prompt` | Sim | O prompt do sistema do agente |1165| `prompt` | Sim | O prompt do sistema do agente |

1166| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas |1166| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas |

1167| `disallowedTools` | Não | Array de nomes de ferramentas a remover do conjunto de ferramentas do agente |1167| `disallowedTools` | Não | Array de nomes de ferramentas a remover do conjunto de ferramentas do agente. Padrões de nível de servidor MCP também são aceitos: `mcp__server` ou `mcp__server__*` remove cada ferramenta desse servidor, e `mcp__*` remove cada ferramenta MCP de qualquer servidor |

1168| `model` | Não | Substituição de modelo para este agente. Aceita um alias como `"sonnet"`, `"opus"`, `"haiku"`, ou `"inherit"`, ou um ID de modelo completo. Se omitido, usa o modelo principal |1168| `model` | Não | Substituição de modelo para este agente. Aceita um alias como `"sonnet"`, `"opus"`, `"haiku"`, ou `"inherit"`, ou um ID de modelo completo. Se omitido, usa o modelo principal |

1169| `skills` | Não | Lista de nomes de skills a pré-carregar no contexto do agente na inicialização. Skills não listados permanecem invocáveis através da ferramenta Skill |1169| `skills` | Não | Lista de nomes de skills a pré-carregar no contexto do agente na inicialização. Skills não listados permanecem invocáveis através da ferramenta Skill |

1170| `memory` | Não | Fonte de memória para este agente: `"user"`, `"project"`, ou `"local"` |1170| `memory` | Não | Fonte de memória para este agente: `"user"`, `"project"`, ou `"local"` |


1189PermissionMode = Literal[1189PermissionMode = Literal[

1190 "default", # Standard permission behavior1190 "default", # Standard permission behavior

1191 "acceptEdits", # Auto-accept file edits1191 "acceptEdits", # Auto-accept file edits

1192 "plan", # Planning mode - read-only tools only1192 "plan", # Planning mode - explore without editing

1193 "dontAsk", # Deny anything not pre-approved instead of prompting1193 "dontAsk", # Deny anything not pre-approved instead of prompting

1194 "bypassPermissions", # Bypass all permission checks (use with caution)1194 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)

1195]1195]

1196```1196```

1197 1197 


1206 "low", # Minimal thinking, fastest responses1206 "low", # Minimal thinking, fastest responses

1207 "medium", # Moderate thinking1207 "medium", # Moderate thinking

1208 "high", # Deep reasoning1208 "high", # Deep reasoning

1209 "xhigh", # Extended reasoning (Opus 4.7 only; falls back to "high" on other models)1209 "xhigh", # Extended reasoning (Opus 4.8 and Opus 4.7; falls back to "high" on other models)

1210 "max", # Maximum effort1210 "max", # Maximum effort

1211]1211]

1212```1212```


1432Use com o campo `betas` em `ClaudeAgentOptions` para ativar recursos beta.1432Use com o campo `betas` em `ClaudeAgentOptions` para ativar recursos beta.

1433 1433 

1434<Warning>1434<Warning>

1435 O beta `context-1m-2025-08-07` foi descontinuado a partir de 30 de abril de 2026. Passar este cabeçalho com Claude Sonnet 4.5 ou Sonnet 4 não tem efeito, e solicitações que excedem a janela de contexto padrão de 200k-token retornam um erro. Para usar uma janela de contexto de 1M-token, migre para [Claude Sonnet 4.6, Claude Opus 4.6, ou Claude Opus 4.7](https://platform.claude.com/docs/en/about-claude/models/overview), que incluem contexto de 1M a preços padrão sem cabeçalho beta necessário.1435 O beta `context-1m-2025-08-07` foi descontinuado a partir de 30 de abril de 2026. Passar este cabeçalho com Claude Sonnet 4.5 ou Sonnet 4 não tem efeito, e solicitações que excedem a janela de contexto padrão de 200k-token retornam um erro. Para usar uma janela de contexto de 1M-token, migre para [Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7, ou Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview), que incluem contexto de 1M a preços padrão sem cabeçalho beta necessário.

1436</Warning>1436</Warning>

1437 1437 

1438<h3 id="mcpsdkserverconfig">1438<h3 id="mcpsdkserverconfig">


1706 uuid: str | None = None1706 uuid: str | None = None

1707```1707```

1708 1708 

1709O campo `subtype` determina quais outros campos são preenchidos. É um de `"success"`, `"error_during_execution"`, `"error_max_turns"`, `"error_max_budget_usd"` ou `"error_max_structured_output_retries"`. A dataclass Python achata todas as variantes em uma forma, portanto campos que não se aplicam ao subtipo retornado são `None`.

1710 

1711Vários campos carregam detalhes de diagnóstico quando a conversa termina em um erro:

1712 

1713* `is_error`: `True` quando a conversa terminou em um estado de erro. Sempre `True` nos subtipos `error_*`. Em `subtype="success"` é `True` quando a solicitação final do modelo falhou, significando que o loop do agente foi concluído mas a última chamada da API retornou um erro.

1714* `api_error_status`: o código de status HTTP do erro de API de encerramento. `None` quando o turno terminou sem um. Preenchido apenas em `subtype="success"`.

1715* `result`: texto da mensagem final do assistente em `subtype="success"`, ou `None` nos subtipos `error_*`. Quando `subtype="success"` e `is_error=True`, isso contém a string de erro da API se uma estiver disponível mas pode estar vazio, então verifique `api_error_status` e o conteúdo anterior de `AssistantMessage` para detalhes.

1716* `errors`: strings de erro no nível do loop, como a mensagem de máximo de turnos. Preenchido apenas nos subtipos `error_*`.

1717 

1709O dict `usage` contém as seguintes chaves quando presentes:1718O dict `usage` contém as seguintes chaves quando presentes:

1710 1719 

1711| Chave | Tipo | Descrição |1720| Chave | Tipo | Descrição |


2051 Tipos de Hook2060 Tipos de Hook

2052</h2>2061</h2>

2053 2062 

2054Para um guia abrangente sobre o uso de hooks com exemplos e padrões comuns, veja o [Hooks guide](/pt/agent-sdk/hooks).2063Para um guia abrangente sobre o uso de hooks com exemplos e padrões comuns, veja o [Guia de Hooks](/pt/agent-sdk/hooks).

2055 2064 

2056<h3 id="hookevent">2065<h3 id="hookevent">

2057 `HookEvent`2066 `HookEvent`


2431 `HookSpecificOutput`2440 `HookSpecificOutput`

2432</h4>2441</h4>

2433 2442 

2434Um `TypedDict` contendo o nome do evento de hook e campos específicos do evento. A forma depende do valor `hookEventName`. Para detalhes completos sobre campos disponíveis por evento de hook, veja [Control execution with hooks](/pt/agent-sdk/hooks#outputs).2443Um `TypedDict` contendo o nome do evento de hook e campos específicos do evento. A forma depende do valor `hookEventName`. Para detalhes completos sobre campos disponíveis por evento de hook, veja [Controlar execução com hooks](/pt/agent-sdk/hooks#outputs).

2435 2444 

2436Uma união discriminada de tipos de saída específicos do evento. O campo `hookEventName` determina quais campos são válidos.2445Uma união discriminada de tipos de saída específicos do evento. O campo `hookEventName` determina quais campos são válidos.

2437 2446 


3447 3456 

3448 3457 

3449async def create_project():3458async def create_project():

3450 options = Cl audeAgentOptions(3459 options = ClaudeAgentOptions(

3451 allowed_tools=["Read", "Write", "Bash"],3460 allowed_tools=["Read", "Write", "Bash"],

3452 permission_mode="acceptEdits",3461 permission_mode="acceptEdits",

3453 cwd="/home/user/project",3462 cwd="/home/user/project",


3625 Defina `"failIfUnavailable": True` nas suas configurações de sandbox para parar em vez disso. A chave ainda não está declarada em `SandboxSettings`, mas o SDK a encaminha para Claude Code, que a honra. `query()` então relata uma `ResultMessage` com `subtype="error_during_execution"` e a razão em `errors`. Observe esse subtipo em vez de esperar que `query()` lance antes de ceder mensagens.3634 Defina `"failIfUnavailable": True` nas suas configurações de sandbox para parar em vez disso. A chave ainda não está declarada em `SandboxSettings`, mas o SDK a encaminha para Claude Code, que a honra. `query()` então relata uma `ResultMessage` com `subtype="error_during_execution"` e a razão em `errors`. Observe esse subtipo em vez de esperar que `query()` lance antes de ceder mensagens.

3626</Note>3635</Note>

3627 3636 

3628<h4 id="example-usage">3637<h4 id="example-usage-1">

3629 Exemplo de uso3638 Exemplo de uso

3630</h4>3639</h4>

3631 3640 

Details

340**Modos de permissão** controlam quanto de supervisão humana você deseja:340**Modos de permissão** controlam quanto de supervisão humana você deseja:

341 341 

342| Modo | Comportamento | Caso de uso |342| Modo | Comportamento | Caso de uso |

343| -------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------ |343| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |

344| `acceptEdits` | Auto-aprova edições de arquivo e comandos comuns do sistema de arquivos, pede outras ações | Fluxos de trabalho de desenvolvimento confiáveis |344| `acceptEdits` | Auto-aprova edições de arquivo e comandos comuns do sistema de arquivos, pede outras ações | Fluxos de trabalho de desenvolvimento confiáveis |

345| `dontAsk` | Nega qualquer coisa não em `allowedTools` | Agentes headless bloqueados |345| `dontAsk` | Nega qualquer coisa não em `allowedTools` | Agentes headless bloqueados |

346| `auto` (apenas TypeScript) | Um classificador de modelo aprova ou nega cada chamada de ferramenta | Agentes autônomos com proteções de segurança |346| `auto` (apenas TypeScript) | Um classificador de modelo aprova ou nega cada chamada de ferramenta | Agentes autônomos com proteções de segurança |

347| `bypassPermissions` | Executa cada ferramenta sem prompts | CI em sandbox, ambientes totalmente confiáveis |347| `bypassPermissions` | Executa cada ferramenta sem prompts, a menos que uma regra [`ask`](/pt/agent-sdk/permissions#how-permissions-are-evaluated) explícita corresponda | CI em sandbox, ambientes totalmente confiáveis |

348| `default` | Requer um callback `canUseTool` para lidar com aprovação | Fluxos de aprovação personalizados |348| `default` | Requer um callback `canUseTool` para lidar com aprovação | Fluxos de aprovação personalizados |

349 349 

350O exemplo acima usa o modo `acceptEdits`, que auto-aprova operações de arquivo para que o agente possa executar sem prompts interativos. Se você quiser solicitar aprovação dos usuários, use o modo `default` e forneça um callback [`canUseTool`](/pt/agent-sdk/user-input) que coleta entrada do usuário. Para mais controle, veja [Permissões](/pt/agent-sdk/permissions).350O exemplo acima usa o modo `acceptEdits`, que auto-aprova operações de arquivo para que o agente possa executar sem prompts interativos. Se você quiser solicitar aprovação dos usuários, use o modo `default` e forneça um callback [`canUseTool`](/pt/agent-sdk/user-input) que coleta entrada do usuário. Para mais controle, veja [Permissões](/pt/agent-sdk/permissions).

Details

150 ```150 ```

151</CodeGroup>151</CodeGroup>

152 152 

153A segunda consulta imprime um resumo dos arquivos da primeira consulta, o que mostra que o agente retomou com contexto completo do store.

154 

153<h2 id="write-your-own-adapter">155<h2 id="write-your-own-adapter">

154 Escreva seu próprio adaptador156 Escreva seu próprio adaptador

155</h2>157</h2>

Details

230 ```230 ```

231 231 

232 ```typescript TypeScript theme={null}232 ```typescript TypeScript theme={null}

233 import { query } from "@anthropic-ai/claude-agent-sdk";

234 

235 const sessionId = "..."; // The ID you captured in the previous example

236 

233 // Earlier session analyzed the code; now build on that analysis237 // Earlier session analyzed the code; now build on that analysis

234 for await (const message of query({238 for await (const message of query({

235 prompt: "Now implement the refactoring you suggested",239 prompt: "Now implement the refactoring you suggested",


245 ```249 ```

246</CodeGroup>250</CodeGroup>

247 251 

252Você deve ver uma resposta que se baseia na análise anterior em vez de começar do zero. Isso confirma que o agente retomou a sessão com seu contexto anterior intacto.

253 

248<Tip>254<Tip>

249 Se uma chamada `resume` retornar uma sessão nova em vez do histórico esperado, a causa mais comum é um `cwd` incompatível. As sessões são armazenadas em `~/.claude/projects/<encoded-cwd>/*.jsonl`, onde `<encoded-cwd>` é o diretório de trabalho absoluto com cada caractere não alfanumérico substituído por `-` (então `/Users/me/proj` se torna `-Users-me-proj`). Se sua chamada resume for executada de um diretório diferente, o SDK procura no lugar errado. O arquivo de sessão também precisa existir na máquina atual.255 Se uma chamada `resume` retornar uma sessão nova em vez do histórico esperado, a causa mais comum é um `cwd` incompatível. As sessões são armazenadas em `~/.claude/projects/<encoded-cwd>/*.jsonl`, ou em `$CLAUDE_CONFIG_DIR/projects/<encoded-cwd>/*.jsonl` se você definir a variável de ambiente `CLAUDE_CONFIG_DIR`, onde `<encoded-cwd>` é o diretório de trabalho absoluto com cada caractere não alfanumérico substituído por `-` (então `/Users/me/proj` se torna `-Users-me-proj`). Se sua chamada resume for executada de um diretório diferente, o SDK procura no lugar errado. O arquivo de sessão também precisa existir na máquina atual.

250</Tip>256</Tip>

251 257 

252Para retomar sessões entre máquinas ou em ambientes sem servidor, espelhe transcrições para armazenamento compartilhado com um adaptador [`SessionStore`](/pt/agent-sdk/session-storage).258Para retomar sessões entre máquinas ou em ambientes sem servidor, espelhe transcrições para armazenamento compartilhado com um adaptador [`SessionStore`](/pt/agent-sdk/session-storage).


268 # Fork: branch from session_id into a new session274 # Fork: branch from session_id into a new session

269 forked_id = None275 forked_id = None

270 async for message in query(276 async for message in query(

271 prompt="Instead of JWT, implement OAuth2 for the auth module",277 prompt="Instead of JWT, outline how OAuth2 would work for the auth module",

272 options=ClaudeAgentOptions(278 options=ClaudeAgentOptions(

273 resume=session_id,279 resume=session_id,

274 fork_session=True,280 fork_session=True,

281 max_turns=5,

275 ),282 ),

276 ):283 ):

277 if isinstance(message, ResultMessage):284 if isinstance(message, ResultMessage):


291 ```298 ```

292 299 

293 ```typescript TypeScript theme={null}300 ```typescript TypeScript theme={null}

301 import { query } from "@anthropic-ai/claude-agent-sdk";

302 

303 const sessionId = "..."; // The ID you captured in the previous example

304 

294 // Fork: branch from sessionId into a new session305 // Fork: branch from sessionId into a new session

295 let forkedId: string | undefined;306 let forkedId: string | undefined;

296 307 

297 for await (const message of query({308 for await (const message of query({

298 prompt: "Instead of JWT, implement OAuth2 for the auth module",309 prompt: "Instead of JWT, outline how OAuth2 would work for the auth module",

299 options: {310 options: {

300 resume: sessionId,311 resume: sessionId,

301 forkSession: true312 forkSession: true,

313 maxTurns: 5

302 }314 }

303 })) {315 })) {

304 if (message.type === "system" && message.subtype === "init") {316 if (message.type === "system" && message.subtype === "init") {


323 ```335 ```

324</CodeGroup>336</CodeGroup>

325 337 

338Você deve ver que `forkedId` difere do ID de sessão original. Retomar a sessão original ainda continua o thread JWT, o que confirma que o fork não modificou o histórico original.

339 

326<h2 id="resume-across-hosts">340<h2 id="resume-across-hosts">

327 Retomar entre hosts341 Retomar entre hosts

328</h2>342</h2>


341</h2>355</h2>

342 356 

343* [How the agent loop works](/pt/agent-sdk/agent-loop): Entenda voltas, mensagens e acumulação de contexto dentro de uma sessão357* [How the agent loop works](/pt/agent-sdk/agent-loop): Entenda voltas, mensagens e acumulação de contexto dentro de uma sessão

344* [File checkpointing](/pt/agent-sdk/file-checkpointing): Rastreie e reverta alterações de arquivo entre sessões358* [File checkpointing](/pt/agent-sdk/file-checkpointing): Faça snapshot e reverta alterações de arquivo que o agente fez dentro de uma sessão

345* [Python `ClaudeAgentOptions`](/pt/agent-sdk/python#claudeagentoptions): Referência completa de opções de sessão para Python359* [Python `ClaudeAgentOptions`](/pt/agent-sdk/python#claudeagentoptions): Referência completa de opções de sessão para Python

346* [TypeScript `Options`](/pt/agent-sdk/typescript#options): Referência completa de opções de sessão para TypeScript360* [TypeScript `Options`](/pt/agent-sdk/typescript#options): Referência completa de opções de sessão para TypeScript

Details

101 parent_tool_use_id: string | null;101 parent_tool_use_id: string | null;

102 uuid: UUID;102 uuid: UUID;

103 session_id: string;103 session_id: string;

104 ttft_ms?: number; // Time to first token in ms, present only on message_start events

104 };105 };

105 ```106 ```

106</CodeGroup>107</CodeGroup>

Details

218 ```218 ```

219</CodeGroup>219</CodeGroup>

220 220 

221<Note>

222 No SDK TypeScript, se seu gerador de mensagens lançar uma exceção, por exemplo quando um arquivo que ele lê está faltando, o stream termina com um erro que diz `Claude Code process aborted by user` em vez do erro original, então verifique o código dentro do seu gerador primeiro quando você vir essa mensagem. O erro também pode ser precedido por uma longa linha minificada do código-fonte do SDK agrupado, então leia até o final da saída para encontrar o texto do erro.

223 

224 No SDK Python, uma exceção do gerador é registrada no nível de debug e a sessão trava sem lançar, então se uma sessão de streaming ficar pendurada sem saída, ative o registro de debug e verifique seu gerador.

225</Note>

226 

221<h2 id="single-message-input">227<h2 id="single-message-input">

222 Entrada de Mensagem Única228 Entrada de Mensagem Única

223</h2>229</h2>


247 * Conversas naturais com múltiplos turnos253 * Conversas naturais com múltiplos turnos

248</Warning>254</Warning>

249 255 

250<h3 id="implementation-example">256Se uma consulta terminar com um resultado de erro, como `error_max_turns`, uma chamada única de `query()` gera um erro que inclui o texto da falha após gerar a mensagem de resultado final, portanto, envolva o loop em um bloco try se seu código precisar continuar. Consulte [Lidar com o resultado](/pt/agent-sdk/agent-loop#handle-the-result) para os subtipos de resultado.

257 

258<h3 id="implementation-example-1">

251 Exemplo de Implementação259 Exemplo de Implementação

252</h3>260</h3>

253 261 

Details

358 Tratamento de erros358 Tratamento de erros

359</h2>359</h2>

360 360 

361A geração de saída estruturada pode falhar quando o agente não consegue produzir JSON válido correspondendo ao seu schema. Isso normalmente acontece quando o schema é muito complexo para a tarefa, a tarefa em si é ambígua, ou o agente atinge seu limite de tentativas tentando corrigir erros de validação.361A geração de saída estruturada pode falhar quando o agente não consegue produzir JSON válido correspondendo ao seu schema. Isso normalmente acontece quando o schema é muito complexo para a tarefa, a tarefa em si é ambígua, ou o agente atinge seu limite de tentativas tentando corrigir erros de validação. Também pode acontecer sem nenhuma falha de validação: um [fallback de modelo](/pt/model-config#automatic-model-fallback) pode retratar uma saída já concluída no meio do fluxo, e se nenhuma tentativa bem-sucedida a substituir, a execução termina com o mesmo erro. Verifique o campo `errors` na mensagem de resultado para distinguir as duas causas antes de depurar seu schema.

362 362 

363Quando um erro ocorre, a mensagem de resultado tem um `subtype` indicando o que deu errado:363Quando um erro ocorre, a mensagem de resultado tem um `subtype` indicando o que deu errado:

364 364 

365| Subtype | Significado |365| Subtype | Significado |

366| ------------------------------------- | -------------------------------------------------------------------- |366| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |

367| `success` | Saída foi gerada e validada com sucesso |367| `success` | Saída foi gerada e validada com sucesso |

368| `error_max_structured_output_retries` | Agente não conseguiu produzir saída válida após múltiplas tentativas |368| `error_max_structured_output_retries` | Nenhuma saída válida sobreviveu após múltiplas tentativas (falhas de validação, ou uma retração de fallback de modelo sem tentativa bem-sucedida) |

369 369 

370O exemplo abaixo verifica o campo `subtype` para determinar se a saída foi gerada com sucesso ou se você precisa lidar com uma falha:370O exemplo abaixo verifica o campo `subtype` para determinar se a saída foi gerada com sucesso ou se você precisa lidar com uma falha:

371 371 

Details

41 Paralelização41 Paralelização

42</h3>42</h3>

43 43 

44Múltiplos subagentes podem ser executados simultaneamente, acelerando dramaticamente fluxos de trabalho complexos.44Múltiplos subagentes podem ser executados simultaneamente, portanto subtarefas independentes terminam no tempo do mais lento em vez da soma de todos eles.

45 45 

46**Exemplo:** durante uma revisão de código, você pode executar os subagentes `style-checker`, `security-scanner` e `test-coverage` simultaneamente, reduzindo o tempo de revisão de minutos para segundos.46**Exemplo:** durante uma revisão de código, você pode executar os subagentes `style-checker`, `security-scanner` e `test-coverage` simultaneamente em vez de sequencialmente.

47 47 

48<h3 id="specialized-instructions-and-knowledge">48<h3 id="specialized-instructions-and-knowledge">

49 Instruções e conhecimento especializados49 Instruções e conhecimento especializados


178</h3>178</h3>

179 179 

180| Campo | Tipo | Obrigatório | Descrição |180| Campo | Tipo | Obrigatório | Descrição |

181| :---------------- | :---------------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |181| :---------------- | :---------------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

182| `description` | `string` | Sim | Descrição em linguagem natural de quando usar este agente |182| `description` | `string` | Sim | Descrição em linguagem natural de quando usar este agente |

183| `prompt` | `string` | Sim | O prompt do sistema do agente definindo seu papel e comportamento |183| `prompt` | `string` | Sim | O prompt do sistema do agente definindo seu papel e comportamento |

184| `tools` | `string[]` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas |184| `tools` | `string[]` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas |

185| `disallowedTools` | `string[]` | Não | Array de nomes de ferramentas a remover do conjunto de ferramentas do agente |185| `disallowedTools` | `string[]` | Não | Array de nomes de ferramentas a remover do conjunto de ferramentas do agente. Padrões de nível de servidor MCP também são aceitos: `mcp__server` ou `mcp__server__*` remove todas as ferramentas desse servidor, e `mcp__*` remove todas as ferramentas MCP de qualquer servidor |

186| `model` | `string` | Não | Substituição de modelo para este agente. Aceita um alias como `'sonnet'`, `'opus'`, `'haiku'`, `'inherit'`, ou um ID de modelo completo. Padrão é o modelo principal se omitido |186| `model` | `string` | Não | Substituição de modelo para este agente. Aceita um alias como `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, ou um ID de modelo completo. Padrão é o modelo principal se omitido |

187| `skills` | `string[]` | Não | Lista de nomes de skills para pré-carregar no contexto do agente na inicialização. Skills não listadas permanecem invocáveis através da ferramenta Skill |187| `skills` | `string[]` | Não | Lista de nomes de skills para pré-carregar no contexto do agente na inicialização. Skills não listadas permanecem invocáveis através da ferramenta Skill |

188| `memory` | `'user' \| 'project' \| 'local'` | Não | Fonte de memória para este agente |188| `memory` | `'user' \| 'project' \| 'local'` | Não | Fonte de memória para este agente |

189| `mcpServers` | `(string \| object)[]` | Não | Servidores MCP disponíveis para este agente, por nome ou configuração inline |189| `mcpServers` | `(string \| object)[]` | Não | Servidores MCP disponíveis para este agente, por nome ou configuração inline |

190| `initialPrompt` | `string` | Não | Auto-enviado como o primeiro turno do usuário quando este agente é executado como o agente da thread principal. Ignorado quando o agente é invocado como um subagente |

190| `maxTurns` | `number` | Não | Número máximo de turnos agentic antes do agente parar |191| `maxTurns` | `number` | Não | Número máximo de turnos agentic antes do agente parar |

191| `background` | `boolean` | Não | Executar este agente como uma tarefa de fundo não-bloqueante quando invocado |192| `background` | `boolean` | Não | Executar este agente como uma tarefa de fundo não-bloqueante quando invocado |

192| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | Não | Nível de esforço de raciocínio para este agente |193| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' \| number` | Não | Nível de esforço de raciocínio para este agente |


195No SDK Python, esses nomes de campo usam camelCase para corresponder ao formato de transmissão. Veja a referência [`AgentDefinition`](/pt/agent-sdk/python#agentdefinition) para detalhes.196No SDK Python, esses nomes de campo usam camelCase para corresponder ao formato de transmissão. Veja a referência [`AgentDefinition`](/pt/agent-sdk/python#agentdefinition) para detalhes.

196 197 

197<Note>198<Note>

198 Subagentes não podem gerar seus próprios subagentes. Não inclua `Agent` no array `tools` de um subagente.199 {/* min-version: 2.1.172 */}A partir do Claude Code v2.1.172, subagentes podem gerar seus próprios subagentes. Um subagente de fundo cinco níveis abaixo do agente principal não pode gerar mais subagentes; subagentes em primeiro plano podem gerar em qualquer profundidade. Para evitar que um subagente gere outros, omita `Agent` de seu array `tools` ou adicione-o a `disallowedTools`. Veja [subagentes aninhados](/pt/sub-agents#spawn-nested-subagents) para as regras de profundidade completas.

199</Note>200</Note>

200 201 

201<h3 id="filesystem-based-definition-alternative">202<h3 id="filesystem-based-definition-alternative">


215A janela de contexto de um subagente começa nova (sem conversa pai) mas não está vazia. O único canal do pai para o subagente é a string de prompt da ferramenta Agent, então inclua quaisquer caminhos de arquivo, mensagens de erro ou decisões que o subagente precise diretamente nesse prompt.216A janela de contexto de um subagente começa nova (sem conversa pai) mas não está vazia. O único canal do pai para o subagente é a string de prompt da ferramenta Agent, então inclua quaisquer caminhos de arquivo, mensagens de erro ou decisões que o subagente precise diretamente nesse prompt.

216 217 

217| O subagente recebe | O subagente não recebe |218| O subagente recebe | O subagente não recebe |

218| :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- |219| :------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------- |

219| Seu próprio prompt do sistema (`AgentDefinition.prompt`) e o prompt da ferramenta Agent | O histórico de conversa do pai ou resultados de ferramentas |220| Seu próprio prompt do sistema (`AgentDefinition.prompt`) e o prompt da ferramenta Agent | O histórico de conversa do pai ou resultados de ferramentas |

220| CLAUDE.md do projeto (carregado via `settingSources`) | Conteúdo de skill pré-carregado, a menos que listado em `AgentDefinition.skills` |221| CLAUDE.md do projeto (carregado via [`settingSources`](/pt/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)) | Conteúdo de skill pré-carregado, a menos que listado em `AgentDefinition.skills` |

221| Definições de ferramentas (herdadas do pai, ou o subconjunto em `tools`) | O prompt do sistema do pai |222| Definições de ferramentas (herdadas do pai, ou o subconjunto em `tools`) | O prompt do sistema do pai |

222 223 

223<Note>224<Note>


336 O nome da ferramenta foi renomeado de `"Task"` para `"Agent"` no Claude Code v2.1.63. Lançamentos atuais do SDK emitem `"Agent"` em blocos `tool_use` mas ainda usam `"Task"` na lista de ferramentas `system:init` e em `result.permission_denials[].tool_name`. Verificar ambos os valores em `block.name` garante compatibilidade entre versões do SDK.337 O nome da ferramenta foi renomeado de `"Task"` para `"Agent"` no Claude Code v2.1.63. Lançamentos atuais do SDK emitem `"Agent"` em blocos `tool_use` mas ainda usam `"Task"` na lista de ferramentas `system:init` e em `result.permission_denials[].tool_name`. Verificar ambos os valores em `block.name` garante compatibilidade entre versões do SDK.

337</Note>338</Note>

338 339 

339Este exemplo itera através de mensagens transmitidas, registrando quando um subagente é invocado e quando mensagens subsequentes originam-se de dentro do contexto de execução desse subagente.340A estrutura de mensagem difere entre SDKs. Em Python, blocos de conteúdo são acessados diretamente via `message.content`. Em TypeScript, `SDKAssistantMessage` envolve a mensagem da API Claude, então o conteúdo é acessado via `message.message.content`.

340 341 

341<Note>342Este exemplo itera através de mensagens transmitidas, registrando quando um subagente é invocado e quando mensagens subsequentes originam-se de dentro do contexto de execução desse subagente.

342 A estrutura de mensagem difere entre SDKs. Em Python, blocos de conteúdo são acessados diretamente via `message.content`. Em TypeScript, `SDKAssistantMessage` envolve a mensagem da API Claude, então o conteúdo é acessado via `message.message.content`.

343</Note>

344 343 

345<CodeGroup>344<CodeGroup>

346 ```python Python theme={null}345 ```python Python theme={null}


427 426 

428Subagentes podem ser retomados para continuar de onde pararam. Subagentes retomados retêm seu histórico de conversa completo, incluindo todas as chamadas de ferramentas anteriores, resultados e raciocínio. O subagente continua exatamente de onde parou em vez de começar do zero.427Subagentes podem ser retomados para continuar de onde pararam. Subagentes retomados retêm seu histórico de conversa completo, incluindo todas as chamadas de ferramentas anteriores, resultados e raciocínio. O subagente continua exatamente de onde parou em vez de começar do zero.

429 428 

430Quando um subagente é concluído, Claude recebe seu ID de agente no resultado da ferramenta Agent. Para retomar um subagente programaticamente:429Quando um subagente é concluído, o resultado da ferramenta Agent inclui um bloco de texto contendo `agentId: <id>`. Os agentes integrados [`Explore` e `Plan`](/pt/sub-agents#built-in-subagents) são de uma única execução e não retornam um `agentId`, então use um agente personalizado ou `general-purpose` quando você precisar retomar. Para retomar um subagente programaticamente:

431 430 

4321. **Capture o ID da sessão**: Extraia `session_id` de mensagens durante a primeira query4311. **Capture o ID da sessão**: Extraia `session_id` de mensagens durante a primeira query

4332. **Extraia o ID do agente**: Analise `agentId` do conteúdo da mensagem4322. **Extraia o ID do agente**: Analise `agentId` do texto do resultado da ferramenta Agent

4343. **Retome a sessão**: Passe `resume: sessionId` nas opções da segunda query e inclua o ID do agente em seu prompt4333. **Retome a sessão**: Passe `resume: sessionId` nas opções da segunda query e inclua o ID do agente em seu prompt

435 434 

436<Note>435<Note>

437 Você deve retomar a mesma sessão para acessar a transcrição do subagente. Cada chamada `query()` inicia uma nova sessão por padrão, então passe `resume: sessionId` para continuar na mesma sessão.436 Você deve retomar a mesma sessão para acessar a transcrição do subagente. Cada chamada `query()` inicia uma nova sessão por padrão, então passe `resume: sessionId` para continuar na mesma sessão.

438 437 

439 Se você estiver usando um agente personalizado (não um integrado), você também precisa passar a mesma definição de agente no parâmetro `agents` para ambas as queries.438 Ao usar um agente personalizado, passe a mesma definição de agente no parâmetro `agents` para ambas as queries.

440</Note>439</Note>

441 440 

442O exemplo abaixo demonstra esse fluxo: a primeira query executa um subagente e captura o ID da sessão e ID do agente, então a segunda query retoma a sessão para fazer uma pergunta de acompanhamento que requer contexto da primeira análise.441O exemplo abaixo define um agente personalizado `endpoint-finder`. A primeira query o executa e captura o ID da sessão e ID do agente do resultado da ferramenta Agent, então a segunda query retoma a sessão para fazer uma pergunta de acompanhamento que requer contexto da primeira análise.

443 442 

444<CodeGroup>443<CodeGroup>

445 ```typescript TypeScript theme={null}

446 import { query, type SDKMessage } from "@anthropic-ai/claude-agent-sdk";

447 

448 // Helper to extract agentId from message content

449 // Stringify to avoid traversing different block types (TextBlock, ToolResultBlock, etc.)

450 function extractAgentId(message: SDKMessage): string | undefined {

451 if (message.type !== "assistant" && message.type !== "user") return undefined;

452 // Stringify the content so we can search it without traversing nested blocks

453 const content = JSON.stringify(message.message.content);

454 const match = content.match(/agentId:\s*([a-f0-9-]+)/);

455 return match?.[1];

456 }

457 

458 let agentId: string | undefined;

459 let sessionId: string | undefined;

460 

461 // First invocation - use the Explore agent to find API endpoints

462 for await (const message of query({

463 prompt: "Use the Explore agent to find all API endpoints in this codebase",

464 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"] }

465 })) {

466 // Capture session_id from ResultMessage (needed to resume this session)

467 if ("session_id" in message) sessionId = message.session_id;

468 // Search message content for the agentId (appears in Agent tool results)

469 const extractedId = extractAgentId(message);

470 if (extractedId) agentId = extractedId;

471 // Print the final result

472 if ("result" in message) console.log(message.result);

473 }

474 

475 // Second invocation - resume and ask follow-up

476 if (agentId && sessionId) {

477 for await (const message of query({

478 prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,

479 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], resume: sessionId }

480 })) {

481 if ("result" in message) console.log(message.result);

482 }

483 }

484 ```

485 

486 ```python Python theme={null}444 ```python Python theme={null}

487 import asyncio445 import asyncio

488 import json

489 import re446 import re

490 from claude_agent_sdk import query, ClaudeAgentOptions447 from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ToolResultBlock

448 

449 AGENTS = {

450 "endpoint-finder": AgentDefinition(

451 description="Locates and catalogs API endpoints in a codebase.",

452 prompt="You find and document API endpoints. Report each endpoint's path, method, and handler.",

453 tools=["Read", "Grep", "Glob"],

454 )

455 }

491 456 

492 457 

493 def extract_agent_id(text: str) -> str | None:458 def extract_agent_id(block: ToolResultBlock) -> str | None:

494 """Extract agentId from Agent tool result text."""459 """Extract agentId from an Agent tool result's text content."""

495 match = re.search(r"agentId:\s*([a-f0-9-]+)", text)460 parts = block.content if isinstance(block.content, list) else [{"text": block.content}]

496 return match.group(1) if match else None461 for part in parts:

462 if match := re.search(r"agentId:\s*([\w-]+)", part.get("text") or ""):

463 return match.group(1)

464 return None

497 465 

498 466 

499 async def main():467 async def main():

500 agent_id = None468 agent_id = None

501 session_id = None469 session_id = None

502 470 

503 # First invocation - use the Explore agent to find API endpoints471 # First invocation - run the endpoint-finder subagent

504 async for message in query(472 async for message in query(

505 prompt="Use the Explore agent to find all API endpoints in this codebase",473 prompt="Use the endpoint-finder agent to find all API endpoints in this codebase",

506 options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"]),474 options=ClaudeAgentOptions(allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS),

507 ):475 ):

508 # Capture session_id from ResultMessage (needed to resume this session)476 # Capture session_id from ResultMessage (needed to resume this session)

509 if hasattr(message, "session_id"):477 if hasattr(message, "session_id"):

510 session_id = message.session_id478 session_id = message.session_id

511 # Search message content for the agentId (appears in Agent tool results)479 # Search tool results for the agentId trailer

512 if hasattr(message, "content"):480 for block in getattr(message, "content", None) or []:

513 # Stringify the content so we can search it without traversing nested blocks481 if isinstance(block, ToolResultBlock):

514 content_str = json.dumps(message.content, default=str)482 agent_id = extract_agent_id(block) or agent_id

515 extracted = extract_agent_id(content_str)

516 if extracted:

517 agent_id = extracted

518 # Print the final result483 # Print the final result

519 if hasattr(message, "result"):484 if hasattr(message, "result"):

520 print(message.result)485 print(message.result)


524 async for message in query(489 async for message in query(

525 prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints",490 prompt=f"Resume agent {agent_id} and list the top 3 most complex endpoints",

526 options=ClaudeAgentOptions(491 options=ClaudeAgentOptions(

527 allowed_tools=["Read", "Grep", "Glob", "Agent"], resume=session_id492 allowed_tools=["Read", "Grep", "Glob", "Agent"], agents=AGENTS, resume=session_id

528 ),493 ),

529 ):494 ):

530 if hasattr(message, "result"):495 if hasattr(message, "result"):


533 498 

534 asyncio.run(main())499 asyncio.run(main())

535 ```500 ```

501 

502 ```typescript TypeScript theme={null}

503 import { query, type SDKMessage } from "@anthropic-ai/claude-agent-sdk";

504 

505 const agents = {

506 "endpoint-finder": {

507 description: "Locates and catalogs API endpoints in a codebase.",

508 prompt: "You find and document API endpoints. Report each endpoint's path, method, and handler.",

509 tools: ["Read", "Grep", "Glob"]

510 }

511 };

512 

513 // Stringify content to search for agentId without traversing nested block types

514 function extractAgentId(message: SDKMessage): string | undefined {

515 if (message.type !== "assistant" && message.type !== "user") return undefined;

516 const content = JSON.stringify(message.message.content);

517 const match = content.match(/agentId:\s*([\w-]+)/);

518 return match?.[1];

519 }

520 

521 let agentId: string | undefined;

522 let sessionId: string | undefined;

523 

524 // First invocation - run the endpoint-finder subagent

525 for await (const message of query({

526 prompt: "Use the endpoint-finder agent to find all API endpoints in this codebase",

527 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], agents }

528 })) {

529 // Capture session_id from ResultMessage (needed to resume this session)

530 if ("session_id" in message) sessionId = message.session_id;

531 // Search message content for the agentId (appears in Agent tool results)

532 const extractedId = extractAgentId(message);

533 if (extractedId) agentId = extractedId;

534 // Print the final result

535 if ("result" in message) console.log(message.result);

536 }

537 

538 // Second invocation - resume and ask follow-up

539 if (agentId && sessionId) {

540 for await (const message of query({

541 prompt: `Resume agent ${agentId} and list the top 3 most complex endpoints`,

542 options: { allowedTools: ["Read", "Grep", "Glob", "Agent"], agents, resume: sessionId }

543 })) {

544 if ("result" in message) console.log(message.result);

545 }

546 }

547 ```

536</CodeGroup>548</CodeGroup>

537 549 

538Transcrições de subagentes persistem independentemente da conversa principal:550Transcrições de subagentes persistem independentemente da conversa principal:


541* **Persistência de sessão**: Transcrições de subagentes persistem dentro de sua sessão. Você pode retomar um subagente após reiniciar Claude Code retomando a mesma sessão.553* **Persistência de sessão**: Transcrições de subagentes persistem dentro de sua sessão. Você pode retomar um subagente após reiniciar Claude Code retomando a mesma sessão.

542* **Limpeza automática**: Transcrições são limpas com base na configuração `cleanupPeriodDays` (padrão: 30 dias).554* **Limpeza automática**: Transcrições são limpas com base na configuração `cleanupPeriodDays` (padrão: 30 dias).

543 555 

544<h2 id="tool-restrictions">556<h2 id="tool-restrictions-1">

545 Restrições de ferramentas557 Restrições de ferramentas

546</h2>558</h2>

547 559 

Details

217| Forma do item: `{ content, status, activeForm }` | Entrada de `TaskCreate`: `{ subject, description, activeForm?, metadata? }`. Entrada de `TaskUpdate`: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status` é `"pending"`, `"in_progress"` ou `"completed"`; defina `status: "deleted"` para deletar |217| Forma do item: `{ content, status, activeForm }` | Entrada de `TaskCreate`: `{ subject, description, activeForm?, metadata? }`. Entrada de `TaskUpdate`: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status` é `"pending"`, `"in_progress"` ou `"completed"`; defina `status: "deleted"` para deletar |

218| Renderizar `block.input.todos` diretamente | Acumular itens entre chamadas, ou ler um snapshot de um resultado de ferramenta `TaskList` |218| Renderizar `block.input.todos` diretamente | Acumular itens entre chamadas, ou ler um snapshot de um resultado de ferramenta `TaskList` |

219 219 

220O ID de tarefa atribuído não está na entrada de `TaskCreate`. Ele volta no `tool_result` correspondente como `{ task: { id, subject } }`, então capture-o do bloco de resultado para codificar seu mapa. O exemplo a seguir mostra a mudança mínima para o loop [Monitorando Mudanças de Tarefas](#monitoring-todo-changes). Para renderizar uma lista completa, observe um resultado de ferramenta `TaskList` no fluxo ou acumule resultados de `TaskCreate` e entradas de `TaskUpdate` em um mapa:220O ID de tarefa atribuído não está na entrada de `TaskCreate`. Ele volta no `tool_result` correspondente como `{ task: { id, subject } }`, então capture-o do bloco de resultado para codificar seu mapa. O exemplo a seguir mostra a mudança mínima para o loop [Monitorando Mudanças de Tarefas](#monitoring-todo-changes). Para renderizar uma lista completa, observe um resultado de ferramenta `TaskList` no fluxo ou acumule resultados de `TaskCreate` e entradas de `TaskUpdate` em um mapa.

221 

222O input `tool_use` transmitido é a forma bruta que o modelo emitiu. Claude Code repara alguns nomes de chave próximos mas incorretos antes da execução, mapeando `id` ou `task_id` para `taskId` e `active_form` para `activeForm`, mas esse reparo não é refletido no fluxo. Leia os campos de entrada de `TaskUpdate` defensivamente, como os exemplos abaixo fazem, em vez de assumir que o nome canônico está sempre presente.

221 223 

222<CodeGroup>224<CodeGroup>

223 ```typescript TypeScript theme={null}225 ```typescript TypeScript theme={null}


233 const input = block.input as { subject: string };235 const input = block.input as { subject: string };

234 console.log(`+ ${input.subject}`);236 console.log(`+ ${input.subject}`);

235 } else if (block.name === "TaskUpdate") {237 } else if (block.name === "TaskUpdate") {

236 const input = block.input as { taskId: string; status?: string };238 const input = block.input as {

237 if (input.status) console.log(` ${input.taskId} -> ${input.status}`);239 taskId?: string;

240 id?: string;

241 task_id?: string;

242 status?: string;

243 };

244 const taskId = input.taskId ?? input.id ?? input.task_id;

245 if (taskId && input.status) console.log(` ${taskId} -> ${input.status}`);

238 }246 }

239 }247 }

240 }248 }


254 if block.name == "TaskCreate":262 if block.name == "TaskCreate":

255 print(f"+ {block.input['subject']}")263 print(f"+ {block.input['subject']}")

256 elif block.name == "TaskUpdate" and block.input.get("status"):264 elif block.name == "TaskUpdate" and block.input.get("status"):

257 print(f" {block.input['taskId']} -> {block.input['status']}")265 task_id = (

266 block.input.get("taskId")

267 or block.input.get("id")

268 or block.input.get("task_id")

269 )

270 if task_id:

271 print(f" {task_id} -> {block.input['status']}")

258 ```272 ```

259</CodeGroup>273</CodeGroup>

260 274 

Details

100}): Promise<WarmQuery>;100}): Promise<WarmQuery>;

101```101```

102 102 

103<h4 id="parameters">103<h4 id="parameters-1">

104 Parâmetros104 Parâmetros

105</h4>105</h4>

106 106 


109| `options` | [`Options`](#options) | Objeto de configuração opcional. Igual ao parâmetro `options` para `query()` |109| `options` | [`Options`](#options) | Objeto de configuração opcional. Igual ao parâmetro `options` para `query()` |

110| `initializeTimeoutMs` | `number` | Tempo máximo em milissegundos para aguardar a inicialização do subprocesso. Padrão é `60000`. Se a inicialização não for concluída no tempo, a promise é rejeitada com um erro de timeout |110| `initializeTimeoutMs` | `number` | Tempo máximo em milissegundos para aguardar a inicialização do subprocesso. Padrão é `60000`. Se a inicialização não for concluída no tempo, a promise é rejeitada com um erro de timeout |

111 111 

112<h4 id="returns">112<h4 id="returns-1">

113 Retorna113 Retorna

114</h4>114</h4>

115 115 


149): SdkMcpToolDefinition<Schema>;149): SdkMcpToolDefinition<Schema>;

150```150```

151 151 

152<h4 id="parameters">152<h4 id="parameters-2">

153 Parâmetros153 Parâmetros

154</h4>154</h4>

155 155 


204}): McpSdkServerConfigWithInstance;204}): McpSdkServerConfigWithInstance;

205```205```

206 206 

207<h4 id="parameters">207<h4 id="parameters-3">

208 Parâmetros208 Parâmetros

209</h4>209</h4>

210 210 


224function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;224function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;

225```225```

226 226 

227<h4 id="parameters">227<h4 id="parameters-4">

228 Parâmetros228 Parâmetros

229</h4>229</h4>

230 230 


251| `tag` | `string \| undefined` | Tag de sessão definida pelo usuário (veja [`tagSession()`](#tagsession)) |251| `tag` | `string \| undefined` | Tag de sessão definida pelo usuário (veja [`tagSession()`](#tagsession)) |

252| `createdAt` | `number \| undefined` | Tempo de criação em milissegundos desde a época, do timestamp da primeira entrada |252| `createdAt` | `number \| undefined` | Tempo de criação em milissegundos desde a época, do timestamp da primeira entrada |

253 253 

254<h4 id="example">254<h4 id="example-1">

255 Exemplo255 Exemplo

256</h4>256</h4>

257 257 


280): Promise<SessionMessage[]>;280): Promise<SessionMessage[]>;

281```281```

282 282 

283<h4 id="parameters">283<h4 id="parameters-5">

284 Parâmetros284 Parâmetros

285</h4>285</h4>

286 286 


303| `message` | `unknown` | Payload de mensagem bruta da transcrição |303| `message` | `unknown` | Payload de mensagem bruta da transcrição |

304| `parent_tool_use_id` | `string \| null` | Para mensagens de subagente, o `tool_use_id` da chamada de ferramenta `Agent` geradora. `null` para mensagens de sessão principal e sessões mais antigas |304| `parent_tool_use_id` | `string \| null` | Para mensagens de subagente, o `tool_use_id` da chamada de ferramenta `Agent` geradora. `null` para mensagens de sessão principal e sessões mais antigas |

305 305 

306<h4 id="example">306<h4 id="example-2">

307 Exemplo307 Exemplo

308</h4>308</h4>

309 309 


337): Promise<SDKSessionInfo | undefined>;337): Promise<SDKSessionInfo | undefined>;

338```338```

339 339 

340<h4 id="parameters">340<h4 id="parameters-6">

341 Parâmetros341 Parâmetros

342</h4>342</h4>

343 343 


362): Promise<void>;362): Promise<void>;

363```363```

364 364 

365<h4 id="parameters">365<h4 id="parameters-7">

366 Parâmetros366 Parâmetros

367</h4>367</h4>

368 368 


386): Promise<void>;386): Promise<void>;

387```387```

388 388 

389<h4 id="parameters">389<h4 id="parameters-8">

390 Parâmetros390 Parâmetros

391</h4>391</h4>

392 392 


412): Promise<ResolvedSettings>;412): Promise<ResolvedSettings>;

413```413```

414 414 

415<h4 id="parameters">415<h4 id="parameters-9">

416 Parâmetros416 Parâmetros

417</h4>417</h4>

418 418 


437| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | Para cada chave de nível superior em `effective`, qual fonte forneceu o valor |437| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | Para cada chave de nível superior em `effective`, qual fonte forneceu o valor |

438| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | Configurações brutas por fonte, ordenadas de precedência mais baixa para mais alta |438| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | Configurações brutas por fonte, ordenadas de precedência mais baixa para mais alta |

439 439 

440<h4 id="example">440<h4 id="example-3">

441 Exemplo441 Exemplo

442</h4>442</h4>

443 443 


481| `debug` | `boolean` | `false` | Ativar modo de depuração para o processo Claude Code |481| `debug` | `boolean` | `false` | Ativar modo de depuração para o processo Claude Code |

482| `debugFile` | `string` | `undefined` | Escrever logs de depuração em um caminho de arquivo específico. Ativa implicitamente o modo de depuração |482| `debugFile` | `string` | `undefined` | Escrever logs de depuração em um caminho de arquivo específico. Ativa implicitamente o modo de depuração |

483| `disallowedTools` | `string[]` | `[]` | Ferramentas para negar. Um nome simples como `"Bash"` remove a ferramenta do contexto do Claude. Uma regra com escopo como `"Bash(rm *)"` deixa a ferramenta disponível e nega chamadas correspondentes em todos os modos de permissão, incluindo `bypassPermissions`. Veja [Permissões](/pt/agent-sdk/permissions#allow-and-deny-rules) |483| `disallowedTools` | `string[]` | `[]` | Ferramentas para negar. Um nome simples como `"Bash"` remove a ferramenta do contexto do Claude. Uma regra com escopo como `"Bash(rm *)"` deixa a ferramenta disponível e nega chamadas correspondentes em todos os modos de permissão, incluindo `bypassPermissions`. Veja [Permissões](/pt/agent-sdk/permissions#allow-and-deny-rules) |

484| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `'high'` | Controla quanto esforço Claude coloca em sua resposta. Funciona com pensamento adaptativo para guiar a profundidade do pensamento |484| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | Padrão do modelo | Controla quanto esforço Claude coloca em sua resposta. Funciona com pensamento adaptativo para guiar a profundidade do pensamento. Veja [ajustar o nível de esforço](/pt/model-config#adjust-effort-level) |

485| `enableFileCheckpointing` | `boolean` | `false` | Ativar rastreamento de mudanças de arquivo para retrocesso. Veja [File checkpointing](/pt/agent-sdk/file-checkpointing) |485| `enableFileCheckpointing` | `boolean` | `false` | Ativar rastreamento de mudanças de arquivo para retrocesso. Veja [File checkpointing](/pt/agent-sdk/file-checkpointing) |

486| `env` | `Record<string, string \| undefined>` | `process.env` | Variáveis de ambiente. Quando definido, isso substitui o ambiente do subprocesso em vez de mesclar com `process.env`, então passe `{ ...process.env, YOUR_VAR: 'value' }` para manter variáveis herdadas como `PATH`. Veja [Lidar com respostas de API lentas ou travadas](#handle-slow-or-stalled-api-responses) para um exemplo deste padrão, e [Variáveis de ambiente](/pt/env-vars) para variáveis que a CLI subjacente lê. Defina `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar sua aplicação no cabeçalho User-Agent |486| `env` | `Record<string, string \| undefined>` | `process.env` | Variáveis de ambiente. Quando definido, isso substitui o ambiente do subprocesso em vez de mesclar com `process.env`, então passe `{ ...process.env, YOUR_VAR: 'value' }` para manter variáveis herdadas como `PATH`. Veja [Lidar com respostas de API lentas ou travadas](#handle-slow-or-stalled-api-responses) para um exemplo deste padrão, e [Variáveis de ambiente](/pt/env-vars) para variáveis que a CLI subjacente lê. Defina `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar sua aplicação no cabeçalho User-Agent |

487| `executable` | `'bun' \| 'deno' \| 'node'` | Auto-detectado | Runtime JavaScript a usar |487| `executable` | `'bun' \| 'deno' \| 'node'` | Auto-detectado | Runtime JavaScript a usar |


499| `maxThinkingTokens` | `number` | `undefined` | *Descontinuado:* Use `thinking` em vez disso. Tokens máximos para processo de pensamento |499| `maxThinkingTokens` | `number` | `undefined` | *Descontinuado:* Use `thinking` em vez disso. Tokens máximos para processo de pensamento |

500| `maxTurns` | `number` | `undefined` | Turnos agênticos máximos (round trips de uso de ferramenta) |500| `maxTurns` | `number` | `undefined` | Turnos agênticos máximos (round trips de uso de ferramenta) |

501| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurações de servidor MCP |501| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configurações de servidor MCP |

502| `model` | `string` | Padrão da CLI | Modelo Claude a usar |502| `model` | `string` | Padrão da CLI | Alias de modelo Claude ou nome de modelo completo. Veja [valores aceitos e IDs específicos do provedor](/pt/model-config#available-models) |

503| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | Callback para lidar com solicitações de elicitação MCP. Chamado quando um servidor MCP solicita entrada do usuário e nenhum hook a trata primeiro. Quando não fornecido, solicitações de elicitação não tratadas são recusadas automaticamente |503| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | Callback para lidar com solicitações de elicitação MCP. Chamado quando um servidor MCP solicita entrada do usuário e nenhum hook a trata primeiro. Quando não fornecido, solicitações de elicitação não tratadas são recusadas automaticamente |

504| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Defina o formato de saída para resultados de agente. Veja [Structured outputs](/pt/agent-sdk/structured-outputs) para detalhes |504| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Defina o formato de saída para resultados de agente. Veja [Structured outputs](/pt/agent-sdk/structured-outputs) para detalhes |

505| `outputStyle` | `string` | `undefined` | Não é um campo `Options`. Defina `outputStyle` no objeto [`settings`](/pt/settings) inline ou em um arquivo de configurações. Veja [Ativar um estilo de saída](/pt/agent-sdk/modifying-system-prompts#activate-an-output-style) |505| `outputStyle` | `string` | `undefined` | Não é um campo `Options`. Defina `outputStyle` no objeto [`settings`](/pt/settings) inline ou em um arquivo de configurações. Veja [Ativar um estilo de saída](/pt/agent-sdk/modifying-system-prompts#activate-an-output-style) |


518| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alfa.* Modo de flush para `sessionStore`. Ignorado quando `sessionStore` não está definido |518| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alfa.* Modo de flush para `sessionStore`. Ignorado quando `sessionStore` não está definido |

519| `settings` | `string \| Settings` | `undefined` | Objeto de [configurações](/pt/settings) inline ou caminho para um arquivo de configurações. Popula a camada de configurações de flag na [ordem de precedência](/pt/settings#settings-precedence). Altere em tempo de execução com [`applyFlagSettings()`](#applyflagsettings) |519| `settings` | `string \| Settings` | `undefined` | Objeto de [configurações](/pt/settings) inline ou caminho para um arquivo de configurações. Popula a camada de configurações de flag na [ordem de precedência](/pt/settings#settings-precedence). Altere em tempo de execução com [`applyFlagSettings()`](#applyflagsettings) |

520| `settingSources` | [`SettingSource`](#settingsource)`[]` | Padrões da CLI (todas as fontes) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desativar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |520| `settingSources` | [`SettingSource`](#settingsource)`[]` | Padrões da CLI (todas as fontes) | Controle quais configurações do sistema de arquivos carregar. Passe `[]` para desativar configurações de usuário, projeto e local. Configurações de política gerenciada carregam independentemente. Veja [Use Claude Code features](/pt/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

521| `skills` | `string[] \| 'all'` | `undefined` | Skills disponíveis para a sessão. Passe `'all'` para ativar cada skill descoberta, ou uma lista de nomes de skills. Quando definido, o SDK ativa a ferramenta Skill automaticamente sem listá-la em `allowedTools`. Veja [Skills](/pt/agent-sdk/skills) |521| `skills` | `string[] \| 'all'` | `undefined` | Skills disponíveis para a sessão. Passe `'all'` para ativar cada skill descoberta, ou uma lista de nomes de skills. Quando definido, o SDK ativa a ferramenta Skill automaticamente em `allowedTools`. Se você também passar `tools`, inclua `'Skill'` nessa lista. Veja [Skills](/pt/agent-sdk/skills) |

522| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Função personalizada para gerar o processo Claude Code. Use para executar Claude Code em VMs, contêineres ou ambientes remotos |522| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Função personalizada para gerar o processo Claude Code. Use para executar Claude Code em VMs, contêineres ou ambientes remotos |

523| `stderr` | `(data: string) => void` | `undefined` | Callback para saída stderr |523| `stderr` | `(data: string) => void` | `undefined` | Callback para saída stderr |

524| `strictMcpConfig` | `boolean` | `false` | Use apenas os servidores passados em `mcpServers` e ignore o projeto `.mcp.json`, configurações do usuário, servidores MCP fornecidos por plugin e [conectores claude.ai](/pt/mcp#use-mcp-servers-from-claude-ai) |524| `strictMcpConfig` | `boolean` | `false` | Use apenas os servidores passados em `mcpServers` e ignore o projeto `.mcp.json`, configurações do usuário, servidores MCP fornecidos por plugin e [conectores claude.ai](/pt/mcp#use-mcp-servers-from-claude-ai) |


553* `API_TIMEOUT_MS`: timeout por solicitação no cliente Anthropic, em milissegundos. Padrão `600000`. Aplica-se ao loop principal e a todos os subagentes.553* `API_TIMEOUT_MS`: timeout por solicitação no cliente Anthropic, em milissegundos. Padrão `600000`. Aplica-se ao loop principal e a todos os subagentes.

554* `CLAUDE_CODE_MAX_RETRIES`: máximo de tentativas de API. Padrão `10`. Cada tentativa obtém sua própria janela `API_TIMEOUT_MS`, então o tempo de parede no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais backoff.554* `CLAUDE_CODE_MAX_RETRIES`: máximo de tentativas de API. Padrão `10`. Cada tentativa obtém sua própria janela `API_TIMEOUT_MS`, então o tempo de parede no pior caso é aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` mais backoff.

555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes lançados com `run_in_background`. Padrão `600000`. Redefine em cada evento de stream; em caso de travamento, aborta o subagente, marca a tarefa como falhada e expõe o erro ao pai com qualquer resultado parcial. Não se aplica a subagentes síncronos.555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: watchdog de travamento para subagentes lançados com `run_in_background`. Padrão `600000`. Redefine em cada evento de stream; em caso de travamento, aborta o subagente, marca a tarefa como falhada e expõe o erro ao pai com qualquer resultado parcial. Não se aplica a subagentes síncronos.

556* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. Desativado por padrão. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. A solicitação abortada passa pelo caminho de tentativa normal.556* `CLAUDE_ENABLE_STREAM_WATCHDOG=1` com `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: aborta a solicitação quando os cabeçalhos chegaram mas o corpo da resposta para de fazer stream. Quando `CLAUDE_ENABLE_STREAM_WATCHDOG` não está definido, o padrão é controlado pelo servidor na API Anthropic direta e desativado em outros provedores. `CLAUDE_STREAM_IDLE_TIMEOUT_MS` padrão é `300000` e é fixado nesse mínimo. A solicitação abortada passa pelo caminho de tentativa normal.

557 557 

558<h3 id="query-object">558<h3 id="query-object">

559 Objeto `Query`559 Objeto `Query`


658}658}

659```659```

660 660 

661<h4 id="methods">661<h4 id="methods-1">

662 Métodos662 Métodos

663</h4>663</h4>

664 664 


717```717```

718 718 

719| Campo | Obrigatório | Descrição |719| Campo | Obrigatório | Descrição |

720| :------------------------------------ | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |720| :------------------------------------ | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

721| `description` | Sim | Descrição em linguagem natural de quando usar este agente |721| `description` | Sim | Descrição em linguagem natural de quando usar este agente |

722| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas do pai. Para pré-carregar Skills no contexto do agente, use o campo `skills` em vez de listar `'Skill'` aqui |722| `tools` | Não | Array de nomes de ferramentas permitidas. Se omitido, herda todas as ferramentas do pai. Para pré-carregar Skills no contexto do agente, use o campo `skills` em vez de listar `'Skill'` aqui |

723| `disallowedTools` | Não | Array de nomes de ferramentas para explicitamente desallocar para este agente |723| `disallowedTools` | Não | Array de nomes de ferramentas para explicitamente desallocar para este agente. Padrões de nível de servidor MCP também são aceitos: `mcp__server` ou `mcp__server__*` remove cada ferramenta desse servidor, e `mcp__*` remove cada ferramenta MCP de qualquer servidor |

724| `prompt` | Sim | O prompt do sistema do agente |724| `prompt` | Sim | O prompt do sistema do agente |

725| `model` | Não | Substituição de modelo para este agente. Aceita um alias como `'sonnet'`, `'opus'`, `'haiku'`, `'inherit'`, ou um ID de modelo completo. Se omitido ou `'inherit'`, usa o modelo principal |725| `model` | Não | Substituição de modelo para este agente. Aceita um alias como `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, ou um ID de modelo completo. Se omitido ou `'inherit'`, usa o modelo principal |

726| `mcpServers` | Não | Especificações de servidor MCP para este agente |726| `mcpServers` | Não | Especificações de servidor MCP para este agente |

727| `skills` | Não | Array de nomes de skills para pré-carregar no contexto do agente |727| `skills` | Não | Array de nomes de skills para pré-carregar no contexto do agente |

728| `initialPrompt` | Não | Auto-enviado como o primeiro turno de usuário quando este agente é executado como o agente da thread principal |728| `initialPrompt` | Não | Auto-enviado como o primeiro turno de usuário quando este agente é executado como o agente da thread principal |


759| :---------- | :--------------------------------------------------------------- | :---------------------------- |759| :---------- | :--------------------------------------------------------------- | :---------------------------- |

760| `'user'` | Configurações globais do usuário | `~/.claude/settings.json` |760| `'user'` | Configurações globais do usuário | `~/.claude/settings.json` |

761| `'project'` | Configurações de projeto compartilhadas (controladas por versão) | `.claude/settings.json` |761| `'project'` | Configurações de projeto compartilhadas (controladas por versão) | `.claude/settings.json` |

762| `'local'` | Configurações de projeto local (gitignored) | `.claude/settings.local.json` |762| `'local'` | Configurações de projeto local (não controladas por versão) | `.claude/settings.local.json` |

763 763 

764<h4 id="default-behavior">764<h4 id="default-behavior">

765 Comportamento padrão765 Comportamento padrão


874type PermissionMode =874type PermissionMode =

875 | "default" // Comportamento de permissão padrão875 | "default" // Comportamento de permissão padrão

876 | "acceptEdits" // Auto-aceitar edições de arquivo876 | "acceptEdits" // Auto-aceitar edições de arquivo

877 | "bypassPermissions" // Bypass de todas as verificações de permissão877 | "bypassPermissions" // Bypass de verificações de permissão; regras de solicitação explícita ainda solicitam

878 | "plan" // Plan Mode - ferramentas somente leitura878 | "plan" // Plan Mode - explorar sem editar

879 | "dontAsk" // Não solicitar permissões, negar se não pré-aprovado879 | "dontAsk" // Não solicitar permissões, negar se não pré-aprovado

880 | "auto"; // Usar um classificador de modelo para aprovar ou negar cada chamada de ferramenta880 | "auto"; // Usar um classificador de modelo para aprovar ou negar cada chamada de ferramenta

881```881```


1035type SdkPluginConfig = {1035type SdkPluginConfig = {

1036 type: "local";1036 type: "local";

1037 path: string;1037 path: string;

1038 skipMcpDiscovery?: boolean;

1038};1039};

1039```1040```

1040 1041 

1041| Campo | Tipo | Descrição |1042| Campo | Tipo | Descrição |

1042| :----- | :-------- | :--------------------------------------------------------------- |1043| :----------------- | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1043| `type` | `'local'` | Deve ser `'local'` (apenas plugins locais atualmente suportados) |1044| `type` | `'local'` | Deve ser `'local'` (apenas plugins locais atualmente suportados) |

1044| `path` | `string` | Caminho absoluto ou relativo para o diretório do plugin |1045| `path` | `string` | Caminho absoluto ou relativo para o diretório do plugin |

1046| `skipMcpDiscovery` | `boolean` | Quando `true`, o SDK carrega skills, hooks, agentes e comandos deste plugin mas não lê seu `.mcp.json` ou manifest `mcpServers`. Defina isso quando sua aplicação possui as conexões MCP do plugin. |

1045 1047 

1046**Exemplo:**1048**Exemplo:**

1047 1049 


1086 | SDKTaskProgressMessage1088 | SDKTaskProgressMessage

1087 | SDKTaskUpdatedMessage1089 | SDKTaskUpdatedMessage

1088 | SDKSessionStateChangedMessage1090 | SDKSessionStateChangedMessage

1091 | SDKWorkerShuttingDownMessage

1089 | SDKCommandsChangedMessage1092 | SDKCommandsChangedMessage

1090 | SDKNotificationMessage1093 | SDKNotificationMessage

1091 | SDKFilesPersistedEvent1094 | SDKFilesPersistedEvent


1096 | SDKPermissionDeniedMessage1099 | SDKPermissionDeniedMessage

1097 | SDKPromptSuggestionMessage1100 | SDKPromptSuggestionMessage

1098 | SDKAPIRetryMessage1101 | SDKAPIRetryMessage

1099 | SDKMirrorErrorMessage;1102 | SDKMirrorErrorMessage

1103 | SDKInformationalMessage;

1100```1104```

1101 1105 

1102<h3 id="sdkassistantmessage">1106<h3 id="sdkassistantmessage">


1183 result: string;1187 result: string;

1184 stop_reason: string | null;1188 stop_reason: string | null;

1185 ttft_ms?: number;1189 ttft_ms?: number;

1190 ttft_stream_ms?: number;

1186 total_cost_usd: number;1191 total_cost_usd: number;

1187 usage: NonNullableUsage;1192 usage: NonNullableUsage;

1188 modelUsage: { [modelName: string]: ModelUsage };1193 modelUsage: { [modelName: string]: ModelUsage };


1221Vários campos no resultado carregam detalhes de diagnóstico além de `subtype`:1226Vários campos no resultado carregam detalhes de diagnóstico além de `subtype`:

1222 1227 

1223* `api_error_status`: o código de status HTTP do erro de API que encerrou a conversa. Ausente ou `null` quando o turno terminou sem um erro de API.1228* `api_error_status`: o código de status HTTP do erro de API que encerrou a conversa. Ausente ou `null` quando o turno terminou sem um erro de API.

1224* `ttft_ms`: tempo até o primeiro token em milissegundos. Presente apenas no braço de sucesso.1229* `ttft_ms`: tempo até o primeiro token em milissegundos, medido quando a primeira mensagem completa do assistente chega. Presente apenas no braço de sucesso.

1230* `ttft_stream_ms`: tempo em milissegundos até o primeiro evento de fluxo `message_start`, quando o fluxo de resposta abre. Menor que `ttft_ms`; a lacuna entre os dois é o tempo gasto transmitindo a primeira mensagem. Presente apenas no braço de sucesso.

1225* `terminal_reason`: por que o loop terminou. Um de `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, ou `"model_error"`.1231* `terminal_reason`: por que o loop terminou. Um de `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, ou `"model_error"`.

1226* `fast_mode_state`: um de `"on"`, `"off"`, ou `"cooldown"`.1232* `fast_mode_state`: um de `"on"`, `"off"`, ou `"cooldown"`.

1227 1233 


1273 parent_tool_use_id: string | null;1279 parent_tool_use_id: string | null;

1274 uuid: UUID;1280 uuid: UUID;

1275 session_id: string;1281 session_id: string;

1282 ttft_ms?: number; // Tempo até o primeiro token em ms, presente apenas em eventos message_start

1276};1283};

1277```1284```

1278 1285 


1295};1302};

1296```1303```

1297 1304 

1305<h3 id="sdkinformationalmessage">

1306 `SDKInformationalMessage`

1307</h3>

1308 

1309Banner de texto genérico emitido pelo loop. Carrega linhas de status sem erro, feedback de hook como a razão de bloqueio de um hook `UserPromptSubmit`, e saída de comando. Renderize `content` como texto simples no `level` fornecido.

1310 

1311```typescript theme={null}

1312type SDKInformationalMessage = {

1313 type: "system";

1314 subtype: "informational";

1315 content: string;

1316 level: "info" | "notice" | "suggestion" | "warning";

1317 tool_use_id?: string;

1318 prevent_continuation?: boolean;

1319 uuid: UUID;

1320 session_id: string;

1321};

1322```

1323 

1324<h3 id="sdkworkershuttingdownmessage">

1325 `SDKWorkerShuttingDownMessage`

1326</h3>

1327 

1328Emitido no encerramento gracioso do worker para que clientes remotos possam mostrar por que o worker desapareceu em vez de esperar pelo timeout de heartbeat. O `reason` é uma string curta em snake\_case definida pela CLI do host, como `"host_exit"` ou `"remote_control_disabled"`. Aja sobre isso apenas ao transmitir ao vivo. Uma sessão retomada reproduz instâncias passadas desta mensagem, então ignore-as nesse caso.

1329 

1330```typescript theme={null}

1331type SDKWorkerShuttingDownMessage = {

1332 type: "system";

1333 subtype: "worker_shutting_down";

1334 reason: string;

1335 uuid: UUID;

1336 session_id: string;

1337};

1338```

1339 

1298<h3 id="sdkplugininstallmessage">1340<h3 id="sdkplugininstallmessage">

1299 `SDKPluginInstallMessage`1341 `SDKPluginInstallMessage`

1300</h3>1342</h3>


1369type SDKMessageOrigin =1411type SDKMessageOrigin =

1370 | { kind: "human" }1412 | { kind: "human" }

1371 | { kind: "channel"; server: string }1413 | { kind: "channel"; server: string }

1372 | { kind: "peer"; from: string; name?: string }1414 | { kind: "peer"; from: string; name?: string; senderTaskId?: string }

1373 | { kind: "task-notification" }1415 | { kind: "task-notification" }

1374 | { kind: "coordinator" };1416 | { kind: "coordinator" }

1417 | { kind: "auto-continuation" };

1375```1418```

1376 1419 

1377| `kind` | Significado |1420| `kind` | Significado |

1378| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |1421| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1379| `human` | Entrada direta do usuário final. Em mensagens de usuário, uma `origin` ausente também significa entrada humana. |1422| `human` | Entrada direta do usuário final. Em mensagens de usuário, uma `origin` ausente também significa entrada humana. |

1380| `channel` | Mensagem chegando em um [canal](/pt/channels). `server` é o nome do servidor MCP de origem. |1423| `channel` | Mensagem chegando em um [canal](/pt/channels). `server` é o nome do servidor MCP de origem. |

1381| `peer` | Mensagem de outra sessão de agente via `SendMessage`. `from` é o endereço do remetente; `name` é o nome de exibição do remetente quando disponível. |1424| `peer` | Reservado para mensagens de outra sessão de agente. `from` é o endereço do remetente e `name` é o nome de exibição do remetente quando disponível. `senderTaskId` é o ID da tarefa do subagente em processo em segundo plano que enviou a mensagem; ausente para pares entre sessões. O Agent SDK não emite essa origem; trate como uma origem desconhecida. |

1382| `task-notification` | Turno sintético injetado após a conclusão de uma tarefa em segundo plano. Consulte [`SDKTaskNotificationMessage`](#sdktasknotificationmessage). |1425| `task-notification` | Turno sintético injetado após a conclusão de uma tarefa em segundo plano. Consulte [`SDKTaskNotificationMessage`](#sdktasknotificationmessage). |

1383| `coordinator` | Mensagem de um coordenador de equipe em uma [equipe de agente](/pt/agent-teams). |1426| `coordinator` | Mensagem de um coordenador de equipe em uma [equipe de agente](/pt/agent-teams). |

1427| `auto-continuation` | Turno sintético injetado quando a sessão continua sem entrada de usuário nova, como um resultado de comando que aciona um prompt de acompanhamento. |

1384 1428 

1385<h2 id="hook-types">1429<h2 id="hook-types">

1386 Tipos de Hook1430 Tipos de Hook


1712type TeammateIdleHookInput = BaseHookInput & {1756type TeammateIdleHookInput = BaseHookInput & {

1713 hook_event_name: "TeammateIdle";1757 hook_event_name: "TeammateIdle";

1714 teammate_name: string;1758 teammate_name: string;

1759 /** @deprecated desde v2.1.178. Carrega o nome da equipe derivado da sessão; será removido. */

1715 team_name: string;1760 team_name: string;

1716};1761};

1717```1762```


1727 task_subject: string;1772 task_subject: string;

1728 task_description?: string;1773 task_description?: string;

1729 teammate_name?: string;1774 teammate_name?: string;

1775 /** @deprecated desde v2.1.178. Carrega o nome da equipe derivado da sessão; será removido. */

1730 team_name?: string;1776 team_name?: string;

1731};1777};

1732```1778```


1934 description: string;1980 description: string;

1935 prompt: string;1981 prompt: string;

1936 subagent_type: string;1982 subagent_type: string;

1937 model?: "sonnet" | "opus" | "haiku";1983 model?: "sonnet" | "opus" | "haiku" | "fable";

1938 resume?: string;1984 resume?: string;

1939 run_in_background?: boolean;1985 run_in_background?: boolean;

1940 max_turns?: number;1986 max_turns?: number;

1941 name?: string;1987 name?: string;

1942 team_name?: string;

1943 mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";1988 mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";

1944 isolation?: "worktree";1989 isolation?: "worktree";

1945};1990};


2385 | WorkflowOutput;2430 | WorkflowOutput;

2386```2431```

2387 2432 

2388<h3 id="agent">2433<h3 id="agent-1">

2389 Agent2434 Agent

2390</h3>2435</h3>

2391 2436 


2397 status: "completed";2442 status: "completed";

2398 agentId: string;2443 agentId: string;

2399 content: Array<{ type: "text"; text: string }>;2444 content: Array<{ type: "text"; text: string }>;

2445 resolvedModel?: string;

2400 totalToolUseCount: number;2446 totalToolUseCount: number;

2401 totalDurationMs: number;2447 totalDurationMs: number;

2402 totalTokens: number;2448 totalTokens: number;


2421 status: "async_launched";2467 status: "async_launched";

2422 agentId: string;2468 agentId: string;

2423 description: string;2469 description: string;

2470 resolvedModel?: string;

2424 prompt: string;2471 prompt: string;

2425 outputFile: string;2472 outputFile: string;

2426 canReadOutputFile?: boolean;2473 canReadOutputFile?: boolean;


2434 2481 

2435Retorna o resultado do subagente. Discriminado no campo `status`: `"completed"` para tarefas concluídas, `"async_launched"` para tarefas em background e `"sub_agent_entered"` para subagentes interativos.2482Retorna o resultado do subagente. Discriminado no campo `status`: `"completed"` para tarefas concluídas, `"async_launched"` para tarefas em background e `"sub_agent_entered"` para subagentes interativos.

2436 2483 

2437<h3 id="askuserquestion">2484O campo `resolvedModel` nas variantes `completed` e `async_launched` nomeia o modelo em que o subagente realmente foi executado, que pode diferir do input `model` solicitado quando [`availableModels`](/pt/model-config#restrict-model-selection) ou outra substituição se aplica. {/* min-version: 2.1.174 */}Este campo requer Claude Code v2.1.174 ou posterior.

2485 

2486<h3 id="askuserquestion-1">

2438 AskUserQuestion2487 AskUserQuestion

2439</h3>2488</h3>

2440 2489 


2455 2504 

2456Retorna as perguntas feitas e as respostas do usuário. `response` é definido quando o usuário digitou uma resposta de forma livre em vez de responder às perguntas estruturadas; quando presente, Claude recebe "O usuário respondeu: …" em vez da lista de respostas por pergunta.2505Retorna as perguntas feitas e as respostas do usuário. `response` é definido quando o usuário digitou uma resposta de forma livre em vez de responder às perguntas estruturadas; quando presente, Claude recebe "O usuário respondeu: …" em vez da lista de respostas por pergunta.

2457 2506 

2458<h3 id="bash">2507<h3 id="bash-1">

2459 Bash2508 Bash

2460</h3>2509</h3>

2461 2510 


2480 2529 

2481Retorna saída de comando com stdout/stderr divididos. Comandos em background incluem um `backgroundTaskId`.2530Retorna saída de comando com stdout/stderr divididos. Comandos em background incluem um `backgroundTaskId`.

2482 2531 

2483<h3 id="monitor">2532<h3 id="monitor-1">

2484 Monitor2533 Monitor

2485</h3>2534</h3>

2486 2535 


2496 2545 

2497Retorna o ID da tarefa em background para o monitor em execução. Use este ID com `TaskStop` para cancelar a observação antecipadamente.2546Retorna o ID da tarefa em background para o monitor em execução. Use este ID com `TaskStop` para cancelar a observação antecipadamente.

2498 2547 

2499<h3 id="edit">2548<h3 id="edit-1">

2500 Edit2549 Edit

2501</h3>2550</h3>

2502 2551 


2530 2579 

2531Retorna o diff estruturado da operação de edição.2580Retorna o diff estruturado da operação de edição.

2532 2581 

2533<h3 id="read">2582<h3 id="read-1">

2534 Read2583 Read

2535</h3>2584</h3>

2536 2585 


2590 2639 

2591Retorna conteúdo do arquivo em um formato apropriado ao tipo de arquivo. Discriminado no campo `type`.2640Retorna conteúdo do arquivo em um formato apropriado ao tipo de arquivo. Discriminado no campo `type`.

2592 2641 

2593<h3 id="write">2642<h3 id="write-1">

2594 Write2643 Write

2595</h3>2644</h3>

2596 2645 


2622 2671 

2623Retorna o resultado da escrita com informações de diff estruturado.2672Retorna o resultado da escrita com informações de diff estruturado.

2624 2673 

2625<h3 id="glob">2674<h3 id="glob-1">

2626 Glob2675 Glob

2627</h3>2676</h3>

2628 2677 


2639 2688 

2640Retorna caminhos de arquivo correspondentes ao padrão glob, classificados por tempo de modificação.2689Retorna caminhos de arquivo correspondentes ao padrão glob, classificados por tempo de modificação.

2641 2690 

2642<h3 id="grep">2691<h3 id="grep-1">

2643 Grep2692 Grep

2644</h3>2693</h3>

2645 2694 


2660 2709 

2661Retorna resultados de busca. A forma varia por `mode`: lista de arquivo, conteúdo com correspondências ou contagens de correspondência.2710Retorna resultados de busca. A forma varia por `mode`: lista de arquivo, conteúdo com correspondências ou contagens de correspondência.

2662 2711 

2663<h3 id="taskstop">2712<h3 id="taskstop-1">

2664 TaskStop2713 TaskStop

2665</h3>2714</h3>

2666 2715 


2677 2726 

2678Retorna confirmação após parar a tarefa em background.2727Retorna confirmação após parar a tarefa em background.

2679 2728 

2680<h3 id="notebookedit">2729<h3 id="notebookedit-1">

2681 NotebookEdit2730 NotebookEdit

2682</h3>2731</h3>

2683 2732 


2699 2748 

2700Retorna o resultado da edição do notebook com conteúdo de arquivo original e atualizado.2749Retorna o resultado da edição do notebook com conteúdo de arquivo original e atualizado.

2701 2750 

2702<h3 id="webfetch">2751<h3 id="webfetch-1">

2703 WebFetch2752 WebFetch

2704</h3>2753</h3>

2705 2754 


2718 2767 

2719Retorna o conteúdo buscado com status HTTP e metadados.2768Retorna o conteúdo buscado com status HTTP e metadados.

2720 2769 

2721<h3 id="websearch">2770<h3 id="websearch-1">

2722 WebSearch2771 WebSearch

2723</h3>2772</h3>

2724 2773 


2740 2789 

2741Retorna resultados de busca da web.2790Retorna resultados de busca da web.

2742 2791 

2743<h3 id="workflow">2792<h3 id="workflow-1">

2744 Workflow2793 Workflow

2745</h3>2794</h3>

2746 2795 


2770| `scriptPath` | `string` | Caminho para o script de workflow persistido para esta execução. Edite-o e passe de volta como `scriptPath` para executar novamente sem reenviar o script |2819| `scriptPath` | `string` | Caminho para o script de workflow persistido para esta execução. Edite-o e passe de volta como `scriptPath` para executar novamente sem reenviar o script |

2771| `error` | `string` | Definido quando o script falha sua verificação de sintaxe. Quando presente, a execução não foi iniciada apesar do status `async_launched` |2820| `error` | `string` | Definido quando o script falha sua verificação de sintaxe. Quando presente, a execução não foi iniciada apesar do status `async_launched` |

2772 2821 

2773<h3 id="todowrite">2822<h3 id="todowrite-1">

2774 TodoWrite2823 TodoWrite

2775</h3>2824</h3>

2776 2825 


2797 A partir do TypeScript Agent SDK 0.3.142, `TodoWrite` está desabilitado por padrão. Use `TaskCreate`, `TaskGet`, `TaskUpdate` e `TaskList` em seu lugar. Veja [Migrar para ferramentas de Task](/pt/agent-sdk/todo-tracking#migrate-to-task-tools) para atualizar seu código de monitoramento, ou defina `CLAUDE_CODE_ENABLE_TASKS=0` para reverter para `TodoWrite`.2846 A partir do TypeScript Agent SDK 0.3.142, `TodoWrite` está desabilitado por padrão. Use `TaskCreate`, `TaskGet`, `TaskUpdate` e `TaskList` em seu lugar. Veja [Migrar para ferramentas de Task](/pt/agent-sdk/todo-tracking#migrate-to-task-tools) para atualizar seu código de monitoramento, ou defina `CLAUDE_CODE_ENABLE_TASKS=0` para reverter para `TodoWrite`.

2798</Note>2847</Note>

2799 2848 

2800<h3 id="taskcreate">2849<h3 id="taskcreate-1">

2801 TaskCreate2850 TaskCreate

2802</h3>2851</h3>

2803 2852 


2814 2863 

2815Retorna a tarefa criada com seu ID atribuído.2864Retorna a tarefa criada com seu ID atribuído.

2816 2865 

2817<h3 id="taskupdate">2866<h3 id="taskupdate-1">

2818 TaskUpdate2867 TaskUpdate

2819</h3>2868</h3>

2820 2869 


2835 2884 

2836Retorna o resultado da atualização, incluindo quais campos foram alterados.2885Retorna o resultado da atualização, incluindo quais campos foram alterados.

2837 2886 

2838<h3 id="taskget">2887<h3 id="taskget-1">

2839 TaskGet2888 TaskGet

2840</h3>2889</h3>

2841 2890 


2856 2905 

2857Retorna o registro completo da tarefa, ou `null` quando o ID não é encontrado.2906Retorna o registro completo da tarefa, ou `null` quando o ID não é encontrado.

2858 2907 

2859<h3 id="tasklist">2908<h3 id="tasklist-1">

2860 TaskList2909 TaskList

2861</h3>2910</h3>

2862 2911 


2876 2925 

2877Retorna um snapshot de todas as tarefas na lista atual.2926Retorna um snapshot de todas as tarefas na lista atual.

2878 2927 

2879<h3 id="exitplanmode">2928<h3 id="exitplanmode-1">

2880 ExitPlanMode2929 ExitPlanMode

2881</h3>2930</h3>

2882 2931 


2895 2944 

2896Retorna o estado do plano após sair do modo de planejamento.2945Retorna o estado do plano após sair do modo de planejamento.

2897 2946 

2898<h3 id="listmcpresources">2947<h3 id="listmcpresources-1">

2899 ListMcpResources2948 ListMcpResources

2900</h3>2949</h3>

2901 2950 


2913 2962 

2914Retorna um array de recursos MCP disponíveis.2963Retorna um array de recursos MCP disponíveis.

2915 2964 

2916<h3 id="readmcpresource">2965<h3 id="readmcpresource-1">

2917 ReadMcpResource2966 ReadMcpResource

2918</h3>2967</h3>

2919 2968 


2931 2980 

2932Retorna o conteúdo do recurso MCP solicitado.2981Retorna o conteúdo do recurso MCP solicitado.

2933 2982 

2934<h3 id="enterworktree">2983<h3 id="enterworktree-1">

2935 EnterWorktree2984 EnterWorktree

2936</h3>2985</h3>

2937 2986 


3010type PermissionUpdateDestination =3059type PermissionUpdateDestination =

3011 | "userSettings" // Configurações globais do usuário3060 | "userSettings" // Configurações globais do usuário

3012 | "projectSettings" // Configurações de projeto por diretório3061 | "projectSettings" // Configurações de projeto por diretório

3013 | "localSettings" // Configurações locais gitignored3062 | "localSettings" // Configurações locais do projeto

3014 | "session" // Apenas sessão atual3063 | "session" // Apenas sessão atual

3015 | "cliArg"; // Argumento CLI3064 | "cliArg"; // Argumento CLI

3016```3065```


3049```3098```

3050 3099 

3051<Warning>3100<Warning>

3052 O beta `context-1m-2025-08-07` foi descontinuado a partir de 30 de abril de 2026. Passar este valor com Claude Sonnet 4.5 ou Sonnet 4 não tem efeito, e requisições que excedem a janela de contexto padrão de 200k-token retornam um erro. Para usar uma janela de contexto de 1M-token, migre para [Claude Sonnet 4.6, Claude Opus 4.6, ou Claude Opus 4.7](https://platform.claude.com/docs/pt/about-claude/models/overview), que incluem contexto de 1M a preço padrão sem header beta necessário.3101 O beta `context-1m-2025-08-07` foi descontinuado a partir de 30 de abril de 2026. Passar este valor com Claude Sonnet 4.5 ou Sonnet 4 não tem efeito, e requisições que excedem a janela de contexto padrão de 200k-token retornam um erro. Para usar uma janela de contexto de 1M-token, migre para [Claude Sonnet 4.6, Claude Opus 4.6, Claude Opus 4.7 ou Claude Opus 4.8](https://platform.claude.com/docs/pt/about-claude/models/overview), que incluem contexto de 1M a preço padrão sem header beta necessário.

3053</Warning>3102</Warning>

3054 3103 

3055<h3 id="slashcommand">3104<h3 id="slashcommand">


3241```typescript theme={null}3290```typescript theme={null}

3242type CallToolResult = {3291type CallToolResult = {

3243 content: Array<{3292 content: Array<{

3244 type: "text" | "image" | "resource";3293 type: "text" | "image" | "audio" | "resource" | "resource_link";

3245 // Campos adicionais variam por tipo3294 // Campos adicionais variam por tipo

3246 }>;3295 }>;

3247 structuredContent?: Record<string, unknown>;3296 structuredContent?: Record<string, unknown>;


3848<Warning>3897<Warning>

3849 Comandos executando com `dangerouslyDisableSandbox: true` têm acesso completo ao sistema. Garanta que seu handler `canUseTool` valide essas solicitações cuidadosamente.3898 Comandos executando com `dangerouslyDisableSandbox: true` têm acesso completo ao sistema. Garanta que seu handler `canUseTool` valide essas solicitações cuidadosamente.

3850 3899 

3851 Se `permissionMode` está definido como `bypassPermissions` e `allowUnsandboxedCommands` está ativado, o modelo pode autonomamente executar comandos fora do sandbox sem quaisquer prompts de aprovação. Esta combinação efetivamente permite que o modelo escape do isolamento de sandbox silenciosamente.3900 Se `permissionMode` está definido como `bypassPermissions` e `allowUnsandboxedCommands` está ativado, o modelo pode autonomamente executar comandos fora do sandbox sem quaisquer prompts de aprovação (uma [`ask` rule](/pt/agent-sdk/permissions#how-permissions-are-evaluated) explícita ainda força uma). Esta combinação efetivamente permite que o modelo escape do isolamento de sandbox silenciosamente.

3852</Warning>3901</Warning>

3853 3902 

3854<h2 id="see-also">3903<h2 id="see-also">

Details

16 16 

17Este guia mostra como detectar cada tipo de solicitação e responder apropriadamente.17Este guia mostra como detectar cada tipo de solicitação e responder apropriadamente.

18 18 

19## Detectar quando Claude precisa de entrada19<h2 id="detect-when-claude-needs-input">

20 Detectar quando Claude precisa de entrada

21</h2>

20 22 

21Passe um callback `canUseTool` nas opções de sua consulta. O callback é acionado sempre que Claude precisa de entrada do usuário, recebendo o nome da ferramenta e a entrada como argumentos:23Passe um callback `canUseTool` nas opções de sua consulta. O callback é acionado sempre que Claude precisa de entrada do usuário, recebendo o nome da ferramenta e a entrada como argumentos:

22 24 


49 Para permitir ou negar automaticamente ferramentas sem solicitar aos usuários, use [hooks](/pt/agent-sdk/hooks) em vez disso. Os hooks são executados antes de `canUseTool` e podem permitir, negar ou modificar solicitações com base em sua própria lógica. Você também pode usar o [hook `PermissionRequest`](/pt/agent-sdk/hooks#available-hooks) para enviar notificações externas (Slack, email, push) quando Claude está aguardando aprovação.51 Para permitir ou negar automaticamente ferramentas sem solicitar aos usuários, use [hooks](/pt/agent-sdk/hooks) em vez disso. Os hooks são executados antes de `canUseTool` e podem permitir, negar ou modificar solicitações com base em sua própria lógica. Você também pode usar o [hook `PermissionRequest`](/pt/agent-sdk/hooks#available-hooks) para enviar notificações externas (Slack, email, push) quando Claude está aguardando aprovação.

50</Note>52</Note>

51 53 

52## Lidar com solicitações de aprovação de ferramentas54<h2 id="handle-tool-approval-requests">

55 Lidar com solicitações de aprovação de ferramentas

56</h2>

53 57 

54Depois de passar um callback `canUseTool` nas opções de sua consulta, ele é acionado quando Claude quer usar uma ferramenta que não é aprovada automaticamente. Seu callback recebe três argumentos:58Depois de passar um callback `canUseTool` nas opções de sua consulta, ele é acionado quando Claude quer usar uma ferramenta que não é aprovada automaticamente. Seu callback recebe três argumentos:

55 59 


197 201 

198Este exemplo usa um fluxo s/n onde qualquer entrada diferente de `s` é tratada como uma negação. Na prática, você pode construir uma interface de usuário mais rica que permite aos usuários modificar a solicitação, fornecer feedback ou redirecionar Claude completamente. Veja [Responder a solicitações de ferramentas](#respond-to-tool-requests) para todas as maneiras que você pode responder.202Este exemplo usa um fluxo s/n onde qualquer entrada diferente de `s` é tratada como uma negação. Na prática, você pode construir uma interface de usuário mais rica que permite aos usuários modificar a solicitação, fornecer feedback ou redirecionar Claude completamente. Veja [Responder a solicitações de ferramentas](#respond-to-tool-requests) para todas as maneiras que você pode responder.

199 203 

200### Responder a solicitações de ferramentas204<h3 id="respond-to-tool-requests">

205 Responder a solicitações de ferramentas

206</h3>

201 207 

202Seu callback retorna um de dois tipos de resposta:208Seu callback retorna um de dois tipos de resposta:

203 209 


407 </Tab>413 </Tab>

408</Tabs>414</Tabs>

409 415 

410## Lidar com perguntas de esclarecimento416<h2 id="handle-clarifying-questions">

417 Lidar com perguntas de esclarecimento

418</h2>

411 419 

412Quando Claude precisa de mais direção em uma tarefa com múltiplas abordagens válidas, ele chama a ferramenta `AskUserQuestion`. Isso aciona seu callback `canUseTool` com `toolName` definido como `AskUserQuestion`. A entrada contém as perguntas do Claude como opções de múltipla escolha, que você exibe ao usuário e retorna suas seleções.420Quando Claude precisa de mais direção em uma tarefa com múltiplas abordagens válidas, ele chama a ferramenta `AskUserQuestion`. Isso aciona seu callback `canUseTool` com `toolName` definido como `AskUserQuestion`. A entrada contém as perguntas do Claude como opções de múltipla escolha, que você exibe ao usuário e retorna suas seleções.

413 421 


551 </Step>559 </Step>

552</Steps>560</Steps>

553 561 

554### Formato de pergunta562<h3 id="question-format">

563 Formato de pergunta

564</h3>

555 565 

556A entrada contém as perguntas geradas pelo Claude em um array `questions`. Cada pergunta tem estes campos:566A entrada contém as perguntas geradas pelo Claude em um array `questions`. Cada pergunta tem estes campos:

557 567 

558| Campo | Descrição |568| Campo | Descrição |

559| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |569| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |

560| `question` | O texto completo da pergunta a exibir |570| `question` | O texto completo da pergunta a exibir |

561| `header` | Rótulo curto para a pergunta (máximo 12 caracteres) |571| `header` | Rótulo curto para a pergunta (máximo 12 caracteres) |

562| `options` | Array de 2-4 escolhas, cada uma com `label` e `description`. TypeScript: opcionalmente `preview` (veja [abaixo](#option-previews-type-script)) |572| `options` | Array de 2-4 escolhas, cada uma com `label` e `description`. TypeScript: opcionalmente `preview` (veja [abaixo](#option-previews-typescript)) |

563| `multiSelect` | Se `true`, os usuários podem selecionar múltiplas opções |573| `multiSelect` | Se `true`, os usuários podem selecionar múltiplas opções |

564 574 

565A estrutura que seu callback recebe:575A estrutura que seu callback recebe:


580}590}

581```591```

582 592 

583#### Visualizações de opção (TypeScript)593<h4 id="option-previews-typescript">

594 Visualizações de opção (TypeScript)

595</h4>

584 596 

585`toolConfig.askUserQuestion.previewFormat` adiciona um campo `preview` a cada opção para que seu aplicativo possa mostrar uma simulação visual ao lado do rótulo. Sem esta configuração, Claude não gera visualizações e o campo está ausente.597`toolConfig.askUserQuestion.previewFormat` adiciona um campo `preview` a cada opção para que seu aplicativo possa mostrar uma simulação visual ao lado do rótulo. Sem esta configuração, Claude não gera visualizações e o campo está ausente.

586 598 


621}633}

622```634```

623 635 

624### Formato de resposta636<h3 id="response-format">

637 Formato de resposta

638</h3>

625 639 

626Retorne um objeto `answers` mapeando cada campo `question` da pergunta para o `label` da opção selecionada:640Retorne um objeto `answers` mapeando cada campo `question` da pergunta para o `label` da opção selecionada:

627 641 


645}659}

646```660```

647 661 

648#### Suporte para entrada de texto livre662<h4 id="support-free-text-input">

663 Suporte para entrada de texto livre

664</h4>

649 665 

650As opções predefinidas do Claude nem sempre cobrirão o que os usuários querem. Para permitir que os usuários digitem sua própria resposta:666As opções predefinidas do Claude nem sempre cobrirão o que os usuários querem. Para permitir que os usuários digitem sua própria resposta:

651 667 


654 670 

655Veja o [exemplo completo](#complete-example) abaixo para uma implementação completa.671Veja o [exemplo completo](#complete-example) abaixo para uma implementação completa.

656 672 

657### Exemplo completo673<h3 id="complete-example">

674 Exemplo completo

675</h3>

658 676 

659Claude faz perguntas de esclarecimento quando precisa de entrada do usuário para prosseguir. Por exemplo, quando solicitado a ajudar a decidir sobre uma pilha de tecnologia para um aplicativo móvel, Claude pode perguntar sobre cross-platform vs nativo, preferências de backend ou plataformas alvo. Essas perguntas ajudam Claude a tomar decisões que correspondem às preferências do usuário em vez de adivinhar.677Claude faz perguntas de esclarecimento quando precisa de entrada do usuário para prosseguir. Por exemplo, quando solicitado a ajudar a decidir sobre uma pilha de tecnologia para um aplicativo móvel, Claude pode perguntar sobre cross-platform vs nativo, preferências de backend ou plataformas alvo. Essas perguntas ajudam Claude a tomar decisões que correspondem às preferências do usuário em vez de adivinhar.

660 678 


821 ```839 ```

822</CodeGroup>840</CodeGroup>

823 841 

824## Limitações842<h2 id="limitations">

843 Limitações

844</h2>

825 845 

826* **Subagentes**: `AskUserQuestion` não está disponível em subagentes gerados por meio da ferramenta Agent846* **Subagentes**: `AskUserQuestion` não está disponível em subagentes gerados por meio da ferramenta Agent

827* **Limites de perguntas**: cada chamada `AskUserQuestion` suporta 1-4 perguntas com 2-4 opções cada847* **Limites de perguntas**: cada chamada `AskUserQuestion` suporta 1-4 perguntas com 2-4 opções cada

828 848 

829## Outras maneiras de obter entrada do usuário849<h2 id="other-ways-to-get-user-input">

850 Outras maneiras de obter entrada do usuário

851</h2>

830 852 

831O callback `canUseTool` e a ferramenta `AskUserQuestion` cobrem a maioria dos cenários de aprovação e esclarecimento, mas o SDK oferece outras maneiras de obter entrada dos usuários:853O callback `canUseTool` e a ferramenta `AskUserQuestion` cobrem a maioria dos cenários de aprovação e esclarecimento, mas o SDK oferece outras maneiras de obter entrada dos usuários:

832 854 

833### Entrada de streaming855<h3 id="streaming-input">

856 Entrada de streaming

857</h3>

834 858 

835Use [entrada de streaming](/pt/agent-sdk/streaming-vs-single-mode) quando você precisar:859Use [entrada de streaming](/pt/agent-sdk/streaming-vs-single-mode) quando você precisar:

836 860 


840 864 

841A entrada de streaming é ideal para interfaces conversacionais onde os usuários interagem com o agente durante toda a execução, não apenas em pontos de aprovação.865A entrada de streaming é ideal para interfaces conversacionais onde os usuários interagem com o agente durante toda a execução, não apenas em pontos de aprovação.

842 866 

843### Ferramentas personalizadas867<h3 id="custom-tools">

868 Ferramentas personalizadas

869</h3>

844 870 

845Use [ferramentas personalizadas](/pt/agent-sdk/custom-tools) quando você precisar:871Use [ferramentas personalizadas](/pt/agent-sdk/custom-tools) quando você precisar:

846 872 


850 876 

851As ferramentas personalizadas lhe dão controle total sobre a interação, mas requerem mais trabalho de implementação do que usar o callback `canUseTool` integrado.877As ferramentas personalizadas lhe dão controle total sobre a interação, mas requerem mais trabalho de implementação do que usar o callback `canUseTool` integrado.

852 878 

853## Recursos relacionados879<h2 id="related-resources">

880 Recursos relacionados

881</h2>

854 882 

855* [Configurar permissões](/pt/agent-sdk/permissions): configurar modos e regras de permissão883* [Configurar permissões](/pt/agent-sdk/permissions): configurar modos e regras de permissão

856* [Controlar execução com hooks](/pt/agent-sdk/hooks): executar código personalizado em pontos-chave do ciclo de vida do agente884* [Controlar execução com hooks](/pt/agent-sdk/hooks): executar código personalizado em pontos-chave do ciclo de vida do agente

agent-teams.md +26 −38

Details

7> Coordene múltiplas instâncias Claude Code trabalhando juntas como uma equipe, com tarefas compartilhadas, mensagens entre agentes e gerenciamento centralizado.7> Coordene múltiplas instâncias Claude Code trabalhando juntas como uma equipe, com tarefas compartilhadas, mensagens entre agentes e gerenciamento centralizado.

8 8 

9<Warning>9<Warning>

10 Equipes de agentes são experimentais e desabilitadas por padrão. Ative-as adicionando `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` ao seu [settings.json](/pt/settings) ou ambiente. Equipes de agentes têm [limitações conhecidas](#limitations) em torno de retomada de sessão, coordenação de tarefas e comportamento de encerramento.10 Equipes de agentes são experimentais e desabilitadas por padrão. Ative-as adicionando `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` ao seu [settings.json](/pt/settings) ou ambiente. Sem essa variável, nenhuma equipe é configurada no início da sessão, nenhum diretório de equipe é escrito, e Claude não gera ou propõe companheiros de equipe. Equipes de agentes têm [limitações conhecidas](#limitations) em torno de retomada de sessão, coordenação de tarefas e comportamento de encerramento.

11</Warning>11</Warning>

12 12 

13Equipes de agentes permitem que você coordene múltiplas instâncias Claude Code trabalhando juntas. Uma sessão atua como o líder da equipe, coordenando o trabalho, atribuindo tarefas e sintetizando resultados. Os companheiros de equipe trabalham independentemente, cada um em sua própria context window, e se comunicam diretamente uns com os outros.13Equipes de agentes permitem que você coordene múltiplas instâncias Claude Code trabalhando juntas. Uma sessão atua como o líder da equipe, coordenando o trabalho, atribuindo tarefas e sintetizando resultados. Os companheiros de equipe trabalham independentemente, cada um em sua própria context window, e se comunicam diretamente uns com os outros.


15Diferentemente de [subagents](/pt/sub-agents), que são executados dentro de uma única sessão e podem apenas relatar de volta ao agente principal, você também pode interagir com companheiros de equipe individuais diretamente sem passar pelo líder.15Diferentemente de [subagents](/pt/sub-agents), que são executados dentro de uma única sessão e podem apenas relatar de volta ao agente principal, você também pode interagir com companheiros de equipe individuais diretamente sem passar pelo líder.

16 16 

17<Note>17<Note>

18 Equipes de agentes requerem Claude Code v2.1.32 ou posterior. Verifique sua versão com `claude --version`.18 Esta página descreve equipes de agentes a partir da v2.1.178. Com `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` definido, gerar um companheiro de equipe não requer mais uma etapa de configuração, e a limpeza acontece automaticamente quando a sessão sai. Antes da v2.1.178, você pedia ao Claude para criar e nomear uma equipe primeiro, e Claude usava as ferramentas `TeamCreate` e `TeamDelete` para configurá-la e removê-la. Ambas as ferramentas não existem mais. A entrada `team_name` na ferramenta Agent é aceita mas ignorada, e o campo `team_name` em `TaskCreated`, `TaskCompleted`, e `TeammateIdle` [payloads de hook](/pt/hooks#taskcreated) carrega o nome derivado da sessão e está descontinuado.

19</Note>19</Note>

20 20 

21Esta página cobre:21Esta página cobre:


78 Inicie sua primeira equipe de agentes78 Inicie sua primeira equipe de agentes

79</h2>79</h2>

80 80 

81Após ativar equipes de agentes, diga ao Claude para criar uma equipe de agentes e descreva a tarefa e a estrutura da equipe que você deseja em linguagem natural. Claude cria a equipe, gera companheiros de equipe e coordena o trabalho com base no seu prompt.81Após ativar equipes de agentes, descreva a tarefa e os companheiros de equipe que você deseja em linguagem natural. Claude os cria e coordena o trabalho com base no seu prompt.

82 82 

83Este exemplo funciona bem porque os três papéis são independentes e podem explorar o problema sem esperar um pelo outro:83Este exemplo funciona bem porque os três papéis são independentes e podem explorar o problema sem esperar um pelo outro:

84 84 

85```text theme={null}85```text theme={null}

86I'm designing a CLI tool that helps developers track TODO comments across86I'm designing a CLI tool that helps developers track TODO comments across

87their codebase. Create an agent team to explore this from different angles: one87their codebase. Spawn three teammates to explore this from different angles:

88teammate on UX, one on technical architecture, one playing devil's advocate.88one on UX, one on technical architecture, one playing devil's advocate.

89```89```

90 90 

91A partir daí, Claude cria uma equipe com uma [lista de tarefas compartilhada](/pt/interactive-mode#task-list), gera companheiros de equipe para cada perspectiva, faz com que explorem o problema, sintetiza descobertas e tenta [limpar a equipe](#clean-up-the-team) quando terminar.91A partir daí, Claude popula uma [lista de tarefas compartilhada](/pt/interactive-mode#task-list), cria companheiros de equipe para cada perspectiva, faz com que explorem o problema e sintetiza descobertas quando terminar.

92 92 

93O terminal do líder lista todos os companheiros de equipe e no que estão trabalhando. Use Shift+Down para percorrer os companheiros de equipe e envie mensagens para eles diretamente. Após o último companheiro de equipe, Shift+Down volta para o líder.93O terminal do líder lista todos os companheiros de equipe e no que estão trabalhando. Use Shift+Down para percorrer os companheiros de equipe e envie mensagens para eles diretamente. Após o último companheiro de equipe, Shift+Down volta para o líder.

94 94 


113 `tmux` tem limitações conhecidas em certos sistemas operacionais e tradicionalmente funciona melhor no macOS. Usar `tmux -CC` no iTerm2 é o ponto de entrada sugerido para `tmux`.113 `tmux` tem limitações conhecidas em certos sistemas operacionais e tradicionalmente funciona melhor no macOS. Usar `tmux -CC` no iTerm2 é o ponto de entrada sugerido para `tmux`.

114</Note>114</Note>

115 115 

116O padrão é `"auto"`, que usa split panes se você já estiver executando dentro de uma sessão tmux, e in-process caso contrário. A configuração `"tmux"` ativa o modo split-pane e detecta automaticamente se deve usar tmux ou iTerm2 com base no seu terminal. Para substituir, defina [`teammateMode`](/pt/settings#available-settings) em `~/.claude/settings.json`:116O padrão é `"auto"`, que usa split panes se você já estiver executando dentro de uma sessão tmux ou seu terminal for iTerm2, e in-process caso contrário. A configuração `"tmux"` ativa o modo split-pane e detecta automaticamente se deve usar tmux ou iTerm2 com base no seu terminal. Para substituir, defina [`teammateMode`](/pt/settings#available-settings) em `~/.claude/settings.json`:

117 117 

118```json theme={null}118```json theme={null}

119{119{


139Claude decide o número de companheiros de equipe a gerar com base em sua tarefa, ou você pode especificar exatamente o que deseja:139Claude decide o número de companheiros de equipe a gerar com base em sua tarefa, ou você pode especificar exatamente o que deseja:

140 140 

141```text theme={null}141```text theme={null}

142Create a team with 4 teammates to refactor these modules in parallel.142Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for

143Use Sonnet for each teammate.143each teammate.

144```144```

145 145 

146Os companheiros de equipe não herdam a seleção `/model` do líder por padrão. Para alterar o modelo usado quando o prompt não especifica um, defina **Default teammate model** em `/config`. Escolha **Default (leader's model)** para que os companheiros de equipe sigam o modelo atual do líder.146Os companheiros de equipe não herdam a seleção `/model` do líder por padrão. Para alterar o modelo usado quando o prompt não especifica um, defina **Default teammate model** em `/config`. Escolha **Default (leader's model)** para que os companheiros de equipe sigam o modelo atual do líder.


186 Encerrar companheiros de equipe186 Encerrar companheiros de equipe

187</h3>187</h3>

188 188 

189Para encerrar graciosamente a sessão de um companheiro de equipe:189Para encerrar graciosamente a sessão de um companheiro de equipe, refira-se a ele pelo nome. Por exemplo, com um companheiro de equipe chamado pesquisador:

190 190 

191```text theme={null}191```text theme={null}

192Ask the researcher teammate to shut down192Ask the researcher teammate to shut down


194 194 

195O líder envia uma solicitação de encerramento. O companheiro de equipe pode aprovar, saindo graciosamente, ou rejeitar com uma explicação.195O líder envia uma solicitação de encerramento. O companheiro de equipe pode aprovar, saindo graciosamente, ou rejeitar com uma explicação.

196 196 

197<h3 id="clean-up-the-team">197Os diretórios compartilhados da equipe são limpos automaticamente quando a sessão termina, portanto não há uma etapa de limpeza separada. Veja [Architecture](#architecture) para saber quais diretórios são removidos e quais persistem para sessões retomadas.

198 Limpar a equipe

199</h3>

200 

201Quando você terminar, peça ao líder para limpar:

202 

203```text theme={null}

204Clean up the team

205```

206 

207Isso remove os recursos compartilhados da equipe. Quando o líder executa a limpeza, ele verifica se há companheiros de equipe ativos e falha se algum ainda estiver em execução, então encerre-os primeiro.

208 

209<Warning>

210 Sempre use o líder para limpar. Os companheiros de equipe não devem executar limpeza porque seu contexto de equipe pode não ser resolvido corretamente, deixando potencialmente recursos em um estado inconsistente.

211</Warning>

212 198 

213<h3 id="enforce-quality-gates-with-hooks">199<h3 id="enforce-quality-gates-with-hooks">

214 Aplicar gates de qualidade com hooks200 Aplicar gates de qualidade com hooks


230 Como Claude inicia equipes de agentes216 Como Claude inicia equipes de agentes

231</h3>217</h3>

232 218 

233Existem duas maneiras pelas quais as equipes de agentes começam:219Uma equipe de agentes se forma quando o primeiro companheiro de equipe é gerado, com a sessão principal atuando como líder. Existem duas maneiras pelas quais os companheiros de equipe são gerados:

234 220 

235* **Você solicita uma equipe**: dê ao Claude uma tarefa que se beneficie do trabalho paralelo e peça explicitamente uma equipe de agentes. Claude cria uma com base em suas instruções.221* **Você solicita companheiros de equipe**: dê ao Claude uma tarefa que se beneficie do trabalho paralelo e peça explicitamente por companheiros de equipe. Claude os gera com base em suas instruções.

236* **Claude propõe uma equipe**: se Claude determinar que sua tarefa se beneficiaria do trabalho paralelo, pode sugerir criar uma equipe. Você confirma antes que ele proceda.222* **Claude propõe companheiros de equipe**: se Claude determinar que sua tarefa se beneficiaria do trabalho paralelo, pode sugerir gerar companheiros de equipe. Você confirma antes que ele proceda.

237 223 

238Em ambos os casos, você permanece no controle. Claude não criará uma equipe sem sua aprovação.224Em ambos os casos, você permanece no controle. Claude não gerará companheiros de equipe sem sua aprovação.

239 225 

240<h3 id="architecture">226<h3 id="architecture">

241 Arquitetura227 Arquitetura


244Uma equipe de agentes consiste em:230Uma equipe de agentes consiste em:

245 231 

246| Componente | Papel |232| Componente | Papel |

247| :------------ | :-------------------------------------------------------------------------------------------------- |233| :------------ | :--------------------------------------------------------------------------------------------- |

248| **Team lead** | A sessão Claude Code principal que cria a equipe, gera companheiros de equipe e coordena o trabalho |234| **Team lead** | A sessão Claude Code principal que gera companheiros de equipe e coordena o trabalho |

249| **Teammates** | Instâncias Claude Code separadas que cada uma trabalha em tarefas atribuídas |235| **Teammates** | Instâncias Claude Code separadas que cada uma trabalha em tarefas atribuídas |

250| **Task list** | Lista compartilhada de itens de trabalho que os companheiros de equipe reivindicam e completam |236| **Task list** | Lista compartilhada de itens de trabalho que os companheiros de equipe reivindicam e completam |

251| **Mailbox** | Sistema de mensagens para comunicação entre agentes |237| **Mailbox** | Sistema de mensagens para comunicação entre agentes |


254 240 

255O sistema gerencia dependências de tarefas automaticamente. Quando um companheiro de equipe completa uma tarefa da qual outras tarefas dependem, as tarefas bloqueadas são desbloqueadas sem intervenção manual.241O sistema gerencia dependências de tarefas automaticamente. Quando um companheiro de equipe completa uma tarefa da qual outras tarefas dependem, as tarefas bloqueadas são desbloqueadas sem intervenção manual.

256 242 

257Equipes e tarefas são armazenadas localmente:243Equipes e tarefas são armazenadas localmente sob um nome derivado da sessão. O nome é `session-` seguido pelos primeiros oito caracteres do ID da sessão:

258 244 

259* **Team config**: `~/.claude/teams/{team-name}/config.json`245* **Team config**: `~/.claude/teams/{team-name}/config.json`

260* **Task list**: `~/.claude/tasks/{team-name}/`246* **Task list**: `~/.claude/tasks/{team-name}/`

261 247 

262Claude Code gera ambas automaticamente quando você cria uma equipe e as atualiza conforme os companheiros de equipe entram, ficam ociosos ou saem. A configuração da equipe contém estado de tempo de execução, como IDs de sessão e IDs de painel tmux, então não a edite manualmente ou a crie previamente: suas alterações são sobrescritas na próxima atualização de estado.248Claude Code gera ambas automaticamente na inicialização da sessão e as atualiza conforme os companheiros de equipe entram, ficam ociosos ou saem. O diretório de configuração da equipe é removido quando a sessão termina. O diretório da lista de tarefas persiste localmente e nunca é carregado, portanto as sessões retomadas mantêm suas tarefas. A retenção é governada pelo mesmo [`cleanupPeriodDays`](/pt/settings#available-settings) que você já controla para transcrições de sessão.

249 

250A configuração da equipe contém estado de tempo de execução, como IDs de sessão e IDs de painel tmux, portanto não a edite manualmente ou a crie previamente: suas alterações são sobrescritas na próxima atualização de estado.

263 251 

264Para definir papéis de companheiros de equipe reutilizáveis, use [definições de subagent](#use-subagent-definitions-for-teammates) em vez disso.252Para definir papéis de companheiros de equipe reutilizáveis, use [definições de subagent](#use-subagent-definitions-for-teammates) em vez disso.

265 253 


268Não há equivalente em nível de projeto da configuração da equipe. Um arquivo como `.claude/teams/teams.json` no seu diretório de projeto não é reconhecido como configuração; Claude o trata como um arquivo ordinário.256Não há equivalente em nível de projeto da configuração da equipe. Um arquivo como `.claude/teams/teams.json` no seu diretório de projeto não é reconhecido como configuração; Claude o trata como um arquivo ordinário.

269 257 

270<h3 id="use-subagent-definitions-for-teammates">258<h3 id="use-subagent-definitions-for-teammates">

271 Usar definições de subagent para companheiros de equipe259 Use subagent definitions for teammates

272</h3>260</h3>

273 261 

274Ao gerar um companheiro de equipe, você pode referenciar um tipo de [subagent](/pt/sub-agents) de qualquer [escopo de subagent](/pt/sub-agents#choose-the-subagent-scope): projeto, usuário, plugin ou definido por CLI. Isso permite que você defina um papel uma vez, como um revisor de segurança ou executor de testes, e o reutilize tanto como um subagent delegado quanto como um companheiro de equipe de equipe de agentes.262Ao gerar um companheiro de equipe, você pode referenciar um tipo de [subagent](/pt/sub-agents) de qualquer [escopo de subagent](/pt/sub-agents#choose-the-subagent-scope): projeto, usuário, plugin ou definido por CLI. Isso permite que você defina um papel uma vez, como um revisor de segurança ou executor de testes, e o reutilize tanto como um subagent delegado quanto como um companheiro de equipe de equipe de agentes.


325Um único revisor tende a gravitar em torno de um tipo de problema por vez. Dividir critérios de revisão em domínios independentes significa que segurança, desempenho e cobertura de testes recebem atenção completa simultaneamente. O prompt atribui a cada companheiro de equipe uma lente distinta para que não se sobreponham:313Um único revisor tende a gravitar em torno de um tipo de problema por vez. Dividir critérios de revisão em domínios independentes significa que segurança, desempenho e cobertura de testes recebem atenção completa simultaneamente. O prompt atribui a cada companheiro de equipe uma lente distinta para que não se sobreponham:

326 314 

327```text theme={null}315```text theme={null}

328Create an agent team to review PR #142. Spawn three reviewers:316Spawn three teammates to review PR #142:

329- One focused on security implications317- One focused on security implications

330- One checking performance impact318- One checking performance impact

331- One validating test coverage319- One validating test coverage


483* **Sem retomada de sessão com companheiros de equipe in-process**: `/resume` e `/rewind` não restauram companheiros de equipe in-process. Após retomar uma sessão, o líder pode tentar enviar mensagens para companheiros de equipe que não existem mais. Se isso acontecer, diga ao líder para gerar novos companheiros de equipe.471* **Sem retomada de sessão com companheiros de equipe in-process**: `/resume` e `/rewind` não restauram companheiros de equipe in-process. Após retomar uma sessão, o líder pode tentar enviar mensagens para companheiros de equipe que não existem mais. Se isso acontecer, diga ao líder para gerar novos companheiros de equipe.

484* **Status da tarefa pode ficar atrasado**: os companheiros de equipe às vezes falham em marcar tarefas como concluídas, o que bloqueia tarefas dependentes. Se uma tarefa parecer presa, verifique se o trabalho está realmente pronto e atualize o status da tarefa manualmente ou diga ao líder para dar um empurrão ao companheiro de equipe.472* **Status da tarefa pode ficar atrasado**: os companheiros de equipe às vezes falham em marcar tarefas como concluídas, o que bloqueia tarefas dependentes. Se uma tarefa parecer presa, verifique se o trabalho está realmente pronto e atualize o status da tarefa manualmente ou diga ao líder para dar um empurrão ao companheiro de equipe.

485* **Encerramento pode ser lento**: os companheiros de equipe terminam sua solicitação atual ou chamada de ferramenta antes de encerrar, o que pode levar tempo.473* **Encerramento pode ser lento**: os companheiros de equipe terminam sua solicitação atual ou chamada de ferramenta antes de encerrar, o que pode levar tempo.

486* **Uma equipe por vez**: um líder pode gerenciar apenas uma equipe. Limpe a equipe atual antes de criar uma nova.474* **Uma equipe por sessão**: uma sessão tem exatamente uma equipe, com escopo para essa sessão. Você não pode criar equipes nomeadas adicionais ou compartilhar uma equipe entre sessões.

487* **Sem equipes aninhadas**: os companheiros de equipe não podem gerar suas próprias equipes ou companheiros de equipe. Apenas o líder pode gerenciar a equipe.475* **Sem equipes aninhadas**: os companheiros de equipe não podem gerar seus próprios companheiros de equipe. Apenas o líder pode gerenciar a equipe.

488* **Líder é fixo**: a sessão que cria a equipe é o líder por sua vida útil. Você não pode promover um companheiro de equipe a líder ou transferir liderança.476* **Líder é fixo**: a sessão principal é o líder por sua vida útil. Você não pode promover um companheiro de equipe a líder ou transferir liderança.

489* **Permissões definidas no tempo de geração**: todos os companheiros de equipe começam com o modo de permissão do líder. Você pode alterar modos de companheiros de equipe individuais após gerar, mas não pode definir modos por companheiro de equipe no tempo de geração.477* **Permissões definidas no tempo de geração**: todos os companheiros de equipe começam com o modo de permissão do líder. Você pode alterar modos de companheiros de equipe individuais após gerar, mas não pode definir modos por companheiro de equipe no tempo de geração.

490* **Split panes requerem tmux ou iTerm2**: o modo in-process padrão funciona em qualquer terminal. O modo split-pane não é suportado no terminal integrado do VS Code, Windows Terminal ou Ghostty.478* **Split panes requerem tmux ou iTerm2**: o modo in-process padrão funciona em qualquer terminal. O modo split-pane não é suportado no terminal integrado do VS Code, Windows Terminal ou Ghostty.

491 479 

agent-view.md +11 −6

Details

143 143 

144O resumo de uma linha em cada linha é gerado por um [modelo Haiku-class](/pt/model-config) para que a linha possa informar o que a sessão está fazendo, o que precisa ou o que produziu sem abrir o transcript. Enquanto uma sessão está ativamente funcionando, o resumo é atualizado no máximo uma vez a cada 15 segundos, mais uma vez quando cada turno termina.144O resumo de uma linha em cada linha é gerado por um [modelo Haiku-class](/pt/model-config) para que a linha possa informar o que a sessão está fazendo, o que precisa ou o que produziu sem abrir o transcript. Enquanto uma sessão está ativamente funcionando, o resumo é atualizado no máximo uma vez a cada 15 segundos, mais uma vez quando cada turno termina.

145 145 

146A partir da v2.1.161, quando a sessão está executando dois ou mais itens de trabalho paralelos, como subagents, comandos shell em background ou monitores, uma contagem `done/total` como `2/5` aparece antes do texto do resumo.

147 

146Cada atualização é uma solicitação curta de Haiku-class através de seu provedor normal, cobrada e tratada sob os mesmos [termos de uso de dados](/pt/data-usage) que a sessão em si. Em provedores de terceiros como Bedrock, Vertex AI, Microsoft Foundry e gateways personalizados, a solicitação volta para o modelo principal da sessão quando nenhum modelo Haiku está configurado. Defina [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/pt/model-config#environment-variables) para escolher o modelo para esses resumos nesses provedores.148Cada atualização é uma solicitação curta de Haiku-class através de seu provedor normal, cobrada e tratada sob os mesmos [termos de uso de dados](/pt/data-usage) que a sessão em si. Em provedores de terceiros como Bedrock, Vertex AI, Microsoft Foundry e gateways personalizados, a solicitação volta para o modelo principal da sessão quando nenhum modelo Haiku está configurado. Defina [`ANTHROPIC_DEFAULT_HAIKU_MODEL`](/pt/model-config#environment-variables) para escolher o modelo para esses resumos nesses provedores.

147 149 

148<h3 id="pull-request-status">150<h3 id="pull-request-status">


170 172 

171Pressione `Space` em uma linha selecionada para abrir o painel de espiada. Ele mostra o que a sessão precisa de você, sua saída mais recente e quaisquer pull requests que abriu. Na maioria das vezes, isso é suficiente e você nunca precisa abrir o transcript completo.173Pressione `Space` em uma linha selecionada para abrir o painel de espiada. Ele mostra o que a sessão precisa de você, sua saída mais recente e quaisquer pull requests que abriu. Na maioria das vezes, isso é suficiente e você nunca precisa abrir o transcript completo.

172 174 

175A partir da v2.1.161, quando a sessão está executando itens de trabalho paralelos, o painel também nomeia o que está em execução há mais tempo e há quanto tempo está acontecendo, para que você possa ver o que a sessão está aguardando sem anexar.

176 

173Digite uma resposta no painel de espiada e pressione `Enter` para enviá-la para essa sessão. Quando a sessão está fazendo uma pergunta de múltipla escolha, o painel de espiada mostra as opções e você pode pressionar uma tecla numérica para escolher uma. Para outras sessões bloqueadas, pressione `Tab` para preencher a entrada com uma resposta sugerida que você pode editar antes de enviar. Prefixe uma resposta com `!` para enviar um comando Bash em vez disso.177Digite uma resposta no painel de espiada e pressione `Enter` para enviá-la para essa sessão. Quando a sessão está fazendo uma pergunta de múltipla escolha, o painel de espiada mostra as opções e você pode pressionar uma tecla numérica para escolher uma. Para outras sessões bloqueadas, pressione `Tab` para preencher a entrada com uma resposta sugerida que você pode editar antes de enviar. Prefixe uma resposta com `!` para enviar um comando Bash em vez disso.

174 178 

175Com [voice dictation](/pt/voice-dictation) ativada, segure ou toque sua tecla push-to-talk enquanto a entrada de resposta está focada para ditar uma resposta em vez de digitá-la. O mesmo funciona na entrada de despacho na parte inferior de agent view.179A partir da v2.1.145, com [voice dictation](/pt/voice-dictation) ativada, segure ou toque sua tecla push-to-talk enquanto a entrada de resposta está focada para ditar uma resposta em vez de digitá-la. O mesmo funciona na entrada de despacho na parte inferior de agent view.

176 180 

177Use `↑` e `↓` para espreitar sessões adjacentes sem fechar o painel, ou `→` para anexar.181Use `↑` e `↓` para espreitar sessões adjacentes sem fechar o painel, ou `→` para anexar.

178 182 


224| `a:<name>` | Sessões executando o agente nomeado |228| `a:<name>` | Sessões executando o agente nomeado |

225| `s:<state>` | Sessões no estado fornecido, como `s:working`. Também aceita `s:blocked` para tudo que está aguardando você |229| `s:<state>` | Sessões no estado fornecido, como `s:working`. Também aceita `s:blocked` para tudo que está aguardando você |

226| `#<number>` ou uma URL de PR | A sessão trabalhando naquele pull request |230| `#<number>` ou uma URL de PR | A sessão trabalhando naquele pull request |

231| Qualquer outra URL | A sessão cujo primeiro prompt continha essa URL |

227 232 

228<h3 id="keyboard-shortcuts">233<h3 id="keyboard-shortcuts">

229 Atalhos de teclado234 Atalhos de teclado


478Cada sessão em background tem um ID curto que você pode usar do shell. O ID é impresso quando você inicia uma sessão com `claude --bg`, e o ID de cada sessão é seu nome de diretório em `~/.claude/jobs/`. Esses comandos são úteis para scripts ou quando você não quer abrir agent view.483Cada sessão em background tem um ID curto que você pode usar do shell. O ID é impresso quando você inicia uma sessão com `claude --bg`, e o ID de cada sessão é seu nome de diretório em `~/.claude/jobs/`. Esses comandos são úteis para scripts ou quando você não quer abrir agent view.

479 484 

480| Comando | Propósito |485| Comando | Propósito |

481| :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |486| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

482| `claude agents` | Abrir agent view |487| `claude agents` | Abrir agent view |

483| `claude agents --cwd <path>` | Abrir agent view com escopo para sessões iniciadas em `<path>` |488| `claude agents --cwd <path>` | Abrir agent view com escopo para sessões iniciadas em `<path>` |

484| `claude agents --json` | Imprimir sessões ativas como um array JSON e sair. Cada entrada tem `pid`, `cwd`, `kind` e `startedAt`, além de `sessionId`, `name` e `status` quando definidos. Combine com `--cwd <path>` para filtrar |489| `claude agents --json` | Imprimir sessões ativas como um array JSON e sair: cada sessão ativa, mais sessões em background que ainda estão funcionando ou bloqueadas mesmo quando seu processo saiu. Adicione `--all` para também incluir sessões em background concluídas. Cada entrada tem `cwd`, `kind` e `startedAt`. Entradas em background também têm `id`, utilizável com `claude attach`/`logs`/`stop`, e `state`: um de `working`, `blocked`, `done`, `failed` ou `stopped`. `pid` e `status` estão presentes apenas enquanto o processo está ativo, mais `waitingFor` quando status é `waiting`, que diz no que a sessão está bloqueada, como `permission prompt` ou `input needed`; `sessionId` e `name` aparecem quando definidos. Combine com `--cwd <path>` para filtrar |

485| `claude attach <id>` | Anexar a uma sessão neste terminal |490| `claude attach <id>` | Anexar a uma sessão neste terminal |

486| `claude logs <id>` | Imprimir a saída recente da sessão |491| `claude logs <id>` | Imprimir a saída recente da sessão |

487| `claude stop <id>` | Interromper uma sessão. Também aceita `claude kill` |492| `claude stop <id>` | Interromper uma sessão. Também aceita `claude kill` |


556 561 

557Antes de você despachar sua primeira sessão, agent view mostra uma dica de integração breve com prompts de exemplo no lugar da lista de sessões. Digite um prompt na entrada na parte inferior e pressione `Enter` para despachar sua primeira sessão.562Antes de você despachar sua primeira sessão, agent view mostra uma dica de integração breve com prompts de exemplo no lugar da lista de sessões. Digite um prompt na entrada na parte inferior e pressione `Enter` para despachar sua primeira sessão.

558 563 

559<h3 id="cannot-open-agents-because-background-tasks-are-running">564<h3 id="cannot-open-agents-because-work-is-running-in-the-background">

560 Cannot open agents because background tasks are running565 Cannot open agents because work is running in the background

561</h3>566</h3>

562 567 

563Se pressionar `←` para colocar a sessão atual em background mostrar `Cannot open agents — N background task(s) running`, a sessão tem trabalho em andamento, como um subagente, um workflow dinâmico ou um comando shell em background, e o atalho não o abandonará silenciosamente. Execute `/tasks` para ver o que está em execução, depois `/bg` para confirmar o abandono deles. Veja [From inside a session](#from-inside-a-session) para saber o que é e o que não é transferido quando você coloca em background.568Se pressionar `←` para colocar a sessão atual em background mostrar `Cannot open agents — N still running in the background`, a sessão tem trabalho em andamento, como um subagente, um workflow dinâmico ou um comando shell em background, e o atalho não o abandonará silenciosamente. Execute `/tasks` para ver o que está em execução, depois `/bg` para confirmar o abandono deles. Veja [From inside a session](#from-inside-a-session) para saber o que é e o que não é transferido quando você coloca em background.

564 569 

565<h3 id="prompt-rejected-as-too-short">570<h3 id="prompt-rejected-as-too-short">

566 Prompt rejected as too short571 Prompt rejected as too short

agents.md +2 −2

Details

9[Subagentes](/pt/sub-agents), [visualização de agentes](/pt/agent-view), [equipes de agentes](/pt/agent-teams) e [workflows dinâmicos](/pt/workflows) cada um paraleliza o trabalho de uma forma diferente. O correto depende de se você quer permanecer em cada conversa você mesmo, delegar tarefas e verificar depois, ou ter Claude coordenando um grupo de trabalhadores para você.9[Subagentes](/pt/sub-agents), [visualização de agentes](/pt/agent-view), [equipes de agentes](/pt/agent-teams) e [workflows dinâmicos](/pt/workflows) cada um paraleliza o trabalho de uma forma diferente. O correto depende de se você quer permanecer em cada conversa você mesmo, delegar tarefas e verificar depois, ou ter Claude coordenando um grupo de trabalhadores para você.

10 10 

11| Abordagem | O que oferece | Use quando |11| Abordagem | O que oferece | Use quando |

12| :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |12| :---------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

13| [Subagentes](/pt/sub-agents) | Trabalhadores delegados dentro de uma sessão que fazem uma tarefa secundária em seu próprio contexto e retornam um resumo | Uma tarefa secundária inundaria sua conversa principal com resultados de pesquisa, logs ou conteúdos de arquivo que você não consultará novamente |13| [Subagentes](/pt/sub-agents) | Trabalhadores delegados dentro de uma sessão que fazem uma tarefa secundária em seu próprio contexto e retornam um resumo | Uma tarefa secundária inundaria sua conversa principal com resultados de pesquisa, logs ou conteúdos de arquivo que você não consultará novamente |

14| [Visualização de agentes](/pt/agent-view) | Uma tela para despachar e monitorar sessões em execução em segundo plano, aberta com `claude agents`. Visualização de pesquisa | Você tem várias tarefas independentes e quer delegá-las, verificar o status rapidamente e intervir apenas quando uma precisar de você |14| [Visualização de agentes](/pt/agent-view) | Uma tela para despachar e monitorar sessões em execução em segundo plano, aberta com `claude agents`. Visualização de pesquisa | Você tem várias tarefas independentes e quer delegá-las, verificar o status rapidamente e intervir apenas quando uma precisar de você |

15| [Equipes de agentes](/pt/agent-teams) | Múltiplas sessões coordenadas com uma lista de tarefas compartilhada e mensagens entre agentes, gerenciadas por um líder. Experimental e desabilitado por padrão | Você quer que Claude divida um projeto em partes, as atribua e mantenha os trabalhadores sincronizados |15| [Equipes de agentes](/pt/agent-teams) | Múltiplas sessões coordenadas com uma lista de tarefas compartilhada e mensagens entre agentes, gerenciadas por um líder. Experimental e desabilitado por padrão | Você quer que Claude divida um projeto em partes, as atribua e mantenha os trabalhadores sincronizados |

16| [Workflows dinâmicos](/pt/workflows) | Um script que executa muitos subagentes e verifica seus resultados, para um trabalho muito grande para coordenar em um único turno ou que precisa de mais de uma passagem. Visualização de pesquisa | Uma tarefa cresce além de um punhado de subagentes, ou você quer que as descobertas sejam verificadas uma contra a outra: uma auditoria em toda a base de código, uma migração de 500 arquivos, pesquisa com verificação cruzada ou um plano elaborado de vários ângulos |16| [Workflows dinâmicos](/pt/workflows) | Um script que executa muitos subagentes e verifica seus resultados, para um trabalho muito grande para coordenar em um único turno ou que precisa de mais de uma passagem | Uma tarefa cresce além de um punhado de subagentes, ou você quer que as descobertas sejam verificadas uma contra a outra: uma auditoria em toda a base de código, uma migração de 500 arquivos, pesquisa com verificação cruzada ou um plano elaborado de vários ângulos |

17 17 

18Em cada abordagem, os trabalhadores são sessões Claude. Para envolver uma ferramenta diferente, exponha-a ao Claude como um [servidor MCP](/pt/mcp).18Em cada abordagem, os trabalhadores são sessões Claude. Para envolver uma ferramenta diferente, exponha-a ao Claude como um [servidor MCP](/pt/mcp).

19 19 

Details

6 6 

7> Saiba como configurar Claude Code através do Amazon Bedrock, incluindo configuração, configuração de IAM e resolução de problemas.7> Saiba como configurar Claude Code através do Amazon Bedrock, incluindo configuração, configuração de IAM e resolução de problemas.

8 8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

79<ContactSalesCard surface="bedrock" />

80 

9<h2 id="prerequisites">81<h2 id="prerequisites">

10 Pré-requisitos82 Pré-requisitos

11</h2>83</h2>


108 Configuração avançada de credenciais180 Configuração avançada de credenciais

109</h4>181</h4>

110 182 

111Claude Code suporta atualização automática de credenciais para AWS SSO e provedores de identidade corporativa. Adicione estas configurações ao seu arquivo de configurações do Claude Code (veja [Configurações](/pt/settings) para localizações de arquivo).183Claude Code suporta atualização automática de credenciais para AWS SSO e provedores de identidade corporativa. Adicione estas configurações ao seu arquivo de configurações do Claude Code (veja [Settings](/pt/settings) para localizações de arquivo).

112 184 

113Estas duas configurações têm diferentes condições de acionamento:185Estas duas configurações têm diferentes condições de acionamento:

114 186 


141 "Credentials": {213 "Credentials": {

142 "AccessKeyId": "value",214 "AccessKeyId": "value",

143 "SecretAccessKey": "value",215 "SecretAccessKey": "value",

144 "SessionToken": "value"216 "SessionToken": "value",

217 "Expiration": "2026-01-01T00:00:00Z"

145 }218 }

146}219}

147```220```

148 221 

222`Expiration` é opcional. {/* min-version: 2.1.176 */}A partir do Claude Code v2.1.176, quando o comando retorna um `Expiration` ISO 8601 válido, Claude Code armazena em cache as credenciais até cinco minutos antes dessa hora. Sem ele, ou em versões anteriores, as credenciais são armazenadas em cache por uma hora.

223 

149<h3 id="3-configure-claude-code">224<h3 id="3-configure-claude-code">

150 3. Configurar Claude Code225 3. Configurar Claude Code

151</h3>226</h3>


155```bash theme={null}230```bash theme={null}

156# Habilitar integração Bedrock231# Habilitar integração Bedrock

157export CLAUDE_CODE_USE_BEDROCK=1232export CLAUDE_CODE_USE_BEDROCK=1

158export AWS_REGION=us-east-1 # ou sua região preferida233export AWS_REGION=us-east-1 # opcional se seu perfil AWS já define uma região

159 234 

160# Opcional: Substituir a região AWS para o modelo pequeno/rápido (Bedrock e Mantle).235# Opcional: Substituir a região AWS para o modelo pequeno/rápido (Bedrock e Mantle).

161# No Bedrock, não tem efeito sem ANTHROPIC_DEFAULT_HAIKU_MODEL236# No Bedrock, não tem efeito sem ANTHROPIC_DEFAULT_HAIKU_MODEL


168 243 

169Ao habilitar Bedrock para Claude Code, tenha em mente o seguinte:244Ao habilitar Bedrock para Claude Code, tenha em mente o seguinte:

170 245 

171* `AWS_REGION` é uma variável de ambiente obrigatória. Claude Code não do arquivo de configuração `.aws` para esta configuração.246* {/* min-version: 2.1.172 */}A partir da v2.1.172, você só precisa definir `AWS_REGION` para substituir a região do seu perfil AWS ou quando seu perfil não tem região. Claude Code resolve a região nesta ordem:

247 

248 * `AWS_REGION`

249 * `AWS_DEFAULT_REGION`

250 * a `region` definida em seu perfil AWS ativo, lida do arquivo de credenciais compartilhadas AWS primeiro e depois do arquivo de configuração compartilhada, correspondendo à precedência do AWS SDK

251 * `us-east-1`

252 

253 O perfil ativo é `AWS_PROFILE` se definido, caso contrário `default`. Defina `AWS_SHARED_CREDENTIALS_FILE` ou `AWS_CONFIG_FILE` para apontar para caminhos de arquivo não padrão. Execute `/status` para ver a região resolvida. Quando a região veio de seus arquivos de configuração AWS ou do fallback padrão, `/status` também anota a fonte. Na v2.1.171 e anterior, Claude Code não lê os arquivos de configuração AWS, então defina `AWS_REGION` explicitamente.

172* Ao usar Bedrock, o comando `/logout` não está disponível, pois a autenticação é tratada através de credenciais AWS.254* Ao usar Bedrock, o comando `/logout` não está disponível, pois a autenticação é tratada através de credenciais AWS.

173* A ferramenta WebSearch não está disponível no Bedrock. Veja [comportamento da ferramenta WebSearch](/pt/tools-reference#websearch-tool-behavior).255* A ferramenta WebSearch não está disponível no Bedrock. Veja [comportamento da ferramenta WebSearch](/pt/tools-reference#websearch-tool-behavior).

174* Você pode usar arquivos de configurações para variáveis de ambiente como `AWS_PROFILE` que você não quer vazar para outros processos. Veja [Configurações](/pt/settings) para mais informações.256* Você pode usar arquivos de configurações para variáveis de ambiente como `AWS_PROFILE` que você não quer vazar para outros processos. Veja [Settings](/pt/settings) para mais informações.

175 257 

176<h3 id="4-pin-model-versions">258<h3 id="4-pin-model-versions">

177 4. Fixar versões de modelo259 4. Fixar versões de modelo

178</h3>260</h3>

179 261 

180<Warning>262<Warning>

181 Fixe versões de modelo específicas ao implantar para vários usuários. Sem fixação, aliases de modelo como `sonnet` e `opus` resolvem para a versão mais recente, que pode não estar disponível em sua conta Bedrock quando Anthropic lançar uma atualização. Claude Code [volta](#startup-model-checks) para a versão anterior na inicialização quando a versão mais recente não está disponível, mas fixação permite que você controle quando seus usuários se movem para um novo modelo.263 Fixe versões de modelo específicas ao implantar para vários usuários. Sem fixação, aliases de modelo como `sonnet` e `opus` resolvem para o padrão integrado do Claude Code para Bedrock, que pode ficar atrás da versão mais recente e pode ainda não estar disponível em sua conta. Claude Code [volta](#startup-model-checks) para a versão anterior na inicialização quando o padrão não está disponível, mas fixação permite que você controle quando seus usuários se movem para um novo modelo.

182</Warning>264</Warning>

183 265 

184Defina estas variáveis de ambiente para IDs de modelo Bedrock específicos.266Defina estas variáveis de ambiente para IDs de modelo Bedrock específicos.


191export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'273export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

192```274```

193 275 

194Estas variáveis usam IDs de perfil de inferência entre regiões (com o prefixo `us.`). Se você usar um prefixo de região diferente ou perfis de inferência de aplicação, ajuste de acordo. Para IDs de modelo atuais e legados, veja [Visão geral de modelos](https://platform.claude.com/docs/en/about-claude/models/overview). Veja [Configuração de modelo](/pt/model-config#pin-models-for-third-party-deployments) para a lista completa de variáveis de ambiente.276Estas variáveis usam IDs de perfil de inferência entre regiões (com o prefixo `us.`). Se você usar um prefixo de região diferente ou perfis de inferência de aplicação, ajuste de acordo. Em regiões AWS GovCloud, use o prefixo `us-gov.`. Para IDs de modelo atuais e legados, veja [Visão geral de modelos](https://platform.claude.com/docs/en/about-claude/models/overview). Veja [Configuração de modelo](/pt/model-config#pin-models-for-third-party-deployments) para a lista completa de variáveis de ambiente.

195 277 

196Claude Code usa estes modelos padrão quando nenhuma variável de fixação está definida:278Claude Code usa estes modelos padrão quando nenhuma variável de fixação está definida:

197 279 


313 Janela de contexto de 1M de tokens395 Janela de contexto de 1M de tokens

314</h2>396</h2>

315 397 

316Claude Opus 4.6 e posteriores, e Sonnet 4.6, suportam a [janela de contexto de 1M de tokens](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) no Amazon Bedrock. Claude Code habilita automaticamente a janela de contexto estendida quando você seleciona uma variante de modelo de 1M.398Claude Opus 4.6 e posteriores, e Sonnet 4.6, suportam a [janela de contexto de 1M de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) no Amazon Bedrock. Claude Code habilita automaticamente a janela de contexto estendida quando você seleciona uma variante de modelo de 1M.

317 399 

318O [assistente de configuração](#sign-in-with-bedrock) oferece uma opção de contexto de 1M quando fixa modelos. Para habilitá-lo para um modelo fixado manualmente em vez disso, acrescente `[1m]` ao ID do modelo. Veja [Fixar modelos para implantações de terceiros](/pt/model-config#pin-models-for-third-party-deployments) para detalhes.400O [assistente de configuração](#sign-in-with-bedrock) oferece uma opção de contexto de 1M quando fixa modelos. Para habilitá-lo para um modelo fixado manualmente em vez disso, acrescente `[1m]` ao ID do modelo. Veja [Fixar modelos para implantações de terceiros](/pt/model-config#pin-models-for-third-party-deployments) para detalhes.

319 401 


366export AWS_REGION=us-east-1448export AWS_REGION=us-east-1

367```449```

368 450 

369Claude Code constrói a URL do endpoint a partir de `AWS_REGION`. Para substituí-la por um endpoint personalizado ou gateway, defina `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`.451Claude Code constrói a URL do endpoint a partir da região AWS. {/* min-version: 2.1.172 */}A partir da v2.1.172, a região é resolvida com a mesma precedência que [Bedrock acima](#3-configure-claude-code); versões anteriores usam apenas `AWS_REGION`. Para substituir a URL por um endpoint personalizado ou gateway, defina `ANTHROPIC_BEDROCK_MANTLE_BASE_URL`.

370 452 

371Execute `/status` dentro do Claude Code para confirmar. A linha do provedor mostra `Amazon Bedrock (Mantle)` quando Mantle está ativo.453Execute `/status` dentro do Claude Code para confirmar. A linha do provedor mostra `Amazon Bedrock (Mantle)` quando Mantle está ativo.

372 454 

Details

6 6 

7> Diga ao classificador do modo automático quais repositórios, buckets e domínios sua organização confia. Defina o contexto do ambiente, substitua as regras padrão de bloqueio e permissão, e inspecione sua configuração efetiva com os subcomandos CLI do auto mode.7> Diga ao classificador do modo automático quais repositórios, buckets e domínios sua organização confia. Defina o contexto do ambiente, substitua as regras padrão de bloqueio e permissão, e inspecione sua configuração efetiva com os subcomandos CLI do auto mode.

8 8 

9[Auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode) permite que Claude Code seja executado sem prompts de permissão, roteando cada chamada de ferramenta através de um classificador que bloqueia qualquer coisa irreversível, destrutiva ou direcionada para fora do seu ambiente. Use o bloco de configurações `autoMode` para dizer ao classificador quais repositórios, buckets e domínios sua organização confia, para que ele pare de bloquear operações internas rotineiras.9[Auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode) permite que Claude Code seja executado sem prompts de permissão rotineiros, roteando chamadas de ferramenta através de um classificador que bloqueia qualquer coisa irreversível, destrutiva ou direcionada para fora do seu ambiente. Regras de negação e solicitação explícita são avaliadas antes do classificador e ainda bloqueiam ou solicitam. Use o bloco de configurações `autoMode` para dizer ao classificador quais repositórios, buckets e domínios sua organização confia, para que ele pare de bloquear operações internas rotineiras.

10 10 

11<Note>11<Note>

12 Auto mode está disponível para todos os usuários na API Anthropic. No Amazon Bedrock, Google Cloud Vertex AI e Microsoft Foundry, você deve primeiro [definir `CLAUDE_CODE_ENABLE_AUTO_MODE`](/pt/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry). Se Claude Code relatar que o auto mode não está disponível para sua conta, verifique os [requisitos completos](/pt/permission-modes#eliminate-prompts-with-auto-mode), que também cobrem os modelos suportados e a habilitação de administrador nos planos Team e Enterprise.12 Auto mode está disponível para todos os usuários na API Anthropic. No Amazon Bedrock, Google Cloud Vertex AI e Microsoft Foundry, você deve primeiro [definir `CLAUDE_CODE_ENABLE_AUTO_MODE`](/pt/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry). Se Claude Code relatar que o auto mode não está disponível para sua conta, verifique os [requisitos completos](/pt/permission-modes#eliminate-prompts-with-auto-mode), que também cobrem os modelos suportados e a habilitação de administrador nos planos Team e Enterprise.


35| Escopo | Arquivo | Use para |35| Escopo | Arquivo | Use para |

36| :----------------------------- | :---------------------------------------------- | :----------------------------------------------------------------- |36| :----------------------------- | :---------------------------------------------- | :----------------------------------------------------------------- |

37| Um desenvolvedor | `~/.claude/settings.json` | Infraestrutura confiável pessoal |37| Um desenvolvedor | `~/.claude/settings.json` | Infraestrutura confiável pessoal |

38| Um projeto, um desenvolvedor | `.claude/settings.local.json` | Buckets ou serviços confiáveis por projeto, gitignored |38| Um projeto, um desenvolvedor | `.claude/settings.local.json` | Buckets ou serviços confiáveis por projeto |

39| Em toda a organização | [Managed settings](/pt/server-managed-settings) | Infraestrutura confiável distribuída para todos os desenvolvedores |39| Em toda a organização | [Managed settings](/pt/server-managed-settings) | Infraestrutura confiável distribuída para todos os desenvolvedores |

40| Flag `--settings` ou Agent SDK | JSON inline | Substituições por invocação para automação |40| Flag `--settings` ou Agent SDK | JSON inline | Substituições por invocação para automação |

41 41 


188Para reagir a negações programaticamente, use o hook [`PermissionDenied`](/pt/hooks#permissiondenied).188Para reagir a negações programaticamente, use o hook [`PermissionDenied`](/pt/hooks#permissiondenied).

189 189 

190<h2 id="see-also">190<h2 id="see-also">

191 See also191 Veja também

192</h2>192</h2>

193 193 

194* [Permission modes](/pt/permission-modes#eliminate-prompts-with-auto-mode): o que é modo automático, o que ele bloqueia por padrão e como ativá-lo194* [Permission modes](/pt/permission-modes#eliminate-prompts-with-auto-mode): o que é modo automático, o que ele bloqueia por padrão e como ativá-lo

Details

63 Separe pesquisa e planejamento da implementação para evitar resolver o problema errado.63 Separe pesquisa e planejamento da implementação para evitar resolver o problema errado.

64</Tip>64</Tip>

65 65 

66Deixar Claude pular direto para codificação pode produzir código que resolve o problema errado. Use [Plan Mode](/pt/permission-modes#analyze-before-you-edit-with-plan-mode) para separar exploração de execução.66Deixar Claude pular direto para codificação pode produzir código que resolve o problema errado. Use [plan mode](/pt/permission-modes#analyze-before-you-edit-with-plan-mode) para separar exploração de execução.

67 67 

68O fluxo de trabalho recomendado tem quatro fases:68O fluxo de trabalho recomendado tem quatro fases:

69 69 

70<Steps>70<Steps>

71 <Step title="Explore">71 <Step title="Explore">

72 Entre em Plan Mode. Claude lê arquivos e responde perguntas sem fazer alterações.72 Entre em plan mode. Claude lê arquivos e responde perguntas sem fazer alterações.

73 73 

74 ```txt claude (plan mode) theme={null}74 ```txt claude (plan mode) theme={null}

75 read /src/auth and understand how we handle sessions and login.75 read /src/auth and understand how we handle sessions and login.


89 </Step>89 </Step>

90 90 

91 <Step title="Implement">91 <Step title="Implement">

92 Saia de Plan Mode e deixe Claude codificar, verificando contra seu plano.92 Saia de plan mode e deixe Claude codificar, verificando contra seu plano.

93 93 

94 ```txt claude (default mode) theme={null}94 ```txt claude (default mode) theme={null}

95 implement the OAuth flow from your plan. write tests for the95 implement the OAuth flow from your plan. write tests for the


107</Steps>107</Steps>

108 108 

109<Callout>109<Callout>

110 Plan Mode é útil, mas também adiciona sobrecarga.110 Plan mode é útil, mas também adiciona sobrecarga.

111 111 

112 Para tarefas onde o escopo é claro e a correção é pequena (como corrigir um erro de digitação, adicionar uma linha de log ou renomear uma variável) peça ao Claude para fazer isso diretamente.112 Para tarefas onde o escopo é claro e a correção é pequena (como corrigir um erro de digitação, adicionar uma linha de log ou renomear uma variável) peça ao Claude para fazer isso diretamente.

113 113 

channels.md +2 −2

Details

349 349 

350Durante a visualização, `--channels` aceita apenas plugins de uma lista de permissão mantida pela Anthropic, ou da lista de permissão da sua organização se um administrador tiver definido [`allowedChannelPlugins`](#restrict-which-channel-plugins-can-run). Os plugins de canal em [claude-plugins-official](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) são o conjunto aprovado padrão. Se você passar algo que não esteja na lista de permissão efetiva, Claude Code inicia normalmente, mas o canal não se registra, e o aviso de inicialização informa por quê.350Durante a visualização, `--channels` aceita apenas plugins de uma lista de permissão mantida pela Anthropic, ou da lista de permissão da sua organização se um administrador tiver definido [`allowedChannelPlugins`](#restrict-which-channel-plugins-can-run). Os plugins de canal em [claude-plugins-official](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) são o conjunto aprovado padrão. Se você passar algo que não esteja na lista de permissão efetiva, Claude Code inicia normalmente, mas o canal não se registra, e o aviso de inicialização informa por quê.

351 351 

352Para testar um canal que você está criando, use `--dangerously-load-development-channels`. Veja [Test during the research preview](/pt/channels-reference#test-during-the-research-preview) para informações sobre como testar canais personalizados que você cria.352Para testar um canal que você está criando, use `--dangerously-load-development-channels`. Veja [Testar durante a visualização de pesquisa](/pt/channels-reference#test-during-the-research-preview) para informações sobre como testar canais personalizados que você cria.

353 353 

354Relate problemas ou feedback no [repositório GitHub do Claude Code](https://github.com/anthropics/claude-code/issues).354Relate problemas ou feedback no [repositório GitHub do Claude Code](https://github.com/anthropics/claude-code/issues).

355 355 


363| ------------------------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------- |363| ------------------------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------- |

364| [Claude Code na web](/pt/claude-code-on-the-web) | Executa tarefas em uma nova sandbox na nuvem, clonada do GitHub | Delegar trabalho assíncrono independente que você verifica depois |364| [Claude Code na web](/pt/claude-code-on-the-web) | Executa tarefas em uma nova sandbox na nuvem, clonada do GitHub | Delegar trabalho assíncrono independente que você verifica depois |

365| [Claude no Slack](/pt/slack) | Gera uma sessão web a partir de uma menção `@Claude` em um canal ou thread | Iniciar tarefas diretamente do contexto de conversa da equipe |365| [Claude no Slack](/pt/slack) | Gera uma sessão web a partir de uma menção `@Claude` em um canal ou thread | Iniciar tarefas diretamente do contexto de conversa da equipe |

366| [Servidor MCP](/pt/mcp) padrão | Claude o consulta durante uma tarefa; nada é enviado para a sessão | Dar ao Claude acesso sob demanda para ler ou consultar um sistema |366| Servidor [MCP](/pt/mcp) padrão | Claude o consulta durante uma tarefa; nada é enviado para a sessão | Dar ao Claude acesso sob demanda para ler ou consultar um sistema |

367| [Remote Control](/pt/remote-control) | Você dirige sua sessão local de claude.ai ou do aplicativo móvel Claude | Dirigir uma sessão em andamento enquanto está longe de sua mesa |367| [Remote Control](/pt/remote-control) | Você dirige sua sessão local de claude.ai ou do aplicativo móvel Claude | Dirigir uma sessão em andamento enquanto está longe de sua mesa |

368 368 

369Os canais preenchem a lacuna nessa lista enviando eventos de fontes não-Claude para sua sessão local já em execução.369Os canais preenchem a lacuna nessa lista enviando eventos de fontes não-Claude para sua sessão local já em execução.

Details

60 60 

61Este passo a passo constrói um servidor de arquivo único que escuta solicitações HTTP e as encaminha para sua sessão Claude Code. No final, qualquer coisa que possa enviar um HTTP POST, como um pipeline de CI, um alerta de monitoramento ou um comando `curl`, pode enviar eventos para Claude.61Este passo a passo constrói um servidor de arquivo único que escuta solicitações HTTP e as encaminha para sua sessão Claude Code. No final, qualquer coisa que possa enviar um HTTP POST, como um pipeline de CI, um alerta de monitoramento ou um comando `curl`, pode enviar eventos para Claude.

62 62 

63Este exemplo usa [Bun](https://bun.sh) como o runtime para seu servidor HTTP integrado e suporte a TypeScript. Você pode usar [Node](https://nodejs.org) ou [Deno](https://deno.com) em vez disso; o único requisito é o [SDK MCP](https://www.npmjs.com/package/@modelcontextprotocol/sdk).63Este exemplo usa [Bun](https://bun.sh) como o runtime para seu servidor HTTP integrado e suporte a TypeScript. Você pode usar [Node](https://nodejs.org) ou [Deno](https://deno.com) em vez disso; o único requisito é o [MCP SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk).

64 64 

65<Steps>65<Steps>

66 <Step title="Criar o projeto">66 <Step title="Criar o projeto">

67 Crie um novo diretório e instale o SDK MCP:67 Crie um novo diretório e instale o MCP SDK:

68 68 

69 ```bash theme={null}69 ```bash theme={null}

70 mkdir webhook-channel && cd webhook-channel70 mkdir webhook-channel && cd webhook-channel


142 claude --dangerously-load-development-channels server:webhook142 claude --dangerously-load-development-channels server:webhook

143 ```143 ```

144 144 

145 A primeira vez que você inicia uma sessão neste projeto, Claude Code pede consentimento antes de usar o novo servidor de `.mcp.json`. O diálogo relata "New MCP server found in this project: webhook". Selecione **Use this MCP server** para continuar.

146 

145 Quando Claude Code inicia, ele lê sua configuração MCP, spawna seu `webhook.ts` como um subprocesso, e o listener HTTP inicia automaticamente na porta que você configurou (8788 neste exemplo). Você não precisa executar o servidor você mesmo.147 Quando Claude Code inicia, ele lê sua configuração MCP, spawna seu `webhook.ts` como um subprocesso, e o listener HTTP inicia automaticamente na porta que você configurou (8788 neste exemplo). Você não precisa executar o servidor você mesmo.

146 148 

149 Um aviso atenuado abaixo do banner de inicialização confirma que o channel está registrado: `Channels (experimental) messages from server:webhook inject directly in this session · restart without --dangerously-load-development-channels to stop`.

150 

147 Se você vir "blocked by org policy," seu administrador de organização precisa [habilitar channels](/pt/channels#enterprise-controls) primeiro.151 Se você vir "blocked by org policy," seu administrador de organização precisa [habilitar channels](/pt/channels#enterprise-controls) primeiro.

148 152 

149 Em um terminal separado, simule um webhook enviando um HTTP POST com uma mensagem para seu servidor. Este exemplo envia um alerta de falha de CI para a porta 8788 (ou qualquer porta que você configurou):153 Em um terminal separado, simule um webhook enviando um HTTP POST com uma mensagem para seu servidor. Este exemplo envia um alerta de falha de CI para a porta 8788 (ou qualquer porta que você configurou):


753curl -d "list the files in this directory" -H "X-Sender: dev" localhost:8788757curl -d "list the files in this directory" -H "X-Sender: dev" localhost:8788

754```758```

755 759 

756O diálogo de permissão local abre em seu terminal Claude Code. Um momento depois o prompt aparece no stream `/events`, incluindo o ID de cinco letras. Aprove-o do lado remoto:760Listar arquivos é somente leitura, então Claude o executa sem aprovação. O diálogo de permissão abre quando Claude chama a ferramenta `reply` para enviar sua resposta de volta. O diálogo local abre em seu terminal Claude Code, e um momento depois o prompt para `mcp__webhook__reply` aparece no stream `/events`, incluindo o ID de cinco letras. Aprove-o do lado remoto:

757 761 

758```bash theme={null}762```bash theme={null}

759curl -d "yes <id>" -H "X-Sender: dev" localhost:8788763curl -d "yes <id>" -H "X-Sender: dev" localhost:8788

760```764```

761 765 

762O diálogo local fecha e a ferramenta é executada. A resposta de Claude volta através da ferramenta `reply` e chega no stream também.766O diálogo local fecha, a ferramenta `reply` é executada, e a resposta de Claude chega no stream.

763 767 

764As três peças específicas de channel neste arquivo:768As três peças específicas de channel neste arquivo:

765 769 

Details

59 59 

60Cada sessão é executada em uma VM gerenciada pela Anthropic com seu repositório clonado. Esta seção cobre o que está disponível quando uma sessão inicia e como personalizá-lo.60Cada sessão é executada em uma VM gerenciada pela Anthropic com seu repositório clonado. Esta seção cobre o que está disponível quando uma sessão inicia e como personalizá-lo.

61 61 

62<h3 id="what-s-available-in-cloud-sessions">62<h3 id="whats-available-in-cloud-sessions">

63 O que está disponível em sessões em nuvem63 O que está disponível em sessões em nuvem

64</h3>64</h3>

65 65 

66As sessões em nuvem começam a partir de um clone fresco do seu repositório. Qualquer coisa confirmada no repositório está disponível. Qualquer coisa que você tenha instalado ou configurado apenas em sua própria máquina não está.66As sessões em nuvem começam a partir de um clone fresco do seu repositório. Qualquer coisa confirmada no repositório está disponível. Qualquer coisa que você tenha instalado ou configurado apenas em sua própria máquina não está.

67 67 

68| | Disponível em sessões em nuvem | Por quê |68| | Disponível em sessões em nuvem | Por quê |

69| :--------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |69| :------------------------------------------------------------------------------ | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

70| Seu `CLAUDE.md` do repositório | Sim | Parte do clone |70| Seu `CLAUDE.md` do repositório | Sim | Parte do clone |

71| Seus hooks `.claude/settings.json` do repositório | Sim | Parte do clone |71| Seus hooks `.claude/settings.json` do repositório | Sim | Parte do clone |

72| Seus servidores MCP `.mcp.json` do repositório | Sim | Parte do clone |72| Seus servidores MCP `.mcp.json` do repositório | Sim | Parte do clone |


74| Seu `.claude/skills/`, `.claude/agents/`, `.claude/commands/` do repositório | Sim | Parte do clone |74| Seu `.claude/skills/`, `.claude/agents/`, `.claude/commands/` do repositório | Sim | Parte do clone |

75| Plugins declarados em `.claude/settings.json` | Sim | Instalados no início da sessão a partir do [marketplace](/pt/plugin-marketplaces) que você declarou. Requer acesso à rede para alcançar a fonte do marketplace |75| Plugins declarados em `.claude/settings.json` | Sim | Instalados no início da sessão a partir do [marketplace](/pt/plugin-marketplaces) que você declarou. Requer acesso à rede para alcançar a fonte do marketplace |

76| Seu `CLAUDE.md` do usuário `~/.claude/` | Não | Vive em sua máquina, não no repositório |76| Seu `CLAUDE.md` do usuário `~/.claude/` | Não | Vive em sua máquina, não no repositório |

77| Suas `~/.claude/skills/`, `~/.claude/agents/`, `~/.claude/commands/` do usuário | Não | Vivem em sua máquina, não no repositório. Confirme-os no diretório `.claude/` do repositório. Skills que você habilita em claude.ai são carregadas em sessões em nuvem automaticamente |

77| Plugins habilitados apenas em suas configurações de usuário | Não | `enabledPlugins` com escopo de usuário vive em `~/.claude/settings.json`. Declare-os em `.claude/settings.json` do repositório |78| Plugins habilitados apenas em suas configurações de usuário | Não | `enabledPlugins` com escopo de usuário vive em `~/.claude/settings.json`. Declare-os em `.claude/settings.json` do repositório |

78| Servidores MCP que você adicionou com `claude mcp add` | Não | Aqueles escrevem em sua configuração de usuário local, não no repositório. Declare o servidor em [`.mcp.json`](/pt/mcp#project-scope) |79| Servidores MCP que você adicionou com `claude mcp add` | Não | Aqueles escrevem em sua configuração de usuário local, não no repositório. Declare o servidor em [`.mcp.json`](/pt/mcp#project-scope) |

79| Tokens de API estáticos e credenciais | Não | Nenhum armazenamento de segredos dedicado existe ainda. Veja abaixo |80| Tokens de API estáticos e credenciais | Não | Nenhum armazenamento de segredos dedicado existe ainda. Veja abaixo |


228Você não precisa habilitar armazenamento em cache ou gerenciar snapshots você mesmo.229Você não precisa habilitar armazenamento em cache ou gerenciar snapshots você mesmo.

229 230 

230<h3 id="setup-scripts-vs-sessionstart-hooks">231<h3 id="setup-scripts-vs-sessionstart-hooks">

231 Scripts de configuração vs. hooks SessionStart232 Scripts de configuração vs. SessionStart hooks

232</h3>233</h3>

233 234 

234Use um script de configuração para instalar coisas que a nuvem precisa mas seu laptop já tem, como um tempo de execução de linguagem ou ferramenta CLI. Use um [hook SessionStart](/pt/hooks#sessionstart) para configuração de projeto que deve ser executada em todos os lugares, nuvem e local, como `npm install`.235Use um script de configuração para instalar coisas que a nuvem precisa mas seu laptop já tem, como um tempo de execução de linguagem ou ferramenta CLI. Use um [SessionStart hook](/pt/hooks#sessionstart) para configuração de projeto que deve ser executada em todos os lugares, nuvem e local, como `npm install`.

235 236 

236Ambos são executados no início de uma sessão, mas pertencem a lugares diferentes:237Ambos são executados no início de uma sessão, mas pertencem a lugares diferentes:

237 238 

238| | Scripts de configuração | Hooks SessionStart |239| | Scripts de configuração | SessionStart hooks |

239| -------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |240| -------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |

240| Anexado a | O ambiente em nuvem | Seu repositório |241| Anexado a | O ambiente em nuvem | Seu repositório |

241| Configurado em | Interface do usuário do ambiente em nuvem | `.claude/settings.json` em seu repositório |242| Configurado em | Interface do usuário do ambiente em nuvem | `.claude/settings.json` em seu repositório |

242| Executa | Antes de Claude Code ser lançado, quando nenhum [ambiente em cache](#environment-caching) está disponível | Depois de Claude Code ser lançado, em todas as sessões incluindo retomadas |243| Executa | Antes de Claude Code ser lançado, quando nenhum [ambiente em cache](#environment-caching) está disponível | Depois de Claude Code ser lançado, em todas as sessões incluindo retomadas |

243| Escopo | Apenas ambientes em nuvem | Ambientes locais e em nuvem |244| Escopo | Apenas ambientes em nuvem | Ambientes locais e em nuvem |

244 245 

245Os hooks SessionStart também podem ser definidos em seu `~/.claude/settings.json` no nível do usuário localmente, mas as configurações no nível do usuário não são transferidas para sessões em nuvem. Na nuvem, apenas os hooks confirmados no repositório são executados.246Os SessionStart hooks também podem ser definidos em seu `~/.claude/settings.json` no nível do usuário localmente, mas as configurações no nível do usuário não são transferidas para sessões em nuvem. Na nuvem, apenas os hooks confirmados no repositório são executados.

246 247 

247<h3 id="install-dependencies-with-a-sessionstart-hook">248<h3 id="install-dependencies-with-a-sessionstart-hook">

248 Instale dependências com um hook SessionStart249 Instale dependências com um SessionStart hook

249</h3>250</h3>

250 251 

251Para instalar dependências apenas em sessões em nuvem, adicione um hook SessionStart ao `.claude/settings.json` do seu repositório:252Para instalar dependências apenas em sessões em nuvem, adicione um SessionStart hook ao `.claude/settings.json` do seu repositório:

252 253 

253```json theme={null}254```json theme={null}

254{255{


282exit 0283exit 0

283```284```

284 285 

285Os hooks SessionStart têm algumas limitações em sessões em nuvem:286Os SessionStart hooks têm algumas limitações em sessões em nuvem:

286 287 

287* **Sem escopo apenas para nuvem**: os hooks são executados em sessões locais e em nuvem. Para pular execução local, verifique a variável de ambiente `CLAUDE_CODE_REMOTE` conforme mostrado acima.288* **Sem escopo apenas para nuvem**: os hooks são executados em sessões locais e em nuvem. Para pular execução local, verifique a variável de ambiente `CLAUDE_CODE_REMOTE` conforme mostrado acima.

288* **Requer acesso à rede**: os comandos de instalação precisam alcançar registros de pacotes. Se seu ambiente usar acesso à rede **None**, esses hooks falham. A [lista de permissões padrão](#default-allowed-domains) em **Trusted** cobre npm, PyPI, RubyGems e crates.io.289* **Requer acesso à rede**: os comandos de instalação precisam alcançar registros de pacotes. Se seu ambiente usar acesso à rede **None**, esses hooks falham. A [lista de permissões padrão](#default-allowed-domains) em **Trusted** cobre npm, PyPI, RubyGems e crates.io.

289* **Compatibilidade com proxy**: todo o tráfego de saída passa por um [proxy de segurança](#security-proxy). Alguns gerenciadores de pacotes não funcionam corretamente com este proxy. Bun é um exemplo conhecido.290* **Compatibilidade com proxy**: todo o tráfego de saída passa por um [proxy de segurança](#security-proxy). Alguns gerenciadores de pacotes não funcionam corretamente com este proxy. Bun é um exemplo conhecido.

290* **Adiciona latência de inicialização**: os hooks são executados cada vez que uma sessão inicia ou é retomada, diferentemente de scripts de configuração que se beneficiam do [armazenamento em cache de ambiente](#environment-caching). Mantenha os scripts de instalação rápidos verificando se as dependências já estão presentes antes de reinstalar.291* **Adiciona latência de inicialização**: os hooks são executados cada vez que uma sessão inicia ou é retomada, diferentemente de scripts de configuração que se beneficiam do [armazenamento em cache de ambiente](#environment-caching). Mantenha os scripts de instalação rápidos verificando se as dependências já estão presentes antes de reinstalar.

291 292 

292Para persistir variáveis de ambiente para comandos Bash subsequentes, escreva no arquivo em `$CLAUDE_ENV_FILE`. Veja [Hooks SessionStart](/pt/hooks#sessionstart) para detalhes.293Para persistir variáveis de ambiente para comandos Bash subsequentes, escreva no arquivo em `$CLAUDE_ENV_FILE`. Veja [SessionStart hooks](/pt/hooks#sessionstart) para detalhes.

293 294 

294Substituir a imagem base pela sua própria imagem Docker ainda não é suportado. Use um script de configuração para instalar o que você precisa no topo da [imagem fornecida](#installed-tools), ou execute sua imagem como um contêiner ao lado de Claude com `docker compose`.295Substituir a imagem base pela sua própria imagem Docker ainda não é suportado. Use um script de configuração para instalar o que você precisa no topo da [imagem fornecida](#installed-tools), ou execute sua imagem como um contêiner ao lado de Claude com `docker compose`.

295 296 


353* Proteção contra solicitações maliciosas354* Proteção contra solicitações maliciosas

354* Limitação de taxa e prevenção de abuso355* Limitação de taxa e prevenção de abuso

355* Filtragem de conteúdo para segurança aprimorada356* Filtragem de conteúdo para segurança aprimorada

357* Uma trilha de auditoria em nível de DNS de nomes de host solicitados

356 358 

357<h3 id="default-allowed-domains">359<h3 id="default-allowed-domains">

358 Domínios padrão permitidos360 Domínios padrão permitidos


745| `/context` | Sim | Mostra o que está atualmente na janela de contexto |747| `/context` | Sim | Mostra o que está atualmente na janela de contexto |

746| `/clear` | Não | Inicie uma nova sessão a partir da barra lateral |748| `/clear` | Não | Inicie uma nova sessão a partir da barra lateral |

747 749 

748A auto-compactação é executada automaticamente quando a janela de contexto se aproxima da capacidade, o mesmo que no CLI. Para acioná-la mais cedo, defina [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/pt/env-vars) em suas [variáveis de ambiente](#configure-your-environment). Por exemplo, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` compacta em 70% de capacidade em vez do padrão \~95%. Para alterar o tamanho efetivo da janela para cálculos de compactação, use [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/pt/env-vars).750A auto-compactação é executada automaticamente quando a janela de contexto se aproxima da capacidade. Para acioná-la mais cedo, defina [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/pt/env-vars) em suas [variáveis de ambiente](#configure-your-environment). Por exemplo, `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70` compacta em 70% de capacidade em vez de esperar até que a janela esteja quase cheia. Para alterar o tamanho efetivo da janela para cálculos de compactação, use [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/pt/env-vars).

749 751 

750[Subagentes](/pt/sub-agents) funcionam da mesma forma que localmente. Claude pode gerá-los com a ferramenta Task para descarregar pesquisa ou trabalho paralelo em uma janela de contexto separada, mantendo a conversa principal mais leve. Subagentes definidos em seu `.claude/agents/` do repositório são coletados automaticamente. [Equipes de agentes](/pt/agent-teams) estão desabilitadas por padrão mas podem ser habilitadas adicionando `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` às suas [variáveis de ambiente](#configure-your-environment).752[Subagentes](/pt/sub-agents) funcionam da mesma forma que localmente. Claude pode gerá-los com a ferramenta Task para descarregar pesquisa ou trabalho paralelo em uma janela de contexto separada, mantendo a conversa principal mais leve. Subagentes definidos em seu `.claude/agents/` do repositório são coletados automaticamente. [Equipes de agentes](/pt/agent-teams) estão desabilitadas por padrão mas podem ser habilitadas adicionando `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` às suas [variáveis de ambiente](#configure-your-environment).

751 753 


868 870 

869* Execute `/login` localmente para atualizar suas credenciais, depois reconecte871* Execute `/login` localmente para atualizar suas credenciais, depois reconecte

870* Confirme que você está conectado à mesma conta que possui a sessão872* Confirme que você está conectado à mesma conta que possui a sessão

871* Se você ver `Remote Control may not be available for this organization`, seu admin não habilitou sessões remotas para seu plano873* Se você ver `Remote Control may not be available for this organization`, seu admin não habilitou sessões em nuvem para seu plano

872 874 

873<h3 id="environment-expired">875<h3 id="environment-expired">

874 Environment expired876 Environment expired

claude-directory.md +1427 −1

Details

6 6 

7> Onde Claude Code lê CLAUDE.md, settings.json, hooks, skills, commands, subagents, workflows, rules e auto memory. Explore o diretório .claude em seu projeto e ~/.claude em seu diretório home.7> Onde Claude Code lê CLAUDE.md, settings.json, hooks, skills, commands, subagents, workflows, rules e auto memory. Explore o diretório .claude em seu projeto e ~/.claude em seu diretório home.

8 8 

9export const ClaudeExplorer = () => {

10 const A = useMemo(() => ({href, children}) => <a href={href} style={{

11 color: 'var(--ce-accent)',

12 textDecoration: 'none',

13 borderBottom: '1px dotted var(--ce-accent)'

14 }}>{children}</a>, []);

15 const C = useMemo(() => ({children}) => <code style={{

16 fontFamily: 'var(--ce-mono)',

17 fontSize: '0.92em',

18 padding: '1px 4px',

19 borderRadius: '3px',

20 background: 'var(--ce-surface)',

21 border: '0.5px solid var(--ce-border-subtle)'

22 }}>{children}</code>, []);

23 const commandsNote = useMemo(() => <>Commands and skills are now the same mechanism. For new workflows, use <A href="/en/skills">skills/</A> instead: same <C>/name</C> invocation, plus you can bundle supporting files.</>, []);

24 const FILE_TREE = useMemo(() => ({

25 project: {

26 label: 'your-project/',

27 children: [{

28 id: 'claude-md',

29 label: 'CLAUDE.md',

30 type: 'file',

31 icon: 'md',

32 color: '#6A9BCC',

33 badge: 'committed',

34 oneLiner: 'Project instructions Claude reads every session',

35 when: 'Loaded into context at the start of every session',

36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',

37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/en/skills">skill</A> or a path-scoped <A href="/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>],

38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',

39 example: `# Project conventions

40 

41## Commands

42- Build: \`npm run build\`

43- Test: \`npm test\`

44- Lint: \`npm run lint\`

45 

46## Stack

47- TypeScript with strict mode

48- React 19, functional components only

49 

50## Rules

51- Named exports, never default exports

52- Tests live next to source: \`foo.ts\` -> \`foo.test.ts\`

53- All API routes return \`{ data, error }\` shape`,

54 docsLink: '/en/memory'

55 }, {

56 id: 'mcp-json',

57 label: '.mcp.json',

58 type: 'file',

59 icon: 'json',

60 color: '#9B7BC4',

61 badge: 'committed',

62 oneLiner: 'Project-scoped MCP servers, shared with your team',

63 when: <>Servers connect when the session begins. Tool schemas are deferred by default and load on demand via <A href="/en/mcp#scale-with-mcp-tool-search">tool search</A></>,

64 description: <>Configures Model Context Protocol (MCP) servers that give Claude access to external tools: databases, APIs, browsers, and more. This file holds the project-scoped servers your whole team uses. Personal servers you want to keep to yourself go in <C>~/.claude.json</C> instead.</>,

65 tips: [<>Use environment variable references for secrets: <C>{'${GITHUB_TOKEN}'}</C></>, <>Lives at the project root, not inside <C>.claude/</C></>, <>For servers only you need, run <C>claude mcp add --scope user</C>. This writes to <C>~/.claude.json</C> instead of <C>.mcp.json</C></>],

66 exampleIntro: <>This example configures the GitHub MCP server so Claude can read issues and open pull requests. The <C>{'${GITHUB_TOKEN}'}</C> reference is read from your shell environment when Claude Code starts the server, so the token never lands in the file.</>,

67 example: `{

68 "mcpServers": {

69 "github": {

70 "command": "npx",

71 "args": ["-y", "@modelcontextprotocol/server-github"],

72 "env": {

73 "GITHUB_TOKEN": "\${GITHUB_TOKEN}"

74 }

75 }

76 }

77}`,

78 docsLink: '/en/mcp'

79 }, {

80 id: 'worktreeinclude',

81 label: '.worktreeinclude',

82 type: 'file',

83 icon: 'md',

84 color: '#8FA876',

85 badge: 'committed',

86 oneLiner: 'Gitignored files to copy into new worktrees',

87 when: <>Read when Claude creates a git worktree via <C>--worktree</C>, the <C>EnterWorktree</C> tool, or subagent <C>isolation: worktree</C></>,

88 description: <>Lists gitignored files to copy from your main repository into each new worktree. Worktrees are fresh checkouts, so untracked files like <C>.env</C> are missing by default. Patterns here use <C>.gitignore</C> syntax. Only files that match a pattern and are also gitignored get copied, so tracked files are never duplicated.</>,

89 tips: [<>Lives at the project root, not inside <C>.claude/</C></>, <>Git-only: if you configure a <A href="/en/hooks#worktreecreate">WorktreeCreate hook</A> for a different VCS, this file is not read. Copy files inside your hook script instead</>, <>Also applies to parallel sessions in the <A href="/en/desktop#work-in-parallel-with-sessions">desktop app</A></>],

90 exampleIntro: 'This example copies your local environment files and a secrets config into every worktree Claude creates. Comments start with # and blank lines are ignored, same as .gitignore.',

91 example: `# Local environment

92.env

93.env.local

94 

95# API credentials

96config/secrets.json`,

97 docsLink: '/en/worktrees#copy-gitignored-files-into-worktrees'

98 }, {

99 id: 'dot-claude',

100 label: '.claude/',

101 type: 'folder',

102 icon: 'folder',

103 color: 'var(--ce-accent)',

104 oneLiner: 'Project-level configuration, rules, and extensions',

105 description: 'Everything Claude Code reads that is specific to this project. If you use git, commit most files here so your team shares them; a few, like settings.local.json, are automatically gitignored. Each file badge shows which.',

106 children: [{

107 id: 'settings-json',

108 label: 'settings.json',

109 type: 'file',

110 icon: 'json',

111 color: 'var(--ce-text-3)',

112 badge: 'committed',

113 oneLiner: 'Permissions, hooks, and configuration',

114 when: <>Overrides global <C>~/.claude/settings.json</C>. Local settings, CLI flags, and managed settings override this</>,

115 description: 'Settings that Claude Code applies directly. Permissions control which commands and tools Claude can use; hooks run your scripts at specific points in a session. Unlike CLAUDE.md, which Claude reads as guidance, these are enforced whether Claude follows them or not.',

116 contains: [<><A href="/en/permissions">permissions</A>: allow, deny, or prompt before Claude uses specific tools or commands</>, <><A href="/en/hooks">hooks</A>: run your own scripts on events like before a tool call or after a file edit</>, <><A href="/en/statusline">statusLine</A>: customize the line shown at the bottom while Claude works</>, <><A href="/en/settings#available-settings">model</A>: pick a default model for this project</>, <><A href="/en/settings#environment-variables">env</A>: environment variables set in every session</>, <><A href="/en/output-styles">outputStyle</A>: select a custom system-prompt style from output-styles/</>],

117 tips: [<>Bash permission patterns support wildcards: <C>Bash(npm test *)</C> matches any command starting with <C>npm test</C></>, <>Array settings like <C>permissions.allow</C> combine across all scopes; scalar settings like <C>model</C> use the most specific value</>],

118 exampleIntro: <>This example allows <C>npm test</C> and <C>npm run</C> commands without prompting, blocks <C>rm -rf</C>, and runs Prettier on files after Claude edits or writes them.</>,

119 example: `{

120 "permissions": {

121 "allow": [

122 "Bash(npm test *)",

123 "Bash(npm run *)"

124 ],

125 "deny": [

126 "Bash(rm -rf *)"

127 ]

128 },

129 "hooks": {

130 "PostToolUse": [{

131 "matcher": "Edit|Write",

132 "hooks": [{

133 "type": "command",

134 "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"

135 }]

136 }]

137 }

138}`,

139 docsLink: '/en/settings'

140 }, {

141 id: 'settings-local-json',

142 label: 'settings.local.json',

143 type: 'file',

144 icon: 'json',

145 color: 'var(--ce-text-3)',

146 badge: 'gitignored',

147 oneLiner: 'Your personal settings overrides for this project',

148 when: 'Highest of the user-editable settings files; CLI flags and managed settings still take precedence',

149 description: 'Personal settings that take precedence over the project defaults. Same JSON format as settings.json, but not committed. Use this when you need different permissions or defaults than the team config.',

150 tips: [<>Same schema as settings.json. Array settings like <C>permissions.allow</C> combine across scopes; scalar settings like <C>model</C> use the local value</>, <>Claude Code adds this file to <C>~/.config/git/ignore</C> the first time it writes one. If you use a custom <C>core.excludesFile</C>, add the pattern there too. To share the ignore rule with your team, also add it to the project <C>.gitignore</C></>],

151 exampleIntro: 'This example adds Docker permissions on top of whatever the team settings.json allows.',

152 example: `{

153 "permissions": {

154 "allow": [

155 "Bash(docker *)"

156 ]

157 }

158}`,

159 docsLink: '/en/settings'

160 }, {

161 id: 'rules',

162 label: 'rules/',

163 type: 'folder',

164 icon: 'folder',

165 color: '#9B7BC4',

166 oneLiner: 'Topic-scoped instructions, optionally gated by file paths',

167 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when a matching file enters context</>,

168 description: [<>Project instructions split into topic files that can load conditionally based on file paths. A rule without <C>paths:</C> frontmatter loads at session start like CLAUDE.md; a rule with <C>paths:</C> loads only when Claude reads a matching file.</>, <>Like CLAUDE.md, rules are guidance Claude reads, not configuration Claude Code enforces. For guaranteed behavior use <A href="/en/hooks">hooks</A> or <A href="/en/permissions">permissions</A>.</>],

169 tips: [<>Use <C>paths:</C> frontmatter with globs to scope rules to directories or file types</>, <>Subdirectories work: <C>.claude/rules/frontend/react.md</C> is discovered automatically</>, 'When CLAUDE.md approaches 200 lines, start splitting into rules'],

170 docsLink: '/en/memory#organize-rules-with-claude/rules/',

171 children: [{

172 id: 'rule-testing',

173 label: 'testing.md',

174 type: 'file',

175 icon: 'md',

176 color: '#9B7BC4',

177 badge: 'committed',

178 oneLiner: 'Test conventions scoped to test files',

179 when: <>Loaded when Claude reads a file matching the <C>paths:</C> globs below</>,

180 description: <>An example rule that only loads when Claude is working on test files. The <C>paths:</C> globs in the frontmatter define which files trigger it; here, anything ending in .test.ts or .test.tsx. For other files, this rule is not loaded into context.</>,

181 example: `---

182paths:

183 - "**/*.test.ts"

184 - "**/*.test.tsx"

185---

186 

187# Testing Rules

188 

189- Use descriptive test names: "should [expected] when [condition]"

190- Mock external dependencies, not internal modules

191- Clean up side effects in afterEach`

192 }, {

193 id: 'rule-api',

194 label: 'api-design.md',

195 type: 'file',

196 icon: 'md',

197 color: '#9B7BC4',

198 badge: 'committed',

199 oneLiner: 'API conventions scoped to backend code',

200 when: <>Loaded when Claude reads a file matching the <C>paths:</C> glob below</>,

201 description: <>A second example showing a rule scoped to backend code. The <C>paths:</C> glob matches files under src/api/, so these conventions load only when Claude is editing API routes.</>,

202 example: `---

203paths:

204 - "src/api/**/*.ts"

205---

206 

207# API Design Rules

208 

209- All endpoints must validate input with Zod schemas

210- Return shape: { data: T } | { error: string }

211- Rate limit all public endpoints`

212 }]

213 }, {

214 id: 'skills',

215 label: 'skills/',

216 type: 'folder',

217 icon: 'folder',

218 color: '#D4A843',

219 oneLiner: 'Reusable prompts you or Claude invoke by name',

220 when: <>Invoked with <C>/skill-name</C> or when Claude matches the task to a skill</>,

221 description: <>Each skill is a folder with a SKILL.md file plus any supporting files it needs. By default, both you and Claude can invoke a skill. Use frontmatter to control that: <C>disable-model-invocation: true</C> for user-only workflows like <C>/deploy</C>, or <C>user-invocable: false</C> to hide from the <C>/</C> menu while Claude can still invoke it.</>,

222 tips: [<>Skills accept arguments: <C>/deploy staging</C> passes "staging" as <C>$ARGUMENTS</C>. Use <C>$0</C>, <C>$1</C>, and so on for positional access</>, <>The <C>description</C> frontmatter determines when Claude auto-invokes the skill</>, 'Bundle reference docs alongside SKILL.md. Claude knows the skill directory path and can read supporting files when you mention them'],

223 docsLink: '/en/skills',

224 children: [{

225 id: 'skill-review',

226 label: 'security-review/',

227 type: 'folder',

228 icon: 'folder',

229 color: '#D4A843',

230 oneLiner: 'A skill bundling SKILL.md with supporting files',

231 children: [{

232 id: 'skill-review-md',

233 label: 'SKILL.md',

234 type: 'file',

235 icon: 'md',

236 color: '#D4A843',

237 badge: 'committed',

238 oneLiner: 'Entrypoint: trigger, invocability, instructions',

239 when: <>User types <C>/security-review &lt;target&gt;</C>; Claude cannot auto-invoke this skill</>,

240 description: [<>This skill uses <C>disable-model-invocation: true</C> so only you can trigger it; Claude never invokes it on its own.</>, <>The <C>!`...`</C> line runs a shell command and injects its output into the prompt. <C>$ARGUMENTS</C> substitutes whatever you typed after the skill name. Claude sees the skill directory path, so mentioning a bundled file like checklist.md lets Claude read it.</>],

241 example: `---

242description: Reviews code changes for security vulnerabilities, authentication gaps, and injection risks

243disable-model-invocation: true

244argument-hint: <branch-or-path>

245---

246 

247## Diff to review

248 

249!\`git diff $ARGUMENTS\`

250 

251Audit the changes above for:

252 

2531. Injection vulnerabilities (SQL, XSS, command)

2542. Authentication and authorization gaps

2553. Hardcoded secrets or credentials

256 

257Use checklist.md in this skill directory for the full review checklist.

258 

259Report findings with severity ratings and remediation steps.`

260 }, {

261 id: 'skill-checklist',

262 label: 'checklist.md',

263 type: 'file',

264 icon: 'md',

265 color: '#D4A843',

266 badge: 'committed',

267 oneLiner: 'Supporting file bundled with the skill',

268 when: 'Claude reads it on demand while running the skill',

269 description: <>Skills can bundle any supporting files: reference docs, templates, scripts. The skill directory path is prepended to SKILL.md, so Claude can read bundled files by name. For scripts in bash injection commands, use the <C>{'${CLAUDE_SKILL_DIR}'}</C> placeholder.</>,

270 example: `# Security Review Checklist

271 

272## Input Validation

273- [ ] All user input sanitized before DB queries

274- [ ] File upload MIME types validated

275- [ ] Path traversal prevented on file operations

276 

277## Authentication

278- [ ] JWT tokens expire after 24 hours

279- [ ] API keys stored in environment variables

280- [ ] Passwords hashed with bcrypt or argon2`

281 }]

282 }]

283 }, {

284 id: 'commands',

285 label: 'commands/',

286 type: 'folder',

287 icon: 'folder',

288 color: '#788C5D',

289 oneLiner: <>Single-file prompts invoked with <C>/name</C></>,

290 note: commandsNote,

291 when: <>User types <C>/command-name</C></>,

292 description: <>A file at <C>commands/deploy.md</C> creates <C>/deploy</C> the same way a skill at <C>skills/deploy/SKILL.md</C> does, and both can be auto-invoked by Claude. Skills use a directory with SKILL.md, letting you bundle reference docs, templates, or scripts alongside the prompt.</>,

293 tips: [<>Use <C>$ARGUMENTS</C> in the file to accept parameters: <C>/fix-issue 123</C></>, 'If a skill and command share a name, the skill takes precedence', 'New commands should usually be skills instead; commands remain supported'],

294 docsLink: '/en/skills',

295 children: [{

296 id: 'cmd-example',

297 label: 'fix-issue.md',

298 type: 'file',

299 icon: 'md',

300 color: '#788C5D',

301 badge: 'committed',

302 oneLiner: <>Invoked as <C>/fix-issue &lt;number&gt;</C></>,

303 note: commandsNote,

304 description: [<>An example command for fixing a GitHub issue. Type <C>/fix-issue 123</C> and the <C>!`...`</C> line runs <C>gh issue view 123</C> in your shell, injecting the output into the prompt before Claude sees it.</>, <><C>$ARGUMENTS</C> substitutes whatever you typed after the command name. For positional access, use <C>$0</C> <C>$1</C> and so on.</>],

305 example: `---

306argument-hint: <issue-number>

307---

308 

309!\`gh issue view $ARGUMENTS\`

310 

311Investigate and fix the issue above.

312 

3131. Trace the bug to its root cause

3142. Implement the fix

3153. Write or update tests

3164. Summarize what you changed and why`

317 }]

318 }, {

319 id: 'output-styles',

320 label: 'output-styles/',

321 type: 'folder',

322 icon: 'folder',

323 color: '#5AA7A7',

324 oneLiner: 'Project-scoped output styles, if your team shares any',

325 when: 'Applied at session start when selected via the outputStyle setting',

326 description: <>Output styles are usually personal, so most live in <C>~/.claude/output-styles/</C>. Put one here if your team shares a style, like a review mode everyone uses. See <A href="#ce-global-output-styles">the Global tab</A> for the full explanation and example.</>,

327 docsLink: '/en/output-styles',

328 children: []

329 }, {

330 id: 'agents',

331 label: 'agents/',

332 type: 'folder',

333 icon: 'folder',

334 color: '#C46686',

335 oneLiner: 'Specialized subagents with their own context window',

336 when: 'Runs in its own context window when you or Claude invoke it',

337 description: 'Each markdown file defines a subagent with its own system prompt, tool access, and optionally its own model. Subagents run in a fresh context window, keeping the main conversation clean. Useful for parallel work or isolated tasks.',

338 tips: ['Each agent gets a fresh context window, separate from your main session', <>Restrict tool access per agent with the <C>tools:</C> frontmatter field</>, 'Type @ and pick an agent from the autocomplete to delegate directly'],

339 docsLink: '/en/sub-agents',

340 children: [{

341 id: 'agent-reviewer',

342 label: 'code-reviewer.md',

343 type: 'file',

344 icon: 'md',

345 color: '#C46686',

346 badge: 'committed',

347 oneLiner: 'Subagent for isolated code review',

348 when: 'Claude spawns it for review tasks, or you @-mention it from the autocomplete',

349 description: <>An example subagent restricted to read-only tools. The <C>description</C> frontmatter tells Claude when to delegate to it automatically; <C>tools:</C> limits it to Read, Grep, and Glob so it can inspect code but never edit. The body becomes the subagent's system prompt.</>,

350 example: `---

351name: code-reviewer

352description: Reviews code for correctness, security, and maintainability

353tools: Read, Grep, Glob

354---

355 

356You are a senior code reviewer. Review for:

357 

3581. Correctness: logic errors, edge cases, null handling

3592. Security: injection, auth bypass, data exposure

3603. Maintainability: naming, complexity, duplication

361 

362Every finding must include a concrete fix.`

363 }]

364 }, {

365 id: 'workflows',

366 label: 'workflows/',

367 type: 'folder',

368 icon: 'folder',

369 color: '#C46686',

370 oneLiner: 'Dynamic workflow scripts that orchestrate many subagents',

371 when: 'Loaded at startup; each file becomes a /<name> command',

372 description: <>Each <C>.js</C> file is a <A href="/en/workflows">dynamic workflow</A>: a script the runtime executes to spawn and coordinate many subagents. Workflows are written by Claude and saved here from <C>/workflows</C> rather than authored from scratch.</>,

373 tips: [<>Save a run from <C>/workflows</C> with <C>s</C> to create one of these</>, <>A project workflow takes precedence over a personal one in <C>~/.claude/workflows/</C> with the same name</>],

374 docsLink: '/en/workflows'

375 }, {

376 id: 'agent-memory',

377 label: 'agent-memory/',

378 type: 'folder',

379 icon: 'folder',

380 color: '#C46686',

381 badge: 'committed',

382 autogen: true,

383 oneLiner: 'Subagent persistent memory, separate from your main session auto memory',

384 when: 'First 200 lines (capped at 25KB) of MEMORY.md loaded into the subagent system prompt when it runs',

385 description: <>Subagents with <C>memory: project</C> in their frontmatter get a dedicated memory directory here. This is distinct from your <A href="/en/memory#auto-memory">main session auto memory</A> at <C>~/.claude/projects/</C>: each subagent reads and writes its own MEMORY.md, not yours.</>,

386 tips: [<>Only created for subagents that set the <C>memory:</C> frontmatter field</>, <>This directory holds project-scoped subagent memory, meant to be shared with your team. To keep memory out of version control use <C>memory: local</C>, which writes to <C>.claude/agent-memory-local/</C> instead. For cross-project memory use <C>memory: user</C>, which writes to <C>~/.claude/agent-memory/</C></>, <>The main session auto memory is a different feature; see <C>~/.claude/projects/</C> in the Global tab</>],

387 docsLink: '/en/sub-agents#enable-persistent-memory',

388 children: [{

389 id: 'agent-memory-sub',

390 label: '<agent-name>/',

391 type: 'folder',

392 icon: 'folder',

393 color: '#C46686',

394 autogen: true,

395 children: [{

396 id: 'agent-memory-md',

397 label: 'MEMORY.md',

398 type: 'file',

399 icon: 'md',

400 color: '#C46686',

401 badge: 'committed',

402 autogen: true,

403 oneLiner: 'The subagent writes and maintains this file automatically',

404 when: 'Loaded into the subagent system prompt when the subagent starts',

405 description: <>Works the same as your <A href="/en/memory#auto-memory">main auto memory</A>: the subagent creates and updates this file itself. You do not write it. The subagent reads it at the start of each task and writes back what it learns.</>,

406 example: `# code-reviewer memory

407 

408## Patterns seen

409- Project uses custom Result<T, E> type, not exceptions

410- Auth middleware expects Bearer token in Authorization header

411- Tests use factory functions in test/factories/

412 

413## Recurring issues

414- Missing null checks on API responses (src/api/*)

415- Unhandled promise rejections in background jobs`

416 }]

417 }]

418 }]

419 }]

420 },

421 global: {

422 label: '~/',

423 children: [{

424 id: 'claude-json',

425 label: '.claude.json',

426 type: 'file',

427 icon: 'json',

428 color: 'var(--ce-text-3)',

429 badge: 'local',

430 oneLiner: 'App state and UI preferences',

431 when: <>Read at session start for your preferences and MCP servers. Claude Code writes back to it when you change settings in <C>/config</C> or approve trust prompts</>,

432 description: <>Holds state that does not belong in settings.json: theme, OAuth session, per-project trust decisions, your personal MCP servers, and UI toggles. Mostly managed through <C>/config</C> rather than editing directly.</>,

433 tips: [<>IDE toggles like <C>autoConnectIde</C> and <C>externalEditorContext</C> live here, not in settings.json</>, <>The <C>projects</C> key tracks per-project state like trust-dialog acceptance and last-session metrics. Permission rules you approve in-session go to <C>.claude/settings.local.json</C> instead</>, <>MCP servers here are yours only: user scope applies across all projects, local scope is per-project but not committed. Team-shared servers go in <C>.mcp.json</C> at the project root instead</>],

434 example: `{

435 "autoConnectIde": true,

436 "externalEditorContext": true,

437 "mcpServers": {

438 "my-tools": {

439 "command": "npx",

440 "args": ["-y", "@example/mcp-server"]

441 }

442 }

443}`,

444 docsLink: '/en/settings#global-config-settings'

445 }, {

446 id: 'global-dot-claude',

447 label: '.claude/',

448 type: 'folder',

449 icon: 'folder',

450 color: 'var(--ce-accent)',

451 oneLiner: 'Your personal configuration across all projects',

452 description: 'The global counterpart to your project .claude/ directory. Files here apply to every project you work in and are never committed to any repository.',

453 children: [{

454 id: 'global-claude-md',

455 label: 'CLAUDE.md',

456 type: 'file',

457 icon: 'md',

458 color: '#6A9BCC',

459 badge: 'local',

460 oneLiner: 'Personal preferences across every project',

461 when: 'Loaded at the start of every session, in every project',

462 description: 'Your global instruction file. Loaded alongside the project CLAUDE.md at session start, so both are in context together. When instructions conflict, project-level instructions take priority. Keep this to preferences that apply everywhere: response style, commit format, personal conventions.',

463 tips: ['Keep it short since it loads into context for every project, alongside that project\'s own CLAUDE.md', 'Good for response style, commit format, and personal conventions'],

464 example: `# Global preferences

465 

466- Keep explanations concise

467- Use conventional commit format

468- Show the terminal command to verify changes

469- Prefer composition over inheritance`,

470 docsLink: '/en/memory'

471 }, {

472 id: 'global-settings',

473 label: 'settings.json',

474 type: 'file',

475 icon: 'json',

476 color: 'var(--ce-text-3)',

477 badge: 'local',

478 oneLiner: 'Default settings for all projects',

479 when: 'Your defaults. Project and local settings.json override any keys you also set there',

480 description: [<>Same keys as project <C>settings.json</C>: permissions, hooks, model, environment variables, and the rest. Put settings here that you want in every project, like permissions you always allow, a preferred model, or a notification hook that runs regardless of which project you're in.</>, <>Settings follow a precedence order: project <C>settings.json</C> overrides any matching keys you set here. This is different from CLAUDE.md, where global and project files are both loaded into context rather than merged key by key.</>],

481 example: `{

482 "permissions": {

483 "allow": [

484 "Bash(git log *)",

485 "Bash(git diff *)"

486 ]

487 }

488}`,

489 docsLink: '/en/settings'

490 }, {

491 id: 'keybindings',

492 label: 'keybindings.json',

493 type: 'file',

494 icon: 'json',

495 color: 'var(--ce-text-3)',

496 badge: 'local',

497 oneLiner: 'Custom keyboard shortcuts',

498 when: 'Read at session start and hot-reloaded when you edit the file',

499 description: <>Rebind keyboard shortcuts in the interactive CLI. Run <C>/keybindings</C> to create or open this file with a schema reference. Ctrl+C, Ctrl+D, Ctrl+M, and Caps Lock are reserved and cannot be rebound.</>,

500 exampleIntro: <>This example binds <C>Ctrl+E</C> to open your external editor and unbinds <C>Ctrl+U</C> by setting it to <C>null</C>. The <C>context</C> field scopes bindings to a specific part of the CLI, here the main chat input.</>,

501 example: `{

502 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",

503 "$docs": "https://code.claude.com/docs/en/keybindings",

504 "bindings": [

505 {

506 "context": "Chat",

507 "bindings": {

508 "ctrl+e": "chat:externalEditor",

509 "ctrl+u": null

510 }

511 }

512 ]

513}`,

514 docsLink: '/en/keybindings'

515 }, {

516 id: 'themes',

517 label: 'themes/',

518 type: 'folder',

519 icon: 'folder',

520 color: '#5AA7A7',

521 oneLiner: 'Custom color themes',

522 when: <>Read at session start and hot-reloaded when files change. Listed in <C>/theme</C></>,

523 description: <>Each <C>.json</C> file defines a custom color theme: a built-in <C>base</C> preset plus an <C>overrides</C> map of color tokens. Create one interactively with <C>/theme</C> or write the JSON by hand. Selecting a custom theme stores <C>custom:&lt;slug&gt;</C> as your theme preference.</>,

524 example: `{

525 "name": "Dracula",

526 "base": "dark",

527 "overrides": {

528 "claude": "#bd93f9",

529 "error": "#ff5555",

530 "success": "#50fa7b"

531 }

532}`,

533 docsLink: '/en/terminal-config#create-a-custom-theme',

534 children: []

535 }, {

536 id: 'global-projects',

537 label: 'projects/',

538 type: 'folder',

539 icon: 'folder',

540 color: '#E8A45C',

541 autogen: true,

542 oneLiner: "Auto memory: Claude's notes to itself, per project",

543 when: 'MEMORY.md loaded at session start; topic files read on demand',

544 description: 'Auto memory lets Claude accumulate knowledge across sessions without you writing anything. Claude saves notes as it works: build commands, debugging insights, architecture notes. Each project gets its own memory directory keyed by the repository path.',

545 tips: [<>On by default. Toggle with <C>/memory</C> or <C>autoMemoryEnabled</C> in settings</>, 'MEMORY.md is the index loaded each session. The first 200 lines, or 25KB, whichever comes first, are read', 'Topic files like debugging.md are read on demand, not at startup', 'These are plain markdown. Edit or delete them anytime'],

546 docsLink: '/en/memory#auto-memory',

547 children: [{

548 id: 'memory-dir',

549 label: '<project>/memory/',

550 type: 'folder',

551 icon: 'folder',

552 color: '#E8A45C',

553 autogen: true,

554 oneLiner: "Claude's accumulated knowledge for one project",

555 children: [{

556 id: 'memory-md',

557 label: 'MEMORY.md',

558 type: 'file',

559 icon: 'md',

560 color: '#E8A45C',

561 badge: 'local',

562 autogen: true,

563 oneLiner: 'Claude writes and maintains this file automatically',

564 when: 'First 200 lines (capped at 25KB) loaded at session start',

565 description: 'Claude creates and updates this file as it works; you do not write it yourself. It acts as an index that Claude reads at the start of every session, pointing to topic files for detail. You can edit or delete it, but Claude will keep updating it.',

566 example: `# Memory Index

567 

568## Project

569- [build-and-test.md](build-and-test.md): npm run build (~45s), Vitest, dev server on 3001

570- [architecture.md](architecture.md): API client singleton, refresh-token auth

571 

572## Reference

573- [debugging.md](debugging.md): auth token rotation and DB connection troubleshooting`,

574 docsLink: '/en/memory'

575 }, {

576 id: 'memory-topic',

577 label: 'debugging.md',

578 type: 'file',

579 icon: 'md',

580 color: '#E8A45C',

581 badge: 'local',

582 autogen: true,

583 oneLiner: 'Topic notes Claude writes when MEMORY.md gets long',

584 when: 'Claude reads this when a related task comes up',

585 description: 'An example of a topic file Claude creates when MEMORY.md grows too long. Claude picks the filename based on what it splits out: debugging.md, architecture.md, build-commands.md, or similar. You never create these yourself. Claude reads a topic file back only when the current task relates to it.',

586 example: `---

587name: Debugging patterns

588description: Auth token rotation and database connection troubleshooting for this project

589type: reference

590---

591 

592## Auth Token Issues

593- Refresh token rotation: old token invalidated immediately

594- If 401 after refresh: check clock skew between client and server

595 

596## Database Connection Drops

597- Connection pool: max 10 in dev, 50 in prod

598- Always check \`docker compose ps\` first`

599 }]

600 }]

601 }, {

602 id: 'global-rules',

603 label: 'rules/',

604 type: 'folder',

605 icon: 'folder',

606 color: '#9B7BC4',

607 oneLiner: 'User-level rules that apply to every project',

608 when: <>Rules without <C>paths:</C> load at session start. Rules with <C>paths:</C> load when a matching file enters context</>,

609 description: 'Same as project .claude/rules/ but applies everywhere. Use this for conventions you want across all your work, like personal code style or commit message format.',

610 docsLink: '/en/memory#organize-rules-with-claude/rules/',

611 children: []

612 }, {

613 id: 'global-skills',

614 label: 'skills/',

615 type: 'folder',

616 icon: 'folder',

617 color: '#D4A843',

618 oneLiner: 'Personal skills available in every project',

619 when: <>Invoked with <C>/skill-name</C> in any project</>,

620 description: 'Skills you built for yourself that work everywhere. Same structure as project skills: each is a folder with SKILL.md, scoped to your user account instead of a single project.',

621 docsLink: '/en/skills',

622 children: []

623 }, {

624 id: 'global-commands',

625 label: 'commands/',

626 type: 'folder',

627 icon: 'folder',

628 color: '#788C5D',

629 oneLiner: 'Personal single-file commands available in every project',

630 note: commandsNote,

631 when: <>User types <C>/command-name</C> in any project</>,

632 description: 'Same as project commands/ but scoped to your user account. Each markdown file becomes a command available everywhere.',

633 docsLink: '/en/skills',

634 children: []

635 }, {

636 id: 'global-output-styles',

637 label: 'output-styles/',

638 type: 'folder',

639 icon: 'folder',

640 color: '#5AA7A7',

641 oneLiner: 'Custom system-prompt sections that adjust how Claude works',

642 when: 'Applied at session start when selected via the outputStyle setting',

643 description: [<>Each markdown file defines an output style: a section appended to the system prompt that, by default, also drops the built-in software-engineering task instructions. Use this to adapt Claude Code for uses beyond coding, or to add teaching or review modes.</>, <>Select a built-in or custom style with <C>/config</C> or the <C>outputStyle</C> key in settings. Styles here are available in every project; project-level styles with the same name take precedence.</>],

644 tips: ['Built-in styles Explanatory and Learning are included with Claude Code; custom styles go here', <>Set <C>keep-coding-instructions: true</C> in frontmatter to keep the default task instructions alongside your additions</>, 'Changes take effect on the next session since the system prompt is fixed at startup for caching'],

645 docsLink: '/en/output-styles',

646 children: [{

647 id: 'output-style-example',

648 label: 'teaching.md',

649 type: 'file',

650 icon: 'md',

651 color: '#5AA7A7',

652 badge: 'local',

653 oneLiner: 'Example style that adds explanations and leaves small changes for you',

654 when: <>Active when <C>outputStyle</C> in settings is set to <C>teaching</C></>,

655 description: <>This style appends instructions to the system prompt: Claude adds a "Why this approach" note after each task and leaves TODO(human) markers for changes under 10 lines instead of writing them itself. Select it by setting <C>outputStyle</C> to the filename without .md, or to the <C>name</C> field if you set one in frontmatter.</>,

656 example: `---

657description: Explains reasoning and asks you to implement small pieces

658keep-coding-instructions: true

659---

660 

661After completing each task, add a brief "Why this approach" note

662explaining the key design decision.

663 

664When a change is under 10 lines, ask the user to implement it

665themselves by leaving a TODO(human) marker instead of writing it.`

666 }]

667 }, {

668 id: 'global-agents',

669 label: 'agents/',

670 type: 'folder',

671 icon: 'folder',

672 color: '#C46686',

673 oneLiner: 'Personal subagents available in every project',

674 when: 'Claude delegates or you @-mention in any project',

675 description: 'Subagents defined here are available across all your projects. Same format as project agents.',

676 docsLink: '/en/sub-agents',

677 children: []

678 }, {

679 id: 'global-workflows',

680 label: 'workflows/',

681 type: 'folder',

682 icon: 'folder',

683 color: '#C46686',

684 oneLiner: 'Personal dynamic workflows available in every project',

685 when: 'Loaded at startup; each file becomes a /<name> command',

686 description: <>Workflow scripts saved here are available across all your projects. A project workflow with the same name in <C>.claude/workflows/</C> takes precedence.</>,

687 docsLink: '/en/workflows',

688 children: []

689 }, {

690 id: 'global-agent-memory',

691 label: 'agent-memory/',

692 type: 'folder',

693 icon: 'folder',

694 color: '#C46686',

695 autogen: true,

696 oneLiner: <>Persistent memory for subagents with <C>memory: user</C></>,

697 when: 'Loaded into the subagent system prompt when the subagent starts',

698 description: <>Subagents with <C>memory: user</C> in their frontmatter store knowledge here that persists across all projects. For project-scoped subagent memory, see <C>.claude/agent-memory/</C> instead.</>,

699 docsLink: '/en/sub-agents#enable-persistent-memory',

700 children: []

701 }]

702 }]

703 }

704 }), []);

705 const BADGE_STYLES = useMemo(() => ({

706 committed: {

707 bg: 'rgba(85,138,66,0.08)',

708 color: 'var(--ce-badge-committed)',

709 border: 'rgba(85,138,66,0.15)',

710 label: 'committed'

711 },

712 gitignored: {

713 bg: 'rgba(217,119,87,0.06)',

714 color: 'var(--ce-badge-gitignored)',

715 border: 'rgba(217,119,87,0.15)',

716 label: 'gitignored'

717 },

718 local: {

719 bg: 'rgba(115,114,108,0.06)',

720 color: 'var(--ce-badge-local)',

721 border: 'rgba(115,114,108,0.12)',

722 label: 'local only'

723 },

724 autogen: {

725 bg: 'rgba(232,164,92,0.1)',

726 color: 'var(--ce-badge-autogen)',

727 border: 'rgba(232,164,92,0.2)',

728 label: 'Claude writes'

729 }

730 }), []);

731 const allNodes = useMemo(() => {

732 const flatten = (nodes, acc, path, parentId) => {

733 for (const node of nodes) {

734 const nextPath = [...path, node.label];

735 acc[node.id] = {

736 ...node,

737 path: nextPath,

738 parentId

739 };

740 if (node.children) flatten(node.children, acc, nextPath, node.id);

741 }

742 return acc;

743 };

744 const project = flatten(FILE_TREE.project.children, {}, [FILE_TREE.project.label]);

745 const global = flatten(FILE_TREE.global.children, {}, [FILE_TREE.global.label]);

746 for (const id in project) project[id].root = 'project';

747 for (const id in global) global[id].root = 'global';

748 return {

749 ...project,

750 ...global

751 };

752 }, [FILE_TREE]);

753 const allFolderIds = useMemo(() => Object.keys(allNodes).filter(id => allNodes[id].type === 'folder'), [allNodes]);

754 const DEFAULT_EXPANDED = ['dot-claude', 'rules', 'skills', 'skill-review', 'commands', 'agents', 'agent-memory', 'agent-memory-sub', 'global-dot-claude', 'global-output-styles', 'global-projects', 'memory-dir'];

755 const [mounted, setMounted] = useState(false);

756 const [activeRoot, setActiveRoot] = useState('project');

757 const [selectedId, setSelectedId] = useState('claude-md');

758 const [expandedFolders, setExpandedFolders] = useState(() => new Set(DEFAULT_EXPANDED));

759 const [forceMobile, setForceMobile] = useState(false);

760 const [copiedId, setCopiedId] = useState(null);

761 const [isFullscreen, setIsFullscreen] = useState(false);

762 const copyTimeoutRef = useRef(null);

763 const rootRef = useRef(null);

764 useEffect(() => {

765 setMounted(true);

766 const applyHash = scroll => {

767 const hash = window.location.hash.slice(1);

768 if (!hash.startsWith('ce-')) return;

769 const id = hash.slice(3);

770 const node = allNodes[id];

771 if (!node) return;

772 setActiveRoot(node.root);

773 setSelectedId(id);

774 setExpandedFolders(new Set(allFolderIds));

775 if (scroll && rootRef.current) rootRef.current.scrollIntoView({

776 behavior: 'smooth',

777 block: 'start'

778 });

779 };

780 applyHash(false);

781 const onHashChange = () => applyHash(true);

782 const onFsChange = () => setIsFullscreen(!!document.fullscreenElement);

783 window.addEventListener('hashchange', onHashChange);

784 document.addEventListener('fullscreenchange', onFsChange);

785 return () => {

786 if (copyTimeoutRef.current) clearTimeout(copyTimeoutRef.current);

787 window.removeEventListener('hashchange', onHashChange);

788 document.removeEventListener('fullscreenchange', onFsChange);

789 };

790 }, []);

791 useEffect(() => {

792 if (!mounted || !rootRef.current) return;

793 const hash = window.location.hash.slice(1);

794 if (hash.startsWith('ce-') && allNodes[hash.slice(3)]) {

795 rootRef.current.scrollIntoView({

796 behavior: 'smooth',

797 block: 'start'

798 });

799 }

800 }, [mounted]);

801 if (!mounted) return null;

802 const selected = allNodes[selectedId];

803 const tree = FILE_TREE[activeRoot];

804 const isCopied = copiedId === selected.id;

805 const toggleFolder = id => {

806 const next = new Set(expandedFolders);

807 next.has(id) ? next.delete(id) : next.add(id);

808 setExpandedFolders(next);

809 };

810 const switchRoot = root => {

811 if (root === activeRoot) return;

812 setActiveRoot(root);

813 const firstId = FILE_TREE[root].children[0].id;

814 setSelectedId(firstId);

815 try {

816 history.replaceState(null, '', '#ce-' + firstId);

817 } catch (e) {}

818 };

819 const toggleFullscreen = () => {

820 if (!rootRef.current) return;

821 if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {});

822 };

823 const selectNode = n => {

824 setSelectedId(n.id);

825 if (n.type === 'folder' && !expandedFolders.has(n.id)) toggleFolder(n.id);

826 try {

827 history.replaceState(null, '', '#ce-' + n.id);

828 } catch (e) {}

829 };

830 const iconBtn = {

831 width: 28,

832 flexShrink: 0,

833 borderRadius: '6px',

834 border: 'none',

835 cursor: 'pointer',

836 background: 'transparent',

837 color: 'var(--ce-text-4)',

838 display: 'flex',

839 alignItems: 'center',

840 justifyContent: 'center'

841 };

842 const visibleFolderIds = allFolderIds.filter(id => allNodes[id].root === activeRoot);

843 const allExpanded = visibleFolderIds.every(id => expandedFolders.has(id));

844 const toggleAllFolders = () => {

845 const next = new Set(expandedFolders);

846 visibleFolderIds.forEach(id => allExpanded ? next.delete(id) : next.add(id));

847 setExpandedFolders(next);

848 };

849 const onTreeKeyDown = e => {

850 if (!['ArrowDown', 'ArrowUp', 'ArrowRight', 'ArrowLeft'].includes(e.key)) return;

851 const visible = [];

852 const walk = nodes => {

853 for (const n of nodes) {

854 visible.push(n.id);

855 if (n.children && expandedFolders.has(n.id)) walk(n.children);

856 }

857 };

858 walk(tree.children);

859 const i = visible.indexOf(selectedId);

860 if (i === -1) return;

861 e.preventDefault();

862 if (e.key === 'ArrowDown' && i < visible.length - 1) selectNode(allNodes[visible[i + 1]]); else if (e.key === 'ArrowUp' && i > 0) selectNode(allNodes[visible[i - 1]]); else if (e.key === 'ArrowRight' && selected.type === 'folder') {

863 if (!expandedFolders.has(selectedId)) toggleFolder(selectedId); else if (selected.children && selected.children.length) selectNode(allNodes[selected.children[0].id]);

864 } else if (e.key === 'ArrowLeft') {

865 if (selected.type === 'folder' && expandedFolders.has(selectedId)) toggleFolder(selectedId); else if (selected.parentId) selectNode(allNodes[selected.parentId]);

866 }

867 };

868 const copyExample = (id, text) => {

869 const done = () => {

870 setCopiedId(id);

871 if (copyTimeoutRef.current) clearTimeout(copyTimeoutRef.current);

872 copyTimeoutRef.current = setTimeout(() => setCopiedId(null), 2000);

873 };

874 const fallback = () => {

875 const ta = document.createElement('textarea');

876 ta.value = text;

877 ta.style.position = 'fixed';

878 ta.style.opacity = '0';

879 document.body.appendChild(ta);

880 ta.select();

881 try {

882 if (document.execCommand('copy')) done();

883 } catch (e) {}

884 document.body.removeChild(ta);

885 };

886 if (navigator.clipboard) {

887 navigator.clipboard.writeText(text).then(done, fallback);

888 } else {

889 fallback();

890 }

891 };

892 const renderIcon = (icon, color, size) => {

893 const sz = size || 14;

894 if (icon === 'folder') {

895 return <svg width={sz} height={sz} viewBox="0 0 14 14" fill="none">

896 <path d="M1.5 3.5a1 1 0 0 1 1-1h2.6l1 1.2h5.4a1 1 0 0 1 1 1v5.8a1 1 0 0 1-1 1h-9a1 1 0 0 1-1-1V3.5z" fill={color} fillOpacity="0.15" stroke={color} strokeWidth="1" />

897 </svg>;

898 }

899 if (icon === 'json') {

900 return <svg width={sz} height={sz} viewBox="0 0 14 14" fill="none">

901 <rect x="2" y="1.5" width="10" height="11" rx="1.5" fill={color} fillOpacity="0.15" stroke={color} strokeWidth="1" />

902 <text x="7" y="9" fontSize="6" fontFamily="monospace" fill={color} textAnchor="middle" fontWeight="700">{'{}'}</text>

903 </svg>;

904 }

905 return <svg width={sz} height={sz} viewBox="0 0 14 14" fill="none">

906 <rect x="2" y="1.5" width="10" height="11" rx="1.5" fill={color} fillOpacity="0.15" stroke={color} strokeWidth="1" />

907 <line x1="4.5" y1="5" x2="9.5" y2="5" stroke={color} strokeWidth="1" />

908 <line x1="4.5" y1="7" x2="9.5" y2="7" stroke={color} strokeWidth="1" />

909 <line x1="4.5" y1="9" x2="8" y2="9" stroke={color} strokeWidth="1" />

910 </svg>;

911 };

912 const renderNode = (node, depth) => {

913 const isFolder = node.type === 'folder';

914 const isExpanded = expandedFolders.has(node.id);

915 const isSelected = selectedId === node.id;

916 return <div key={node.id}>

917 <button role="treeitem" tabIndex={-1} onClick={() => selectNode(node)} aria-selected={isSelected} aria-expanded={isFolder ? isExpanded : undefined} style={{

918 display: 'flex',

919 alignItems: 'center',

920 gap: '5px',

921 width: '100%',

922 padding: `4px 8px 4px ${8 + depth * 16}px`,

923 background: isSelected ? 'var(--ce-accent-bg)' : 'transparent',

924 borderTop: 'none',

925 borderRight: 'none',

926 borderBottom: 'none',

927 borderLeft: isSelected ? '2px solid var(--ce-accent)' : '2px solid transparent',

928 outline: 'none',

929 cursor: 'pointer',

930 textAlign: 'left',

931 fontFamily: 'var(--ce-mono)',

932 fontSize: '13.5px',

933 color: isSelected ? 'var(--ce-accent)' : 'var(--ce-text-2)',

934 fontWeight: isSelected ? 550 : 400,

935 transition: 'all 0.1s'

936 }}>

937 {isFolder ? <span onClick={e => {

938 e.stopPropagation();

939 toggleFolder(node.id);

940 }} style={{

941 fontSize: '14px',

942 color: 'var(--ce-text-4)',

943 width: '20px',

944 height: '20px',

945 display: 'inline-flex',

946 alignItems: 'center',

947 justifyContent: 'center',

948 cursor: 'pointer',

949 borderRadius: '4px',

950 marginLeft: '-6px',

951 flexShrink: 0

952 }} onMouseEnter={e => {

953 e.currentTarget.style.background = 'var(--ce-arrow-hover)';

954 e.currentTarget.style.color = 'var(--ce-text-2)';

955 }} onMouseLeave={e => {

956 e.currentTarget.style.background = 'transparent';

957 e.currentTarget.style.color = 'var(--ce-text-4)';

958 }}>{isExpanded ? '▾' : '▸'}</span> : <span style={{

959 width: '14px',

960 flexShrink: 0

961 }} />}

962 {renderIcon(node.icon, node.color)}

963 <span style={{

964 flex: 1,

965 overflow: 'hidden',

966 textOverflow: 'ellipsis',

967 whiteSpace: 'nowrap'

968 }}>{node.label}</span>

969 {node.badge && BADGE_STYLES[node.badge] && <span title={BADGE_STYLES[node.badge].label} style={{

970 width: 6,

971 height: 6,

972 borderRadius: '50%',

973 background: BADGE_STYLES[node.badge].color,

974 flexShrink: 0,

975 opacity: 0.7

976 }} />}

977 </button>

978 {isFolder && isExpanded && node.children && <div role="group">{node.children.map(child => renderNode(child, depth + 1))}</div>}

979 </div>;

980 };

981 return <>

982 <style>{`

983 .ce-root {

984 --ce-mono: var(--font-mono, ui-monospace, monospace);

985 --ce-accent: #D97757;

986 --ce-accent-bg: rgba(217,119,87,0.06);

987 --ce-accent-border: rgba(217,119,87,0.12);

988 --ce-bg: #fff;

989 --ce-surface: #FAFAF7;

990 --ce-surface-hover: #F0EEE6;

991 --ce-border: #E8E6DC;

992 --ce-border-subtle: #F0EEE6;

993 --ce-text: #141413;

994 --ce-text-2: #5E5D59;

995 --ce-text-3: #73726C;

996 --ce-text-4: #9C9A92;

997 --ce-text-5: #B8B6AE;

998 --ce-sep: #D1CFC5;

999 --ce-code-header: #F5F4ED;

1000 --ce-code-bg: #1A1918;

1001 --ce-arrow-hover: rgba(0,0,0,0.08);

1002 --ce-badge-committed: #3d6b2e;

1003 --ce-badge-gitignored: #b85c3a;

1004 --ce-badge-local: #5e5d59;

1005 --ce-badge-autogen: #b07520;

1006 --ce-when-text: #4a7fb5;

1007 }

1008 .dark .ce-root {

1009 --ce-bg: #1a1918;

1010 --ce-surface: #232221;

1011 --ce-surface-hover: #2e2d2b;

1012 --ce-border: #3a3936;

1013 --ce-border-subtle: #2e2d2b;

1014 --ce-text: #e8e6dc;

1015 --ce-text-2: #c4c2b8;

1016 --ce-text-3: #9c9a92;

1017 --ce-text-4: #73726c;

1018 --ce-text-5: #5e5d59;

1019 --ce-sep: #4a4946;

1020 --ce-code-header: #2e2d2b;

1021 --ce-code-bg: #0d0d0c;

1022 --ce-arrow-hover: rgba(255,255,255,0.08);

1023 --ce-badge-committed: #6fa85c;

1024 --ce-badge-gitignored: #e08a60;

1025 --ce-badge-local: #9c9a92;

1026 --ce-badge-autogen: #e8a45c;

1027 --ce-when-text: #8bb4e0;

1028 }

1029 .ce-mobile-fallback { display: none; border: 1px solid rgba(0,0,0,0.1); background: rgba(0,0,0,0.03); }

1030 .dark .ce-mobile-fallback { border-color: rgba(255,255,255,0.15); background: rgba(255,255,255,0.04); }

1031 @media (max-width: 700px) {

1032 .ce-root:not(.ce-force) { display: none !important; }

1033 .ce-mobile-fallback { display: block; }

1034 }

1035 `}</style>

1036 {!forceMobile && <div className="ce-mobile-fallback" style={{

1037 padding: '14px 16px',

1038 borderRadius: '8px',

1039 fontSize: '14px'

1040 }}>

1041 The interactive explorer works best on a larger screen. See the <a href="#file-reference" style={{

1042 color: '#D97757'

1043 }}>file reference table</a> below, or <button onClick={() => setForceMobile(true)} style={{

1044 border: 'none',

1045 background: 'none',

1046 padding: 0,

1047 color: '#D97757',

1048 textDecoration: 'underline',

1049 cursor: 'pointer',

1050 font: 'inherit'

1051 }}>show the explorer anyway</button>.

1052 </div>}

1053 <div ref={rootRef} className={forceMobile ? 'ce-root ce-force' : 'ce-root'} style={{

1054 borderRadius: isFullscreen ? 0 : '12px',

1055 border: '1px solid var(--ce-border)',

1056 background: 'var(--ce-bg)',

1057 display: 'flex',

1058 alignItems: 'stretch',

1059 overflow: 'hidden',

1060 fontFamily: 'var(--font-sans, -apple-system, sans-serif)',

1061 ...isFullscreen && ({

1062 height: '100vh'

1063 })

1064 }}>

1065 {}

1066 <div style={{

1067 width: 'min(240px, 35%)',

1068 minWidth: '180px',

1069 flexShrink: 0,

1070 borderRight: '1px solid var(--ce-border-subtle)',

1071 background: 'var(--ce-surface)',

1072 display: 'flex',

1073 flexDirection: 'column'

1074 }}>

1075 <div style={{

1076 padding: '8px 8px 4px',

1077 borderBottom: '1px solid var(--ce-border-subtle)',

1078 display: 'flex',

1079 gap: '4px'

1080 }}>

1081 {['project', 'global'].map(root => <button key={root} onClick={() => switchRoot(root)} style={{

1082 flex: 1,

1083 padding: '6px 0',

1084 borderRadius: '6px',

1085 border: 'none',

1086 cursor: 'pointer',

1087 fontFamily: 'var(--ce-mono)',

1088 fontSize: '11.5px',

1089 background: activeRoot === root ? 'var(--ce-accent-bg)' : 'transparent',

1090 color: activeRoot === root ? 'var(--ce-accent)' : 'var(--ce-text-4)',

1091 fontWeight: activeRoot === root ? 600 : 430

1092 }}>

1093 {root === 'project' ? 'Project' : 'Global (~/)'}

1094 </button>)}

1095 <button onClick={toggleAllFolders} title={allExpanded ? 'Collapse all' : 'Expand all'} style={{

1096 ...iconBtn,

1097 fontSize: 11

1098 }}>

1099 {allExpanded ? '⊟' : '⊞'}

1100 </button>

1101 <button onClick={toggleFullscreen} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'} style={{

1102 ...iconBtn,

1103 fontSize: 13

1104 }}>

1105 {isFullscreen ? '⤡' : '⛶'}

1106 </button>

1107 </div>

1108 <div role="tree" aria-label="Configuration files" tabIndex={0} onKeyDown={onTreeKeyDown} style={{

1109 padding: '6px 0',

1110 overflowY: 'auto',

1111 flex: 1,

1112 outline: 'none'

1113 }}>

1114 {tree.children.map(node => renderNode(node, 0))}

1115 </div>

1116 </div>

1117 

1118 {}

1119 <div style={{

1120 flex: 1,

1121 minWidth: 0,

1122 padding: '20px 24px',

1123 minHeight: '400px',

1124 overflowY: 'auto'

1125 }}>

1126 <span aria-live="polite" style={{

1127 position: 'absolute',

1128 width: 1,

1129 height: 1,

1130 overflow: 'hidden',

1131 clip: 'rect(0 0 0 0)'

1132 }}>{selected.label} selected</span>

1133 {}

1134 <div style={{

1135 fontFamily: 'var(--ce-mono)',

1136 fontSize: '11px',

1137 color: 'var(--ce-text-4)',

1138 marginBottom: '10px',

1139 cursor: 'default'

1140 }}>

1141 {selected.path.map((seg, i) => <span key={i}>

1142 <span style={{

1143 color: i === selected.path.length - 1 ? 'var(--ce-accent)' : 'var(--ce-text-4)'

1144 }}>{seg.replace(/\/$/, '')}</span>

1145 {i < selected.path.length - 1 && <span style={{

1146 color: 'var(--ce-sep)'

1147 }}> / </span>}

1148 </span>)}

1149 </div>

1150 

1151 {}

1152 <div style={{

1153 display: 'flex',

1154 alignItems: 'flex-start',

1155 gap: '10px',

1156 marginBottom: '10px'

1157 }}>

1158 <span style={{

1159 flexShrink: 0,

1160 display: 'flex'

1161 }}>{renderIcon(selected.icon, selected.color, 24)}</span>

1162 <div style={{

1163 flex: 1,

1164 minWidth: 0

1165 }}>

1166 <div style={{

1167 fontSize: '22px',

1168 fontWeight: 600,

1169 color: 'var(--ce-text)',

1170 letterSpacing: '-0.3px',

1171 lineHeight: '26px'

1172 }}>{selected.label}</div>

1173 {selected.oneLiner && <div style={{

1174 fontSize: '15px',

1175 color: 'var(--ce-text-3)',

1176 marginTop: '3px'

1177 }}>{selected.oneLiner}</div>}

1178 </div>

1179 <div style={{

1180 display: 'flex',

1181 gap: '4px',

1182 flexShrink: 0

1183 }}>

1184 {[selected.autogen && 'autogen', selected.badge].filter(Boolean).map(k => {

1185 const s = BADGE_STYLES[k];

1186 if (!s) return null;

1187 return <span key={k} style={{

1188 fontFamily: 'var(--ce-mono)',

1189 fontSize: '10px',

1190 fontWeight: 600,

1191 textTransform: 'uppercase',

1192 letterSpacing: '0.3px',

1193 padding: '2px 6px',

1194 borderRadius: '4px',

1195 background: s.bg,

1196 color: s.color,

1197 border: `0.5px solid ${s.border}`

1198 }}>{s.label}</span>;

1199 })}

1200 </div>

1201 </div>

1202 

1203 {}

1204 {selected.note && <div style={{

1205 padding: '10px 12px',

1206 borderRadius: '8px',

1207 marginBottom: '14px',

1208 background: 'rgba(217,119,87,0.06)',

1209 border: '1px solid rgba(217,119,87,0.2)',

1210 borderLeft: '3px solid var(--ce-accent)',

1211 fontSize: '15px',

1212 color: 'var(--ce-text-2)',

1213 lineHeight: 1.6

1214 }}>

1215 {selected.note}

1216 </div>}

1217 

1218 {}

1219 {selected.when && <div style={{

1220 padding: '8px 12px',

1221 borderRadius: '6px',

1222 background: 'rgba(106,155,204,0.06)',

1223 border: '0.5px solid rgba(106,155,204,0.12)',

1224 fontSize: '15px',

1225 color: 'var(--ce-when-text)',

1226 marginBottom: '16px'

1227 }}>

1228 <div style={{

1229 fontSize: '10px',

1230 fontWeight: 700,

1231 textTransform: 'uppercase',

1232 letterSpacing: '0.4px',

1233 opacity: 0.65,

1234 marginBottom: '3px'

1235 }}>When it loads</div>

1236 <div style={{

1237 fontWeight: 500

1238 }}>{selected.when}</div>

1239 </div>}

1240 

1241 {}

1242 {selected.description && <div style={{

1243 fontSize: '16px',

1244 color: 'var(--ce-text-2)',

1245 lineHeight: 1.65,

1246 marginBottom: '16px'

1247 }}>

1248 {Array.isArray(selected.description) ? selected.description.map((para, i) => <div key={i} style={{

1249 marginBottom: i < selected.description.length - 1 ? '12px' : 0

1250 }}>{para}</div>) : selected.description}

1251 </div>}

1252 

1253 {}

1254 {selected.contains && selected.contains.length > 0 && <div style={{

1255 marginBottom: '16px'

1256 }}>

1257 <div style={{

1258 fontSize: '11px',

1259 fontWeight: 700,

1260 color: 'var(--ce-text-4)',

1261 textTransform: 'uppercase',

1262 letterSpacing: '0.4px',

1263 marginBottom: '8px'

1264 }}>Common keys</div>

1265 {selected.contains.map((item, i) => <div key={i} style={{

1266 display: 'flex',

1267 gap: '7px',

1268 fontSize: '15px',

1269 color: 'var(--ce-text-2)',

1270 lineHeight: 1.5,

1271 marginBottom: '5px'

1272 }}>

1273 <span style={{

1274 fontSize: '7px',

1275 color: 'var(--ce-text-4)',

1276 marginTop: '6px'

1277 }}>●</span>

1278 <span>{item}</span>

1279 </div>)}

1280 </div>}

1281 

1282 {}

1283 {selected.tips && selected.tips.length > 0 && <div style={{

1284 padding: '12px 14px',

1285 borderRadius: '8px',

1286 background: 'var(--ce-surface)',

1287 border: '1px solid var(--ce-border-subtle)',

1288 marginBottom: '16px'

1289 }}>

1290 <div style={{

1291 fontSize: '11px',

1292 fontWeight: 700,

1293 color: 'var(--ce-accent)',

1294 textTransform: 'uppercase',

1295 letterSpacing: '0.4px',

1296 marginBottom: '6px'

1297 }}>Tips</div>

1298 {selected.tips.map((tip, i) => <div key={i} style={{

1299 display: 'flex',

1300 gap: '7px',

1301 fontSize: '14.5px',

1302 color: 'var(--ce-text-2)',

1303 marginBottom: i < selected.tips.length - 1 ? '5px' : 0

1304 }}>

1305 <span style={{

1306 fontSize: '7px',

1307 color: 'var(--ce-accent)',

1308 marginTop: '6px'

1309 }}>●</span>

1310 <span>{tip}</span>

1311 </div>)}

1312 </div>}

1313 

1314 {}

1315 {selected.example && <div style={{

1316 marginBottom: '16px'

1317 }}>

1318 {selected.exampleIntro && <div style={{

1319 fontSize: '15px',

1320 color: 'var(--ce-text-2)',

1321 lineHeight: 1.6,

1322 marginBottom: '10px'

1323 }}>

1324 {selected.exampleIntro}

1325 </div>}

1326 <div style={{

1327 display: 'flex',

1328 justifyContent: 'space-between',

1329 alignItems: 'center',

1330 padding: '6px 10px',

1331 background: 'var(--ce-code-header)',

1332 border: '1px solid var(--ce-border)',

1333 borderRadius: '8px 8px 0 0'

1334 }}>

1335 <span style={{

1336 fontFamily: 'var(--ce-mono)',

1337 fontSize: '11px',

1338 fontWeight: 600,

1339 color: 'var(--ce-text-3)'

1340 }}>{selected.label}</span>

1341 <button onClick={() => copyExample(selected.id, selected.example)} style={{

1342 padding: '3px 8px',

1343 borderRadius: '4px',

1344 fontSize: '11px',

1345 fontWeight: 600,

1346 cursor: 'pointer',

1347 transition: 'all 0.15s',

1348 background: isCopied ? 'rgba(85,138,66,0.08)' : 'var(--ce-code-header)',

1349 border: isCopied ? '0.5px solid rgba(85,138,66,0.2)' : '0.5px solid var(--ce-border)',

1350 color: isCopied ? '#558A42' : 'var(--ce-text-3)'

1351 }}>

1352 {isCopied ? '✓ Copied' : 'Copy'}

1353 </button>

1354 </div>

1355 <pre style={{

1356 margin: 0,

1357 padding: '12px 14px',

1358 background: 'var(--ce-code-bg)',

1359 color: '#E8E6DC',

1360 fontFamily: 'var(--ce-mono)',

1361 fontSize: '13px',

1362 lineHeight: 1.65,

1363 borderRadius: '0 0 8px 8px',

1364 overflowX: 'auto',

1365 whiteSpace: 'pre'

1366 }}>{selected.example}</pre>

1367 </div>}

1368 

1369 {}

1370 {selected.docsLink && <a href={selected.docsLink} style={{

1371 display: 'inline-flex',

1372 padding: '5px 12px',

1373 borderRadius: '6px',

1374 background: 'var(--ce-accent-bg)',

1375 border: '1px solid var(--ce-accent-border)',

1376 color: 'var(--ce-accent)',

1377 fontSize: '12px',

1378 fontWeight: 600,

1379 textDecoration: 'none'

1380 }}>Full docs →</a>}

1381 

1382 {}

1383 {selected.children && selected.children.length > 0 && <div style={{

1384 marginTop: '20px'

1385 }}>

1386 <div style={{

1387 fontSize: '11px',

1388 fontWeight: 700,

1389 color: 'var(--ce-text-4)',

1390 textTransform: 'uppercase',

1391 letterSpacing: '0.4px',

1392 marginBottom: '8px'

1393 }}>Contents</div>

1394 <div style={{

1395 display: 'flex',

1396 flexDirection: 'column',

1397 gap: '4px'

1398 }}>

1399 {selected.children.map(child => <button key={child.id} onClick={() => selectNode(child)} style={{

1400 display: 'flex',

1401 alignItems: 'center',

1402 gap: '8px',

1403 padding: '6px 8px',

1404 width: '100%',

1405 background: 'var(--ce-surface)',

1406 borderRadius: '6px',

1407 border: 'none',

1408 cursor: 'pointer',

1409 textAlign: 'left',

1410 transition: 'background 0.1s'

1411 }} onMouseEnter={e => e.currentTarget.style.background = 'var(--ce-surface-hover)'} onMouseLeave={e => e.currentTarget.style.background = 'var(--ce-surface)'}>

1412 {renderIcon(child.icon, child.color, 13)}

1413 <span style={{

1414 fontFamily: 'var(--ce-mono)',

1415 fontSize: '12px',

1416 color: 'var(--ce-text-2)'

1417 }}>{child.label}</span>

1418 {child.oneLiner && <span style={{

1419 fontSize: '11px',

1420 color: 'var(--ce-text-4)',

1421 overflow: 'hidden',

1422 textOverflow: 'ellipsis',

1423 whiteSpace: 'nowrap'

1424 }}>{child.oneLiner}</span>}

1425 </button>)}

1426 </div>

1427 </div>}

1428 </div>

1429 </div>

1430 </>;

1431};

1432 

9Claude Code lê instruções, configurações, skills, subagents e memória do seu diretório de projeto e de `~/.claude` em seu diretório home. Confirme arquivos de projeto no git para compartilhá-los com sua equipe; arquivos em `~/.claude` são configuração pessoal que se aplica em todos os seus projetos.1433Claude Code lê instruções, configurações, skills, subagents e memória do seu diretório de projeto e de `~/.claude` em seu diretório home. Confirme arquivos de projeto no git para compartilhá-los com sua equipe; arquivos em `~/.claude` são configuração pessoal que se aplica em todos os seus projetos.

10 1434 

11No Windows, `~/.claude` é resolvido para `%USERPROFILE%\.claude`. Se você definir [`CLAUDE_CONFIG_DIR`](/pt/env-vars), cada caminho `~/.claude` nesta página fica sob esse diretório.1435No Windows, `~/.claude` é resolvido para `%USERPROFILE%\.claude`. Se você definir [`CLAUDE_CONFIG_DIR`](/pt/env-vars), cada caminho `~/.claude` nesta página fica sob esse diretório.


18 1442 

19Clique em arquivos na árvore para ver o que cada um faz, quando carrega e um exemplo.1443Clique em arquivos na árvore para ver o que cada um faz, quando carrega e um exemplo.

20 1444 

21<h2 id="what-s-not-shown">1445<ClaudeExplorer />

1446 

1447<h2 id="what’s-not-shown">

22 O que não é mostrado1448 O que não é mostrado

23</h2>1449</h2>

24 1450 

Details

6 6 

7> Configure Claude Code para usar a API Claude operada pela Anthropic com autenticação AWS, controle de acesso IAM e faturamento do AWS Marketplace.7> Configure Claude Code para usar a API Claude operada pela Anthropic com autenticação AWS, controle de acesso IAM e faturamento do AWS Marketplace.

8 8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

79export const Experiment = ({flag, treatment, children}) => {

80 const VID_KEY = 'exp_vid';

81 const CONSENT_COUNTRIES = new Set(['AT', 'BE', 'BG', 'HR', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'GR', 'HU', 'IE', 'IT', 'LV', 'LT', 'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'RE', 'GP', 'MQ', 'GF', 'YT', 'BL', 'MF', 'PM', 'WF', 'PF', 'NC', 'AW', 'CW', 'SX', 'FO', 'GL', 'AX', 'GB', 'UK', 'AI', 'BM', 'IO', 'VG', 'KY', 'FK', 'GI', 'MS', 'PN', 'SH', 'TC', 'GG', 'JE', 'IM', 'CA', 'BR', 'IN']);

82 const fnv1a = s => {

83 let h = 0x811c9dc5;

84 for (let i = 0; i < s.length; i++) {

85 h ^= s.charCodeAt(i);

86 h += (h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24);

87 }

88 return h >>> 0;

89 };

90 const bucket = (seed, vid) => fnv1a(fnv1a(seed + vid) + '') % 10000 < 5000 ? 'control' : 'treatment';

91 const [decision] = useState(() => {

92 const params = new URLSearchParams(location.search);

93 const preBucketed = document.documentElement.dataset['gb_' + flag.replace(/-/g, '_')];

94 const force = params.get('gb-force');

95 if (force) {

96 for (const p of force.split(',')) {

97 const [k, v] = p.split(':');

98 if (k === flag) return {

99 variant: v || 'treatment',

100 track: false

101 };

102 }

103 }

104 if (navigator.globalPrivacyControl) {

105 return {

106 variant: 'control',

107 track: false

108 };

109 }

110 const prefsMatch = document.cookie.match(/(?:^|; )anthropic-consent-preferences=([^;]+)/);

111 if (prefsMatch) {

112 try {

113 if (JSON.parse(decodeURIComponent(prefsMatch[1])).analytics !== true) {

114 return {

115 variant: 'control',

116 track: false

117 };

118 }

119 } catch {

120 return {

121 variant: 'control',

122 track: false

123 };

124 }

125 } else {

126 const country = params.get('country')?.toUpperCase() || (document.cookie.match(/(?:^|; )cf_geo=([A-Z]{2})/) || [])[1];

127 if (!country || CONSENT_COUNTRIES.has(country)) {

128 return {

129 variant: 'control',

130 track: false

131 };

132 }

133 }

134 let vid;

135 try {

136 const ajsMatch = document.cookie.match(/(?:^|; )ajs_anonymous_id=([^;]+)/);

137 if (ajsMatch) {

138 vid = decodeURIComponent(ajsMatch[1]).replace(/^"|"$/g, '');

139 } else {

140 vid = localStorage.getItem(VID_KEY);

141 if (!vid) {

142 vid = crypto.randomUUID();

143 }

144 document.cookie = `ajs_anonymous_id=${vid}; domain=.claude.com; path=/; Secure; SameSite=Lax; max-age=31536000`;

145 }

146 try {

147 localStorage.setItem(VID_KEY, vid);

148 } catch {}

149 } catch {

150 return {

151 variant: 'control',

152 track: false

153 };

154 }

155 const variant = preBucketed === '1' ? 'treatment' : preBucketed === '0' ? 'control' : bucket(flag, vid);

156 return {

157 variant,

158 track: true,

159 vid

160 };

161 });

162 useEffect(() => {

163 if (!decision.track) return;

164 fetch('https://api.anthropic.com/api/event_logging/v2/batch', {

165 method: 'POST',

166 headers: {

167 'Content-Type': 'application/json',

168 'x-service-name': 'claude_code_docs'

169 },

170 body: JSON.stringify({

171 events: [{

172 event_type: 'GrowthbookExperimentEvent',

173 event_data: {

174 device_id: decision.vid,

175 anonymous_id: decision.vid,

176 timestamp: new Date().toISOString(),

177 experiment_id: flag,

178 variation_id: decision.variant === 'treatment' ? 1 : 0,

179 environment: 'production'

180 }

181 }]

182 }),

183 keepalive: true

184 }).catch(() => {});

185 }, []);

186 return decision.variant === 'treatment' ? treatment : children;

187};

188 

189<Experiment flag="docs-contact-sales-cta" treatment={<ContactSalesCard surface="claude_platform_on_aws" />} />

190 

9Claude Platform on AWS é a API Claude operada pela Anthropic com autenticação AWS, controle de acesso IAM e faturamento do AWS Marketplace. As solicitações chegam diretamente à API da Anthropic, portanto você obtém os mesmos modelos e recursos que a [Claude API](https://platform.claude.com/docs) no mesmo cronograma de lançamento. Você se autentica com credenciais AWS ou uma chave de API do workspace, e paga através do AWS Marketplace.191Claude Platform on AWS é a API Claude operada pela Anthropic com autenticação AWS, controle de acesso IAM e faturamento do AWS Marketplace. As solicitações chegam diretamente à API da Anthropic, portanto você obtém os mesmos modelos e recursos que a [Claude API](https://platform.claude.com/docs) no mesmo cronograma de lançamento. Você se autentica com credenciais AWS ou uma chave de API do workspace, e paga através do AWS Marketplace.

10 192 

11Use este guia para apontar Claude Code para um workspace que você já provisionou através do Claude Platform on AWS. Para a assinatura AWS e configuração do workspace que vem antes disso, consulte a [documentação do Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws).193Use este guia para apontar Claude Code para um workspace que você já provisionou através do Claude Platform on AWS. Para a assinatura AWS e configuração do workspace que vem antes disso, consulte a [documentação do Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws).


92 3. Fixe versões de modelo274 3. Fixe versões de modelo

93</h3>275</h3>

94 276 

95Claude Platform on AWS usa os mesmos IDs de modelo que a API Claude direta. Os aliases padrão `opus`, `sonnet` e `haiku` resolvem para as versões mais recentes disponíveis em seu workspace.277Claude Platform on AWS usa os mesmos IDs de modelo que a API Claude direta. Os aliases padrão `fable`, `opus`, `sonnet` e `haiku` resolvem para os padrões integrados do Claude Code para Claude Platform on AWS, que podem ficar atrás da versão mais recente. Sem `ANTHROPIC_DEFAULT_OPUS_MODEL`, o alias `opus` resolve para Opus 4.7.

96 278 

97Se você implantar Claude Code para uma equipe, fixe os IDs de modelo explicitamente para que um novo lançamento não mova todos de uma vez:279Se você implantar Claude Code para uma equipe, fixe os IDs de modelo explicitamente para que um novo lançamento não mova todos de uma vez:

98 280 

99```bash theme={null}281```bash theme={null}

282export ANTHROPIC_DEFAULT_FABLE_MODEL=claude-fable-5

100export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7283export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7

101export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6284export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6

102export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5285export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5


157 `403 Forbidden` ou `AccessDenied` em cada solicitação340 `403 Forbidden` ou `AccessDenied` em cada solicitação

158</h3>341</h3>

159 342 

160O principal IAM que Claude Code resolveu provavelmente não tem permissão para invocar o serviço Anthropic em seu workspace. Verifique a função anexada ao seu perfil AWS ou ao executor que iniciou Claude Code, e verifique se ela tem as ações `aws-external-anthropic` documentadas na [referência de ação IAM](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions).343O principal IAM que Claude Code resolveu provavelmente não tem permissão para invocar o serviço Anthropic em seu workspace. Verifique a função anexada ao seu perfil AWS ou ao executor que iniciou Claude Code, e verifique se ela tem as ações `aws-external-anthropic` documentadas na [referência de ação IAM](https://platform.claude.com/docs/pt/api/claude-platform-on-aws-iam-actions).

161 344 

162Se você definir `ANTHROPIC_AWS_API_KEY`, a chave tem precedência sobre SigV4 e uma chave obsoleta produz o mesmo erro. Regenere a chave no Console AWS em **Claude Platform on AWS → API keys** ou desdefina a variável para voltar às suas credenciais AWS.345Se você definir `ANTHROPIC_AWS_API_KEY`, a chave tem precedência sobre SigV4 e uma chave obsoleta produz o mesmo erro. Regenere a chave no Console AWS em **Claude Platform on AWS → API keys** ou desdefina a variável para voltar às suas credenciais AWS.

163 346 


179 362 

180A assinatura do Claude Platform on AWS, configuração de workspace e IAM que vem antes de configurar Claude Code é coberta na documentação da plataforma:363A assinatura do Claude Platform on AWS, configuração de workspace e IAM que vem antes de configurar Claude Code é coberta na documentação da plataforma:

181 364 

182* [Visão geral do Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws): assinatura, configuração de workspace e referência de produto365* [Visão geral do Claude Platform on AWS](https://platform.claude.com/docs/pt/build-with-claude/claude-platform-on-aws): assinatura, configuração de workspace e referência de produto

183* [Referência de ação IAM](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions): permissões e políticas gerenciadas366* [Referência de ação IAM](https://platform.claude.com/docs/pt/api/claude-platform-on-aws-iam-actions): permissões e políticas gerenciadas

cli-reference.md +11 −9

Details

13Você pode iniciar sessões, canalizar conteúdo, retomar conversas e gerenciar atualizações com estes comandos:13Você pode iniciar sessões, canalizar conteúdo, retomar conversas e gerenciar atualizações com estes comandos:

14 14 

15| Comando | Descrição | Exemplo |15| Comando | Descrição | Exemplo |

16| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------- |16| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |

17| `claude` | Iniciar sessão interativa | `claude` |17| `claude` | Iniciar sessão interativa | `claude` |

18| `claude "query"` | Iniciar sessão interativa com prompt inicial | `claude "explain this project"` |18| `claude "query"` | Iniciar sessão interativa com prompt inicial | `claude "explain this project"` |

19| `claude -p "query"` | Consultar via SDK e sair | `claude -p "explain this function"` |19| `claude -p "query"` | Consultar via SDK e sair | `claude -p "explain this function"` |


26| `claude auth login` | Faça login em sua conta Anthropic. Use `--email` para preencher previamente seu endereço de email, `--sso` para forçar autenticação SSO e `--console` para fazer login com Anthropic Console para faturamento de uso de API em vez de uma assinatura Claude | `claude auth login --console` |26| `claude auth login` | Faça login em sua conta Anthropic. Use `--email` para preencher previamente seu endereço de email, `--sso` para forçar autenticação SSO e `--console` para fazer login com Anthropic Console para faturamento de uso de API em vez de uma assinatura Claude | `claude auth login --console` |

27| `claude auth logout` | Fazer logout de sua conta Anthropic | `claude auth logout` |27| `claude auth logout` | Fazer logout de sua conta Anthropic | `claude auth logout` |

28| `claude auth status` | Mostrar status de autenticação como JSON. Use `--text` para saída legível por humanos. Sai com código 0 se conectado, 1 se não | `claude auth status` |28| `claude auth status` | Mostrar status de autenticação como JSON. Use `--text` para saída legível por humanos. Sai com código 0 se conectado, 1 se não | `claude auth status` |

29| `claude agents` | Abrir [visualização de agente](/pt/agent-view) para monitorar e despachar sessões de fundo paralelas. Use `--cwd <path>` para mostrar apenas sessões iniciadas nesse diretório, ou `--json` para imprimir sessões ativas como um array JSON para scripts. Passe `--permission-mode`, `--model`, `--effort` ou `--agent` para definir [padrões para sessões despachadas](/pt/agent-view#permission-mode-model-and-effort). Aceita `--settings`, `--add-dir`, `--plugin-dir` e `--mcp-config` como o comando `claude` de nível superior. Abrir visualização de agente requer um terminal interativo | `claude agents --json` |29| `claude agents` | Abrir [visualização de agente](/pt/agent-view) para monitorar e despachar sessões de fundo paralelas. Use `--cwd <path>` para mostrar apenas sessões iniciadas nesse diretório, ou `--json` para imprimir sessões ativas como um array JSON para scripts (`--json --all` também inclui sessões de fundo concluídas). Passe `--permission-mode`, `--model`, `--effort` ou `--agent` para definir [padrões para sessões despachadas](/pt/agent-view#permission-mode-model-and-effort). Aceita `--settings`, `--add-dir`, `--plugin-dir` e `--mcp-config` como o comando `claude` de nível superior. Abrir visualização de agente requer um terminal interativo | `claude agents --json` |

30| `claude attach <id>` | Anexar a uma [sessão de fundo](/pt/agent-view#manage-sessions-from-the-shell) neste terminal | `claude attach 7c5dcf5d` |30| `claude attach <id>` | Anexar a uma [sessão de fundo](/pt/agent-view#manage-sessions-from-the-shell) neste terminal | `claude attach 7c5dcf5d` |

31| `claude auto-mode defaults` | Imprimir as regras do classificador [auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode) integradas como JSON. Use `claude auto-mode config` para ver sua configuração efetiva com as configurações aplicadas | `claude auto-mode defaults > rules.json` |31| `claude auto-mode defaults` | Imprimir as regras do classificador [auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode) integradas como JSON. Use `claude auto-mode config` para ver sua configuração efetiva com as configurações aplicadas | `claude auto-mode defaults > rules.json` |

32| `claude daemon status` | Imprimir o estado do [supervisor](/pt/agent-view#the-supervisor-process) de sessão de fundo, versão, diretório de socket e contagem de workers para diagnósticos. Sai com 1 se o supervisor não estiver em execução | `claude daemon status` |32| `claude daemon status` | Imprimir o estado do [supervisor](/pt/agent-view#the-supervisor-process) de sessão de fundo, versão, diretório de socket e contagem de workers para diagnósticos. Sai com 1 se o supervisor não estiver em execução | `claude daemon status` |


51Personalize o comportamento do Claude Code com estes sinalizadores de linha de comando. `claude --help` não lista todos os sinalizadores, portanto a ausência de um sinalizador em `--help` não significa que ele não está disponível.51Personalize o comportamento do Claude Code com estes sinalizadores de linha de comando. `claude --help` não lista todos os sinalizadores, portanto a ausência de um sinalizador em `--help` não significa que ele não está disponível.

52 52 

53| Sinalizador | Descrição | Exemplo |53| Sinalizador | Descrição | Exemplo |

54| :---------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |54| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |

55| `--add-dir` | Adicionar diretórios de trabalho adicionais para Claude ler e editar arquivos. Concede acesso a arquivos; a maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) desses diretórios. Valida se cada caminho existe como um diretório. Para persistir esses diretórios entre sessões, defina [`permissions.additionalDirectories`](/pt/settings#permission-settings) nas configurações | `claude --add-dir ../apps ../lib` |55| `--add-dir` | Adicionar diretórios de trabalho adicionais para Claude ler e editar arquivos. Concede acesso a arquivos; a maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) desses diretórios. Valida se cada caminho existe como um diretório. Para persistir esses diretórios entre sessões, defina [`permissions.additionalDirectories`](/pt/settings#permission-settings) nas configurações | `claude --add-dir ../apps ../lib` |

56| `--advisor <model>` | {/* min-version: 2.1.98 */}Ativar a [ferramenta advisor](/pt/advisor) do lado do servidor para esta sessão com um alias de modelo: `opus`, `sonnet` ou `fable` ({/* min-version: 2.1.170 */}v2.1.170+), ou um ID de modelo completo. Tem precedência sobre a configuração `advisorModel` para a sessão. Requer Claude Code v2.1.98 ou posterior | `claude --advisor opus` |

56| `--agent` | Especificar um agente para a sessão atual (substitui a configuração `agent`) | `claude --agent my-custom-agent` |57| `--agent` | Especificar um agente para a sessão atual (substitui a configuração `agent`) | `claude --agent my-custom-agent` |

57| `--agents` | Definir subagents personalizados dinamicamente via JSON. Usa os mesmos nomes de campo que o [frontmatter](/pt/sub-agents#supported-frontmatter-fields) de subagent, mais um campo `prompt` para as instruções do agente | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |58| `--agents` | Definir subagents personalizados dinamicamente via JSON. Usa os mesmos nomes de campo que o [frontmatter](/pt/sub-agents#supported-frontmatter-fields) de subagent, mais um campo `prompt` para as instruções do agente | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

58| `--allow-dangerously-skip-permissions` | Adicionar `bypassPermissions` ao ciclo de modo `Shift+Tab` sem iniciar nele. Permite começar em um modo diferente como `plan` e mudar para `bypassPermissions` depois. Veja [modos de permissão](/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |59| `--allow-dangerously-skip-permissions` | Adicionar `bypassPermissions` ao ciclo de modo `Shift+Tab` sem iniciar nele. Permite começar em um modo diferente como `plan` e mudar para `bypassPermissions` depois. Veja [modos de permissão](/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

59| `--allowedTools` | Ferramentas que executam sem solicitar permissão. Veja [sintaxe de regra de permissão](/pt/settings#permission-rule-syntax) para correspondência de padrões. Para restringir quais ferramentas estão disponíveis, use `--tools` em vez disso | `"Bash(git log *)" "Bash(git diff *)" "Read"` |60| `--allowedTools`, `--allowed-tools` | Ferramentas que executam sem solicitar permissão. Veja [sintaxe de regra de permissão](/pt/settings#permission-rule-syntax) para correspondência de padrões. Para restringir quais ferramentas estão disponíveis, use `--tools` em vez disso | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

60| `--append-system-prompt` | Anexar texto personalizado ao final do prompt do sistema padrão | `claude --append-system-prompt "Always use TypeScript"` |61| `--append-system-prompt` | Anexar texto personalizado ao final do prompt do sistema padrão | `claude --append-system-prompt "Always use TypeScript"` |

61| `--append-system-prompt-file` | Carregar texto de prompt do sistema adicional de um arquivo e anexar ao prompt padrão | `claude --append-system-prompt-file ./extra-rules.txt` |62| `--append-system-prompt-file` | Carregar texto de prompt do sistema adicional de um arquivo e anexar ao prompt padrão | `claude --append-system-prompt-file ./extra-rules.txt` |

62| `--bare` | Modo mínimo: pular auto-descoberta de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md para que chamadas com script iniciem mais rapidamente. Claude tem acesso a ferramentas Bash, leitura de arquivo e edição de arquivo. Define [`CLAUDE_CODE_SIMPLE`](/pt/env-vars). Veja [modo bare](/pt/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |63| `--bare` | Modo mínimo: pular auto-descoberta de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md para que chamadas com script iniciem mais rapidamente. Claude tem acesso a ferramentas Bash, leitura de arquivo e edição de arquivo. Define [`CLAUDE_CODE_SIMPLE`](/pt/env-vars). Veja [modo bare](/pt/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |


70| `--debug` | Ativar modo de depuração com filtragem de categoria opcional (por exemplo, `"api,hooks"` ou `"!statsig,!file"`) | `claude --debug "api,mcp"` |71| `--debug` | Ativar modo de depuração com filtragem de categoria opcional (por exemplo, `"api,hooks"` ou `"!statsig,!file"`) | `claude --debug "api,mcp"` |

71| `--debug-file <path>` | Escrever logs de depuração em um caminho de arquivo específico. Ativa implicitamente o modo de depuração. Tem precedência sobre `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |72| `--debug-file <path>` | Escrever logs de depuração em um caminho de arquivo específico. Ativa implicitamente o modo de depuração. Tem precedência sobre `CLAUDE_CODE_DEBUG_LOGS_DIR` | `claude --debug-file /tmp/claude-debug.log` |

72| `--disable-slash-commands` | Desativar todas as skills e comandos para esta sessão | `claude --disable-slash-commands` |73| `--disable-slash-commands` | Desativar todas as skills e comandos para esta sessão | `claude --disable-slash-commands` |

73| `--disallowedTools` | Regras de negação. Um nome de ferramenta simples remove essa ferramenta do contexto do modelo. Uma regra com escopo como `Bash(rm *)` deixa a ferramenta disponível e nega apenas chamadas correspondentes | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |74| `--disallowedTools`, `--disallowed-tools` | Regras de negação. Um nome de ferramenta simples remove as ferramentas correspondentes do contexto do modelo: `"Edit"` remove Edit, `"*"` remove todas as ferramentas e `"mcp__*"` remove todas as ferramentas MCP. Uma regra com escopo como `Bash(rm *)` deixa a ferramenta disponível e nega apenas chamadas correspondentes | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

74| `--effort` | Definir o [nível de esforço](/pt/model-config#adjust-effort-level) para a sessão atual. Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo. Substitui a configuração [`effortLevel`](/pt/settings#available-settings) para esta sessão e não persiste | `claude --effort high` |75| `--effort` | Definir o [nível de esforço](/pt/model-config#adjust-effort-level) para a sessão atual. Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo. Substitui a configuração [`effortLevel`](/pt/settings#available-settings) para esta sessão e não persiste | `claude --effort high` |

75| `--enable-auto-mode` | {/* max-version: 2.1.110 */}Removido em v2.1.111. Auto mode agora está no ciclo `Shift+Tab` por padrão; use `--permission-mode auto` para iniciar nele | `claude --permission-mode auto` |76| `--enable-auto-mode` | {/* max-version: 2.1.110 */}Removido em v2.1.111. Auto mode agora está no ciclo `Shift+Tab` por padrão; use `--permission-mode auto` para iniciar nele | `claude --permission-mode auto` |

76| `--exclude-dynamic-system-prompt-sections` | Mover seções por máquina do prompt do sistema (diretório de trabalho, informações de ambiente, caminhos de memória, status do git) para a primeira mensagem do usuário. Melhora a reutilização de prompt-cache em diferentes usuários e máquinas executando a mesma tarefa. Aplica-se apenas com o prompt do sistema padrão; ignorado quando `--system-prompt` ou `--system-prompt-file` está definido. Use com `-p` para cargas de trabalho com script e multi-usuário | `claude -p --exclude-dynamic-system-prompt-sections "query"` |77| `--exclude-dynamic-system-prompt-sections` | Mover seções por máquina do prompt do sistema (diretório de trabalho, informações de ambiente, caminhos de memória, status do git) para a primeira mensagem do usuário. Melhora a reutilização de prompt-cache em diferentes usuários e máquinas executando a mesma tarefa. Aplica-se apenas com o prompt do sistema padrão; ignorado quando `--system-prompt` ou `--system-prompt-file` está definido. Use com `-p` para cargas de trabalho com script e multi-usuário | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

77| `--exec` | Executar um comando shell como um trabalho de fundo com suporte PTY em vez de iniciar uma sessão Claude. Use com `--bg` para iniciar a partir do shell | `claude --bg --exec 'pytest -x'` |78| `--exec` | Executar um comando shell como um trabalho de fundo com suporte PTY em vez de iniciar uma sessão Claude. Use com `--bg` para iniciar a partir do shell | `claude --bg --exec 'pytest -x'` |

78| `--fallback-model` | Ativar fallback automático para um modelo especificado quando o modelo padrão está sobrecarregado ou não está disponível, por exemplo um modelo descontinuado. Entra em vigor em modo print (`-p`) e em [sessões de fundo](/pt/agent-view), que são executadas de forma não interativa; ignorado em uma sessão interativa | `claude -p --fallback-model sonnet "query"` |79| `--fallback-model` | Ativar fallback automático para o(s) modelo(s) especificado(s) quando o modelo primário está sobrecarregado ou não está disponível, por exemplo um modelo descontinuado. Aceita uma lista separada por vírgula tentada em ordem. Veja [Cadeias de modelo fallback](/pt/model-config#fallback-model-chains). Para persistir uma cadeia entre sessões, use a configuração [`fallbackModel`](/pt/settings#available-settings), que este sinalizador substitui | `claude --fallback-model sonnet,haiku` |

79| `--fork-session` | Ao retomar, criar um novo ID de sessão em vez de reutilizar o original (use com `--resume` ou `--continue`) | `claude --resume abc123 --fork-session` |80| `--fork-session` | Ao retomar, criar um novo ID de sessão em vez de reutilizar o original (use com `--resume` ou `--continue`) | `claude --resume abc123 --fork-session` |

80| `--from-pr` | Retomar sessões vinculadas a um pull request específico. Aceita um número de PR, uma URL de PR do GitHub ou GitHub Enterprise, uma URL de merge request do GitLab ou uma URL de pull request do Bitbucket. As sessões são vinculadas automaticamente quando Claude cria o pull request | `claude --from-pr 123` |81| `--from-pr` | Retomar sessões vinculadas a um pull request específico. Aceita um número de PR, uma URL de PR do GitHub ou GitHub Enterprise, uma URL de merge request do GitLab ou uma URL de pull request do Bitbucket. As sessões são vinculadas automaticamente quando Claude cria o pull request | `claude --from-pr 123` |

81| `--ide` | Conectar automaticamente ao IDE na inicialização se exatamente um IDE válido estiver disponível | `claude --ide` |82| `--ide` | Conectar automaticamente ao IDE na inicialização se exatamente um IDE válido estiver disponível | `claude --ide` |


89| `--max-budget-usd` | Valor máximo em dólares a gastar em chamadas de API antes de parar (apenas modo print) | `claude -p --max-budget-usd 5.00 "query"` |90| `--max-budget-usd` | Valor máximo em dólares a gastar em chamadas de API antes de parar (apenas modo print) | `claude -p --max-budget-usd 5.00 "query"` |

90| `--max-turns` | Limitar o número de turnos de agente (apenas modo print). Sai com um erro quando o limite é atingido. Sem limite por padrão | `claude -p --max-turns 3 "query"` |91| `--max-turns` | Limitar o número de turnos de agente (apenas modo print). Sai com um erro quando o limite é atingido. Sem limite por padrão | `claude -p --max-turns 3 "query"` |

91| `--mcp-config` | Carregar servidores MCP de arquivos JSON ou strings (separados por espaço) | `claude --mcp-config ./mcp.json` |92| `--mcp-config` | Carregar servidores MCP de arquivos JSON ou strings (separados por espaço) | `claude --mcp-config ./mcp.json` |

92| `--model` | Define o modelo para a sessão atual com um alias para o modelo mais recente (`sonnet` ou `opus`) ou o nome completo de um modelo. Substitui a configuração [`model`](/pt/settings#available-settings) e [`ANTHROPIC_MODEL`](/pt/model-config#environment-variables) | `claude --model claude-sonnet-4-6` |93| `--model` | Define o modelo para a sessão atual com um alias para o modelo mais recente (`sonnet`, `opus`, `haiku` ou `fable`) ou o nome completo de um modelo. Substitui a configuração [`model`](/pt/settings#available-settings) e [`ANTHROPIC_MODEL`](/pt/model-config#environment-variables) | `claude --model claude-sonnet-4-6` |

93| `--name`, `-n` | Definir um nome de exibição para a sessão, mostrado em `/resume` e no título do terminal. Você pode retomar uma sessão nomeada com `claude --resume <name>`. <br /><br />[`/rename`](/pt/commands) altera o nome durante a sessão e também o mostra na barra de prompt | `claude -n "my-feature-work"` |94| `--name`, `-n` | Definir um nome de exibição para a sessão, mostrado em `/resume` e no título do terminal. Você pode retomar uma sessão nomeada com `claude --resume <name>`. <br /><br />[`/rename`](/pt/commands) altera o nome durante a sessão e também o mostra na barra de prompt | `claude -n "my-feature-work"` |

94| `--no-chrome` | Desativar [integração do navegador Chrome](/pt/chrome) para esta sessão | `claude --no-chrome` |95| `--no-chrome` | Desativar [integração do navegador Chrome](/pt/chrome) para esta sessão | `claude --no-chrome` |

95| `--no-session-persistence` | Desativar persistência de sessão para que as sessões não sejam salvas em disco e não possam ser retomadas. Apenas modo print. A variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars) faz o mesmo em qualquer modo | `claude -p --no-session-persistence "query"` |96| `--no-session-persistence` | Desativar persistência de sessão para que as sessões não sejam salvas em disco e não possam ser retomadas. Apenas modo print. A variável de ambiente [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars) faz o mesmo em qualquer modo | `claude -p --no-session-persistence "query"` |


104| `--remote-control`, `--rc` | Iniciar uma sessão interativa com [Remote Control](/pt/remote-control#start-a-remote-control-session) ativado para que você também possa controlá-la a partir de claude.ai ou do aplicativo Claude. Opcionalmente, passe um nome para a sessão | `claude --remote-control "My Project"` |105| `--remote-control`, `--rc` | Iniciar uma sessão interativa com [Remote Control](/pt/remote-control#start-a-remote-control-session) ativado para que você também possa controlá-la a partir de claude.ai ou do aplicativo Claude. Opcionalmente, passe um nome para a sessão | `claude --remote-control "My Project"` |

105| `--remote-control-session-name-prefix <prefix>` | Prefixo para nomes de sessão [Remote Control](/pt/remote-control) gerados automaticamente quando nenhum nome explícito está definido. Padrão é o nome do host da sua máquina, produzindo nomes como `myhost-graceful-unicorn`. Defina `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` para o mesmo efeito | `claude remote-control --remote-control-session-name-prefix dev-box` |106| `--remote-control-session-name-prefix <prefix>` | Prefixo para nomes de sessão [Remote Control](/pt/remote-control) gerados automaticamente quando nenhum nome explícito está definido. Padrão é o nome do host da sua máquina, produzindo nomes como `myhost-graceful-unicorn`. Defina `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` para o mesmo efeito | `claude remote-control --remote-control-session-name-prefix dev-box` |

106| `--replay-user-messages` | Re-emitir mensagens do usuário de stdin de volta em stdout para confirmação. Requer `--input-format stream-json` e `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |107| `--replay-user-messages` | Re-emitir mensagens do usuário de stdin de volta em stdout para confirmação. Requer `--input-format stream-json` e `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

107| `--resume`, `-r` | Retomar uma sessão específica por ID ou nome, ou mostrar um seletor interativo para escolher uma sessão. Inclui sessões que adicionaram este diretório com `/add-dir`. A partir de v2.1.144, [sessões de fundo](/pt/agent-view) aparecem no seletor marcadas com `bg` | `claude --resume auth-refactor` |108| `--resume`, `-r` | Retomar uma sessão específica por ID ou nome, ou mostrar um seletor interativo para escolher uma sessão. O seletor e a busca por nome incluem sessões que adicionaram este diretório com `/add-dir`; passar um ID de sessão pesquisa apenas o diretório do projeto atual e seus git worktrees. A partir de v2.1.144, [sessões de fundo](/pt/agent-view) aparecem no seletor marcadas com `bg` | `claude --resume auth-refactor` |

109| `--safe-mode` | {/* min-version: 2.1.169 */}Iniciar com todas as personalizações desativadas para solucionar problemas de uma configuração quebrada: CLAUDE.md, skills, plugins, hooks, servidores MCP, comandos e agentes personalizados, estilos de saída, workflows, temas personalizados, atalhos de teclado personalizados, comandos de linha de status e sugestão de arquivo, servidores LSP e memória automática não carregam. Autenticação, seleção de modelo, ferramentas integradas e permissões funcionam normalmente, o que difere de [`--bare`](/pt/headless#start-faster-with-bare-mode). A política de configurações gerenciadas ainda se aplica, incluindo hooks configurados por política, linha de status e comandos de sugestão de arquivo; plugins gerenciados, skills gerenciadas, CLAUDE.md gerenciado e servidores MCP configurados por política não. Útil para verificar se uma personalização é o que dispara [fallback automático de Fable 5](/pt/model-config#automatic-model-fallback). Define [`CLAUDE_CODE_SAFE_MODE`](/pt/env-vars) | `claude --safe-mode` |

108| `--session-id` | Usar um ID de sessão específico para a conversa (deve ser um UUID válido) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |110| `--session-id` | Usar um ID de sessão específico para a conversa (deve ser um UUID válido) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |

109| `--setting-sources` | Lista separada por vírgula de fontes de configuração a carregar (`user`, `project`, `local`) | `claude --setting-sources user,project` |111| `--setting-sources` | Lista separada por vírgula de fontes de configuração a carregar (`user`, `project`, `local`) | `claude --setting-sources user,project` |

110| `--settings` | Caminho para um arquivo JSON de configurações ou uma string JSON para carregar configurações adicionais. Os valores que você define aqui substituem as mesmas chaves em seus arquivos `settings.json` para esta sessão. As chaves que você omite mantêm seus valores baseados em arquivo. Veja [precedência de configurações](/pt/settings#settings-precedence) | `claude --settings ./settings.json` |112| `--settings` | Caminho para um arquivo JSON de configurações ou uma string JSON para carregar configurações adicionais. Os valores que você define aqui substituem as mesmas chaves em seus arquivos `settings.json` para esta sessão. As chaves que você omite mantêm seus valores baseados em arquivo. Veja [precedência de configurações](/pt/settings#settings-precedence) | `claude --settings ./settings.json` |


114| `--teleport` | Retomar uma [sessão web](/pt/claude-code-on-the-web) em seu terminal local | `claude --teleport` |116| `--teleport` | Retomar uma [sessão web](/pt/claude-code-on-the-web) em seu terminal local | `claude --teleport` |

115| `--teammate-mode` | Definir como [equipe de agentes](/pt/agent-teams) colegas de equipe são exibidos: `auto` (padrão), `in-process` ou `tmux`. Substitui a configuração [`teammateMode`](/pt/settings#available-settings) para esta sessão. Veja [Escolher um modo de exibição](/pt/agent-teams#choose-a-display-mode) | `claude --teammate-mode in-process` |117| `--teammate-mode` | Definir como [equipe de agentes](/pt/agent-teams) colegas de equipe são exibidos: `auto` (padrão), `in-process` ou `tmux`. Substitui a configuração [`teammateMode`](/pt/settings#available-settings) para esta sessão. Veja [Escolher um modo de exibição](/pt/agent-teams#choose-a-display-mode) | `claude --teammate-mode in-process` |

116| `--tmux` | Criar uma sessão tmux para o worktree. Requer `--worktree`. Usa painéis nativos do iTerm2 quando disponível; passe `--tmux=classic` para tmux tradicional | `claude -w feature-auth --tmux` |118| `--tmux` | Criar uma sessão tmux para o worktree. Requer `--worktree`. Usa painéis nativos do iTerm2 quando disponível; passe `--tmux=classic` para tmux tradicional | `claude -w feature-auth --tmux` |

117| `--tools` | Restringir quais ferramentas integradas Claude pode usar. Use `""` para desativar todas, `"default"` para todas, ou nomes de ferramentas como `"Bash,Edit,Read"` | `claude --tools "Bash,Edit,Read"` |119| `--tools` | Restringir quais ferramentas integradas Claude pode usar. Use `""` para desativar todas, `"default"` para todas, ou nomes de ferramentas como `"Bash,Edit,Read"`. Ferramentas MCP não são afetadas; para negar essas também, use `--disallowedTools "mcp__*"` ou passe `--strict-mcp-config` sem `--mcp-config` para que nenhum servidor MCP carregue | `claude --tools "Bash,Edit,Read"` |

118| `--verbose` | Ativar logging detalhado, mostra saída completa turno por turno. Substitui a configuração [`viewMode`](/pt/settings#available-settings) para esta sessão | `claude --verbose` |120| `--verbose` | Ativar logging detalhado, mostra saída completa turno por turno. Substitui a configuração [`viewMode`](/pt/settings#available-settings) para esta sessão | `claude --verbose` |

119| `--version`, `-v` | Exibir o número da versão | `claude -v` |121| `--version`, `-v` | Exibir o número da versão | `claude -v` |

120| `--worktree`, `-w` | Iniciar Claude em um [git worktree](/pt/worktrees) isolado em `<repo>/.claude/worktrees/<name>`. Se nenhum nome for fornecido, um será gerado automaticamente. Passe `#<number>` ou uma URL de pull request do GitHub para buscar esse PR de `origin` e ramificar o worktree a partir dele | `claude -w feature-auth` |122| `--worktree`, `-w` | Iniciar Claude em um [git worktree](/pt/worktrees) isolado em `<repo>/.claude/worktrees/<name>`. Se nenhum nome for fornecido, um será gerado automaticamente. Passe `#<number>` ou uma URL de pull request do GitHub para buscar esse PR de `origin` e ramificar o worktree a partir dele | `claude -w feature-auth` |

code-review.md +5 −5

Details

293 293 

294O botão **Re-run** na aba Checks do GitHub não retrigger Code Review. Use o comando de comentário ou um novo push em vez disso.294O botão **Re-run** na aba Checks do GitHub não retrigger Code Review. Use o comando de comentário ou um novo push em vez disso.

295 295 

296<h3 id="review-didn-t-run-and-the-pr-shows-a-spend-cap-message">296<h3 id="review-didnt-run-and-the-pr-shows-a-spend-cap-message">

297 Revisão não foi executada e o PR mostra uma mensagem de limite de gasto297 Revisão não foi executada e o PR mostra uma mensagem de limite de gasto

298</h3>298</h3>

299 299 

300Quando o limite de gasto mensal de sua organização é atingido, Code Review publica um único comentário no PR explicando que a revisão foi ignorada. As revisões retomam automaticamente no início do próximo período de faturamento, ou imediatamente quando um administrador aumenta o limite em [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage).300Quando o limite de gasto mensal de sua organização é atingido, Code Review publica um único comentário no PR explicando que a revisão foi ignorada. As revisões retomam automaticamente no início do próximo período de faturamento, ou imediatamente quando um administrador aumenta o limite em [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage).

301 301 

302<h3 id="find-issues-that-aren-t-showing-as-inline-comments">302<h3 id="find-issues-that-arent-showing-as-inline-comments">

303 Encontrar problemas que não aparecem como comentários inline303 Encontrar problemas que não aparecem como comentários inline

304</h3>304</h3>

305 305 


313 Revisar um diff localmente313 Revisar um diff localmente

314</h2>314</h2>

315 315 

316O comando [`/code-review`](/pt/commands) revisa um diff em seu terminal sem instalar o GitHub App. Execute-o em qualquer sessão Claude Code: ele relata bugs de correção e {/* min-version: 2.1.151 */}reutilização, simplificação e limpezas de eficiência no diff atual. Passe `--comment` para publicar descobertas como comentários PR inline, ou `--fix` para aplicar as descobertas à sua árvore de trabalho após a revisão.316O comando [`/code-review`](/pt/commands) revisa um diff em seu terminal sem instalar o GitHub App. Execute-o em qualquer sessão Claude Code: ele relata bugs de correção e {/* min-version: 2.1.151 */}reutilização, simplificação e limpezas de eficiência. Por padrão, a revisão local cobre os commits de sua branch à frente de sua upstream mais quaisquer alterações não confirmadas na árvore de trabalho. Passe `--comment` para publicar descobertas como comentários PR inline, ou `--fix` para aplicar as descobertas à sua árvore de trabalho após a revisão.

317 317 

318Níveis de [esforço](/pt/model-config#adjust-effort-level) mais baixos retornam menos descobertas com maior confiança, enquanto `high` até `max` fornecem cobertura mais ampla e podem incluir descobertas incertas. Sem um argumento de esforço, a revisão usa o esforço atual da sessão. Passe um caminho ou referência de PR para revisar um alvo específico em vez do diff atual.318Níveis de [esforço](/pt/model-config#adjust-effort-level) mais baixos retornam menos descobertas com maior confiança, enquanto `high` até `max` fornecem cobertura mais ampla e podem incluir descobertas incertas. Sem um argumento de esforço, a revisão usa o esforço atual da sessão. Para revisar algo diferente do diff padrão, passe um alvo: um caminho de arquivo, um número de PR, um nome de branch ou um intervalo de ref como `main...my-feature`. A forma de intervalo de ref revisa o diff confirmado que um pull request de `my-feature` para `main` conteria, independentemente de como a upstream da branch está configurada.

319 319 

320`/code-review ultra --fix` executa a [ultrareview](/pt/ultrareview) mais profunda na nuvem, então aplica suas descobertas à sua árvore de trabalho quando chegam de volta em sua sessão.320`/code-review ultra --fix` executa a [ultrareview](/pt/ultrareview) mais profunda na nuvem, então aplica suas descobertas à sua árvore de trabalho quando chegam de volta em sua sessão. Ultrareview usa seu próprio escopo: sua branch atual contra a branch padrão do repositório, mais quaisquer alterações não confirmadas e preparadas na árvore de trabalho.

321 321 

322O comando foi nomeado `/simplify` antes da v2.1.147, quando aplicava correções por padrão. {/* min-version: 2.1.154 */}A partir da v2.1.154, `/simplify` executa uma revisão separada apenas de limpeza que aplica correções sem procurar por bugs. Se você criou scripts com `/simplify` para busca de bugs, mude para `/code-review --fix`, que permanece inalterado.322O comando foi nomeado `/simplify` antes da v2.1.147, quando aplicava correções por padrão. {/* min-version: 2.1.154 */}A partir da v2.1.154, `/simplify` executa uma revisão separada apenas de limpeza que aplica correções sem procurar por bugs. Se você criou scripts com `/simplify` para busca de bugs, mude para `/code-review --fix`, que permanece inalterado.

323 323 

commands.md +24 −13

Details

12 12 

13Um comando é reconhecido apenas no início da sua mensagem. O texto que segue o nome do comando é passado para ele como argumentos.13Um comando é reconhecido apenas no início da sua mensagem. O texto que segue o nome do comando é passado para ele como argumentos.

14 14 

15## Comandos em um fluxo de trabalho típico15<h2 id="commands-across-a-typical-workflow">

16 Comandos em um fluxo de trabalho típico

17</h2>

16 18 

17A maioria dos comandos é útil em um ponto específico de uma sessão, desde a configuração de um projeto até o envio de uma alteração.19A maioria dos comandos é útil em um ponto específico de uma sessão, desde a configuração de um projeto até o envio de uma alteração.

18 20 


28 30 

29**Quando algo está errado.** `/rewind` reverte o código e a conversa para um checkpoint, ou resume parte da conversa. `/doctor` e `/debug` diagnosticam problemas de instalação e tempo de execução, e `/feedback` relata um bug com contexto de sessão anexado.31**Quando algo está errado.** `/rewind` reverte o código e a conversa para um checkpoint, ou resume parte da conversa. `/doctor` e `/debug` diagnosticam problemas de instalação e tempo de execução, e `/feedback` relata um bug com contexto de sessão anexado.

30 32 

31## Todos os comandos33<h2 id="all-commands">

34 Todos os comandos

35</h2>

32 36 

33A tabela abaixo lista todos os comandos incluídos no Claude Code. A maioria são comandos integrados cujo comportamento é codificado na CLI. Dois tipos de entradas são marcados:37A tabela abaixo lista todos os comandos incluídos no Claude Code. A maioria são comandos integrados cujo comportamento é codificado na CLI. Dois tipos de entradas são marcados:

34 38 


46| Comando | Propósito |50| Comando | Propósito |

47| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |51| :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

48| `/add-dir <path>` | Adicionar um diretório de trabalho para acesso a arquivos durante a sessão atual. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) do diretório adicionado. Você pode retomar a sessão posteriormente do diretório adicionado com `--continue` ou `--resume` |52| `/add-dir <path>` | Adicionar um diretório de trabalho para acesso a arquivos durante a sessão atual. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) do diretório adicionado. Você pode retomar a sessão posteriormente do diretório adicionado com `--continue` ou `--resume` |

53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}Ativar ou desativar a [ferramenta advisor](/pt/advisor), que consulta um segundo modelo para orientação em momentos-chave durante uma tarefa. Aceita `opus`, `sonnet`, `fable` ({/* min-version: 2.1.170 */}v2.1.170+), ou um ID de modelo completo. Sem um argumento, abre um seletor. Requer Claude Code v2.1.98 ou posterior |

49| `/agents` | Gerenciar configurações de [agent](/pt/sub-agents) |54| `/agents` | Gerenciar configurações de [agent](/pt/sub-agents) |

50| `/autofix-pr [prompt]` | Gerar uma sessão [Claude Code na web](/pt/claude-code-on-the-web#auto-fix-pull-requests) que monitora o PR do branch atual e envia correções quando o CI falha ou revisores deixam comentários. Detecta o PR aberto do seu branch verificado com `gh pr view`; para monitorar um PR diferente, primeiro verifique seu branch. Por padrão, a sessão remota é instruída a corrigir todas as falhas de CI e comentários de revisão; passe um prompt para dar instruções diferentes, por exemplo `/autofix-pr only fix lint and type errors`. Requer a CLI `gh` e acesso a [Claude Code na web](/pt/claude-code-on-the-web#who-can-use-claude-code-on-the-web) |55| `/autofix-pr [prompt]` | Gerar uma sessão [Claude Code na web](/pt/claude-code-on-the-web#auto-fix-pull-requests) que monitora o PR do branch atual e envia correções quando o CI falha ou revisores deixam comentários. Detecta o PR aberto do seu branch verificado com `gh pr view`; para monitorar um PR diferente, primeiro verifique seu branch. Por padrão, a sessão remota é instruída a corrigir todas as falhas de CI e comentários de revisão; passe um prompt para dar instruções diferentes, por exemplo `/autofix-pr only fix lint and type errors`. Requer a CLI `gh` e acesso a [Claude Code na web](/pt/claude-code-on-the-web) |

51| `/background [prompt]` | Desanexar a sessão atual para executar como um [agente de fundo](/pt/agent-view) e liberar este terminal. Passe um prompt para enviar uma instrução adicional antes de desanexar. Monitore a sessão com `claude agents`. Alias: `/bg` |56| `/background [prompt]` | Desanexar a sessão atual para executar como um [agente de fundo](/pt/agent-view) e liberar este terminal. Passe um prompt para enviar uma instrução adicional antes de desanexar. Monitore a sessão com `claude agents`. Alias: `/bg` |

52| `/batch <instruction>` | **[Skill](/pt/skills#bundled-skills).** Orquestrar mudanças em larga escala em um codebase em paralelo. Pesquisa o codebase, decompõe o trabalho em 5 a 30 unidades independentes e apresenta um plano. Uma vez aprovado, gera um [subagent de fundo](/pt/sub-agents#run-subagents-in-foreground-or-background) por unidade em um [git worktree](/pt/worktrees) isolado. Cada subagent implementa sua unidade, executa testes e abre uma solicitação de pull. Requer um repositório git. Exemplo: `/batch migrate src/ from Solid to React` |57| `/batch <instruction>` | **[Skill](/pt/skills#bundled-skills).** Orquestrar mudanças em larga escala em um codebase em paralelo. Pesquisa o codebase, decompõe o trabalho em 5 a 30 unidades independentes e apresenta um plano. Uma vez aprovado, gera um [subagent de fundo](/pt/sub-agents#run-subagents-in-foreground-or-background) por unidade em um [git worktree](/pt/worktrees) isolado. Cada subagent implementa sua unidade, executa testes e abre uma solicitação de pull. Requer um repositório git. Exemplo: `/batch migrate src/ from Solid to React` |

53| `/branch [name]` | Criar um branch da conversa atual neste ponto. Alterna você para o branch e preserva o original, ao qual você pode retornar com `/resume`. Alias: `/fork`. Quando [`CLAUDE_CODE_FORK_SUBAGENT`](/pt/env-vars) está definido, `/fork` em vez disso gera um [subagent bifurcado](/pt/sub-agents#fork-the-current-conversation) e não é mais um alias para este comando |58| `/branch [name]` | Criar um branch da conversa atual neste ponto, para que você possa tentar uma direção diferente sem perder a conversa como está. Alterna você para o branch e preserva o original, ao qual você pode retornar com `/resume`. Para entregar uma tarefa secundária a um subagent de fundo em vez de alternar para uma cópia você mesmo, use `/fork` |

54| `/btw <question>` | Fazer uma [pergunta rápida](/pt/interactive-mode#side-questions-with-%2Fbtw) sem adicionar à conversa |59| `/btw <question>` | Fazer uma [pergunta rápida](/pt/interactive-mode#side-questions-with-%2Fbtw) sem adicionar à conversa |

60| `/cd <path>` | {/* min-version: 2.1.169 */}Mover esta sessão para um novo diretório de trabalho. O cache de prompt da conversa é preservado: o [`CLAUDE.md`](/pt/memory) do novo diretório é anexado como uma mensagem em vez de reconstruir o prompt do sistema. A sessão é relocada para o armazenamento de projeto do novo diretório, então `--resume` e `--continue` o encontram de lá. Solicita que você confie no diretório se você não tiver trabalhado nele antes. Para conceder acesso a um diretório extra sem mover a sessão, use `/add-dir`. Restrinja ou desative destinos `/cd` com [regras de permissão `Cd`](/pt/permissions#cd). Requer Claude Code v2.1.169 ou posterior; versões anteriores relatam `Unknown command: /cd` |

55| `/chrome` | Configurar configurações do [Claude no Chrome](/pt/chrome) |61| `/chrome` | Configurar configurações do [Claude no Chrome](/pt/chrome) |

56| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/pt/skills#bundled-skills).** Carregar material de referência da API Claude para a linguagem do seu projeto (Python, TypeScript, Java, Go, Ruby, C#, PHP ou cURL) e referência de Managed Agents. Cobre uso de ferramentas, streaming, lotes, saídas estruturadas e armadilhas comuns. Também ativa automaticamente quando seu código importa `anthropic` ou `@anthropic-ai/sdk`. Execute `/claude-api migrate` para atualizar o código existente da API Claude para um modelo mais recente: Claude pergunta quais arquivos verificar e qual modelo direcionar, depois atualiza IDs de modelo, configuração de thinking e outros parâmetros que mudaram entre versões. Execute `/claude-api managed-agents-onboard` para um passo a passo interativo que cria um novo Managed Agent do zero |62| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/pt/skills#bundled-skills).** Carregar material de referência da API Claude para a linguagem do seu projeto (Python, TypeScript, Java, Go, Ruby, C#, PHP ou cURL) e referência de Managed Agents. Cobre uso de ferramentas, streaming, lotes, saídas estruturadas e armadilhas comuns. Também ativa automaticamente quando seu código importa `anthropic` ou `@anthropic-ai/sdk`. Execute `/claude-api migrate` para atualizar o código existente da API Claude para um modelo mais recente: Claude pergunta quais arquivos verificar e qual modelo direcionar, depois atualiza IDs de modelo, configuração de thinking e outros parâmetros que mudaram entre versões. Execute `/claude-api managed-agents-onboard` para um passo a passo interativo que cria um novo Managed Agent do zero |

57| `/clear [name]` | Iniciar uma nova conversa com contexto vazio. A conversa anterior permanece disponível em `/resume`. Passe um nome para rotular a conversa anterior no seletor `/resume`. Para liberar contexto enquanto continua a mesma conversa, use `/compact` em vez disso. Aliases: `/reset`, `/new` |63| `/clear [name]` | Iniciar uma nova conversa com contexto vazio. A conversa anterior permanece disponível em `/resume`. Passe um nome para rotular a conversa anterior no seletor `/resume`. Para liberar contexto enquanto continua a mesma conversa, use `/compact` em vez disso. Aliases: `/reset`, `/new` |


74| `/feedback [report]` | Enviar feedback, relatar um bug ou compartilhar sua conversa. Aliases: `/bug`, `/share` |80| `/feedback [report]` | Enviar feedback, relatar um bug ou compartilhar sua conversa. Aliases: `/bug`, `/share` |

75| `/fewer-permission-prompts` | **[Skill](/pt/skills#bundled-skills).** Verificar seus transcritos para chamadas de ferramentas Bash e MCP comuns somente leitura, depois adicionar uma lista de permissões priorizada ao projeto `.claude/settings.json` para reduzir prompts de permissão |81| `/fewer-permission-prompts` | **[Skill](/pt/skills#bundled-skills).** Verificar seus transcritos para chamadas de ferramentas Bash e MCP comuns somente leitura, depois adicionar uma lista de permissões priorizada ao projeto `.claude/settings.json` para reduzir prompts de permissão |

76| `/focus` | Alternar a visualização de foco, que mostra apenas seu último prompt, um resumo de chamada de ferramenta de uma linha com estatísticas de edição de diff e a resposta final. A seleção persiste entre sessões; defina [`viewMode`](/pt/settings#available-settings) nas configurações para substituir. Disponível apenas em [renderização em tela cheia](/pt/fullscreen) |82| `/focus` | Alternar a visualização de foco, que mostra apenas seu último prompt, um resumo de chamada de ferramenta de uma linha com estatísticas de edição de diff e a resposta final. A seleção persiste entre sessões; defina [`viewMode`](/pt/settings#available-settings) nas configurações para substituir. Disponível apenas em [renderização em tela cheia](/pt/fullscreen) |

83| `/fork <directive>` | {/* min-version: 2.1.161 */}Gerar um [subagent bifurcado](/pt/sub-agents#fork-the-current-conversation): um subagent de fundo que herda a conversa completa e trabalha na diretiva enquanto você continua. Seu resultado retorna à sua conversa quando termina. Para alternar para uma cópia da conversa você mesmo, use `/branch`. Antes da v2.1.161, `/fork` é um alias para `/branch` |

77| `/goal [condition\|clear]` | Definir uma [meta](/pt/goal): Claude continua trabalhando entre turnos até que a condição seja atendida. Sem um argumento, mostra a meta atual ou mais recentemente alcançada. `clear`, `stop`, `off`, `reset`, `none` ou `cancel` remove uma meta ativa antecipadamente |84| `/goal [condition\|clear]` | Definir uma [meta](/pt/goal): Claude continua trabalhando entre turnos até que a condição seja atendida. Sem um argumento, mostra a meta atual ou mais recentemente alcançada. `clear`, `stop`, `off`, `reset`, `none` ou `cancel` remove uma meta ativa antecipadamente |

78| `/heapdump` | Escrever um snapshot de heap JavaScript e um detalhamento de memória para `~/Desktop`, ou seu diretório inicial no Linux sem uma pasta Desktop, para diagnosticar alto uso de memória. Consulte [solução de problemas](/pt/troubleshooting#high-cpu-or-memory-usage) |85| `/heapdump` | Escrever um snapshot de heap JavaScript e um detalhamento de memória para `~/Desktop`, ou seu diretório inicial no Linux sem uma pasta Desktop, para diagnosticar alto uso de memória. Consulte [solução de problemas](/pt/troubleshooting#high-cpu-or-memory-usage) |

79| `/help` | Mostrar ajuda e comandos disponíveis |86| `/help` | Mostrar ajuda e comandos disponíveis |


83| `/insights` | Gerar um relatório analisando suas sessões do Claude Code, incluindo áreas do projeto, padrões de interação e pontos de fricção |90| `/insights` | Gerar um relatório analisando suas sessões do Claude Code, incluindo áreas do projeto, padrões de interação e pontos de fricção |

84| `/install-github-app` | Configurar o aplicativo [Claude GitHub Actions](/pt/github-actions) para um repositório. Orienta você na seleção de um repositório e configuração da integração |91| `/install-github-app` | Configurar o aplicativo [Claude GitHub Actions](/pt/github-actions) para um repositório. Orienta você na seleção de um repositório e configuração da integração |

85| `/install-slack-app` | Instalar o aplicativo Claude Slack. Abre um navegador para concluir o fluxo OAuth |92| `/install-slack-app` | Instalar o aplicativo Claude Slack. Abre um navegador para concluir o fluxo OAuth |

86| `/keybindings` | Abrir ou criar seu arquivo de configuração de atalhos de teclado |93| `/keybindings` | Abrir seu arquivo de [atalhos de teclado](/pt/keybindings) |

87| `/login` | Entrar em sua conta Anthropic |94| `/login` | Entrar em sua conta Anthropic |

88| `/logout` | Sair de sua conta Anthropic |95| `/logout` | Sair de sua conta Anthropic |

89| `/loop [interval] [prompt]` | **[Skill](/pt/skills#bundled-skills).** Executar um prompt repetidamente enquanto a sessão permanece aberta. Omita o intervalo e Claude se auto-regula entre iterações. Omita o prompt e, [onde disponível](/pt/scheduled-tasks#run-the-built-in-maintenance-prompt), Claude executa uma verificação de manutenção autônoma ou o prompt em `.claude/loop.md`. Exemplo: `/loop 5m check if the deploy finished`. Consulte [Executar prompts em um cronograma](/pt/scheduled-tasks). Alias: `/proactive` |96| `/loop [interval] [prompt]` | **[Skill](/pt/skills#bundled-skills).** Executar um prompt repetidamente enquanto a sessão permanece aberta. Omita o intervalo e Claude se auto-regula entre iterações. Omita o prompt e, [onde disponível](/pt/scheduled-tasks#run-the-built-in-maintenance-prompt), Claude executa uma verificação de manutenção autônoma ou o prompt em `.claude/loop.md`. Exemplo: `/loop 5m check if the deploy finished`. Consulte [Executar prompts em um cronograma](/pt/scheduled-tasks). Alias: `/proactive` |

90| `/mcp` | Gerenciar conexões de servidor MCP e autenticação OAuth |97| `/mcp [reconnect <server>\|enable\|disable [<server>\|all]]` | Gerenciar conexões de servidor MCP e autenticação OAuth. Execute sem argumento para abrir a lista interativa, passe `reconnect <server>` para reconectar um servidor desconectado, ou passe `enable`/`disable` com um nome de servidor ou `all` para alterar o estado de conexão sem abrir o diálogo |

91| `/memory` | Editar arquivos de memória `CLAUDE.md`, ativar ou desativar [auto-memory](/pt/memory#auto-memory) e visualizar entradas de auto-memory |98| `/memory` | Editar arquivos de memória `CLAUDE.md`, ativar ou desativar [auto-memory](/pt/memory#auto-memory) e visualizar entradas de auto-memory |

92| `/mobile` | Mostrar código QR para baixar o aplicativo Claude mobile. Aliases: `/ios`, `/android` |99| `/mobile` | Mostrar código QR para baixar o aplicativo Claude mobile. Aliases: `/ios`, `/android` |

93| `/model [model]` | Alternar o modelo de IA e salvá-lo como padrão para novas sessões. Para modelos que suportam, use as setas esquerda/direita para [ajustar o nível de esforço](/pt/model-config#adjust-effort-level). Sem um argumento, abre um seletor; pressione `s` em uma linha para alternar apenas para a sessão atual. O seletor pede confirmação quando a conversa tem saída anterior, já que a próxima resposta relê o histórico completo sem contexto em cache. Uma vez confirmado, a alteração entra em vigor sem esperar a resposta atual terminar |100| `/model [model]` | Alternar o modelo de IA e salvá-lo como padrão para novas sessões. Para modelos que suportam, use as setas esquerda/direita para [ajustar o nível de esforço](/pt/model-config#adjust-effort-level). Sem um argumento, abre um seletor; pressione `s` em uma linha para alternar apenas para a sessão atual. O seletor pede confirmação quando a conversa tem saída anterior, já que a próxima resposta relê o histórico completo sem contexto em cache. Uma vez confirmado, a alteração entra em vigor sem esperar a resposta atual terminar |

94| `/passes` | Compartilhar uma semana gratuita do Claude Code com amigos. Visível apenas se sua conta for elegível |101| `/passes` | Compartilhar uma semana gratuita do Claude Code com amigos. Visível apenas se sua conta for elegível |

95| `/permissions` | Gerenciar regras de permissão para permitir, perguntar e negar ferramentas. Abre um diálogo interativo onde você pode visualizar regras por escopo, adicionar ou remover regras, gerenciar diretórios de trabalho e revisar [negações de modo automático recentes](/pt/auto-mode-config#review-denials). Alias: `/allowed-tools` |102| `/permissions` | Gerenciar regras de permissão para permitir, perguntar e negar ferramentas. Abre um diálogo interativo onde você pode visualizar regras por escopo, adicionar ou remover regras, gerenciar diretórios de trabalho e revisar [negações de modo automático recentes](/pt/auto-mode-config#review-denials). Alias: `/allowed-tools` |

96| `/plan [description]` | Entrar no Plan Mode diretamente do prompt. Passe uma descrição opcional para entrar no Plan Mode e começar imediatamente com essa tarefa, por exemplo `/plan fix the auth bug` |103| `/plan [description]` | Entrar no Plan Mode diretamente do prompt. Passe uma descrição opcional para entrar no Plan Mode e começar imediatamente com essa tarefa, por exemplo `/plan fix the auth bug` |

97| `/plugin` | Gerenciar [plugins](/pt/plugins) do Claude Code |104| `/plugin [subcommand]` | Gerenciar [plugins](/pt/plugins) do Claude Code. Execute sem argumento para abrir o menu de plugin, ou passe um subcomando como `list`, `install`, `enable` ou `disable` para agir diretamente |

98| `/powerup` | Descobrir recursos do Claude Code através de lições interativas rápidas com demos animadas |105| `/powerup` | Descobrir recursos do Claude Code através de lições interativas rápidas com demos animadas |

99| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}Removido na v2.1.91. Peça ao Claude diretamente para visualizar comentários de solicitação de pull. Em versões anteriores, busca e exibe comentários de uma solicitação de pull do GitHub; detecta automaticamente o PR para o branch atual, ou passe uma URL ou número de PR. Requer a CLI `gh` |106| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}Removido na v2.1.91. Peça ao Claude diretamente para visualizar comentários de solicitação de pull. Em versões anteriores, busca e exibe comentários de uma solicitação de pull do GitHub; detecta automaticamente o PR para o branch atual, ou passe uma URL ou número de PR. Requer a CLI `gh` |

100| `/privacy-settings` | Visualizar e atualizar suas configurações de privacidade. Disponível apenas para assinantes dos planos Pro e Max |107| `/privacy-settings` | Visualizar e atualizar suas configurações de privacidade. Disponível apenas para assinantes dos planos Pro e Max |

101| `/radio` | Abrir Claude FM lo-fi radio em seu navegador. Imprime a URL do stream quando nenhum navegador está disponível. Não disponível no Bedrock, Vertex ou Foundry |108| `/radio` | Abrir Claude FM lo-fi radio em seu navegador. Imprime a URL do stream quando nenhum navegador está disponível. Não disponível no Bedrock, Vertex ou Foundry |

102| `/recap` | Gerar um resumo de uma linha da sessão atual sob demanda. Consulte [Session recap](/pt/interactive-mode#session-recap) para o recap automático que aparece depois que você esteve ausente |109| `/recap` | Gerar um resumo de uma linha da sessão atual sob demanda. Consulte [Session recap](/pt/interactive-mode#session-recap) para o recap automático que aparece depois que você esteve ausente |

103| `/release-notes` | Visualizar o changelog em um seletor de versão interativo. Selecione uma versão específica para ver suas notas de lançamento, ou escolha mostrar todas as versões |110| `/release-notes` | Visualizar o changelog em um seletor de versão interativo. Selecione uma versão específica para ver suas notas de lançamento, ou escolha mostrar todas as versões |

104| `/reload-plugins` | Recarregar todos os [plugins](/pt/plugins) ativos para aplicar alterações pendentes sem reiniciar. Relata contagens para cada componente recarregado e sinaliza quaisquer erros de carregamento |111| `/reload-plugins [--force]` | Recarregar todos os [plugins](/pt/plugins) ativos para aplicar alterações pendentes sem reiniciar. Relata contagens para cada componente recarregado e sinaliza quaisquer erros de carregamento. Quando o recarregamento alteraria quais ferramentas MCP são carregadas e invalidaria o cache de prompt, o comando avisa e pula a menos que você passe `--force` |

105| `/reload-skills` | {/* min-version: 2.1.152 */}Verificar novamente [skill](/pt/skills) e diretórios de comando para que skills adicionadas ou alteradas no disco durante a sessão fiquem disponíveis sem reiniciar. Relata quantas skills estão disponíveis e quantas foram adicionadas ou removidas |112| `/reload-skills` | {/* min-version: 2.1.152 */}Verificar novamente [skill](/pt/skills) e diretórios de comando para que skills adicionadas ou alteradas no disco durante a sessão fiquem disponíveis sem reiniciar. Relata quantas skills estão disponíveis e quantas foram adicionadas ou removidas. Adicionado na v2.1.152 |

106| `/remote-control` | Disponibilizar esta sessão para [controle remoto](/pt/remote-control) do claude.ai. Alias: `/rc` |113| `/remote-control` | Disponibilizar esta sessão para [controle remoto](/pt/remote-control) do claude.ai. Alias: `/rc` |

107| `/remote-env` | Configurar o ambiente remoto padrão para [sessões web iniciadas com `--remote`](/pt/claude-code-on-the-web#configure-your-environment) |114| `/remote-env` | Escolher o ambiente padrão para [agentes em nuvem](/pt/claude-code-on-the-web#configure-your-environment) |

108| `/rename [name]` | Renomear a sessão atual e mostrar o nome na barra de prompt. Sem um nome, gera automaticamente um a partir do histórico de conversa |115| `/rename [name]` | Renomear a sessão atual e mostrar o nome na barra de prompt. Sem um nome, gera automaticamente um a partir do histórico de conversa |

109| `/resume [session]` | Retomar uma conversa por ID ou nome, ou abrir o seletor de sessão. A partir da v2.1.144, [sessões de fundo](/pt/agent-view) aparecem no seletor marcadas com `bg`. Alias: `/continue` |116| `/resume [session]` | Retomar uma conversa por ID ou nome, ou abrir o seletor de sessão. A partir da v2.1.144, [sessões de fundo](/pt/agent-view) aparecem no seletor marcadas com `bg`. Alias: `/continue` |

110| `/review [PR]` | Revisar uma solicitação de pull localmente em sua sessão atual. Para uma revisão mais profunda baseada em nuvem, consulte [`/code-review ultra`](/pt/ultrareview) |117| `/review [PR]` | Revisar uma solicitação de pull localmente em sua sessão atual. Para uma revisão mais profunda baseada em nuvem, consulte [`/code-review ultra`](/pt/ultrareview) |


124| `/statusline` | Configurar a [linha de status](/pt/statusline) do Claude Code. Descreva o que você quer, ou execute sem argumentos para auto-configurar a partir do seu prompt de shell |131| `/statusline` | Configurar a [linha de status](/pt/statusline) do Claude Code. Descreva o que você quer, ou execute sem argumentos para auto-configurar a partir do seu prompt de shell |

125| `/stickers` | Pedir adesivos do Claude Code |132| `/stickers` | Pedir adesivos do Claude Code |

126| `/stop` | Parar a [sessão de fundo](/pt/agent-view) atual. Disponível apenas enquanto anexado a uma sessão de fundo; a transcrição e qualquer worktree são mantidos. Para desanexar sem parar, use `/exit` ou pressione `←` |133| `/stop` | Parar a [sessão de fundo](/pt/agent-view) atual. Disponível apenas enquanto anexado a uma sessão de fundo; a transcrição e qualquer worktree são mantidos. Para desanexar sem parar, use `/exit` ou pressione `←` |

127| `/tasks` | Listar e gerenciar tarefas em segundo plano. Também disponível como `/bashes` |134| `/tasks` | Visualizar e gerenciar tudo em execução em segundo plano. Também disponível como `/bashes` |

128| `/team-onboarding` | Gerar um guia de integração de equipe a partir do seu histórico de uso do Claude Code. Claude analisa suas sessões, comandos e uso de servidor MCP dos últimos 30 dias e produz um guia markdown que um colega de equipe pode colar como primeira mensagem para se configurar rapidamente. Para assinantes do claude.ai nos planos Pro, Max, Team e Enterprise, também retorna um link de compartilhamento que colegas de equipe podem abrir diretamente no Claude Code |135| `/team-onboarding` | Gerar um guia de integração de equipe a partir do seu histórico de uso do Claude Code. Claude analisa suas sessões, comandos e uso de servidor MCP dos últimos 30 dias e produz um guia markdown que um colega de equipe pode colar como primeira mensagem para se configurar rapidamente. Para assinantes do claude.ai nos planos Pro, Max, Team e Enterprise, também retorna um link de compartilhamento que colegas de equipe podem abrir diretamente no Claude Code |

129| `/teleport` | Puxar uma sessão [Claude Code na web](/pt/claude-code-on-the-web#from-web-to-terminal) para este terminal: abre um seletor, depois busca o branch e a conversa. Também disponível como `/tp`. Requer uma assinatura claude.ai |136| `/teleport` | Puxar uma sessão [Claude Code na web](/pt/claude-code-on-the-web#from-web-to-terminal) para este terminal: abre um seletor, depois busca o branch e a conversa. Também disponível como `/tp`. Requer uma assinatura claude.ai |

130| `/terminal-setup` | Configurar atalhos de teclado do terminal para Shift+Enter e outros atalhos. Visível apenas em terminais que precisam, como VS Code, Cursor, Devin Desktop, Alacritty ou Zed |137| `/terminal-setup` | Configurar atalhos de teclado do terminal para Shift+Enter e outros atalhos. Visível apenas em terminais que precisam, como VS Code, Cursor, Devin Desktop, Alacritty ou Zed |


141| `/web-setup` | Conectar sua conta GitHub ao [Claude Code na web](/pt/web-quickstart#connect-from-your-terminal) usando suas credenciais locais de `gh` CLI. `/schedule` solicita isso automaticamente se o GitHub não estiver conectado |148| `/web-setup` | Conectar sua conta GitHub ao [Claude Code na web](/pt/web-quickstart#connect-from-your-terminal) usando suas credenciais locais de `gh` CLI. `/schedule` solicita isso automaticamente se o GitHub não estiver conectado |

142| `/workflows` | Abrir a visualização de progresso do [workflow](/pt/workflows#watch-the-run) para assistir, pausar, retomar ou salvar workflows em execução e concluídos |149| `/workflows` | Abrir a visualização de progresso do [workflow](/pt/workflows#watch-the-run) para assistir, pausar, retomar ou salvar workflows em execução e concluídos |

143 150 

144## MCP prompts151<h2 id="mcp-prompts">

152 MCP prompts

153</h2>

145 154 

146Os servidores MCP podem expor prompts que aparecem como comandos. Estes usam o formato `/mcp__<server>__<prompt>` e são descobertos dinamicamente a partir de servidores conectados. Consulte [MCP prompts](/pt/mcp#use-mcp-prompts-as-commands) para detalhes.155Os servidores MCP podem expor prompts que aparecem como comandos. Estes usam o formato `/mcp__<server>__<prompt>` e são descobertos dinamicamente a partir de servidores conectados. Consulte [MCP prompts](/pt/mcp#use-mcp-prompts-as-commands) para detalhes.

147 156 

148## Veja também157<h2 id="see-also">

158 Veja também

159</h2>

149 160 

150* [Skills](/pt/skills): criar seus próprios comandos161* [Skills](/pt/skills): criar seus próprios comandos

151* [Modo interativo](/pt/interactive-mode): atalhos de teclado, modo Vim e histórico de comandos162* [Modo interativo](/pt/interactive-mode): atalhos de teclado, modo Vim e histórico de comandos

Details

227no meio da sessão. *Sonnet* é o padrão de trabalho para trabalho de recursos cotidianos,227no meio da sessão. *Sonnet* é o padrão de trabalho para trabalho de recursos cotidianos,

228bugs, testes e revisões. Recorra a *Opus* em refatorações grandes, depuração complicada,228bugs, testes e revisões. Recorra a *Opus* em refatorações grandes, depuração complicada,

229ou qualquer coisa de alto risco. Desça para *Haiku* para perguntas rápidas,229ou qualquer coisa de alto risco. Desça para *Haiku* para perguntas rápidas,

230formatação e edições mecânicas onde a velocidade vence.230formatação e edições mecânicas onde a velocidade vence. *Fable 5* é o modelo mais

231capaz para suas tarefas mais difíceis e de longa duração; não é o

232padrão, então selecione-o com `/model fable`, e observe que conteúdo de cibersegurança e

233biologia volta automaticamente para Opus.

231 234 

232*Tente agora:* digite `/model` e escolha Sonnet se você ainda não o fez. É235*Tente agora:* digite `/model` e escolha Sonnet se você ainda não o fez. É

233o padrão certo para a maioria das tarefas.236o padrão certo para a maioria das tarefas.


236```239```

237 240 

238| Modelo | Melhor para |241| Modelo | Melhor para |

239| ------ | ---------------------------------------------------------------------------------------------------------------- |242| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

243| Fable 5 | As tarefas mais difíceis e de longa duração. Apenas com opt-in: selecione com `/model fable`. Conteúdo de cibersegurança ou biologia [volta para Opus](/pt/model-config#automatic-model-fallback) |

240| Opus | Refatorações em larga escala, depuração complexa, decisões de arquitetura, mudanças de alto risco |244| Opus | Refatorações em larga escala, depuração complexa, decisões de arquitetura, mudanças de alto risco |

241| Sonnet | Trabalho de recursos cotidianos, correções de bugs, testes, documentação, revisão de código. Padrão recomendado. |245| Sonnet | Trabalho de recursos cotidianos, correções de bugs, testes, documentação, revisão de código. Padrão recomendado. |

242| Haiku | Perguntas rápidas, formatação, edições mecânicas, iteração rápida |246| Haiku | Perguntas rápidas, formatação, edições mecânicas, iteração rápida |

computer-use.md +3 −3

Details

226Outra sessão do Claude Code mantém o bloqueio. Termine a tarefa nessa sessão ou saia dela. Se a outra sessão travou, o bloqueio é liberado automaticamente quando Claude detecta que o processo não está mais em execução.226Outra sessão do Claude Code mantém o bloqueio. Termine a tarefa nessa sessão ou saia dela. Se a outra sessão travou, o bloqueio é liberado automaticamente quando Claude detecta que o processo não está mais em execução.

227 227 

228<h3 id="macos-permissions-prompt-keeps-reappearing">228<h3 id="macos-permissions-prompt-keeps-reappearing">

229 O prompt de permissões do macOS continua reaparecendo229 macOS permissions prompt keeps reappearing

230</h3>230</h3>

231 231 

232O macOS às vezes requer uma reinicialização do processo solicitante após você conceder Screen Recording. Saia completamente do Claude Code e inicie uma nova sessão. Se o prompt persistir, abra **System Settings > Privacy & Security > Screen Recording** e confirme que seu aplicativo de terminal está listado e ativado.232O macOS às vezes requer uma reinicialização do processo solicitante após você conceder Screen Recording. Saia completamente do Claude Code e inicie uma nova sessão. Se o prompt persistir, abra **System Settings > Privacy & Security > Screen Recording** e confirme que seu aplicativo de terminal está listado e ativado.

233 233 

234<h3 id="computer-use-doesn-t-appear-in-/mcp">234<h3 id="computer-use-doesnt-appear-in-/mcp">

235 `computer-use` não aparece em `/mcp`235 `computer-use` doesn't appear in `/mcp`

236</h3>236</h3>

237 237 

238O servidor só aparece em configurações elegíveis. Verifique se:238O servidor só aparece em configurações elegíveis. Verifique se:

context-window.md +1591 −5

Details

6 6 

7> Uma simulação interativa de como a janela de contexto do Claude Code se preenche durante uma sessão. Veja o que é carregado automaticamente, quanto cada leitura de arquivo custa e quando regras e hooks são acionados.7> Uma simulação interativa de como a janela de contexto do Claude Code se preenche durante uma sessão. Veja o que é carregado automaticamente, quanto cada leitura de arquivo custa e quando regras e hooks são acionados.

8 8 

9A janela de contexto do Claude Code contém tudo o que Claude sabe sobre sua sessão: suas instruções, os arquivos que lê, suas próprias respostas e conteúdo que nunca aparece em seu terminal. A linha do tempo abaixo mostra o que é carregado e quando. Veja [o detalhamento escrito](#what-the-timeline-shows) para o mesmo conteúdo como uma lista.9export const ContextWindow = () => {

10 const MAX = 200000;

11 const STARTUP_END = 0.2;

12 {}

13 const EVENTS = useMemo(() => [{}, {

14 t: 0.015,

15 kind: 'auto',

16 label: 'System prompt',

17 tokens: 4200,

18 color: '#6B6964',

19 vis: 'hidden',

20 desc: 'Core instructions for behavior, tool use, and response formatting. Always loaded first. You never see it.',

21 link: null

22 }, {

23 t: 0.035,

24 kind: 'auto',

25 label: 'Auto memory (MEMORY.md)',

26 tokens: 680,

27 color: '#E8A45C',

28 vis: 'hidden',

29 desc: "Claude's notes to itself from previous sessions: build commands it learned, patterns it noticed, mistakes to avoid. The first 200 lines or 25KB, whichever comes first, are loaded into the conversation context.",

30 link: '/en/memory#auto-memory'

31 }, {

32 t: 0.06,

33 kind: 'auto',

34 label: 'Environment info',

35 tokens: 280,

36 color: '#6B6964',

37 vis: 'hidden',

38 desc: 'Working directory, platform, shell, OS version, and whether this is a git repo. Git branch, status, and recent commits load as a separate block at the very end of the system prompt.',

39 link: null

40 }, {

41 t: 0.08,

42 kind: 'auto',

43 label: 'MCP tools (deferred)',

44 tokens: 120,

45 color: '#9B7BC4',

46 vis: 'hidden',

47 desc: 'MCP tool names listed so Claude knows what is available. By default, full schemas stay deferred and Claude loads specific ones on demand via tool search when a task needs them. Set `ENABLE_TOOL_SEARCH=auto` to load schemas upfront when they fit within 10% of the context window, or `ENABLE_TOOL_SEARCH=false` to load everything.',

48 link: '/en/mcp#scale-with-mcp-tool-search'

49 }, {

50 t: 0.1,

51 kind: 'auto',

52 label: 'Skill descriptions',

53 tokens: 450,

54 color: '#D4A843',

55 vis: 'hidden',

56 noSurviveCompact: true,

57 desc: 'One-line descriptions of available skills so Claude knows what it can invoke. Full skill content loads only when Claude actually uses one. Skills with `disable-model-invocation: true` are not in this list. They stay completely out of context until you invoke them with `/name`. Unlike the rest of the startup content, this listing is not re-injected after `/compact`. Only skills you actually invoked get preserved.',

58 link: '/en/skills'

59 }, {

60 t: 0.12,

61 kind: 'auto',

62 label: '~/.claude/CLAUDE.md',

63 tokens: 320,

64 color: '#6A9BCC',

65 vis: 'hidden',

66 desc: 'Your global preferences. Applies to every project. Loaded alongside project instructions at the start of every conversation.',

67 link: '/en/memory#choose-where-to-put-claude-md-files'

68 }, {

69 t: 0.14,

70 kind: 'auto',

71 label: 'Project CLAUDE.md',

72 tokens: 1800,

73 color: '#6A9BCC',

74 vis: 'hidden',

75 desc: 'Project conventions, build commands, architecture notes. The most important file you can create. Lives in your project root, so your whole team gets the same instructions.',

76 tip: 'Keep it under 200 lines. Move reference content to skills or path-scoped rules so it only loads when needed.',

77 link: '/en/memory'

78 }, {}, {

79 t: 0.22,

80 kind: 'user',

81 label: 'Your prompt',

82 tokens: 45,

83 color: '#558A42',

84 vis: 'full',

85 desc: '"Fix the auth bug where users get 401 after token refresh"',

86 link: null

87 }, {}, {

88 t: 0.28,

89 kind: 'claude',

90 label: 'Read src/api/auth.ts',

91 tokens: 2400,

92 color: '#8A8880',

93 vis: 'brief',

94 desc: 'Main auth file. You see "Read auth.ts" in your terminal, but the 2,400 tokens of file content only Claude sees.',

95 tip: 'File reads dominate context usage. Be specific in prompts ("fix the bug in auth.ts") so Claude reads fewer files. For research-heavy tasks, use a subagent.',

96 link: null

97 }, {

98 t: 0.32,

99 kind: 'claude',

100 label: 'Read src/lib/tokens.ts',

101 tokens: 1100,

102 color: '#8A8880',

103 vis: 'brief',

104 desc: 'Following imports to the token module. Shown as a one-liner in your terminal.',

105 link: null

106 }, {

107 t: 0.35,

108 kind: 'auto',

109 label: 'Rule: api-conventions.md',

110 tokens: 380,

111 color: '#4A9B8E',

112 vis: 'brief',

113 desc: 'This rule in `.claude/rules/` has a `paths:` pattern matching `src/api/**`. It loaded automatically when Claude read a file in that directory. You see "Loaded .claude/rules/api-conventions.md" in your terminal, but not the rule content.',

114 link: '/en/memory#path-specific-rules'

115 }, {

116 t: 0.38,

117 kind: 'claude',

118 label: 'Read middleware.ts',

119 tokens: 1800,

120 color: '#8A8880',

121 vis: 'brief',

122 desc: 'Tracing the auth flow deeper.',

123 link: null

124 }, {

125 t: 0.41,

126 kind: 'claude',

127 label: 'Read auth.test.ts',

128 tokens: 1600,

129 color: '#8A8880',

130 vis: 'brief',

131 desc: 'Checking existing tests for expected behavior.',

132 link: null

133 }, {

134 t: 0.44,

135 kind: 'auto',

136 label: 'Rule: testing.md',

137 tokens: 290,

138 color: '#4A9B8E',

139 vis: 'brief',

140 desc: 'Another path-scoped rule, this one matching `*.test.ts` files. Triggered when Claude read auth.test.ts. Shown as a one-line "Loaded" notice.',

141 link: '/en/memory#path-specific-rules'

142 }, {

143 t: 0.47,

144 kind: 'claude',

145 label: 'grep "refreshToken"',

146 tokens: 600,

147 color: '#A09E96',

148 vis: 'brief',

149 desc: 'Search results across the codebase. You see the command ran, not the full output.',

150 link: null

151 }, {}, {

152 t: 0.53,

153 kind: 'claude',

154 label: "Claude's analysis",

155 tokens: 800,

156 color: '#D97757',

157 vis: 'full',

158 desc: 'Explains the bug: token invalidated too early in the rotation. This text appears in your terminal.',

159 link: null

160 }, {

161 t: 0.57,

162 kind: 'claude',

163 label: 'Edit auth.ts',

164 tokens: 400,

165 color: '#D97757',

166 vis: 'full',

167 desc: 'Fixes the token rotation order. The diff appears in your terminal.',

168 link: null

169 }, {

170 t: 0.59,

171 kind: 'hook',

172 label: 'Hook: prettier',

173 tokens: 120,

174 color: '#B8860B',

175 vis: 'hidden',

176 desc: 'A PostToolUse hook in `settings.json` runs prettier after every file edit and reports back via `hookSpecificOutput.additionalContext`. That field enters Claude\'s context. Plain stdout on exit 0 does not. It is written to the debug log only.',

177 tip: 'Output JSON with `additionalContext` to send info to Claude. For PostToolUse hooks, exit code 2 surfaces stderr as an error but cannot block since the tool already ran. Keep output concise since it enters context without truncation.',

178 link: '/en/hooks-guide'

179 }, {

180 t: 0.62,

181 kind: 'claude',

182 label: 'Edit auth.test.ts',

183 tokens: 600,

184 color: '#D97757',

185 vis: 'full',

186 desc: 'Adds a regression test for the fix. The diff appears in your terminal.',

187 link: null

188 }, {

189 t: 0.64,

190 kind: 'hook',

191 label: 'Hook: prettier',

192 tokens: 100,

193 color: '#B8860B',

194 vis: 'hidden',

195 desc: 'The same hook fires again for the test file. Every matching tool event triggers it.',

196 link: '/en/hooks-guide'

197 }, {

198 t: 0.67,

199 kind: 'claude',

200 label: 'npm test output',

201 tokens: 1200,

202 color: '#A09E96',

203 vis: 'brief',

204 desc: 'Runs the test suite. You see "Running npm test..." and the pass count, not the full 1,200 tokens of output.',

205 link: null

206 }, {

207 t: 0.70,

208 kind: 'claude',

209 label: 'Summary',

210 tokens: 400,

211 color: '#D97757',

212 vis: 'full',

213 desc: '"Fixed token rotation. Added regression test. All tests pass."',

214 link: null

215 }, {}, {

216 t: 0.72,

217 kind: 'user',

218 label: 'Your follow-up',

219 tokens: 40,

220 color: '#558A42',

221 vis: 'full',

222 desc: '"Use a subagent to research session timeout handling, then fix it"',

223 tip: 'Follow-ups add to the same context. Delegating research to a subagent keeps large file reads out of your main window.',

224 link: null

225 }, {

226 t: 0.79,

227 kind: 'claude',

228 label: 'Spawn research subagent',

229 tokens: 80,

230 color: '#D97757',

231 vis: 'brief',

232 desc: "Claude delegates the research to a subagent with a fresh, separate context window. It loads CLAUDE.md and the same MCP and skill setup, but starts without your conversation history or the main session's auto memory.",

233 link: '/en/sub-agents'

234 }, {

235 t: 0.795,

236 kind: 'sub',

237 label: 'System prompt',

238 tokens: 0,

239 subTokens: 900,

240 color: '#6B6964',

241 vis: 'hidden',

242 desc: "The subagent gets its own system prompt, shorter than the main session's. For the general-purpose agent, it's a brief prompt plus environment details. The main session's auto memory is not included. If a custom agent has memory: in its frontmatter, it loads its own separate MEMORY.md here instead.",

243 link: '/en/sub-agents#enable-persistent-memory'

244 }, {

245 t: 0.80,

246 kind: 'sub',

247 label: 'Project CLAUDE.md (own copy)',

248 tokens: 0,

249 subTokens: 1800,

250 color: '#6A9BCC',

251 vis: 'hidden',

252 desc: "The subagent loads CLAUDE.md too. Same file, same content, but it counts against the subagent's context, not yours. The built-in Explore and Plan agents skip this for a smaller context.",

253 link: '/en/sub-agents'

254 }, {

255 t: 0.805,

256 kind: 'sub',

257 label: 'MCP tools + skills',

258 tokens: 0,

259 subTokens: 970,

260 color: '#9B7BC4',

261 vis: 'hidden',

262 desc: "The subagent has access to the same MCP servers and skills. It gets most of the parent's tools, minus several that don't apply in a nested context, including plan-mode controls, background-task tools, and by default the Agent tool itself to prevent recursion.",

263 link: '/en/sub-agents'

264 }, {

265 t: 0.81,

266 kind: 'sub',

267 label: 'Task prompt from main',

268 tokens: 0,

269 subTokens: 120,

270 color: '#558A42',

271 vis: 'hidden',

272 desc: "Instead of a user prompt, the subagent receives the task Claude wrote for it: 'Research session timeout handling in this codebase.'",

273 link: '/en/sub-agents'

274 }, {

275 t: 0.82,

276 kind: 'sub',

277 label: 'Read session.ts',

278 tokens: 0,

279 subTokens: 2200,

280 color: '#8A8880',

281 vis: 'hidden',

282 desc: "Now the subagent does its work. This file read fills the subagent's context, not yours.",

283 link: '/en/sub-agents'

284 }, {

285 t: 0.825,

286 kind: 'sub',

287 label: 'Read timeouts.ts',

288 tokens: 0,

289 subTokens: 800,

290 color: '#8A8880',

291 vis: 'hidden',

292 desc: "Another file read in the subagent's separate context.",

293 link: '/en/sub-agents'

294 }, {

295 t: 0.83,

296 kind: 'sub',

297 label: 'Read config/*.ts',

298 tokens: 0,

299 subTokens: 3100,

300 color: '#8A8880',

301 vis: 'hidden',

302 desc: "The subagent can read as many files as it needs. None of this touches your main context.",

303 link: '/en/sub-agents'

304 }, {

305 t: 0.85,

306 kind: 'claude',

307 label: 'Subagent returns summary',

308 tokens: 420,

309 color: '#D97757',

310 vis: 'brief',

311 desc: "Only the subagent's final text response comes back to your context, plus a small metadata trailer with token counts and duration. The subagent read 6,100 tokens of files. You got a 420-token result. That's the context savings.",

312 link: '/en/sub-agents'

313 }, {

314 t: 0.86,

315 kind: 'claude',

316 label: "Claude's response",

317 tokens: 1200,

318 color: '#D97757',

319 vis: 'full',

320 desc: 'Analysis and fix for session timeouts. This text appears in your terminal.',

321 link: null

322 }, {}, {

323 t: 0.875,

324 kind: 'user',

325 label: '!git status',

326 tokens: 180,

327 color: '#558A42',

328 vis: 'full',

329 desc: "You ran a shell command with the ! prefix to see which files Claude modified. The command and its output both enter context as part of your message. Useful for grounding Claude in command output without Claude running it.",

330 link: '/en/interactive-mode#bash-mode-with-prefix'

331 }, {

332 t: 0.89,

333 kind: 'user',

334 label: '/commit-push',

335 tokens: 620,

336 color: '#558A42',

337 vis: 'brief',

338 desc: 'You invoked a skill that has `disable-model-invocation: true`. Its description was not in the skill index at startup, so it cost zero context until this moment. Now the full skill content loads and Claude follows its instructions to stage, commit, and push your changes.',

339 tip: 'Set `disable-model-invocation: true` on skills with side effects like committing, deploying, or sending messages. They stay out of context entirely until you need them.',

340 link: '/en/skills#control-who-invokes-a-skill'

341 }, {}, {

342 t: 0.93,

343 kind: 'compact',

344 label: '/compact',

345 tokens: 0,

346 color: '#D97757',

347 vis: 'brief',

348 desc: 'Replaces the conversation with a structured summary. You see a "Conversation compacted" message. The summarization happens without appearing in your terminal.',

349 link: '/en/how-claude-code-works#the-context-window'

350 }].filter(e => e.t !== undefined), []);

351 const VIS_META = {

352 hidden: {

353 label: 'Invisible in your terminal',

354 sub: 'This content does not appear in your terminal.'

355 },

356 brief: {

357 label: 'One-liner in your terminal',

358 sub: 'You see a brief mention, not the full content.'

359 },

360 full: {

361 label: 'Shown in your terminal',

362 sub: 'The actual content appears in your terminal.'

363 }

364 };

365 {}

366 const GATES = [{

367 at: 0.18,

368 kind: 'prompt',

369 text: 'Fix the auth bug where users get 401 after token refresh',

370 resumeTo: 0.22

371 }, {

372 at: 0.705,

373 kind: 'prompt',

374 text: 'Use a subagent to research session timeout handling, then fix it',

375 resumeTo: 0.72

376 }, {

377 at: 0.865,

378 kind: 'bang',

379 text: '!git status',

380 resumeTo: 0.875

381 }, {

382 at: 0.88,

383 kind: 'slash',

384 text: '/commit-push',

385 resumeTo: 0.89

386 }, {

387 at: 0.90,

388 kind: 'compact',

389 text: '/compact',

390 resumeTo: 1

391 }];

392 const KIND_META = {

393 auto: {

394 badge: 'auto',

395 detail: 'Auto-loaded',

396 badgeBg: 'rgba(94,93,89,0.15)',

397 badgeColor: '#8A8880'

398 },

399 user: {

400 badge: 'you',

401 detail: 'You typed this',

402 badgeBg: 'rgba(85,138,66,0.15)',

403 badgeColor: '#6BA656'

404 },

405 claude: {

406 badge: 'claude',

407 detail: "Claude's work",

408 badgeBg: 'rgba(217,119,87,0.12)',

409 badgeColor: '#D97757'

410 },

411 hook: {

412 badge: 'hook',

413 detail: 'Hook (automatic)',

414 badgeBg: 'rgba(184,134,11,0.15)',

415 badgeColor: '#CCA020'

416 },

417 compact: {

418 badge: 'compact',

419 detail: 'Compaction',

420 badgeBg: 'rgba(217,119,87,0.12)',

421 badgeColor: '#D97757'

422 },

423 sub: {

424 badge: 'subagent',

425 detail: "In subagent's context",

426 badgeBg: 'rgba(155,123,196,0.12)',

427 badgeColor: '#9B7BC4'

428 }

429 };

430 const LEGEND = [{

431 c: '#6B6964',

432 l: 'System'

433 }, {

434 c: '#6A9BCC',

435 l: 'CLAUDE.md'

436 }, {

437 c: '#E8A45C',

438 l: 'Memory'

439 }, {

440 c: '#D4A843',

441 l: 'Skills'

442 }, {

443 c: '#9B7BC4',

444 l: 'MCP'

445 }, {

446 c: '#4A9B8E',

447 l: 'Rules'

448 }, {

449 c: '#558A42',

450 l: 'You'

451 }, {

452 c: '#8A8880',

453 l: 'Files'

454 }, {

455 c: '#A09E96',

456 l: 'Output'

457 }, {

458 c: '#D97757',

459 l: 'Claude'

460 }, {

461 c: '#B8860B',

462 l: 'Hooks'

463 }];

464 const fmt = n => n >= 1000 ? (n / 1000).toFixed(1).replace(/\.0$/, '') + 'K' : n + '';

465 const [time, setTime] = useState(0);

466 const [playing, setPlaying] = useState(false);

467 const [hovIdx, setHovIdx] = useState(null);

468 const [selIdx, setSelIdx] = useState(null);

469 const [hovCat, setHovCat] = useState(null);

470 const [gatesPassed, setGatesPassed] = useState(0);

471 const [mounted, setMounted] = useState(false);

472 const [hasInteracted, setHasInteracted] = useState(false);

473 const lastRef = useRef(null);

474 const scrollRef = useRef(null);

475 const detailRef = useRef(null);

476 useEffect(() => setMounted(true), []);

477 const activeGate = GATES.find((g, i) => i >= gatesPassed && time >= g.at && time < g.resumeTo);

478 useEffect(() => {

479 if (!playing) return;

480 let raf;

481 let stopped = false;

482 const tick = ts => {

483 if (stopped) return;

484 if (!lastRef.current) lastRef.current = ts;

485 const dt = (ts - lastRef.current) / 1000;

486 lastRef.current = ts;

487 setTime(prev => {

488 const next = prev + dt * 0.032;

489 const gate = GATES.find((g, i) => i >= gatesPassed && next >= g.at && prev < g.resumeTo);

490 if (gate) {

491 stopped = true;

492 setPlaying(false);

493 return gate.at;

494 }

495 if (next >= 1) {

496 stopped = true;

497 setPlaying(false);

498 return 1;

499 }

500 return next;

501 });

502 if (!stopped) raf = requestAnimationFrame(tick);

503 };

504 raf = requestAnimationFrame(tick);

505 return () => {

506 stopped = true;

507 cancelAnimationFrame(raf);

508 lastRef.current = null;

509 };

510 }, [playing, gatesPassed]);

511 const sendPrompt = () => {

512 if (!activeGate) return;

513 const isCompact = activeGate.kind === 'compact';

514 setGatesPassed(n => n + 1);

515 setTime(activeGate.resumeTo);

516 setSelIdx(null);

517 setHovIdx(null);

518 if (!isCompact) setPlaying(true);

519 };

520 const visibleCount = EVENTS.filter(e => e.t <= time).length;

521 const preCompactVisible = useMemo(() => EVENTS.slice(0, visibleCount), [EVENTS, visibleCount]);

522 const compactGateIdx = GATES.length - 1;

523 const isCompacted = gatesPassed > compactGateIdx && preCompactVisible.some(e => e.kind === 'compact');

524 const {visible, preCompactTotal} = useMemo(() => {

525 const nonCompact = preCompactVisible.filter(e => e.kind !== 'compact');

526 if (!isCompacted) {

527 return {

528 visible: preCompactVisible,

529 preCompactTotal: 0

530 };

531 }

532 {}

533 const autoLoads = nonCompact.filter(e => e.kind === 'auto' && e.t < STARTUP_END && !e.noSurviveCompact);

534 const summarized = nonCompact.filter(e => e.t >= STARTUP_END && e.kind !== 'sub');

535 const sumTokens = summarized.reduce((s, e) => s + e.tokens, 0);

536 const summaryBlock = {

537 t: STARTUP_END,

538 kind: 'compact',

539 label: 'Conversation summary',

540 tokens: Math.round(sumTokens * 0.12),

541 color: '#A09E96',

542 vis: 'hidden',

543 desc: `All ${summarized.length} conversation events condensed into one structured summary. The summary keeps: your requests and intent, key technical concepts, files examined or modified with important code snippets, errors and how they were fixed, pending tasks, and current work. It replaces the verbatim conversation: full tool outputs and intermediate reasoning are gone. Claude can still reference the work but won't have the exact code it read earlier.`,

544 link: '/en/how-claude-code-works#the-context-window'

545 };

546 return {

547 visible: [...autoLoads, summaryBlock],

548 preCompactTotal: nonCompact.reduce((s, e) => s + e.tokens, 0)

549 };

550 }, [preCompactVisible, isCompacted]);

551 const {blocks, totalTokens} = useMemo(() => {

552 const bl = visible.map((e, visIdx) => ({

553 ...e,

554 id: e.label + e.t,

555 visIdx

556 })).filter(e => e.tokens > 0 || e.label === 'Conversation summary');

557 return {

558 blocks: bl,

559 totalTokens: bl.reduce((s, b) => s + b.tokens, 0)

560 };

561 }, [visible]);

562 const subTotal = useMemo(() => visible.filter(e => e.kind === 'sub').reduce((s, e) => s + (e.subTokens || 0), 0), [visible]);

563 useEffect(() => {

564 if (!scrollRef.current) return;

565 if (isCompacted) scrollRef.current.scrollTo({

566 top: 0,

567 behavior: 'smooth'

568 }); else if (playing || activeGate) scrollRef.current.scrollTop = scrollRef.current.scrollHeight;

569 }, [visible.length, !!activeGate, isCompacted]);

570 const rootRef = useRef(null);

571 const keyStateRef = useRef({});

572 const [isFullscreen, setIsFullscreen] = useState(false);

573 keyStateRef.current = {

574 time,

575 activeGate,

576 sendPrompt,

577 hasInteracted

578 };

579 useEffect(() => {

580 const onFsChange = () => setIsFullscreen(!!document.fullscreenElement);

581 document.addEventListener('fullscreenchange', onFsChange);

582 return () => document.removeEventListener('fullscreenchange', onFsChange);

583 }, []);

584 const toggleFullscreen = () => {

585 if (!rootRef.current) return;

586 if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {});

587 };

588 useEffect(() => {

589 const onKey = e => {

590 const tag = e.target.tagName;

591 if (tag === 'INPUT' || tag === 'BUTTON' || tag === 'TEXTAREA' || tag === 'SELECT' || e.target.isContentEditable) return;

592 if (!rootRef.current) return;

593 const rect = rootRef.current.getBoundingClientRect();

594 if (rect.width === 0 && rect.height === 0) return;

595 if (rect.bottom < 0 || rect.top > window.innerHeight) return;

596 if (e.code === 'Space') {

597 const {time: t, activeGate: g, sendPrompt: send, hasInteracted: hi} = keyStateRef.current;

598 if (!hi) return;

599 e.preventDefault();

600 if (t === 0) setPlaying(true); else if (g) send(); else if (t >= 1) {

601 setTime(0);

602 setGatesPassed(0);

603 setSelIdx(null);

604 setHovIdx(null);

605 setPlaying(true);

606 } else setPlaying(p => !p);

607 }

608 };

609 window.addEventListener('keydown', onKey);

610 return () => window.removeEventListener('keydown', onKey);

611 }, []);

612 const pct = totalTokens / MAX * 100;

613 const barColor = pct > 75 ? '#D97757' : pct > 50 ? '#B8860B' : '#558A42';

614 const activeIdx = selIdx !== null ? selIdx : hovIdx;

615 const hovEvent = activeIdx !== null ? visible[activeIdx] : null;

616 useEffect(() => {

617 if (detailRef.current) detailRef.current.scrollTop = 0;

618 }, [hovEvent]);

619 const focusT = hovEvent ? hovEvent.t : time;

620 const takeaway = isCompacted ? 'Compaction replaces the conversation with a structured summary. System prompt, CLAUDE.md, memory, and MCP tools reload automatically. The skill listing is the one exception. Only skills you actually invoked are preserved.' : focusT < STARTUP_END ? 'A lot loads before you type anything. CLAUDE.md, memory, skills, and MCP tools are all in context before your first prompt.' : focusT < 0.28 ? "Your prompt is tiny compared to what's already loaded. Most of Claude's context is project knowledge, not your words." : focusT < 0.50 ? 'Each file Claude reads grows the context. Path-scoped rules load automatically alongside matching files.' : focusT < 0.71 ? 'Hooks fire automatically on tool events. Output reaches Claude via additionalContext JSON. Exit code 2 surfaces stderr to Claude. Plain stdout on exit 0 goes to the debug log, not the transcript.' : focusT < 0.79 ? 'Follow-up questions keep building on the same context. Everything from earlier is still there.' : focusT < 0.87 ? "The subagent works in its own separate context window. None of its file reads touch yours. Only the final summary comes back." : focusT < 0.88 ? 'Bang commands run in your shell and prefix the output to your next message. Useful for grounding Claude in command results without it running them.' : focusT < 0.90 ? 'User-only skills stay out of context entirely until you invoke them. The skill index at startup only lists skills Claude can call on its own.' : '/compact summarizes the conversation to free space while keeping key information. In a real session, run it when context starts affecting performance or before a long new task.';

621 const terminalView = isCompacted ? 'A "Conversation compacted" message. The summarization happens silently.' : focusT < STARTUP_END ? 'The input box, waiting for your first message. Everything above loads silently before you type anything.' : focusT < 0.28 ? 'Your prompt. Claude hasn\'t started working yet.' : focusT < 0.52 ? 'Your prompt and "Reading files...". Rules show as one-line "Loaded" notices, not their content.' : focusT < 0.72 ? "Claude's response and file diffs. Hooks fire silently. Tool output like npm test shows as a brief summary, not the full content." : focusT < 0.79 ? 'Your follow-up prompt.' : focusT < 0.86 ? "A brief notice that a subagent is working, then its result. You don't see the subagent's individual file reads." : focusT < 0.90 ? "Claude's response, your git status output, and the commit-push skill running." : 'Your full conversation. /compact is available to run.';

622 const mono = 'var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace)';

623 const renderWithCode = s => s.split('`').map((part, i) => i % 2 === 1 ? <code key={i} style={{

624 fontFamily: mono,

625 fontSize: '0.92em',

626 background: 'var(--cw-track)',

627 padding: '1px 4px',

628 borderRadius: 3

629 }}>{part}</code> : part);

630 if (!mounted) return null;

631 return <>

632 <div className="cw-mobile-fallback">

633 This interactive timeline works best on a larger screen. See <a href="#what-the-timeline-shows" style={{

634 color: '#D97757'

635 }}>the written breakdown below</a> for the same concepts.

636 </div>

637 <div className="cw-root" ref={rootRef} onClickCapture={() => setHasInteracted(true)} style={isFullscreen ? {

638 height: '100vh',

639 borderRadius: 0,

640 display: 'flex',

641 flexDirection: 'column'

642 } : {}}>

643 <style>{`

644 .cw-root {

645 --cw-bg: #FAFAF8;

646 --cw-text: #1A1918;

647 --cw-text-2: #3D3C38;

648 --cw-text-3: #5E5D59;

649 --cw-text-dim: #6E6C64;

650 --cw-text-faint: #8A8880;

651 --cw-surface: rgba(0,0,0,0.025);

652 --cw-surface-2: rgba(0,0,0,0.04);

653 --cw-border: rgba(0,0,0,0.08);

654 --cw-track: rgba(0,0,0,0.04);

655 --cw-hover: rgba(0,0,0,0.04);

656 --cw-rail: rgba(0,0,0,0.08);

657 --cw-scrollbar: rgba(0,0,0,0.22);

658 background: var(--cw-bg);

659 border-radius: 12px;

660 overflow: hidden;

661 font-family: var(--font-sans, -apple-system, BlinkMacSystemFont, sans-serif);

662 color: var(--cw-text);

663 border: 1px solid var(--cw-border);

664 }

665 .dark .cw-root {

666 --cw-bg: #111110;

667 --cw-text: #E8E6DC;

668 --cw-text-2: #B8B6AE;

669 --cw-text-3: #9C9A92;

670 --cw-text-dim: #8A8880;

671 --cw-text-faint: #6E6C64;

672 --cw-surface: rgba(255,255,255,0.02);

673 --cw-surface-2: rgba(255,255,255,0.015);

674 --cw-border: rgba(255,255,255,0.06);

675 --cw-track: rgba(255,255,255,0.03);

676 --cw-hover: rgba(255,255,255,0.04);

677 --cw-rail: rgba(255,255,255,0.04);

678 --cw-scrollbar: rgba(255,255,255,0.18);

679 }

680 .cw-scroll::-webkit-scrollbar { width: 6px; }

681 .cw-scroll::-webkit-scrollbar-track { background: transparent; }

682 .cw-scroll::-webkit-scrollbar-thumb { background: var(--cw-scrollbar); border-radius: 3px; }

683 @keyframes cw-blink { 50% { opacity: 0; } }

684 @keyframes cw-fadein { from { opacity: 0; transform: translateY(-4px); } to { opacity: 1; transform: translateY(0); } }

685 .cw-compacted-row { animation: cw-fadein 0.3s ease-out backwards; }

686 .cw-mobile-fallback { display: none; padding: 14px 16px; border-radius: 8px; font-size: 14px; border: 1px solid rgba(0,0,0,0.1); background: rgba(0,0,0,0.03); }

687 .dark .cw-mobile-fallback { border-color: rgba(255,255,255,0.15); background: rgba(255,255,255,0.04); }

688 @media (max-width: 700px) {

689 .cw-root { display: none !important; }

690 .cw-mobile-fallback { display: block; }

691 }

692 `}</style>

10 693 

11## O que a linha do tempo mostra694 {}

695 <div style={{

696 padding: '16px 20px 12px',

697 display: 'flex',

698 alignItems: 'flex-end',

699 gap: 24

700 }}>

701 <div style={{

702 flex: 1,

703 minWidth: 0

704 }}>

705 <div style={{

706 fontSize: 18,

707 fontWeight: 600,

708 letterSpacing: -0.3,

709 lineHeight: 1

710 }}>

711 Explore the context window

712 </div>

713 <div style={{

714 fontSize: 14,

715 color: 'var(--cw-text-dim)',

716 marginTop: 4

717 }}>

718 A simulated session showing what enters context and what it costs

719 </div>

720 </div>

721 <div style={{

722 textAlign: 'right',

723 flexShrink: 0

724 }}>

725 <div style={{

726 fontFamily: mono,

727 fontSize: 20,

728 fontWeight: 600,

729 color: barColor,

730 letterSpacing: -0.5,

731 lineHeight: 1

732 }}>

733 ~{fmt(totalTokens)}<span style={{

734 fontSize: 15,

735 fontWeight: 500,

736 marginLeft: 4

737 }}>tokens</span>

738 </div>

739 <div style={{

740 fontFamily: mono,

741 fontSize: 13,

742 color: 'var(--cw-text-dim)',

743 marginTop: 2

744 }} title="Token counts are illustrative. Actual values vary with your CLAUDE.md size, MCP servers, and file lengths.">

745 / {fmt(MAX)} · illustrative

746 </div>

747 </div>

748 </div>

749 

750 {}

751 <div style={{

752 padding: '0 20px'

753 }}>

754 <div style={{

755 height: 4,

756 borderRadius: 2,

757 background: 'var(--cw-track)',

758 overflow: 'hidden',

759 marginBottom: 6

760 }}>

761 <div style={{

762 width: pct + '%',

763 height: '100%',

764 background: barColor,

765 transition: 'width 0.6s cubic-bezier(0.4, 0, 0.2, 1), background 0.3s'

766 }} />

767 </div>

768 <div style={{

769 height: 28,

770 borderRadius: 5,

771 background: 'var(--cw-track)',

772 border: '1px solid var(--cw-border)',

773 overflow: 'hidden',

774 display: 'flex'

775 }}>

776 {blocks.map((b, i) => {

777 const w = Math.max(b.tokens / MAX * 100, 0.15);

778 const isHov = b.visIdx === activeIdx;

779 const catMatch = hovCat && b.color === hovCat;

780 const dimmed = hovCat ? !catMatch : activeIdx !== null && !isHov;

781 return <div key={b.id} onMouseEnter={() => setHovIdx(b.visIdx)} onMouseLeave={() => setHovIdx(null)} onClick={() => setSelIdx(selIdx === b.visIdx ? null : b.visIdx)} style={{

782 width: w + '%',

783 height: '100%',

784 background: b.color,

785 opacity: isHov || catMatch ? 1 : dimmed ? 0.25 : 0.65,

786 borderRight: i < blocks.length - 1 ? '0.5px solid var(--cw-border)' : 'none',

787 transition: 'opacity 0.15s',

788 cursor: 'pointer'

789 }} />;

790 })}

791 </div>

792 <div style={{

793 display: 'flex',

794 gap: 12,

795 marginTop: 6,

796 flexWrap: 'wrap',

797 justifyContent: 'space-between'

798 }}>

799 <div style={{

800 display: 'flex',

801 gap: 12,

802 flexWrap: 'wrap'

803 }}>

804 {LEGEND.map(x => {

805 const active = hovCat === x.c;

806 return <div key={x.l} onMouseEnter={() => setHovCat(x.c)} onMouseLeave={() => setHovCat(null)} style={{

807 display: 'flex',

808 alignItems: 'center',

809 gap: 4,

810 padding: '2px 6px',

811 borderRadius: 4,

812 cursor: 'pointer',

813 background: active ? 'var(--cw-hover)' : 'transparent',

814 transition: 'background 0.1s'

815 }}>

816 <div style={{

817 width: 6,

818 height: 6,

819 borderRadius: 1.5,

820 background: x.c,

821 opacity: active ? 1 : 0.7

822 }} />

823 <span style={{

824 fontSize: 12,

825 color: active ? 'var(--cw-text)' : 'var(--cw-text-dim)'

826 }}>{x.l}</span>

827 </div>;

828 })}

829 </div>

830 <div style={{

831 display: 'flex',

832 gap: 6,

833 alignItems: 'center',

834 fontSize: 12,

835 color: 'var(--cw-text-dim)'

836 }}>

837 <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="#558A42" strokeWidth="2.5">

838 <path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z" /><circle cx="12" cy="12" r="3" />

839 </svg>

840 <span>= appears in your terminal</span>

841 </div>

842 </div>

843 </div>

844 

845 {}

846 <div style={{

847 display: 'flex',

848 padding: '14px 20px 0',

849 gap: 16,

850 height: isFullscreen ? 'calc(100vh - 240px)' : 420

851 }}>

852 

853 {}

854 <div ref={scrollRef} className="cw-scroll" style={{

855 flex: 1,

856 minWidth: 0,

857 overflowY: 'auto',

858 paddingRight: 8,

859 scrollBehavior: 'smooth'

860 }}>

861 {visible.length === 0 && !playing && <div style={{

862 height: '100%',

863 display: 'flex',

864 flexDirection: 'column',

865 alignItems: 'center',

866 justifyContent: 'center',

867 gap: 16

868 }}>

869 <div style={{

870 fontFamily: mono,

871 fontSize: 16,

872 color: 'var(--cw-text-dim)',

873 display: 'flex',

874 alignItems: 'center',

875 gap: 8

876 }}>

877 <span style={{

878 color: 'var(--cw-text-faint)'

879 }}>$</span>

880 <span>claude</span>

881 <span style={{

882 display: 'inline-block',

883 width: 8,

884 height: 16,

885 background: 'var(--cw-text-dim)',

886 opacity: 0.5,

887 animation: 'cw-blink 1s step-end infinite'

888 }} />

889 </div>

890 <button onClick={() => setPlaying(true)} style={{

891 padding: '10px 20px',

892 borderRadius: 8,

893 border: '1px solid rgba(217,119,87,0.3)',

894 background: 'rgba(217,119,87,0.08)',

895 color: '#D97757',

896 fontSize: 15,

897 fontWeight: 600,

898 cursor: 'pointer',

899 display: 'flex',

900 alignItems: 'center',

901 gap: 8

902 }}>

903 <span>▶</span>

904 <span>Start session</span>

905 </button>

906 <div style={{

907 fontSize: 13,

908 color: 'var(--cw-text-faint)',

909 maxWidth: 280,

910 textAlign: 'center',

911 lineHeight: 1.5

912 }}>

913 Watch what loads into context, from the moment you run <code style={{

914 fontFamily: mono

915 }}>claude</code> through a full conversation.

916 </div>

917 </div>}

918 {isCompacted && <div style={{

919 marginBottom: 10,

920 padding: '10px 12px',

921 borderRadius: 6,

922 background: 'rgba(217,119,87,0.05)',

923 border: '1px solid rgba(217,119,87,0.15)'

924 }}>

925 <div style={{

926 fontSize: 13,

927 fontWeight: 600,

928 color: '#D97757',

929 marginBottom: 3

930 }}>

931 After /compact

932 </div>

933 <div style={{

934 fontSize: 13,

935 color: 'var(--cw-text-3)',

936 lineHeight: 1.5,

937 fontFamily: mono

938 }}>

939 {fmt(preCompactTotal)} → {fmt(totalTokens)} tokens · freed {fmt(preCompactTotal - totalTokens)}

940 </div>

941 <div style={{

942 fontSize: 13,

943 color: 'var(--cw-text-dim)',

944 lineHeight: 1.5,

945 marginTop: 4

946 }}>

947 This is what's left in context: startup content, which lives outside the message history and reloads after compaction, plus a structured summary of the entire conversation. Skill descriptions don't reload.

948 </div>

949 </div>}

950 {time > 0 && visible.length > 0 && <div style={{

951 fontSize: 12,

952 fontWeight: 700,

953 color: 'var(--cw-text-faint)',

954 textTransform: 'uppercase',

955 letterSpacing: 0.6,

956 marginBottom: 6,

957 paddingLeft: 28

958 }}>

959 {isCompacted ? 'Reloaded after compact' : 'Before you type anything'}

960 </div>}

961 

962 {time > 0 && visible.map((evt, i) => {

963 const meta = KIND_META[evt.kind];

964 const isHov = hovIdx === i;

965 const prevKind = i > 0 ? visible[i - 1].kind : null;

966 const isSub = evt.kind === 'sub';

967 const enteringSubagent = isSub && prevKind !== 'sub';

968 const leavingSubagent = prevKind === 'sub' && !isSub;

969 let showPhase = null;

970 if (evt.kind === 'user' && prevKind !== 'user') showPhase = 'You'; else if (evt.kind === 'claude' && prevKind === 'user') showPhase = 'Claude works'; else if (evt.label === 'Conversation summary') showPhase = 'Summarized by /compact';

971 const isNewRow = isCompacted && !(evt.kind === 'auto' && evt.t < STARTUP_END);

972 return <div key={evt.label + evt.t} className={isNewRow ? 'cw-compacted-row' : ''} style={isNewRow ? {

973 animationDelay: `${i * 60}ms`

974 } : {}}>

975 {showPhase && <div style={{

976 fontSize: 12,

977 fontWeight: 700,

978 color: 'var(--cw-text-faint)',

979 textTransform: 'uppercase',

980 letterSpacing: 0.6,

981 marginTop: 14,

982 marginBottom: 6,

983 paddingLeft: 28

984 }}>

985 {showPhase}

986 </div>}

987 {enteringSubagent && <div style={{

988 marginLeft: 28,

989 marginTop: 6,

990 marginBottom: 2,

991 paddingLeft: 10,

992 borderLeft: '2px solid rgba(155,123,196,0.4)',

993 fontSize: 12,

994 fontWeight: 600,

995 color: '#9B7BC4',

996 textTransform: 'uppercase',

997 letterSpacing: 0.5

998 }}>

999 Subagent's separate context window

1000 </div>}

1001 {leavingSubagent && <div style={{

1002 marginLeft: 28,

1003 marginBottom: 6,

1004 paddingLeft: 10,

1005 paddingBottom: 6,

1006 borderLeft: '2px solid rgba(155,123,196,0.4)',

1007 fontSize: 12,

1008 color: 'var(--cw-text-dim)',

1009 fontFamily: mono

1010 }}>

1011 ↓ {fmt(subTotal)} tokens stayed in subagent's context · only the summary returns

1012 </div>}

1013 <div onMouseEnter={() => setHovIdx(i)} onMouseLeave={() => setHovIdx(null)} onClick={() => setSelIdx(selIdx === i ? null : i)} style={{

1014 display: 'flex',

1015 alignItems: 'flex-start',

1016 borderRadius: 6,

1017 cursor: 'pointer',

1018 background: selIdx === i || isHov ? 'var(--cw-hover)' : 'transparent',

1019 outline: selIdx === i ? '1px solid rgba(217,119,87,0.4)' : 'none',

1020 opacity: hovCat && evt.color !== hovCat ? 0.35 : 1,

1021 transition: 'background 0.1s, opacity 0.15s',

1022 marginLeft: isSub ? 28 : 0,

1023 paddingLeft: isSub ? 10 : 0,

1024 borderLeft: isSub ? '2px solid rgba(155,123,196,0.4)' : 'none'

1025 }}>

1026 <div style={{

1027 width: 28,

1028 display: 'flex',

1029 flexDirection: 'column',

1030 alignItems: 'center',

1031 paddingTop: 8,

1032 flexShrink: 0

1033 }}>

1034 <div style={{

1035 width: evt.kind === 'user' || evt.kind === 'compact' ? 10 : 7,

1036 height: evt.kind === 'user' || evt.kind === 'compact' ? 10 : 7,

1037 borderRadius: '50%',

1038 background: evt.color,

1039 opacity: isHov ? 1 : 0.6,

1040 transition: 'opacity 0.15s',

1041 boxShadow: isHov ? `0 0 8px ${evt.color}40` : 'none'

1042 }} />

1043 {i < visible.length - 1 && <div style={{

1044 width: 1.5,

1045 flex: 1,

1046 background: 'var(--cw-rail)',

1047 marginTop: 2,

1048 minHeight: 6

1049 }} />}

1050 </div>

1051 <div style={{

1052 flex: 1,

1053 minWidth: 0,

1054 padding: '5px 10px 5px 4px',

1055 display: 'flex',

1056 alignItems: 'center',

1057 gap: 8

1058 }}>

1059 <span style={{

1060 fontSize: 12,

1061 fontWeight: 600,

1062 padding: '1px 5px',

1063 borderRadius: 3,

1064 background: meta.badgeBg,

1065 color: meta.badgeColor,

1066 flexShrink: 0,

1067 fontFamily: mono

1068 }}>

1069 {meta.badge}

1070 </span>

1071 <span style={{

1072 fontSize: 15,

1073 fontFamily: mono,

1074 color: isHov ? 'var(--cw-text)' : evt.kind === 'user' ? '#558A42' : evt.kind === 'auto' ? 'var(--cw-text-dim)' : 'var(--cw-text-2)',

1075 flex: 1,

1076 minWidth: 0,

1077 overflow: 'hidden',

1078 textOverflow: 'ellipsis',

1079 whiteSpace: 'nowrap',

1080 fontWeight: evt.kind === 'user' ? 550 : 400

1081 }}>

1082 {evt.label}

1083 </span>

1084 {evt.tokens > 0 && <span style={{

1085 fontSize: 12,

1086 fontFamily: mono,

1087 color: 'var(--cw-text-faint)',

1088 flexShrink: 0

1089 }}>

1090 +{fmt(evt.tokens)}

1091 </span>}

1092 {evt.subTokens > 0 && <span style={{

1093 fontSize: 12,

1094 fontFamily: mono,

1095 color: '#9B7BC4',

1096 flexShrink: 0,

1097 opacity: 0.6

1098 }}>

1099 +{fmt(evt.subTokens)}

1100 </span>}

1101 {evt.tokens > 0 && <div style={{

1102 width: 50,

1103 height: 5,

1104 borderRadius: 2,

1105 background: 'var(--cw-track)',

1106 flexShrink: 0,

1107 overflow: 'hidden'

1108 }}>

1109 <div style={{

1110 width: Math.min(evt.tokens / 5000 * 100, 100) + '%',

1111 height: '100%',

1112 background: evt.color,

1113 opacity: isHov ? 0.8 : 0.4,

1114 transition: 'opacity 0.15s'

1115 }} />

1116 </div>}

1117 <span style={{

1118 width: 14,

1119 flexShrink: 0,

1120 display: 'flex',

1121 justifyContent: 'center'

1122 }} title={VIS_META[evt.vis].label}>

1123 {evt.vis !== 'hidden' && <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke={evt.vis === 'full' ? '#558A42' : 'currentColor'} style={{

1124 color: 'var(--cw-text-faint)',

1125 opacity: evt.vis === 'full' ? 1 : 0.5

1126 }} strokeWidth="2">

1127 <path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z" /><circle cx="12" cy="12" r="3" />

1128 </svg>}

1129 </span>

1130 </div>

1131 </div>

1132 </div>;

1133 })}

1134 

1135 {activeGate && (activeGate.kind === 'prompt' || activeGate.kind === 'bang' || activeGate.kind === 'slash') && <div style={{

1136 paddingLeft: 28,

1137 marginTop: 12,

1138 paddingRight: 8

1139 }}>

1140 <div style={{

1141 fontSize: 11,

1142 fontWeight: 600,

1143 color: '#6BA656',

1144 fontFamily: mono,

1145 textTransform: 'uppercase',

1146 letterSpacing: 0.5,

1147 marginBottom: 4,

1148 paddingLeft: 2

1149 }}>

1150 You type in your terminal

1151 </div>

1152 <div style={{

1153 display: 'flex',

1154 alignItems: 'flex-start',

1155 gap: 8,

1156 padding: '10px 12px',

1157 borderRadius: 6,

1158 background: 'rgba(85,138,66,0.06)',

1159 border: '1px solid rgba(85,138,66,0.2)'

1160 }}>

1161 <span style={{

1162 color: '#558A42',

1163 fontSize: 15,

1164 fontFamily: mono,

1165 flexShrink: 0

1166 }}>❯</span>

1167 <span style={{

1168 fontSize: 15,

1169 fontFamily: mono,

1170 color: 'var(--cw-text-2)',

1171 flex: 1,

1172 lineHeight: 1.5

1173 }}>

1174 {activeGate.text}

1175 <span style={{

1176 display: 'inline-block',

1177 width: 7,

1178 height: 13,

1179 marginLeft: 2,

1180 background: '#558A42',

1181 opacity: 0.5,

1182 verticalAlign: 'middle',

1183 animation: 'cw-blink 1s step-end infinite'

1184 }} />

1185 </span>

1186 <button onClick={sendPrompt} style={{

1187 padding: '5px 12px',

1188 borderRadius: 5,

1189 border: 'none',

1190 background: '#558A42',

1191 color: '#fff',

1192 fontSize: 13,

1193 fontWeight: 600,

1194 cursor: 'pointer',

1195 flexShrink: 0

1196 }}>

1197 {activeGate.kind === 'prompt' ? 'Send ↵' : 'Run ↵'}

1198 </button>

1199 </div>

1200 </div>}

1201 {activeGate && activeGate.kind === 'compact' && <div style={{

1202 paddingLeft: 28,

1203 marginTop: 12,

1204 paddingRight: 8

1205 }}>

1206 <div style={{

1207 padding: '12px 14px',

1208 borderRadius: 6,

1209 background: 'rgba(217,119,87,0.06)',

1210 border: '1px solid rgba(217,119,87,0.25)'

1211 }}>

1212 <div style={{

1213 fontSize: 13,

1214 color: 'var(--cw-text-3)',

1215 marginBottom: 8,

1216 lineHeight: 1.5

1217 }}>

1218 Context is at <span style={{

1219 fontFamily: mono,

1220 fontWeight: 600,

1221 color: barColor

1222 }}>{fmt(totalTokens)} tokens</span>.

1223 Run <code style={{

1224 fontFamily: mono,

1225 background: 'var(--cw-track)',

1226 padding: '1px 4px',

1227 borderRadius: 3

1228 }}>/compact</code> to

1229 summarize older exchanges and free space for more work.

1230 </div>

1231 <div style={{

1232 display: 'flex',

1233 alignItems: 'center',

1234 gap: 8

1235 }}>

1236 <span style={{

1237 color: '#D97757',

1238 fontSize: 15,

1239 fontFamily: mono

1240 }}>❯</span>

1241 <span style={{

1242 fontSize: 15,

1243 fontFamily: mono,

1244 color: 'var(--cw-text-2)',

1245 flex: 1

1246 }}>

1247 {activeGate.text}

1248 </span>

1249 <button onClick={sendPrompt} style={{

1250 padding: '5px 12px',

1251 borderRadius: 5,

1252 border: 'none',

1253 background: '#D97757',

1254 color: '#fff',

1255 fontSize: 13,

1256 fontWeight: 600,

1257 cursor: 'pointer',

1258 flexShrink: 0

1259 }}>

1260 Run ↵

1261 </button>

1262 </div>

1263 </div>

1264 </div>}

1265 </div>

1266 

1267 {}

1268 <div style={{

1269 width: 300,

1270 flexShrink: 0,

1271 display: 'flex',

1272 flexDirection: 'column'

1273 }}>

1274 <div ref={detailRef} className="cw-scroll" style={{

1275 padding: '14px 16px',

1276 borderRadius: 10,

1277 background: 'var(--cw-surface)',

1278 border: '1px solid var(--cw-border)',

1279 flex: 1,

1280 minHeight: 0,

1281 overflowY: 'auto',

1282 display: 'flex',

1283 flexDirection: 'column',

1284 gap: 10

1285 }}>

1286 {hovEvent ? <div>

1287 <div style={{

1288 display: 'flex',

1289 alignItems: 'center',

1290 gap: 8,

1291 marginBottom: 8

1292 }}>

1293 <div style={{

1294 width: 10,

1295 height: 10,

1296 borderRadius: 3,

1297 background: hovEvent.color,

1298 opacity: 0.8

1299 }} />

1300 <span style={{

1301 fontSize: 16,

1302 fontWeight: 600

1303 }}>{hovEvent.label}</span>

1304 </div>

1305 <div style={{

1306 display: 'flex',

1307 width: 'fit-content',

1308 padding: '3px 8px',

1309 borderRadius: 4,

1310 marginBottom: 8,

1311 background: KIND_META[hovEvent.kind].badgeBg

1312 }}>

1313 <span style={{

1314 fontSize: 12,

1315 fontWeight: 600,

1316 color: KIND_META[hovEvent.kind].badgeColor

1317 }}>

1318 {KIND_META[hovEvent.kind].detail}

1319 </span>

1320 </div>

1321 {hovEvent.tokens > 0 && <div style={{

1322 fontSize: 14,

1323 fontFamily: mono,

1324 color: 'var(--cw-text-dim)',

1325 marginBottom: 6

1326 }}>

1327 {fmt(hovEvent.tokens)} tokens

1328 </div>}

1329 {hovEvent.subTokens > 0 && <div style={{

1330 fontSize: 14,

1331 fontFamily: mono,

1332 color: '#9B7BC4',

1333 marginBottom: 6

1334 }}>

1335 {fmt(hovEvent.subTokens)} tokens in the subagent's context

1336 </div>}

1337 <p style={{

1338 fontSize: 15,

1339 color: 'var(--cw-text-3)',

1340 lineHeight: 1.55,

1341 margin: 0

1342 }}>

1343 {renderWithCode(hovEvent.desc)}

1344 </p>

1345 <div style={{

1346 marginTop: 10,

1347 padding: '8px 10px',

1348 borderRadius: 6,

1349 background: hovEvent.vis === 'full' ? 'rgba(85,138,66,0.08)' : 'var(--cw-surface-2)',

1350 border: '1px solid ' + (hovEvent.vis === 'full' ? 'rgba(85,138,66,0.2)' : 'var(--cw-border)')

1351 }}>

1352 <div style={{

1353 display: 'flex',

1354 alignItems: 'center',

1355 gap: 6,

1356 marginBottom: 3

1357 }}>

1358 <span style={{

1359 fontSize: 13,

1360 color: hovEvent.vis === 'full' ? '#558A42' : 'var(--cw-text-dim)'

1361 }}>

1362 {hovEvent.vis === 'full' ? '●' : hovEvent.vis === 'brief' ? '◐' : '○'}

1363 </span>

1364 <span style={{

1365 fontSize: 12,

1366 fontWeight: 600,

1367 color: 'var(--cw-text-2)'

1368 }}>

1369 {VIS_META[hovEvent.vis].label}

1370 </span>

1371 </div>

1372 <div style={{

1373 fontSize: 13,

1374 color: 'var(--cw-text-dim)',

1375 lineHeight: 1.4

1376 }}>

1377 {VIS_META[hovEvent.vis].sub}

1378 </div>

1379 </div>

1380 {hovEvent.tip && <div style={{

1381 marginTop: 10,

1382 padding: '8px 10px',

1383 borderRadius: 6,

1384 background: 'rgba(85,138,66,0.06)',

1385 border: '1px solid rgba(85,138,66,0.15)'

1386 }}>

1387 <div style={{

1388 fontSize: 12,

1389 fontWeight: 600,

1390 color: '#558A42',

1391 marginBottom: 3,

1392 display: 'flex',

1393 alignItems: 'center',

1394 gap: 4

1395 }}>

1396 <span>💡</span> Save context

1397 </div>

1398 <div style={{

1399 fontSize: 13,

1400 color: 'var(--cw-text-3)',

1401 lineHeight: 1.5

1402 }}>

1403 {renderWithCode(hovEvent.tip)}

1404 </div>

1405 </div>}

1406 {hovEvent.link && <a href={hovEvent.link} style={{

1407 display: 'inline-block',

1408 marginTop: 10,

1409 fontSize: 13,

1410 color: '#D97757',

1411 textDecoration: 'none',

1412 borderBottom: '1px solid rgba(217,119,87,0.3)'

1413 }}>

1414 Learn more →

1415 </a>}

1416 </div> : <div style={{

1417 display: 'flex',

1418 flexDirection: 'column',

1419 alignItems: 'center',

1420 textAlign: 'center',

1421 gap: 4,

1422 padding: '12px 0 4px'

1423 }}>

1424 <div style={{

1425 fontSize: 22,

1426 opacity: 0.2

1427 }}>👁</div>

1428 <div style={{

1429 fontSize: 14,

1430 fontWeight: 500,

1431 color: 'var(--cw-text-dim)'

1432 }}>Hover or click any event</div>

1433 <div style={{

1434 fontSize: 12,

1435 color: 'var(--cw-text-faint)',

1436 lineHeight: 1.4,

1437 maxWidth: 200

1438 }}>

1439 Hover to preview. Click to pin so you can scroll.

1440 </div>

1441 </div>}

1442 

1443 <div style={{

1444 padding: '10px 12px',

1445 borderRadius: 8,

1446 background: 'rgba(217,119,87,0.05)',

1447 border: '1px solid rgba(217,119,87,0.12)'

1448 }}>

1449 <div style={{

1450 fontSize: 11,

1451 fontWeight: 700,

1452 color: '#D97757',

1453 textTransform: 'uppercase',

1454 letterSpacing: 0.5,

1455 marginBottom: 3

1456 }}>

1457 Key takeaway

1458 </div>

1459 <div style={{

1460 fontSize: 13,

1461 color: 'var(--cw-text-3)',

1462 lineHeight: 1.5

1463 }}>

1464 {takeaway}

1465 </div>

1466 </div>

1467 

1468 <div style={{

1469 padding: '10px 12px',

1470 borderRadius: 8,

1471 background: 'var(--cw-surface-2)',

1472 border: '1px solid var(--cw-border)'

1473 }}>

1474 <div style={{

1475 fontSize: 11,

1476 fontWeight: 700,

1477 color: 'var(--cw-text-dim)',

1478 textTransform: 'uppercase',

1479 letterSpacing: 0.5,

1480 marginBottom: 3

1481 }}>

1482 In your terminal you see

1483 </div>

1484 <div style={{

1485 fontSize: 13,

1486 color: 'var(--cw-text-3)',

1487 lineHeight: 1.5

1488 }}>

1489 {terminalView}

1490 </div>

1491 </div>

1492 </div>

1493 </div>

1494 </div>

1495 

1496 {}

1497 <div style={{

1498 padding: '10px 20px 14px',

1499 display: 'flex',

1500 alignItems: 'center',

1501 gap: 10

1502 }}>

1503 <button aria-label={time >= 1 ? 'Restart' : activeGate ? 'Continue' : playing ? 'Pause' : 'Play'} onClick={() => {

1504 if (time >= 1) {

1505 setTime(0);

1506 setGatesPassed(0);

1507 setSelIdx(null);

1508 setHovIdx(null);

1509 setPlaying(true);

1510 } else if (activeGate) sendPrompt(); else setPlaying(!playing);

1511 }} style={{

1512 width: 30,

1513 height: 30,

1514 borderRadius: 6,

1515 border: 'none',

1516 background: 'rgba(217,119,87,0.1)',

1517 color: '#D97757',

1518 cursor: 'pointer',

1519 fontSize: 15,

1520 fontWeight: 700,

1521 display: 'flex',

1522 alignItems: 'center',

1523 justifyContent: 'center'

1524 }}>

1525 {time >= 1 ? '↺' : playing ? '⏸' : '▶'}

1526 </button>

1527 <div style={{

1528 flex: 1,

1529 height: 3,

1530 borderRadius: 2,

1531 background: 'var(--cw-track)',

1532 overflow: 'hidden'

1533 }}>

1534 <div style={{

1535 width: time * 100 + '%',

1536 height: '100%',

1537 background: '#D97757',

1538 transition: 'width 0.1s linear'

1539 }} />

1540 </div>

1541 <span style={{

1542 fontSize: 12,

1543 fontFamily: mono,

1544 color: 'var(--cw-text-faint)',

1545 minWidth: 30

1546 }}>

1547 {Math.round(time * 100)}%

1548 </span>

1549 <button onClick={toggleFullscreen} aria-label={isFullscreen ? 'Exit fullscreen' : 'Enter fullscreen'} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'} style={{

1550 width: 28,

1551 height: 28,

1552 borderRadius: 6,

1553 border: '1px solid var(--cw-border)',

1554 background: 'var(--cw-surface)',

1555 color: 'var(--cw-text-dim)',

1556 cursor: 'pointer',

1557 fontSize: 15,

1558 flexShrink: 0,

1559 marginLeft: 4,

1560 display: 'flex',

1561 alignItems: 'center',

1562 justifyContent: 'center'

1563 }}>

1564 {isFullscreen ? '⤡' : '⛶'}

1565 </button>

1566 </div>

1567 </div>

1568 </>;

1569};

1570 

1571A janela de contexto do Claude Code contém tudo o que Claude sabe sobre sua sessão: suas instruções, os arquivos que lê, suas próprias respostas e conteúdo que nunca aparece em seu terminal. A linha do tempo abaixo mostra uma sessão completa do início até a compactação: o que é carregado antes de você digitar, o que cada leitura de arquivo, regra e hook adiciona conforme Claude trabalha, e como um subagent mantém leituras grandes fora de seu contexto. Veja [o detalhamento escrito](#what-the-timeline-shows) para o mesmo conteúdo como uma lista.

1572 

1573<ContextWindow />

1574 

1575<h2 id="what-the-timeline-shows">

1576 O que a linha do tempo mostra

1577</h2>

12 1578 

13A sessão percorre um fluxo realista com contagens de tokens representativas:1579A sessão percorre um fluxo realista com contagens de tokens representativas:

14 1580 


17* **O prompt de acompanhamento**: um [subagent](/pt/sub-agents) lida com a pesquisa em sua própria janela de contexto separada, então as leituras de arquivo grandes ficam fora da sua. Apenas o resumo e um pequeno trailer de metadados voltam.1583* **O prompt de acompanhamento**: um [subagent](/pt/sub-agents) lida com a pesquisa em sua própria janela de contexto separada, então as leituras de arquivo grandes ficam fora da sua. Apenas o resumo e um pequeno trailer de metadados voltam.

18* **No final**: `/compact` substitui a conversa por um resumo estruturado. A maioria do conteúdo de inicialização é recarregada automaticamente; a tabela abaixo mostra o que acontece com cada mecanismo.1584* **No final**: `/compact` substitui a conversa por um resumo estruturado. A maioria do conteúdo de inicialização é recarregada automaticamente; a tabela abaixo mostra o que acontece com cada mecanismo.

19 1585 

20## O que sobrevive à compactação1586<h2 id="what-survives-compaction">

1587 O que sobrevive à compactação

1588</h2>

21 1589 

22Quando uma sessão longa é compactada, Claude Code resume o histórico de conversa para caber na janela de contexto. O que acontece com suas instruções depende de como foram carregadas:1590Quando uma sessão longa é compactada, Claude Code resume o histórico de conversa para caber na janela de contexto. O que acontece com suas instruções depende de como foram carregadas:

23 1591 


35 1603 

36Corpos de skills são re-injetados após compactação, mas skills grandes são truncados para caber no limite por skill, e os skills invocados mais antigos são descartados uma vez que o orçamento total é excedido. O truncamento mantém o início do arquivo, então coloque as instruções mais importantes perto do topo de `SKILL.md`.1604Corpos de skills são re-injetados após compactação, mas skills grandes são truncados para caber no limite por skill, e os skills invocados mais antigos são descartados uma vez que o orçamento total é excedido. O truncamento mantém o início do arquivo, então coloque as instruções mais importantes perto do topo de `SKILL.md`.

37 1605 

38## Verifique sua própria sessão1606<h2 id="when-your-context-fills-up">

1607 Quando sua janela de contexto se preenche

1608</h2>

1609 

1610Claude Code faz compactação automática conforme você se aproxima do limite, então uma janela de contexto cheia não encerra sua sessão. A passagem automática funciona da mesma forma que a etapa `/compact` na linha do tempo. Veja [Quando o contexto se preenche](/pt/how-claude-code-works#when-context-fills-up) para o que ela preserva.

1611 

1612Você também pode agir antes da passagem automática ser executada:

1613 

1614* **Compacte com um foco**: execute `/compact` com instruções, como `/compact focus on the auth bug fix`, antes de iniciar uma tarefa longa nova. O resumo mantém o que você escolhe em vez do que a passagem automática acha que é importante.

1615* **Limpe entre tarefas**: execute `/clear` ao mudar para trabalho não relacionado. Conversa antiga ocupa espaço dos arquivos que você precisa em seguida e custa tokens em cada mensagem.

1616* **Delegue leituras grandes**: envie pesquisa para um [subagent](/pt/sub-agents) para que o conteúdo do arquivo fique em sua janela de contexto, não na sua.

1617 

1618Se você precisar de uma janela maior em vez de uma conversa menor, Fable 5, Opus 4.6 e posteriores, e Sonnet 4.6 suportam uma janela de contexto de 1 milhão de tokens. Veja [Extended context](/pt/model-config#extended-context) para disponibilidade por plano e como selecionar uma variante de modelo `[1m]`. A compactação funciona da mesma forma no limite maior.

1619 

1620<h2 id="check-your-own-session">

1621 Verifique sua própria sessão

1622</h2>

39 1623 

40A visualização usa números representativos. Para ver seu uso real de contexto em qualquer ponto, execute `/context` para um detalhamento ao vivo por categoria com sugestões de otimização. Execute `/memory` para verificar quais arquivos CLAUDE.md e memória automática foram carregados na inicialização.1624A visualização usa números representativos. Para ver seu uso real de contexto em qualquer ponto, execute `/context` para um detalhamento ao vivo por categoria com sugestões de otimização. Execute `/memory` para verificar quais arquivos CLAUDE.md e memória automática foram carregados na inicialização.

41 1625 

42## Recursos relacionados1626<h2 id="related-resources">

1627 Recursos relacionados

1628</h2>

43 1629 

44Para cobertura mais profunda dos recursos mostrados na linha do tempo, veja estas páginas:1630Para cobertura mais profunda dos recursos mostrados na linha do tempo, veja estas páginas:

45 1631 

costs.md +4 −2

Details

35 35 

36Em um plano Pro, Max, Team ou Enterprise, `/usage` também mostra um detalhamento do que conta contra seus limites de plano. Ele atribui o uso recente a skills, subagents, plugins e servidores MCP individuais, cada um mostrado como uma porcentagem do total. Pressione `d` ou `w` para alternar entre as últimas 24 horas e os últimos 7 dias. As figuras são aproximadas e calculadas a partir do histórico de sessão local nesta máquina, portanto, o uso de outros dispositivos ou claude.ai não está incluído.36Em um plano Pro, Max, Team ou Enterprise, `/usage` também mostra um detalhamento do que conta contra seus limites de plano. Ele atribui o uso recente a skills, subagents, plugins e servidores MCP individuais, cada um mostrado como uma porcentagem do total. Pressione `d` ou `w` para alternar entre as últimas 24 horas e os últimos 7 dias. As figuras são aproximadas e calculadas a partir do histórico de sessão local nesta máquina, portanto, o uso de outros dispositivos ou claude.ai não está incluído.

37 37 

38Na [extensão do VS Code](/pt/vs-code#check-account-and-usage), o mesmo detalhamento aparece no diálogo Account & usage com um alternador Day e Week. Requer Claude Code v2.1.174 ou posterior.

39 

38<h2 id="managing-costs-for-teams">40<h2 id="managing-costs-for-teams">

39 Gerenciando custos para equipes41 Gerenciando custos para equipes

40</h2>42</h2>


85* Use Sonnet para colegas de equipe. Ele equilibra capacidade e custo para tarefas de coordenação.87* Use Sonnet para colegas de equipe. Ele equilibra capacidade e custo para tarefas de coordenação.

86* Mantenha equipes pequenas. Cada colega de equipe executa sua própria janela de contexto, portanto, o uso de tokens é aproximadamente proporcional ao tamanho da equipe.88* Mantenha equipes pequenas. Cada colega de equipe executa sua própria janela de contexto, portanto, o uso de tokens é aproximadamente proporcional ao tamanho da equipe.

87* Mantenha prompts de geração focados. Colegas de equipe carregam CLAUDE.md, servidores MCP e skills automaticamente, mas tudo no prompt de geração adiciona ao seu contexto desde o início.89* Mantenha prompts de geração focados. Colegas de equipe carregam CLAUDE.md, servidores MCP e skills automaticamente, mas tudo no prompt de geração adiciona ao seu contexto desde o início.

88* Limpe equipes quando o trabalho estiver concluído. Colegas de equipe ativos continuam consumindo tokens mesmo se ociosos.90* Desligue colegas de equipe quando o trabalho estiver concluído. Cada colega de equipe ativo continua consumindo tokens até sair ou a sessão terminar.

89* Equipes de agentes são desabilitadas por padrão. Defina `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` em seu [settings.json](/pt/settings) ou ambiente para habilitá-las. Veja [habilitar equipes de agentes](/pt/agent-teams#enable-agent-teams).91* Equipes de agentes são desabilitadas por padrão. Defina `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` em seu [settings.json](/pt/settings) ou ambiente para habilitá-las. Veja [habilitar equipes de agentes](/pt/agent-teams#enable-agent-teams).

90 92 

91<h2 id="reduce-token-usage">93<h2 id="reduce-token-usage">


196 Ajuste o pensamento estendido198 Ajuste o pensamento estendido

197</h3>199</h3>

198 200 

199O pensamento estendido é habilitado por padrão porque melhora significativamente o desempenho em tarefas complexas de planejamento e raciocínio. Tokens de pensamento são faturados como tokens de saída, e o orçamento padrão pode ser dezenas de milhares de tokens por solicitação dependendo do modelo. Para tarefas mais simples onde raciocínio profundo não é necessário, você pode reduzir custos baixando o [nível de esforço](/pt/model-config#adjust-effort-level) com `/effort` ou em `/model`, desabilitando pensamento em `/config`, ou baixando o orçamento com `MAX_THINKING_TOKENS=8000`.201O pensamento estendido é habilitado por padrão porque melhora significativamente o desempenho em tarefas complexas de planejamento e raciocínio. Tokens de pensamento são faturados como tokens de saída, e o orçamento padrão pode ser dezenas de milhares de tokens por solicitação dependendo do modelo. Para tarefas mais simples onde raciocínio profundo não é necessário, você pode reduzir custos baixando o [nível de esforço](/pt/model-config#adjust-effort-level) com `/effort` ou em `/model`, desabilitando pensamento em `/config`, ou, em modelos com um [orçamento de pensamento fixo](/pt/model-config#adaptive-reasoning-and-fixed-thinking-budgets), baixando o orçamento com `MAX_THINKING_TOKENS=8000`. Modelos de raciocínio adaptativo ignoram orçamentos diferentes de zero, portanto use níveis de esforço lá em vez disso. Desabilitar pensamento não está disponível no Fable 5, que sempre usa pensamento estendido.

200 202 

201<h3 id="delegate-verbose-operations-to-subagents">203<h3 id="delegate-verbose-operations-to-subagents">

202 Delegue operações verbosas para subagentes204 Delegue operações verbosas para subagentes

data-usage.md +3 −3

Details

62**Usuários comerciais (Team, Enterprise e API)**:62**Usuários comerciais (Team, Enterprise e API)**:

63 63 

64* Padrão: período de retenção de 30 dias64* Padrão: período de retenção de 30 dias

65* [Zero data retention](/pt/zero-data-retention): disponível para Claude Code no Claude for Enterprise. ZDR é habilitado por organização; cada nova organização deve ter ZDR habilitado separadamente pela sua equipe de conta65* [Zero data retention](/pt/zero-data-retention): disponível para Claude Code no Claude for Enterprise. ZDR não está incluído no plano Enterprise padrão; é habilitado por organização após sua equipe de conta confirmar a elegibilidade

66* Cache local: os clientes de Claude Code armazenam transcrições de sessão localmente em texto simples em `~/.claude/projects/` por 30 dias por padrão para permitir retomada de sessão. Ajuste o período com `cleanupPeriodDays`. Consulte [dados da aplicação](/pt/claude-directory#application-data) para saber o que é armazenado e como limpá-lo.66* Cache local: os clientes de Claude Code armazenam transcrições de sessão localmente em texto simples em `~/.claude/projects/` por 30 dias por padrão para permitir retomada de sessão. Ajuste o período com `cleanupPeriodDays`. Consulte [dados da aplicação](/pt/claude-directory#application-data) para saber o que é armazenado e como limpá-lo.

67 67 

68Você pode excluir sessões individuais de Claude Code na web a qualquer momento. Excluir uma sessão remove permanentemente os dados de evento da sessão. Para instruções sobre como excluir sessões, consulte [Excluir sessões](/pt/claude-code-on-the-web#delete-sessions).68Você pode excluir sessões individuais de Claude Code na web a qualquer momento. Excluir uma sessão remove permanentemente os dados de evento da sessão. Para instruções sobre como excluir sessões, consulte [Excluir sessões](/pt/claude-code-on-the-web#delete-sessions).


83 83 

84O diagrama abaixo mostra como Claude Code se conecta a serviços externos durante a instalação e operação normal. Linhas sólidas indicam conexões obrigatórias, enquanto linhas tracejadas representam fluxos de dados opcionais ou iniciados pelo usuário.84O diagrama abaixo mostra como Claude Code se conecta a serviços externos durante a instalação e operação normal. Linhas sólidas indicam conexões obrigatórias, enquanto linhas tracejadas representam fluxos de dados opcionais ou iniciados pelo usuário.

85 85 

86<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/claude-code-data-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=5b1131530bdfdd415700a0cb4d4070c4" alt="Diagram showing Claude Code's external connections: install/update connects to the distribution server, and user requests connect to Anthropic services including Console auth, public-api, and optionally metrics, Sentry, and bug reporting" width="720" height="520" data-path="images/claude-code-data-flow.svg" />86<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/claude-code-data-flow.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=5b1131530bdfdd415700a0cb4d4070c4" alt="Diagram showing Claude Code's external connections: install/update connects to the distribution server, and user requests connect to Anthropic services including Console auth, public-api, and optionally metrics and Sentry. Feedback sent with /feedback goes to Google Cloud Storage and optionally creates a GitHub issue" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

87 87 

88Claude Code é executado localmente. Para interagir com o LLM, Claude Code envia dados pela rede. Esses dados incluem todos os prompts do usuário e saídas do modelo, criptografados em trânsito via TLS 1.2+. Claude Code é compatível com a maioria dos VPNs e proxies LLM populares.88Claude Code é executado localmente. Para interagir com o LLM, Claude Code envia dados pela rede. Esses dados incluem todos os prompts do usuário e saídas do modelo, criptografados em trânsito via TLS 1.2+. Claude Code é compatível com a maioria dos VPNs e proxies LLM populares.

89 89 


119 119 

120Claude Code se conecta de máquinas dos usuários ao Sentry para logging de erros operacionais. Os dados são criptografados em trânsito usando TLS e em repouso usando criptografia AES de 256 bits. Leia mais na [documentação de segurança do Sentry](https://sentry.io/security/). Para desabilitar o logging de erros, defina a variável de ambiente `DISABLE_ERROR_REPORTING`.120Claude Code se conecta de máquinas dos usuários ao Sentry para logging de erros operacionais. Os dados são criptografados em trânsito usando TLS e em repouso usando criptografia AES de 256 bits. Leia mais na [documentação de segurança do Sentry](https://sentry.io/security/). Para desabilitar o logging de erros, defina a variável de ambiente `DISABLE_ERROR_REPORTING`.

121 121 

122Quando você executa o comando `/feedback`, uma cópia do histórico de conversa incluindo código é enviada para a Anthropic. Antes de enviar, você escolhe quanto histórico incluir: apenas a sessão atual, que é o padrão, ou também outras sessões do mesmo projeto nos últimos 24 horas ou 7 dias. Os dados são criptografados em trânsito via TLS. Opcionalmente, um problema do GitHub é criado no repositório público. Para desabilitar, defina a variável de ambiente `DISABLE_FEEDBACK_COMMAND` como `1`.122Quando você executa o comando `/feedback`, uma cópia do histórico de conversa incluindo código é enviada para a Anthropic. Antes de enviar, você escolhe quanto histórico incluir: apenas a sessão atual, que é o padrão, ou também outras sessões do mesmo projeto nos últimos 24 horas ou 7 dias. Os dados são criptografados em trânsito via TLS e armazenados no Google Cloud Storage, que criptografa dados armazenados em repouso por padrão. Opcionalmente, um problema do GitHub é criado no repositório público. Para desabilitar, defina a variável de ambiente `DISABLE_FEEDBACK_COMMAND` como `1`.

123 123 

124Quando você usa um provedor de terceiros como Bedrock ou Vertex, ou não tem credenciais da Anthropic configuradas, `/feedback` escreve o relatório em um arquivo local sob `~/.claude/feedback-bundles/` em vez de enviá-lo para a Anthropic. Padrões conhecidos de chave de API e token são removidos antes do arquivo ser escrito. Nada sai de sua máquina até que você envie esse arquivo para seu representante de conta da Anthropic ou o anexe a uma solicitação de suporte.124Quando você usa um provedor de terceiros como Bedrock ou Vertex, ou não tem credenciais da Anthropic configuradas, `/feedback` escreve o relatório em um arquivo local sob `~/.claude/feedback-bundles/` em vez de enviá-lo para a Anthropic. Padrões conhecidos de chave de API e token são removidos antes do arquivo ser escrito. Nada sai de sua máquina até que você envie esse arquivo para seu representante de conta da Anthropic ou o anexe a uma solicitação de suporte.

125 125 

Details

78 Teste contra uma configuração limpa78 Teste contra uma configuração limpa

79</h2>79</h2>

80 80 

81Se as verificações direcionadas não isolarem a causa, ou sua configuração estiver em um estado desconhecido, compare contra uma sessão que não carrega nada de sua configuração usual. Aponte [`CLAUDE_CONFIG_DIR`](/pt/env-vars) para um diretório vazio para contornar tudo sob `~/.claude` e inicie a partir de um diretório que não tenha pasta `.claude`, `.mcp.json` ou `CLAUDE.md` para que a configuração do projeto também seja ignorada.81{/* min-version: 2.1.169 */}Comece com [`claude --safe-mode`](/pt/cli-reference#cli-flags), que inicia uma sessão com todas as personalizações desabilitadas, incluindo `CLAUDE.md`, skills, plugins, hooks, servidores MCP e comandos e agentes personalizados. Autenticação, seleção de modelo, ferramentas integradas e permissões funcionam normalmente. Se o problema desaparecer no modo seguro, uma dessas superfícies é a causa; use as verificações direcionadas acima para descobrir qual. As configurações gerenciadas implantadas pela sua organização ainda se aplicam parcialmente, portanto hooks configurados por política e linha de status são executados mesmo no modo seguro.

82 

83Se o problema persistir no modo seguro, ou suas configurações em si forem suspeitas, compare contra uma sessão que não carrega nada de sua configuração usual. Aponte [`CLAUDE_CONFIG_DIR`](/pt/env-vars) para um diretório vazio para contornar tudo sob `~/.claude` e inicie a partir de um diretório que não tenha pasta `.claude`, `.mcp.json` ou `CLAUDE.md` para que a configuração do projeto também seja ignorada.

82 84 

83```bash theme={null}85```bash theme={null}

84cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude86cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

desktop.md +23 −21

Details

77Os modos de permissão controlam quanto de autonomia Claude tem durante uma sessão: se ele pergunta antes de editar arquivos, executar comandos ou ambos. Você pode alternar modos a qualquer momento usando o seletor de modo ao lado do botão enviar. Comece com Ask permissions para ver exatamente o que Claude faz, depois mude para Auto accept edits ou Plan mode conforme você fica confortável.77Os modos de permissão controlam quanto de autonomia Claude tem durante uma sessão: se ele pergunta antes de editar arquivos, executar comandos ou ambos. Você pode alternar modos a qualquer momento usando o seletor de modo ao lado do botão enviar. Comece com Ask permissions para ver exatamente o que Claude faz, depois mude para Auto accept edits ou Plan mode conforme você fica confortável.

78 78 

79| Modo | Chave de configuração | Comportamento |79| Modo | Chave de configuração | Comportamento |

80| ---------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |80| ---------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

81| **Ask permissions** | `default` | Claude pergunta antes de editar arquivos ou executar comandos. Você vê um diff e pode aceitar ou rejeitar cada alteração. Recomendado para novos usuários. |81| **Ask permissions** | `default` | Claude pergunta antes de editar arquivos ou executar comandos. Você vê um diff e pode aceitar ou rejeitar cada alteração. Recomendado para novos usuários. |

82| **Auto accept edits** | `acceptEdits` | Claude aceita automaticamente edições de arquivo e comandos comuns do sistema de arquivos como `mkdir`, `touch` e `mv`, mas ainda pergunta antes de executar outros comandos de terminal. Use isso quando você confia em alterações de arquivo e quer iteração mais rápida. |82| **Auto accept edits** | `acceptEdits` | Claude aceita automaticamente edições de arquivo e comandos comuns do sistema de arquivos como `mkdir`, `touch` e `mv`, mas ainda pergunta antes de executar outros comandos de terminal. Use isso quando você confia em alterações de arquivo e quer iteração mais rápida. |

83| **Plan mode** | `plan` | Claude lê arquivos e executa comandos para explorar, depois propõe um plano sem editar seu código-fonte. Bom para tarefas complexas onde você quer revisar a abordagem primeiro. |83| **Plan mode** | `plan` | Claude lê arquivos e executa comandos para explorar, depois propõe um plano sem editar seu código-fonte. Bom para tarefas complexas onde você quer revisar a abordagem primeiro. |

84| **Auto** | `auto` | Claude executa todas as ações com verificações de segurança em segundo plano que verificam o alinhamento com sua solicitação. Reduz prompts de permissão mantendo supervisão. Ative em suas Configurações → Claude Code. Veja [requisitos de disponibilidade](#auto-mode-availability) abaixo. |84| **Auto** | `auto` | Claude executa todas as ações com verificações de segurança em segundo plano que verificam o alinhamento com sua solicitação. Reduz prompts de permissão mantendo supervisão. Ative em suas Configurações → Claude Code. Veja [requisitos de disponibilidade](#auto-mode-availability) abaixo. |

85| **Bypass permissions** | `bypassPermissions` | Claude é executado sem nenhum prompt de permissão, equivalente a `--dangerously-skip-permissions` no CLI. Ative em suas Configurações → Claude Code em "Allow bypass permissions mode". Use apenas em containers ou VMs sandboxed. Administradores corporativos podem desabilitar essa opção. |85| **Bypass permissions** | `bypassPermissions` | Claude é executado sem nenhum prompt de permissão, exceto aqueles forçados por [regras de solicitação](/pt/permissions#manage-permissions) explícitas; equivalente a `--dangerously-skip-permissions` no CLI. Ative em suas Configurações → Claude Code em "Allow bypass permissions mode". Use apenas em containers ou VMs sandboxed. Administradores corporativos podem desabilitar essa opção. |

86 86 

87O modo de permissão `dontAsk` está disponível apenas no [CLI](/pt/permission-modes#allow-only-pre-approved-tools-with-dontask-mode).87O modo de permissão `dontAsk` está disponível apenas no [CLI](/pt/permission-modes#allow-only-pre-approved-tools-with-dontask-mode).

88 88 


94 Comece tarefas complexas em Plan mode para que Claude mapeie uma abordagem antes de fazer alterações. Depois de aprovar o plano, mude para Auto accept edits ou Ask permissions para executá-lo. Veja [explorar primeiro, depois planejar, depois codificar](/pt/best-practices#explore-first-then-plan-then-code) para mais sobre esse fluxo de trabalho.94 Comece tarefas complexas em Plan mode para que Claude mapeie uma abordagem antes de fazer alterações. Depois de aprovar o plano, mude para Auto accept edits ou Ask permissions para executá-lo. Veja [explorar primeiro, depois planejar, depois codificar](/pt/best-practices#explore-first-then-plan-then-code) para mais sobre esse fluxo de trabalho.

95</Tip>95</Tip>

96 96 

97Sessões remotas suportam Auto accept edits e Plan mode. Ask permissions não está disponível porque sessões remotas aceitam automaticamente edições de arquivo por padrão, e Bypass permissions não está disponível porque o ambiente remoto já é sandboxed.97Sessões remotas suportam Accept edits, Plan mode e Auto mode. Accept edits corresponde ao modo `default`: sessões remotas pré-aprovam edições de arquivo, então o seletor mostra Accept edits em vez de Ask permissions. Bypass permissions não está disponível porque o ambiente remoto já é sandboxed.

98 98 

99Administradores corporativos podem restringir quais modos de permissão estão disponíveis. Veja [configuração corporativa](#enterprise-configuration) para detalhes.99Administradores corporativos podem restringir quais modos de permissão estão disponíveis. Veja [configuração corporativa](#enterprise-configuration) para detalhes.

100 100 


487| `program` | string | Um script a executar com `node`. Veja [quando usar `program` vs `runtimeExecutable`](#when-to-use-program-vs-runtimeexecutable) |487| `program` | string | Um script a executar com `node`. Veja [quando usar `program` vs `runtimeExecutable`](#when-to-use-program-vs-runtimeexecutable) |

488| `args` | string\[] | Argumentos passados para `program`. Usado apenas quando `program` está definido |488| `args` | string\[] | Argumentos passados para `program`. Usado apenas quando `program` está definido |

489 489 

490<a id="when-to-use-program-vs-runtimeexecutable" />

491 

490<h5 id="when-to-use-program-vs-runtimeexecutable">492<h5 id="when-to-use-program-vs-runtimeexecutable">

491 When to use `program` vs `runtimeExecutable`493 When to use `program` vs `runtimeExecutable`

492</h5>494</h5>


598 600 

599Para definir variáveis de ambiente para sessões locais e servidores de desenvolvimento em qualquer plataforma, abra o menu suspenso de ambiente na caixa de prompt, passe o mouse sobre **Local** e clique no ícone de engrenagem para abrir o editor de ambiente local. Variáveis que você salva aqui são armazenadas criptografadas em sua máquina e se aplicam a cada sessão local e servidor de visualização que você inicia. Você também pode adicionar variáveis à chave `env` em seu arquivo `~/.claude/settings.json`, embora essas alcancem apenas sessões Claude e não servidores de desenvolvimento. Veja [variáveis de ambiente](/pt/env-vars) para a lista completa de variáveis suportadas.601Para definir variáveis de ambiente para sessões locais e servidores de desenvolvimento em qualquer plataforma, abra o menu suspenso de ambiente na caixa de prompt, passe o mouse sobre **Local** e clique no ícone de engrenagem para abrir o editor de ambiente local. Variáveis que você salva aqui são armazenadas criptografadas em sua máquina e se aplicam a cada sessão local e servidor de visualização que você inicia. Você também pode adicionar variáveis à chave `env` em seu arquivo `~/.claude/settings.json`, embora essas alcancem apenas sessões Claude e não servidores de desenvolvimento. Veja [variáveis de ambiente](/pt/env-vars) para a lista completa de variáveis suportadas.

600 602 

601[Extended thinking](/pt/model-config#extended-thinking) está ativado por padrão, o que melhora o desempenho em tarefas de raciocínio complexo mas usa tokens adicionais. Para desabilitar o thinking completamente, defina `MAX_THINKING_TOKENS` para `0` no editor de ambiente local. Em modelos com [adaptive reasoning](/pt/model-config#adjust-effort-level), qualquer outro valor de `MAX_THINKING_TOKENS` é ignorado porque adaptive reasoning controla a profundidade do thinking. Em Opus 4.6 e Sonnet 4.6, defina `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` para `1` para usar um orçamento de thinking fixo; Opus 4.7 e posterior sempre usam adaptive reasoning e não têm modo de orçamento fixo.603[Extended thinking](/pt/model-config#extended-thinking) está ativado por padrão, o que melhora o desempenho em tarefas de raciocínio complexo mas usa tokens adicionais. Para desabilitar o thinking, defina `MAX_THINKING_TOKENS` para `0` no editor de ambiente local; isso não tem efeito no Fable 5, que sempre usa extended thinking. Em [provedores de terceiros](/pt/third-party-integrations), `0` omite o parâmetro `thinking` em vez disso, e modelos de adaptive-reasoning ainda podem pensar. Em modelos com [adaptive reasoning](/pt/model-config#adjust-effort-level), qualquer outro valor de `MAX_THINKING_TOKENS` é ignorado porque adaptive reasoning controla a profundidade do thinking. Em Opus 4.6 e Sonnet 4.6, defina `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` para `1` para usar um orçamento de thinking fixo; Opus 4.7 e posterior sempre usam adaptive reasoning e não têm modo de orçamento fixo.

602 604 

603<h3 id="remote-sessions">605<h3 id="cloud-sessions">

604 Remote sessions606 Cloud sessions

605</h3>607</h3>

606 608 

607Sessões remotas continuam em segundo plano mesmo se você fechar o aplicativo. O uso conta para seus [limites do plano de assinatura](/pt/costs) sem cobranças de computação separadas.609Sessões em nuvem continuam em segundo plano mesmo se você fechar o aplicativo. O uso conta para seus [limites do plano de assinatura](/pt/costs) sem cobranças de computação separadas.

608 610 

609Você pode criar ambientes em nuvem personalizados com diferentes níveis de acesso de rede e variáveis de ambiente. Selecione o menu suspenso de ambiente ao iniciar uma sessão remota e escolha **Add environment**. Veja [o ambiente em nuvem](/pt/claude-code-on-the-web#the-cloud-environment) para detalhes sobre configuração de acesso de rede e variáveis de ambiente.611Você pode criar ambientes em nuvem personalizados com diferentes níveis de acesso de rede e variáveis de ambiente. Selecione o menu suspenso de ambiente ao iniciar uma sessão em nuvem e escolha **Add environment**. Veja [o ambiente em nuvem](/pt/claude-code-on-the-web#the-cloud-environment) para detalhes sobre configuração de acesso de rede e variáveis de ambiente.

610 612 

611<h3 id="ssh-sessions">613<h3 id="ssh-sessions">

612 SSH sessions614 SSH sessions


710 712 

711Equipes de TI podem gerenciar o aplicativo desktop através de MDM em macOS ou group policy no Windows. As políticas disponíveis incluem ativar ou desativar o recurso Claude Code, controlar atualizações automáticas e definir uma URL de implantação personalizada.713Equipes de TI podem gerenciar o aplicativo desktop através de MDM em macOS ou group policy no Windows. As políticas disponíveis incluem ativar ou desativar o recurso Claude Code, controlar atualizações automáticas e definir uma URL de implantação personalizada.

712 714 

713* **macOS**: configure via domínio de preferência `com.anthropic.Claude` usando ferramentas como Jamf ou Kandji715* **macOS**: configure via domínio de preferência `com.anthropic.claudefordesktop` usando ferramentas como Jamf ou Kandji

714* **Windows**: configure via registro em `SOFTWARE\Policies\Claude`716* **Windows**: configure via registro em `SOFTWARE\Policies\Claude`

715 717 

716<h3 id="authentication-and-sso">718<h3 id="authentication-and-sso">


779* **[MCP servers](/pt/mcp)** configurados em `~/.claude.json` ou `.mcp.json` funcionam em ambos781* **[MCP servers](/pt/mcp)** configurados em `~/.claude.json` ou `.mcp.json` funcionam em ambos

780* **[Hooks](/pt/hooks)** e **[skills](/pt/skills)** definidos em configurações se aplicam a ambos782* **[Hooks](/pt/hooks)** e **[skills](/pt/skills)** definidos em configurações se aplicam a ambos

781* **[Configurações](/pt/settings)** em `~/.claude.json` e `~/.claude/settings.json` são compartilhadas. Regras de permissão, ferramentas permitidas e outras configurações em `settings.json` se aplicam a sessões Desktop.783* **[Configurações](/pt/settings)** em `~/.claude.json` e `~/.claude/settings.json` são compartilhadas. Regras de permissão, ferramentas permitidas e outras configurações em `settings.json` se aplicam a sessões Desktop.

782* **Modelos**: Sonnet, Opus e Haiku estão disponíveis em ambos. Em Desktop, selecione o modelo no menu suspenso ao lado do botão enviar. Você pode alterar o modelo durante a sessão a partir do mesmo menu suspenso.784* **Modelos**: os mesmos [modelos](/pt/model-config#available-models) estão disponíveis em ambos. Em Desktop, selecione o modelo no menu suspenso ao lado do botão enviar. Você pode alterar o modelo durante a sessão a partir do mesmo menu suspenso.

783 785 

784<Note>786<Note>

785 **MCP servers do aplicativo de chat Claude Desktop**: o aplicativo Desktop carrega MCP servers de `claude_desktop_config.json` em sessões da aba Code, juntamente com servers de `~/.claude.json` e `.mcp.json`. Um server definido em `claude_desktop_config.json` está disponível tanto na superfície de chat Desktop quanto na aba Code.787 **MCP servers do aplicativo de chat Claude Desktop**: o aplicativo Desktop carrega MCP servers de `claude_desktop_config.json` em sessões da aba Code, juntamente com servers de `~/.claude.json` e `.mcp.json`. Um server definido em `claude_desktop_config.json` está disponível tanto na superfície de chat Desktop quanto na aba Code.


794Esta tabela compara capacidades principais entre CLI e Desktop. Para uma lista completa de flags CLI, veja a [referência CLI](/pt/cli-reference).796Esta tabela compara capacidades principais entre CLI e Desktop. Para uma lista completa de flags CLI, veja a [referência CLI](/pt/cli-reference).

795 797 

796| Recurso | CLI | Desktop |798| Recurso | CLI | Desktop |

797| ------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |799| ------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

798| Modos de permissão | Todos os modos incluindo `dontAsk` | Ask permissions, Auto accept edits, Plan mode, Auto e Bypass permissions via Configurações |800| Modos de permissão | Todos os modos incluindo `dontAsk` | Ask permissions, Auto accept edits, Plan mode, Auto e Bypass permissions via Configurações |

799| `--dangerously-skip-permissions` | Flag CLI | Modo Bypass permissions. Ative em Configurações → Claude Code → "Allow bypass permissions mode" |801| `--dangerously-skip-permissions` | Flag CLI | Modo Bypass permissions. Ative em Configurações → Claude Code → "Allow bypass permissions mode" |

800| [Provedores de terceiros](/pt/third-party-integrations) | Bedrock, Vertex, Foundry | API da Anthropic por padrão. Implantações corporativas podem configurar Vertex AI e provedores de gateway. Veja o [guia de configuração corporativa](https://support.claude.com/en/articles/12622667-enterprise-configuration). |802| [Provedores de terceiros](/pt/third-party-integrations) | Bedrock, Vertex AI, Foundry | API da Anthropic por padrão. Implantações corporativas podem configurar Vertex AI e provedores de gateway. Veja o [guia de configuração corporativa](https://support.claude.com/en/articles/12622667-enterprise-configuration). Para executar a aba Code em Bedrock, Vertex AI, Foundry ou um gateway LLM auto-hospedado, veja a [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview). |

801| [MCP servers](/pt/mcp) | Configure em arquivos de configuração | UI de Connectors para sessões locais e SSH, ou arquivos de configuração |803| [MCP servers](/pt/mcp) | Configure em arquivos de configuração | UI de Connectors para sessões locais e SSH, ou arquivos de configuração |

802| [Plugins](/pt/plugins) | Comando `/plugin` | UI do gerenciador de plugins |804| [Plugins](/pt/plugins) | Comando `/plugin` | UI do gerenciador de plugins |

803| @mention de arquivos | Baseado em texto | Com autocompletar; sessões locais e SSH apenas |805| @mention de arquivos | Baseado em texto | Com autocompletar; sessões locais e SSH apenas |


809| Integração Dispatch | Não disponível | [Sessões Dispatch](#sessions-from-dispatch) na barra lateral |811| Integração Dispatch | Não disponível | [Sessões Dispatch](#sessions-from-dispatch) na barra lateral |

810| Scripting e automação | [`--print`](/pt/cli-reference), [Agent SDK](/pt/headless) | Não disponível |812| Scripting e automação | [`--print`](/pt/cli-reference), [Agent SDK](/pt/headless) | Não disponível |

811 813 

812<h3 id="what-s-not-available-in-desktop">814<h3 id="whats-not-available-in-desktop">

813 What's not available in Desktop815 What's not available in Desktop

814</h3>816</h3>

815 817 

816Os seguintes recursos estão disponíveis apenas no CLI ou extensão VS Code:818Os seguintes recursos estão disponíveis apenas no CLI ou extensão VS Code, exceto onde observado:

817 819 

818* **Provedores de terceiros**: Desktop se conecta à API da Anthropic por padrão. Implantações corporativas podem configurar Vertex AI e provedores de gateway via [configurações gerenciadas](https://support.claude.com/en/articles/12622667-enterprise-configuration). Para Bedrock ou Foundry, use o [CLI](/pt/quickstart).820* **Provedores de terceiros**: Desktop se conecta à API da Anthropic por padrão. Implantações corporativas podem configurar Vertex AI e provedores de gateway via [configurações gerenciadas](https://support.claude.com/en/articles/12622667-enterprise-configuration). Para Bedrock ou Foundry no CLI, veja o [quickstart](/pt/quickstart). Como uma exceção à seção acima, a [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview) executa a aba Code em Bedrock, Vertex AI, Foundry ou um gateway LLM auto-hospedado.

819* **Linux**: o aplicativo desktop está disponível apenas em macOS e Windows. No Linux, use o [CLI](/pt/quickstart).821* **Linux**: o aplicativo desktop está disponível apenas em macOS e Windows. No Linux, use o [CLI](/pt/quickstart).

820* **Sugestões de código inline**: Desktop não fornece sugestões no estilo autocompletar. Funciona através de prompts conversacionais e alterações de código explícitas.822* **Sugestões de código inline**: Desktop não fornece sugestões no estilo autocompletar. Funciona através de prompts conversacionais e alterações de código explícitas.

821* **Equipes de agentes**: sessões paralelas de Claude Code que se comunicam entre si estão disponíveis no [CLI](/pt/agent-teams), não em Desktop. Para trabalho multi-agente dentro de uma sessão, use [dynamic workflows](/pt/workflows), que são executados em Desktop.823* **Equipes de agentes**: sessões paralelas de Claude Code que se comunicam entre si estão disponíveis no [CLI](/pt/agent-teams), não em Desktop. Para trabalho multi-agente dentro de uma sessão, use [dynamic workflows](/pt/workflows), que são executados em Desktop.


885 887 

886Se toggles de MCP server não respondem ou servidores falham em conectar no Windows, verifique se o servidor está adequadamente configurado em suas configurações, reinicie o aplicativo, verifique se o processo do servidor está em execução no Task Manager e revise logs do servidor para erros de conexão.888Se toggles de MCP server não respondem ou servidores falham em conectar no Windows, verifique se o servidor está adequadamente configurado em suas configurações, reinicie o aplicativo, verifique se o processo do servidor está em execução no Task Manager e revise logs do servidor para erros de conexão.

887 889 

888<h3 id="app-won-t-quit">890<h3 id="app-wont-quit">

889 Aplicativo não quer sair891 Aplicativo não quer sair

890</h3>892</h3>

891 893 


899* **PATH não atualizado após instalação**: abra uma nova janela de terminal. PATH é atualizado apenas para novas sessões de terminal.901* **PATH não atualizado após instalação**: abra uma nova janela de terminal. PATH é atualizado apenas para novas sessões de terminal.

900* **Erro de instalação concorrente**: se você vê um erro sobre outra instalação em progresso mas não há uma, tente executar o instalador como Administrador.902* **Erro de instalação concorrente**: se você vê um erro sobre outra instalação em progresso mas não há uma, tente executar o instalador como Administrador.

901 903 

902<h3 id="branch-doesn-t-exist-yet-when-opening-in-cli">904<h3 id="branch-doesnt-exist-yet-when-opening-in-cli">

903 "Branch doesn't exist yet" ao abrir em CLI905 "Branch doesn't exist yet" ao abrir em CLI

904</h3>906</h3>

905 907 

906Sessões remotas podem criar branches que não existem em sua máquina local. Clique no nome do branch na barra de ferramentas da sessão para copiá-lo, depois busque-o localmente:908Sessões na nuvem podem criar branches que não existem em sua máquina local. Clique no nome do branch na barra de ferramentas da sessão para copiá-lo, depois busque-o localmente:

907 909 

908```bash theme={null}910```bash theme={null}

909git fetch origin <branch-name>911git fetch origin <branch-name>


914 Ainda preso?916 Ainda preso?

915</h3>917</h3>

916 918 

917* Pesquise ou registre um bug em [GitHub Issues](https://github.com/anthropics/claude-code/issues)919* Abra Help Get Support no aplicativo desktop, ou visite o [centro de suporte Claude](https://support.claude.com/) diretamente

918* Visite o [centro de suporte Claude](https://support.claude.com/)920* Para problemas que também se reproduzem no CLI `claude` autossuficiente, pesquise ou registre um bug em [GitHub Issues](https://github.com/anthropics/claude-code/issues)

919 921 

920Ao registrar um bug, inclua a versão do seu aplicativo desktop, seu sistema operacional, a mensagem de erro exata e logs relevantes. Em macOS, verifique Console.app. No Windows, verifique Event Viewer → Windows Logs → Application.922Ao registrar um problema, inclua a versão do seu aplicativo desktop, seu sistema operacional, a mensagem de erro exata e logs relevantes. Em macOS, verifique Console.app. No Windows, verifique Event Viewer → Windows Logs → Application.

Details

71 </Step>71 </Step>

72 72 

73 <Step title="Escolha um modelo">73 <Step title="Escolha um modelo">

74 Selecione um modelo no dropdown ao lado do botão enviar. Consulte [modelos](/pt/model-config#available-models) para uma comparação de Opus, Sonnet e Haiku. Você pode alterar o modelo mais tarde no mesmo dropdown.74 Selecione um modelo no dropdown ao lado do botão enviar. Consulte [modelos](/pt/model-config#available-models) para uma comparação dos modelos disponíveis. Você pode alterar o modelo mais tarde no mesmo dropdown.

75 </Step>75 </Step>

76 76 

77 <Step title="Diga a Claude o que fazer">77 <Step title="Diga a Claude o que fazer">


129 129 

130Desktop executa o mesmo mecanismo que a CLI com uma interface gráfica. Você pode executar ambos simultaneamente no mesmo projeto, e eles compartilham configuração (arquivos CLAUDE.md, MCP servers, hooks, skills e configurações). Para uma comparação completa de recursos, equivalentes de flag e o que não está disponível no Desktop, consulte [Comparação de CLI](/pt/desktop#coming-from-the-cli).130Desktop executa o mesmo mecanismo que a CLI com uma interface gráfica. Você pode executar ambos simultaneamente no mesmo projeto, e eles compartilham configuração (arquivos CLAUDE.md, MCP servers, hooks, skills e configurações). Para uma comparação completa de recursos, equivalentes de flag e o que não está disponível no Desktop, consulte [Comparação de CLI](/pt/desktop#coming-from-the-cli).

131 131 

132<h2 id="what-s-next">132<h2 id="whats-next">

133 Próximas etapas133 Próximas etapas

134</h2>134</h2>

135 135 

Details

169 * **Marketplaces**: adicione, remova ou atualize seus marketplaces adicionados169 * **Marketplaces**: adicione, remova ou atualize seus marketplaces adicionados

170 * **Errors**: visualize quaisquer erros de carregamento de plugins170 * **Errors**: visualize quaisquer erros de carregamento de plugins

171 171 

172 Vá para a aba **Discover** para ver plugins do marketplace que você acabou de adicionar. {/* min-version: 2.1.154 */}Plugins marcados como relevantes para seu diretório de trabalho atual são fixados no topo com um rótulo **suggested for this directory**.172 Vá para a aba **Discover** para ver plugins do marketplace que você acabou de adicionar. {/* min-version: 2.1.154 */}Quando seu administrador tiver adicionado o marketplace à lista de permissões por meio da configuração gerenciada [`pluginSuggestionMarketplaces`](/pt/settings#available-settings), plugins marcados como relevantes para seu diretório de trabalho atual são fixados no topo com um rótulo **suggested for this directory**.

173 </Step>173 </Step>

174 174 

175 <Step title="Instale um plugin">175 <Step title="Instale um plugin">


328* digitar para filtrar por nome ou descrição do plugin328* digitar para filtrar por nome ou descrição do plugin

329* pressionar Enter para abrir a visualização de detalhes de um plugin e habilitar, desabilitar ou desinstalá-lo329* pressionar Enter para abrir a visualização de detalhes de um plugin e habilitar, desabilitar ou desinstalá-lo

330 330 

331A visualização de detalhes mostra os componentes que o plugin contribui: comandos, skills, agentes, hooks, servidores MCP e servidores LSP. O mesmo inventário está disponível na linha de comando com `claude plugin details`.

332 

331Quando você instala um plugin que declara dependências, a saída de instalação lista quais dependências foram auto-instaladas junto com ele.333Quando você instala um plugin que declara dependências, a saída de instalação lista quais dependências foram auto-instaladas junto com ele.

332 334 

333Você também pode gerenciar plugins com comandos diretos.335Você também pode gerenciar plugins com comandos diretos.

334 336 

337Liste plugins instalados sem abrir o menu:

338 

339```shell theme={null}

340/plugin list

341```

342 

343Passe `--enabled` ou `--disabled` para mostrar apenas plugins nesse estado.

344 

335Desabilite um plugin sem desinstalá-lo:345Desabilite um plugin sem desinstalá-lo:

336 346 

337```shell theme={null}347```shell theme={null}


369 379 

370Claude Code recarrega todos os plugins ativos e mostra contagens para plugins, skills, agentes, hooks, servidores MCP de plugin e servidores LSP de plugin.380Claude Code recarrega todos os plugins ativos e mostra contagens para plugins, skills, agentes, hooks, servidores MCP de plugin e servidores LSP de plugin.

371 381 

372O recarregamento tem um custo de token na próxima solicitação: componentes recém-carregados se anunciam no conteúdo anexado à conversa, enquanto o histórico existente ainda lê do cache de prompt. Um plugin que fornece servidores MCP custa mais quando suas ferramentas não são adiadas por [busca de ferramentas MCP](/pt/mcp#scale-with-mcp-tool-search): a mudança invalida o cache e a próxima solicitação relê toda a conversa. Consulte [habilitando ou desabilitando um plugin](/pt/prompt-caching#enabling-or-disabling-a-plugin) para obter detalhes.382O recarregamento tem um custo de token na próxima solicitação: componentes recém-carregados se anunciam no conteúdo anexado à conversa, enquanto o histórico existente ainda lê do cache de prompt. Um plugin que fornece servidores MCP custa mais quando suas ferramentas não são adiadas por [busca de ferramentas MCP](/pt/mcp#scale-with-mcp-tool-search): a mudança invalida o cache e a próxima solicitação relê toda a conversa. {/* min-version: 2.1.163 */}Nesse caso `/reload-plugins` mostra um aviso e não aplica o recarregamento; passe `--force` para aplicar mesmo assim. Consulte [habilitando ou desabilitando um plugin](/pt/prompt-caching#enabling-or-disabling-a-plugin) para obter detalhes.

373 383 

374<h2 id="manage-marketplaces">384<h2 id="manage-marketplaces">

375 Gerencie marketplaces385 Gerencie marketplaces


445Isso é útil quando você quer gerenciar atualizações de Claude Code manualmente mas ainda receber atualizações automáticas de plugins.455Isso é útil quando você quer gerenciar atualizações de Claude Code manualmente mas ainda receber atualizações automáticas de plugins.

446 456 

447<h2 id="configure-team-marketplaces">457<h2 id="configure-team-marketplaces">

448 Configure marketplaces de equipe458 Configurar marketplaces de equipe

449</h2>459</h2>

450 460 

451Administradores de equipe podem configurar instalação automática de marketplace para projetos adicionando configuração de marketplace a `.claude/settings.json`. Quando membros da equipe confiam na pasta do repositório, Claude Code os solicita a instalar esses marketplaces e plugins.461Administradores de equipe podem configurar instalação automática de marketplace para projetos adicionando configuração de marketplace a `.claude/settings.json`. Quando membros da equipe confiam na pasta do repositório, Claude Code os solicita a instalar esses marketplaces e plugins.

env-vars.md +35 −20

Details

73O arquivo que você escolhe controla para quem as variáveis se aplicam:73O arquivo que você escolhe controla para quem as variáveis se aplicam:

74 74 

75| Arquivo | Aplica-se a |75| Arquivo | Aplica-se a |

76| :---------------------------- | :------------------------------------------------------------- |76| :---------------------------- | :----------------------------------------------------------------------------------- |

77| `~/.claude/settings.json` | Você, em cada projeto |77| `~/.claude/settings.json` | Você, em cada projeto |

78| `.claude/settings.json` | Todos trabalhando no projeto, verificado no controle de origem |78| `.claude/settings.json` | Todos trabalhando no projeto, verificado no controle de origem |

79| `.claude/settings.local.json` | Você, apenas neste projeto, não verificado |79| `.claude/settings.local.json` | Você, apenas neste projeto (adicione-o ao seu gitignore se você o criar manualmente) |

80| Configurações gerenciadas | Todos na sua organização, implantados por um administrador |80| Configurações gerenciadas | Todos na sua organização, implantados por um administrador |

81 81 

82Veja [Arquivos de configurações](/pt/settings#settings-files) para onde cada arquivo reside e [Precedência de configurações](/pt/settings#settings-precedence) para como eles se combinam quando mais de um define a mesma variável.82Veja [Arquivos de configurações](/pt/settings#settings-files) para onde cada arquivo reside e [Precedência de configurações](/pt/settings#settings-precedence) para como eles se combinam quando mais de um define a mesma variável.


96</h2>96</h2>

97 97 

98| Variável | Propósito |98| Variável | Propósito |

99| :------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |99| :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

100| `ANTHROPIC_API_KEY` | Chave de API enviada como cabeçalho `X-Api-Key`. Quando definida, essa chave é usada em vez de sua assinatura Claude Pro, Max, Team ou Enterprise, mesmo que você esteja conectado. Em modo não interativo (`-p`), a chave é sempre usada quando presente. Em modo interativo, você é solicitado a aprovar a chave uma vez antes de ela substituir sua assinatura. Para usar sua assinatura em vez disso, execute `unset ANTHROPIC_API_KEY` |100| `ANTHROPIC_API_KEY` | Chave de API enviada como cabeçalho `X-Api-Key`. Quando definida, essa chave é usada em vez de sua assinatura Claude Pro, Max, Team ou Enterprise, mesmo que você esteja conectado. Em modo não interativo (`-p`), a chave é sempre usada quando presente. Em modo interativo, você é solicitado a aprovar a chave uma vez antes de ela substituir sua assinatura. Para usar sua assinatura em vez disso, execute `unset ANTHROPIC_API_KEY` |

101| `ANTHROPIC_AUTH_TOKEN` | Valor personalizado para o cabeçalho `Authorization` (o valor que você definir aqui será prefixado com `Bearer `) |101| `ANTHROPIC_AUTH_TOKEN` | Valor personalizado para o cabeçalho `Authorization` (o valor que você definir aqui será prefixado com `Bearer `) |

102| `ANTHROPIC_AWS_API_KEY` | Chave de API do workspace para [Claude Platform on AWS](/pt/claude-platform-on-aws), gerada no AWS Console. Enviada como `x-api-key` e tem precedência sobre AWS SigV4 |102| `ANTHROPIC_AWS_API_KEY` | Chave de API do workspace para [Claude Platform on AWS](/pt/claude-platform-on-aws), gerada no AWS Console. Enviada como `x-api-key` e tem precedência sobre AWS SigV4 |


112| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | Descrição de exibição para a entrada de modelo personalizado no seletor `/model`. Padrão é `Custom model (<model-id>)` quando não definido |112| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | Descrição de exibição para a entrada de modelo personalizado no seletor `/model`. Padrão é `Custom model (<model-id>)` quando não definido |

113| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | Nome de exibição para a entrada de modelo personalizado no seletor `/model`. Padrão é o ID do modelo quando não definido |113| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | Nome de exibição para a entrada de modelo personalizado no seletor `/model`. Padrão é o ID do modelo quando não definido |

114| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | Veja [Configuração de modelo](/pt/model-config#customize-pinned-model-display-and-capabilities) |114| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | Veja [Configuração de modelo](/pt/model-config#customize-pinned-model-display-and-capabilities) |

115| `ANTHROPIC_DEFAULT_FABLE_MODEL` | Veja [Configuração de modelo](/pt/model-config#environment-variables) |

116| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | Veja [Configuração de modelo](/pt/model-config#customize-pinned-model-display-and-capabilities) |

117| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | Veja [Configuração de modelo](/pt/model-config#customize-pinned-model-display-and-capabilities) |

118| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | Veja [Configuração de modelo](/pt/model-config#customize-pinned-model-display-and-capabilities) |

115| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Veja [Configuração de modelo](/pt/model-config#environment-variables) |119| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Veja [Configuração de modelo](/pt/model-config#environment-variables) |

116| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | Veja [Configuração de modelo](/pt/model-config#customize-pinned-model-display-and-capabilities) |120| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | Veja [Configuração de modelo](/pt/model-config#customize-pinned-model-display-and-capabilities) |

117| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | Veja [Configuração de modelo](/pt/model-config#customize-pinned-model-display-and-capabilities) |121| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | Veja [Configuração de modelo](/pt/model-config#customize-pinned-model-display-and-capabilities) |


133| `ANTHROPIC_VERTEX_BASE_URL` | Substitua a URL do endpoint Vertex AI. Use para endpoints Vertex personalizados ou ao rotear através de um [gateway LLM](/pt/llm-gateway). Veja [Google Vertex AI](/pt/google-vertex-ai) |137| `ANTHROPIC_VERTEX_BASE_URL` | Substitua a URL do endpoint Vertex AI. Use para endpoints Vertex personalizados ou ao rotear através de um [gateway LLM](/pt/llm-gateway). Veja [Google Vertex AI](/pt/google-vertex-ai) |

134| `ANTHROPIC_VERTEX_PROJECT_ID` | ID do projeto GCP para solicitações Vertex AI. Substituído por `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` ou o projeto no seu arquivo de credenciais `GOOGLE_APPLICATION_CREDENTIALS`. Veja [Google Vertex AI](/pt/google-vertex-ai) |138| `ANTHROPIC_VERTEX_PROJECT_ID` | ID do projeto GCP para solicitações Vertex AI. Substituído por `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` ou o projeto no seu arquivo de credenciais `GOOGLE_APPLICATION_CREDENTIALS`. Veja [Google Vertex AI](/pt/google-vertex-ai) |

135| `ANTHROPIC_WORKSPACE_ID` | ID do workspace para [federação de identidade de carga de trabalho](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Defina isso quando sua regra de federação está no escopo de mais de um workspace para que a troca de token saiba qual workspace direcionar |139| `ANTHROPIC_WORKSPACE_ID` | ID do workspace para [federação de identidade de carga de trabalho](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Defina isso quando sua regra de federação está no escopo de mais de um workspace para que a troca de token saiba qual workspace direcionar |

140| `API_FORCE_IDLE_TIMEOUT` | {/* min-version: 2.1.169 */}Substitua o tempo limite de inatividade de 5 minutos que aborta uma resposta de modelo de streaming quando nenhum byte chega. Defina como `0` para desabilitar o tempo limite, por exemplo, quando um [gateway](/pt/llm-gateway) lento ou modelo local pausa por mais de 5 minutos entre chunks. Defina como `1` para manter o tempo limite em cada provedor. Quando não definido, o tempo limite está inativo em conexões diretas da API Anthropic e [Claude Platform on AWS](/pt/claude-platform-on-aws), onde o próprio watchdog de stream de nível de byte do Claude Code é executado, e ativo em cada outro provedor, incluindo [Vertex AI](/pt/google-vertex-ai), [Foundry](/pt/microsoft-foundry), [Mantle](/pt/amazon-bedrock#use-the-mantle-endpoint), [Bedrock](/pt/amazon-bedrock) e conexões de gateway, para que um stream travado seja abortado em vez de ficar pendurado. A partir de v2.1.169 |

136| `API_TIMEOUT_MS` | Tempo limite para solicitações de API em milissegundos (padrão: 600000, ou 10 minutos; máximo: 2147483647). Aumente isso quando as solicitações expiram em redes lentas ou ao rotear através de um proxy. Valores acima do máximo causam overflow do temporizador subjacente e fazem com que as solicitações falhem imediatamente |141| `API_TIMEOUT_MS` | Tempo limite para solicitações de API em milissegundos (padrão: 600000, ou 10 minutos; máximo: 2147483647). Aumente isso quando as solicitações expiram em redes lentas ou ao rotear através de um proxy. Valores acima do máximo causam overflow do temporizador subjacente e fazem com que as solicitações falhem imediatamente |

137| `AWS_BEARER_TOKEN_BEDROCK` | Chave de API do Bedrock para autenticação (veja [Chaves de API do Bedrock](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |142| `AWS_BEARER_TOKEN_BEDROCK` | Chave de API do Bedrock para autenticação (veja [Chaves de API do Bedrock](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |

138| `BASH_DEFAULT_TIMEOUT_MS` | Tempo limite padrão para comandos bash de longa duração (padrão: 120000, ou 2 minutos) |143| `BASH_DEFAULT_TIMEOUT_MS` | Tempo limite padrão para comandos bash de longa duração (padrão: 120000, ou 2 minutos) |

139| `BASH_MAX_OUTPUT_LENGTH` | Número máximo de caracteres nas saídas bash antes da saída completa ser salva em um arquivo e Claude receber o caminho mais uma visualização curta. Veja [Comportamento da ferramenta Bash](/pt/tools-reference#bash-tool-behavior) |144| `BASH_MAX_OUTPUT_LENGTH` | Número máximo de caracteres nas saídas bash antes da saída completa ser salva em um arquivo e Claude receber o caminho mais uma visualização curta. Veja [Comportamento da ferramenta Bash](/pt/tools-reference#bash-tool-behavior) |

140| `BASH_MAX_TIMEOUT_MS` | Tempo limite máximo que o modelo pode definir para comandos bash de longa duração (padrão: 600000, ou 10 minutos) |145| `BASH_MAX_TIMEOUT_MS` | Tempo limite máximo que o modelo pode definir para comandos bash de longa duração (padrão: 600000, ou 10 minutos) |

141| `CCR_FORCE_BUNDLE` | Defina como `1` para forçar [`claude --remote`](/pt/claude-code-on-the-web#send-local-repositories-without-github) a agrupar e fazer upload do seu repositório local mesmo quando o acesso ao GitHub está disponível |146| `CCR_FORCE_BUNDLE` | Defina como `1` para forçar [`claude --remote`](/pt/claude-code-on-the-web#send-local-repositories-without-github) a agrupar e fazer upload do seu repositório local mesmo quando o acesso ao GitHub está disponível |

142| `CLAUDECODE` | Defina como `1` em subprocessos que Claude Code gera (ferramentas Bash e PowerShell, sessões tmux, [hook](/pt/hooks) comandos, [linha de status](/pt/statusline) comandos, subprocessos [servidor MCP](/pt/mcp) stdio). Use para detectar quando um script está sendo executado dentro de um subprocesso gerado por Claude Code |147| `CLAUDECODE` | Defina como `1` em subprocessos que Claude Code gera (ferramentas Bash e PowerShell, sessões tmux, [hook](/pt/hooks) comandos, [linha de status](/pt/statusline) comandos, subprocessos [servidor MCP](/pt/mcp) stdio). Extensões IDE também definem isso em seus terminais integrados. Use para detectar quando um script está sendo executado dentro de um subprocesso gerado por Claude Code. Para verificar se o processo atual foi gerado diretamente por uma chamada de ferramenta ou hook, em vez de dentro de um servidor MCP stdio que Claude Code iniciou, use `CLAUDE_CODE_CHILD_SESSION` em vez disso |

143| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Defina como `1` para desabilitar todos os tipos de [subagente](/pt/sub-agents) integrados, como Explore e Plan. Aplica-se apenas em modo não interativo (a flag `-p`). Útil para usuários do SDK que desejam uma tela em branco |148| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Defina como `1` para desabilitar todos os tipos de [subagente](/pt/sub-agents) integrados, como Explore e Plan. Aplica-se apenas em modo não interativo (a flag `-p`). Útil para usuários do SDK que desejam uma tela em branco |

144| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Defina como `1` para pular o prefixo `mcp__<server>__` em nomes de ferramentas de servidores MCP criados pelo SDK. As ferramentas usam seus nomes originais. Apenas uso do SDK |149| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Defina como `1` para pular o prefixo `mcp__<server>__` em nomes de ferramentas de servidores MCP criados pelo SDK. As ferramentas usam seus nomes originais. Apenas uso do SDK |

145| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Tempo limite de travamento em milissegundos para subagentes em segundo plano. Padrão `600000` (10 minutos). O temporizador é reiniciado em cada evento de progresso de streaming; se nenhum progresso chegar dentro da janela, o subagente é abortado e a tarefa é marcada como falha, exibindo qualquer resultado parcial para o pai |150| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Tempo limite de travamento em milissegundos para subagentes em segundo plano. Padrão `600000` (10 minutos). O temporizador é reiniciado em cada evento de progresso de streaming; se nenhum progresso chegar dentro da janela, o subagente é abortado e a tarefa é marcada como falha, exibindo qualquer resultado parcial para o pai |

146| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Defina a porcentagem da capacidade de contexto (1-100) na qual a auto-compactação é acionada. Por padrão, a auto-compactação é acionada em aproximadamente 95% de capacidade. Use valores mais baixos como `50` para compactar mais cedo. Valores acima do limite padrão não têm efeito. Aplica-se a conversas principais e subagentes. Esta porcentagem se alinha com o campo `context_window.used_percentage` disponível na [linha de status](/pt/statusline) |151| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Defina a porcentagem (1-100) da janela de auto-compactação na qual a auto-compactação é acionada. Use valores mais baixos como `50` para compactar mais cedo. Esta variável causa compactação mais cedo quando Claude Code compacta proativamente: quando `CLAUDE_CODE_AUTO_COMPACT_WINDOW` está definido, em [sessões em nuvem](/pt/claude-code-on-the-web), em sessões [Remote Control](/pt/remote-control) e em Sonnet 4.6 e Opus 4.6 sem [contexto estendido](/pt/model-config#extended-context), que compactam no limite de 200K por padrão. Em outros casos, como uma sessão local em Opus 4.8 ou qualquer modelo com contexto estendido, a auto-compactação é acionada quando a conversa atinge o limite de contexto do modelo. O override pode baixar o limite, então valores acima do padrão não têm efeito. Aplica-se a conversas principais e subagentes |

147| `CLAUDE_AUTO_BACKGROUND_TASKS` | Defina como `1` para forçar a habilitação do envio automático para segundo plano de tarefas de agente de longa duração. Quando habilitado, subagentes são movidos para o segundo plano após executarem por aproximadamente dois minutos |152| `CLAUDE_AUTO_BACKGROUND_TASKS` | Defina como `1` para forçar a habilitação do envio automático para segundo plano de tarefas de agente de longa duração. Quando habilitado, subagentes são movidos para o segundo plano após executarem por aproximadamente dois minutos |

148| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Retorne ao diretório de trabalho original após cada comando Bash ou PowerShell na sessão principal |153| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Retorne ao diretório de trabalho original após cada comando Bash ou PowerShell na sessão principal |

149| `CLAUDE_CODE_ACCESSIBILITY` | Defina como `1` para manter o cursor do terminal nativo visível e desabilitar o indicador de cursor de texto invertido. Permite que ampliadores de tela como macOS Zoom rastreiem a posição do cursor |154| `CLAUDE_CODE_ACCESSIBILITY` | Defina como `1` para manter o cursor do terminal nativo visível e desabilitar o indicador de cursor de texto invertido. Permite que ampliadores de tela como macOS Zoom rastreiem a posição do cursor |

150| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | Defina como `1` para carregar arquivos de memória de diretórios especificados com `--add-dir`. Carrega `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` e `CLAUDE.local.md`. Por padrão, diretórios adicionais não carregam arquivos de memória |155| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | Defina como `1` para carregar arquivos de memória de diretórios especificados com `--add-dir`. Carrega `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` e `CLAUDE.local.md`. Por padrão, diretórios adicionais não carregam arquivos de memória |

151| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | Defina como `1` para repintar a tela inteira em cada quadro em [renderização em tela cheia](/pt/fullscreen) em vez de enviar atualizações incrementais. Use isso se o modo tela cheia mostrar fragmentos de texto obsoletos ou deslocados. Claude Code habilita isso automaticamente para sessões em segundo plano e [visualização de agentes](/pt/agent-view) no Windows |156| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | Defina como `1` para repintar a tela inteira em cada quadro em [renderização em tela cheia](/pt/fullscreen) em vez de enviar atualizações incrementais. Use isso se o modo tela cheia mostrar fragmentos de texto obsoletos ou deslocados. Claude Code habilita isso automaticamente para sessões em segundo plano e [visualização de agentes](/pt/agent-view) no Windows |

157| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | Defina como `1` para enviar o parâmetro [esforço](/pt/model-config#adjust-effort-level) com cada solicitação, mesmo quando Claude Code não reconhece o ID do modelo como capaz de esforço. Use isso ao rotear através de um [gateway LLM](/pt/llm-gateway) ou provedor de terceiros que serve modelos sob identificadores personalizados. Modelos que rejeitam o parâmetro de esforço na API, incluindo modelos Claude 3, Sonnet 4.0 e 4.5, Opus 4.0 e 4.1 e Haiku 4.5, ainda são excluídos para que as solicitações não falhem |

152| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Intervalo em milissegundos no qual as credenciais devem ser atualizadas (ao usar [`apiKeyHelper`](/pt/settings#available-settings)) |158| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Intervalo em milissegundos no qual as credenciais devem ser atualizadas (ao usar [`apiKeyHelper`](/pt/settings#available-settings)) |

153| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Defina como `0` para omitir o bloco de atribuição (versão do cliente e impressão digital do prompt) do início do prompt do sistema. Desabilitá-lo melhora as taxas de acerto do cache de prompt ao rotear através de um [gateway LLM](/pt/llm-gateway). O cache da API Anthropic não é afetado |159| `CLAUDE_CODE_ATTRIBUTION_HEADER` | Defina como `0` para omitir o bloco de atribuição (versão do cliente e impressão digital do prompt) do início do prompt do sistema. Desabilitá-lo melhora as taxas de acerto do cache de prompt ao rotear através de um [gateway LLM](/pt/llm-gateway). O cache da API Anthropic não é afetado |

154| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Defina a capacidade de contexto em tokens usada para cálculos de auto-compactação. Padrão é a janela de contexto do modelo: 200K para modelos padrão ou 1M para modelos de [contexto estendido](/pt/model-config#extended-context). Use um valor mais baixo como `500000` em um modelo de 1M para tratar a janela como 500K para fins de compactação. O valor é limitado à janela de contexto real do modelo. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` é aplicado como uma porcentagem deste valor. Definir esta variável desacopla o limite de compactação do `used_percentage` da linha de status, que sempre usa a janela de contexto completa do modelo |160| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Defina a capacidade de contexto em tokens usada para cálculos de auto-compactação. Padrão é a janela de contexto do modelo: 200K para modelos padrão ou 1M para modelos de [contexto estendido](/pt/model-config#extended-context). Use um valor mais baixo como `500000` em um modelo de 1M para tratar a janela como 500K para fins de compactação. O valor é limitado à janela de contexto real do modelo. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` é aplicado como uma porcentagem deste valor. Definir esta variável desacopla o limite de compactação do `used_percentage` da linha de status, que sempre usa a janela de contexto completa do modelo |

155| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Substitua a [conexão IDE](/pt/vs-code) automática. Por padrão, Claude Code se conecta automaticamente quando iniciado dentro do terminal integrado de uma IDE suportada. Defina como `false` para evitar isso. Defina como `true` para forçar uma tentativa de conexão quando a detecção automática falha, como quando tmux obscurece o terminal pai. Tem precedência sobre a configuração global [`autoConnectIde`](/pt/settings#global-config-settings) |161| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Substitua a [conexão IDE](/pt/vs-code) automática. Por padrão, Claude Code se conecta automaticamente quando iniciado dentro do terminal integrado de uma IDE suportada. Defina como `false` para evitar isso. Defina como `true` para forçar uma tentativa de conexão quando a detecção automática falha, como quando tmux obscurece o terminal pai. Tem precedência sobre a configuração global [`autoConnectIde`](/pt/settings#global-config-settings) |

156| `CLAUDE_CODE_CERT_STORE` | Lista separada por vírgula de fontes de certificado CA para conexões TLS. `bundled` é o conjunto de CA Mozilla fornecido com Claude Code. `system` é o armazenamento de confiança do sistema operacional. Padrão é `bundled,system` |162| `CLAUDE_CODE_CERT_STORE` | Lista separada por vírgula de fontes de certificado CA para conexões TLS. `bundled` é o conjunto de CA Mozilla fornecido com Claude Code. `system` é o armazenamento de confiança do sistema operacional. Padrão é `bundled,system` |

163| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Defina como `1` em subprocessos que Claude Code gera via ferramentas Bash, PowerShell e Monitor, [hook](/pt/hooks) comandos e [linha de status](/pt/statusline) comandos. Não definido para subprocessos [servidor MCP](/pt/mcp) stdio, que são de longa duração e sobrevivem à sessão que os gerou. Diferentemente de `CLAUDECODE`, isso é definido apenas pelo Claude Code quando ele inicia um subprocesso e não por extensões IDE, então distingue de forma confiável uma sessão aninhada de um `claude` de nível superior iniciado em um terminal integrado IDE. Uma `claude` TUI interativa aninhada iniciada desta forma é automaticamente excluída de `--resume`, `--continue`, histórico de seta para cima e a lista `claude agents`. Sessões `claude -p` não interativas ainda persistem. Defina `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` para substituir esta exclusão. Requer Claude Code v2.1.172 ou posterior |

157| `CLAUDE_CODE_CLIENT_CERT` | Caminho para arquivo de certificado do cliente para autenticação mTLS |164| `CLAUDE_CODE_CLIENT_CERT` | Caminho para arquivo de certificado do cliente para autenticação mTLS |

158| `CLAUDE_CODE_CLIENT_KEY` | Caminho para arquivo de chave privada do cliente para autenticação mTLS |165| `CLAUDE_CODE_CLIENT_KEY` | Caminho para arquivo de chave privada do cliente para autenticação mTLS |

159| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Frase-passe para `CLAUDE_CODE_CLIENT_KEY` criptografada (opcional) |166| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Frase-passe para `CLAUDE_CODE_CLIENT_KEY` criptografada (opcional) |

160| `CLAUDE_CODE_DEBUG_LOGS_DIR` | Substitua o caminho do arquivo de log de depuração. Apesar do nome, este é um caminho de arquivo, não um diretório. Requer que o modo de depuração seja habilitado separadamente via `--debug`, `/debug` ou a variável de ambiente `DEBUG`: definir apenas essa variável não habilita o logging. A flag [`--debug-file`](/pt/cli-reference#cli-flags) faz ambos de uma vez. Padrão é `~/.claude/debug/<session-id>.txt` |167| `CLAUDE_CODE_DEBUG_LOGS_DIR` | Substitua o caminho do arquivo de log de depuração. Apesar do nome, este é um caminho de arquivo, não um diretório. Requer que o modo de depuração seja habilitado separadamente via `--debug`, `/debug` ou a variável de ambiente `DEBUG`: definir apenas essa variável não habilita o logging. A flag [`--debug-file`](/pt/cli-reference#cli-flags) faz ambos de uma vez. Padrão é `~/.claude/debug/<session-id>.txt` |

161| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Nível de log mínimo escrito no arquivo de log de depuração. Valores: `verbose`, `debug` (padrão), `info`, `warn`, `error`. Defina como `verbose` para incluir diagnósticos de alto volume como saída completa de comando de linha de status, ou aumente para `error` para reduzir ruído |168| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | Nível de log mínimo escrito no arquivo de log de depuração. Valores: `verbose`, `debug` (padrão), `info`, `warn`, `error`. Defina como `verbose` para incluir diagnósticos de alto volume como saída completa de comando de linha de status, ou aumente para `error` para reduzir ruído |

162| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Defina como `1` para desabilitar suporte a [janela de contexto de 1M](/pt/model-config#extended-context). Quando definido, variantes de modelo de 1M não estão disponíveis no seletor de modelo. Útil para ambientes corporativos com requisitos de conformidade |169| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Defina como `1` para desabilitar suporte a [janela de contexto de 1M](/pt/model-config#extended-context). Quando definido, variantes de modelo de 1M não estão disponíveis no seletor de modelo. Útil para ambientes corporativos com requisitos de conformidade |

163| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Defina como `1` para desabilitar [raciocínio adaptativo](/pt/model-config#adjust-effort-level) em Opus 4.6 e Sonnet 4.6 e voltar ao orçamento de pensamento fixo controlado por `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}Não tem efeito em Opus 4.7 e posterior, que sempre usa raciocínio adaptativo |170| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Defina como `1` para desabilitar [raciocínio adaptativo](/pt/model-config#adjust-effort-level) em Opus 4.6 e Sonnet 4.6 e voltar ao orçamento de pensamento fixo controlado por `MAX_THINKING_TOKENS`. {/* min-version: 2.1.111 */}A partir de v2.1.111, não tem efeito em Fable 5, ou em Opus 4.7 e posterior, que sempre usam raciocínio adaptativo |

171| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | {/* min-version: 2.1.98 */}Defina como `1` para desabilitar a [ferramenta advisor](/pt/advisor). O comando `/advisor` e a flag `--advisor` ficam indisponíveis e qualquer `advisorModel` configurado é ignorado. Requer Claude Code v2.1.98 ou posterior |

164| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | Defina como `1` para desativar [agentes em segundo plano e visualização de agentes](/pt/agent-view): `claude agents`, `--bg`, `/background` e o supervisor sob demanda. Equivalente à configuração [`disableAgentView`](/pt/settings#available-settings) |172| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | Defina como `1` para desativar [agentes em segundo plano e visualização de agentes](/pt/agent-view): `claude agents`, `--bg`, `/background` e o supervisor sob demanda. Equivalente à configuração [`disableAgentView`](/pt/settings#available-settings) |

165| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | Defina como `1` para desabilitar [renderização em tela cheia](/pt/fullscreen) e usar o renderizador de tela principal clássico. A conversa permanece no scrollback nativo do seu terminal para que `Cmd+f` e modo de cópia tmux funcionem como de costume. Tem precedência sobre `CLAUDE_CODE_NO_FLICKER` e a configuração [`tui`](/pt/settings#available-settings). Você também pode alternar com `/tui default` |173| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | Defina como `1` para desabilitar [renderização em tela cheia](/pt/fullscreen) e usar o renderizador de tela principal clássico. A conversa permanece no scrollback nativo do seu terminal para que `Cmd+f` e modo de cópia tmux funcionem como de costume. Tem precedência sobre `CLAUDE_CODE_NO_FLICKER` e a configuração [`tui`](/pt/settings#available-settings). Você também pode alternar com `/tui default`. Não se aplica a sessões em segundo plano abertas de [visualização de agentes](/pt/agent-view), que sempre usam renderização em tela cheia |

166| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Defina como `1` para desabilitar o processamento de anexos. Menções de arquivo com sintaxe `@` são enviadas como texto simples em vez de serem expandidas para conteúdo de arquivo |174| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | Defina como `1` para desabilitar o processamento de anexos. Menções de arquivo com sintaxe `@` são enviadas como texto simples em vez de serem expandidas para conteúdo de arquivo |

167| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Defina como `1` para desabilitar [memória automática](/pt/memory#auto-memory). Defina como `0` para forçar a memória automática mesmo quando `--bare` mode ou [`autoMemoryEnabled: false`](/pt/settings#available-settings) desabilitaria de outra forma. Quando desabilitada, Claude não cria ou carrega arquivos de memória automática |175| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Defina como `1` para desabilitar [memória automática](/pt/memory#auto-memory). Defina como `0` para forçar a memória automática mesmo quando `--bare` mode ou [`autoMemoryEnabled: false`](/pt/settings#available-settings) desabilitaria de outra forma. Quando desabilitada, Claude não cria ou carrega arquivos de memória automática |

168| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Defina como `1` para desabilitar toda a funcionalidade de tarefas em segundo plano, incluindo o parâmetro `run_in_background` em ferramentas Bash e subagent, auto-backgrounding e o atalho Ctrl+B |176| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Defina como `1` para desabilitar toda a funcionalidade de tarefas em segundo plano, incluindo o parâmetro `run_in_background` em ferramentas Bash e subagent, auto-backgrounding e o atalho Ctrl+B |

177| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Defina como `1` para desabilitar as [skills](/pt/skills) e workflows que vêm com Claude Code: skills agrupadas e workflows integrados são removidos inteiramente, enquanto comandos slash integrados como `/init` permanecem digitáveis mas são ocultados do modelo. Skills de plugins, `.claude/skills/` e `.claude/commands/` não são afetadas. Equivalente à configuração [`disableBundledSkills`](/pt/settings#available-settings); `0` não a substitui |

169| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Defina como `1` para evitar carregar qualquer arquivo de memória CLAUDE.md no contexto, incluindo arquivos de usuário, projeto e memória automática |178| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Defina como `1` para evitar carregar qualquer arquivo de memória CLAUDE.md no contexto, incluindo arquivos de usuário, projeto e memória automática |

170| `CLAUDE_CODE_DISABLE_CRON` | Defina como `1` para desabilitar [tarefas agendadas](/pt/scheduled-tasks). A skill `/loop` e ferramentas cron ficam indisponíveis e qualquer tarefa já agendada para de disparar, incluindo tarefas que já estão em execução no meio da sessão |179| `CLAUDE_CODE_DISABLE_CRON` | Defina como `1` para desabilitar [tarefas agendadas](/pt/scheduled-tasks). A skill `/loop` e ferramentas cron ficam indisponíveis e qualquer tarefa já agendada para de disparar, incluindo tarefas que já estão em execução no meio da sessão |

171| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos do Anthropic e campos de esquema de ferramenta beta (como `defer_loading` e `eager_input_streaming`) de solicitações de API. Use isso quando um gateway proxy rejeita solicitações com erros como "Unexpected value(s) for the `anthropic-beta` header" ou "Extra inputs are not permitted". Campos padrão (`name`, `description`, `input_schema`, `cache_control`) são preservados. |180| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Defina como `1` para remover cabeçalhos de solicitação `anthropic-beta` específicos do Anthropic e campos de esquema de ferramenta beta (como `defer_loading` e `eager_input_streaming`) de solicitações de API. Use isso quando um gateway proxy rejeita solicitações com erros como "Unexpected value(s) for the `anthropic-beta` header" ou "Extra inputs are not permitted". Campos padrão (`name`, `description`, `input_schema`, `cache_control`) são preservados. |


180| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | Defina como `1` para pular a adição automática do marketplace de plugin oficial na primeira execução |189| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | Defina como `1` para pular a adição automática do marketplace de plugin oficial na primeira execução |

181| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | Defina como `1` para pular o carregamento de skills do diretório de skills gerenciado em todo o sistema. Útil para sessões de contêiner ou CI que não devem carregar skills provisionadas pelo operador |190| `CLAUDE_CODE_DISABLE_POLICY_SKILLS` | Defina como `1` para pular o carregamento de skills do diretório de skills gerenciado em todo o sistema. Útil para sessões de contêiner ou CI que não devem carregar skills provisionadas pelo operador |

182| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Defina como `1` para desabilitar atualizações automáticas de título do terminal com base no contexto da conversa. Em sessões Agent SDK e `claude -p`, isso também pula a solicitação de Haiku em segundo plano que gera o título da sessão |191| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Defina como `1` para desabilitar atualizações automáticas de título do terminal com base no contexto da conversa. Em sessões Agent SDK e `claude -p`, isso também pula a solicitação de Haiku em segundo plano que gera o título da sessão |

183| `CLAUDE_CODE_DISABLE_THINKING` | Defina como `1` para forçar a desabilitação de [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) independentemente do suporte do modelo ou outras configurações. Mais direto que `MAX_THINKING_TOKENS=0` |192| `CLAUDE_CODE_DISABLE_THINKING` | Defina como `1` para omitir o parâmetro `thinking` de solicitações de API inteiramente. Esta é uma opção de compatibilidade para proxies e gateways que rejeitam o parâmetro. O comportamento da variável é inalterado em relação a versões anteriores; em modelos que pensam por padrão, omitir o parâmetro significa que o modelo ainda pode pensar. Para desabilitar explicitamente [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) na API Anthropic, use `MAX_THINKING_TOKENS=0` em vez disso, que também é ineficaz em Fable 5 já que não pode ter pensamento desligado. Em [provedores de terceiros](/pt/third-party-integrations), `0` igualmente omite o parâmetro, então as duas variáveis se comportam da mesma forma lá |

184| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Defina como `1` para desabilitar rolagem virtual em [renderização em tela cheia](/pt/fullscreen) e renderizar cada mensagem na transcrição. Use isso se a rolagem em modo tela cheia mostrar regiões em branco onde as mensagens deveriam aparecer |193| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | Defina como `1` para desabilitar rolagem virtual em [renderização em tela cheia](/pt/fullscreen) e renderizar cada mensagem na transcrição. Use isso se a rolagem em modo tela cheia mostrar regiões em branco onde as mensagens deveriam aparecer |

185| `CLAUDE_CODE_DISABLE_WORKFLOWS` | Defina como `1` para desabilitar [workflows](/pt/workflows#turn-workflows-off). Equivalente à configuração [`disableWorkflows`](/pt/settings#available-settings) |194| `CLAUDE_CODE_DISABLE_WORKFLOWS` | Defina como `1` para desabilitar [workflows](/pt/workflows#turn-workflows-off). Equivalente à configuração [`disableWorkflows`](/pt/settings#available-settings) |

186| `CLAUDE_CODE_EFFORT_LEVEL` | Defina o nível de esforço para modelos suportados. Valores: `low`, `medium`, `high`, `xhigh`, `max` ou `auto` para usar o padrão do modelo. Os níveis disponíveis dependem do modelo. Tem precedência sobre `/effort` e a configuração `effortLevel`. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) |195| `CLAUDE_CODE_EFFORT_LEVEL` | Defina o nível de esforço para modelos suportados. Valores: `low`, `medium`, `high`, `xhigh`, `max` ou `auto` para usar o padrão do modelo. Os níveis disponíveis dependem do modelo. Tem precedência sobre `/effort` e a configuração `effortLevel`. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) |


198| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Defina como `1` para habilitar [equipes de agentes](/pt/agent-teams). As equipes de agentes são experimentais e desabilitadas por padrão |207| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Defina como `1` para habilitar [equipes de agentes](/pt/agent-teams). As equipes de agentes são experimentais e desabilitadas por padrão |

199| `CLAUDE_CODE_EXTRA_BODY` | Objeto JSON para mesclar no nível superior de cada corpo de solicitação de API. Útil para passar parâmetros específicos do provedor que Claude Code não expõe diretamente |208| `CLAUDE_CODE_EXTRA_BODY` | Objeto JSON para mesclar no nível superior de cada corpo de solicitação de API. Útil para passar parâmetros específicos do provedor que Claude Code não expõe diretamente |

200| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Substitua o limite de token padrão para leituras de arquivo. Útil quando você precisa ler arquivos maiores na íntegra |209| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Substitua o limite de token padrão para leituras de arquivo. Útil quando você precisa ler arquivos maiores na íntegra |

210| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {/* min-version: 2.1.172 */}Defina como `1` para forçar persistência de transcrição, histórico de prompt e registro `claude agents` mesmo quando este `claude` foi iniciado de dentro de outra sessão Claude Code. Use quando um valor `CLAUDE_CODE_CHILD_SESSION` herdado, por exemplo de um servidor tmux iniciado pela primeira vez pela ferramenta Bash do Claude Code, causa uma sessão genuína de nível superior a ser classificada incorretamente como aninhada. Também honrado em v2.1.169 e anterior; não tem efeito em v2.1.170 e v2.1.171, onde a detecção de sessão aninhada que ele substitui foi removida |

201| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Defina como `1` para forçar a habilitação do modo privado DEC 2026 [saída sincronizada](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) quando seu terminal suporta mas não é detectado automaticamente. Útil para emuladores como `eat` do Emacs que implementam BSU/ESU mas não respondem à sonda de capacidade. Não tem efeito sob tmux |211| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Defina como `1` para forçar a habilitação do modo privado DEC 2026 [saída sincronizada](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) quando seu terminal suporta mas não é detectado automaticamente. Útil para emuladores como `eat` do Emacs que implementam BSU/ESU mas não respondem à sonda de capacidade. Não tem efeito sob tmux |

202| `CLAUDE_CODE_FORK_SUBAGENT` | Defina como `1` para habilitar [subagentes bifurcados](/pt/sub-agents#fork-the-current-conversation). Um subagente bifurcado herda o contexto de conversa completo da sessão principal em vez de começar do zero. Quando habilitado, `/fork` gera um subagente bifurcado em vez de agir como um alias para [`/branch`](/pt/commands), e todos os spawns de subagente são executados em segundo plano. Funciona em modo interativo e via SDK ou `claude -p` |212| `CLAUDE_CODE_FORK_SUBAGENT` | Defina como `1` para permitir [subagentes bifurcados](/pt/sub-agents#fork-the-current-conversation), ou `0` para desabilitá-los, substituindo qualquer rollout do lado do servidor. Quando habilitado, Claude pode solicitar o tipo de subagente `fork` para gerar uma bifurcação, um subagente que herda o contexto de conversa completo em vez de começar do zero. Spawns sem um tipo de subagente ainda usam o subagente de propósito geral, e todos os spawns de subagente são executados em segundo plano. O comando [`/fork`](/pt/commands) explícito funciona sem essa variável. Funciona em modo interativo e via SDK ou `claude -p` |

203| `CLAUDE_CODE_GIT_BASH_PATH` | Apenas Windows: caminho para o executável Git Bash (`bash.exe`). Use quando Git Bash está instalado mas não está no seu PATH. Veja [Configuração do Windows](/pt/setup#set-up-on-windows) |213| `CLAUDE_CODE_GIT_BASH_PATH` | Apenas Windows: caminho para o executável Git Bash (`bash.exe`). Use quando Git Bash está instalado mas não está no seu PATH. Veja [Configuração do Windows](/pt/setup#set-up-on-windows) |

204| `CLAUDE_CODE_GLOB_HIDDEN` | Defina como `false` para excluir dotfiles dos resultados quando Claude invoca a [ferramenta Glob](/pt/tools-reference#glob-tool-behavior). Incluído por padrão. Não afeta autocomplete de arquivo `@`, `ls`, Grep ou Read |214| `CLAUDE_CODE_GLOB_HIDDEN` | Defina como `false` para excluir dotfiles dos resultados quando Claude invoca a [ferramenta Glob](/pt/tools-reference#glob-tool-behavior). Incluído por padrão. Não afeta autocomplete de arquivo `@`, `ls`, Grep ou Read |

205| `CLAUDE_CODE_GLOB_NO_IGNORE` | Defina como `false` para fazer a [ferramenta Glob](/pt/tools-reference#glob-tool-behavior) respeitar padrões `.gitignore`. Por padrão, Glob retorna todos os arquivos correspondentes, incluindo os ignorados pelo git. Não afeta autocomplete de arquivo `@`, que tem sua própria [configuração `respectGitignore`](/pt/settings#available-settings) |215| `CLAUDE_CODE_GLOB_NO_IGNORE` | Defina como `false` para fazer a [ferramenta Glob](/pt/tools-reference#glob-tool-behavior) respeitar padrões `.gitignore`. Por padrão, Glob retorna todos os arquivos correspondentes, incluindo os ignorados pelo git. Não afeta autocomplete de arquivo `@`, que tem sua própria [configuração `respectGitignore`](/pt/settings#available-settings) |


239| `CLAUDE_CODE_REMOTE_SESSION_ID` | Definido automaticamente em [sessões em nuvem](/pt/claude-code-on-the-web) para o ID da sessão atual. Leia isso para construir um link de volta para a transcrição da sessão. Veja [Vincular artefatos de volta à sessão](/pt/claude-code-on-the-web#link-artifacts-back-to-the-session) |249| `CLAUDE_CODE_REMOTE_SESSION_ID` | Definido automaticamente em [sessões em nuvem](/pt/claude-code-on-the-web) para o ID da sessão atual. Leia isso para construir um link de volta para a transcrição da sessão. Veja [Vincular artefatos de volta à sessão](/pt/claude-code-on-the-web#link-artifacts-back-to-the-session) |

240| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Defina como `1` para retomar automaticamente se a sessão anterior terminou no meio de uma volta. Usado em modo SDK para que o modelo continue sem exigir que o SDK reenvie o prompt |250| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Defina como `1` para retomar automaticamente se a sessão anterior terminou no meio de uma volta. Usado em modo SDK para que o modelo continue sem exigir que o SDK reenvie o prompt |

241| `CLAUDE_CODE_RESUME_PROMPT` | Substitua a mensagem de continuação injetada ao retomar uma sessão que terminou no meio de uma volta. Padrão é `Continue from where you left off.`. Scripts de spawn para agentes de longa duração podem definir isso para uma mensagem de inicialização mais diretiva. Uma string vazia usa o padrão |251| `CLAUDE_CODE_RESUME_PROMPT` | Substitua a mensagem de continuação injetada ao retomar uma sessão que terminou no meio de uma volta. Padrão é `Continue from where you left off.`. Scripts de spawn para agentes de longa duração podem definir isso para uma mensagem de inicialização mais diretiva. Uma string vazia usa o padrão |

252| `CLAUDE_CODE_SAFE_MODE` | Defina como `1` para iniciar em modo seguro: CLAUDE.md, skills, plugins, hooks, servidores MCP, comandos personalizados e agentes, estilos de saída, workflows, temas personalizados, atalhos de teclado personalizados, comandos de linha de status e sugestão de arquivo, servidores LSP e memória automática não carregam, para solucionar problemas de uma configuração quebrada. A política de configurações gerenciadas ainda se aplica, incluindo hooks configurados por política, linha de status e comandos de sugestão de arquivo; plugins gerenciados, skills gerenciadas, CLAUDE.md gerenciado e servidores MCP configurados por política não. Equivalente a passar [`--safe-mode`](/pt/cli-reference#cli-flags). Processos filhos gerados diretamente herdam a variável |

242| `CLAUDE_CODE_SCRIPT_CAPS` | Objeto JSON limitando quantas vezes scripts específicos podem ser invocados por sessão quando `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` está definido. As chaves são substrings correspondidas contra o texto do comando; os valores são limites de chamadas inteiras. Por exemplo, `{"deploy.sh": 2}` permite que `deploy.sh` seja chamado no máximo duas vezes. A correspondência é baseada em substring, então truques de expansão de shell como `./scripts/deploy.sh $(evil)` ainda contam contra o limite. Fan-out em tempo de execução via `xargs` ou `find -exec` não é detectado; este é um controle de defesa em profundidade |253| `CLAUDE_CODE_SCRIPT_CAPS` | Objeto JSON limitando quantas vezes scripts específicos podem ser invocados por sessão quando `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` está definido. As chaves são substrings correspondidas contra o texto do comando; os valores são limites de chamadas inteiras. Por exemplo, `{"deploy.sh": 2}` permite que `deploy.sh` seja chamado no máximo duas vezes. A correspondência é baseada em substring, então truques de expansão de shell como `./scripts/deploy.sh $(evil)` ainda contam contra o limite. Fan-out em tempo de execução via `xargs` ou `find -exec` não é detectado; este é um controle de defesa em profundidade |

243| `CLAUDE_CODE_SCROLL_SPEED` | Defina o multiplicador de rolagem da roda do mouse em [renderização em tela cheia](/pt/fullscreen#mouse-wheel-scrolling). Aceita valores de 1 a 20. Defina como `3` para corresponder a `vim` se seu terminal enviar um evento de roda por entalhe sem amplificação. Ignorado no terminal IDE JetBrains, onde Claude Code usa seu próprio tratamento de rolagem |254| `CLAUDE_CODE_SCROLL_SPEED` | Defina o multiplicador de rolagem da roda do mouse em [renderização em tela cheia](/pt/fullscreen#mouse-wheel-scrolling). Aceita valores de 1 a 20 e valores fracionários abaixo de 1, como `0.5` para desacelerar a rolagem acelerada de trackpad e roda em terminais que já amplificam eventos de roda. Defina como `3` para corresponder a `vim` se seu terminal enviar um evento de roda por entalhe sem amplificação. Ignorado no terminal IDE JetBrains, onde Claude Code usa seu próprio tratamento de rolagem |

244| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Substitua o orçamento de tempo em milissegundos para hooks [SessionEnd](/pt/hooks#sessionend). Aplica-se à saída de sessão, `/clear` e alternância de sessões via `/resume` interativo. Por padrão, o orçamento é 1,5 segundos, automaticamente aumentado para o `timeout` por hook mais alto configurado em arquivos de configuração, até 60 segundos. Timeouts em hooks fornecidos por plugin não aumentam o orçamento |255| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Substitua o orçamento de tempo em milissegundos para hooks [SessionEnd](/pt/hooks#sessionend). Aplica-se à saída de sessão, `/clear` e alternância de sessões via `/resume` interativo. Por padrão, o orçamento é 1,5 segundos, automaticamente aumentado para o `timeout` por hook mais alto configurado em arquivos de configuração, até 60 segundos. Timeouts em hooks fornecidos por plugin não aumentam o orçamento |

245| `CLAUDE_CODE_SESSION_ID` | Definido automaticamente em subprocessos de ferramenta Bash e PowerShell para o ID da sessão atual. Corresponde ao campo `session_id` passado para [hooks](/pt/hooks). Atualizado em `/clear`. Use para correlacionar scripts e ferramentas externas com a sessão Claude Code que as iniciou |256| `CLAUDE_CODE_SESSION_ID` | Definido automaticamente em subprocessos de ferramenta Bash e PowerShell, subprocessos de [comando hook](/pt/hooks) e subprocessos [servidor MCP](/pt/mcp) stdio para o ID da sessão atual. Para Bash, PowerShell e hooks, isso corresponde ao campo `session_id` na entrada JSON do hook e é atualizado em `/clear`. Um subprocesso de servidor MCP retém o ID com o qual foi gerado. Em `--resume <session-id>` ele recebe o ID retomado, correspondendo a hooks e Bash. Em `--continue` ou `--resume` sem um ID explícito, ele pode receber o ID de inicialização inicial em vez disso. Use para correlacionar scripts e ferramentas externas com a sessão Claude Code que as iniciou |

246| `CLAUDE_CODE_SHELL` | Substitua a detecção automática de shell. Útil quando seu shell de login difere do seu shell de trabalho preferido (por exemplo, `bash` vs `zsh`) |257| `CLAUDE_CODE_SHELL` | Substitua a detecção automática de shell. Útil quando seu shell de login difere do seu shell de trabalho preferido (por exemplo, `bash` vs `zsh`) |

247| `CLAUDE_CODE_SHELL_PREFIX` | Prefixo de comando que envolve comandos shell que Claude Code gera: chamadas de ferramenta Bash, comandos [hook](/pt/hooks) e comandos de inicialização de [servidor MCP](/pt/mcp) stdio. Útil para logging ou auditoria. Exemplo: definir `/path/to/logger.sh` executa cada comando como `/path/to/logger.sh <command>` |258| `CLAUDE_CODE_SHELL_PREFIX` | Prefixo de comando que envolve comandos shell que Claude Code gera: chamadas de ferramenta Bash, comandos [hook](/pt/hooks), [linha de status](/pt/statusline) comandos e comandos de inicialização de [servidor MCP](/pt/mcp) stdio. Hooks de forma exec e hooks PowerShell são executados sem o prefixo. Útil para logging ou auditoria. Definir um caminho de executável simples como `/path/to/logger.sh` executa cada comando como `/path/to/logger.sh '<command>'`. O wrapper recebe a linha de comando como um único argumento shell-quoted em `$1`, então o wrapper deve re-avaliar `$1` com um shell, por exemplo `exec bash -c "$1"`. Tratar `$1` como um caminho de executável simples quebra servidores MCP stdio que passam argumentos como `npx -y <package>`. Para chamadas de ferramenta Bash, `$1` contém a invocação de shell completa que Claude Code monta, incluindo configuração de ambiente, não apenas o comando que Claude executou |

248| `CLAUDE_CODE_SIMPLE` | Defina como `1` para executar com um prompt do sistema mínimo e apenas as ferramentas Bash, leitura de arquivo e edição de arquivo. Ferramentas MCP de `--mcp-config` ainda estão disponíveis. Desabilita auto-descoberta de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md. Tokens OAuth e credenciais de keychain não são lidos, então a autenticação Anthropic deve vir de `ANTHROPIC_API_KEY` ou um `apiKeyHelper` em `--settings`. Equivalente a passar [`--bare`](/pt/headless#start-faster-with-bare-mode) |259| `CLAUDE_CODE_SIMPLE` | Defina como `1` para executar com um prompt do sistema mínimo e apenas as ferramentas Bash, leitura de arquivo e edição de arquivo. Ferramentas MCP de `--mcp-config` ainda estão disponíveis. Desabilita auto-descoberta de hooks, skills, plugins, servidores MCP, memória automática e CLAUDE.md. Tokens OAuth e credenciais de keychain não são lidos, então a autenticação Anthropic deve vir de `ANTHROPIC_API_KEY` ou um `apiKeyHelper` em `--settings`. Equivalente a passar [`--bare`](/pt/headless#start-faster-with-bare-mode) |

249| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | Defina como `1` para usar um prompt do sistema mais curto e descrições de ferramenta abreviadas em qualquer modelo. Defina como `0`, `false`, `no` ou `off` para optar por não participar mesmo em modelos onde o experimento ou configuração do servidor habilitaria de outra forma. O conjunto de ferramentas completo, hooks, servidores MCP e descoberta de CLAUDE.md permanecem habilitados |260| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | Defina como `1` para usar um prompt do sistema mais curto e descrições de ferramenta abreviadas em qualquer modelo. Defina como `0`, `false`, `no` ou `off` para optar por não participar mesmo em modelos onde o experimento ou configuração do servidor habilitaria de outra forma. O conjunto de ferramentas completo, hooks, servidores MCP e descoberta de CLAUDE.md permanecem habilitados |

250| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | Pule autenticação do lado do cliente para [Claude Platform on AWS](/pt/claude-platform-on-aws), para gateways que assinam solicitações por conta própria |261| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | Pule autenticação do lado do cliente para [Claude Platform on AWS](/pt/claude-platform-on-aws), para gateways que assinam solicitações por conta própria |


258| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Defina como `1` para remover credenciais do Anthropic e do provedor de nuvem de ambientes de subprocesso (ferramenta Bash, hooks, servidores MCP stdio). O processo Claude pai mantém essas credenciais para chamadas de API, mas processos filhos não podem lê-las, reduzindo a exposição a ataques de injeção de prompt que tentam exfiltrar segredos via expansão de shell. No Linux, isso também executa subprocessos Bash em um namespace PID isolado para que não possam ler ambientes de processo do host via `/proc`; como efeito colateral, `ps`, `pgrep` e `kill` não podem ver ou sinalizar processos do host. `claude-code-action` define isso automaticamente quando `allowed_non_write_users` está configurado |269| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Defina como `1` para remover credenciais do Anthropic e do provedor de nuvem de ambientes de subprocesso (ferramenta Bash, hooks, servidores MCP stdio). O processo Claude pai mantém essas credenciais para chamadas de API, mas processos filhos não podem lê-las, reduzindo a exposição a ataques de injeção de prompt que tentam exfiltrar segredos via expansão de shell. No Linux, isso também executa subprocessos Bash em um namespace PID isolado para que não possam ler ambientes de processo do host via `/proc`; como efeito colateral, `ps`, `pgrep` e `kill` não podem ver ou sinalizar processos do host. `claude-code-action` define isso automaticamente quando `allowed_non_write_users` está configurado |

259| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | Defina como `1` em modo não interativo (a flag `-p`) para aguardar a conclusão da instalação de plugin antes da primeira consulta. Sem isso, plugins instalam em segundo plano e podem não estar disponíveis na primeira volta. Combine com `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` para limitar a espera |270| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | Defina como `1` em modo não interativo (a flag `-p`) para aguardar a conclusão da instalação de plugin antes da primeira consulta. Sem isso, plugins instalam em segundo plano e podem não estar disponíveis na primeira volta. Combine com `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` para limitar a espera |

260| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | Tempo limite em milissegundos para instalação síncrona de plugin. Quando excedido, Claude Code prossegue sem plugins e registra um erro. Sem padrão: sem essa variável, instalação síncrona aguarda até a conclusão |271| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | Tempo limite em milissegundos para instalação síncrona de plugin. Quando excedido, Claude Code prossegue sem plugins e registra um erro. Sem padrão: sem essa variável, instalação síncrona aguarda até a conclusão |

261| `CLAUDE_CODE_SYNC_SKILLS` | Defina como `1` para baixar suas skills habilitadas do claude.ai em `~/.claude/skills/` antes da primeira consulta e ressincronizar a cada 10 minutos. Aplica-se apenas em modo não interativo com a flag `-p`. Definido automaticamente em sessões [Claude Code on the web](/pt/claude-code-on-the-web). Requer autenticação claude.ai |272| `CLAUDE_CODE_SYNC_SKILLS` | Defina como `1` para baixar suas skills habilitadas do claude.ai em `~/.claude/skills/` antes da primeira consulta e ressincronizar a cada 10 minutos. Aplica-se apenas em modo não interativo com a flag `-p`. Requer autenticação claude.ai. [Claude Code on the web](/pt/claude-code-on-the-web) sessões recebem suas skills habilitadas do claude.ai automaticamente; você não precisa definir isso lá |

273| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | Tempo limite em milissegundos para uma ressincronização de skills no meio da sessão quando `CLAUDE_CODE_SYNC_SKILLS` está definido (padrão: 30000). Limita o download acionado quando o host solicita um recarregamento de skill durante a sessão. Quando excedido, a ressincronização para e os downloads de skill restantes continuam em segundo plano |

262| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | Tempo limite em milissegundos para a primeira consulta aguardar na sincronização inicial de skills quando `CLAUDE_CODE_SYNC_SKILLS` está definido (padrão: 5000). Quando excedido, a consulta prossegue e os downloads de skill restantes continuam em segundo plano |274| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | Tempo limite em milissegundos para a primeira consulta aguardar na sincronização inicial de skills quando `CLAUDE_CODE_SYNC_SKILLS` está definido (padrão: 5000). Quando excedido, a consulta prossegue e os downloads de skill restantes continuam em segundo plano |

263| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Defina como `false` para desabilitar destaque de sintaxe na saída de diff. Útil quando cores interferem com sua configuração de terminal. Para também desabilitar destaque em blocos de código e visualizações de arquivo, use a configuração [`syntaxHighlightingDisabled`](/pt/settings) |275| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | Defina como `false` para desabilitar destaque de sintaxe na saída de diff. Útil quando cores interferem com sua configuração de terminal. Para também desabilitar destaque em blocos de código e visualizações de arquivo, use a configuração [`syntaxHighlightingDisabled`](/pt/settings) |

264| `CLAUDE_CODE_TASK_LIST_ID` | Compartilhe uma lista de tarefas entre sessões. Defina o mesmo ID em múltiplas instâncias do Claude Code para coordenar em uma lista de tarefas compartilhada. Veja [Lista de tarefas](/pt/interactive-mode#task-list) |276| `CLAUDE_CODE_TASK_LIST_ID` | Compartilhe uma lista de tarefas entre sessões. Defina o mesmo ID em múltiplas instâncias do Claude Code para coordenar em uma lista de tarefas compartilhada. Veja [Lista de tarefas](/pt/interactive-mode#task-list) |

265| `CLAUDE_CODE_TEAM_NAME` | Nome da equipe de agentes à qual este companheiro pertence. Definido automaticamente em membros de [equipe de agentes](/pt/agent-teams) |277| `CLAUDE_CODE_TEAM_NAME` | Nome da equipe de agentes à qual este companheiro pertence. Definido automaticamente em membros de [equipe de agentes](/pt/agent-teams) |

266| `CLAUDE_CODE_TMPDIR` | Substitua o diretório temporário usado para arquivos temporários internos. Claude Code acrescenta `/claude-{uid}/` em Unix ou `/claude/` no Windows a este caminho. Padrão: `/tmp` em macOS, `os.tmpdir()` em Linux e Windows. {/* min-version: 2.1.161 */}A partir de v2.1.161, em macOS e Linux, subprocessos Bash recebem um fallback `$TMPDIR` curto sob o padrão do sistema quando sua substituição é um caminho longo, já que algumas ferramentas falham quando caminhos temporários ficam muito longos. Os próprios arquivos temporários do Claude Code sempre usam sua substituição |278| `CLAUDE_CODE_TMPDIR` | Substitua o diretório temporário usado para arquivos temporários internos. Claude Code acrescenta `/claude-{uid}/` em Unix ou `/claude/` no Windows a este caminho. Padrão: `/tmp` em macOS, `os.tmpdir()` em Linux e Windows. {/* min-version: 2.1.161 */}A partir de v2.1.161, em macOS e Linux, subprocessos Bash [sandboxed](/pt/sandboxing) recebem um fallback `$TMPDIR` curto sob o padrão do sistema quando sua substituição é um caminho longo, já que algumas ferramentas falham quando caminhos temporários ficam muito longos. Comandos Bash não sandboxed herdam seu `$TMPDIR` de shell inalterado. Os próprios arquivos temporários do Claude Code sempre usam sua substituição |

267| `CLAUDE_CODE_TMUX_TRUECOLOR` | Defina como `1` para permitir saída truecolor de 24 bits dentro de tmux. Por padrão, Claude Code limita a 256 cores quando `$TMUX` está definido porque tmux não passa sequências de escape truecolor a menos que esteja configurado para isso. Defina isso após adicionar `set -ga terminal-overrides ',*:Tc'` ao seu `~/.tmux.conf`. Veja [Configuração de terminal](/pt/terminal-config) para outras configurações de tmux |279| `CLAUDE_CODE_TMUX_TRUECOLOR` | Defina como `1` para permitir saída truecolor de 24 bits dentro de tmux. Por padrão, Claude Code limita a 256 cores quando `$TMUX` está definido porque tmux não passa sequências de escape truecolor a menos que esteja configurado para isso. Defina isso após adicionar `set -ga terminal-overrides ',*:Tc'` ao seu `~/.tmux.conf`. Veja [Configuração de terminal](/pt/terminal-config) para outras configurações de tmux |

268| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | Use [Claude Platform on AWS](/pt/claude-platform-on-aws) |280| `CLAUDE_CODE_USE_ANTHROPIC_AWS` | Use [Claude Platform on AWS](/pt/claude-platform-on-aws) |

269| `CLAUDE_CODE_USE_BEDROCK` | Use [Bedrock](/pt/amazon-bedrock) |281| `CLAUDE_CODE_USE_BEDROCK` | Use [Bedrock](/pt/amazon-bedrock) |


274| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/pt/google-vertex-ai) |286| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/pt/google-vertex-ai) |

275| `CLAUDE_CONFIG_DIR` | Substitua o diretório de configuração (padrão: `~/.claude`). Todas as configurações, credenciais, histórico de sessão e plugins são armazenados sob este caminho. Útil para executar múltiplas contas lado a lado: por exemplo, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |287| `CLAUDE_CONFIG_DIR` | Substitua o diretório de configuração (padrão: `~/.claude`). Todas as configurações, credenciais, histórico de sessão e plugins são armazenados sob este caminho. Útil para executar múltiplas contas lado a lado: por exemplo, `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

276| `CLAUDE_EFFORT` | Definido automaticamente em subprocessos de ferramenta Bash e comandos hook para o [nível de esforço](/pt/model-config#adjust-effort-level) ativo para a volta: `low`, `medium`, `high`, `xhigh` ou `max`. Ultracode não é um nível distinto e relata como `xhigh`. Corresponde ao campo `effort.level` passado para [hooks](/pt/hooks). Apenas definido quando o modelo atual suporta o parâmetro de esforço |288| `CLAUDE_EFFORT` | Definido automaticamente em subprocessos de ferramenta Bash e comandos hook para o [nível de esforço](/pt/model-config#adjust-effort-level) ativo para a volta: `low`, `medium`, `high`, `xhigh` ou `max`. Ultracode não é um nível distinto e relata como `xhigh`. Corresponde ao campo `effort.level` passado para [hooks](/pt/hooks). Apenas definido quando o modelo atual suporta o parâmetro de esforço |

277| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Defina como `1` para forçar a habilitação do watchdog ocioso de nível de byte, ou defina como `0` para forçar a desabilitação. Quando não definido, o watchdog é habilitado por padrão para conexões da API Anthropic. O watchdog de byte aborta uma conexão quando nenhum byte chega no fio pela duração definida por `CLAUDE_STREAM_IDLE_TIMEOUT_MS`, com um mínimo de 5 minutos, independente do watchdog de nível de evento |289| `CLAUDE_ENABLE_BYTE_WATCHDOG` | Defina como `1` para forçar a habilitação do watchdog ocioso de nível de byte, ou defina como `0` para forçar a desabilitação. Quando não definido, o watchdog é habilitado por padrão para conexões diretas da API Anthropic e [Claude Platform on AWS](/pt/claude-platform-on-aws). O watchdog de byte aborta uma conexão quando nenhum byte chega no fio por 180 segundos por padrão em conexões diretas da API Anthropic, 300 segundos em Claude Platform on AWS e quando habilitado em Bedrock, ou para o valor de `CLAUDE_STREAM_IDLE_TIMEOUT_MS` quando isso está definido, que é fixado a um mínimo de 5 minutos, independente do watchdog de nível de evento |

278| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Defina como `1` para habilitar o watchdog ocioso de streaming de nível de byte em respostas `vnd.amazon.eventstream` do Amazon Bedrock. Desativado por padrão. Configure o tempo limite com `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |290| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | Defina como `1` para habilitar o watchdog ocioso de streaming de nível de byte em respostas `vnd.amazon.eventstream` do Amazon Bedrock. Desativado por padrão. Configure o tempo limite com `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |

279| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Defina como `1` para habilitar o watchdog ocioso de streaming de nível de evento. Desativado por padrão. Aplica-se a todos os provedores, incluindo Bedrock. Para Vertex e Foundry, este é o único watchdog ocioso disponível. Em Bedrock, você também pode habilitar o watchdog de nível de byte independente com `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK`; os dois funcionam juntos quando ambos estão definidos. Configure o tempo limite com `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |291| `CLAUDE_ENABLE_STREAM_WATCHDOG` | Defina como `1` para forçar a habilitação do watchdog ocioso de streaming de nível de evento, ou defina como `0` para forçar a desabilitação. Quando não definido, o padrão é controlado pelo servidor na API Anthropic direta e desativado em outros provedores. {/* min-version: 2.1.169 */}A partir de v2.1.169, provedores diferentes da API Anthropic direta e Claude Platform on AWS também têm um tempo limite de inatividade de corpo padrão de 5 minutos independente desta variável; veja `API_FORCE_IDLE_TIMEOUT`. Em Bedrock, você também pode habilitar o watchdog de nível de byte independente com `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK`; os dois funcionam juntos quando ambos estão definidos. Configure o tempo limite com `CLAUDE_STREAM_IDLE_TIMEOUT_MS` |

280| `CLAUDE_ENV_FILE` | Caminho para um script de shell cujo conteúdo Claude Code executa antes de cada comando Bash no mesmo processo de shell, para que as exportações no arquivo sejam visíveis para o comando. Use para persistir ativação de virtualenv ou conda entre comandos. Também preenchido dinamicamente por hooks [SessionStart](/pt/hooks#persist-environment-variables), [Setup](/pt/hooks#setup), [CwdChanged](/pt/hooks#cwdchanged) e [FileChanged](/pt/hooks#filechanged) |292| `CLAUDE_ENV_FILE` | Caminho para um script de shell cujo conteúdo Claude Code executa antes de cada comando Bash no mesmo processo de shell, para que as exportações no arquivo sejam visíveis para o comando. Use para persistir ativação de virtualenv ou conda entre comandos. Também preenchido dinamicamente por hooks [SessionStart](/pt/hooks#persist-environment-variables), [Setup](/pt/hooks#setup), [CwdChanged](/pt/hooks#cwdchanged) e [FileChanged](/pt/hooks#filechanged) |

281| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Prefixo para nomes de sessão [Remote Control](/pt/remote-control) gerados automaticamente quando nenhum nome explícito é fornecido. Padrão é o nome do host da sua máquina, produzindo nomes como `myhost-graceful-unicorn`. A flag CLI `--remote-control-session-name-prefix` define o mesmo valor para uma única invocação |293| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | Prefixo para nomes de sessão [Remote Control](/pt/remote-control) gerados automaticamente quando nenhum nome explícito é fornecido. Padrão é o nome do host da sua máquina, produzindo nomes como `myhost-graceful-unicorn`. A flag CLI `--remote-control-session-name-prefix` define o mesmo valor para uma única invocação |

282| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Tempo limite em milissegundos antes que o watchdog ocioso de streaming feche uma conexão travada. Padrão e mínimo `300000` (5 minutos) para ambos os watchdogs de nível de byte e de nível de evento; valores mais baixos são silenciosamente fixados para absorver pausas de pensamento estendido e buffering de proxy. Para provedores de terceiros, requer `CLAUDE_ENABLE_STREAM_WATCHDOG=1`. Em Bedrock, também se aplica quando `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` |294| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Tempo limite em milissegundos antes que o watchdog ocioso de streaming feche uma conexão travada. Quando você define esta variável explicitamente, o mínimo é `300000` (5 minutos); valores mais baixos são silenciosamente fixados para absorver pausas de pensamento estendido e buffering de proxy. Quando não definido, o watchdog de nível de evento padrão é 300 segundos e o watchdog de nível de byte padrão é 180 segundos em conexões diretas da API Anthropic (300 segundos em Claude Platform on AWS e outros provedores). O padrão de 180 segundos do watchdog de byte não definido é um valor separado e não está sujeito ao clamp de 5 minutos. Para o watchdog de nível de evento em provedores de terceiros, requer `CLAUDE_ENABLE_STREAM_WATCHDOG=1`; o tempo limite de inatividade de corpo descrito em `API_FORCE_IDLE_TIMEOUT` se aplica independentemente. Em Bedrock, também se aplica quando `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` |

283| `DEBUG` | Defina como `1` para habilitar modo de depuração, equivalente a iniciar com [`--debug`](/pt/cli-reference#cli-flags). Logs de depuração são escritos em `~/.claude/debug/<session-id>.txt`, ou no caminho definido por `CLAUDE_CODE_DEBUG_LOGS_DIR`. Apenas os valores verdadeiros `1`, `true`, `yes` e `on` habilitam modo de depuração, então padrões de namespace como `DEBUG=express:*` definidos para outras ferramentas não o acionam |295| `DEBUG` | Defina como `1` para habilitar modo de depuração, equivalente a iniciar com [`--debug`](/pt/cli-reference#cli-flags). Logs de depuração são escritos em `~/.claude/debug/<session-id>.txt`, ou no caminho definido por `CLAUDE_CODE_DEBUG_LOGS_DIR`. Apenas os valores verdadeiros `1`, `true`, `yes` e `on` habilitam modo de depuração, então padrões de namespace como `DEBUG=express:*` definidos para outras ferramentas não o acionam |

284| `DISABLE_AUTOUPDATER` | Defina como `1` para desabilitar atualizações automáticas em segundo plano. Manual `claude update` ainda funciona. Use `DISABLE_UPDATES` para bloquear ambos |296| `DISABLE_AUTOUPDATER` | Defina como `1` para desabilitar atualizações automáticas em segundo plano. Manual `claude update` ainda funciona. Use `DISABLE_UPDATES` para bloquear ambos |

285| `DISABLE_AUTO_COMPACT` | Defina como `1` para desabilitar compactação automática ao se aproximar do limite de contexto. O comando manual `/compact` permanece disponível. Use quando você deseja controle explícito sobre quando a compactação ocorre |297| `DISABLE_AUTO_COMPACT` | Defina como `1` para desabilitar compactação automática ao se aproximar do limite de contexto. O comando manual `/compact` permanece disponível. Use quando você deseja controle explícito sobre quando a compactação ocorre |


296| `DISABLE_LOGIN_COMMAND` | Defina como `1` para ocultar o comando `/login`. Útil quando a autenticação é tratada externamente via chaves de API ou `apiKeyHelper` |308| `DISABLE_LOGIN_COMMAND` | Defina como `1` para ocultar o comando `/login`. Útil quando a autenticação é tratada externamente via chaves de API ou `apiKeyHelper` |

297| `DISABLE_LOGOUT_COMMAND` | Defina como `1` para ocultar o comando `/logout` |309| `DISABLE_LOGOUT_COMMAND` | Defina como `1` para ocultar o comando `/logout` |

298| `DISABLE_PROMPT_CACHING` | Defina como `1` para desabilitar [prompt caching](/pt/prompt-caching#disable-prompt-caching) para todos os modelos (tem precedência sobre configurações por modelo) |310| `DISABLE_PROMPT_CACHING` | Defina como `1` para desabilitar [prompt caching](/pt/prompt-caching#disable-prompt-caching) para todos os modelos (tem precedência sobre configurações por modelo) |

311| `DISABLE_PROMPT_CACHING_FABLE` | Defina como `1` para desabilitar prompt caching para modelos Fable |

299| `DISABLE_PROMPT_CACHING_HAIKU` | Defina como `1` para desabilitar prompt caching para modelos Haiku |312| `DISABLE_PROMPT_CACHING_HAIKU` | Defina como `1` para desabilitar prompt caching para modelos Haiku |

300| `DISABLE_PROMPT_CACHING_OPUS` | Defina como `1` para desabilitar prompt caching para modelos Opus |313| `DISABLE_PROMPT_CACHING_OPUS` | Defina como `1` para desabilitar prompt caching para modelos Opus |

301| `DISABLE_PROMPT_CACHING_SONNET` | Defina como `1` para desabilitar prompt caching para modelos Sonnet |314| `DISABLE_PROMPT_CACHING_SONNET` | Defina como `1` para desabilitar prompt caching para modelos Sonnet |


307| `ENABLE_PROMPT_CACHING_1H` | Defina como `1` para solicitar um TTL de cache de prompt de 1 hora em vez do padrão de 5 minutos. Destinado para usuários de chave de API, [Bedrock](/pt/amazon-bedrock), [Vertex](/pt/google-vertex-ai), [Foundry](/pt/microsoft-foundry) e [Claude Platform on AWS](/pt/claude-platform-on-aws). Usuários de assinatura recebem TTL de 1 hora automaticamente. Escritas de cache de 1 hora são cobradas a uma taxa mais alta |320| `ENABLE_PROMPT_CACHING_1H` | Defina como `1` para solicitar um TTL de cache de prompt de 1 hora em vez do padrão de 5 minutos. Destinado para usuários de chave de API, [Bedrock](/pt/amazon-bedrock), [Vertex](/pt/google-vertex-ai), [Foundry](/pt/microsoft-foundry) e [Claude Platform on AWS](/pt/claude-platform-on-aws). Usuários de assinatura recebem TTL de 1 hora automaticamente. Escritas de cache de 1 hora são cobradas a uma taxa mais alta |

308| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Descontinuado. Use `ENABLE_PROMPT_CACHING_1H` em vez disso |321| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | Descontinuado. Use `ENABLE_PROMPT_CACHING_1H` em vez disso |

309| `ENABLE_TOOL_SEARCH` | Controla [busca de ferramentas MCP](/pt/mcp#scale-with-mcp-tool-search). Não definido: todas as ferramentas MCP adiadas por padrão, mas carregadas antecipadamente em Vertex AI ou quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte. Valores: `true` (sempre adia e envia o cabeçalho beta, solicitações falham em modelos Vertex AI anteriores a Sonnet 4.5 ou Opus 4.5, ou em proxies que não suportam `tool_reference`), `auto` (modo de limite: carrega antecipadamente se as ferramentas se encaixarem em 10% do contexto), `auto:N` (limite personalizado, por exemplo, `auto:5` para 5%), `false` (carrega tudo antecipadamente) |322| `ENABLE_TOOL_SEARCH` | Controla [busca de ferramentas MCP](/pt/mcp#scale-with-mcp-tool-search). Não definido: todas as ferramentas MCP adiadas por padrão, mas carregadas antecipadamente em Vertex AI ou quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte. Valores: `true` (sempre adia e envia o cabeçalho beta, solicitações falham em modelos Vertex AI anteriores a Sonnet 4.5 ou Opus 4.5, ou em proxies que não suportam `tool_reference`), `auto` (modo de limite: carrega antecipadamente se as ferramentas se encaixarem em 10% do contexto), `auto:N` (limite personalizado, por exemplo, `auto:5` para 5%), `false` (carrega tudo antecipadamente) |

310| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Defina como qualquer valor não vazio para acionador fallback para [`--fallback-model`](/pt/cli-reference#cli-flags) após erros de sobrecarga repetidos em qualquer modelo primário. Por padrão, apenas modelos Opus acionam o fallback |323| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | Defina como qualquer valor não vazio para fazer todos os modelos, não apenas Opus, parar de tentar novamente com um erro de sobrecarga repetido quando nenhum modelo fallback está configurado. {/* min-version: 2.1.160 */}A partir de v2.1.160, uma [cadeia de modelo fallback](/pt/model-config#fallback-model-chains) configurada aciona em erros de sobrecarga repetidos para qualquer modelo primário, então esta variável não afeta a alternância para um modelo fallback |

311| `FORCE_AUTOUPDATE_PLUGINS` | Defina como `1` para forçar auto-atualizações de plugins mesmo quando o auto-atualizador principal está desabilitado via `DISABLE_AUTOUPDATER` |324| `FORCE_AUTOUPDATE_PLUGINS` | Defina como `1` para forçar auto-atualizações de plugins mesmo quando o auto-atualizador principal está desabilitado via `DISABLE_AUTOUPDATER` |

312| `FORCE_PROMPT_CACHING_5M` | Defina como `1` para forçar o TTL de cache de prompt de 5 minutos mesmo quando o TTL de 1 hora se aplicaria de outra forma. Substitui `ENABLE_PROMPT_CACHING_1H` |325| `FORCE_PROMPT_CACHING_5M` | Defina como `1` para forçar o TTL de cache de prompt de 5 minutos mesmo quando o TTL de 1 hora se aplicaria de outra forma. Substitui `ENABLE_PROMPT_CACHING_1H` |

313| `HTTP_PROXY` | Especifique servidor proxy HTTP para conexões de rede |326| `HTTP_PROXY` | Especifique servidor proxy HTTP para conexões de rede |


315| `IS_DEMO` | Defina como `1` para habilitar modo demo: oculta seu email e nome da organização do cabeçalho e saída `/status`, e pula onboarding. Útil ao fazer streaming ou gravar uma sessão |328| `IS_DEMO` | Defina como `1` para habilitar modo demo: oculta seu email e nome da organização do cabeçalho e saída `/status`, e pula onboarding. Útil ao fazer streaming ou gravar uma sessão |

316| `MAX_MCP_OUTPUT_TOKENS` | Número máximo de tokens permitidos em respostas de ferramentas MCP. Claude Code exibe um aviso quando a saída excede 10.000 tokens. Ferramentas que declaram [`anthropic/maxResultSizeChars`](/pt/mcp#raise-the-limit-for-a-specific-tool) usam esse limite de caracteres para conteúdo de texto em vez disso, mas conteúdo de imagem dessas ferramentas ainda está sujeito a essa variável (padrão: 25000) |329| `MAX_MCP_OUTPUT_TOKENS` | Número máximo de tokens permitidos em respostas de ferramentas MCP. Claude Code exibe um aviso quando a saída excede 10.000 tokens. Ferramentas que declaram [`anthropic/maxResultSizeChars`](/pt/mcp#raise-the-limit-for-a-specific-tool) usam esse limite de caracteres para conteúdo de texto em vez disso, mas conteúdo de imagem dessas ferramentas ainda está sujeito a essa variável (padrão: 25000) |

317| `MAX_STRUCTURED_OUTPUT_RETRIES` | Número de vezes para tentar novamente quando a resposta do modelo falha na validação contra o [`--json-schema`](/pt/cli-reference#cli-flags) em modo não interativo (a flag `-p`). Padrão é 5 |330| `MAX_STRUCTURED_OUTPUT_RETRIES` | Número de vezes para tentar novamente quando a resposta do modelo falha na validação contra o [`--json-schema`](/pt/cli-reference#cli-flags) em modo não interativo (a flag `-p`). Padrão é 5 |

318| `MAX_THINKING_TOKENS` | Substitua o orçamento de token de [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking). O teto é o [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) do modelo menos um. Defina como `0` para desabilitar pensamento inteiramente. Em modelos com [raciocínio adaptativo](/pt/model-config#adjust-effort-level), o orçamento é ignorado a menos que raciocínio adaptativo seja desabilitado via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |331| `MAX_THINKING_TOKENS` | Substitua o orçamento de token de [pensamento estendido](https://platform.claude.com/docs/en/build-with-claude/extended-thinking). O teto é o [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) do modelo menos um. Defina como `0` para desabilitar pensamento na API Anthropic exceto em Fable 5, que não pode ter pensamento desligado. Em [provedores de terceiros](/pt/third-party-integrations), `0` igualmente omite o parâmetro, e modelos com [raciocínio adaptativo](/pt/model-config#adjust-effort-level) ainda podem pensar. Para valores diferentes de zero em modelos de raciocínio adaptativo, o orçamento é ignorado a menos que raciocínio adaptativo seja desabilitado via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |

319| `MCP_CLIENT_SECRET` | Segredo do cliente OAuth para servidores MCP que requerem [credenciais pré-configuradas](/pt/mcp#use-pre-configured-oauth-credentials). Evita o prompt interativo ao adicionar um servidor com `--client-secret` |332| `MCP_CLIENT_SECRET` | Segredo do cliente OAuth para servidores MCP que requerem [credenciais pré-configuradas](/pt/mcp#use-pre-configured-oauth-credentials). Evita o prompt interativo ao adicionar um servidor com `--client-secret` |

320| `MCP_CONNECTION_NONBLOCKING` | Controla se a inicialização aguarda servidores MCP se conectarem antes da primeira consulta. {/* min-version: 2.1.142 */}A partir do Claude Code v2.1.142, a inicialização MCP é não-bloqueante por padrão: servidores se conectam em segundo plano e suas ferramentas ficam disponíveis conforme terminam. Defina como `0` para restaurar a espera de conexão bloqueante de 5 segundos. Servidores configurados com [`alwaysLoad: true`](/pt/mcp#exempt-a-server-from-deferral) ainda bloqueiam a inicialização independentemente, já que suas ferramentas devem estar presentes quando o primeiro prompt é construído |333| `MCP_CONNECTION_NONBLOCKING` | Controla se a inicialização aguarda servidores MCP se conectarem antes da primeira consulta. {/* min-version: 2.1.142 */}A partir do Claude Code v2.1.142, a inicialização MCP é não-bloqueante por padrão: servidores se conectam em segundo plano e suas ferramentas ficam disponíveis conforme terminam. Defina como `0` para restaurar a espera de conexão bloqueante de 5 segundos. Servidores configurados com [`alwaysLoad: true`](/pt/mcp#exempt-a-server-from-deferral) ainda bloqueiam a inicialização independentemente, já que suas ferramentas devem estar presentes quando o primeiro prompt é construído |

321| `MCP_CONNECT_TIMEOUT_MS` | Quanto tempo a inicialização bloqueante MCP aguarda, em milissegundos, para o lote de conexão antes de tirar um snapshot da lista de ferramentas (padrão: 5000). Aplica-se quando `MCP_CONNECTION_NONBLOCKING=0` ou para servidores marcados [`alwaysLoad: true`](/pt/mcp#exempt-a-server-from-deferral). Servidores ainda pendentes no prazo continuam se conectando em segundo plano mas não aparecerão até a próxima consulta. Distinto de `MCP_TIMEOUT`, que limita a tentativa de conexão de um servidor individual |334| `MCP_CONNECT_TIMEOUT_MS` | Quanto tempo a inicialização bloqueante MCP aguarda, em milissegundos, para o lote de conexão antes de tirar um snapshot da lista de ferramentas (padrão: 5000). Aplica-se quando `MCP_CONNECTION_NONBLOCKING=0` ou para servidores marcados [`alwaysLoad: true`](/pt/mcp#exempt-a-server-from-deferral). Servidores ainda pendentes no prazo continuam se conectando em segundo plano mas não aparecerão até a próxima consulta. Distinto de `MCP_TIMEOUT`, que limita a tentativa de conexão de um servidor individual |


323| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP remotos (HTTP/SSE) para conectar em paralelo durante a inicialização (padrão: 20) |336| `MCP_REMOTE_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP remotos (HTTP/SSE) para conectar em paralelo durante a inicialização (padrão: 20) |

324| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP locais (stdio) para conectar em paralelo durante a inicialização (padrão: 3) |337| `MCP_SERVER_CONNECTION_BATCH_SIZE` | Número máximo de servidores MCP locais (stdio) para conectar em paralelo durante a inicialização (padrão: 3) |

325| `MCP_TIMEOUT` | Tempo limite em milissegundos para inicialização do servidor MCP (padrão: 30000, ou 30 segundos) |338| `MCP_TIMEOUT` | Tempo limite em milissegundos para inicialização do servidor MCP (padrão: 30000, ou 30 segundos) |

326| `MCP_TOOL_TIMEOUT` | Tempo limite em milissegundos para execução de ferramentas MCP (padrão: 100000000, aproximadamente 28 horas). Um campo `timeout` por servidor em `.mcp.json` substitui isso para esse servidor. Valores abaixo de 1000 são fixados em um segundo |339| `MCP_TOOL_TIMEOUT` | Tempo limite em milissegundos para execução de ferramentas MCP (padrão: 100000000, aproximadamente 28 horas). Um campo `timeout` por servidor em `.mcp.json` substitui isso para esse servidor. Para a variável env, valores abaixo de 1000 são fixados em um segundo; para o campo por servidor, valores abaixo de 1000 são ignorados |

327| `NO_PROXY` | Lista de domínios e IPs para os quais as solicitações serão emitidas diretamente, contornando proxy |340| `NO_PROXY` | Lista de domínios e IPs para os quais as solicitações serão emitidas diretamente, contornando proxy |

328| `OTEL_LOG_RAW_API_BODIES` | Emita solicitação e resposta JSON da API Anthropic Messages como eventos de log `api_request_body` / `api_response_body`. Defina como `1` para corpos inline truncados em 60 KB, ou `file:<dir>` para escrever corpos não truncados em disco e emitir um caminho `body_ref` em vez disso. Desabilitado por padrão; corpos incluem todo o histórico de conversa. Veja [Monitoramento](/pt/monitoring-usage#api-request-body-event) |341| `OTEL_LOG_RAW_API_BODIES` | Emita solicitação e resposta JSON da API Anthropic Messages como eventos de log `api_request_body` / `api_response_body`. Defina como `1` para corpos inline truncados em 60 KB, ou `file:<dir>` para escrever corpos não truncados em disco e emitir um caminho `body_ref` em vez disso. Desabilitado por padrão; corpos incluem todo o histórico de conversa. Veja [Monitoramento](/pt/monitoring-usage#api-request-body-event) |

329| `OTEL_LOG_TOOL_CONTENT` | Defina como `1` para incluir conteúdo de entrada e saída de ferramenta em eventos de span OpenTelemetry. Desabilitado por padrão para proteger dados sensíveis. Veja [Monitoramento](/pt/monitoring-usage) |342| `OTEL_LOG_TOOL_CONTENT` | Defina como `1` para incluir conteúdo de entrada e saída de ferramenta em eventos de span OpenTelemetry. Desabilitado por padrão para proteger dados sensíveis. Veja [Monitoramento](/pt/monitoring-usage) |


348| `VERTEX_REGION_CLAUDE_4_6_OPUS` | Substitua região para Claude Opus 4.6 ao usar Vertex AI |361| `VERTEX_REGION_CLAUDE_4_6_OPUS` | Substitua região para Claude Opus 4.6 ao usar Vertex AI |

349| `VERTEX_REGION_CLAUDE_4_6_SONNET` | Substitua região para Claude Sonnet 4.6 ao usar Vertex AI |362| `VERTEX_REGION_CLAUDE_4_6_SONNET` | Substitua região para Claude Sonnet 4.6 ao usar Vertex AI |

350| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {/* min-version: 2.1.111 */}Substitua região para Claude Opus 4.7 ao usar Vertex AI. Adicionado em v2.1.111 |363| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {/* min-version: 2.1.111 */}Substitua região para Claude Opus 4.7 ao usar Vertex AI. Adicionado em v2.1.111 |

364| `VERTEX_REGION_CLAUDE_4_8_OPUS` | {/* min-version: 2.1.154 */}Substitua região para Claude Opus 4.8 ao usar Vertex AI. Adicionado em v2.1.154 |

365| `VERTEX_REGION_CLAUDE_FABLE_5` | {/* min-version: 2.1.170 */}Substitua região para Claude Fable 5 ao usar Vertex AI. Adicionado em v2.1.170 |

351| `VERTEX_REGION_CLAUDE_HAIKU_4_5` | Substitua região para Claude Haiku 4.5 ao usar Vertex AI |366| `VERTEX_REGION_CLAUDE_HAIKU_4_5` | Substitua região para Claude Haiku 4.5 ao usar Vertex AI |

352 367 

353Variáveis padrão do exportador OpenTelemetry (`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` e variantes específicas de sinal) também são suportadas. Veja [Monitoramento](/pt/monitoring-usage) para detalhes de configuração.368Variáveis padrão do exportador OpenTelemetry (`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_RESOURCE_ATTRIBUTES` e variantes específicas de sinal) também são suportadas. Veja [Monitoramento](/pt/monitoring-usage) para detalhes de configuração.

errors.md +198 −47

Details

14 O Claude Code chama a API Claude para respostas do modelo, portanto, a maioria dos erros de tempo de execução mapeia para um código de erro de API subjacente. Esta página cobre o que cada erro significa dentro do Claude Code e como se recuperar. Para as definições de código de status HTTP bruto, consulte a [referência de erro da plataforma Claude](https://platform.claude.com/docs/pt/api/errors).14 O Claude Code chama a API Claude para respostas do modelo, portanto, a maioria dos erros de tempo de execução mapeia para um código de erro de API subjacente. Esta página cobre o que cada erro significa dentro do Claude Code e como se recuperar. Para as definições de código de status HTTP bruto, consulte a [referência de erro da plataforma Claude](https://platform.claude.com/docs/pt/api/errors).

15</Note>15</Note>

16 16 

17## Encontre seu erro17<h2 id="find-your-error">

18 Encontre seu erro

19</h2>

18 20 

19Corresponda a mensagem que você vê em seu terminal a uma seção abaixo.21Corresponda a mensagem que você vê em seu terminal a uma seção abaixo.

20 22 


26| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |28| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |

27| `Auto mode could not evaluate this action and is blocking it for safety` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |29| `Auto mode could not evaluate this action and is blocking it for safety` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |

28| `Auto mode classifier transcript exceeded context window` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |30| `Auto mode classifier transcript exceeded context window` | [Erros de servidor](#auto-mode-cannot-determine-the-safety-of-an-action) |

29| `You've hit your session limit` / `You've hit your weekly limit` | [Limites de uso](#youve-hit-your-session-limit) |31| `You've hit your session limit` / `You've hit your weekly limit` | [Limites de uso](#you%E2%80%99ve-hit-your-session-limit) |

32| `Usage credits required for 1M context` | [Limites de uso](#usage-credits-required-for-1m-context) |

30| `Server is temporarily limiting requests` | [Limites de uso](#server-is-temporarily-limiting-requests) |33| `Server is temporarily limiting requests` | [Limites de uso](#server-is-temporarily-limiting-requests) |

31| `Request rejected (429)` | [Limites de uso](#request-rejected-429) |34| `Request rejected (429)` | [Limites de uso](#request-rejected-429) |

32| `Credit balance is too low` | [Limites de uso](#credit-balance-is-too-low) |35| `Credit balance is too low` | [Limites de uso](#credit-balance-is-too-low) |

33| `Not logged in · Please run /login` | [Autenticação](#not-logged-in) |36| `Not logged in · Please run /login` | [Autenticação](#not-logged-in) |

37| `Could not resolve authentication method` | [Autenticação](#could-not-resolve-authentication-method) |

34| `Invalid API key` | [Autenticação](#invalid-api-key) |38| `Invalid API key` | [Autenticação](#invalid-api-key) |

35| `This organization has been disabled` | [Autenticação](#this-organization-has-been-disabled) |39| `This organization has been disabled` | [Autenticação](#this-organization-has-been-disabled) |

40| `Your organization has disabled API key authentication` | [Autenticação](#your-organization-has-disabled-api-key-authentication) |

36| `Your organization has disabled Claude subscription access` | [Autenticação](#your-organization-has-disabled-claude-subscription-access) |41| `Your organization has disabled Claude subscription access` | [Autenticação](#your-organization-has-disabled-claude-subscription-access) |

37| `Routines are disabled by your organization's policy` | [Autenticação](#routines-are-disabled-by-your-organizations-policy) |42| `Routines are disabled by your organization's policy` | [Autenticação](#routines-are-disabled-by-your-organization%E2%80%99s-policy) |

38| `OAuth token revoked` / `OAuth token has expired` | [Autenticação](#oauth-token-revoked-or-expired) |43| `OAuth token revoked` / `OAuth token has expired` | [Autenticação](#oauth-token-revoked-or-expired) |

39| `does not meet scope requirement user:profile` | [Autenticação](#oauth-scope-requirement) |44| `does not meet scope requirement user:profile` | [Autenticação](#oauth-scope-requirement) |

40| `Unable to connect to API` | [Rede](#unable-to-connect-to-api) |45| `Unable to connect to API` | [Rede](#unable-to-connect-to-api) |


47| `Unable to resize image` | [Erros de solicitação](#unable-to-resize-image) |52| `Unable to resize image` | [Erros de solicitação](#unable-to-resize-image) |

48| `PDF too large` / `PDF is password protected` | [Erros de solicitação](#pdf-errors) |53| `PDF too large` / `PDF is password protected` | [Erros de solicitação](#pdf-errors) |

49| `Extra inputs are not permitted` | [Erros de solicitação](#extra-inputs-are-not-permitted) |54| `Extra inputs are not permitted` | [Erros de solicitação](#extra-inputs-are-not-permitted) |

50| `There's an issue with the selected model` | [Erros de solicitação](#theres-an-issue-with-the-selected-model) |55| `There's an issue with the selected model` | [Erros de solicitação](#there%E2%80%99s-an-issue-with-the-selected-model) |

51| `Claude Opus is not available with the Claude Pro plan` | [Erros de solicitação](#claude-opus-is-not-available-with-the-claude-pro-plan) |56| `Claude Opus is not available with the Claude Pro plan` | [Erros de solicitação](#claude-opus-is-not-available-with-the-claude-pro-plan) |

52| `thinking.type.enabled is not supported for this model` | [Erros de solicitação](#thinking-type-enabled-is-not-supported-for-this-model) |57| `thinking.type.enabled is not supported for this model` | [Erros de solicitação](#thinking-type-enabled-is-not-supported-for-this-model) |

53| `max_tokens must be greater than thinking.budget_tokens` | [Erros de solicitação](#thinking-budget-exceeds-output-limit) |58| `max_tokens must be greater than thinking.budget_tokens` | [Erros de solicitação](#thinking-budget-exceeds-output-limit) |


55| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Erros de solicitação](#usage-policy-refusal) |60| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Erros de solicitação](#usage-policy-refusal) |

56| Respostas parecem de qualidade inferior ao normal | [Qualidade de resposta](#responses-seem-lower-quality-than-usual) |61| Respostas parecem de qualidade inferior ao normal | [Qualidade de resposta](#responses-seem-lower-quality-than-usual) |

57 62 

58## Tentativas automáticas63<h2 id="automatic-retries">

64 Tentativas automáticas

65</h2>

59 66 

60O Claude Code tenta novamente falhas transitórias antes de mostrar um erro. Erros de servidor, respostas sobrecarregadas, tempos limite de solicitação, throttles 429 temporários e conexões perdidas são todos repetidos até 10 vezes com backoff exponencial. Enquanto tenta novamente, o spinner mostra uma contagem regressiva `Retrying in Ns · attempt x/y`.67O Claude Code tenta novamente falhas transitórias antes de mostrar um erro. Erros de servidor, respostas sobrecarregadas, tempos limite de solicitação, throttles 429 temporários e conexões perdidas são todos repetidos até 10 vezes com backoff exponencial. Enquanto tenta novamente, o spinner mostra uma contagem regressiva `Retrying in Ns · attempt x/y`.

61 68 


66| [`CLAUDE_CODE_MAX_RETRIES`](/pt/env-vars) | 10 | Número de tentativas de repetição. Reduza-o para expor falhas mais rapidamente em scripts; aumente-o para aguardar incidentes mais longos. |73| [`CLAUDE_CODE_MAX_RETRIES`](/pt/env-vars) | 10 | Número de tentativas de repetição. Reduza-o para expor falhas mais rapidamente em scripts; aumente-o para aguardar incidentes mais longos. |

67| [`API_TIMEOUT_MS`](/pt/env-vars) | 600000 | Tempo limite por solicitação em milissegundos. Aumente-o para redes lentas ou proxies. |74| [`API_TIMEOUT_MS`](/pt/env-vars) | 600000 | Tempo limite por solicitação em milissegundos. Aumente-o para redes lentas ou proxies. |

68 75 

69## Erros de servidor76<h2 id="server-errors">

77 Erros de servidor

78</h2>

70 79 

71Esses erros vêm do provedor de inferência em vez de sua conta ou solicitação. Na API Anthropic, isso significa infraestrutura Anthropic. No Bedrock, Vertex AI, Foundry ou um gateway personalizado, significa a infraestrutura desse provedor.80Esses erros vêm do provedor de inferência em vez de sua conta ou solicitação. Na API Anthropic, isso significa infraestrutura Anthropic. No Bedrock, Vertex AI, Foundry ou um gateway personalizado, significa a infraestrutura desse provedor.

72 81 

73### API Error: 500 Internal server error82<h3 id="api-error-500-internal-server-error">

83 API Error: 500 Internal server error

84</h3>

74 85 

75Claude Code mostra o código de status e a mensagem de erro da API para qualquer resposta 5xx. O exemplo abaixo mostra uma resposta 500 na API Anthropic:86Claude Code mostra o código de status e a mensagem de erro da API para qualquer resposta 5xx. O exemplo abaixo mostra uma resposta 500 na API Anthropic:

76 87 


88* Aguarde um minuto e envie sua mensagem novamente. Sua mensagem original ainda está na conversa, portanto, para um prompt longo você pode digitar `try again` em vez de colar tudo novamente.99* Aguarde um minuto e envie sua mensagem novamente. Sua mensagem original ainda está na conversa, portanto, para um prompt longo você pode digitar `try again` em vez de colar tudo novamente.

89* Se o erro persistir sem incidente postado, execute `/feedback` para que a Anthropic possa investigar com os detalhes da sua solicitação. Consulte [Relatar um erro](#report-an-error) se `/feedback` não estiver disponível no seu ambiente.100* Se o erro persistir sem incidente postado, execute `/feedback` para que a Anthropic possa investigar com os detalhes da sua solicitação. Consulte [Relatar um erro](#report-an-error) se `/feedback` não estiver disponível no seu ambiente.

90 101 

91### API Error: Repeated 529 Overloaded errors102<h3 id="api-error-repeated-529-overloaded-errors">

103 API Error: Repeated 529 Overloaded errors

104</h3>

92 105 

93A API está temporariamente em capacidade máxima em todos os usuários. Claude Code já tentou novamente várias vezes antes de mostrar esta mensagem:106A API está temporariamente em capacidade máxima em todos os usuários. Claude Code já tentou novamente várias vezes antes de mostrar esta mensagem:

94 107 


104* Tente novamente em alguns minutos117* Tente novamente em alguns minutos

105* Execute `/model` e mude para um modelo diferente para continuar trabalhando, já que a capacidade é rastreada por modelo. Claude Code o solicita fazer isso quando um modelo está sob carga particularmente alta, por exemplo `Opus is experiencing high load, please use /model to switch to Sonnet`.118* Execute `/model` e mude para um modelo diferente para continuar trabalhando, já que a capacidade é rastreada por modelo. Claude Code o solicita fazer isso quando um modelo está sob carga particularmente alta, por exemplo `Opus is experiencing high load, please use /model to switch to Sonnet`.

106 119 

107### Request timed out120<h3 id="request-timed-out">

121 Request timed out

122</h3>

108 123 

109A API não respondeu antes do prazo de conexão.124A API não respondeu antes do prazo de conexão.

110 125 


121* Se uma rede lenta ou proxy for a causa, aumente `API_TIMEOUT_MS` conforme descrito em [Tentativas automáticas](#automatic-retries)136* Se uma rede lenta ou proxy for a causa, aumente `API_TIMEOUT_MS` conforme descrito em [Tentativas automáticas](#automatic-retries)

122* Se os tempos limite forem frequentes e sua rede estiver saudável, consulte [Erros de rede e conexão](#network-and-connection-errors) abaixo137* Se os tempos limite forem frequentes e sua rede estiver saudável, consulte [Erros de rede e conexão](#network-and-connection-errors) abaixo

123 138 

124### Auto mode cannot determine the safety of an action139<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

140 Auto mode cannot determine the safety of an action

141</h3>

125 142 

126O modelo que [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) usa para classificar ações não conseguiu produzir uma decisão, portanto, o modo automático não aprovou a ação automaticamente. A mensagem que você vê depende do motivo pelo qual o classificador falhou.143O modelo que [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) usa para classificar ações não conseguiu produzir uma decisão, portanto, o modo automático não aprovou a ação automaticamente. A mensagem que você vê depende do motivo pelo qual o classificador falhou.

127 144 


163* Aprove ou negue a ação no prompt que aparece180* Aprove ou negue a ação no prompt que aparece

164* Execute `/compact` para reduzir o tamanho da conversa para que as ações subsequentes se encaixem novamente na janela do classificador181* Execute `/compact` para reduzir o tamanho da conversa para que as ações subsequentes se encaixem novamente na janela do classificador

165 182 

166## Limites de uso183<h2 id="usage-limits">

184 Limites de uso

185</h2>

167 186 

168Esses erros significam que uma cota vinculada à sua conta ou plano foi atingida. Eles são distintos dos [erros de servidor](#server-errors), que afetam todos.187Esses erros significam que uma cota vinculada à sua conta ou plano foi atingida. Eles são distintos dos [erros de servidor](#server-errors), que afetam todos.

169 188 

170### Você atingiu seu limite de sessão189<h3 id="you’ve-hit-your-session-limit">

190 Você atingiu seu limite de sessão

191</h3>

171 192 

172Os planos de assinatura incluem uma permissão de uso contínua. Quando acaba, você vê uma dessas mensagens:193Os planos de assinatura incluem uma permissão de uso contínua. Quando acaba, você vê uma dessas mensagens:

173 194 


188 209 

189Para monitorar sua permissão restante antes de atingir o limite, adicione os campos `rate_limits` a uma [linha de status personalizada](/pt/statusline#rate-limit-usage), ou no aplicativo Desktop clique no [anel de uso](/pt/desktop#check-usage) ao lado do seletor de modelo.210Para monitorar sua permissão restante antes de atingir o limite, adicione os campos `rate_limits` a uma [linha de status personalizada](/pt/statusline#rate-limit-usage), ou no aplicativo Desktop clique no [anel de uso](/pt/desktop#check-usage) ao lado do seletor de modelo.

190 211 

191### O servidor está limitando temporariamente as solicitações212<h3 id="usage-credits-required-for-1m-context">

213 Créditos de uso necessários para contexto de 1M

214</h3>

215 

216O modelo selecionado usa a janela de contexto estendida de 1M tokens, e seu plano inclui apenas através de créditos de uso.

217 

218```text theme={null}

219API Error: Usage credits required for 1M context · run /usage-credits to turn them on, or /model to switch to standard context

220```

221 

222Esta é uma verificação de direito, não um esgotamento de cota. Ela é acionada mesmo quando suas permissões de sessão e semanais têm capacidade restante. Consulte [Extended context](/pt/model-config#extended-context) para saber quais planos incluem contexto de 1M diretamente e quais exigem créditos de uso.

223 

224{/* min-version: 2.1.172 */}Quando este erro aparece no meio da conversa porque o contexto cresceu além de 200K tokens, Claude Code compacta automaticamente a conversa de volta para o limite de contexto padrão e mantém a sessão nesse limite depois, portanto nenhuma ação é necessária. Em versões anteriores à v2.1.172, o erro se repetia em cada solicitação subsequente, incluindo `/compact`; execute `/clear` nessas versões para recuperar. Os passos abaixo se aplicam quando você selecionou explicitamente um modelo `[1m]`.

225 

226**O que fazer:**

227 

228* Execute `/model` e selecione a variante sem o sufixo `[1m]` para voltar à janela de contexto padrão

229* Execute `/usage-credits` para ativar a cobrança medida para a variante de 1M em Pro e Max, ou para solicitá-la ao seu administrador em Team e Enterprise

230* Se o erro persistir após `/model`, uma ID de modelo de 1M pode estar definida em outro lugar. Consulte [There's an issue with the selected model](#there%E2%80%99s-an-issue-with-the-selected-model) para os locais de configuração a verificar em ordem de prioridade.

231* Para remover variantes de 1M do seletor de modelo completamente, defina [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/pt/env-vars)

232 

233<h3 id="server-is-temporarily-limiting-requests">

234 O servidor está limitando temporariamente as solicitações

235</h3>

192 236 

193A API aplicou um throttle de curta duração que não está relacionado à sua cota de plano.237A API aplicou um throttle de curta duração que não está relacionado à sua cota de plano.

194 238 


203* Aguarde brevemente e tente novamente247* Aguarde brevemente e tente novamente

204* Verifique [status.claude.com](https://status.claude.com) se persistir248* Verifique [status.claude.com](https://status.claude.com) se persistir

205 249 

206### Solicitação rejeitada (429)250<h3 id="request-rejected-429">

251 Solicitação rejeitada (429)

252</h3>

207 253 

208Você atingiu o limite de taxa configurado para sua chave de API, projeto Amazon Bedrock ou projeto Google Vertex AI.254Você atingiu o limite de taxa configurado para sua chave de API, projeto Amazon Bedrock ou projeto Google Vertex AI.

209 255 


220* Para chaves de API Anthropic, consulte a [referência de limites de taxa](https://platform.claude.com/docs/en/api/rate-limits) para saber como os níveis funcionam e como definir limites por workspace266* Para chaves de API Anthropic, consulte a [referência de limites de taxa](https://platform.claude.com/docs/en/api/rate-limits) para saber como os níveis funcionam e como definir limites por workspace

221* Reduza a concorrência: reduza [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/pt/env-vars), evite executar muitos subagentes paralelos ou mude para um modelo menor com `/model` para execuções de script de alto volume267* Reduza a concorrência: reduza [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/pt/env-vars), evite executar muitos subagentes paralelos ou mude para um modelo menor com `/model` para execuções de script de alto volume

222 268 

223### Saldo de crédito muito baixo269<h3 id="credit-balance-is-too-low">

270 Saldo de crédito muito baixo

271</h3>

224 272 

225Sua organização Console ficou sem créditos pré-pagos.273Sua organização Console ficou sem créditos pré-pagos.

226 274 


234* Mude para autenticação de assinatura com `/login` se você tiver um plano Pro, Max, Team ou Enterprise282* Mude para autenticação de assinatura com `/login` se você tiver um plano Pro, Max, Team ou Enterprise

235* Defina limites de gastos por workspace no Console para evitar que um único projeto drene o saldo da organização. Consulte [Manage costs effectively](/pt/costs).283* Defina limites de gastos por workspace no Console para evitar que um único projeto drene o saldo da organização. Consulte [Manage costs effectively](/pt/costs).

236 284 

237## Erros de autenticação285<h2 id="authentication-errors">

286 Erros de autenticação

287</h2>

238 288 

239Esses erros significam que o Claude Code não pode provar quem você é para a API. Execute `/status` a qualquer momento para ver qual credencial está ativa no momento.289Esses erros significam que o Claude Code não pode provar quem você é para a API. Execute `/status` a qualquer momento para ver qual credencial está ativa no momento.

240 290 

241### Not logged in291<h3 id="not-logged-in">

292 Not logged in

293</h3>

242 294 

243Nenhuma credencial válida está disponível para esta sessão.295Nenhuma credencial válida está disponível para esta sessão.

244 296 


255 307 

256Se você for solicitado a fazer login repetidamente, consulte [Not logged in or token expired](/pt/troubleshoot-install#not-logged-in-or-token-expired) para correções de relógio do sistema e Keychain do macOS.308Se você for solicitado a fazer login repetidamente, consulte [Not logged in or token expired](/pt/troubleshoot-install#not-logged-in-or-token-expired) para correções de relógio do sistema e Keychain do macOS.

257 309 

258### Invalid API key310<h3 id="could-not-resolve-authentication-method">

311 Could not resolve authentication method

312</h3>

313 

314A sessão atingiu o cliente da API sem nenhuma credencial. Isso aparece em [background sessions](/pt/agent-view), sessões em nuvem e contextos do Agent SDK onde a verificação de login interativo não é executada antes da primeira solicitação.

315 

316```text theme={null}

317Could not resolve authentication method. Expected one of apiKey, authToken, credentials, config, or profile to be set. Or for one of the "X-Api-Key" or "Authorization" headers to be explicitly omitted

318```

319 

320{/* min-version: 2.1.174 */}Antes da v2.1.174, uma sessão em background ou em nuvem atribuída a um worker pré-inicializado ocioso poderia falhar dessa forma mesmo quando credenciais válidas estavam configuradas. Atualize para recuperar. Nas versões atuais, o erro significa que nenhuma credencial estava disponível para o processo do worker.

321 

322**O que fazer:**

323 

324* Atualize para v2.1.174 ou posterior se isso aparecer em uma sessão em background ou em nuvem e suas credenciais já estão configuradas

325* Confirme que `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` ou suas credenciais do provedor de nuvem estão definidas no ambiente que inicia o worker, não apenas no seu shell interativo

326* Para o Agent SDK, consulte [authentication setup](/pt/agent-sdk/overview#get-started)

327* Execute `/status` em uma sessão interativa no mesmo ambiente para confirmar qual fonte de credencial é resolvida

328 

329<h3 id="invalid-api-key">

330 Invalid API key

331</h3>

259 332 

260A variável de ambiente `ANTHROPIC_API_KEY` ou script `apiKeyHelper` retornou uma chave que a API rejeitou.333A variável de ambiente `ANTHROPIC_API_KEY` ou script `apiKeyHelper` retornou uma chave que a API rejeitou.

261 334 


271* Se a chave vem de um script [`apiKeyHelper`](/pt/settings#available-settings), execute o script diretamente para confirmar que ele imprime uma chave válida em stdout344* Se a chave vem de um script [`apiKeyHelper`](/pt/settings#available-settings), execute o script diretamente para confirmar que ele imprime uma chave válida em stdout

272* Execute `/status` para confirmar qual fonte de credencial o Claude Code está realmente usando345* Execute `/status` para confirmar qual fonte de credencial o Claude Code está realmente usando

273 346 

274### This organization has been disabled347<h3 id="this-organization-has-been-disabled">

348 This organization has been disabled

349</h3>

275 350 

276Uma `ANTHROPIC_API_KEY` obsoleta de uma organização Console desabilitada está substituindo seu login de assinatura.351Uma `ANTHROPIC_API_KEY` obsoleta de uma organização Console desabilitada está substituindo seu login de assinatura.

277 352 


288* Execute `/status` depois para confirmar que a credencial ativa é sua assinatura363* Execute `/status` depois para confirmar que a credencial ativa é sua assinatura

289* Se nenhuma variável de ambiente estiver definida e o erro persistir, a organização desabilitada é a vinculada ao seu `/login`. Entre em contato com o suporte ou faça login com uma conta diferente.364* Se nenhuma variável de ambiente estiver definida e o erro persistir, a organização desabilitada é a vinculada ao seu `/login`. Entre em contato com o suporte ou faça login com uma conta diferente.

290 365 

291### Your organization has disabled Claude subscription access366<h3 id="your-organization-has-disabled-api-key-authentication">

367 Your organization has disabled API key authentication

368</h3>

369 

370O administrador da sua organização Console desativou a autenticação por chave de API, portanto a API rejeita a chave que o Claude Code está enviando. A dica de recuperação após o `·` varia dependendo de onde a chave veio:

371 

372```text theme={null}

373Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account

374Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead

375Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account

376Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

377```

378 

379As variáveis de ambiente e `apiKeyHelper` têm precedência sobre `/login`, portanto, executar apenas `/login` não ajuda enquanto qualquer um deles ainda estiver fornecendo uma chave. Consulte [Authentication precedence](/pt/authentication#authentication-precedence).

380 

381**O que fazer:**

382 

383* Se a mensagem mencionar `ANTHROPIC_API_KEY`, desdefina-a no shell atual e remova-a do seu perfil de shell ou arquivo `.env`, depois relance `claude`

384* Se a mensagem mencionar `apiKeyHelper`, remova a configuração [`apiKeyHelper`](/pt/settings#available-settings) do seu `settings.json`

385* Execute `/login` para fazer login com sua conta claude.ai

386* Execute `/status` depois para confirmar que a credencial ativa é sua assinatura em vez de uma chave de API

387* Se você precisar de autenticação por chave de API para automação, peça ao administrador da sua organização para reabilitá-la no Console

388 

389<h3 id="your-organization-has-disabled-claude-subscription-access">

390 Your organization has disabled Claude subscription access

391</h3>

292 392 

293Sua organização Claude não permite fazer login no Claude Code com um login de assinatura. Executar `/login` novamente com a mesma conta retorna o mesmo erro.393Sua organização Claude não permite fazer login no Claude Code com um login de assinatura. Executar `/login` novamente com a mesma conta retorna o mesmo erro.

294 394 


304* Autentique-se com uma chave de API do Console em vez de sua assinatura. Consulte [Claude Console authentication](/pt/authentication#claude-console-authentication) para configuração.404* Autentique-se com uma chave de API do Console em vez de sua assinatura. Consulte [Claude Console authentication](/pt/authentication#claude-console-authentication) para configuração.

305* Se você é o administrador e não vê uma opção para ativar o acesso, entre em contato com o [suporte da Anthropic](https://support.claude.com)405* Se você é o administrador e não vê uma opção para ativar o acesso, entre em contato com o [suporte da Anthropic](https://support.claude.com)

306 406 

307### Routines are disabled by your organization's policy407<h3 id="routines-are-disabled-by-your-organizations-policy">

408 Routines are disabled by your organization's policy

409</h3>

308 410 

309Seu administrador de Team ou Enterprise desativou rotinas no nível da organização. O erro aparece quando você tenta criar ou executar uma rotina, incluindo de `/schedule` e da interface de usuário [Routines](/pt/routines) em claude.ai/code.411Seu administrador de Team ou Enterprise desativou rotinas no nível da organização. O erro aparece quando você tenta criar ou executar uma rotina, incluindo de `/schedule` e da interface de usuário [Routines](/pt/routines) em claude.ai/code.

310 412 


319* Peça ao seu administrador para ativar o toggle **Routines** em [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)421* Peça ao seu administrador para ativar o toggle **Routines** em [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)

320* Para trabalho agendado único que não requer rotinas no nível da organização, consulte [scheduled tasks](/pt/scheduled-tasks)422* Para trabalho agendado único que não requer rotinas no nível da organização, consulte [scheduled tasks](/pt/scheduled-tasks)

321 423 

322### OAuth token revoked or expired424<h3 id="oauth-token-revoked-or-expired">

425 OAuth token revoked or expired

426</h3>

323 427 

324Seu login salvo não é mais válido. Um token revogado significa que você se desconectou em todos os lugares ou um administrador removeu o acesso; um token expirado significa que a atualização automática falhou no meio da sessão.428Seu login salvo não é mais válido. Um token revogado significa que você se desconectou em todos os lugares ou um administrador removeu o acesso; um token expirado significa que a atualização automática falhou no meio da sessão.

325 429 


336* Para prompts repetidos de login entre inicializações, consulte as verificações de relógio do sistema e Keychain do macOS em [Troubleshooting](/pt/troubleshoot-install#not-logged-in-or-token-expired)440* Para prompts repetidos de login entre inicializações, consulte as verificações de relógio do sistema e Keychain do macOS em [Troubleshooting](/pt/troubleshoot-install#not-logged-in-or-token-expired)

337* Para outras falhas incluindo `403 Forbidden` e problemas de navegador OAuth, consulte [Login and authentication](/pt/troubleshoot-install#login-and-authentication)441* Para outras falhas incluindo `403 Forbidden` e problemas de navegador OAuth, consulte [Login and authentication](/pt/troubleshoot-install#login-and-authentication)

338 442 

339### OAuth scope requirement443<h3 id="oauth-scope-requirement">

444 OAuth scope requirement

445</h3>

340 446 

341O token armazenado é anterior a um escopo de permissão que um recurso mais novo precisa. Você vê isso com mais frequência em `/usage` e no indicador de uso da linha de status:447O token armazenado é anterior a um escopo de permissão que um recurso mais novo precisa. Você vê isso com mais frequência em `/usage` e no indicador de uso da linha de status:

342 448 


348 454 

349* Execute `/login` para criar um novo token com os escopos atuais. Você não precisa fazer logout primeiro.455* Execute `/login` para criar um novo token com os escopos atuais. Você não precisa fazer logout primeiro.

350 456 

351## Erros de rede e conexão457<h2 id="network-and-connection-errors">

458 Erros de rede e conexão

459</h2>

352 460 

353Esses erros significam que uma solicitação de rede do Claude Code não conseguiu alcançar seu destino. Eles geralmente se originam em sua rede local, proxy ou firewall, ou na política de rede do ambiente em nuvem.461Esses erros significam que uma solicitação de rede do Claude Code não conseguiu alcançar seu destino. Eles geralmente se originam em sua rede local, proxy ou firewall, ou na política de rede do ambiente em nuvem.

354 462 

355### Unable to connect to API463<h3 id="unable-to-connect-to-api">

464 Unable to connect to API

465</h3>

356 466 

357A conexão TCP com a API falhou ou nunca foi concluída.467A conexão TCP com a API falhou ou nunca foi concluída.

358 468 


381* No macOS, um cliente VPN que foi desconectado ou desinstalado pode deixar uma interface de túnel ou regra de roteamento para trás. Verifique `ifconfig` para interfaces `utun` obsoletas e remova a extensão de rede da VPN em Configurações do Sistema.491* No macOS, um cliente VPN que foi desconectado ou desinstalado pode deixar uma interface de túnel ou regra de roteamento para trás. Verifique `ifconfig` para interfaces `utun` obsoletas e remova a extensão de rede da VPN em Configurações do Sistema.

382* Docker Desktop e runtimes de contêiner semelhantes podem interceptar tráfego de saída. Saia deles e tente novamente para descartar isso.492* Docker Desktop e runtimes de contêiner semelhantes podem interceptar tráfego de saída. Saia deles e tente novamente para descartar isso.

383 493 

384### SSL certificate errors494<h3 id="ssl-certificate-errors">

495 SSL certificate errors

496</h3>

385 497 

386Um proxy ou dispositivo de segurança em sua rede está interceptando tráfego TLS com seu próprio certificado, e o Claude Code não confia nele.498Um proxy ou dispositivo de segurança em sua rede está interceptando tráfego TLS com seu próprio certificado, e o Claude Code não confia nele.

387 499 


396* Consulte [Network configuration](/pt/network-config#custom-ca-certificates) para instruções de configuração completas508* Consulte [Network configuration](/pt/network-config#custom-ca-certificates) para instruções de configuração completas

397* Não defina `NODE_TLS_REJECT_UNAUTHORIZED=0`, que desabilita completamente a validação de certificado509* Não defina `NODE_TLS_REJECT_UNAUTHORIZED=0`, que desabilita completamente a validação de certificado

398 510 

399### Host not allowed in a cloud session511<h3 id="host-not-allowed-in-a-cloud-session">

512 Host not allowed in a cloud session

513</h3>

400 514 

401Uma solicitação HTTP de saída de uma sessão em nuvem ou rotina foi bloqueada pela política de rede do ambiente.515Uma solicitação HTTP de saída de uma sessão em nuvem ou rotina foi bloqueada pela política de rede do ambiente.

402 516 


417 531 

418Consulte [Network access](/pt/claude-code-on-the-web#network-access) para níveis de acesso e a lista de permissões padrão. As sessões locais da CLI não são afetadas por essa política.532Consulte [Network access](/pt/claude-code-on-the-web#network-access) para níveis de acesso e a lista de permissões padrão. As sessões locais da CLI não são afetadas por essa política.

419 533 

420## Erros de solicitação534<h2 id="request-errors">

535 Erros de solicitação

536</h2>

421 537 

422Esses erros significam que a API recebeu sua solicitação mas rejeitou seu conteúdo.538Esses erros significam que a API recebeu sua solicitação mas rejeitou seu conteúdo.

423 539 

424### Prompt is too long540<h3 id="prompt-is-too-long">

541 Prompt is too long

542</h3>

425 543 

426A conversa mais arquivos anexados excedem a janela de contexto do modelo.544A conversa mais arquivos anexados excedem a janela de contexto do modelo.

427 545 


440 558 

441Consulte [Explore the context window](/pt/context-window) para uma visualização interativa de como o contexto se preenche.559Consulte [Explore the context window](/pt/context-window) para uma visualização interativa de como o contexto se preenche.

442 560 

443### Error during compaction: Conversation too long561<h3 id="error-during-compaction-conversation-too-long">

562 Error during compaction: Conversation too long

563</h3>

444 564 

445`/compact` em si falhou porque não há contexto livre suficiente para manter o resumo que produz.565`/compact` em si falhou porque não há contexto livre suficiente para manter o resumo que produz.

446 566 


455* Pressione Esc duas vezes para abrir a lista de mensagens e voltar vários turnos. Isso remove as mensagens mais recentes do contexto. Depois execute `/compact` novamente.575* Pressione Esc duas vezes para abrir a lista de mensagens e voltar vários turnos. Isso remove as mensagens mais recentes do contexto. Depois execute `/compact` novamente.

456* Se voltar não liberar espaço suficiente, execute `/clear` para iniciar uma sessão nova. Sua conversa anterior é preservada e pode ser reabierta com `/resume`.576* Se voltar não liberar espaço suficiente, execute `/clear` para iniciar uma sessão nova. Sua conversa anterior é preservada e pode ser reabierta com `/resume`.

457 577 

458### Request too large578<h3 id="request-too-large">

579 Request too large

580</h3>

459 581 

460O corpo da solicitação bruta excedeu o limite de bytes da API antes da tokenização, geralmente por causa de um arquivo ou anexo grande colado.582O corpo da solicitação bruta excedeu o limite de bytes da API antes da tokenização, geralmente por causa de um arquivo ou anexo grande colado.

461 583 


471* Referencie arquivos grandes por caminho em vez de colar seu conteúdo, para que Claude possa lê-los em pedaços593* Referencie arquivos grandes por caminho em vez de colar seu conteúdo, para que Claude possa lê-los em pedaços

472* Para imagens, consulte [Image was too large](#image-was-too-large) abaixo594* Para imagens, consulte [Image was too large](#image-was-too-large) abaixo

473 595 

474### Image was too large596<h3 id="image-was-too-large">

597 Image was too large

598</h3>

475 599 

476Uma imagem colada ou anexada excede os limites de tamanho ou dimensão da API.600Uma imagem colada ou anexada excede os limites de tamanho ou dimensão da API.

477 601 


480API Error: 400 ... image dimensions exceed max allowed size604API Error: 400 ... image dimensions exceed max allowed size

481```605```

482 606 

483A imagem permanece no histórico de conversa após o erro, portanto, cada mensagem subsequente falha com o mesmo erro até você removê-la.607{/* min-version: 2.1.142 */}Claude Code substitui a imagem não processável por um espaço reservado de texto e tenta novamente, portanto, as mensagens subsequentes têm sucesso. Em versões anteriores a 2.1.142, uma imagem colada poderia permanecer na conversa e repetir o mesmo erro em cada mensagem subsequente. Para recuperar nessas versões, pressione Esc duas vezes e volte passado o turno onde a imagem foi adicionada.

484 608 

485**O que fazer:**609**O que fazer:**

486 610 

487* Pressione Esc duas vezes e volte passado o turno onde a imagem foi adicionada

488* Redimensione a imagem antes de colar. A API aceita imagens de até 8000 pixels na borda mais longa para uma única imagem, ou 2000 pixels quando muitas imagens estão em contexto.611* Redimensione a imagem antes de colar. A API aceita imagens de até 8000 pixels na borda mais longa para uma única imagem, ou 2000 pixels quando muitas imagens estão em contexto.

489* Faça uma captura de tela mais apertada da região relevante em vez da tela inteira612* Faça uma captura de tela mais apertada da região relevante em vez da tela inteira

490 613 

491### Unable to resize image614<h3 id="unable-to-resize-image">

615 Unable to resize image

616</h3>

492 617 

493Claude Code não conseguiu reduzir a escala de uma imagem anexada antes de enviá-la para a API.618Claude Code não conseguiu reduzir a escala de uma imagem anexada antes de enviá-la para a API.

494 619 


506* Se a mensagem pedir para você converter a imagem, converta-a para PNG, JPEG, GIF ou WebP e anexe-a novamente. Claude Code pode verificar dimensões para esses formatos sem o processador de imagem.631* Se a mensagem pedir para você converter a imagem, converta-a para PNG, JPEG, GIF ou WebP e anexe-a novamente. Claude Code pode verificar dimensões para esses formatos sem o processador de imagem.

507* Se a mensagem relatar um limite de dimensão ou tamanho, redimensione ou recomprima a imagem abaixo desse limite antes de anexar.632* Se a mensagem relatar um limite de dimensão ou tamanho, redimensione ou recomprima a imagem abaixo desse limite antes de anexar.

508 633 

509### PDF errors634<h3 id="pdf-errors">

635 PDF errors

636</h3>

510 637 

511O PDF que você anexou não pôde ser processado.638O PDF que você anexou não pôde ser processado.

512 639 


521* Para PDFs de tamanho excessivo, peça ao Claude para ler um intervalo de páginas com a ferramenta Read em vez de anexar o arquivo inteiro, ou extraia texto com uma ferramenta como `pdftotext` e referencie o arquivo de saída por caminho648* Para PDFs de tamanho excessivo, peça ao Claude para ler um intervalo de páginas com a ferramenta Read em vez de anexar o arquivo inteiro, ou extraia texto com uma ferramenta como `pdftotext` e referencie o arquivo de saída por caminho

522* Para PDFs protegidos ou inválidos, remova a senha ou re-exporte o arquivo de seu aplicativo de origem, depois tente novamente649* Para PDFs protegidos ou inválidos, remova a senha ou re-exporte o arquivo de seu aplicativo de origem, depois tente novamente

523 650 

524### Extra inputs are not permitted651<h3 id="extra-inputs-are-not-permitted">

652 Extra inputs are not permitted

653</h3>

525 654 

526Um proxy ou gateway LLM entre Claude Code e a API removeu o cabeçalho de solicitação `anthropic-beta`, portanto, a API rejeitou campos que dependem dele.655Um proxy ou gateway LLM entre Claude Code e a API removeu o cabeçalho de solicitação `anthropic-beta`, portanto, a API rejeitou campos que dependem dele.

527 656 


538* Configure seu gateway para encaminhar o cabeçalho `anthropic-beta`. Consulte [LLM gateway configuration](/pt/llm-gateway).667* Configure seu gateway para encaminhar o cabeçalho `anthropic-beta`. Consulte [LLM gateway configuration](/pt/llm-gateway).

539* Como fallback, defina [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/pt/env-vars) antes de iniciar. Isso desabilita recursos que requerem o cabeçalho beta para que as solicitações tenham sucesso através de um gateway que não pode encaminhá-lo.668* Como fallback, defina [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/pt/env-vars) antes de iniciar. Isso desabilita recursos que requerem o cabeçalho beta para que as solicitações tenham sucesso através de um gateway que não pode encaminhá-lo.

540 669 

541### There's an issue with the selected model670<h3 id="there’s-an-issue-with-the-selected-model">

671 There's an issue with the selected model

672</h3>

542 673 

543O nome do modelo configurado não foi reconhecido ou sua conta não tem acesso a ele. A partir de v2.1.160, a dica à direita, mostrada aqui em sua forma interativa, varia por superfície.674O nome do modelo configurado não foi reconhecido ou sua conta não tem acesso a ele. A partir de v2.1.160, a dica à direita, mostrada aqui em sua forma interativa, varia por superfície.

544 675 


555* Se o modelo errado continuar voltando na CLI, um ID obsoleto está definido em algum lugar. Verifique em [ordem de prioridade](/pt/model-config#setting-your-model): a flag `--model`, a variável de ambiente `ANTHROPIC_MODEL`, depois o campo `model` em `.claude/settings.local.json`, o `.claude/settings.json` do seu projeto e `~/.claude/settings.json`. Remova o valor obsoleto e Claude Code volta ao padrão da sua conta.686* Se o modelo errado continuar voltando na CLI, um ID obsoleto está definido em algum lugar. Verifique em [ordem de prioridade](/pt/model-config#setting-your-model): a flag `--model`, a variável de ambiente `ANTHROPIC_MODEL`, depois o campo `model` em `.claude/settings.local.json`, o `.claude/settings.json` do seu projeto e `~/.claude/settings.json`. Remova o valor obsoleto e Claude Code volta ao padrão da sua conta.

556* Para implantações Vertex AI, consulte [Vertex AI troubleshooting](/pt/google-vertex-ai#troubleshooting).687* Para implantações Vertex AI, consulte [Vertex AI troubleshooting](/pt/google-vertex-ai#troubleshooting).

557 688 

558### Claude Opus is not available with the Claude Pro plan689<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">

690 Claude Opus is not available with the Claude Pro plan

691</h3>

559 692 

560Seu plano de assinatura ativo não inclui o modelo que você selecionou.693Seu plano de assinatura ativo não inclui o modelo que você selecionou.

561 694 


569* Se você atualizou seu plano recentemente e ainda vê isso, execute `/logout` depois `/login`. O token armazenado reflete seu plano no momento em que você fez login, portanto, atualizar na web não entra em vigor em uma sessão existente até você se re-autenticar.702* Se você atualizou seu plano recentemente e ainda vê isso, execute `/logout` depois `/login`. O token armazenado reflete seu plano no momento em que você fez login, portanto, atualizar na web não entra em vigor em uma sessão existente até você se re-autenticar.

570* Consulte [claude.com/pricing](https://claude.com/pricing) para saber quais modelos cada plano inclui703* Consulte [claude.com/pricing](https://claude.com/pricing) para saber quais modelos cada plano inclui

571 704 

572### thinking.type.enabled is not supported for this model705<h3 id="thinking-type-enabled-is-not-supported-for-this-model">

706 thinking.type.enabled is not supported for this model

707</h3>

573 708 

574Sua versão do Claude Code é mais antiga que o mínimo para Opus 4.7 ou Opus 4.8. A CLI enviou uma configuração de thinking que o modelo não aceita mais.709Sua versão do Claude Code é mais antiga que o mínimo para Opus 4.7 ou Opus 4.8. A CLI enviou uma configuração de thinking que o modelo não aceita mais.

575 710 


583* Se você não conseguir atualizar, execute `/model` e selecione Opus 4.6 ou Sonnet718* Se você não conseguir atualizar, execute `/model` e selecione Opus 4.6 ou Sonnet

584* Se você atingir isso no Agent SDK, consulte [SDK troubleshooting](/pt/agent-sdk/quickstart#troubleshooting)719* Se você atingir isso no Agent SDK, consulte [SDK troubleshooting](/pt/agent-sdk/quickstart#troubleshooting)

585 720 

586### Thinking budget exceeds output limit721<h3 id="thinking-budget-exceeds-output-limit">

722 Thinking budget exceeds output limit

723</h3>

587 724 

588O orçamento de thinking estendido configurado excede o comprimento máximo de resposta, portanto, não há espaço deixado para a resposta real.725O orçamento de thinking estendido configurado excede o comprimento máximo de resposta, portanto, não há espaço deixado para a resposta real.

589 726 


598* Reduza `MAX_THINKING_TOKENS`, ou aumente [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/pt/env-vars) acima do orçamento de thinking735* Reduza `MAX_THINKING_TOKENS`, ou aumente [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/pt/env-vars) acima do orçamento de thinking

599* Consulte [Extended thinking](/pt/model-config#extended-thinking) para saber como o orçamento interage com o comprimento de saída736* Consulte [Extended thinking](/pt/model-config#extended-thinking) para saber como o orçamento interage com o comprimento de saída

600 737 

601### Tool use or thinking block mismatch738<h3 id="tool-use-or-thinking-block-mismatch">

739 Tool use or thinking block mismatch

740</h3>

602 741 

603O histórico de conversa chegou à API em um estado inconsistente, geralmente após uma chamada de ferramenta ser interrompida ou um turno ser editado no meio do fluxo.742O histórico de conversa chegou à API em um estado inconsistente, geralmente após uma chamada de ferramenta ser interrompida ou um turno ser editado no meio do fluxo.

604 743 


615* {/* max-version: 2.1.155 */}Se você está usando Opus 4.7 ou Opus 4.8, execute `claude update` primeiro. Versões anteriores a v2.1.156 podem acionar esse erro durante o uso normal de ferramentas, e `/rewind` não o limpa.754* {/* max-version: 2.1.155 */}Se você está usando Opus 4.7 ou Opus 4.8, execute `claude update` primeiro. Versões anteriores a v2.1.156 podem acionar esse erro durante o uso normal de ferramentas, e `/rewind` não o limpa.

616* Execute `/rewind`, ou pressione Esc duas vezes, para voltar a um checkpoint antes do turno corrompido e continuar de lá. Consulte [Checkpointing](/pt/checkpointing) para saber como os checkpoints são criados e restaurados.755* Execute `/rewind`, ou pressione Esc duas vezes, para voltar a um checkpoint antes do turno corrompido e continuar de lá. Consulte [Checkpointing](/pt/checkpointing) para saber como os checkpoints são criados e restaurados.

617 756 

618### Usage Policy refusal757<h3 id="usage-policy-refusal">

758 Usage Policy refusal

759</h3>

619 760 

620A API recusou responder porque o conteúdo na conversa acionou uma verificação de [Usage Policy](https://www.anthropic.com/legal/aup). A mensagem inclui um ID de Solicitação que você pode citar para suporte se acreditar que a recusa está incorreta.761A API recusou responder porque o conteúdo na conversa acionou uma verificação de [Usage Policy](https://www.anthropic.com/legal/aup). A mensagem inclui um ID de Solicitação que você pode citar para suporte se acreditar que a recusa está incorreta.

621 762 


629 770 

630* Pressione Esc duas vezes ou execute `/rewind` para voltar a um checkpoint antes do turno que acionou a recusa, depois reformule ou tome uma abordagem diferente. Consulte [Checkpointing](/pt/checkpointing).771* Pressione Esc duas vezes ou execute `/rewind` para voltar a um checkpoint antes do turno que acionou a recusa, depois reformule ou tome uma abordagem diferente. Consulte [Checkpointing](/pt/checkpointing).

631* Se você não conseguir identificar qual turno causou, execute `/clear` para iniciar uma conversa nova no mesmo projeto. Sua conversa anterior é preservada em disco e permanece disponível em `/resume`.772* Se você não conseguir identificar qual turno causou, execute `/clear` para iniciar uma conversa nova no mesmo projeto. Sua conversa anterior é preservada em disco e permanece disponível em `/resume`.

632* Em [modo não interativo](/pt/headless) (`-p`), onde rewind não está disponível, tente novamente com um prompt reformulado ou inicie uma nova sessão sem `--continue`.773* Em [modo não interativo](/pt/headless) (`-p`), onde rewind não está disponível, tente novamente com um prompt reformulado em uma nova sessão sem `--continue`. As verificações de política variam por modelo, portanto, mudar para um modelo diferente com `--model` também pode resolver a recusa em alguns casos.

774 

775<h2 id="responses-seem-lower-quality-than-usual">

776 As respostas parecem ter qualidade inferior ao usual

777</h2>

778 

779Se as respostas do Claude parecem menos capazes do que você espera, mas nenhum erro é exibido, a causa geralmente é o estado da conversa em vez do modelo em si. O Claude Code não muda silenciosamente versões de modelo. Ele pode mudar para um modelo fallback em três casos específicos:

633 780 

634## As respostas parecem ter qualidade inferior ao usual781* Um [`--fallback-model`](/pt/cli-reference#cli-flags) configurado assume o controle após um erro de disponibilidade, apenas para esse turno, com um aviso na transcrição

782* Uma verificação de inicialização do Bedrock ou Vertex AI encontra seu modelo padrão indisponível

783* [Automatic model fallback](/pt/model-config#automatic-model-fallback) no Fable 5 move a sessão para o modelo Opus padrão e mostra um aviso na transcrição

635 784 

636Se as respostas do Claude parecem menos capazes do que você espera, mas nenhum erro é exibido, a causa geralmente é o estado da conversa em vez do modelo em si. O Claude Code não muda silenciosamente versões de modelo. Ele pode mudar para um modelo fallback em casos específicos, como uma cota Opus sendo atingida ou um Bedrock ou Vertex AI region não tendo seu modelo; a verificação de seleção de modelo abaixo captura ambos, e [Model configuration](/pt/model-config) explica quando fallback se aplica.785A verificação de seleção de modelo abaixo captura o segundo e terceiro casos; o primeiro aparece como um aviso de transcrição em vez de uma mudança `/model`. [Model configuration](/pt/model-config) explica quando cada fallback se aplica.

637 786 

638Verifique estes primeiro:787Verifique estes primeiro:

639 788 


646 795 

647Se a qualidade ainda parecer incorreta após verificar o acima, execute `/feedback` e descreva o que você esperava versus o que obteve. Feedback enviado dessa forma inclui a transcrição da conversa, que é a forma mais rápida para Anthropic diagnosticar uma regressão real. Consulte [Report an error](#report-an-error) se `/feedback` não estiver disponível no seu ambiente.796Se a qualidade ainda parecer incorreta após verificar o acima, execute `/feedback` e descreva o que você esperava versus o que obteve. Feedback enviado dessa forma inclui a transcrição da conversa, que é a forma mais rápida para Anthropic diagnosticar uma regressão real. Consulte [Report an error](#report-an-error) se `/feedback` não estiver disponível no seu ambiente.

648 797 

649## Relatar um erro798<h2 id="report-an-error">

799 Relatar um erro

800</h2>

650 801 

651Esta página cobre erros da API Claude. Para erros de outros componentes do Claude Code, consulte o guia relevante:802Esta página cobre erros da API Claude. Para erros de outros componentes do Claude Code, consulte o guia relevante:

652 803 

fast-mode.md +4 −4

Details

112 O uso do modo rápido é cobrado diretamente nos créditos de uso, mesmo que você tenha uso restante no seu plano. Isso significa que os tokens do modo rápido não contam contra o uso incluído do seu plano e são cobrados à taxa do modo rápido desde o primeiro token.112 O uso do modo rápido é cobrado diretamente nos créditos de uso, mesmo que você tenha uso restante no seu plano. Isso significa que os tokens do modo rápido não contam contra o uso incluído do seu plano e são cobrados à taxa do modo rápido desde o primeiro token.

113</Note>113</Note>

114 114 

115* **Habilitação de administrador para Teams e Enterprise**: o modo rápido está desativado por padrão para organizações Teams e Enterprise. Um administrador deve explicitamente [ativar o modo rápido](#enable-fast-mode-for-your-organization) antes que os usuários possam acessá-lo.115* **Habilitação de administrador para Team e Enterprise**: o modo rápido está desativado por padrão para organizações Team e Enterprise. Um administrador deve explicitamente [ativar o modo rápido](#enable-fast-mode-for-your-organization) antes que os usuários possam acessá-lo.

116 116 

117<Note>117<Note>

118 Se seu administrador não tiver ativado o modo rápido para sua organização, o comando `/fast` mostrará "Fast mode has been disabled by your organization."118 Se seu administrador não tiver ativado o modo rápido para sua organização, o comando `/fast` mostrará "Fast mode has been disabled by your organization." Se a lista de permissões [`availableModels`](/pt/model-config#restrict-model-selection) da sua organização excluir o modelo Opus do modo rápido, `/fast` é recusado com "is not in your organization's allowed models".

119</Note>119</Note>

120 120 

121<h3 id="enable-fast-mode-for-your-organization">121<h3 id="enable-fast-mode-for-your-organization">


125Os administradores podem ativar o modo rápido em:125Os administradores podem ativar o modo rápido em:

126 126 

127* **Console** (clientes de API): [Preferências do Claude Code](https://platform.claude.com/claude-code/preferences)127* **Console** (clientes de API): [Preferências do Claude Code](https://platform.claude.com/claude-code/preferences)

128* **Claude AI** (Teams e Enterprise): [Admin Settings > Claude Code](https://claude.ai/admin-settings/claude-code)128* **Claude AI** (Team e Enterprise): [Admin Settings > Claude Code](https://claude.ai/admin-settings/claude-code)

129 129 

130Outra opção para desativar completamente o modo rápido é definir `CLAUDE_CODE_DISABLE_FAST_MODE=1`. Consulte [Variáveis de ambiente](/pt/env-vars).130Outra opção para desativar completamente o modo rápido é definir `CLAUDE_CODE_DISABLE_FAST_MODE=1`. Consulte [Variáveis de ambiente](/pt/env-vars).

131 131 


133 Require per-session opt-in133 Require per-session opt-in

134</h3>134</h3>

135 135 

136Por padrão, o modo rápido persiste entre sessões: se um usuário ativa o modo rápido, ele permanece ativado em futuras sessões. Os administradores em planos [Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) ou [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) podem evitar isso definindo `fastModePerSessionOptIn` como `true` em [managed settings](/pt/settings#settings-files) ou [server-managed settings](/pt/server-managed-settings). Isso faz com que cada sessão comece com o modo rápido desativado, exigindo que os usuários o ativem explicitamente com `/fast`.136Por padrão, o modo rápido persiste entre sessões: se um usuário ativa o modo rápido, ele permanece ativado em futuras sessões. Os administradores em planos [Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) ou [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) podem evitar isso definindo `fastModePerSessionOptIn` como `true` em [managed settings](/pt/settings#settings-files) ou [server-managed settings](/pt/server-managed-settings). Isso faz com que cada sessão comece com o modo rápido desativado, exigindo que os usuários o ativem explicitamente com `/fast`.

137 137 

138```json theme={null}138```json theme={null}

139{139{

Details

109 109 

110 **Coloque em uma skill** se for material de referência que Claude precisa às vezes (documentação de API, guias de estilo) ou um fluxo de trabalho que você dispara com `/<name>` (deploy, review, release).110 **Coloque em uma skill** se for material de referência que Claude precisa às vezes (documentação de API, guias de estilo) ou um fluxo de trabalho que você dispara com `/<name>` (deploy, review, release).

111 111 

112 **Regra prática:** Mantenha CLAUDE.md com menos de 200 linhas. Se estiver crescendo, mova conteúdo de referência para skills ou divida em arquivos [`.claude/rules/`](/pt/memory#organize-rules-with-clauderules).112 **Regra prática:** Mantenha CLAUDE.md com menos de 200 linhas. Se estiver crescendo, mova conteúdo de referência para skills ou divida em arquivos [`.claude/rules/`](/pt/memory#organize-rules-with-claude%2Frules%2F).

113 </Tab>113 </Tab>

114 114 

115 <Tab title="CLAUDE.md vs Rules vs Skills">115 <Tab title="CLAUDE.md vs Rules vs Skills">


198 198 

199Os recursos podem ser definidos em múltiplos níveis: em toda a máquina, por projeto, via plugins ou através de políticas gerenciadas. Você também pode aninhar arquivos CLAUDE.md em subdiretórios ou colocar skills em pacotes específicos de um monorepo. Quando o mesmo recurso existe em múltiplos níveis, aqui está como eles se sobrepõem:199Os recursos podem ser definidos em múltiplos níveis: em toda a máquina, por projeto, via plugins ou através de políticas gerenciadas. Você também pode aninhar arquivos CLAUDE.md em subdiretórios ou colocar skills em pacotes específicos de um monorepo. Quando o mesmo recurso existe em múltiplos níveis, aqui está como eles se sobrepõem:

200 200 

201* **Arquivos CLAUDE.md** são aditivos: todos os níveis contribuem conteúdo ao contexto de Claude simultaneamente. Arquivos do seu diretório de trabalho e acima carregam no lançamento; subdiretórios carregam conforme você trabalha neles. Quando as instruções entram em conflito, Claude usa julgamento para reconciliá-las, com instruções mais específicas tipicamente tendo precedência. Consulte [como arquivos CLAUDE.md carregam](/pt/memory#how-claudemd-files-load).201* **Arquivos CLAUDE.md** são aditivos: todos os níveis contribuem conteúdo ao contexto de Claude simultaneamente. Arquivos do seu diretório de trabalho e acima carregam no lançamento; subdiretórios carregam conforme você trabalha neles. Quando as instruções entram em conflito, Claude usa julgamento para reconciliá-las, com instruções mais específicas tipicamente tendo precedência. Consulte [como arquivos CLAUDE.md carregam](/pt/memory#how-claude-md-files-load).

202* **Skills e subagents** substituem por nome: quando o mesmo nome existe em múltiplos níveis, uma definição vence com base na prioridade (gerenciado > usuário > projeto para skills; gerenciado > sinalizador CLI > projeto > usuário > plugin para subagents). Skills de plugin são [nomeadas](/pt/plugins#add-skills-to-your-plugin) para evitar conflitos. Consulte [descoberta de skill](/pt/skills#where-skills-live) e [escopo de subagent](/pt/sub-agents#choose-the-subagent-scope).202* **Skills e subagents** substituem por nome: quando o mesmo nome existe em múltiplos níveis, uma definição vence com base na prioridade (gerenciado > usuário > projeto para skills; gerenciado > sinalizador CLI > projeto > usuário > plugin para subagents). Skills de plugin são [nomeadas](/pt/plugins#add-skills-to-your-plugin) para evitar conflitos. Consulte [descoberta de skill](/pt/skills#where-skills-live) e [escopo de subagent](/pt/sub-agents#choose-the-subagent-scope).

203* **Servidores MCP** substituem por nome: local > projeto > usuário. Consulte [escopo MCP](/pt/mcp#scope-hierarchy-and-precedence).203* **Servidores MCP** substituem por nome: local > projeto > usuário. Consulte [escopo MCP](/pt/mcp#scope-hierarchy-and-precedence).

204* **Hooks** se mesclam: todos os hooks registrados disparam para seus eventos correspondentes independentemente da fonte. Consulte [hooks](/pt/hooks-guide).204* **Hooks** se mesclam: todos os hooks registrados disparam para seus eventos correspondentes independentemente da fonte. Consulte [hooks](/pt/hooks-guide).

fullscreen.md +22 −3

Details

104export CLAUDE_CODE_SCROLL_SPEED=3104export CLAUDE_CODE_SCROLL_SPEED=3

105```105```

106 106 

107Um valor de `3` corresponde ao padrão em `vim` e aplicativos semelhantes. A configuração aceita valores de 1 a 20.107Um valor de `3` corresponde ao padrão em `vim` e aplicativos semelhantes. A configuração aceita valores de 1 a 20, e valores fracionários abaixo de 1, como `0.5`, para desacelerar a rolagem acelerada do trackpad e da roda em terminais que já amplificam eventos de roda.

108 108 

109Para ajustar a velocidade de rolagem interativamente, execute `/scroll-speed`. O diálogo mostra uma régua que você pode rolar enquanto está aberto para que você possa sentir a mudança imediatamente. Pressione `←` e `→` para ajustar, `r` para redefinir para o padrão detectado automaticamente e `Enter` para salvar. O comando escreve o mesmo valor que a variável de ambiente `CLAUDE_CODE_SCROLL_SPEED` define, persistido em `~/.claude/settings.json`. O comando não está disponível no terminal do IDE JetBrains.109Para ajustar a velocidade de rolagem interativamente, execute `/scroll-speed`. O diálogo mostra uma régua que você pode rolar enquanto está aberto para que você possa sentir a mudança imediatamente. Pressione `←` e `→` para ajustar, `r` para redefinir para o padrão detectado automaticamente e `Enter` para salvar. O comando escreve o mesmo valor que a variável de ambiente `CLAUDE_CODE_SCROLL_SPEED` define, persistido em `~/.claude/settings.json`. O comando não está disponível no terminal do IDE JetBrains.

110 110 

111Separadamente da velocidade base, Claude Code acelera a taxa de rolagem quando você gira a roda rapidamente, portanto uma rotação rápida cobre mais distância do que o mesmo número de entalhes lentos. {/* min-version: 2.1.174 */}Para desativar a aceleração e manter uma taxa constante por entalhe, defina `wheelScrollAccelerationEnabled` como `false` em [`settings.json`](/pt/settings#available-settings). Esta configuração requer Claude Code v2.1.174 ou posterior.

112 

111<h3 id="scroll-in-the-jetbrains-ide-terminal">113<h3 id="scroll-in-the-jetbrains-ide-terminal">

112 Rolagem no terminal do IDE JetBrains114 Rolagem no terminal do IDE JetBrains

113</h3>115</h3>


171 173 

172A captura de mouse é o ponto de atrito mais comum, especialmente sobre SSH ou dentro do tmux. Quando Claude Code captura eventos de mouse, a cópia nativa ao selecionar do seu terminal para de funcionar. A seleção que você faz com clique e arraste existe dentro do Claude Code, não no buffer de seleção do seu terminal, portanto o modo de cópia tmux, dicas do Kitty e ferramentas semelhantes não a veem.174A captura de mouse é o ponto de atrito mais comum, especialmente sobre SSH ou dentro do tmux. Quando Claude Code captura eventos de mouse, a cópia nativa ao selecionar do seu terminal para de funcionar. A seleção que você faz com clique e arraste existe dentro do Claude Code, não no buffer de seleção do seu terminal, portanto o modo de cópia tmux, dicas do Kitty e ferramentas semelhantes não a veem.

173 175 

174Claude Code tenta escrever a seleção na sua área de transferência, mas o caminho que usa depende da sua configuração. Dentro do tmux, escreve no buffer de colagem do tmux. Sobre SSH, volta para sequências de escape OSC 52, que alguns terminais bloqueiam por padrão. O iTerm2 bloqueia até que você ative Configurações → Geral → Seleção → Aplicativos no terminal podem acessar a área de transferência. Executar [`/terminal-setup`](/pt/terminal-config) no iTerm2 ativa isso para você. Claude Code imprime um toast após cada cópia informando qual caminho foi usado.176Claude Code escreve a seleção na sua área de transferência do sistema, e o caminho que usa depende da sua configuração. Em uma sessão local, ele executa uma ferramenta de área de transferência nativa:

177 

178* **macOS**: `pbcopy`

179* **Linux**: `wl-copy` no Wayland, ou `xclip` ou `xsel` no X11, o que estiver instalado. Claude Code escreve tanto a área de transferência quanto a seleção PRIMARY, portanto a colagem com clique do meio funciona.

180* **Windows e WSL**: PowerShell `Set-Clipboard`

181 

182Dentro do tmux, também escreve no buffer de colagem do tmux. Sobre SSH, volta para sequências de escape OSC 52. Claude Code imprime um toast após cada cópia informando qual caminho foi usado.

183 

184Alguns terminais bloqueiam OSC 52 por padrão. O iTerm2 bloqueia até que você ative Configurações → Geral → Seleção → Aplicativos no terminal podem acessar a área de transferência; executar [`/terminal-setup`](/pt/terminal-config) no iTerm2 ativa isso para você.

185 

186Para uma seleção nativa única, a tecla a usar depende do seu terminal:

187 

188* **Terminal.app**: `Fn`

189* **iTerm2**: `Option`

190* **VS Code, Cursor e Devin Desktop**: `Shift`, ou `Option` no macOS com a configuração `terminal.integrated.macOptionClickForcesSelection` ativada

191* **Maioria dos outros terminais**: `Shift`

192 

193Mantenha essa tecla pressionada enquanto clica e arrasta. Seu terminal manipula a seleção em si em vez de passá-la para Claude Code, portanto atalhos de cópia como `Cmd+C` funcionam no que você seleciona. Claude Code também mostra a tecla correta em sua dica na tela.

175 194 

176Para uma seleção nativa única, mantenha pressionada a tecla modificadora de bypass do seu terminal enquanto clica e arrasta: `Option` no iTerm2, ou `Shift` na maioria dos terminais Linux e Windows. O modificador diz ao seu terminal para manipular a seleção em si em vez de encaminhar eventos de mouse para Claude Code, portanto `Cmd+C` e outros atalhos de cópia do seu terminal funcionam nela.195Sobre SSH ou dentro do tmux, Claude Code nem sempre consegue detectar o terminal do qual você está se conectando, portanto a dica lista as teclas candidatas em vez disso.

177 196 

178Se você depender da seleção nativa o tempo todo, defina `CLAUDE_CODE_DISABLE_MOUSE=1` para optar por não participar da captura de mouse mantendo a renderização sem cintilação e memória plana:197Se você depender da seleção nativa o tempo todo, defina `CLAUDE_CODE_DISABLE_MOUSE=1` para optar por não participar da captura de mouse mantendo a renderização sem cintilação e memória plana:

179 198 

github-actions.md +102 −38

Details

12 Claude Code GitHub Actions é construído sobre o [Claude Agent SDK](/pt/agent-sdk/overview), que permite integração programática do Claude Code em suas aplicações. Você pode usar o SDK para construir fluxos de trabalho de automação personalizados além do GitHub Actions.12 Claude Code GitHub Actions é construído sobre o [Claude Agent SDK](/pt/agent-sdk/overview), que permite integração programática do Claude Code em suas aplicações. Você pode usar o SDK para construir fluxos de trabalho de automação personalizados além do GitHub Actions.

13</Note>13</Note>

14 14 

15<Info>15<h2 id="why-use-claude-code-github-actions">

16 **Claude Opus 4.8 agora está disponível.** Claude Code GitHub Actions usa Sonnet por padrão. Para usar Opus 4.8, configure o [parâmetro de modelo](#breaking-changes-reference) para usar `claude-opus-4-8`.16 Por que usar Claude Code GitHub Actions?

17</Info>17</h2>

18 

19## Por que usar Claude Code GitHub Actions?

20 18 

21* **Criação instantânea de PR**: Descreva o que você precisa, e Claude cria um PR completo com todas as alterações necessárias19* **Criação instantânea de PR**: Descreva o que você precisa, e Claude cria um PR completo com todas as alterações necessárias

22* **Implementação de código automatizada**: Transforme issues em código funcional com um único comando20* **Implementação de código automatizada**: Transforme issues em código funcional com um único comando


24* **Configuração simples**: Comece em minutos com nosso instalador e chave de API22* **Configuração simples**: Comece em minutos com nosso instalador e chave de API

25* **Seguro por padrão**: Seu código permanece nos runners do Github23* **Seguro por padrão**: Seu código permanece nos runners do Github

26 24 

27## O que Claude pode fazer?25<h2 id="what-can-claude-do">

26 O que Claude pode fazer?

27</h2>

28 28 

29Claude Code fornece uma poderosa GitHub Action que transforma como você trabalha com código:29Claude Code fornece uma poderosa GitHub Action que transforma como você trabalha com código:

30 30 

31### Claude Code Action31<h3 id="claude-code-action">

32 Claude Code Action

33</h3>

32 34 

33Esta GitHub Action permite que você execute Claude Code dentro de seus fluxos de trabalho do GitHub Actions. Você pode usar isso para construir qualquer fluxo de trabalho personalizado sobre Claude Code.35Esta GitHub Action permite que você execute Claude Code dentro de seus fluxos de trabalho do GitHub Actions. Você pode usar isso para construir qualquer fluxo de trabalho personalizado sobre Claude Code.

34 36 

35[Ver repositório →](https://github.com/anthropics/claude-code-action)37[Ver repositório →](https://github.com/anthropics/claude-code-action)

36 38 

37## Configuração39<h2 id="setup">

40 Configuração

41</h2>

38 42 

39## Configuração rápida43<h2 id="quick-setup">

44 Configuração rápida

45</h2>

40 46 

41A maneira mais fácil de configurar esta action é através do Claude Code no terminal. Basta abrir claude e executar `/install-github-app`.47A maneira mais fácil de configurar esta action é através do Claude Code no terminal. Basta abrir claude e executar `/install-github-app`.

42 48 


48 * Este método de início rápido está disponível apenas para usuários diretos da Claude API. Se você está usando Amazon Bedrock ou Google Vertex AI, consulte a seção [Usando com Amazon Bedrock & Google Vertex AI](#using-with-amazon-bedrock-%26-google-vertex-ai).54 * Este método de início rápido está disponível apenas para usuários diretos da Claude API. Se você está usando Amazon Bedrock ou Google Vertex AI, consulte a seção [Usando com Amazon Bedrock & Google Vertex AI](#using-with-amazon-bedrock-%26-google-vertex-ai).

49</Note>55</Note>

50 56 

51## Configuração manual57<h2 id="manual-setup">

58 Configuração manual

59</h2>

52 60 

53Se o comando `/install-github-app` falhar ou você preferir configuração manual, siga estas instruções de configuração manual:61Se o comando `/install-github-app` falhar ou você preferir configuração manual, siga estas instruções de configuração manual:

54 62 


68 Após concluir a configuração rápida ou manual, teste a action marcando `@claude` em um comentário de issue ou PR.76 Após concluir a configuração rápida ou manual, teste a action marcando `@claude` em um comentário de issue ou PR.

69</Tip>77</Tip>

70 78 

71## Atualizando da versão Beta79<h2 id="upgrading-from-beta">

80 Atualizando da versão Beta

81</h2>

72 82 

73<Warning>83<Warning>

74 Claude Code GitHub Actions v1.0 introduz mudanças significativas que exigem atualizar seus arquivos de fluxo de trabalho para fazer upgrade da versão beta para v1.0.84 Claude Code GitHub Actions v1.0 introduz mudanças significativas que exigem atualizar seus arquivos de fluxo de trabalho para fazer upgrade da versão beta para v1.0.


76 86 

77Se você está usando a versão beta do Claude Code GitHub Actions, recomendamos que você atualize seus fluxos de trabalho para usar a versão GA. A nova versão simplifica a configuração enquanto adiciona recursos poderosos como detecção automática de modo.87Se você está usando a versão beta do Claude Code GitHub Actions, recomendamos que você atualize seus fluxos de trabalho para usar a versão GA. A nova versão simplifica a configuração enquanto adiciona recursos poderosos como detecção automática de modo.

78 88 

79### Mudanças essenciais89<h3 id="essential-changes">

90 Mudanças essenciais

91</h3>

80 92 

81Todos os usuários beta devem fazer essas alterações em seus arquivos de fluxo de trabalho para fazer upgrade:93Todos os usuários beta devem fazer essas alterações em seus arquivos de fluxo de trabalho para fazer upgrade:

82 94 


853. **Atualize as entradas de prompt**: Substitua `direct_prompt` por `prompt`973. **Atualize as entradas de prompt**: Substitua `direct_prompt` por `prompt`

864. **Mova as opções de CLI**: Converta `max_turns`, `model`, `custom_instructions`, etc. para `claude_args`984. **Mova as opções de CLI**: Converta `max_turns`, `model`, `custom_instructions`, etc. para `claude_args`

87 99 

88### Referência de Mudanças Significativas100<h3 id="breaking-changes-reference">

101 Referência de Mudanças Significativas

102</h3>

89 103 

90| Entrada Beta Antiga | Nova Entrada v1.0 |104| Entrada Beta Antiga | Nova Entrada v1.0 |

91| --------------------- | ---------------------------------------- |105| --------------------- | ---------------------------------------- |


99| `disallowed_tools` | `claude_args: --disallowedTools` |113| `disallowed_tools` | `claude_args: --disallowedTools` |

100| `claude_env` | `settings` formato JSON |114| `claude_env` | `settings` formato JSON |

101 115 

102### Exemplo Antes e Depois116<h3 id="before-and-after-example">

117 Exemplo Antes e Depois

118</h3>

103 119 

104**Versão beta:**120**Versão beta:**

105 121 


131 A action agora detecta automaticamente se deve executar em modo interativo (responde a menções `@claude`) ou modo de automação (executa imediatamente com um prompt) com base em sua configuração.147 A action agora detecta automaticamente se deve executar em modo interativo (responde a menções `@claude`) ou modo de automação (executa imediatamente com um prompt) com base em sua configuração.

132</Tip>148</Tip>

133 149 

134## Exemplos de casos de uso150<h2 id="example-use-cases">

151 Exemplos de casos de uso

152</h2>

135 153 

136Claude Code GitHub Actions pode ajudá-lo com uma variedade de tarefas. O [diretório de exemplos](https://github.com/anthropics/claude-code-action/tree/main/examples) contém fluxos de trabalho prontos para uso em diferentes cenários.154Claude Code GitHub Actions pode ajudá-lo com uma variedade de tarefas. O [diretório de exemplos](https://github.com/anthropics/claude-code-action/tree/main/examples) contém fluxos de trabalho prontos para uso em diferentes cenários.

137 155 

138### Fluxo de trabalho básico156<h3 id="basic-workflow">

157 Fluxo de trabalho básico

158</h3>

139 159 

140```yaml theme={null}160```yaml theme={null}

141name: Claude Code161name: Claude Code


154 # Responds to @claude mentions in comments174 # Responds to @claude mentions in comments

155```175```

156 176 

157### Usando skills177<h3 id="using-skills">

178 Usando skills

179</h3>

158 180 

159A entrada `prompt` aceita uma invocação de [skill](/pt/skills) bem como texto simples:181A entrada `prompt` aceita uma invocação de [skill](/pt/skills) bem como texto simples:

160 182 


180 prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"202 prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

181```203```

182 204 

183### Automação personalizada com prompts205<h3 id="custom-automation-with-prompts">

206 Automação personalizada com prompts

207</h3>

184 208 

185```yaml theme={null}209```yaml theme={null}

186name: Daily Report210name: Daily Report


198 claude_args: "--model opus"222 claude_args: "--model opus"

199```223```

200 224 

201### Casos de uso comuns225<h3 id="common-use-cases">

226 Casos de uso comuns

227</h3>

202 228 

203Em comentários de issue ou PR:229Em comentários de issue ou PR:

204 230 


210 236 

211Claude analisará automaticamente o contexto e responderá apropriadamente.237Claude analisará automaticamente o contexto e responderá apropriadamente.

212 238 

213## Melhores práticas239<h2 id="best-practices">

240 Melhores práticas

241</h2>

214 242 

215### Configuração CLAUDE.md243<h3 id="claude-md-configuration">

244 Configuração CLAUDE.md

245</h3>

216 246 

217Crie um arquivo `CLAUDE.md` na raiz do seu repositório para definir diretrizes de estilo de código, critérios de revisão, regras específicas do projeto e padrões preferidos. Este arquivo guia a compreensão de Claude dos padrões do seu projeto.247Crie um arquivo `CLAUDE.md` na raiz do seu repositório para definir diretrizes de estilo de código, critérios de revisão, regras específicas do projeto e padrões preferidos. Este arquivo guia a compreensão de Claude dos padrões do seu projeto.

218 248 

219### Considerações de segurança249<h3 id="security-considerations">

250 Considerações de segurança

251</h3>

220 252 

221<Warning>Nunca faça commit de chaves de API diretamente em seu repositório.</Warning>253<Warning>Nunca faça commit de chaves de API diretamente em seu repositório.</Warning>

222 254 


231 263 

232Sempre use GitHub Secrets (por exemplo, `${{ secrets.ANTHROPIC_API_KEY }}`) em vez de codificar chaves de API diretamente em seus arquivos de fluxo de trabalho.264Sempre use GitHub Secrets (por exemplo, `${{ secrets.ANTHROPIC_API_KEY }}`) em vez de codificar chaves de API diretamente em seus arquivos de fluxo de trabalho.

233 265 

234### Otimizando desempenho266<h3 id="optimizing-performance">

267 Otimizando desempenho

268</h3>

235 269 

236Use templates de issue para fornecer contexto, mantenha seu `CLAUDE.md` conciso e focado, e configure timeouts apropriados para seus fluxos de trabalho.270Use templates de issue para fornecer contexto, mantenha seu `CLAUDE.md` conciso e focado, e configure timeouts apropriados para seus fluxos de trabalho.

237 271 

238### Custos de CI272<h3 id="ci-costs">

273 Custos de CI

274</h3>

239 275 

240Ao usar Claude Code GitHub Actions, esteja ciente dos custos associados:276Ao usar Claude Code GitHub Actions, esteja ciente dos custos associados:

241 277 


257* Defina timeouts no nível do fluxo de trabalho para evitar jobs descontrolados293* Defina timeouts no nível do fluxo de trabalho para evitar jobs descontrolados

258* Considere usar controles de concorrência do GitHub para limitar execuções paralelas294* Considere usar controles de concorrência do GitHub para limitar execuções paralelas

259 295 

260## Exemplos de configuração296<h2 id="configuration-examples">

297 Exemplos de configuração

298</h2>

261 299 

262A Claude Code Action v1 simplifica a configuração com parâmetros unificados:300A Claude Code Action v1 simplifica a configuração com parâmetros unificados:

263 301 


282 Ao responder a comentários de issue ou PR, Claude responde automaticamente a menções @claude. Para outros eventos, use o parâmetro `prompt` para fornecer instruções.320 Ao responder a comentários de issue ou PR, Claude responde automaticamente a menções @claude. Para outros eventos, use o parâmetro `prompt` para fornecer instruções.

283</Tip>321</Tip>

284 322 

285## Usando com Amazon Bedrock & Google Vertex AI323<h2 id="using-with-amazon-bedrock--google-vertex-ai">

324 Usando com Amazon Bedrock & Google Vertex AI

325</h2>

286 326 

287Para ambientes empresariais, você pode usar Claude Code GitHub Actions com sua própria infraestrutura em nuvem. Esta abordagem oferece controle sobre residência de dados e faturamento enquanto mantém a mesma funcionalidade.327Para ambientes empresariais, você pode usar Claude Code GitHub Actions com sua própria infraestrutura em nuvem. Esta abordagem oferece controle sobre residência de dados e faturamento enquanto mantém a mesma funcionalidade.

288 328 

289### Pré-requisitos329<h3 id="prerequisites">

330 Pré-requisitos

331</h3>

290 332 

291Antes de configurar Claude Code GitHub Actions com provedores de nuvem, você precisa:333Antes de configurar Claude Code GitHub Actions com provedores de nuvem, você precisa:

292 334 

293#### Para Google Cloud Vertex AI:335<h4 id="for-google-cloud-vertex-ai">

336 Para Google Cloud Vertex AI:

337</h4>

294 338 

2951. Um Projeto Google Cloud com Vertex AI habilitado3391. Um Projeto Google Cloud com Vertex AI habilitado

2962. Workload Identity Federation configurado para GitHub Actions3402. Workload Identity Federation configurado para GitHub Actions

2973. Uma conta de serviço com as permissões necessárias3413. Uma conta de serviço com as permissões necessárias

2984. Uma GitHub App (recomendado) ou use o GITHUB\_TOKEN padrão3424. Uma GitHub App (recomendado) ou use o GITHUB\_TOKEN padrão

299 343 

300#### Para Amazon Bedrock:344<h4 id="for-amazon-bedrock">

345 Para Amazon Bedrock:

346</h4>

301 347 

3021. Uma conta AWS com Amazon Bedrock habilitado3481. Uma conta AWS com Amazon Bedrock habilitado

3032. GitHub OIDC Identity Provider configurado na AWS3492. GitHub OIDC Identity Provider configurado na AWS


609 </Step>655 </Step>

610</Steps>656</Steps>

611 657 

612## Troubleshooting658<h2 id="troubleshooting">

659 Troubleshooting

660</h2>

613 661 

614### Claude não responde aos comandos @claude662<h3 id="claude-not-responding-to-claude-commands">

663 Claude não responde aos comandos @claude

664</h3>

615 665 

616Verifique se a GitHub App está instalada corretamente, confirme que os fluxos de trabalho estão habilitados, garanta que a chave de API está definida nos secrets do repositório e confirme que o comentário contém `@claude` (não `/claude`).666Verifique se a GitHub App está instalada corretamente, confirme que os fluxos de trabalho estão habilitados, garanta que a chave de API está definida nos secrets do repositório e confirme que o comentário contém `@claude` (não `/claude`).

617 667 

618### CI não está sendo executado nos commits de Claude668<h3 id="ci-not-running-on-claude’s-commits">

669 CI não está sendo executado nos commits de Claude

670</h3>

619 671 

620Garanta que você está usando a GitHub App ou app personalizada (não usuário Actions), verifique se os gatilhos do fluxo de trabalho incluem os eventos necessários e confirme que as permissões da app incluem gatilhos de CI.672Garanta que você está usando a GitHub App ou app personalizada (não usuário Actions), verifique se os gatilhos do fluxo de trabalho incluem os eventos necessários e confirme que as permissões da app incluem gatilhos de CI.

621 673 

622### Erros de autenticação674<h3 id="authentication-errors">

675 Erros de autenticação

676</h3>

623 677 

624Confirme que a chave de API é válida e tem permissões suficientes. Para Bedrock/Vertex, verifique a configuração de credenciais e garanta que os secrets estejam nomeados corretamente nos fluxos de trabalho.678Confirme que a chave de API é válida e tem permissões suficientes. Para Bedrock/Vertex, verifique a configuração de credenciais e garanta que os secrets estejam nomeados corretamente nos fluxos de trabalho.

625 679 

626## Configuração avançada680<h2 id="advanced-configuration">

681 Configuração avançada

682</h2>

627 683 

628### Parâmetros da Action684<h3 id="action-parameters">

685 Parâmetros da Action

686</h3>

629 687 

630A Claude Code Action v1 usa uma configuração simplificada:688A Claude Code Action v1 usa uma configuração simplificada:

631 689 


644\*Prompt é opcional - quando omitido para comentários de issue/PR, Claude responde à frase de gatilho\702\*Prompt é opcional - quando omitido para comentários de issue/PR, Claude responde à frase de gatilho\

645\*\*Necessário para Claude API direto, não para Bedrock/Vertex703\*\*Necessário para Claude API direto, não para Bedrock/Vertex

646 704 

647#### Passe argumentos de CLI705<h4 id="pass-cli-arguments">

706 Passe argumentos de CLI

707</h4>

648 708 

649O parâmetro `claude_args` aceita qualquer argumento de CLI do Claude Code:709O parâmetro `claude_args` aceita qualquer argumento de CLI do Claude Code:

650 710 


660* `--allowedTools`: Lista separada por vírgula de ferramentas permitidas. O alias `--allowed-tools` também funciona.720* `--allowedTools`: Lista separada por vírgula de ferramentas permitidas. O alias `--allowed-tools` também funciona.

661* `--debug`: Habilitar saída de debug721* `--debug`: Habilitar saída de debug

662 722 

663### Métodos de integração alternativos723<h3 id="alternative-integration-methods">

724 Métodos de integração alternativos

725</h3>

664 726 

665Enquanto o comando `/install-github-app` é a abordagem recomendada, você também pode:727Enquanto o comando `/install-github-app` é a abordagem recomendada, você também pode:

666 728 


670 732 

671Consulte a [documentação do Claude Code Action](https://github.com/anthropics/claude-code-action/blob/main/docs) para guias detalhados sobre autenticação, segurança e configuração avançada.733Consulte a [documentação do Claude Code Action](https://github.com/anthropics/claude-code-action/blob/main/docs) para guias detalhados sobre autenticação, segurança e configuração avançada.

672 734 

673### Personalizando o comportamento de Claude735<h3 id="customizing-claude’s-behavior">

736 Personalizando o comportamento de Claude

737</h3>

674 738 

675Você pode configurar o comportamento de Claude de duas maneiras:739Você pode configurar o comportamento de Claude de duas maneiras:

676 740 

Details

205 Instância GHES não acessível205 Instância GHES não acessível

206</h3>206</h3>

207 207 

208Se revisões ou sessões web expirarem, sua instância GHES pode não ser acessível a partir da infraestrutura Anthropic. Confirme se seu firewall permite conexões de entrada dos [endereços IP da API Anthropic](https://platform.claude.com/docs/en/api/ip-addresses).208Se revisões ou sessões web expirarem, sua instância GHES pode não ser acessível a partir da infraestrutura Anthropic. Confirme se seu firewall permite conexões de entrada dos [endereços IP da API Anthropic](https://platform.claude.com/docs/pt/api/ip-addresses).

209 209 

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

211 Recursos relacionados211 Recursos relacionados

gitlab-ci-cd.md +85 −29

Details

16 Esta integração é construída sobre o [Claude Code CLI e Agent SDK](/pt/agent-sdk/overview), permitindo o uso programático do Claude em seus trabalhos de CI/CD e fluxos de trabalho de automação personalizados.16 Esta integração é construída sobre o [Claude Code CLI e Agent SDK](/pt/agent-sdk/overview), permitindo o uso programático do Claude em seus trabalhos de CI/CD e fluxos de trabalho de automação personalizados.

17</Note>17</Note>

18 18 

19## Por que usar Claude Code com GitLab?19<h2 id="why-use-claude-code-with-gitlab">

20 Por que usar Claude Code com GitLab?

21</h2>

20 22 

21* **Criação instantânea de MR**: Descreva o que você precisa, e Claude propõe um MR completo com alterações e explicação23* **Criação instantânea de MR**: Descreva o que você precisa, e Claude propõe um MR completo com alterações e explicação

22* **Implementação automatizada**: Transforme problemas em código funcional com um único comando ou menção24* **Implementação automatizada**: Transforme problemas em código funcional com um único comando ou menção


25* **Pronto para empresas**: Escolha Claude API, Amazon Bedrock ou Google Vertex AI para atender às necessidades de residência de dados e compras27* **Pronto para empresas**: Escolha Claude API, Amazon Bedrock ou Google Vertex AI para atender às necessidades de residência de dados e compras

26* **Seguro por padrão**: Executa em seus executores GitLab com sua proteção de branch e aprovações28* **Seguro por padrão**: Executa em seus executores GitLab com sua proteção de branch e aprovações

27 29 

28## Como funciona30<h2 id="how-it-works">

31 Como funciona

32</h2>

29 33 

30Claude Code usa GitLab CI/CD para executar tarefas de IA em trabalhos isolados e confirmar resultados de volta via MRs:34Claude Code usa GitLab CI/CD para executar tarefas de IA em trabalhos isolados e confirmar resultados de volta via MRs:

31 35 


40 44 

41Escolha endpoints regionais para reduzir latência e atender aos requisitos de soberania de dados enquanto usa acordos de nuvem existentes.45Escolha endpoints regionais para reduzir latência e atender aos requisitos de soberania de dados enquanto usa acordos de nuvem existentes.

42 46 

43## O que Claude pode fazer?47<h2 id="what-can-claude-do">

48 O que Claude pode fazer?

49</h2>

44 50 

45Claude Code permite fluxos de trabalho poderosos de CI/CD que transformam a forma como você trabalha com código:51Claude Code permite fluxos de trabalho poderosos de CI/CD que transformam a forma como você trabalha com código:

46 52 


50* Corrigir bugs e regressões identificados por testes ou comentários56* Corrigir bugs e regressões identificados por testes ou comentários

51* Responder a comentários de acompanhamento para iterar sobre as alterações solicitadas57* Responder a comentários de acompanhamento para iterar sobre as alterações solicitadas

52 58 

53## Configuração59<h2 id="setup">

60 Configuração

61</h2>

54 62 

55### Configuração rápida63<h3 id="quick-setup">

64 Configuração rápida

65</h3>

56 66 

57A forma mais rápida de começar é adicionar um trabalho mínimo ao seu `.gitlab-ci.yml` e definir sua chave de API como uma variável mascarada.67A forma mais rápida de começar é adicionar um trabalho mínimo ao seu `.gitlab-ci.yml` e definir sua chave de API como uma variável mascarada.

58 68 


98Após adicionar o trabalho e sua variável `ANTHROPIC_API_KEY`, teste executando o trabalho manualmente em **CI/CD** → **Pipelines**, ou dispare-o a partir de um MR para deixar Claude propor atualizações em um branch e abrir um MR se necessário.108Após adicionar o trabalho e sua variável `ANTHROPIC_API_KEY`, teste executando o trabalho manualmente em **CI/CD** → **Pipelines**, ou dispare-o a partir de um MR para deixar Claude propor atualizações em um branch e abrir um MR se necessário.

99 109 

100<Note>110<Note>

101 Para executar no Amazon Bedrock ou Google Vertex AI em vez da Claude API, consulte a seção [Usando com Amazon Bedrock & Google Vertex AI](#usando-com-amazon-bedrock--google-vertex-ai) abaixo para configuração de autenticação e ambiente.111 Para executar no Amazon Bedrock ou Google Vertex AI em vez da Claude API, consulte a seção [Usando com Amazon Bedrock & Google Vertex AI](#using-with-amazon-bedrock-%26-google-vertex-ai) abaixo para configuração de autenticação e ambiente.

102</Note>112</Note>

103 113 

104### Configuração manual (recomendada para produção)114<h3 id="manual-setup-recommended-for-production">

115 Configuração manual (recomendada para produção)

116</h3>

105 117 

106Se você preferir uma configuração mais controlada ou precisar de provedores corporativos:118Se você preferir uma configuração mais controlada ou precisar de provedores corporativos:

107 119 


120 * Adicione um webhook de projeto para "Comments (notes)" ao seu ouvinte de eventos (se você usar um)132 * Adicione um webhook de projeto para "Comments (notes)" ao seu ouvinte de eventos (se você usar um)

121 * Faça o ouvinte chamar a API de gatilho de pipeline com variáveis como `AI_FLOW_INPUT` e `AI_FLOW_CONTEXT` quando um comentário contiver `@claude`133 * Faça o ouvinte chamar a API de gatilho de pipeline com variáveis como `AI_FLOW_INPUT` e `AI_FLOW_CONTEXT` quando um comentário contiver `@claude`

122 134 

123## Exemplos de casos de uso135<h2 id="example-use-cases">

136 Exemplos de casos de uso

137</h2>

124 138 

125### Transforme problemas em MRs139<h3 id="turn-issues-into-mrs">

140 Transforme problemas em MRs

141</h3>

126 142 

127Em um comentário de problema:143Em um comentário de problema:

128 144 


132 148 

133Claude analisa o problema e a base de código, escreve alterações em um branch e abre um MR para revisão.149Claude analisa o problema e a base de código, escreve alterações em um branch e abre um MR para revisão.

134 150 

135### Obtenha ajuda de implementação151<h3 id="get-implementation-help">

152 Obtenha ajuda de implementação

153</h3>

136 154 

137Em uma discussão de MR:155Em uma discussão de MR:

138 156 


142 160 

143Claude propõe alterações, adiciona código com cache apropriado e atualiza o MR.161Claude propõe alterações, adiciona código com cache apropriado e atualiza o MR.

144 162 

145### Corrija bugs rapidamente163<h3 id="fix-bugs-quickly">

164 Corrija bugs rapidamente

165</h3>

146 166 

147Em um comentário de problema ou MR:167Em um comentário de problema ou MR:

148 168 


152 172 

153Claude localiza o bug, implementa uma correção e atualiza o branch ou abre um novo MR.173Claude localiza o bug, implementa uma correção e atualiza o branch ou abre um novo MR.

154 174 

155## Usando com Amazon Bedrock & Google Vertex AI175<h2 id="using-with-amazon-bedrock--google-vertex-ai">

176 Usando com Amazon Bedrock & Google Vertex AI

177</h2>

156 178 

157Para ambientes corporativos, você pode executar Claude Code inteiramente em sua infraestrutura de nuvem com a mesma experiência do desenvolvedor.179Para ambientes corporativos, você pode executar Claude Code inteiramente em sua infraestrutura de nuvem com a mesma experiência do desenvolvedor.

158 180 


238 </Tab>260 </Tab>

239</Tabs>261</Tabs>

240 262 

241## Exemplos de configuração263<h2 id="configuration-examples">

264 Exemplos de configuração

265</h2>

242 266 

243Abaixo estão trechos prontos para usar que você pode adaptar ao seu pipeline.267Abaixo estão trechos prontos para usar que você pode adaptar ao seu pipeline.

244 268 

245### .gitlab-ci.yml básico (Claude API)269<h3 id="basic-gitlab-ci-yml-claude-api">

270 .gitlab-ci.yml básico (Claude API)

271</h3>

246 272 

247```yaml theme={null}273```yaml theme={null}

248stages:274stages:


271 # Claude Code usará ANTHROPIC_API_KEY das variáveis de CI/CD297 # Claude Code usará ANTHROPIC_API_KEY das variáveis de CI/CD

272```298```

273 299 

274### Exemplo de trabalho Amazon Bedrock (OIDC)300<h3 id="amazon-bedrock-job-example-oidc">

301 Exemplo de trabalho Amazon Bedrock (OIDC)

302</h3>

275 303 

276**Pré-requisitos:**304**Pré-requisitos:**

277 305 


322 IDs de modelo para Bedrock incluem prefixos específicos de região (por exemplo, `us.anthropic.claude-sonnet-4-6`). Passe o modelo desejado via sua configuração de trabalho ou prompt se seu fluxo de trabalho suportar.350 IDs de modelo para Bedrock incluem prefixos específicos de região (por exemplo, `us.anthropic.claude-sonnet-4-6`). Passe o modelo desejado via sua configuração de trabalho ou prompt se seu fluxo de trabalho suportar.

323</Note>351</Note>

324 352 

325### Exemplo de trabalho Google Vertex AI (Workload Identity Federation)353<h3 id="google-vertex-ai-job-example-workload-identity-federation">

354 Exemplo de trabalho Google Vertex AI (Workload Identity Federation)

355</h3>

326 356 

327**Pré-requisitos:**357**Pré-requisitos:**

328 358 


375 Com Workload Identity Federation, você não precisa armazenar chaves de conta de serviço. Use condições de confiança específicas do repositório e contas de serviço com privilégio mínimo.405 Com Workload Identity Federation, você não precisa armazenar chaves de conta de serviço. Use condições de confiança específicas do repositório e contas de serviço com privilégio mínimo.

376</Note>406</Note>

377 407 

378## Melhores práticas408<h2 id="best-practices">

409 Melhores práticas

410</h2>

379 411 

380### Configuração CLAUDE.md412<h3 id="claude-md-configuration">

413 Configuração CLAUDE.md

414</h3>

381 415 

382Crie um arquivo `CLAUDE.md` na raiz do repositório para definir padrões de codificação, critérios de revisão e regras específicas do projeto. Claude lê este arquivo durante as execuções e segue suas convenções ao propor alterações.416Crie um arquivo `CLAUDE.md` na raiz do repositório para definir padrões de codificação, critérios de revisão e regras específicas do projeto. Claude lê este arquivo durante as execuções e segue suas convenções ao propor alterações.

383 417 

384### Considerações de segurança418<h3 id="security-considerations">

419 Considerações de segurança

420</h3>

385 421 

386**Nunca confirme chaves de API ou credenciais de nuvem em seu repositório**. Sempre use variáveis de CI/CD do GitLab:422**Nunca confirme chaves de API ou credenciais de nuvem em seu repositório**. Sempre use variáveis de CI/CD do GitLab:

387 423 


390* Limite permissões de trabalho e saída de rede426* Limite permissões de trabalho e saída de rede

391* Revise os MRs do Claude como qualquer outro colaborador427* Revise os MRs do Claude como qualquer outro colaborador

392 428 

393### Otimizando desempenho429<h3 id="optimizing-performance">

430 Otimizando desempenho

431</h3>

394 432 

395* Mantenha `CLAUDE.md` focado e conciso433* Mantenha `CLAUDE.md` focado e conciso

396* Forneça descrições claras de problema/MR para reduzir iterações434* Forneça descrições claras de problema/MR para reduzir iterações

397* Configure timeouts de trabalho sensatos para evitar execuções descontroladas435* Configure timeouts de trabalho sensatos para evitar execuções descontroladas

398* Cache npm e instalações de pacotes em executores onde possível436* Cache npm e instalações de pacotes em executores onde possível

399 437 

400### Custos de CI438<h3 id="ci-costs">

439 Custos de CI

440</h3>

401 441 

402Ao usar Claude Code com GitLab CI/CD, esteja ciente dos custos associados:442Ao usar Claude Code com GitLab CI/CD, esteja ciente dos custos associados:

403 443 


415 * Defina valores apropriados de `max_turns` e timeout de trabalho455 * Defina valores apropriados de `max_turns` e timeout de trabalho

416 * Limite concorrência para controlar execuções paralelas456 * Limite concorrência para controlar execuções paralelas

417 457 

418## Segurança e governança458<h2 id="security-and-governance">

459 Segurança e governança

460</h2>

419 461 

420* Cada trabalho é executado em um contêiner isolado com acesso de rede restrito462* Cada trabalho é executado em um contêiner isolado com acesso de rede restrito

421* As alterações do Claude fluem através de MRs para que os revisores vejam cada diff463* As alterações do Claude fluem através de MRs para que os revisores vejam cada diff


423* Claude Code usa permissões com escopo de workspace para restringir gravações465* Claude Code usa permissões com escopo de workspace para restringir gravações

424* Os custos permanecem sob seu controle porque você traz suas próprias credenciais de provedor466* Os custos permanecem sob seu controle porque você traz suas próprias credenciais de provedor

425 467 

426## Solução de problemas468<h2 id="troubleshooting">

469 Solução de problemas

470</h2>

427 471 

428### Claude não responde aos comandos @claude472<h3 id="claude-not-responding-to-claude-commands">

473 Claude não responde aos comandos @claude

474</h3>

429 475 

430* Verifique se seu pipeline está sendo disparado (manualmente, evento de MR ou via ouvinte de nota/webhook)476* Verifique se seu pipeline está sendo disparado (manualmente, evento de MR ou via ouvinte de nota/webhook)

431* Certifique-se de que as variáveis de CI/CD (`ANTHROPIC_API_KEY` ou configurações de provedor de nuvem) estão presentes e desmascaradas477* Certifique-se de que as variáveis de CI/CD (`ANTHROPIC_API_KEY` ou configurações de provedor de nuvem) estão presentes e desmascaradas

432* Verifique se o comentário contém `@claude` (não `/claude`) e se seu gatilho de menção está configurado478* Verifique se o comentário contém `@claude` (não `/claude`) e se seu gatilho de menção está configurado

433 479 

434### O trabalho não consegue escrever comentários ou abrir MRs480<h3 id="job-can’t-write-comments-or-open-mrs">

481 O trabalho não consegue escrever comentários ou abrir MRs

482</h3>

435 483 

436* Certifique-se de que `CI_JOB_TOKEN` tem permissões suficientes para o projeto, ou use um Project Access Token com escopo `api`484* Certifique-se de que `CI_JOB_TOKEN` tem permissões suficientes para o projeto, ou use um Project Access Token com escopo `api`

437* Verifique se a ferramenta `mcp__gitlab` está habilitada em `--allowedTools`485* Verifique se a ferramenta `mcp__gitlab` está habilitada em `--allowedTools`

438* Confirme se o trabalho é executado no contexto do MR ou tem contexto suficiente via variáveis `AI_FLOW_*`486* Confirme se o trabalho é executado no contexto do MR ou tem contexto suficiente via variáveis `AI_FLOW_*`

439 487 

440### Erros de autenticação488<h3 id="authentication-errors">

489 Erros de autenticação

490</h3>

441 491 

442* **Para Claude API**: Confirme que `ANTHROPIC_API_KEY` é válida e não expirou492* **Para Claude API**: Confirme que `ANTHROPIC_API_KEY` é válida e não expirou

443* **Para Bedrock/Vertex**: Verifique configuração de OIDC/WIF, representação de função e nomes de segredos; confirme disponibilidade de região e modelo493* **Para Bedrock/Vertex**: Verifique configuração de OIDC/WIF, representação de função e nomes de segredos; confirme disponibilidade de região e modelo

444 494 

445## Configuração avançada495<h2 id="advanced-configuration">

496 Configuração avançada

497</h2>

446 498 

447### Parâmetros e variáveis comuns499<h3 id="common-parameters-and-variables">

500 Parâmetros e variáveis comuns

501</h3>

448 502 

449Claude Code suporta estas entradas comumente usadas:503Claude Code suporta estas entradas comumente usadas:

450 504 


458 Sinalizadores e parâmetros exatos podem variar por versão de `@anthropic-ai/claude-code`. Execute `claude --help` em seu trabalho para ver as opções suportadas.512 Sinalizadores e parâmetros exatos podem variar por versão de `@anthropic-ai/claude-code`. Execute `claude --help` em seu trabalho para ver as opções suportadas.

459</Note>513</Note>

460 514 

461### Personalizando o comportamento do Claude515<h3 id="customizing-claude’s-behavior">

516 Personalizando o comportamento do Claude

517</h3>

462 518 

463Você pode guiar Claude de duas formas principais:519Você pode guiar Claude de duas formas principais:

464 520 

glossary.md +8 −8

Details

162 Effort level162 Effort level

163</h3>163</h3>

164 164 

165Uma configuração que controla quanto do orçamento de pensamento de raciocínio adaptativo Claude usa em cada turno. Esforço mais alto significa mais tokens de pensamento e raciocínio mais profundo; esforço mais baixo é mais rápido e barato. Effort é suportado em Opus 4.6 e posterior, e em Sonnet 4.6.165Uma configuração que controla quanto do orçamento de pensamento de raciocínio adaptativo Claude usa em cada turno. Esforço mais alto significa mais tokens de pensamento e raciocínio mais profundo; esforço mais baixo é mais rápido e barato. Effort é suportado em Fable 5, em Opus 4.6 e posterior, e em Sonnet 4.6.

166 166 

167Saiba mais: [Adjust effort level](/pt/model-config#adjust-effort-level)167Saiba mais: [Adjust effort level](/pt/model-config#adjust-effort-level)

168 168 


170 Extended thinking170 Extended thinking

171</h3>171</h3>

172 172 

173Raciocínio passo a passo visível que o modelo realiza antes de responder. Você pode limitar tokens de pensamento com `MAX_THINKING_TOKENS` ou ajustar o [effort level](#effort-level). Thinking aparece em texto itálico cinza no terminal.173Raciocínio passo a passo visível que o modelo realiza antes de responder. Você pode ajustá-lo com o [effort level](#effort-level), ou limitar tokens de pensamento com `MAX_THINKING_TOKENS` em modelos com um orçamento de pensamento fixo. Thinking aparece em texto itálico cinza no terminal.

174 174 

175Saiba mais: [Use extended thinking](/pt/model-config#extended-thinking)175Saiba mais: [Use extended thinking](/pt/model-config#extended-thinking)

176 176 


254 254 

255O comportamento de aprovação de linha de base para a sessão. Cicle com `Shift+Tab` na CLI ou use o seletor de modo em VS Code, Desktop e claude.ai. Os modos disponíveis são `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` e `bypassPermissions`.255O comportamento de aprovação de linha de base para a sessão. Cicle com `Shift+Tab` na CLI ou use o seletor de modo em VS Code, Desktop e claude.ai. Os modos disponíveis são `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` e `bypassPermissions`.

256 256 

257Saiba mais: [Choose a permission mode](/pt/permission-modes)257Saiba mais: [Escolha um permission mode](/pt/permission-modes)

258 258 

259<h3 id="permission-rule">259<h3 id="permission-rule">

260 Permission rule260 Permission rule


270 270 

271Um [permission mode](#permission-mode) onde Claude pesquisa e propõe alterações sem editar seus arquivos de origem. Pode ler, pesquisar e executar comandos de exploração, depois apresenta um plano para aprovação antes de tocar em qualquer coisa. Entre em plan mode com `/plan` ou pressionando `Shift+Tab`.271Um [permission mode](#permission-mode) onde Claude pesquisa e propõe alterações sem editar seus arquivos de origem. Pode ler, pesquisar e executar comandos de exploração, depois apresenta um plano para aprovação antes de tocar em qualquer coisa. Entre em plan mode com `/plan` ou pressionando `Shift+Tab`.

272 272 

273Saiba mais: [Analyze before you edit with plan mode](/pt/permission-modes#analyze-before-you-edit-with-plan-mode)273Saiba mais: [Analise antes de editar com plan mode](/pt/permission-modes#analyze-before-you-edit-with-plan-mode)

274 274 

275<h3 id="plugin">275<h3 id="plugin">

276 Plugin276 Plugin


292 Prompt injection292 Prompt injection

293</h3>293</h3>

294 294 

295Instruções hostis incorporadas em um arquivo, página web ou resultado de tool que tentam redirecionar Claude para ações que você nunca pediu. As defesas do Claude Code incluem o sistema de permissões, listas de bloqueio de comandos e verificação de confiança. [Auto mode](#auto-mode) adiciona uma sonda do lado do servidor que escaneia resultados de tool para conteúdo suspeito e um classificador que nunca vê resultados de tool, então texto injetado não pode influenciar suas decisões de aprovação.295Instruções hostis incorporadas em um arquivo, página web ou resultado de tool que tentam redirecionar Claude para ações que você nunca pediu. As defesas do Claude Code incluem o sistema de permissões, detecção de injeção de comando e verificação de confiança. [Auto mode](#auto-mode) adiciona uma sonda do lado do servidor que escaneia resultados de tool para conteúdo suspeito e um classificador que nunca vê resultados de tool, então texto injetado não pode influenciar suas decisões de aprovação.

296 296 

297Saiba mais: [Protect against prompt injection](/pt/security#protect-against-prompt-injection)297Saiba mais: [Proteja-se contra prompt injection](/pt/security#protect-against-prompt-injection)

298 298 

299<h2 id="r">299<h2 id="r">

300 R300 R


382 382 

383Um comando, `/teleport`, que puxa uma sessão Claude Code na nuvem para seu terminal local. Claude busca o branch, carrega o histórico de conversa e retoma do último estado da sessão web. A direção reversa é `--remote`, que envia uma tarefa local para executar na web.383Um comando, `/teleport`, que puxa uma sessão Claude Code na nuvem para seu terminal local. Claude busca o branch, carrega o histórico de conversa e retoma do último estado da sessão web. A direção reversa é `--remote`, que envia uma tarefa local para executar na web.

384 384 

385Saiba mais: [From web to terminal](/pt/claude-code-on-the-web#from-web-to-terminal)385Saiba mais: [Da web para o terminal](/pt/claude-code-on-the-web#from-web-to-terminal)

386 386 

387<h3 id="tool">387<h3 id="tool">

388 Tool388 Tool


427***427***

428 428 

429<h2 id="deprecated-and-renamed-terms">429<h2 id="deprecated-and-renamed-terms">

430 Deprecated and renamed terms430 Termos descontinuados e renomeados

431</h2>431</h2>

432 432 

433Estes termos aparecem em docs mais antigas, posts de blog e conteúdo da comunidade. Use o nome atual ao pesquisar neste site.433Estes termos aparecem em docs mais antigas, posts de blog e conteúdo da comunidade. Use o nome atual ao pesquisar neste site.

Details

6 6 

7> Saiba como configurar Claude Code através do Google Vertex AI, incluindo configuração, configuração de IAM e resolução de problemas.7> Saiba como configurar Claude Code através do Google Vertex AI, incluindo configuração, configuração de IAM e resolução de problemas.

8 8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

79<ContactSalesCard surface="vertex" />

80 

9<h2 id="prerequisites">81<h2 id="prerequisites">

10 Pré-requisitos82 Pré-requisitos

11</h2>83</h2>


155</h3>227</h3>

156 228 

157<Warning>229<Warning>

158 Fixe versões de modelo específicas ao implantar para vários usuários. Sem fixação, aliases de modelo como `sonnet` e `opus` resolvem para a versão mais recente, que pode ainda não estar ativada no seu projeto Vertex AI quando Anthropic lançar uma atualização. Claude Code [volta](#startup-model-checks) para a versão anterior na inicialização quando a mais recente não está disponível, mas fixar permite que você controle quando seus usuários se movem para um novo modelo.230 Fixe versões de modelo específicas ao implantar para vários usuários. Sem fixação, aliases de modelo como `sonnet` e `opus` resolvem para o padrão integrado do Claude Code para Vertex AI, que pode ficar atrás da versão mais recente e pode ainda não estar ativado no seu projeto. Claude Code [volta](#startup-model-checks) para a versão anterior na inicialização quando o padrão não está disponível, mas fixar permite que você controle quando seus usuários se movem para um novo modelo.

159</Warning>231</Warning>

160 232 

161Defina estas variáveis de ambiente para IDs de modelo Vertex AI específicos.233Defina estas variáveis de ambiente para IDs de modelo Vertex AI específicos.

headless.md +11 −3

Details

62 `--bare` é o modo recomendado para chamadas com script e SDK, e se tornará o padrão para `-p` em uma versão futura.62 `--bare` é o modo recomendado para chamadas com script e SDK, e se tornará o padrão para `-p` em uma versão futura.

63</Note>63</Note>

64 64 

65<h3 id="background-tasks-at-exit">

66 Tarefas em segundo plano ao sair

67</h3>

68 

69Se Claude iniciar uma [tarefa Bash em segundo plano](/pt/tools-reference#bash-tool-behavior) durante uma execução de `claude -p`, por exemplo um servidor de desenvolvimento ou uma compilação de observação, essa tarefa será encerrada cerca de cinco segundos após Claude retornar seu resultado final e stdin ter sido fechado. O período de carência permite que uma tarefa que termina logo após o resultado ainda entregue sua saída. Antes da v2.1.163, um processo em segundo plano que nunca sairia manteria a invocação de `claude -p` aberta indefinidamente.

70 

65<h2 id="examples">71<h2 id="examples">

66 Exemplos72 Exemplos

67</h2>73</h2>


163Quando uma solicitação de API falha com um erro que pode ser repetido, Claude Code emite um evento `system/api_retry` antes de tentar novamente. Você pode usar isso para exibir o progresso de repetição ou implementar lógica de backoff personalizada.169Quando uma solicitação de API falha com um erro que pode ser repetido, Claude Code emite um evento `system/api_retry` antes de tentar novamente. Você pode usar isso para exibir o progresso de repetição ou implementar lógica de backoff personalizada.

164 170 

165| Campo | Tipo | Descrição |171| Campo | Tipo | Descrição |

166| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |172| ---------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

167| `type` | `"system"` | tipo de mensagem |173| `type` | `"system"` | tipo de mensagem |

168| `subtype` | `"api_retry"` | identifica isso como um evento de repetição |174| `subtype` | `"api_retry"` | identifica isso como um evento de repetição |

169| `attempt` | inteiro | número da tentativa atual, começando em 1 |175| `attempt` | inteiro | número da tentativa atual, começando em 1 |

170| `max_retries` | inteiro | total de repetições permitidas |176| `max_retries` | inteiro | total de repetições permitidas |

171| `retry_delay_ms` | inteiro | milissegundos até a próxima tentativa |177| `retry_delay_ms` | inteiro | milissegundos até a próxima tentativa |

172| `error_status` | inteiro ou nulo | código de status HTTP, ou `null` para erros de conexão sem resposta HTTP |178| `error_status` | inteiro ou nulo | código de status HTTP, ou `null` para erros de conexão sem resposta HTTP |

173| `error` | string | categoria de erro: `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `rate_limit`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, ou `unknown` |179| `error` | string | categoria de erro: `authentication_failed`, `oauth_org_not_allowed`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, ou `unknown` |

174| `uuid` | string | identificador único do evento |180| `uuid` | string | identificador único do evento |

175| `session_id` | string | sessão à qual o evento pertence |181| `session_id` | string | sessão à qual o evento pertence |

176 182 


226O sinalizador `--allowedTools` usa [sintaxe de regra de permissão](/pt/settings#permission-rule-syntax). O ` *` à direita habilita correspondência de prefixo, então `Bash(git diff *)` permite qualquer comando começando com `git diff`. O espaço antes de `*` é importante: sem ele, `Bash(git diff*)` também corresponderia a `git diff-index`.232O sinalizador `--allowedTools` usa [sintaxe de regra de permissão](/pt/settings#permission-rule-syntax). O ` *` à direita habilita correspondência de prefixo, então `Bash(git diff *)` permite qualquer comando começando com `git diff`. O espaço antes de `*` é importante: sem ele, `Bash(git diff*)` também corresponderia a `git diff-index`.

227 233 

228<Note>234<Note>

229 [skills](/pt/skills) invocadas pelo usuário como `/code-review` e [comandos integrados](/pt/commands) estão disponíveis apenas no modo interativo. No modo `-p`, descreva a tarefa que você deseja realizar.235 Skills invocadas pelo usuário e comandos personalizados funcionam no modo `-p`: inclua `/skill-name` na string de prompt e Claude Code o expande antes de executar. Comandos integrados que abrem um diálogo interativo, como `/config` e `/login`, não estão disponíveis no modo `-p`.

230</Note>236</Note>

231 237 

232<h3 id="customize-the-system-prompt">238<h3 id="customize-the-system-prompt">


265claude -p "Continue that review" --resume "$session_id"271claude -p "Continue that review" --resume "$session_id"

266```272```

267 273 

274Execute ambos os comandos do mesmo diretório: a busca de ID de sessão é limitada ao diretório do projeto atual e seus git worktrees. Consulte [Resume a session](/pt/sessions#resume-a-session) para as regras de escopo completas.

275 

268<h2 id="next-steps">276<h2 id="next-steps">

269 Próximas etapas277 Próximas etapas

270</h2>278</h2>

hooks.md +65 −26

Details

16 Ciclo de vida do hook16 Ciclo de vida do hook

17</h2>17</h2>

18 18 

19Hooks disparam em pontos específicos durante uma sessão do Claude Code. Quando um evento dispara e um matcher corresponde, o Claude Code passa contexto JSON sobre o evento para seu manipulador de hook. Para hooks de comando, a entrada chega em stdin. Para hooks HTTP, chega como corpo da solicitação POST. Seu manipulador pode então inspecionar a entrada, tomar ação e opcionalmente retornar uma decisão. Os eventos caem em três cadências: uma vez por sessão (`SessionStart`, `SessionEnd`), uma vez por turno (`UserPromptSubmit`, `Stop`, `StopFailure`) e em cada chamada de ferramenta dentro do loop agentic (`PreToolUse`, `PostToolUse`):19Hooks disparam em pontos específicos durante uma sessão do Claude Code. Quando um evento dispara e um matcher corresponde, o Claude Code passa contexto JSON sobre o evento para seu manipulador de hook. Para hooks de comando, a entrada chega em stdin. Para hooks HTTP, chega como corpo da solicitação POST. Seu manipulador pode então inspecionar a entrada, tomar ação e opcionalmente retornar uma decisão. Os eventos caem em três cadências: uma vez por sessão (`SessionStart`, `SessionEnd`), uma vez por turno (`UserPromptSubmit`, `Stop`, `StopFailure`) e em cada chamada de ferramenta dentro do loop agentic (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`):

20 20 

21<div style={{maxWidth: "500px", margin: "0 auto"}}>21<div style={{maxWidth: "500px", margin: "0 auto"}}>

22 <Frame>22 <Frame>


108Agora suponha que o Claude Code decida executar `Bash "rm -rf /tmp/build"`. Aqui está o que acontece:108Agora suponha que o Claude Code decida executar `Bash "rm -rf /tmp/build"`. Aqui está o que acontece:

109 109 

110<Frame>110<Frame>

111 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" alt="Fluxo de resolução de hook: evento PreToolUse dispara, matcher verifica correspondência de Bash, condição if verifica correspondência de Bash(rm *), manipulador de hook executa, resultado retorna ao Claude Code" width="930" height="270" data-path="images/hook-resolution.svg" />111 <img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/hook-resolution.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=be0bf3053550c26de5f54cd64674c197" alt="Diagrama de resolução de hook: PreToolUse dispara, o matcher verifica correspondência de Bash, então a condição if verifica correspondência de Bash(rm *). Se ambos corresponderem, o comando do hook é executado e retorna permissionDecision deny, então a chamada da ferramenta é bloqueada e o Claude Code continua. Se qualquer verificação falhar em corresponder, o hook é ignorado e a chamada da ferramenta é permitida prosseguir." width="930" height="270" data-path="images/hook-resolution.svg" />

112</Frame>112</Frame>

113 113 

114<Steps>114<Steps>


174Onde você define um hook determina seu escopo:174Onde você define um hook determina seu escopo:

175 175 

176| Local | Escopo | Compartilhável |176| Local | Escopo | Compartilhável |

177| :------------------------------------------------------------- | :------------------------------- | :-------------------------------------- |177| :------------------------------------------------------------- | :------------------------------- | :---------------------------------------- |

178| `~/.claude/settings.json` | Todos os seus projetos | Não, local para sua máquina |178| `~/.claude/settings.json` | Todos os seus projetos | Não, local para sua máquina |

179| `.claude/settings.json` | Projeto único | Sim, pode ser confirmado no repositório |179| `.claude/settings.json` | Projeto único | Sim, pode ser confirmado no repositório |

180| `.claude/settings.local.json` | Projeto único | Não, gitignored |180| `.claude/settings.local.json` | Projeto único | Não, gitignored quando Claude Code o cria |

181| Configurações de política gerenciada | Organização inteira | Sim, controlado por administrador |181| Configurações de política gerenciada | Organização inteira | Sim, controlado por administrador |

182| [Plugin](/pt/plugins) `hooks/hooks.json` | Quando o plugin está ativado | Sim, agrupado com o plugin |182| [Plugin](/pt/plugins) `hooks/hooks.json` | Quando o plugin está ativado | Sim, agrupado com o plugin |

183| Frontmatter de [Skill](/pt/skills) ou [agente](/pt/sub-agents) | Enquanto o componente está ativo | Sim, definido no arquivo do componente |183| Frontmatter de [Skill](/pt/skills) ou [agente](/pt/sub-agents) | Enquanto o componente está ativo | Sim, definido no arquivo do componente |


311Esses campos se aplicam a todos os tipos de hook:311Esses campos se aplicam a todos os tipos de hook:

312 312 

313| Campo | Obrigatório | Descrição |313| Campo | Obrigatório | Descrição |

314| :-------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |314| :-------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

315| `type` | sim | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` ou `"agent"` |315| `type` | sim | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` ou `"agent"` |

316| `if` | não | Sintaxe de regra de permissão para filtrar quando este hook executa, como `"Bash(git *)"` ou `"Edit(*.ts)"`. O hook apenas é gerado se a chamada de ferramenta corresponde ao padrão, ou se um comando Bash é muito complexo para analisar. Apenas avaliado em eventos de ferramenta: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Em outros eventos, um hook com `if` definido nunca executa. Usa a mesma sintaxe que [regras de permissão](/pt/permissions) |316| `if` | não | Sintaxe de regra de permissão para filtrar quando este hook executa, como `"Bash(git *)"` ou `"Edit(*.ts)"`. O comando do hook apenas é executado se a chamada de ferramenta corresponde ao padrão. Consulte a [tabela de correspondência Bash](#bash-if-matching) abaixo para saber como padrões Bash são avaliados contra subcomandos, `$()` e backticks. Apenas avaliado em eventos de ferramenta: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Em outros eventos, um hook com `if` definido nunca executa. Usa a mesma sintaxe que [regras de permissão](/pt/permissions) |

317| `timeout` | não | Segundos antes de cancelar. Padrões: 600 para `command`, `http` e `mcp_tool`; 30 para `prompt`; 60 para `agent`. [`UserPromptSubmit`](#userpromptsubmit) reduz o padrão de `command`, `http` e `mcp_tool` para 30, e [`MessageDisplay`](#messagedisplay) reduz para 10 |317| `timeout` | não | Segundos antes de cancelar. Padrões: 600 para `command`, `http` e `mcp_tool`; 30 para `prompt`; 60 para `agent`. [`UserPromptSubmit`](#userpromptsubmit) reduz o padrão de `command`, `http` e `mcp_tool` para 30, e [`MessageDisplay`](#messagedisplay) reduz para 10 |

318| `statusMessage` | não | Mensagem de spinner personalizada exibida enquanto o hook executa |318| `statusMessage` | não | Mensagem de spinner personalizada exibida enquanto o hook executa |

319| `once` | não | Se `true`, executa apenas uma vez por sessão e depois é removido. Apenas honrado para hooks declarados em [frontmatter de skill](#hooks-in-skills-and-agents); ignorado em arquivos de configurações e frontmatter de agente |319| `once` | não | Se `true`, executa apenas uma vez por sessão e depois é removido. Apenas honrado para hooks declarados em [frontmatter de skill](#hooks-in-skills-and-agents); ignorado em arquivos de configurações e frontmatter de agente |

320 320 

321O campo `if` contém exatamente uma regra de permissão. Não há sintaxe `&&`, `||` ou lista para combinar regras; para aplicar múltiplas condições, defina um manipulador de hook separado para cada. Para Bash, a regra é correspondida contra cada subcomando da entrada da ferramenta após atribuições `VAR=value` iniciais serem removidas, então `if: "Bash(git push *)"` corresponde tanto a `FOO=bar git push` quanto a `npm test && git push`. O hook executa se qualquer subcomando corresponde, e sempre executa quando o comando é muito complexo para analisar.321O campo `if` contém exatamente uma regra de permissão. Não há sintaxe `&&`, `||` ou lista para combinar regras; para aplicar múltiplas condições, defina um manipulador de hook separado para cada.

322 

323<span id="bash-if-matching" />Para padrões Bash, se seu comando de hook executa depende da forma do padrão e do comando Bash que Claude está invocando. Atribuições `VAR=value` iniciais são removidas antes da correspondência.

324 

325| padrão `if` | Comando Bash | Hook executa? | Por quê |

326| :----------------- | :--------------------- | :------------ | :-------------------------------------------------------------------------------------------------------------- |

327| `Bash(git *)` | `FOO=bar git push` | sim | atribuições iniciais são removidas; `git push` corresponde |

328| `Bash(git *)` | `npm test && git push` | sim | cada subcomando é verificado; `git push` corresponde |

329| `Bash(rm *)` | `echo $(rm -rf /)` | sim | comandos dentro de `$()` e backticks são verificados; `rm -rf /` corresponde |

330| `Bash(rm *)` | `echo $(date)` | não | nenhum subcomando corresponde a `rm *` |

331| `Bash(git push *)` | `echo $(date)` | sim | padrões que especificam mais do que o nome do comando executam o hook mesmo assim em `$()`, backticks ou `$VAR` |

332 

333O filtro também falha aberto, executando seu hook independentemente do padrão, quando o comando Bash não pode ser analisado. Como o filtro `if` é melhor esforço, use o [sistema de permissão](/pt/permissions) em vez de um hook para impor um allow ou deny duro.

322 334 

323<h4 id="command-hook-fields">335<h4 id="command-hook-fields">

324 Campos de hook de comando336 Campos de hook de comando


461Além dos [campos comuns](#common-fields), hooks de prompt e agente aceitam esses campos:473Além dos [campos comuns](#common-fields), hooks de prompt e agente aceitam esses campos:

462 474 

463| Campo | Obrigatório | Descrição |475| Campo | Obrigatório | Descrição |

464| :------- | :---------- | :---------------------------------------------------------------------------------------------------- |476| :------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

465| `prompt` | sim | Texto do prompt a enviar para o modelo. Use `$ARGUMENTS` como placeholder para a entrada JSON do hook |477| `prompt` | sim | Texto do prompt a enviar para o modelo. Use `$ARGUMENTS` como placeholder para a entrada JSON do hook. Escape com uma barra invertida para incluir texto literal: `\$1.00` renderiza como `$1.00` |

466| `model` | não | Modelo a usar para avaliação. Padrão para um modelo rápido |478| `model` | não | Modelo a usar para avaliação. Padrão para um modelo rápido |

467 479 

468Todos os hooks correspondentes executam em paralelo, e manipuladores idênticos são automaticamente desduplicados. Hooks de comando são desduplicados por string de comando e `args`, e hooks HTTP são desduplicados por URL. Manipuladores executam no diretório atual com o ambiente do Claude Code. A variável de ambiente `$CLAUDE_CODE_REMOTE` é definida como `"true"` em ambientes web remotos e não é definida na CLI local.480Todos os hooks correspondentes executam em paralelo, e manipuladores idênticos são automaticamente desduplicados. Hooks de comando são desduplicados por string de comando e `args`, e hooks HTTP são desduplicados por URL. Manipuladores executam no diretório atual com o ambiente do Claude Code. A variável de ambiente `$CLAUDE_CODE_REMOTE` é definida como `"true"` em ambientes web remotos e não é definida na CLI local.


619| `agent_id` | Identificador único para o subagente. Presente apenas quando o hook dispara dentro de uma chamada de subagente. Use isso para distinguir chamadas de hook de subagente de chamadas de thread principal. |631| `agent_id` | Identificador único para o subagente. Presente apenas quando o hook dispara dentro de uma chamada de subagente. Use isso para distinguir chamadas de hook de subagente de chamadas de thread principal. |

620| `agent_type` | Nome do agente (por exemplo, `"Explore"` ou `"security-reviewer"`). Presente quando a sessão usa `--agent` ou o hook dispara dentro de um subagente. Para subagentes, o tipo do subagente tem precedência sobre o valor `--agent` da sessão. Para [subagentes personalizados](/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo. |632| `agent_type` | Nome do agente (por exemplo, `"Explore"` ou `"security-reviewer"`). Presente quando a sessão usa `--agent` ou o hook dispara dentro de um subagente. Para subagentes, o tipo do subagente tem precedência sobre o valor `--agent` da sessão. Para [subagentes personalizados](/pt/sub-agents), este é o campo `name` do frontmatter do agente, não o nome do arquivo. |

621 633 

622Apenas hooks [`SessionStart`](#sessionstart) recebem um campo `model`. Não há variável de ambiente `$CLAUDE_MODEL`. Um processo de hook herda o ambiente pai, então pode ler `$ANTHROPIC_MODEL` se você defini-lo em seu shell, mas esse valor não muda quando você alterna modelos com `/model` durante uma sessão.634Apenas hooks [`SessionStart`](#sessionstart) podem receber um campo `model`, e não é garantido que esteja presente. Não há variável de ambiente `$CLAUDE_MODEL`. Um processo de hook herda o ambiente pai, então pode ler `$ANTHROPIC_MODEL` se você defini-lo em seu shell, mas esse valor não muda quando você alterna modelos com `/model` durante uma sessão.

623 635 

624Por exemplo, um hook `PreToolUse` para um comando Bash recebe isso em stdin:636Por exemplo, um hook `PreToolUse` para um comando Bash recebe isso em stdin:

625 637 


782# Hook de notificação: ping no desktop quando Claude Code precisa de atenção.794# Hook de notificação: ping no desktop quando Claude Code precisa de atenção.

783input=$(cat)795input=$(cat)

784title="Claude Code'796title="Claude Code'

785body=$(jq -r '.message // 'Needs your attention'' <<<"$input")797body=$(jq -r '.message // 'Needs your attention'' <<<'$input")

786seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")798seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")

787jq -nc --arg seq "$seq" '{terminalSequence: $seq}'799jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

788```800```


815* [SessionStart](#sessionstart), [Setup](#setup) e [SubagentStart](#subagentstart): no início da conversa, antes do primeiro prompt827* [SessionStart](#sessionstart), [Setup](#setup) e [SubagentStart](#subagentstart): no início da conversa, antes do primeiro prompt

816* [UserPromptSubmit](#userpromptsubmit) e [UserPromptExpansion](#userpromptexpansion): ao lado do prompt enviado828* [UserPromptSubmit](#userpromptsubmit) e [UserPromptExpansion](#userpromptexpansion): ao lado do prompt enviado

817* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure) e [PostToolBatch](#posttoolbatch): ao lado do resultado da ferramenta829* [PreToolUse](#pretooluse), [PostToolUse](#posttooluse), [PostToolUseFailure](#posttoolusefailure) e [PostToolBatch](#posttoolbatch): ao lado do resultado da ferramenta

830* [Stop](#stop) e [SubagentStop](#subagentstop): no final da rodada. A conversa continua para que Claude possa agir sobre o feedback. Consulte [Controle de decisão Stop](#stop-decision-control)

818 831 

819Quando vários hooks retornam `additionalContext` para o mesmo evento, Claude recebe todos os valores. Se um valor exceder 10.000 caracteres, o Claude Code escreve o texto completo em um arquivo no diretório de sessão e passa ao Claude o caminho do arquivo com uma visualização curta em vez disso.832Quando vários hooks retornam `additionalContext` para o mesmo evento, Claude recebe todos os valores. Se um valor exceder 10.000 caracteres, o Claude Code escreve o texto completo em um arquivo no diretório de sessão e passa ao Claude o caminho do arquivo com uma visualização curta em vez disso.

820 833 


838 851 

839| Eventos | Padrão de decisão | Campos-chave |852| Eventos | Padrão de decisão | Campos-chave |

840| :---------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |853| :---------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

841| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | `decision` de nível superior | `decision: "block"`, `reason` |854| UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolUseFailure, PostToolBatch, Stop, SubagentStop, ConfigChange, PreCompact | `decision` de nível superior | `decision: "block"`, `reason`. Stop e SubagentStop também aceitam `hookSpecificOutput.additionalContext` para [feedback não-erro que continua a conversa](#stop-decision-control) |

842| TeammateIdle, TaskCreated, TaskCompleted | Código de saída ou `continue: false` | Código de saída 2 bloqueia a ação com feedback de stderr. JSON `{"continue": false, "stopReason": "..."}` também para o colega inteiramente, correspondendo ao comportamento do hook `Stop` |855| TeammateIdle, TaskCreated, TaskCompleted | Código de saída ou `continue: false` | Código de saída 2 bloqueia a ação com feedback de stderr. JSON `{"continue": false, "stopReason": "..."}` também para o colega inteiramente, correspondendo ao comportamento do hook `Stop` |

843| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |856| PreToolUse | `hookSpecificOutput` | `permissionDecision` (allow/deny/ask/defer), `permissionDecisionReason` |

844| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |857| PermissionRequest | `hookSpecificOutput` | `decision.behavior` (allow/deny) |


850| SessionStart, Setup, SubagentStart | Apenas contexto | `hookSpecificOutput.additionalContext` adiciona contexto para Claude. SessionStart também aceita [`initialUserMessage`, `watchPaths`, `sessionTitle` e `reloadSkills`](#sessionstart-decision-control). Sem bloqueio ou controle de decisão |863| SessionStart, Setup, SubagentStart | Apenas contexto | `hookSpecificOutput.additionalContext` adiciona contexto para Claude. SessionStart também aceita [`initialUserMessage`, `watchPaths`, `sessionTitle` e `reloadSkills`](#sessionstart-decision-control). Sem bloqueio ou controle de decisão |

851| WorktreeRemove, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | Nenhum | Sem controle de decisão. Usado para efeitos colaterais como logging ou limpeza |864| WorktreeRemove, Notification, SessionEnd, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | Nenhum | Sem controle de decisão. Usado para efeitos colaterais como logging ou limpeza |

852 865 

866Alguns eventos também podem reescrever conteúdo em vez de apenas permitir ou bloquear:

867 

868* `PreToolUse` — `updatedInput` diretamente sob `hookSpecificOutput` substitui os argumentos de uma ferramenta antes de executar ([detalhes](#pretooluse-decision-control))

869* `PermissionRequest` — `updatedInput` dentro do objeto `decision` ([detalhes](#permissionrequest-decision-control))

870* `PostToolUse` — `updatedToolOutput` substitui o resultado da ferramenta ([detalhes](#posttooluse-decision-control))

871* `UserPromptSubmit` — não pode substituir o prompt; apenas injeta `additionalContext` ao lado dele

872 

873Para casos de uso de redação ou transformação, intercepte em `PreToolUse` para entradas de ferramenta de saída e `PostToolUse` para resultados de ferramenta de entrada.

874 

853Aqui estão exemplos de cada padrão em ação:875Aqui estão exemplos de cada padrão em ação:

854 876 

855<Tabs>877<Tabs>


926 Entrada de SessionStart948 Entrada de SessionStart

927</h4>949</h4>

928 950 

929Além dos [campos de entrada comuns](#common-input-fields), hooks SessionStart recebem `source`, `model` e opcionalmente `agent_type` e `session_title`. O campo `source` indica como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear` ou `"compact"` após compactação. O campo `model` contém o identificador do modelo. Se você iniciar Claude Code com `claude --agent <name>`, um campo `agent_type` contém o nome do agente. O campo `session_title` carrega o título da sessão atual se um já estiver definido, por exemplo via `--name` ou `/rename`. Um hook que emite `sessionTitle` pode verificar `session_title` primeiro para evitar sobrescrever um título que o usuário definiu explicitamente.951Além dos [campos de entrada comuns](#common-input-fields), hooks SessionStart recebem `source` e opcionalmente `model`, `agent_type` e `session_title`. O campo `source` indica como a sessão começou: `"startup"` para novas sessões, `"resume"` para sessões retomadas, `"clear"` após `/clear` ou `"compact"` após compactação. O campo `model` contém o identificador do modelo ativo. Pode ser omitido, por exemplo após `/clear` ou quando uma sessão é restaurada através de recuperação de conversa, então verifique o campo antes de lê-lo. Se você iniciar Claude Code com `claude --agent <name>`, um campo `agent_type` contém o nome do agente. O campo `session_title` carrega o título da sessão atual se um já estiver definido, por exemplo via `--name` ou `/rename`. Um hook que emite `sessionTitle` pode verificar `session_title` primeiro para evitar sobrescrever um título que o usuário definiu explicitamente.

930 952 

931```json theme={null}953```json theme={null}

932{954{


1502Em `PostToolUse`, `tool_response` para uma chamada Agent concluída carrega o texto final do subagente junto com telemetria de uso. Leia esses campos para registrar custo por subagente de um hook:1524Em `PostToolUse`, `tool_response` para uma chamada Agent concluída carrega o texto final do subagente junto com telemetria de uso. Leia esses campos para registrar custo por subagente de um hook:

1503 1525 

1504| Campo | Tipo | Exemplo | Descrição |1526| Campo | Tipo | Exemplo | Descrição |

1505| :------------------ | :----- | :---------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------- |1527| :------------------ | :----- | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |

1506| `status` | string | `"completed"` | `"completed"` para chamadas síncronas, `"async_launched"` para `run_in_background: true` |1528| `status` | string | `"completed"` | `"completed"` para chamadas síncronas, `"async_launched"` para `run_in_background: true` |

1507| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para a execução do subagente |1529| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para a execução do subagente |

1508| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto final do subagente |1530| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Os blocos de texto final do subagente |

1531| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo que o subagente executou, que pode diferir do modelo solicitado. {/* min-version: 2.1.174 */}Requer Claude Code v2.1.174 ou posterior |

1509| `totalTokens` | number | `12450` | Total de tokens cobrados através dos turnos do subagente |1532| `totalTokens` | number | `12450` | Total de tokens cobrados através dos turnos do subagente |

1510| `totalDurationMs` | number | `48211` | Duração de relógio de parede da execução do subagente |1533| `totalDurationMs` | number | `48211` | Duração de relógio de parede da execução do subagente |

1511| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta que o subagente fez |1534| `totalToolUseCount` | number | `7` | Contagem de chamadas de ferramenta que o subagente fez |

1512| `usage` | object | `{"input_tokens": 8320, ...}` | Divisão de tokens por tipo: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1535| `usage` | object | `{"input_tokens": 8320, ...}` | Divisão de tokens por tipo: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |

1513 1536 

1514Para chamadas `run_in_background: true`, a ferramenta retorna imediatamente após lançar o subagente, então `tool_response` não carrega campos de uso. Tem `status: "async_launched"`, `agentId`, `description`, `prompt` e `outputFile` em vez disso.1537Para chamadas `run_in_background: true`, a ferramenta retorna imediatamente após lançar o subagente, então `tool_response` não carrega campos de uso. Tem `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` e `resolvedModel` em vez disso.

1538 

1539O campo `resolvedModel` nomeia o modelo que o subagente realmente executa, que pode diferir do valor `model` em `tool_input`. Requer Claude Code v2.1.174 ou posterior.

1540 

1541<a id="askuserquestion" />

1515 1542 

1516<h5 id="askuserquestion">1543<h5 id="askuserquestion">

1517 AskUserQuestion1544 AskUserQuestion


2088}2115}

2089```2116```

2090 2117 

2091Hooks SubagentStop usam o mesmo formato de controle de decisão que [hooks Stop](#stop-decision-control). Eles não suportam `additionalContext`. Retornar `decision: "block"` com uma `reason` mantém o subagente em execução e entrega `reason` ao subagente como sua próxima instrução. Para injetar contexto na sessão pai após um subagente retornar, use um hook [`PostToolUse`](#posttooluse) na ferramenta `Agent` em vez disso.2118Hooks SubagentStop usam o mesmo formato de controle de decisão que [hooks Stop](#stop-decision-control), incluindo `hookSpecificOutput.additionalContext` com `hookEventName` definido para `"SubagentStop"`, para feedback não-erro que mantém o subagente em execução. Retornar `decision: "block"` com uma `reason` mantém o subagente em execução e entrega `reason` ao subagente como sua próxima instrução. Para injetar contexto na sessão pai após um subagente retornar, use um hook [`PostToolUse`](#posttooluse) na ferramenta `Agent` em vez disso.

2092 2119 

2093<h3 id="taskcreated">2120<h3 id="taskcreated">

2094 TaskCreated2121 TaskCreated


2115 "task_subject": "Implement user authentication",2142 "task_subject": "Implement user authentication",

2116 "task_description": "Add login and signup endpoints",2143 "task_description": "Add login and signup endpoints",

2117 "teammate_name": "implementer",2144 "teammate_name": "implementer",

2118 "team_name": "my-project"2145 "team_name": "session-a1b2c3d4"

2119}2146}

2120```2147```

2121 2148 

2122| Campo | Descrição |2149| Campo | Descrição |

2123| :----------------- | :-------------------------------------------------- |2150| :----------------- | :------------------------------------------------------------------------- |

2124| `task_id` | Identificador da tarefa sendo criada |2151| `task_id` | Identificador da tarefa sendo criada |

2125| `task_subject` | Título da tarefa |2152| `task_subject` | Título da tarefa |

2126| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2153| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |

2127| `teammate_name` | Nome do colega criando a tarefa. Pode estar ausente |2154| `teammate_name` | Nome do colega criando a tarefa. Pode estar ausente |

2128| `team_name` | Nome da equipe. Pode estar ausente |2155| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |

2129 2156 

2130<h4 id="taskcreated-decision-control">2157<h4 id="taskcreated-decision-control">

2131 Controle de decisão de TaskCreated2158 Controle de decisão de TaskCreated


2176 "task_subject": "Implement user authentication",2203 "task_subject": "Implement user authentication",

2177 "task_description": "Add login and signup endpoints",2204 "task_description": "Add login and signup endpoints",

2178 "teammate_name": "implementer",2205 "teammate_name": "implementer",

2179 "team_name": "my-project"2206 "team_name": "session-a1b2c3d4"

2180}2207}

2181```2208```

2182 2209 

2183| Campo | Descrição |2210| Campo | Descrição |

2184| :----------------- | :------------------------------------------------------ |2211| :----------------- | :------------------------------------------------------------------------- |

2185| `task_id` | Identificador da tarefa sendo concluída |2212| `task_id` | Identificador da tarefa sendo concluída |

2186| `task_subject` | Título da tarefa |2213| `task_subject` | Título da tarefa |

2187| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |2214| `task_description` | Descrição detalhada da tarefa. Pode estar ausente |

2188| `teammate_name` | Nome do colega completando a tarefa. Pode estar ausente |2215| `teammate_name` | Nome do colega completando a tarefa. Pode estar ausente |

2189| `team_name` | Nome da equipe. Pode estar ausente |2216| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |

2190 2217 

2191<h4 id="taskcompleted-decision-control">2218<h4 id="taskcompleted-decision-control">

2192 Controle de decisão de TaskCompleted2219 Controle de decisão de TaskCompleted


2294Hooks `Stop` e `SubagentStop` podem controlar se Claude continua. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:2321Hooks `Stop` e `SubagentStop` podem controlar se Claude continua. Além dos [campos de saída JSON](#json-output) disponíveis para todos os hooks, seu script de hook pode retornar esses campos específicos do evento:

2295 2322 

2296| Campo | Descrição |2323| Campo | Descrição |

2297| :--------- | :------------------------------------------------------------------------------ |2324| :------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2298| `decision` | `"block"` previne Claude de parar. Omita para permitir que Claude pare |2325| `decision` | `"block"` previne Claude de parar. Omita para permitir que Claude pare |

2299| `reason` | Obrigatório quando `decision` é `"block"`. Diz ao Claude por que deve continuar |2326| `reason` | Obrigatório quando `decision` é `"block"`. Diz ao Claude por que deve continuar |

2327| `hookSpecificOutput.additionalContext` | Feedback não-erro para Claude. A conversa continua para que Claude possa agir sobre isso, mas diferentemente de `decision: "block"` é mostrado na transcrição como feedback de hook em vez de erro de hook |

2300 2328 

2301```json theme={null}2329```json theme={null}

2302{2330{


2305}2333}

2306```2334```

2307 2335 

2336Use `additionalContext` quando o hook está funcionando como projetado e dando orientação a Claude, como "execute a suite de testes antes de terminar". Mantém a conversa indo através das mesmas proteções de loop que `decision: "block"`, a saber a entrada `stop_hook_active` e o limite de 8 continuações consecutivas, mas a transcrição a rotula como `Stop hook feedback` e nenhuma notificação de erro de hook é mostrada:

2337 

2338```json theme={null}

2339{

2340 "hookSpecificOutput": {

2341 "hookEventName": "Stop",

2342 "additionalContext": "Please run the test suite before finishing"

2343 }

2344}

2345```

2346 

2308<h3 id="stopfailure">2347<h3 id="stopfailure">

2309 StopFailure2348 StopFailure

2310</h3>2349</h3>


2359 "permission_mode": "default",2398 "permission_mode": "default",

2360 "hook_event_name": "TeammateIdle",2399 "hook_event_name": "TeammateIdle",

2361 "teammate_name": "researcher",2400 "teammate_name": "researcher",

2362 "team_name": "my-project"2401 "team_name": "session-a1b2c3d4"

2363}2402}

2364```2403```

2365 2404 

2366| Campo | Descrição |2405| Campo | Descrição |

2367| :-------------- | :--------------------------------------------- |2406| :-------------- | :------------------------------------------------------------------------- |

2368| `teammate_name` | Nome do colega que está prestes a ficar ocioso |2407| `teammate_name` | Nome do colega que está prestes a ficar ocioso |

2369| `team_name` | Nome da equipe |2408| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |

2370 2409 

2371<h4 id="teammateidle-decision-control">2410<h4 id="teammateidle-decision-control">

2372 Controle de decisão de TeammateIdle2411 Controle de decisão de TeammateIdle

hooks-guide.md +21 −9

Details

506 506 

507Quando múltiplos hooks correspondem ao mesmo evento, o comando de cada hook executa até a conclusão antes do Claude Code mesclar os resultados. Um hook retornando `deny` não impede que hooks irmãos executem. Não confie em um `deny` de um hook para suprimir efeitos colaterais em outro hook.507Quando múltiplos hooks correspondem ao mesmo evento, o comando de cada hook executa até a conclusão antes do Claude Code mesclar os resultados. Um hook retornando `deny` não impede que hooks irmãos executem. Não confie em um `deny` de um hook para suprimir efeitos colaterais em outro hook.

508 508 

509Após todos os hooks correspondentes terminarem, Claude Code combina suas saídas. Para decisões de permissão `PreToolUse`, a resposta mais restritiva vence: `deny` substitui `ask`, que substitui `allow`. Texto de `additionalContext` é mantido de cada hook e passado ao Claude junto.509Após todos os hooks correspondentes terminarem, Claude Code combina suas saídas. Para decisões de permissão `PreToolUse`, a resposta mais restritiva vence, na ordem `deny`, `defer`, `ask`, `allow`. Texto de `additionalContext` é mantido de cada hook e passado ao Claude junto.

510 510 

511O exemplo abaixo registra dois hooks `PreToolUse` em `Bash`. O primeiro anexa cada comando a um arquivo de log e sai com 0. O segundo executa um script que sai com 2 para negar quando o comando contém `rm -rf`:511O exemplo abaixo registra dois hooks `PreToolUse` em `Bash`. O primeiro anexa cada comando a um arquivo de log e sai com 0. O segundo executa um script que sai com 2 para negar quando o comando contém `rm -rf`:

512 512 


576 exit 2 # exit 2 = bloquear a ação576 exit 2 # exit 2 = bloquear a ação

577fi577fi

578 578 

579exit 0 # exit 0 = deixar prosseguir579exit 0 # exit 0 = nenhuma decisão; o fluxo de permissão normal se aplica

580```580```

581 581 

582O código de saída determina o que acontece a seguir:582O código de saída determina o que acontece a seguir:


751 O campo `if` requer Claude Code v2.1.85 ou posterior. Versões anteriores o ignoram e executam o hook em cada chamada correspondida.751 O campo `if` requer Claude Code v2.1.85 ou posterior. Versões anteriores o ignoram e executam o hook em cada chamada correspondida.

752</Note>752</Note>

753 753 

754O campo `if` usa [sintaxe de regra de permissão](/pt/permissions) para filtrar hooks por nome de ferramenta e argumentos juntos, para que o processo do hook apenas seja gerado quando a chamada de ferramenta corresponder, ou quando um comando Bash é muito complexo para analisar. Isto vai além de `matcher`, que filtra no nível do grupo apenas por nome de ferramenta.754O campo `if` usa [sintaxe de regra de permissão](/pt/permissions) para filtrar hooks por nome de ferramenta e argumentos juntos, para que o processo do hook apenas seja gerado quando a chamada de ferramenta corresponder. Isto vai além de `matcher`, que filtra no nível do grupo apenas por nome de ferramenta.

755 755 

756Por exemplo, para executar um hook apenas quando Claude usa comandos `git` em vez de todos os comandos Bash:756Por exemplo, para executar um hook apenas quando Claude usa comandos `git` em vez de todos os comandos Bash:

757 757 


774}774}

775```775```

776 776 

777O processo do hook apenas é gerado quando um subcomando do comando Bash corresponde a `git *`, ou quando o comando é muito complexo para analisar em subcomandos. Para comandos compostos como `npm test && git push`, Claude Code avalia cada subcomando e dispara o hook porque `git push` corresponde. O campo `if` aceita os mesmos padrões que regras de permissão: `"Bash(git *)"`, `"Edit(*.ts)"` e assim por diante. Para corresponder múltiplos nomes de ferramenta, use manipuladores separados cada um com seu próprio valor `if`, ou corresponda no nível `matcher` onde alternação de pipe é suportada.777Se seu hook deve executar depende da forma do seu padrão `if` e do comando Bash que Claude está invocando:

778 

779| padrão `if` | Comando Bash | Hook executa? | Por quê |

780| :----------------- | :--------------------- | :------------ | :--------------------------------------------------------------------------------------------------------------- |

781| `Bash(git *)` | `git push` | sim | nome do comando corresponde |

782| `Bash(git *)` | `npm test && git push` | sim | cada subcomando é verificado; `git push` corresponde |

783| `Bash(git *)` | `echo $(git log)` | sim | comandos dentro de `$()` e backticks são verificados; `git log` corresponde |

784| `Bash(git *)` | `echo $(date)` | não | nenhum subcomando corresponde a `git *` |

785| `Bash(git push *)` | `echo $(date)` | sim | padrões que especificam mais do que o nome do comando executam o hook mesmo assim em `$()`, backticks, ou `$VAR` |

786 

787O filtro também falha aberto, executando seu hook independentemente do padrão, quando o comando Bash não pode ser analisado. Como o filtro é melhor esforço, use o [sistema de permissão](/pt/permissions) em vez de um hook para impor um allow ou deny difícil.

788 

789O campo `if` aceita os mesmos padrões que regras de permissão: `"Bash(git *)"`, `"Edit(*.ts)"`, e assim por diante. Para corresponder múltiplos nomes de ferramenta, use manipuladores separados cada um com seu próprio valor `if`, ou corresponda no nível `matcher` onde alternação de pipe é suportada.

778 790 

779`if` funciona apenas em eventos de ferramenta: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Adicioná-lo a qualquer outro evento impede o hook de executar.791`if` funciona apenas em eventos de ferramenta: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` e `PermissionDenied`. Adicioná-lo a qualquer outro evento impede o hook de executar.

780 792 


785Onde você adiciona um hook determina seu escopo:797Onde você adiciona um hook determina seu escopo:

786 798 

787| Local | Escopo | Compartilhável |799| Local | Escopo | Compartilhável |

788| :---------------------------------------------------------- | :------------------------------------ | :------------------------------------- |800| :---------------------------------------------------------- | :------------------------------------ | :---------------------------------------- |

789| `~/.claude/settings.json` | Todos os seus projetos | Não, local para sua máquina |801| `~/.claude/settings.json` | Todos os seus projetos | Não, local para sua máquina |

790| `.claude/settings.json` | Projeto único | Sim, pode ser commitado no repo |802| `.claude/settings.json` | Projeto único | Sim, pode ser commitado no repo |

791| `.claude/settings.local.json` | Projeto único | Não, gitignored |803| `.claude/settings.local.json` | Projeto único | Não, gitignored quando Claude Code o cria |

792| Configurações de política gerenciada | Organização inteira | Sim, controlado por admin |804| Configurações de política gerenciada | Organização inteira | Sim, controlado por admin |

793| [Plugin](/pt/plugins) `hooks/hooks.json` | Quando o plugin está habilitado | Sim, empacotado com o plugin |805| [Plugin](/pt/plugins) `hooks/hooks.json` | Quando o plugin está habilitado | Sim, empacotado com o plugin |

794| [Skill](/pt/skills) ou [agente](/pt/sub-agents) frontmatter | Enquanto a skill ou agente está ativo | Sim, definido no arquivo do componente |806| [Skill](/pt/skills) ou [agente](/pt/sub-agents) frontmatter | Enquanto a skill ou agente está ativo | Sim, definido no arquivo do componente |

795 807 

796Execute [`/hooks`](/pt/hooks#the-hooks-menu) no Claude Code para navegar por todos os hooks configurados agrupados por evento. Para desabilitar hooks, defina `"disableAllHooks": true` no seu arquivo de configuração. Hooks configurados em configurações gerenciadas ainda executam a menos que `disableAllHooks` também esteja definido lá.808Execute [`/hooks`](/pt/hooks#the-%2Fhooks-menu) no Claude Code para navegar por todos os hooks configurados agrupados por evento. Para desabilitar hooks, defina `"disableAllHooks": true` no seu arquivo de configuração. Hooks configurados em configurações gerenciadas ainda executam a menos que `disableAllHooks` também esteja definido lá.

797 809 

798Se você editar arquivos de configuração diretamente enquanto Claude Code está em execução, o observador de arquivo normalmente pega mudanças de hook automaticamente.810Se você editar arquivos de configuração diretamente enquanto Claude Code está em execução, o observador de arquivo normalmente pega mudanças de hook automaticamente.

799 811 


872 HTTP hooks884 HTTP hooks

873</h2>885</h2>

874 886 

875Use hooks `type: "http"` para POST dados de evento para um endpoint HTTP em vez de executar um comando shell. O endpoint recebe o mesmo JSON que um hook de comando receberia em stdin, e retorna resultados através do corpo da resposta HTTP usando o mesmo formato JSON.887Use `type: "http"` hooks para fazer POST de dados de evento para um endpoint HTTP em vez de executar um comando shell. O endpoint recebe o mesmo JSON que um hook de comando receberia em stdin, e retorna resultados através do corpo da resposta HTTP usando o mesmo formato JSON.

876 888 

877HTTP hooks são úteis quando você quer que um servidor web, função em nuvem ou serviço externo manipule a lógica do hook: por exemplo, um serviço de auditoria compartilhado que registra eventos de uso de ferramenta em toda uma equipe.889HTTP hooks são úteis quando você quer que um servidor web, função em nuvem ou serviço externo manipule a lógica do hook: por exemplo, um serviço de auditoria compartilhado que registra eventos de uso de ferramenta em toda uma equipe.

878 890 

879Este exemplo posta cada uso de ferramenta para um serviço de logging local:891Este exemplo faz POST de cada uso de ferramenta para um serviço de logging local:

880 892 

881```json theme={null}893```json theme={null}

882{894{

Details

16 16 

17Quando você dá uma tarefa a Claude, ele trabalha através de três fases: **reunir contexto**, **tomar ação** e **verificar resultados**. Essas fases se misturam. Claude usa ferramentas ao longo do processo, seja pesquisando arquivos para entender seu código, editando para fazer alterações ou executando testes para verificar seu trabalho.17Quando você dá uma tarefa a Claude, ele trabalha através de três fases: **reunir contexto**, **tomar ação** e **verificar resultados**. Essas fases se misturam. Claude usa ferramentas ao longo do processo, seja pesquisando arquivos para entender seu código, editando para fazer alterações ou executando testes para verificar seu trabalho.

18 18 

19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agentic-loop.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=4a30fb7ce2815012a9f27c955e2c6bb0" alt="O loop agentic: Seu prompt leva Claude a reunir contexto, tomar ação, verificar resultados e repetir até que a tarefa seja concluída. Você pode interromper em qualquer ponto." width="720" height="280" data-path="images/agentic-loop.svg" />19<img src="https://mintcdn.com/claude-code/ikqp3_70mqIahteV/images/agentic-loop.svg?fit=max&auto=format&n=ikqp3_70mqIahteV&q=85&s=4a30fb7ce2815012a9f27c955e2c6bb0" alt="Diagrama do loop agentic: Seu prompt leva Claude a reunir contexto, tomar ação, verificar resultados e repetir até que a tarefa seja concluída. Você pode interromper em qualquer ponto." width="720" height="280" data-path="images/agentic-loop.svg" />

20 20 

21O loop se adapta ao que você pede. Uma pergunta sobre sua base de código pode precisar apenas de coleta de contexto. Uma correção de bug passa por todas as três fases repetidamente. Uma refatoração pode envolver verificação extensiva. Claude decide o que cada etapa requer com base no que aprendeu da etapa anterior, encadeando dezenas de ações e se autocorrigindo ao longo do caminho.21O loop se adapta ao que você pede. Uma pergunta sobre sua base de código pode precisar apenas de coleta de contexto. Uma correção de bug passa por todas as três fases repetidamente. Uma refatoração pode envolver verificação extensiva. Claude decide o que cada etapa requer com base no que aprendeu da etapa anterior, encadeando dezenas de ações e se autocorrigindo ao longo do caminho.

22 22 


176 Desfaça alterações com checkpoints176 Desfaça alterações com checkpoints

177</h3>177</h3>

178 178 

179**Cada edição de arquivo é reversível.** Antes de Claude editar qualquer arquivo, ele tira um snapshot do conteúdo atual. Se algo der errado, pressione `Esc` duas vezes para retroceder a um estado anterior ou peça a Claude para desfazer.179**Cada edição de arquivo é reversível.** Antes de Claude editar qualquer arquivo, ele tira um snapshot do conteúdo atual. Se algo der errado, pressione `Esc` duas vezes para retroceder a um estado anterior, ou peça a Claude para desfazer.

180 180 

181Checkpoints são locais para sua sessão, separados do git. Eles cobrem apenas alterações de arquivo. Ações que afetam sistemas remotos (bancos de dados, APIs, implantações) não podem ser checkpointed, é por isso que Claude pergunta antes de executar comandos com efeitos colaterais externos.181Checkpoints são locais para sua sessão, separados do git. Eles cobrem apenas alterações de arquivo. Ações que afetam sistemas remotos (bancos de dados, APIs, implantações) não podem ser checkpointed, é por isso que Claude pergunta antes de executar comandos com efeitos colaterais externos.

182 182 


188 188 

189* **Padrão**: Claude pergunta antes de edições de arquivo e comandos shell189* **Padrão**: Claude pergunta antes de edições de arquivo e comandos shell

190* **Auto-aceitar edições**: Claude edita arquivos e executa comandos comuns do sistema de arquivos como `mkdir` e `mv` sem perguntar, ainda pergunta por outros comandos190* **Auto-aceitar edições**: Claude edita arquivos e executa comandos comuns do sistema de arquivos como `mkdir` e `mv` sem perguntar, ainda pergunta por outros comandos

191* **Plan Mode**: Claude usa apenas ferramentas somente leitura, criando um plano que você pode aprovar antes da execução191* **Plan Mode**: Claude explora e propõe um plano sem editar seus arquivos de origem; prompts de permissão ainda se aplicam como no modo padrão

192* **Auto mode**: Claude avalia todas as ações com verificações de segurança em segundo plano. Atualmente uma visualização de pesquisa192* **Auto mode**: Claude avalia todas as ações com verificações de segurança em segundo plano. Atualmente uma visualização de pesquisa

193 193 

194Você também pode permitir comandos específicos em `.claude/settings.json` para que Claude não pergunte cada vez. Isso é útil para comandos confiáveis como `npm test` ou `git status`. As configurações podem ser escopo de políticas em toda a organização até preferências pessoais. Consulte [Permissões](/pt/permissions) para detalhes.194Você também pode permitir comandos específicos em `.claude/settings.json` para que Claude não pergunte cada vez. Isso é útil para comandos confiáveis como `npm test` ou `git status`. As configurações podem ser escopo de políticas em toda a organização até preferências pessoais. Consulte [Permissões](/pt/permissions) para detalhes.


213* `/agents` ajuda você a configurar subagents personalizados213* `/agents` ajuda você a configurar subagents personalizados

214* `/doctor` diagnostica problemas comuns com sua instalação214* `/doctor` diagnostica problemas comuns com sua instalação

215 215 

216<h3 id="it-s-a-conversation">216<h3 id="its-a-conversation">

217 É uma conversa217 É uma conversa

218</h3>218</h3>

219 219 


282 282 

283Revise o plano, refine-o através de conversa, depois deixe Claude implementar. Essa abordagem de duas fases produz melhores resultados do que pular direto para código.283Revise o plano, refine-o através de conversa, depois deixe Claude implementar. Essa abordagem de duas fases produz melhores resultados do que pular direto para código.

284 284 

285<h3 id="delegate-don-t-dictate">285<h3 id="delegate-dont-dictate">

286 Delegue, não dite286 Delegue, não dite

287</h3>287</h3>

288 288 


295 295 

296Você não precisa especificar quais arquivos ler ou quais comandos executar. Claude descobre isso.296Você não precisa especificar quais arquivos ler ou quais comandos executar. Claude descobre isso.

297 297 

298<h2 id="what-s-next">298<h2 id="whats-next">

299 O que vem a seguir299 O que vem a seguir

300</h2>300</h2>

301 301 

Details

27</h3>27</h3>

28 28 

29| Atalho | Descrição | Contexto |29| Atalho | Descrição | Contexto |

30| :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |30| :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

31| `Ctrl+C` | Interromper, ou limpar entrada | Interrompe uma operação em execução. Se nada estiver em execução, o primeiro pressionamento limpa a entrada do prompt e um segundo pressionamento sai do Claude Code |31| `Ctrl+C` | Interromper, ou limpar entrada | Interrompe uma operação em execução. Se nada estiver em execução, o primeiro pressionamento limpa a entrada do prompt e um segundo pressionamento sai do Claude Code |

32| `Ctrl+X Ctrl+K` | Encerrar todos os [subagentes em segundo plano](/pt/sub-agents#run-subagents-in-foreground-or-background) nesta sessão. Pressione duas vezes em 3 segundos para confirmar | Controle de subagente |32| `Ctrl+X Ctrl+K` | Encerrar todos os [subagentes em segundo plano](/pt/sub-agents#run-subagents-in-foreground-or-background) nesta sessão. Pressione duas vezes em 3 segundos para confirmar | Controle de subagente |

33| `Ctrl+D` | Sair da sessão do Claude Code | Sinal EOF |33| `Ctrl+D` | Sair da sessão do Claude Code | Sinal EOF |


39| `Ctrl+B` | Tarefas em execução em segundo plano | Coloca comandos bash e agentes em segundo plano. Usuários de Tmux pressione duas vezes |39| `Ctrl+B` | Tarefas em execução em segundo plano | Coloca comandos bash e agentes em segundo plano. Usuários de Tmux pressione duas vezes |

40| `Ctrl+T` | Alternar lista de tarefas | Mostrar ou ocultar a [lista de tarefas](#task-list) na área de status do terminal |40| `Ctrl+T` | Alternar lista de tarefas | Mostrar ou ocultar a [lista de tarefas](#task-list) na área de status do terminal |

41| `Left/Right arrows` | Ciclar através de abas de diálogo | Navegue entre abas em diálogos de permissão e menus |41| `Left/Right arrows` | Ciclar através de abas de diálogo | Navegue entre abas em diálogos de permissão e menus |

42| `Up/Down arrows` ou `Ctrl+P`/`Ctrl+N` | Mover cursor ou navegar histórico de comandos | Em entrada multilinha, primeiro move o cursor dentro do prompt. Uma vez que o cursor está na borda superior ou inferior, pressionar novamente navega pelo histórico de comandos |42| `Up/Down arrows` ou `Ctrl+P`/`Ctrl+N` | Mover cursor ou navegar histórico de comandos | Quando a entrada abrange mais de uma linha visual, seja envolvida ou multilinha, primeiro move o cursor dentro do prompt. Uma vez que o cursor está na primeira ou última linha visual, pressionar novamente navega pelo histórico de comandos. {/* min-version: 2.1.169 */}A partir da v2.1.169, entrada de linha única envolvida se comporta da mesma forma que multilinha |

43| `Esc` | Interromper Claude | Pare a resposta atual ou chamada de ferramenta no meio da vez para que você possa redirecionar. Claude mantém o trabalho realizado até agora |43| `Esc` | Interromper Claude | Pare a resposta atual ou chamada de ferramenta no meio da vez para que você possa redirecionar. Claude mantém o trabalho realizado até agora |

44| `Esc` + `Esc` | Limpar rascunho de entrada, ou retroceder | Quando a entrada do prompt contém texto, duplo `Esc` limpa e salva o rascunho no histórico para que `Up` o recupere. Quando a entrada está vazia, duplo `Esc` abre o [menu de retrocesso](/pt/checkpointing) para restaurar ou resumir código e conversa de um ponto anterior |44| `Esc` + `Esc` | Limpar rascunho de entrada, ou retroceder | Quando a entrada do prompt contém texto, duplo `Esc` limpa e salva o rascunho no histórico para que `Up` o recupere. Quando a entrada está vazia, duplo `Esc` abre o [menu de retrocesso](/pt/checkpointing) para restaurar ou resumir código e conversa de um ponto anterior |

45| `Shift+Tab` ou `Alt+M` (algumas configurações) | Alternar modos de permissão | Alternar entre `default`, `acceptEdits`, `plan` e qualquer modo que você tenha ativado, como `auto` ou `bypassPermissions`. Veja [modos de permissão](/pt/permission-modes). |45| `Shift+Tab` ou `Alt+M` (algumas configurações) | Alternar modos de permissão | Alternar entre `default`, `acceptEdits`, `plan` e qualquer modo que você tenha ativado, como `auto` ou `bypassPermissions`. Veja [modos de permissão](/pt/permission-modes). |

46| `Option+P` (macOS) ou `Alt+P` (Windows/Linux) | Alternar modelo | Alternar modelos sem limpar seu prompt |46| `Option+P` (macOS) ou `Alt+P` (Windows/Linux) | Alternar modelo | Alternar modelos sem limpar seu prompt |

47| `Option+T` (macOS) ou `Alt+T` (Windows/Linux) | Alternar pensamento estendido | Ativar ou desativar modo de pensamento estendido. {/* min-version: 2.1.132 */}A partir da v2.1.132, este atalho funciona no macOS sem configurar Option como Meta |47| `Option+T` (macOS) ou `Alt+T` (Windows/Linux) | Alternar pensamento estendido | Ativar ou desativar modo de pensamento estendido. Não tem efeito no Fable 5, que sempre usa pensamento estendido. {/* min-version: 2.1.132 */}A partir da v2.1.132 este atalho funciona no macOS sem configurar Option como Meta |

48| `Option+O` (macOS) ou `Alt+O` (Windows/Linux) | Alternar modo rápido | Ativar ou desativar [modo rápido](/pt/fast-mode) |48| `Option+O` (macOS) ou `Alt+O` (Windows/Linux) | Alternar modo rápido | Ativar ou desativar [modo rápido](/pt/fast-mode) |

49 49 

50<h3 id="text-editing">50<h3 id="text-editing">


372| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |372| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

373| `Space`, `Enter`, `Escape` | Descartar a resposta e retornar ao prompt |373| `Space`, `Enter`, `Escape` | Descartar a resposta e retornar ao prompt |

374| `Up` / `Down` | Rolar a resposta |374| `Up` / `Down` | Rolar a resposta |

375| `c` | Copiar a resposta para sua área de transferência como Markdown bruto. Use isto em vez de seleção com mouse, que captura a renderização do terminal com quebra de linha rígida em vez do texto de origem |

375| `f` | Dividir em uma nova sessão. A divisão herda a conversa pai mais esta pergunta e resposta como voltas de transcrição reais, então você pode continuar com acesso completo a ferramentas. A sessão original é preservada em [`/resume`](/pt/commands). Disponível apenas em sessões locais |376| `f` | Dividir em uma nova sessão. A divisão herda a conversa pai mais esta pergunta e resposta como voltas de transcrição reais, então você pode continuar com acesso completo a ferramentas. A sessão original é preservada em [`/resume`](/pt/commands). Disponível apenas em sessões locais |

376| `x` | Limpar a lista de trocas `/btw` anteriores mostradas acima da resposta atual |377| `x` | Limpar a lista de trocas `/btw` anteriores mostradas acima da resposta atual |

377 378 

jetbrains.md +13 −5

Details

35 Instalação35 Instalação

36</h2>36</h2>

37 37 

38<h3 id="marketplace-installation">38O plugin executa o comando `claude` no terminal integrado do seu IDE e se conecta a ele. Ele não agrupa sua própria cópia da CLI, portanto instale ambas as partes:

39 Instalação do Marketplace39 

40</h3>40<Steps>

41 <Step title="Instale o Claude Code CLI">

42 Siga o [guia de início rápido](/pt/quickstart) para instalar a CLI se você ainda não o fez. O plugin mostra uma notificação "Cannot launch Claude Code" quando `claude` não está no seu PATH.

43 </Step>

44 

45 <Step title="Instale o plugin JetBrains">

46 Instale o [plugin Claude Code](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) do JetBrains Marketplace e reinicie seu IDE.

47 </Step>

48</Steps>

41 49 

42Encontre e instale o [plugin Claude Code](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) do marketplace JetBrains e reinicie seu IDE.50Se `claude` estiver instalado em algum lugar que seu IDE não consiga encontrar, defina o caminho completo na [configuração do comando Claude](#general-settings) do plugin.

43 51 

44Se você ainda não instalou Claude Code, consulte o [guia de início rápido](/pt/quickstart) para instruções de instalação.52Claude Code funciona com qualquer assinatura Claude paga (Pro, Max, Team ou Enterprise) ou uma conta Claude Console, e nenhuma chave de API é necessária. Você será solicitado a [fazer login](/pt/authentication#log-in-to-claude-code) na primeira vez que executar `claude`.

45 53 

46<Note>54<Note>

47 Após instalar o plugin, você pode precisar reiniciar completamente seu IDE para que ele entre em vigor.55 Após instalar o plugin, você pode precisar reiniciar completamente seu IDE para que ele entre em vigor.

keybindings.md +6 −6

Details

16 Arquivo de configuração16 Arquivo de configuração

17</h2>17</h2>

18 18 

19O arquivo de configuração de keybindings é um objeto com um array `bindings`. Cada bloco especifica um contexto e um mapa de sequências de teclas para ações.19O arquivo de configuração de atalhos de teclado é um objeto com um array `bindings`. Cada bloco especifica um contexto e um mapa de sequências de teclas para ações.

20 20 

21<Note>As alterações no arquivo de keybindings são detectadas automaticamente e aplicadas sem reiniciar Claude Code.</Note>21<Note>As alterações no arquivo de atalhos de teclado são detectadas automaticamente e aplicadas sem reiniciar Claude Code.</Note>

22 22 

23| Campo | Descrição |23| Campo | Descrição |

24| :--------- | :------------------------------------------------------- |24| :--------- | :------------------------------------------------------- |


203Ações disponíveis no contexto `Task`:203Ações disponíveis no contexto `Task`:

204 204 

205| Ação | Padrão | Descrição |205| Ação | Padrão | Descrição |

206| :---------------- | :----- | :------------------------------------ |206| :---------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |

207| `task:background` | Ctrl+B | Colocar tarefa atual em segundo plano |207| `task:background` | Ctrl+B, Ctrl+X Ctrl+B | Colocar tarefa atual em segundo plano. {/* min-version: 2.1.169 */}O acorde Ctrl+X Ctrl+B requer v2.1.169 ou posterior e evita o conflito de prefixo do tmux |

208 208 

209<h3 id="theme-actions">209<h3 id="theme-actions">

210 Ações de tema210 Ações de tema


537 Validação537 Validação

538</h2>538</h2>

539 539 

540Claude Code valida seus keybindings e mostra avisos para:540Claude Code valida seus atalhos de teclado e mostra avisos para:

541 541 

542* Erros de análise (JSON inválido ou estrutura)542* Erros de análise (JSON inválido ou estrutura)

543* Nomes de contexto inválidos543* Nomes de contexto inválidos


545* Conflitos de multiplexador de terminal545* Conflitos de multiplexador de terminal

546* Vinculações duplicadas no mesmo contexto546* Vinculações duplicadas no mesmo contexto

547 547 

548Execute `/doctor` para ver quaisquer avisos de keybindings.548Execute `/doctor` para ver quaisquer avisos de atalhos de teclado.

Details

148 148 

149Use isso para diretórios em que você nunca trabalha, como pacotes de outras equipes, código legado ou subárvores fornecidas. A lista de exclusão é estática, não um switch por tarefa. Para focar em um pacote hoje e outro amanhã, [inicie Claude do diretório desse pacote](#choose-where-to-start-claude) em vez de editar exclusões.149Use isso para diretórios em que você nunca trabalha, como pacotes de outras equipes, código legado ou subárvores fornecidas. A lista de exclusão é estática, não um switch por tarefa. Para focar em um pacote hoje e outro amanhã, [inicie Claude do diretório desse pacote](#choose-where-to-start-claude) em vez de editar exclusões.

150 150 

151Se você quer apenas essas exclusões para você, coloque a configuração em `.claude/settings.local.json`, que é gitignored e não confirmado. Os padrões usam sintaxe glob correspondida contra caminhos de arquivo absolutos, então comece padrões de estilo relativo com `**/` para corresponder em qualquer lugar da árvore. O exemplo abaixo exclui pacotes pertencentes a outras equipes:151Se você quer apenas essas exclusões para você, coloque a configuração em `.claude/settings.local.json`. Claude Code gitignores esse arquivo quando o cria; já que você está criando manualmente aqui, adicione-o ao seu gitignore. Os padrões usam sintaxe glob correspondida contra caminhos de arquivo absolutos, então comece padrões de estilo relativo com `**/` para corresponder em qualquer lugar da árvore. O exemplo abaixo exclui pacotes pertencentes a outras equipes:

152 152 

153```json .claude/settings.local.json theme={null}153```json .claude/settings.local.json theme={null}

154{154{

llm-gateway.md +2 −0

Details

14* **Registro de auditoria** - Rastreie todas as interações de modelo para conformidade14* **Registro de auditoria** - Rastreie todas as interações de modelo para conformidade

15* **Roteamento de modelo** - Alterne entre provedores sem alterações de código15* **Roteamento de modelo** - Alterne entre provedores sem alterações de código

16 16 

17Esta página aborda os requisitos de gateway e a configuração para o Claude Code CLI. As implantações do Enterprise Desktop podem configurar provedores de gateway por meio de [configurações gerenciadas](https://support.claude.com/pt/articles/12622667-enterprise-configuration). O aplicativo Claude Desktop também pode ser executado em um gateway auto-hospedado através da [visualização de pesquisa Cowork on 3P](https://claude.com/docs/cowork/3p/gateway), que usa suas próprias chaves de configuração.

18 

17<h2 id="gateway-requirements">19<h2 id="gateway-requirements">

18 Requisitos do gateway20 Requisitos do gateway

19</h2>21</h2>

mcp.md +159 −73

Details

12 12 

13Se você está conectando seu primeiro servidor, comece com o [guia de início rápido do MCP](/pt/mcp-quickstart) para um passo a passo detalhado. Esta página é a referência completa.13Se você está conectando seu primeiro servidor, comece com o [guia de início rápido do MCP](/pt/mcp-quickstart) para um passo a passo detalhado. Esta página é a referência completa.

14 14 

15## O que você pode fazer com MCP15<h2 id="what-you-can-do-with-mcp">

16 O que você pode fazer com MCP

17</h2>

16 18 

17Com servidores MCP conectados, você pode pedir ao Claude Code para:19Com servidores MCP conectados, você pode pedir ao Claude Code para:

18 20 


23* **Automatizar fluxos de trabalho**: "Crie rascunhos do Gmail convidando esses 10 usuários para uma sessão de feedback sobre o novo recurso."25* **Automatizar fluxos de trabalho**: "Crie rascunhos do Gmail convidando esses 10 usuários para uma sessão de feedback sobre o novo recurso."

24* **Reagir a eventos externos**: Um servidor MCP também pode atuar como um [canal](/pt/channels) que envia mensagens para sua sessão, para que Claude reaja a mensagens do Telegram, chats do Discord ou eventos de webhook enquanto você está ausente.26* **Reagir a eventos externos**: Um servidor MCP também pode atuar como um [canal](/pt/channels) que envia mensagens para sua sessão, para que Claude reaja a mensagens do Telegram, chats do Discord ou eventos de webhook enquanto você está ausente.

25 27 

26## Encontre e crie servidores MCP28<h2 id="find-and-build-mcp-servers">

29 Encontre e crie servidores MCP

30</h2>

27 31 

28Navegue por conectores revisados no [Diretório Anthropic](https://claude.ai/directory). Os conectores do Diretório usam a mesma infraestrutura MCP que Claude Code, então você pode adicionar qualquer servidor remoto listado lá com `claude mcp add`.32Navegue por conectores revisados no [Diretório Anthropic](https://claude.ai/directory). Os conectores do Diretório usam a mesma infraestrutura MCP que Claude Code, então você pode adicionar qualquer servidor remoto listado lá com `claude mcp add`.

29 33 


55 </Step>59 </Step>

56</Steps>60</Steps>

57 61 

58## Instalando servidores MCP62<h2 id="installing-mcp-servers">

63 Instalando servidores MCP

64</h2>

59 65 

60Os servidores MCP podem ser configurados de várias maneiras dependendo de suas necessidades:66Os servidores MCP podem ser configurados de várias maneiras dependendo de suas necessidades:

61 67 

62### Opção 1: Adicionar um servidor HTTP remoto68<h3 id="option-1-add-a-remote-http-server">

69 Opção 1: Adicionar um servidor HTTP remoto

70</h3>

63 71 

64Servidores HTTP são a opção recomendada para conectar a servidores MCP remotos. Este é o transporte mais amplamente suportado para serviços baseados em nuvem.72Servidores HTTP são a opção recomendada para conectar a servidores MCP remotos. Este é o transporte mais amplamente suportado para serviços baseados em nuvem.

65 73 


77 85 

78Ao configurar servidores MCP via JSON em `.mcp.json`, `~/.claude.json`, ou `claude mcp add-json`, o campo `type` aceita `streamable-http` como um alias para `http`. A especificação MCP usa o nome `streamable-http` para este transporte, portanto as configurações copiadas da documentação do servidor funcionam sem modificação.86Ao configurar servidores MCP via JSON em `.mcp.json`, `~/.claude.json`, ou `claude mcp add-json`, o campo `type` aceita `streamable-http` como um alias para `http`. A especificação MCP usa o nome `streamable-http` para este transporte, portanto as configurações copiadas da documentação do servidor funcionam sem modificação.

79 87 

80### Opção 2: Adicionar um servidor SSE remoto88<h3 id="option-2-add-a-remote-sse-server">

89 Opção 2: Adicionar um servidor SSE remoto

90</h3>

81 91 

82<Warning>92<Warning>

83 O transporte SSE (Server-Sent Events) está descontinuado. Use servidores HTTP em vez disso, quando disponível.93 O transporte SSE (Server-Sent Events) está descontinuado. Use servidores HTTP em vez disso, quando disponível.


95 --header "X-API-Key: your-key-here"105 --header "X-API-Key: your-key-here"

96```106```

97 107 

98### Opção 3: Adicionar um servidor stdio local108<h3 id="option-3-add-a-local-stdio-server">

109 Opção 3: Adicionar um servidor stdio local

110</h3>

99 111 

100Servidores Stdio são executados como processos locais em sua máquina. Eles são ideais para ferramentas que precisam de acesso direto ao sistema ou scripts personalizados.112Servidores Stdio são executados como processos locais em sua máquina. Eles são ideais para ferramentas que precisam de acesso direto ao sistema ou scripts personalizados.

101 113 


108claude mcp add [options] <name> -- <command> [args...]120claude mcp add [options] <name> -- <command> [args...]

109 121 

110# Exemplo real: Adicionar servidor Airtable122# Exemplo real: Adicionar servidor Airtable

111claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \123claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \

112 -- npx -y airtable-mcp-server124 -- npx -y airtable-mcp-server

113```125```

114 126 

115<Note>127<Note>

116 **Importante: Ordenação de opções**128 **Importante: Separar argumentos do servidor com `--`**

117 129 

118 Todas as opções (`--transport`, `--env`, `--scope`, `--header`) devem vir **antes** do nome do servidor. O `--` (travessão duplo) então separa o nome do servidor do comando e argumentos que são passados para o servidor MCP.130 Para servidores stdio, o `--` (travessão duplo) separa as próprias opções do Claude, como `--transport`, `--env` e `--scope`, do comando e argumentos que executam o servidor. Tudo após `--` é passado para o servidor sem modificação.

119 131 

120 Por exemplo:132 Por exemplo:

121 133 

122 * `claude mcp add --transport stdio myserver -- npx server` → executa `npx server`134 * `claude mcp add --transport stdio myserver -- npx server` → executa `npx server`

123 * `claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080` → executa `python server.py --port 8080` com `KEY=value` no ambiente135 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → executa `python server.py --port 8080` com `KEY=value` no ambiente

124 136 

125 Isso evita conflitos entre as flags do Claude e as flags do servidor.137 Sem `--`, Claude Code tentaria analisar as flags do servidor, como `--port` acima, como suas próprias opções.

138 

139 `--env` aceita múltiplos pares `KEY=value`. Se o nome do servidor vem diretamente após `--env`, a CLI lê o nome como outro par e o rejeita, portanto coloque pelo menos uma outra opção entre `--env` e o nome do servidor, como nos exemplos acima.

126</Note>140</Note>

127 141 

128### Opção 4: Adicionar um servidor WebSocket remoto142<h3 id="option-4-add-a-remote-websocket-server">

143 Opção 4: Adicionar um servidor WebSocket remoto

144</h3>

129 145 

130Servidores WebSocket mantêm uma conexão bidirecional persistente, o que é adequado para servidores MCP remotos que enviam eventos para Claude sem solicitação. Use HTTP em vez disso quando seu servidor apenas responde a solicitações, já que HTTP suporta OAuth e a flag `claude mcp add --transport`, enquanto WebSocket não suporta nenhum dos dois.146Servidores WebSocket mantêm uma conexão bidirecional persistente, o que é adequado para servidores MCP remotos que enviam eventos para Claude sem solicitação. Use HTTP em vez disso quando seu servidor apenas responde a solicitações, já que HTTP suporta OAuth e a flag `claude mcp add --transport`, enquanto WebSocket não suporta nenhum dos dois.

131 147 


138 154 

139A entrada `type: "ws"` aceita os mesmos campos `url`, `headers`, `headersHelper`, `timeout` e `alwaysLoad` que `http`. A autenticação é apenas por cabeçalho, portanto passe um token estático em `headers` ou gere um no momento da conexão com [`headersHelper`](#use-dynamic-headers-for-custom-authentication). A flag `claude mcp add --transport` não aceita `ws`.155A entrada `type: "ws"` aceita os mesmos campos `url`, `headers`, `headersHelper`, `timeout` e `alwaysLoad` que `http`. A autenticação é apenas por cabeçalho, portanto passe um token estático em `headers` ou gere um no momento da conexão com [`headersHelper`](#use-dynamic-headers-for-custom-authentication). A flag `claude mcp add --transport` não aceita `ws`.

140 156 

141### Gerenciando seus servidores157<h3 id="managing-your-servers">

158 Gerenciando seus servidores

159</h3>

142 160 

143Uma vez configurados, você pode gerenciar seus servidores MCP com estes comandos:161Uma vez configurados, você pode gerenciar seus servidores MCP com estes comandos:

144 162 


164 182 

165O nome do servidor `workspace` é reservado para uso interno. Se sua configuração define um servidor com esse nome, Claude Code o ignora no tempo de carregamento e mostra um aviso pedindo que você o renomeie.183O nome do servidor `workspace` é reservado para uso interno. Se sua configuração define um servidor com esse nome, Claude Code o ignora no tempo de carregamento e mostra um aviso pedindo que você o renomeie.

166 184 

167### Atualizações dinâmicas de ferramentas185<h3 id="dynamic-tool-updates">

186 Atualizações dinâmicas de ferramentas

187</h3>

168 188 

169Claude Code suporta notificações MCP `list_changed`, permitindo que servidores MCP atualizem dinamicamente suas ferramentas, prompts e recursos disponíveis sem exigir que você se desconecte e reconecte. Quando um servidor MCP envia uma notificação `list_changed`, Claude Code atualiza automaticamente as capacidades disponíveis desse servidor.189Claude Code suporta notificações MCP `list_changed`, permitindo que servidores MCP atualizem dinamicamente suas ferramentas, prompts e recursos disponíveis sem exigir que você se desconecte e reconecte. Quando um servidor MCP envia uma notificação `list_changed`, Claude Code atualiza automaticamente as capacidades disponíveis desse servidor.

170 190 

171### Reconexão automática191<h3 id="automatic-reconnection">

192 Reconexão automática

193</h3>

172 194 

173Se um servidor HTTP ou SSE se desconectar durante a sessão, Claude Code se reconecta automaticamente com backoff exponencial: até cinco tentativas, começando com um atraso de um segundo e dobrando a cada vez. O servidor aparece como pendente em `/mcp` enquanto a reconexão está em andamento. Após cinco tentativas falhadas, o servidor é marcado como falho e você pode tentar novamente manualmente de `/mcp`. Servidores Stdio são processos locais e não são reconectados automaticamente.195Se um servidor HTTP ou SSE se desconectar durante a sessão, Claude Code se reconecta automaticamente com backoff exponencial: até cinco tentativas, começando com um atraso de um segundo e dobrando a cada vez. O servidor aparece como pendente em `/mcp` enquanto a reconexão está em andamento. Após cinco tentativas falhadas, o servidor é marcado como falho e você pode tentar novamente manualmente de `/mcp`. Servidores Stdio são processos locais e não são reconectados automaticamente.

174 196 

175O mesmo backoff se aplica quando um servidor HTTP ou SSE falha sua conexão inicial na inicialização. A partir da v2.1.121, Claude Code tenta novamente a conexão inicial até três vezes em erros transitórios, como uma resposta 5xx, uma conexão recusada ou um tempo limite, e então marca o servidor como falho se ainda não conseguir se conectar. Erros de autenticação e não encontrado não são retentados porque exigem uma mudança de configuração para serem resolvidos.197O mesmo backoff se aplica quando um servidor HTTP ou SSE falha sua conexão inicial na inicialização. A partir da v2.1.121, Claude Code tenta novamente a conexão inicial até três vezes em erros transitórios, como uma resposta 5xx, uma conexão recusada ou um tempo limite, e então marca o servidor como falho se ainda não conseguir se conectar. Erros de autenticação e não encontrado não são retentados porque exigem uma mudança de configuração para serem resolvidos.

176 198 

177### Enviar mensagens com canais199<h3 id="push-messages-with-channels">

200 Enviar mensagens com canais

201</h3>

178 202 

179Um servidor MCP também pode enviar mensagens diretamente para sua sessão para que Claude possa reagir a eventos externos como resultados de CI, alertas de monitoramento ou mensagens de chat. Para habilitar isso, seu servidor declara a capacidade `claude/channel` e você a ativa com a flag `--channels` na inicialização. Veja [Canais](/pt/channels) para usar um canal oficialmente suportado, ou [Referência de canais](/pt/channels-reference) para construir o seu próprio.203Um servidor MCP também pode enviar mensagens diretamente para sua sessão para que Claude possa reagir a eventos externos como resultados de CI, alertas de monitoramento ou mensagens de chat. Para habilitar isso, seu servidor declara a capacidade `claude/channel` e você a ativa com a flag `--channels` na inicialização. Veja [Canais](/pt/channels) para usar um canal oficialmente suportado, ou [Referência de canais](/pt/channels-reference) para construir o seu próprio.

180 204 


192 * Use `/mcp` para autenticar com servidores remotos que exigem autenticação OAuth 2.0216 * Use `/mcp` para autenticar com servidores remotos que exigem autenticação OAuth 2.0

193</Tip>217</Tip>

194 218 

195O `timeout` por servidor é um limite de tempo de parede rígido por chamada de ferramenta, e notificações de progresso do servidor não o estendem. Valores abaixo de 1000 são arredondados para um segundo. Para servidores HTTP e SSE, o orçamento de primeiro byte por solicitação de busca tem um mínimo de 60 segundos independentemente deste valor, portanto apenas o watchdog de chamada de ferramenta honra valores menores.219O `timeout` por servidor é um limite de tempo de parede rígido por chamada de ferramenta, e notificações de progresso do servidor não o estendem. Valores abaixo de 1000 são ignorados e caem para `MCP_TOOL_TIMEOUT`, ou para seu padrão de cerca de 28 horas quando essa variável não está definida. {/* min-version: 2.1.162 */}Antes da v2.1.162, valores abaixo de 1000 eram arredondados para um segundo. Para servidores HTTP e SSE, o orçamento de primeiro byte por solicitação de busca tem um mínimo de 60 segundos.

196 220 

197### Servidores MCP fornecidos por plugins221<h3 id="plugin-provided-mcp-servers">

222 Servidores MCP fornecidos por plugins

223</h3>

198 224 

199[Plugins](/pt/plugins) podem agrupar servidores MCP, fornecendo automaticamente ferramentas e integrações quando o plugin está habilitado. Os servidores MCP de plugins funcionam de forma idêntica aos servidores configurados pelo usuário.225[Plugins](/pt/plugins) podem agrupar servidores MCP, fornecendo automaticamente ferramentas e integrações quando o plugin está habilitado. Os servidores MCP de plugins funcionam de forma idêntica aos servidores configurados pelo usuário.

200 226 


240**Recursos de MCP de plugin**:266**Recursos de MCP de plugin**:

241 267 

242* **Ciclo de vida automático**: Na inicialização da sessão, os servidores para plugins habilitados se conectam automaticamente. Se você habilitar ou desabilitar um plugin durante uma sessão, execute `/reload-plugins` para conectar ou desconectar seus servidores MCP268* **Ciclo de vida automático**: Na inicialização da sessão, os servidores para plugins habilitados se conectam automaticamente. Se você habilitar ou desabilitar um plugin durante uma sessão, execute `/reload-plugins` para conectar ou desconectar seus servidores MCP

243* **Variáveis de ambiente**: Use `${CLAUDE_PLUGIN_ROOT}` para arquivos agrupados do plugin, `${CLAUDE_PLUGIN_DATA}` para [estado persistente](/pt/plugins-reference#persistent-data-directory) que sobrevive a atualizações de plugins, e `${CLAUDE_PROJECT_DIR}` para a raiz do projeto estável269* **Variáveis de ambiente**: use `${CLAUDE_PLUGIN_ROOT}` para arquivos agrupados do plugin, `${CLAUDE_PLUGIN_DATA}` para [estado persistente](/pt/plugins-reference#persistent-data-directory) que sobrevive a atualizações de plugins, e `${CLAUDE_PROJECT_DIR}` para a raiz do projeto estável

244* **Acesso a variáveis de ambiente do usuário**: Acesso às mesmas variáveis de ambiente que servidores configurados manualmente270* **Acesso a variáveis de ambiente do usuário**: Acesso às mesmas variáveis de ambiente que servidores configurados manualmente

245* **Múltiplos tipos de transporte**: Suporte para transportes stdio, SSE, HTTP e WebSocket (o suporte de transporte pode variar por servidor)271* **Múltiplos tipos de transporte**: Suporte para transportes stdio, SSE, HTTP e WebSocket (o suporte de transporte pode variar por servidor)

246 272 


253 279 

254Os servidores de plugins aparecem na lista com indicadores mostrando que vêm de plugins.280Os servidores de plugins aparecem na lista com indicadores mostrando que vêm de plugins.

255 281 

282**Nomes de ferramentas MCP de plugin**:

283 

284As ferramentas de um servidor MCP agrupado em um plugin incluem tanto o nome do plugin quanto a chave do servidor em seu nome chamável. A forma completa é `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`, onde qualquer caractere fora de `A-Z`, `a-z`, `0-9`, `_` e `-` é substituído por `_`. Para o servidor `database-tools` agrupado em um plugin chamado `my-plugin`, uma ferramenta `query` é chamável como:

285 

286```

287mcp__plugin_my-plugin_database-tools__query

288```

289 

290Use este nome completo ao referenciar a ferramenta em [regras de permissão](/pt/permissions), na lista `allowed-tools` de uma skill, ou no [campo `tools` de um subagente](/pt/sub-agents#available-tools).

291 

256**Benefícios dos servidores MCP de plugins**:292**Benefícios dos servidores MCP de plugins**:

257 293 

258* **Distribuição agrupada**: Ferramentas e servidores empacotados juntos294* **Distribuição agrupada**: Ferramentas e servidores empacotados juntos


261 297 

262Veja a [referência de componentes de plugins](/pt/plugins-reference#mcp-servers) para detalhes sobre como agrupar servidores MCP com plugins.298Veja a [referência de componentes de plugins](/pt/plugins-reference#mcp-servers) para detalhes sobre como agrupar servidores MCP com plugins.

263 299 

264## Escopos de instalação de MCP300<h2 id="mcp-installation-scopes">

301 Escopos de instalação de MCP

302</h2>

265 303 

266Os servidores MCP podem ser configurados em três escopos. O escopo que você escolhe controla em quais projetos o servidor é carregado e se a configuração é compartilhada com sua equipe. Os administradores também podem implantar servidores no nível empresarial via [configuração gerenciada](#managed-mcp-configuration).304Os servidores MCP podem ser configurados em três escopos. O escopo que você escolhe controla em quais projetos o servidor é carregado e se a configuração é compartilhada com sua equipe. Os administradores também podem implantar servidores no nível empresarial via [configuração gerenciada](#managed-mcp-configuration).

267 305 


271| [Projeto](#project-scope) | Apenas projeto atual | Sim, via controle de versão | `.mcp.json` na raiz do projeto |309| [Projeto](#project-scope) | Apenas projeto atual | Sim, via controle de versão | `.mcp.json` na raiz do projeto |

272| [Usuário](#user-scope) | Todos os seus projetos | Não | `~/.claude.json` |310| [Usuário](#user-scope) | Todos os seus projetos | Não | `~/.claude.json` |

273 311 

274### Escopo local312<h3 id="local-scope">

313 Escopo local

314</h3>

275 315 

276O escopo local é o padrão. Um servidor com escopo local carrega apenas no projeto onde você o adicionou e permanece privado para você. Claude Code o armazena em `~/.claude.json` sob o caminho desse projeto, então o mesmo servidor não aparecerá em seus outros projetos. Use o escopo local para servidores de desenvolvimento pessoal, configurações experimentais ou servidores com credenciais que você não deseja no controle de versão.316O escopo local é o padrão. Um servidor com escopo local carrega apenas no projeto onde você o adicionou e permanece privado para você. Claude Code o armazena em `~/.claude.json` sob o caminho desse projeto, então o mesmo servidor não aparecerá em seus outros projetos. Use o escopo local para servidores de desenvolvimento pessoal, configurações experimentais ou servidores com credenciais que você não deseja no controle de versão.

277 317 


304}344}

305```345```

306 346 

307### Escopo de projeto347<h3 id="project-scope">

348 Escopo de projeto

349</h3>

308 350 

309Servidores com escopo de projeto permitem colaboração em equipe armazenando configurações em um arquivo `.mcp.json` no diretório raiz do seu projeto. Este arquivo é projetado para ser verificado no controle de versão, garantindo que todos os membros da equipe tenham acesso às mesmas ferramentas e serviços MCP. Quando você adiciona um servidor com escopo de projeto, Claude Code cria ou atualiza automaticamente este arquivo com a estrutura de configuração apropriada.351Servidores com escopo de projeto permitem colaboração em equipe armazenando configurações em um arquivo `.mcp.json` no diretório raiz do seu projeto. Este arquivo é projetado para ser verificado no controle de versão, garantindo que todos os membros da equipe tenham acesso às mesmas ferramentas e serviços MCP. Quando você adiciona um servidor com escopo de projeto, Claude Code cria ou atualiza automaticamente este arquivo com a estrutura de configuração apropriada.

310 352 


329 371 

330Por razões de segurança, Claude Code solicita aprovação antes de usar servidores com escopo de projeto de arquivos `.mcp.json`. Se você precisar redefinir essas escolhas de aprovação, use o comando `claude mcp reset-project-choices`.372Por razões de segurança, Claude Code solicita aprovação antes de usar servidores com escopo de projeto de arquivos `.mcp.json`. Se você precisar redefinir essas escolhas de aprovação, use o comando `claude mcp reset-project-choices`.

331 373 

332### Escopo de usuário374<h3 id="user-scope">

375 Escopo de usuário

376</h3>

333 377 

334Servidores com escopo de usuário são armazenados em `~/.claude.json` e fornecem acessibilidade entre projetos, tornando-os disponíveis em todos os projetos em sua máquina enquanto permanecem privados para sua conta de usuário. Este escopo funciona bem para servidores de utilitários pessoais, ferramentas de desenvolvimento ou serviços que você usa frequentemente em diferentes projetos.378Servidores com escopo de usuário são armazenados em `~/.claude.json` e fornecem acessibilidade entre projetos, tornando-os disponíveis em todos os projetos em sua máquina enquanto permanecem privados para sua conta de usuário. Este escopo funciona bem para servidores de utilitários pessoais, ferramentas de desenvolvimento ou serviços que você usa frequentemente em diferentes projetos.

335 379 


338claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic382claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

339```383```

340 384 

341### Hierarquia de escopo e precedência385<h3 id="scope-hierarchy-and-precedence">

386 Hierarquia de escopo e precedência

387</h3>

342 388 

343Quando o mesmo servidor é definido em mais de um lugar, Claude Code se conecta a ele uma vez, usando a definição da fonte com maior precedência. A entrada inteira do servidor dessa fonte é usada; os campos não são mesclados entre escopos.389Quando o mesmo servidor é definido em mais de um lugar, Claude Code se conecta a ele uma vez, usando a definição da fonte com maior precedência. A entrada inteira do servidor dessa fonte é usada; os campos não são mesclados entre escopos.

344 390 


350 396 

351Os três escopos correspondem duplicatas por nome. Plugins e conectores correspondem por endpoint, então um que aponta para a mesma URL ou comando que um servidor acima é tratado como uma duplicata.397Os três escopos correspondem duplicatas por nome. Plugins e conectores correspondem por endpoint, então um que aponta para a mesma URL ou comando que um servidor acima é tratado como uma duplicata.

352 398 

353### Expansão de variáveis de ambiente em `.mcp.json`399<h3 id="environment-variable-expansion-in-mcp-json">

400 Expansão de variáveis de ambiente em `.mcp.json`

401</h3>

354 402 

355Claude Code suporta expansão de variáveis de ambiente em arquivos `.mcp.json`, permitindo que equipes compartilhem configurações mantendo flexibilidade para caminhos específicos da máquina e valores sensíveis como chaves de API.403Claude Code suporta expansão de variáveis de ambiente em arquivos `.mcp.json`, permitindo que equipes compartilhem configurações mantendo flexibilidade para caminhos específicos da máquina e valores sensíveis como chaves de API.

356 404 


386 434 

387Se uma variável de ambiente necessária não estiver definida e não tiver um valor padrão, Claude Code falhará ao analisar a configuração.435Se uma variável de ambiente necessária não estiver definida e não tiver um valor padrão, Claude Code falhará ao analisar a configuração.

388 436 

389## Exemplos práticos437<h2 id="practical-examples">

438 Exemplos práticos

439</h2>

390 440 

391{/* ### Exemplo: Automatizar testes de navegador com Playwright441<h3 id="example-monitor-errors-with-sentry">

392 442 Exemplo: Monitorar erros com Sentry

393```bash443</h3>

394claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

395```

396 

397Então escreva e execute testes de navegador:

398 

399```text

400Teste se o fluxo de login funciona com test@example.com

401```

402```text

403Tire uma captura de tela da página de checkout em mobile

404```

405```text

406Verifique se o recurso de pesquisa retorna resultados

407``` */}

408 

409### Exemplo: Monitorar erros com Sentry

410 444 

411```bash theme={null}445```bash theme={null}

412claude mcp add --transport http sentry https://mcp.sentry.dev/mcp446claude mcp add --transport http sentry https://mcp.sentry.dev/mcp


432Qual implantação introduziu esses novos erros?466Qual implantação introduziu esses novos erros?

433```467```

434 468 

435### Exemplo: Conectar ao GitHub para revisões de código469<h3 id="example-connect-to-github-for-code-reviews">

470 Exemplo: Conectar ao GitHub para revisões de código

471</h3>

436 472 

437O servidor MCP remoto do GitHub autentica com um token de acesso pessoal do GitHub passado como cabeçalho. Para obter um, abra suas [configurações de token do GitHub](https://github.com/settings/personal-access-tokens), gere um novo token refinado com acesso aos repositórios com os quais você deseja que Claude trabalhe, então adicione o servidor:473O servidor MCP remoto do GitHub autentica com um token de acesso pessoal do GitHub passado como cabeçalho. Para obter um, abra suas [configurações de token do GitHub](https://github.com/settings/personal-access-tokens), gere um novo token refinado com acesso aos repositórios com os quais você deseja que Claude trabalhe, então adicione o servidor:

438 474 


455Mostre-me todos os PRs abertos atribuídos a mim491Mostre-me todos os PRs abertos atribuídos a mim

456```492```

457 493 

458### Exemplo: Consultar seu banco de dados PostgreSQL494<h3 id="example-query-your-postgresql-database">

495 Exemplo: Consultar seu banco de dados PostgreSQL

496</h3>

459 497 

460```bash theme={null}498```bash theme={null}

461claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \499claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \


476Encontre clientes que não fizeram uma compra em 90 dias514Encontre clientes que não fizeram uma compra em 90 dias

477```515```

478 516 

479## Autenticar com servidores MCP remotos517<h2 id="authenticate-with-remote-mcp-servers">

518 Autenticar com servidores MCP remotos

519</h2>

480 520 

481Muitos servidores MCP baseados em nuvem exigem autenticação. Claude Code suporta OAuth 2.0 para conexões seguras.521Muitos servidores MCP baseados em nuvem exigem autenticação. Claude Code suporta OAuth 2.0 para conexões seguras.

482 522 


514 * A autenticação OAuth funciona com servidores HTTP554 * A autenticação OAuth funciona com servidores HTTP

515</Tip>555</Tip>

516 556 

517### Usar uma porta de callback OAuth fixa557<h3 id="use-a-fixed-oauth-callback-port">

558 Usar uma porta de callback OAuth fixa

559</h3>

518 560 

519Alguns servidores MCP exigem um URI de redirecionamento específico registrado antecipadamente. Por padrão, Claude Code escolhe uma porta aleatória disponível para o callback OAuth. Use `--callback-port` para fixar a porta para que corresponda a um URI de redirecionamento pré-registrado do formulário `http://localhost:PORT/callback`.561Alguns servidores MCP exigem um URI de redirecionamento específico registrado antecipadamente. Por padrão, Claude Code escolhe uma porta aleatória disponível para o callback OAuth. Use `--callback-port` para fixar a porta para que corresponda a um URI de redirecionamento pré-registrado do formulário `http://localhost:PORT/callback`.

520 562 


527 my-server https://mcp.example.com/mcp569 my-server https://mcp.example.com/mcp

528```570```

529 571 

530### Usar credenciais OAuth pré-configuradas572<h3 id="use-pre-configured-oauth-credentials">

573 Usar credenciais OAuth pré-configuradas

574</h3>

531 575 

532Alguns servidores MCP não suportam configuração automática de OAuth via Registro Dinâmico de Cliente. Se você vir um erro como "Incompatible auth server: does not support dynamic client registration," o servidor requer credenciais pré-configuradas. Claude Code também suporta servidores que usam um Documento de Metadados de ID do Cliente (CIMD) em vez de Registro Dinâmico de Cliente, e descobre esses automaticamente. Se a descoberta automática falhar, registre um aplicativo OAuth através do portal do desenvolvedor do servidor primeiro, depois forneça as credenciais ao adicionar o servidor.576Alguns servidores MCP não suportam configuração automática de OAuth via Registro Dinâmico de Cliente. Se você vir um erro como "Incompatible auth server: does not support dynamic client registration," o servidor requer credenciais pré-configuradas. Claude Code também suporta servidores que usam um Documento de Metadados de ID do Cliente (CIMD) em vez de Registro Dinâmico de Cliente, e descobre esses automaticamente. Se a descoberta automática falhar, registre um aplicativo OAuth através do portal do desenvolvedor do servidor primeiro, depois forneça as credenciais ao adicionar o servidor.

533 577 


598 * Use `claude mcp get <name>` para verificar se as credenciais OAuth estão configuradas para um servidor642 * Use `claude mcp get <name>` para verificar se as credenciais OAuth estão configuradas para um servidor

599</Tip>643</Tip>

600 644 

601### Substituir descoberta de metadados OAuth645<h3 id="override-oauth-metadata-discovery">

646 Substituir descoberta de metadados OAuth

647</h3>

602 648 

603Aponte Claude Code para uma URL de metadados específica de servidor de autorização OAuth para contornar a cadeia de descoberta padrão. Defina `authServerMetadataUrl` quando os endpoints padrão do servidor MCP falharem, ou quando você deseja rotear a descoberta através de um proxy interno. Por padrão, Claude Code primeiro verifica os Metadados de Recurso Protegido RFC 9728 em `/.well-known/oauth-protected-resource`, depois volta para os metadados do servidor de autorização RFC 8414 em `/.well-known/oauth-authorization-server`.649Aponte Claude Code para uma URL de metadados específica de servidor de autorização OAuth para contornar a cadeia de descoberta padrão. Defina `authServerMetadataUrl` quando os endpoints padrão do servidor MCP falharem, ou quando você deseja rotear a descoberta através de um proxy interno. Por padrão, Claude Code primeiro verifica os Metadados de Recurso Protegido RFC 9728 em `/.well-known/oauth-protected-resource`, depois volta para os metadados do servidor de autorização RFC 8414 em `/.well-known/oauth-authorization-server`.

604 650 


620 666 

621A URL deve usar `https://`. `authServerMetadataUrl` requer Claude Code v2.1.64 ou posterior. Os `scopes_supported` da URL de metadados substituem os escopos que o servidor upstream anuncia.667A URL deve usar `https://`. `authServerMetadataUrl` requer Claude Code v2.1.64 ou posterior. Os `scopes_supported` da URL de metadados substituem os escopos que o servidor upstream anuncia.

622 668 

623### Restringir escopos OAuth669<h3 id="restrict-oauth-scopes">

670 Restringir escopos OAuth

671</h3>

624 672 

625Defina `oauth.scopes` para fixar os escopos que Claude Code solicita durante o fluxo de autorização. Esta é a forma suportada de restringir um servidor MCP a um subconjunto aprovado pela equipe de segurança quando o servidor de autorização upstream anuncia mais escopos do que você deseja conceder. O valor é uma única string separada por espaço, correspondendo ao formato do parâmetro `scope` em RFC 6749 §3.3.673Defina `oauth.scopes` para fixar os escopos que Claude Code solicita durante o fluxo de autorização. Esta é a forma suportada de restringir um servidor MCP a um subconjunto aprovado pela equipe de segurança quando o servidor de autorização upstream anuncia mais escopos do que você deseja conceder. O valor é uma única string separada por espaço, correspondendo ao formato do parâmetro `scope` em RFC 6749 §3.3.

626 674 


644 692 

645Se o servidor depois retorna um 403 `insufficient_scope` para uma chamada de ferramenta, Claude Code se autentica novamente com os mesmos escopos fixados. Amplie `oauth.scopes` quando uma ferramenta que você precisa requer um escopo fora do pino.693Se o servidor depois retorna um 403 `insufficient_scope` para uma chamada de ferramenta, Claude Code se autentica novamente com os mesmos escopos fixados. Amplie `oauth.scopes` quando uma ferramenta que você precisa requer um escopo fora do pino.

646 694 

647### Usar cabeçalhos dinâmicos para autenticação personalizada695<h3 id="use-dynamic-headers-for-custom-authentication">

696 Usar cabeçalhos dinâmicos para autenticação personalizada

697</h3>

648 698 

649Se seu servidor MCP usar um esquema de autenticação diferente de OAuth (como Kerberos, tokens de curta duração ou um SSO interno), use `headersHelper` para gerar cabeçalhos de solicitação no momento da conexão. Claude Code executa o comando e mescla sua saída nos cabeçalhos de conexão.699Se seu servidor MCP usar um esquema de autenticação diferente de OAuth (como Kerberos, tokens de curta duração ou um SSO interno), use `headersHelper` para gerar cabeçalhos de solicitação no momento da conexão. Claude Code executa o comando e mescla sua saída nos cabeçalhos de conexão.

650 700 


695 `headersHelper` executa comandos shell arbitrários. Quando definido no escopo de projeto ou local, ele só é executado após você aceitar o diálogo de confiança do espaço de trabalho.745 `headersHelper` executa comandos shell arbitrários. Quando definido no escopo de projeto ou local, ele só é executado após você aceitar o diálogo de confiança do espaço de trabalho.

696</Note>746</Note>

697 747 

698## Adicionar servidores MCP de configuração JSON748<h2 id="add-mcp-servers-from-json-configuration">

749 Adicionar servidores MCP de configuração JSON

750</h2>

699 751 

700Se você tiver uma configuração JSON para um servidor MCP, você pode adicioná-la diretamente:752Se você tiver uma configuração JSON para um servidor MCP, você pode adicioná-la diretamente:

701 753 


731 * Você pode usar `--scope user` para adicionar o servidor à sua configuração de usuário em vez da específica do projeto783 * Você pode usar `--scope user` para adicionar o servidor à sua configuração de usuário em vez da específica do projeto

732</Tip>784</Tip>

733 785 

734## Importar servidores MCP do Claude Desktop786<h2 id="import-mcp-servers-from-claude-desktop">

787 Importar servidores MCP do Claude Desktop

788</h2>

735 789 

736Se você já configurou servidores MCP no Claude Desktop, você pode importá-los:790Se você já configurou servidores MCP no Claude Desktop, você pode importá-los:

737 791 


764 * Se servidores com os mesmos nomes já existirem, eles receberão um sufixo numérico (por exemplo, `server_1`)818 * Se servidores com os mesmos nomes já existirem, eles receberão um sufixo numérico (por exemplo, `server_1`)

765</Tip>819</Tip>

766 820 

767## Usar servidores MCP do Claude.ai821<h2 id="use-mcp-servers-from-claude-ai">

822 Usar servidores MCP do Claude.ai

823</h2>

768 824 

769Se você fez login no Claude Code com uma conta [Claude.ai](https://claude.ai), os servidores MCP que você adicionou no Claude.ai estão automaticamente disponíveis no Claude Code:825Se você fez login no Claude Code com uma conta [Claude.ai](https://claude.ai), os servidores MCP que você adicionou no Claude.ai estão automaticamente disponíveis no Claude Code:

770 826 


794 850 

795Um servidor que você adicionou no Claude Code tem [precedência](#scope-hierarchy-and-precedence) sobre um conector do claude.ai que aponta para a mesma URL. Quando isso acontece, `/mcp` lista o conector como oculto e mostra como remover a duplicata se você preferir usar o conector.851Um servidor que você adicionou no Claude Code tem [precedência](#scope-hierarchy-and-precedence) sobre um conector do claude.ai que aponta para a mesma URL. Quando isso acontece, `/mcp` lista o conector como oculto e mostra como remover a duplicata se você preferir usar o conector.

796 852 

853Alguns conectores hospedados pela Anthropic, como Microsoft 365, Gmail e Google Calendar, não suportam OAuth local do Claude Code porque o provedor de identidade upstream aceita apenas a URL de redirecionamento que o claude.ai registrou. A partir da v2.1.162, autenticar um desses hosts em `/mcp` mostra uma mensagem direcionando você para conectá-lo em Configurações → Conectores no claude.ai. Uma vez conectado lá, o conector aparece no Claude Code automaticamente.

854 

797Para desabilitar servidores MCP do claude.ai no Claude Code, defina a variável de ambiente `ENABLE_CLAUDEAI_MCP_SERVERS` como `false`:855Para desabilitar servidores MCP do claude.ai no Claude Code, defina a variável de ambiente `ENABLE_CLAUDEAI_MCP_SERVERS` como `false`:

798 856 

799```bash theme={null}857```bash theme={null}

800ENABLE_CLAUDEAI_MCP_SERVERS=false claude858ENABLE_CLAUDEAI_MCP_SERVERS=false claude

801```859```

802 860 

803## Usar Claude Code como um servidor MCP861<h2 id="use-claude-code-as-an-mcp-server">

862 Usar Claude Code como um servidor MCP

863</h2>

804 864 

805Você pode usar Claude Code em si como um servidor MCP que outros aplicativos podem se conectar:865Você pode usar Claude Code em si como um servidor MCP que outros aplicativos podem se conectar:

806 866 


859 * Observe que este servidor MCP está apenas expondo as ferramentas do Claude Code ao seu cliente MCP, então seu próprio cliente é responsável por implementar confirmação do usuário para chamadas de ferramentas individuais.919 * Observe que este servidor MCP está apenas expondo as ferramentas do Claude Code ao seu cliente MCP, então seu próprio cliente é responsável por implementar confirmação do usuário para chamadas de ferramentas individuais.

860</Tip>920</Tip>

861 921 

862## Limites de saída MCP e avisos922<h2 id="mcp-output-limits-and-warnings">

923 Limites de saída MCP e avisos

924</h2>

863 925 

864Quando as ferramentas MCP produzem grandes saídas, Claude Code ajuda a gerenciar o uso de tokens para evitar sobrecarregar seu contexto de conversa:926Quando as ferramentas MCP produzem grandes saídas, Claude Code ajuda a gerenciar o uso de tokens para evitar sobrecarregar seu contexto de conversa:

865 927 


881* Geram relatórios ou documentação detalhados943* Geram relatórios ou documentação detalhados

882* Processam arquivos de log extensos ou informações de depuração944* Processam arquivos de log extensos ou informações de depuração

883 945 

884### Aumentar o limite para uma ferramenta específica946<h3 id="raise-the-limit-for-a-specific-tool">

947 Aumentar o limite para uma ferramenta específica

948</h3>

885 949 

886Se você está construindo um servidor MCP, você pode permitir que ferramentas individuais retornem resultados maiores do que o limite padrão de persistência em disco definindo `_meta["anthropic/maxResultSizeChars"]` na entrada da ferramenta em resposta `tools/list`. Claude Code aumenta o limite dessa ferramenta para o valor anotado, até um teto rígido de 500.000 caracteres.950Se você está construindo um servidor MCP, você pode permitir que ferramentas individuais retornem resultados maiores do que o limite padrão de persistência em disco definindo `_meta["anthropic/maxResultSizeChars"]` na entrada da ferramenta em resposta `tools/list`. Claude Code aumenta o limite dessa ferramenta para o valor anotado, até um teto rígido de 500.000 caracteres.

887 951 


903 Se você encontrar frequentemente avisos de saída com servidores MCP específicos que você não controla, considere aumentar o limite `MAX_MCP_OUTPUT_TOKENS`. Você também pode pedir ao autor do servidor para adicionar a anotação `anthropic/maxResultSizeChars` ou para paginar suas respostas. A anotação não tem efeito em ferramentas que retornam conteúdo de imagem; para essas, aumentar `MAX_MCP_OUTPUT_TOKENS` é a única opção.967 Se você encontrar frequentemente avisos de saída com servidores MCP específicos que você não controla, considere aumentar o limite `MAX_MCP_OUTPUT_TOKENS`. Você também pode pedir ao autor do servidor para adicionar a anotação `anthropic/maxResultSizeChars` ou para paginar suas respostas. A anotação não tem efeito em ferramentas que retornam conteúdo de imagem; para essas, aumentar `MAX_MCP_OUTPUT_TOKENS` é a única opção.

904</Warning>968</Warning>

905 969 

906## Responder a solicitações de elicitação MCP970<h2 id="respond-to-mcp-elicitation-requests">

971 Responder a solicitações de elicitação MCP

972</h2>

907 973 

908Os servidores MCP podem solicitar entrada estruturada de você durante uma tarefa usando elicitação. Quando um servidor precisa de informações que não consegue obter por conta própria, Claude Code exibe um diálogo interativo e passa sua resposta de volta para o servidor. Nenhuma configuração é necessária do seu lado: diálogos de elicitação aparecem automaticamente quando um servidor os solicita.974Os servidores MCP podem solicitar entrada estruturada de você durante uma tarefa usando elicitação. Quando um servidor precisa de informações que não consegue obter por conta própria, Claude Code exibe um diálogo interativo e passa sua resposta de volta para o servidor. Nenhuma configuração é necessária do seu lado: diálogos de elicitação aparecem automaticamente quando um servidor os solicita.

909 975 


912* **Modo de formulário**: Claude Code mostra um diálogo com campos de formulário definidos pelo servidor (por exemplo, um prompt de nome de usuário e senha). Preencha os campos e envie.978* **Modo de formulário**: Claude Code mostra um diálogo com campos de formulário definidos pelo servidor (por exemplo, um prompt de nome de usuário e senha). Preencha os campos e envie.

913* **Modo de URL**: Claude Code abre uma URL do navegador para autenticação ou aprovação. Complete o fluxo no navegador, depois confirme no CLI.979* **Modo de URL**: Claude Code abre uma URL do navegador para autenticação ou aprovação. Complete o fluxo no navegador, depois confirme no CLI.

914 980 

915Para responder automaticamente a solicitações de elicitação sem mostrar um diálogo, use o [hook `Elicitation`](/pt/hooks#Elicitation).981Para responder automaticamente a solicitações de elicitação sem mostrar um diálogo, use o [hook `Elicitation`](/pt/hooks#elicitation).

916 982 

917Se você está construindo um servidor MCP que usa elicitação, veja a [especificação de elicitação MCP](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation) para detalhes de protocolo e exemplos de esquema.983Se você está construindo um servidor MCP que usa elicitação, veja a [especificação de elicitação MCP](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation) para detalhes de protocolo e exemplos de esquema.

918 984 

919## Usar recursos MCP985<h2 id="use-mcp-resources">

986 Usar recursos MCP

987</h2>

920 988 

921Os servidores MCP podem expor recursos que você pode referenciar usando menções @, semelhante a como você referencia arquivos.989Os servidores MCP podem expor recursos que você pode referenciar usando menções @, semelhante a como você referencia arquivos.

922 990 

923### Referenciar recursos MCP991<h3 id="reference-mcp-resources">

992 Referenciar recursos MCP

993</h3>

924 994 

925<Steps>995<Steps>

926 <Step title="Liste recursos disponíveis">996 <Step title="Liste recursos disponíveis">


957 * Os recursos podem conter qualquer tipo de conteúdo que o servidor MCP fornece (texto, JSON, dados estruturados, etc.)1027 * Os recursos podem conter qualquer tipo de conteúdo que o servidor MCP fornece (texto, JSON, dados estruturados, etc.)

958</Tip>1028</Tip>

959 1029 

960## Escalar com MCP Tool Search1030<h2 id="scale-with-mcp-tool-search">

1031 Escalar com MCP Tool Search

1032</h2>

961 1033 

962Tool Search mantém o uso de contexto MCP baixo adiando definições de ferramentas até que Claude precise delas. Apenas nomes de ferramentas e instruções do servidor são carregados no início da sessão, então adicionar mais servidores MCP tem impacto mínimo na sua janela de contexto.1034Tool Search mantém o uso de contexto MCP baixo adiando definições de ferramentas até que Claude precise delas. Apenas nomes de ferramentas e instruções do servidor são carregados no início da sessão, então adicionar mais servidores MCP tem impacto mínimo na sua janela de contexto. Claude Code não impõe um limite fixo de ferramentas por servidor; o limite prático é o seu orçamento de janela de contexto.

963 1035 

964### Como funciona1036<h3 id="how-it-works">

1037 Como funciona

1038</h3>

965 1039 

966Tool Search é ativado por padrão. As ferramentas MCP são adiadas em vez de carregadas no contexto antecipadamente, e Claude usa uma ferramenta de pesquisa para descobrir as relevantes quando uma tarefa precisa delas. Apenas as ferramentas que Claude realmente usa entram no contexto. Da sua perspectiva, as ferramentas MCP funcionam exatamente como antes.1040Tool Search é ativado por padrão. As ferramentas MCP são adiadas em vez de carregadas no contexto antecipadamente, e Claude usa uma ferramenta de pesquisa para descobrir as relevantes quando uma tarefa precisa delas. Apenas as ferramentas que Claude realmente usa entram no contexto. Da sua perspectiva, as ferramentas MCP funcionam exatamente como antes.

967 1041 

968Se você preferir carregamento baseado em limite, defina `ENABLE_TOOL_SEARCH=auto` para carregar esquemas antecipadamente quando se encaixarem em 10% da janela de contexto e adiar apenas o excesso. Veja [Configurar pesquisa de ferramentas](#configure-tool-search) para todas as opções.1042Se você preferir carregamento baseado em limite, defina `ENABLE_TOOL_SEARCH=auto` para carregar esquemas antecipadamente quando se encaixarem em 10% da janela de contexto e adiar apenas o excesso. Veja [Configurar pesquisa de ferramentas](#configure-tool-search) para todas as opções.

969 1043 

970### Para autores de servidores MCP1044<h3 id="for-mcp-server-authors">

1045 Para autores de servidores MCP

1046</h3>

971 1047 

972Se você está construindo um servidor MCP, o campo de instruções do servidor se torna mais útil com Tool Search habilitado. As instruções do servidor ajudam Claude a entender quando pesquisar suas ferramentas, semelhante a como [skills](/pt/skills) funcionam.1048Se você está construindo um servidor MCP, o campo de instruções do servidor se torna mais útil com Tool Search habilitado. As instruções do servidor ajudam Claude a entender quando pesquisar suas ferramentas, semelhante a como [skills](/pt/skills) funcionam.

973 1049 


979 1055 

980Claude Code trunca descrições de ferramentas e instruções de servidor em 2KB cada. Mantenha-as concisas para evitar truncamento, e coloque detalhes críticos perto do início.1056Claude Code trunca descrições de ferramentas e instruções de servidor em 2KB cada. Mantenha-as concisas para evitar truncamento, e coloque detalhes críticos perto do início.

981 1057 

982### Configurar pesquisa de ferramentas1058<h3 id="configure-tool-search">

1059 Configurar pesquisa de ferramentas

1060</h3>

983 1061 

984Tool Search é ativado por padrão: as ferramentas MCP são adiadas e descobertas sob demanda. Claude Code desabilita-o por padrão no Vertex AI. Também é desabilitado quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte, já que a maioria dos proxies não encaminha blocos `tool_reference`. Defina `ENABLE_TOOL_SEARCH` explicitamente para substituir qualquer fallback.1062Tool Search é ativado por padrão: as ferramentas MCP são adiadas e descobertas sob demanda. Claude Code desabilita-o por padrão no Vertex AI. Também é desabilitado quando `ANTHROPIC_BASE_URL` aponta para um host que não é de primeira parte, já que a maioria dos proxies não encaminha blocos `tool_reference`. Defina `ENABLE_TOOL_SEARCH` explicitamente para substituir qualquer fallback.

985 1063 

986Tool Search requer um modelo que suporte blocos `tool_reference`: Sonnet 4 e posterior, ou Opus 4 e posterior. Os modelos Haiku não suportam. No Vertex AI, tool search é suportado para Claude Sonnet 4.5 e posterior e Claude Opus 4.5 e posterior.1064Tool Search requer um modelo que suporte blocos `tool_reference`. Os modelos Haiku não suportam. No Vertex AI, tool search é suportado para Claude Sonnet 4.5 e posterior e Claude Opus 4.5 e posterior.

987 1065 

988Controle o comportamento da pesquisa de ferramentas com a variável de ambiente `ENABLE_TOOL_SEARCH`:1066Controle o comportamento da pesquisa de ferramentas com a variável de ambiente `ENABLE_TOOL_SEARCH`:

989 1067 


1015}1093}

1016```1094```

1017 1095 

1018### Isentar um servidor de adiamento1096<h3 id="exempt-a-server-from-deferral">

1097 Isentar um servidor de adiamento

1098</h3>

1019 1099 

1020Se as ferramentas de um servidor devem estar sempre visíveis para Claude sem uma etapa de pesquisa, defina `alwaysLoad` como `true` na configuração desse servidor. Cada ferramenta desse servidor então carrega no contexto no início da sessão independentemente da configuração `ENABLE_TOOL_SEARCH`. Use isso para um pequeno número de ferramentas que Claude precisa a cada turno, já que cada ferramenta antecipada consome contexto que estaria disponível para sua conversa.1100Se as ferramentas de um servidor devem estar sempre visíveis para Claude sem uma etapa de pesquisa, defina `alwaysLoad` como `true` na configuração desse servidor. Cada ferramenta desse servidor então carrega no contexto no início da sessão independentemente da configuração `ENABLE_TOOL_SEARCH`. Use isso para um pequeno número de ferramentas que Claude precisa a cada turno, já que cada ferramenta antecipada consome contexto que estaria disponível para sua conversa.

1021 1101 


1037 1117 

1038Definir `alwaysLoad: true` também bloqueia a inicialização até que o servidor se conecte, limitado ao tempo limite de conexão padrão de 5 segundos. Isso se aplica mesmo que a inicialização MCP seja [não bloqueante por padrão](/pt/env-vars), já que as ferramentas devem estar presentes quando o primeiro prompt é construído. Outros servidores continuam a se conectar em segundo plano.1118Definir `alwaysLoad: true` também bloqueia a inicialização até que o servidor se conecte, limitado ao tempo limite de conexão padrão de 5 segundos. Isso se aplica mesmo que a inicialização MCP seja [não bloqueante por padrão](/pt/env-vars), já que as ferramentas devem estar presentes quando o primeiro prompt é construído. Outros servidores continuam a se conectar em segundo plano.

1039 1119 

1040## Usar prompts MCP como comandos1120<h2 id="use-mcp-prompts-as-commands">

1121 Usar prompts MCP como comandos

1122</h2>

1041 1123 

1042Os servidores MCP podem expor prompts que se tornam disponíveis como comandos no Claude Code.1124Os servidores MCP podem expor prompts que se tornam disponíveis como comandos no Claude Code.

1043 1125 

1044### Executar prompts MCP1126<h3 id="execute-mcp-prompts">

1127 Executar prompts MCP

1128</h3>

1045 1129 

1046<Steps>1130<Steps>

1047 <Step title="Descubra prompts disponíveis">1131 <Step title="Descubra prompts disponíveis">


1076 * Os nomes do servidor e do prompt são normalizados (espaços se tornam sublinhados)1160 * Os nomes do servidor e do prompt são normalizados (espaços se tornam sublinhados)

1077</Tip>1161</Tip>

1078 1162 

1079## Configuração MCP gerenciada1163<h2 id="managed-mcp-configuration">

1164 Configuração MCP gerenciada

1165</h2>

1080 1166 

1081Para organizações que precisam de controle centralizado sobre quais servidores MCP os usuários podem se conectar, consulte [Configuração MCP gerenciada](/pt/managed-mcp). Ela aborda a implantação de um conjunto fixo de servidores com `managed-mcp.json`, restrição de servidores com `allowedMcpServers` e `deniedMcpServers`, e o que os usuários veem quando um servidor é bloqueado.1167Para organizações que precisam de controle centralizado sobre quais servidores MCP os usuários podem se conectar, consulte [Configuração MCP gerenciada](/pt/managed-mcp). Ela aborda a implantação de um conjunto fixo de servidores com `managed-mcp.json`, restrição de servidores com `allowedMcpServers` e `deniedMcpServers`, e o que os usuários veem quando um servidor é bloqueado.

memory.md +92 −32

Details

18* [Configurar memória automática](#auto-memory) para que Claude tome notas automaticamente18* [Configurar memória automática](#auto-memory) para que Claude tome notas automaticamente

19* [Solucionar problemas](#troubleshoot-memory-issues) quando as instruções não estão sendo seguidas19* [Solucionar problemas](#troubleshoot-memory-issues) quando as instruções não estão sendo seguidas

20 20 

21## CLAUDE.md vs memória automática21<h2 id="claude-md-vs-auto-memory">

22 CLAUDE.md vs memória automática

23</h2>

22 24 

23Claude Code tem dois sistemas de memória complementares. Ambos são carregados no início de cada conversa. Claude os trata como contexto, não como configuração imposta. Para bloquear uma ação independentemente do que Claude decidir, use um [hook PreToolUse](/pt/hooks-guide) em vez disso. Quanto mais específicas e concisas forem suas instruções, mais consistentemente Claude as seguirá.25Claude Code tem dois sistemas de memória complementares. Ambos são carregados no início de cada conversa. Claude os trata como contexto, não como configuração imposta. Para bloquear uma ação independentemente do que Claude decidir, use um [hook PreToolUse](/pt/hooks-guide) em vez disso. Quanto mais específicas e concisas forem suas instruções, mais consistentemente Claude as seguirá.

24 26 


34 36 

35Subagents também podem manter sua própria memória automática. Veja [configuração de subagent](/pt/sub-agents#enable-persistent-memory) para detalhes.37Subagents também podem manter sua própria memória automática. Veja [configuração de subagent](/pt/sub-agents#enable-persistent-memory) para detalhes.

36 38 

37## Arquivos CLAUDE.md39<h2 id="claude-md-files">

40 Arquivos CLAUDE.md

41</h2>

38 42 

39Arquivos CLAUDE.md são arquivos markdown que dão a Claude instruções persistentes para um projeto, seu fluxo de trabalho pessoal ou toda a sua organização. Você escreve esses arquivos em texto simples; Claude os lê no início de cada sessão.43Arquivos CLAUDE.md são arquivos markdown que dão a Claude instruções persistentes para um projeto, seu fluxo de trabalho pessoal ou toda a sua organização. Você escreve esses arquivos em texto simples; Claude os lê no início de cada sessão.

40 44 

41### Quando adicionar a CLAUDE.md45<h3 id="when-to-add-to-claude-md">

46 Quando adicionar a CLAUDE.md

47</h3>

42 48 

43Trate CLAUDE.md como o lugar onde você escreve o que teria que re-explicar. Adicione a ele quando:49Trate CLAUDE.md como o lugar onde você escreve o que teria que re-explicar. Adicione a ele quando:

44 50 


49 55 

50Mantenha-o com fatos que Claude deve manter em cada sessão: comandos de compilação, convenções, layout do projeto, regras "sempre faça X". Se uma entrada é um procedimento de múltiplas etapas ou só importa para uma parte da base de código, mova-a para uma [skill](/pt/skills) ou uma [regra com escopo de caminho](#organize-rules-with-claude/rules/) em vez disso. A [visão geral da extensão](/pt/features-overview#build-your-setup-over-time) cobre quando usar cada mecanismo.56Mantenha-o com fatos que Claude deve manter em cada sessão: comandos de compilação, convenções, layout do projeto, regras "sempre faça X". Se uma entrada é um procedimento de múltiplas etapas ou só importa para uma parte da base de código, mova-a para uma [skill](/pt/skills) ou uma [regra com escopo de caminho](#organize-rules-with-claude/rules/) em vez disso. A [visão geral da extensão](/pt/features-overview#build-your-setup-over-time) cobre quando usar cada mecanismo.

51 57 

52### Escolha onde colocar arquivos CLAUDE.md58<h3 id="choose-where-to-put-claude-md-files">

59 Escolha onde colocar arquivos CLAUDE.md

60</h3>

53 61 

54Arquivos CLAUDE.md podem estar em vários locais, cada um com um escopo diferente. A tabela abaixo lista-os em ordem de carregamento, do escopo mais amplo para o mais específico, então uma instrução de projeto aparece em contexto após uma instrução de usuário.62Arquivos CLAUDE.md podem estar em vários locais, cada um com um escopo diferente. A tabela abaixo lista-os em ordem de carregamento, do escopo mais amplo para o mais específico, então uma instrução de projeto aparece em contexto após uma instrução de usuário.

55 63 


64 72 

65Para projetos grandes, você pode dividir instruções em arquivos específicos de tópicos usando [regras de projeto](#organize-rules-with-claude/rules/). As regras permitem que você escope instruções para tipos de arquivo específicos ou subdiretórios.73Para projetos grandes, você pode dividir instruções em arquivos específicos de tópicos usando [regras de projeto](#organize-rules-with-claude/rules/). As regras permitem que você escope instruções para tipos de arquivo específicos ou subdiretórios.

66 74 

67### Configure um CLAUDE.md de projeto75<h3 id="set-up-a-project-claude-md">

76 Configure um CLAUDE.md de projeto

77</h3>

68 78 

69Um CLAUDE.md de projeto pode ser armazenado em `./CLAUDE.md` ou `./.claude/CLAUDE.md`. Crie este arquivo e adicione instruções que se apliquem a qualquer pessoa trabalhando no projeto: comandos de compilação e teste, padrões de codificação, decisões arquitetônicas, convenções de nomenclatura e fluxos de trabalho comuns. Essas instruções são compartilhadas com sua equipe através do controle de versão, então foque em padrões de nível de projeto em vez de preferências pessoais.79Um CLAUDE.md de projeto pode ser armazenado em `./CLAUDE.md` ou `./.claude/CLAUDE.md`. Crie este arquivo e adicione instruções que se apliquem a qualquer pessoa trabalhando no projeto: comandos de compilação e teste, padrões de codificação, decisões arquitetônicas, convenções de nomenclatura e fluxos de trabalho comuns. Essas instruções são compartilhadas com sua equipe através do controle de versão, então foque em padrões de nível de projeto em vez de preferências pessoais.

70 80 


74 Defina `CLAUDE_CODE_NEW_INIT=1` para ativar um fluxo interativo de múltiplas fases. `/init` pergunta quais artefatos configurar: arquivos CLAUDE.md, skills e hooks. Em seguida, explora sua base de código com um subagent, preenche lacunas por meio de perguntas de acompanhamento e apresenta uma proposta revisável antes de escrever qualquer arquivo.84 Defina `CLAUDE_CODE_NEW_INIT=1` para ativar um fluxo interativo de múltiplas fases. `/init` pergunta quais artefatos configurar: arquivos CLAUDE.md, skills e hooks. Em seguida, explora sua base de código com um subagent, preenche lacunas por meio de perguntas de acompanhamento e apresenta uma proposta revisável antes de escrever qualquer arquivo.

75</Tip>85</Tip>

76 86 

77### Escreva instruções eficazes87<h3 id="write-effective-instructions">

88 Escreva instruções eficazes

89</h3>

78 90 

79Arquivos CLAUDE.md são carregados na janela de contexto no início de cada sessão, consumindo tokens junto com sua conversa. A [visualização da janela de contexto](/pt/context-window) mostra onde CLAUDE.md é carregado em relação ao resto do contexto de inicialização. Como são contexto em vez de configuração imposta, como você escreve as instruções afeta o quão confiável Claude as segue. Instruções específicas, concisas e bem estruturadas funcionam melhor.91Arquivos CLAUDE.md são carregados na janela de contexto no início de cada sessão, consumindo tokens junto com sua conversa. A [visualização da janela de contexto](/pt/context-window) mostra onde CLAUDE.md é carregado em relação ao resto do contexto de inicialização. Como são contexto em vez de configuração imposta, como você escreve as instruções afeta o quão confiável Claude as segue. Instruções específicas, concisas e bem estruturadas funcionam melhor.

80 92 


90 102 

91**Consistência**: se duas regras se contradizem, Claude pode escolher uma arbitrariamente. Revise seus arquivos CLAUDE.md, arquivos CLAUDE.md aninhados em subdiretórios e [`.claude/rules/`](#organize-rules-with-claude/rules/) periodicamente para remover instruções desatualizadas ou conflitantes. Em monorepos, use [`claudeMdExcludes`](#exclude-specific-claude-md-files) para pular arquivos CLAUDE.md de outras equipes que não são relevantes para seu trabalho.103**Consistência**: se duas regras se contradizem, Claude pode escolher uma arbitrariamente. Revise seus arquivos CLAUDE.md, arquivos CLAUDE.md aninhados em subdiretórios e [`.claude/rules/`](#organize-rules-with-claude/rules/) periodicamente para remover instruções desatualizadas ou conflitantes. Em monorepos, use [`claudeMdExcludes`](#exclude-specific-claude-md-files) para pular arquivos CLAUDE.md de outras equipes que não são relevantes para seu trabalho.

92 104 

93### Importe arquivos adicionais105<h3 id="import-additional-files">

106 Importe arquivos adicionais

107</h3>

94 108 

95Arquivos CLAUDE.md podem importar arquivos adicionais usando a sintaxe `@path/to/import`. Arquivos importados são expandidos e carregados em contexto no lançamento junto com o CLAUDE.md que os referencia.109Arquivos CLAUDE.md podem importar arquivos adicionais usando a sintaxe `@path/to/import`. Arquivos importados são expandidos e carregados em contexto no lançamento junto com o CLAUDE.md que os referencia.

96 110 


120 134 

121Para uma abordagem mais estruturada para organizar instruções, veja [`.claude/rules/`](#organize-rules-with-claude/rules/).135Para uma abordagem mais estruturada para organizar instruções, veja [`.claude/rules/`](#organize-rules-with-claude/rules/).

122 136 

123### AGENTS.md137<h3 id="agents-md">

138 AGENTS.md

139</h3>

124 140 

125Claude Code lê `CLAUDE.md`, não `AGENTS.md`. Se seu repositório já usa `AGENTS.md` para outros agentes de codificação, crie um `CLAUDE.md` que o importe para que ambas as ferramentas leiam as mesmas instruções sem duplicá-las. Você também pode adicionar instruções específicas do Claude Code abaixo da importação. Claude carrega o arquivo importado no início da sessão, depois anexa o resto:141Claude Code lê `CLAUDE.md`, não `AGENTS.md`. Se seu repositório já usa `AGENTS.md` para outros agentes de codificação, crie um `CLAUDE.md` que o importe para que ambas as ferramentas leiam as mesmas instruções sem duplicá-las. Você também pode adicionar instruções específicas do Claude Code abaixo da importação. Claude carrega o arquivo importado no início da sessão, depois anexa o resto:

126 142 


140 156 

141No Windows, criar um symlink requer privilégios de Administrador ou Modo de Desenvolvedor, então use a importação `@AGENTS.md` em vez disso.157No Windows, criar um symlink requer privilégios de Administrador ou Modo de Desenvolvedor, então use a importação `@AGENTS.md` em vez disso.

142 158 

143Executar [`/init`](/pt/commands) em um repositório que já tem um `AGENTS.md` o lê e incorpora as partes relevantes no `CLAUDE.md` gerado. Ele também lê outras configurações de ferramentas como `.cursorrules` e `.windsurfrules`.159Executar [`/init`](/pt/commands) em um repositório que já tem um `AGENTS.md` o lê e incorpora as partes relevantes no `CLAUDE.md` gerado. Ele também lê outras configurações de ferramentas como `.cursorrules`, `.devin/rules/` e `.windsurfrules`.

144 160 

145### Como arquivos CLAUDE.md são carregados161<h3 id="how-claude-md-files-load">

162 Como arquivos CLAUDE.md são carregados

163</h3>

146 164 

147Claude Code lê arquivos CLAUDE.md caminhando para cima na árvore de diretórios a partir do seu diretório de trabalho atual, verificando cada diretório ao longo do caminho para arquivos `CLAUDE.md` e `CLAUDE.local.md`. Isso significa que se você executar Claude Code em `foo/bar/`, ele carrega instruções de `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` e qualquer arquivo `CLAUDE.local.md` ao lado deles.165Claude Code lê arquivos CLAUDE.md caminhando para cima na árvore de diretórios a partir do seu diretório de trabalho atual, verificando cada diretório ao longo do caminho para arquivos `CLAUDE.md` e `CLAUDE.local.md`. Isso significa que se você executar Claude Code em `foo/bar/`, ele carrega instruções de `foo/bar/CLAUDE.md`, `foo/CLAUDE.md` e qualquer arquivo `CLAUDE.local.md` ao lado deles.

148 166 


154 172 

155Comentários HTML em nível de bloco (`<!-- notas do mantenedor -->`) em arquivos CLAUDE.md são removidos antes do conteúdo ser injetado no contexto de Claude. Use-os para deixar notas para mantenedores humanos sem gastar tokens de contexto neles. Comentários dentro de blocos de código são preservados. Quando você abre um arquivo CLAUDE.md diretamente com a ferramenta Read, os comentários permanecem visíveis.173Comentários HTML em nível de bloco (`<!-- notas do mantenedor -->`) em arquivos CLAUDE.md são removidos antes do conteúdo ser injetado no contexto de Claude. Use-os para deixar notas para mantenedores humanos sem gastar tokens de contexto neles. Comentários dentro de blocos de código são preservados. Quando você abre um arquivo CLAUDE.md diretamente com a ferramenta Read, os comentários permanecem visíveis.

156 174 

157#### Carregue de diretórios adicionais175<h4 id="load-from-additional-directories">

176 Carregue de diretórios adicionais

177</h4>

158 178 

159A flag `--add-dir` dá a Claude acesso a diretórios adicionais fora do seu diretório de trabalho principal. Por padrão, arquivos CLAUDE.md desses diretórios não são carregados.179A flag `--add-dir` dá a Claude acesso a diretórios adicionais fora do seu diretório de trabalho principal. Por padrão, arquivos CLAUDE.md desses diretórios não são carregados.

160 180 


166 186 

167Isso carrega `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` e `CLAUDE.local.md` do diretório adicional. `CLAUDE.local.md` é ignorado se você excluir `local` de [`--setting-sources`](/pt/cli-reference).187Isso carrega `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` e `CLAUDE.local.md` do diretório adicional. `CLAUDE.local.md` é ignorado se você excluir `local` de [`--setting-sources`](/pt/cli-reference).

168 188 

169### Organize regras com `.claude/rules/`189<h3 id="organize-rules-with-claude/rules/">

190 Organize regras com `.claude/rules/`

191</h3>

170 192 

171Para projetos maiores, você pode organizar instruções em múltiplos arquivos usando o diretório `.claude/rules/`. Isso mantém as instruções modulares e mais fáceis para as equipes manterem. As regras também podem ser [escopadas para caminhos de arquivo específicos](#path-specific-rules), então elas só são carregadas em contexto quando Claude trabalha com arquivos correspondentes, reduzindo ruído e economizando espaço de contexto.193Para projetos maiores, você pode organizar instruções em múltiplos arquivos usando o diretório `.claude/rules/`. Isso mantém as instruções modulares e mais fáceis para as equipes manterem. As regras também podem ser [escopadas para caminhos de arquivo específicos](#path-specific-rules), então elas só são carregadas em contexto quando Claude trabalha com arquivos correspondentes, reduzindo ruído e economizando espaço de contexto.

172 194 


174 As regras são carregadas em contexto a cada sessão ou quando arquivos correspondentes são abertos. Para instruções específicas de tarefa que não precisam estar em contexto o tempo todo, use [skills](/pt/skills) em vez disso, que só são carregadas quando você as invoca ou quando Claude determina que são relevantes para seu prompt.196 As regras são carregadas em contexto a cada sessão ou quando arquivos correspondentes são abertos. Para instruções específicas de tarefa que não precisam estar em contexto o tempo todo, use [skills](/pt/skills) em vez disso, que só são carregadas quando você as invoca ou quando Claude determina que são relevantes para seu prompt.

175</Note>197</Note>

176 198 

177#### Configure regras199<h4 id="set-up-rules">

200 Configure regras

201</h4>

178 202 

179Coloque arquivos markdown no diretório `.claude/rules/` do seu projeto. Cada arquivo deve cobrir um tópico, com um nome de arquivo descritivo como `testing.md` ou `api-design.md`. Todos os arquivos `.md` são descobertos recursivamente, então você pode organizar regras em subdiretórios como `frontend/` ou `backend/`:203Coloque arquivos markdown no diretório `.claude/rules/` do seu projeto. Cada arquivo deve cobrir um tópico, com um nome de arquivo descritivo como `testing.md` ou `api-design.md`. Todos os arquivos `.md` são descobertos recursivamente, então você pode organizar regras em subdiretórios como `frontend/` ou `backend/`:

180 204 


190 214 

191Regras sem [frontmatter `paths`](#path-specific-rules) são carregadas no lançamento com a mesma prioridade que `.claude/CLAUDE.md`.215Regras sem [frontmatter `paths`](#path-specific-rules) são carregadas no lançamento com a mesma prioridade que `.claude/CLAUDE.md`.

192 216 

193#### Regras específicas de caminho217<h4 id="path-specific-rules">

218 Regras específicas de caminho

219</h4>

194 220 

195As regras podem ser escopadas para arquivos específicos usando frontmatter YAML com o campo `paths`. Essas regras condicionais só se aplicam quando Claude está trabalhando com arquivos correspondentes aos padrões especificados.221As regras podem ser escopadas para arquivos específicos usando frontmatter YAML com o campo `paths`. Essas regras condicionais só se aplicam quando Claude está trabalhando com arquivos correspondentes aos padrões especificados.

196 222 


229---255---

230```256```

231 257 

232#### Compartilhe regras entre projetos com symlinks258<h4 id="share-rules-across-projects-with-symlinks">

259 Compartilhe regras entre projetos com symlinks

260</h4>

233 261 

234O diretório `.claude/rules/` suporta symlinks, então você pode manter um conjunto compartilhado de regras e vinculá-las em múltiplos projetos. Symlinks são resolvidos e carregados normalmente, e symlinks circulares são detectados e tratados graciosamente.262O diretório `.claude/rules/` suporta symlinks, então você pode manter um conjunto compartilhado de regras e vinculá-las em múltiplos projetos. Symlinks são resolvidos e carregados normalmente, e symlinks circulares são detectados e tratados graciosamente.

235 263 


240ln -s ~/company-standards/security.md .claude/rules/security.md268ln -s ~/company-standards/security.md .claude/rules/security.md

241```269```

242 270 

243#### Regras de nível de usuário271<h4 id="user-level-rules">

272 Regras de nível de usuário

273</h4>

244 274 

245Regras pessoais em `~/.claude/rules/` se aplicam a cada projeto na sua máquina. Use-as para preferências que não são específicas do projeto:275Regras pessoais em `~/.claude/rules/` se aplicam a cada projeto na sua máquina. Use-as para preferências que não são específicas do projeto:

246 276 


252 282 

253Regras de nível de usuário são carregadas antes das regras de projeto, dando às regras de projeto prioridade mais alta.283Regras de nível de usuário são carregadas antes das regras de projeto, dando às regras de projeto prioridade mais alta.

254 284 

255### Gerencie CLAUDE.md para grandes equipes285<h3 id="manage-claude-md-for-large-teams">

286 Gerencie CLAUDE.md para grandes equipes

287</h3>

256 288 

257Para organizações implantando Claude Code em equipes, você pode centralizar instruções e controlar quais arquivos CLAUDE.md são carregados.289Para organizações implantando Claude Code em equipes, você pode centralizar instruções e controlar quais arquivos CLAUDE.md são carregados.

258 290 

259#### Implante CLAUDE.md em toda a organização291<h4 id="deploy-organization-wide-claude-md">

292 Implante CLAUDE.md em toda a organização

293</h4>

260 294 

261As organizações podem implantar um CLAUDE.md gerenciado centralmente que se aplica a todos os usuários em uma máquina. Este arquivo não pode ser excluído por configurações individuais.295As organizações podem implantar um CLAUDE.md gerenciado centralmente que se aplica a todos os usuários em uma máquina. Este arquivo não pode ser excluído por configurações individuais.

262 296 


302 336 

303Regras de configurações são impostas pelo cliente independentemente do que Claude decide fazer. Instruções de CLAUDE.md moldam o comportamento de Claude, mas não são uma camada de imposição rígida.337Regras de configurações são impostas pelo cliente independentemente do que Claude decide fazer. Instruções de CLAUDE.md moldam o comportamento de Claude, mas não são uma camada de imposição rígida.

304 338 

305#### Exclua arquivos CLAUDE.md específicos339<h4 id="exclude-specific-claude-md-files">

340 Exclua arquivos CLAUDE.md específicos

341</h4>

306 342 

307Em grandes monorepos, arquivos CLAUDE.md ancestrais podem conter instruções que não são relevantes para seu trabalho. A configuração `claudeMdExcludes` permite que você pule arquivos específicos por caminho ou padrão glob.343Em grandes monorepos, arquivos CLAUDE.md ancestrais podem conter instruções que não são relevantes para seu trabalho. A configuração `claudeMdExcludes` permite que você pule arquivos específicos por caminho ou padrão glob.

308 344 


321 357 

322Arquivos CLAUDE.md de política gerenciada não podem ser excluídos. Isso garante que as instruções em toda a organização sempre se apliquem independentemente das configurações individuais.358Arquivos CLAUDE.md de política gerenciada não podem ser excluídos. Isso garante que as instruções em toda a organização sempre se apliquem independentemente das configurações individuais.

323 359 

324## Memória automática360<h2 id="auto-memory">

361 Memória automática

362</h2>

325 363 

326A memória automática permite que Claude acumule conhecimento entre sessões sem você escrever nada. Claude salva notas para si mesma enquanto trabalha: comandos de compilação, insights de depuração, notas de arquitetura, preferências de estilo de código e hábitos de fluxo de trabalho. Claude não salva algo a cada sessão. Ela decide o que vale a pena lembrar com base em se a informação seria útil em uma conversa futura.364A memória automática permite que Claude acumule conhecimento entre sessões sem você escrever nada. Claude salva notas para si mesma enquanto trabalha: comandos de compilação, insights de depuração, notas de arquitetura, preferências de estilo de código e hábitos de fluxo de trabalho. Claude não salva algo a cada sessão. Ela decide o que vale a pena lembrar com base em se a informação seria útil em uma conversa futura.

327 365 


329 A memória automática requer Claude Code v2.1.59 ou posterior. Verifique sua versão com `claude --version`.367 A memória automática requer Claude Code v2.1.59 ou posterior. Verifique sua versão com `claude --version`.

330</Note>368</Note>

331 369 

332### Ative ou desative a memória automática370<h3 id="enable-or-disable-auto-memory">

371 Ative ou desative a memória automática

372</h3>

333 373 

334A memória automática está ativada por padrão. Para alterná-la, abra `/memory` em uma sessão e use o toggle de memória automática, ou defina `autoMemoryEnabled` nas configurações do seu projeto:374A memória automática está ativada por padrão. Para alterná-la, abra `/memory` em uma sessão e use o toggle de memória automática, ou defina `autoMemoryEnabled` nas configurações do seu projeto:

335 375 


341 381 

342Para desabilitar a memória automática via variável de ambiente, defina `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`.382Para desabilitar a memória automática via variável de ambiente, defina `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`.

343 383 

344### Local de armazenamento384<h3 id="storage-location">

385 Local de armazenamento

386</h3>

345 387 

346Cada projeto obtém seu próprio diretório de memória em `~/.claude/projects/<project>/memory/`. O caminho `<project>` é derivado do repositório git, então todos os worktrees e subdiretórios dentro do mesmo repositório compartilham um diretório de memória automática. Fora de um repositório git, a raiz do projeto é usada em vez disso.388Cada projeto obtém seu próprio diretório de memória em `~/.claude/projects/<project>/memory/`. O caminho `<project>` é derivado do repositório git, então todos os worktrees e subdiretórios dentro do mesmo repositório compartilham um diretório de memória automática. Fora de um repositório git, a raiz do projeto é usada em vez disso.

347 389 


369 411 

370A memória automática é local da máquina. Todos os worktrees e subdiretórios dentro do mesmo repositório git compartilham um diretório de memória automática. Os arquivos não são compartilhados entre máquinas ou ambientes em nuvem.412A memória automática é local da máquina. Todos os worktrees e subdiretórios dentro do mesmo repositório git compartilham um diretório de memória automática. Os arquivos não são compartilhados entre máquinas ou ambientes em nuvem.

371 413 

372### Como funciona414<h3 id="how-it-works">

415 Como funciona

416</h3>

373 417 

374As primeiras 200 linhas de `MEMORY.md`, ou os primeiros 25KB, o que vier primeiro, são carregados no início de cada conversa. Conteúdo além desse limite não é carregado no início da sessão. Claude mantém `MEMORY.md` conciso movendo notas detalhadas para arquivos de tópico separados.418As primeiras 200 linhas de `MEMORY.md`, ou os primeiros 25KB, o que vier primeiro, são carregados no início de cada conversa. Conteúdo além desse limite não é carregado no início da sessão. Claude mantém `MEMORY.md` conciso movendo notas detalhadas para arquivos de tópico separados.

375 419 


379 423 

380Claude lê e escreve arquivos de memória durante sua sessão. Quando você vê "Writing memory" ou "Recalled memory" na interface do Claude Code, Claude está ativamente atualizando ou lendo de `~/.claude/projects/<project>/memory/`.424Claude lê e escreve arquivos de memória durante sua sessão. Quando você vê "Writing memory" ou "Recalled memory" na interface do Claude Code, Claude está ativamente atualizando ou lendo de `~/.claude/projects/<project>/memory/`.

381 425 

382### Audite e edite sua memória426<h3 id="audit-and-edit-your-memory">

427 Audite e edite sua memória

428</h3>

383 429 

384Arquivos de memória automática são markdown simples que você pode editar ou deletar a qualquer momento. Execute [`/memory`](#view-and-edit-with-memory) para navegar e abrir arquivos de memória de dentro de uma sessão.430Arquivos de memória automática são markdown simples que você pode editar ou deletar a qualquer momento. Execute [`/memory`](#view-and-edit-with-%2Fmemory) para navegar e abrir arquivos de memória de dentro de uma sessão.

385 431 

386## Visualize e edite com `/memory`432<h2 id="view-and-edit-with-/memory">

433 Visualize e edite com `/memory`

434</h2>

387 435 

388O comando `/memory` lista todos os arquivos CLAUDE.md, CLAUDE.local.md e rules carregados em sua sessão atual, permite que você alterne a memória automática ativada ou desativada, e fornece um link para abrir a pasta de memória automática. Selecione qualquer arquivo para abri-lo no seu editor.436O comando `/memory` lista todos os arquivos CLAUDE.md, CLAUDE.local.md e rules carregados em sua sessão atual, permite que você alterne a memória automática ativada ou desativada, e fornece um link para abrir a pasta de memória automática. Selecione qualquer arquivo para abri-lo no seu editor.

389 437 

390Quando você pede a Claude para lembrar algo, como "sempre use pnpm, não npm" ou "lembre-se de que os testes de API requerem uma instância local de Redis," Claude salva em memória automática. Para adicionar instruções a CLAUDE.md em vez disso, peça a Claude diretamente, como "adicione isto a CLAUDE.md," ou edite o arquivo você mesmo via `/memory`.438Quando você pede a Claude para lembrar algo, como "sempre use pnpm, não npm" ou "lembre-se de que os testes de API requerem uma instância local de Redis," Claude salva em memória automática. Para adicionar instruções a CLAUDE.md em vez disso, peça a Claude diretamente, como "adicione isto a CLAUDE.md," ou edite o arquivo você mesmo via `/memory`.

391 439 

392## Solucione problemas de memória440<h2 id="troubleshoot-memory-issues">

441 Solucione problemas de memória

442</h2>

393 443 

394Estes são os problemas mais comuns com CLAUDE.md e memória automática, junto com passos para depurá-los.444Estes são os problemas mais comuns com CLAUDE.md e memória automática, junto com passos para depurá-los.

395 445 

396### Claude não está seguindo meu CLAUDE.md446<h3 id="claude-isn’t-following-my-claude-md">

447 Claude não está seguindo meu CLAUDE.md

448</h3>

397 449 

398O conteúdo de CLAUDE.md é entregue como uma mensagem de usuário após o prompt do sistema, não como parte do próprio prompt do sistema. Claude o lê e tenta segui-lo, mas não há garantia de conformidade estrita, especialmente para instruções vagas ou conflitantes.450O conteúdo de CLAUDE.md é entregue como uma mensagem de usuário após o prompt do sistema, não como parte do próprio prompt do sistema. Claude o lê e tenta segui-lo, mas não há garantia de conformidade estrita, especialmente para instruções vagas ou conflitantes.

399 451 


412 Use o hook [`InstructionsLoaded`](/pt/hooks#instructionsloaded) para registrar exatamente quais arquivos de instrução são carregados, quando são carregados e por quê. Isso é útil para depurar regras específicas de caminho ou arquivos carregados preguiçosamente em subdiretórios.464 Use o hook [`InstructionsLoaded`](/pt/hooks#instructionsloaded) para registrar exatamente quais arquivos de instrução são carregados, quando são carregados e por quê. Isso é útil para depurar regras específicas de caminho ou arquivos carregados preguiçosamente em subdiretórios.

413</Tip>465</Tip>

414 466 

415### Não sei o que a memória automática salvou467<h3 id="i-don’t-know-what-auto-memory-saved">

468 Não sei o que a memória automática salvou

469</h3>

416 470 

417Execute `/memory` e selecione a pasta de memória automática para navegar o que Claude salvou. Tudo é markdown simples que você pode ler, editar ou deletar.471Execute `/memory` e selecione a pasta de memória automática para navegar o que Claude salvou. Tudo é markdown simples que você pode ler, editar ou deletar.

418 472 

419### Meu CLAUDE.md é muito grande473<h3 id="my-claude-md-is-too-large">

474 Meu CLAUDE.md é muito grande

475</h3>

420 476 

421Arquivos com mais de 200 linhas consomem mais contexto e podem reduzir a aderência. Use [regras com escopo de caminho](#path-specific-rules) para carregar instruções apenas quando Claude trabalha com arquivos correspondentes, ou reduza conteúdo que não é necessário em cada sessão. Dividir em [importações `@path`](#import-additional-files) ajuda na organização, mas não reduz contexto, já que arquivos importados são carregados no lançamento.477Arquivos com mais de 200 linhas consomem mais contexto e podem reduzir a aderência. Use [regras com escopo de caminho](#path-specific-rules) para carregar instruções apenas quando Claude trabalha com arquivos correspondentes, ou reduza conteúdo que não é necessário em cada sessão. Dividir em [importações `@path`](#import-additional-files) ajuda na organização, mas não reduz contexto, já que arquivos importados são carregados no lançamento.

422 478 

423### Instruções parecem perdidas após `/compact`479<h3 id="instructions-seem-lost-after-/compact">

480 Instruções parecem perdidas após `/compact`

481</h3>

424 482 

425CLAUDE.md de raiz de projeto sobrevive à compactação: após `/compact`, Claude relê do disco e reinjecta no contexto. Arquivos CLAUDE.md aninhados em subdiretórios não são reinjetados automaticamente; eles recarregam na próxima vez que Claude lê um arquivo naquele subdiretório.483CLAUDE.md de raiz de projeto sobrevive à compactação: após `/compact`, Claude relê do disco e reinjecta no contexto. Arquivos CLAUDE.md aninhados em subdiretórios não são reinjetados automaticamente; eles recarregam na próxima vez que Claude lê um arquivo naquele subdiretório.

426 484 


428 486 

429Veja [Escreva instruções eficazes](#write-effective-instructions) para orientação sobre tamanho, estrutura e especificidade.487Veja [Escreva instruções eficazes](#write-effective-instructions) para orientação sobre tamanho, estrutura e especificidade.

430 488 

431## Recursos relacionados489<h2 id="related-resources">

490 Recursos relacionados

491</h2>

432 492 

433* [Debug sua configuração](/pt/debug-your-config): diagnostique por que CLAUDE.md ou configurações não estão tendo efeito493* [Debug sua configuração](/pt/debug-your-config): diagnostique por que CLAUDE.md ou configurações não estão tendo efeito

434* [Skills](/pt/skills): empacote fluxos de trabalho repetíveis que carregam sob demanda494* [Skills](/pt/skills): empacote fluxos de trabalho repetíveis que carregam sob demanda

Details

6 6 

7> Saiba como configurar Claude Code através do Microsoft Foundry, incluindo configuração, instalação e resolução de problemas.7> Saiba como configurar Claude Code através do Microsoft Foundry, incluindo configuração, instalação e resolução de problemas.

8 8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

79<ContactSalesCard surface="foundry" />

80 

9<h2 id="prerequisites">81<h2 id="prerequisites">

10 Pré-requisitos82 Pré-requisitos

11</h2>83</h2>


17* Azure CLI instalado e configurado (opcional - necessário apenas se você não tiver outro mecanismo para obter credenciais)89* Azure CLI instalado e configurado (opcional - necessário apenas se você não tiver outro mecanismo para obter credenciais)

18 90 

19<Note>91<Note>

20 Se você está implantando Claude Code para vários usuários, [fixe suas versões de modelo](#4-pin-model-versions) para evitar problemas quando Anthropic lançar novos modelos.92 Se você está implantando Claude Code para vários usuários, [fixe suas versões de modelo](#4-pin-model-versions) antes de fazer o lançamento.

21</Note>93</Note>

22 94 

23<h2 id="setup">95<h2 id="setup">


90</h3>162</h3>

91 163 

92<Warning>164<Warning>

93 Fixe versões de modelo específicas para cada implantação. Se você usar aliases de modelo (`sonnet`, `opus`, `haiku`) sem fixar, Claude Code pode tentar usar uma versão de modelo mais recente que não está disponível em sua conta Foundry, quebrando usuários existentes quando Anthropic lançar atualizações. Quando você criar implantações do Azure, selecione uma versão de modelo específica em vez de "atualizar automaticamente para a mais recente".165 Fixe versões de modelo específicas para cada implantação. Sem fixar, aliases de modelo como `sonnet` e `opus` resolvem para o padrão integrado do Claude Code para Foundry, que pode ficar atrás da versão mais recente e pode ainda não estar disponível em sua conta. Foundry não possui verificação de modelo na inicialização, portanto as solicitações falham quando o padrão não está disponível. Quando você criar implantações do Azure, selecione uma versão de modelo específica em vez de "atualizar automaticamente para a mais recente".

94</Warning>166</Warning>

95 167 

96Defina as variáveis de modelo para corresponder aos nomes de implantação que você criou na etapa 1.168Defina as variáveis de modelo para corresponder aos nomes de implantação que você criou na etapa 1.

model-config.md +149 −27

Details

32| Alias de modelo | Comportamento |32| Alias de modelo | Comportamento |

33| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |33| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

34| **`default`** | Valor especial que limpa qualquer substituição de modelo e reverte para o modelo recomendado para seu tipo de conta. Não é em si um alias de modelo |34| **`default`** | Valor especial que limpa qualquer substituição de modelo e reverte para o modelo recomendado para seu tipo de conta. Não é em si um alias de modelo |

35| **`best`** | Usa o modelo mais capaz disponível, atualmente equivalente a `opus` |35| **`best`** | Usa Fable 5 onde sua organização tem acesso a ele, caso contrário o modelo Opus mais recente |

36| **`fable`** | Usa Claude Fable 5 para suas tarefas mais difíceis e de longa duração |

36| **`sonnet`** | Usa o modelo Sonnet mais recente para tarefas de codificação diária |37| **`sonnet`** | Usa o modelo Sonnet mais recente para tarefas de codificação diária |

37| **`opus`** | Usa o modelo Opus mais recente para tarefas de raciocínio complexo |38| **`opus`** | Usa o modelo Opus mais recente para tarefas de raciocínio complexo |

38| **`haiku`** | Usa o modelo Haiku rápido e eficiente para tarefas simples |39| **`haiku`** | Usa o modelo Haiku rápido e eficiente para tarefas simples |

39| **`sonnet[1m]`** | Usa Sonnet com uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas |40| **`sonnet[1m]`** | Usa Sonnet com uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas |

40| **`opus[1m]`** | Usa Opus com uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas |41| **`opus[1m]`** | Usa Opus com uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas |

41| **`opusplan`** | Modo especial que usa `opus` durante o Plan Mode, depois muda para `sonnet` para execução |42| **`opusplan`** | Modo especial que usa `opus` durante Plan Mode, depois muda para `sonnet` para execução |

42 43 

43Na API Anthropic, `opus` se resolve para Opus 4.8 e `sonnet` se resolve para Sonnet 4.6. Na [Claude Platform on AWS](/pt/claude-platform-on-aws), `opus` se resolve para Opus 4.7 e `sonnet` se resolve para Sonnet 4.6. No Bedrock, Vertex e Foundry, `opus` se resolve para Opus 4.6 e `sonnet` se resolve para Sonnet 4.5; modelos mais recentes estão disponíveis nesses provedores selecionando o nome completo do modelo explicitamente ou definindo `ANTHROPIC_DEFAULT_OPUS_MODEL` ou `ANTHROPIC_DEFAULT_SONNET_MODEL`.44Na API Anthropic, `opus` se resolve para Opus 4.8 e `sonnet` se resolve para Sonnet 4.6. Na [Claude Platform on AWS](/pt/claude-platform-on-aws), `opus` se resolve para Opus 4.7 e `sonnet` se resolve para Sonnet 4.6. No Bedrock, Vertex e Foundry, `opus` se resolve para Opus 4.6 e `sonnet` se resolve para Sonnet 4.5; modelos mais recentes estão disponíveis nesses provedores selecionando o nome completo do modelo explicitamente ou definindo `ANTHROPIC_DEFAULT_OPUS_MODEL` ou `ANTHROPIC_DEFAULT_SONNET_MODEL`.

44 45 


48 Opus 4.8 requer Claude Code v2.1.154 ou posterior. Execute `claude update` para atualizar.49 Opus 4.8 requer Claude Code v2.1.154 ou posterior. Execute `claude update` para atualizar.

49</Note>50</Note>

50 51 

52<h3 id="work-with-fable-5">

53 Trabalhar com Fable 5

54</h3>

55 

56[Claude Fable 5](https://platform.claude.com/docs/pt/about-claude/models/introducing-claude-fable-5-and-claude-mythos-5) é o modelo mais capaz no Claude Code, adequado para tarefas maiores que uma única sessão. Ele sustenta sessões autônomas longas, investiga antes de agir e verifica seu trabalho com mais frequência do que modelos menores.

57 

58Fable 5 não é o modelo padrão. Selecione-o com `/model fable`. Solicitações que seus classificadores de segurança sinalizam, mais frequentemente em domínios de cibersegurança e biologia, acionam [fallback automático de modelo](#automatic-model-fallback).

59 

60Para aproveitar ao máximo o Fable 5:

61 

62* **Descreva o resultado, não as etapas**: entregue-lhe o resultado que você deseja e deixe-o planejar o caminho. Para mantê-lo funcionando até que esse resultado se mantenha, [defina uma meta](/pt/goal).

63* **Entregue-lhe problemas ambíguos**: investigações de causa raiz, depuração de interrupções e decisões de arquitetura são onde a investigação e verificação extras compensam.

64* **Pule os lembretes de verificação**: ele verifica seu próprio trabalho com menos solicitação, portanto lembretes para testar ou verificar geralmente são desnecessários.

65* **Dimensione tarefas maiores**: dê-lhe trabalho que você normalmente dividiria em pedaços. Ele mantém sessões longas sem perder o fio.

66 

67<Note>

68 Fable 5 requer Claude Code v2.1.170 ou posterior. Versões mais antigas não mostram Fable 5 no seletor de modelo e não podem selecioná-lo. Execute `claude update` para atualizar. Fable 5 não está disponível sob [retenção zero de dados](/pt/zero-data-retention), onde o seletor `/model` o omite ou o mostra desabilitado.

69</Note>

70 

51<h3 id="setting-your-model">71<h3 id="setting-your-model">

52 Configurando seu modelo72 Configurando seu modelo

53</h3>73</h3>


101 121 

102Os administradores corporativos podem usar `availableModels` em [configurações gerenciadas ou de política](/pt/settings#settings-files) para restringir quais modelos os usuários podem selecionar.122Os administradores corporativos podem usar `availableModels` em [configurações gerenciadas ou de política](/pt/settings#settings-files) para restringir quais modelos os usuários podem selecionar.

103 123 

104Quando `availableModels` é definido, os usuários não podem alternar para modelos que não estão na lista via `/model`, sinalizador `--model` ou variável de ambiente `ANTHROPIC_MODEL`.124Quando `availableModels` é definido, a lista de permissões se aplica em todos os lugares onde um usuário pode especificar um modelo:

125 

126* **Modelo de sessão principal**: `/model`, o sinalizador `--model` e a variável de ambiente `ANTHROPIC_MODEL`

127* **Resolução de alias**: {/* min-version: 2.1.176 */}as variáveis de ambiente `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` e `ANTHROPIC_DEFAULT_FABLE_MODEL` não podem redirecionar um alias permitido para um modelo fora da lista

128* **Modo rápido**: {/* min-version: 2.1.176 */}`/fast` recusa alternar quando isso implicaria mudar implicitamente para um modelo Opus fora da lista, com a mensagem "não está nos modelos permitidos da sua organização"

129* **Modelos de subagente**: o campo `model` em [subagente](/pt/sub-agents#choose-a-model) frontmatter, o parâmetro `model` da ferramenta Agent, o seletor de modelo em `/agents` e `CLAUDE_CODE_SUBAGENT_MODEL`

130* **Modelo de advisor**: a configuração [`advisorModel`](/pt/advisor) configurada

131* **Cadeias de fallback**: elementos de uma [cadeia de modelo de fallback](#fallback-model-chains) fora da lista são descartados

132 

133Alternar para um modelo bloqueado com `/model` é rejeitado com um erro, enquanto um sinalizador `--model` bloqueado ou valor `ANTHROPIC_MODEL` é substituído na inicialização com um aviso nomeando tanto o modelo solicitado quanto o substituído, e a sessão é iniciada no modelo padrão. Uma substituição de subagente ou advisor bloqueada volta para o modelo herdado ou padrão em vez de falhar na solicitação.

105 134 

106```json theme={null}135```json theme={null}

107{136{


113 Comportamento do modelo padrão142 Comportamento do modelo padrão

114</h3>143</h3>

115 144 

116A opção Padrão no seletor de modelo não é afetada por `availableModels`. Ela sempre permanece disponível e representa o padrão de tempo de execução do sistema [baseado no nível de assinatura do usuário](#default-model-setting).145Por padrão, a opção Padrão no seletor de modelo não é afetada por `availableModels`. Ela permanece disponível e representa o padrão de tempo de execução do sistema [baseado no nível de assinatura do usuário](#default-model-setting).

117 146 

118Mesmo com `availableModels: []`, os usuários ainda podem usar Claude Code com o modelo Padrão para seu nível.147Para estender a lista de permissões à opção Padrão, defina `enforceAvailableModels` como `true` em configurações gerenciadas ou de política junto com uma lista `availableModels` não vazia. Quando o padrão do nível não está na lista de permissões, Padrão se resolve para a primeira entrada permitida em vez do padrão do nível. Isso requer Claude Code v2.1.175 ou posterior.

148 

149Um array `availableModels` vazio nunca ativa a imposição. Mesmo com `availableModels: []`, os usuários ainda podem usar Claude Code com o modelo Padrão para seu nível, independentemente de `enforceAvailableModels`.

119 150 

120<h3 id="control-the-model-users-run-on">151<h3 id="control-the-model-users-run-on">

121 Controlar o modelo em que os usuários executam152 Controlar o modelo em que os usuários executam


123 154 

124A configuração `model` é uma seleção inicial, não uma imposição. Ela define qual modelo está ativo quando uma sessão é iniciada, mas os usuários ainda podem abrir `/model` e escolher Padrão, que se resolve para o padrão do sistema para seu nível, independentemente do que `model` está definido.155A configuração `model` é uma seleção inicial, não uma imposição. Ela define qual modelo está ativo quando uma sessão é iniciada, mas os usuários ainda podem abrir `/model` e escolher Padrão, que se resolve para o padrão do sistema para seu nível, independentemente do que `model` está definido.

125 156 

126Para controlar totalmente a experiência do modelo, combine três configurações:157Para controlar totalmente a experiência do modelo, combine estas configurações:

127 158 

128* **`availableModels`**: restringe para quais modelos nomeados os usuários podem alternar159* **`availableModels`**: restringe para quais modelos nomeados os usuários podem alternar

160* **`enforceAvailableModels`**: estende a lista de permissões `availableModels` à opção Padrão, para que Padrão não possa se resolver para um modelo fora da lista

129* **`model`**: define a seleção de modelo inicial quando uma sessão é iniciada161* **`model`**: define a seleção de modelo inicial quando uma sessão é iniciada

130* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`**: controlam para o que a opção Padrão e os aliases `sonnet`, `opus` e `haiku` se resolvem162* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**: controlam para o que a opção Padrão e os aliases `sonnet`, `opus`, `haiku` e `fable` se resolvem

131 163 

132Este exemplo inicia os usuários em Sonnet 4.5, limita o seletor a Sonnet e Haiku, e fixa Padrão para se resolver em Sonnet 4.5 em vez da versão mais recente:164Este exemplo inicia os usuários em Sonnet 4.5, limita o seletor a Sonnet e Haiku, e garante que Padrão se resolve para um modelo na lista de permissões em vez do padrão do nível:

133 165 

134```json theme={null}166```json theme={null}

135{167{

136 "model": "claude-sonnet-4-5",168 "model": "claude-sonnet-4-5",

137 "availableModels": ["claude-sonnet-4-5", "haiku"],169 "availableModels": ["claude-sonnet-4-5", "haiku"],

170 "enforceAvailableModels": true,

138 "env": {171 "env": {

139 "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"172 "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"

140 }173 }

141}174}

142```175```

143 176 

144Sem o bloco `env`, um usuário que seleciona Padrão no seletor obteria a versão mais recente do Sonnet, contornando a fixação de versão em `model` e `availableModels`.177Sem `enforceAvailableModels` ou o bloco `env`, um usuário que seleciona Padrão no seletor obteria a versão mais recente para seu nível, contornando a fixação de versão em `model` e `availableModels`. As duas configurações cobrem escopos diferentes: `enforceAvailableModels` faz Padrão obedecer à lista de permissões, enquanto o bloco `env` fixa qual versão um alias permitido como `sonnet` se resolve. Use `enforceAvailableModels` sozinho quando restringir famílias de modelo é suficiente; adicione o bloco `env` quando você também precisar fixar uma versão específica.

145 178 

146<h3 id="merge-behavior">179<h3 id="merge-behavior">

147 Comportamento de mesclagem180 Comportamento de mesclagem

148</h3>181</h3>

149 182 

150Quando `availableModels` é definido em vários níveis, como configurações de usuário e configurações de projeto, os arrays são mesclados e desduplicados. Para impor uma lista de permissões rigorosa, defina `availableModels` em configurações gerenciadas ou de política que têm a prioridade mais alta.183Quando `availableModels` é definido em configurações de usuário, projeto e local apenas, os arrays são mesclados e desduplicados entre esses níveis.

184 

185Quando `availableModels` é definido em configurações gerenciadas ou de política, o valor gerenciado ou de política substitui completamente o resultado mesclado: entradas adicionadas em configurações de usuário ou projeto não podem ampliá-lo. Configurações gerenciadas e de política substituem valores de menor precedência para `enforceAvailableModels` da mesma forma. A partir de Claude Code v2.1.175, esta é a única maneira de impor uma lista de permissões rigorosa; versões anteriores mesclam a lista gerenciada com entradas de menor precedência.

151 186 

152<h3 id="mantle-model-ids">187<h3 id="mantle-model-ids">

153 IDs de modelo Mantle188 IDs de modelo Mantle

154</h3>189</h3>

155 190 

156Quando o [endpoint Bedrock Mantle](/pt/amazon-bedrock#use-the-mantle-endpoint) está habilitado, entradas em `availableModels` que começam com `anthropic.` são adicionadas ao seletor `/model` como opções personalizadas e roteadas para o endpoint Mantle. Esta é uma exceção à correspondência somente de alias descrita em [Fixar modelos para implantações de terceiros](#pin-models-for-third-party-deployments). A configuração ainda restringe o seletor às entradas listadas, portanto inclua os aliases padrão junto com qualquer ID Mantle.191Quando o [endpoint Bedrock Mantle](/pt/amazon-bedrock#use-the-mantle-endpoint) está habilitado, entradas em `availableModels` que começam com `anthropic.` são adicionadas ao seletor `/model` como opções personalizadas e roteadas para o endpoint Mantle. A configuração ainda restringe o seletor às entradas listadas, portanto inclua os aliases padrão junto com qualquer ID Mantle.

157 192 

158<h2 id="special-model-behavior">193<h2 id="special-model-behavior">

159 Comportamento especial do modelo194 Comportamento especial do modelo


172 207 

173Enterprise pagamento conforme o uso significa uma organização Enterprise cobrada por uso em vez de por assento de assinatura.208Enterprise pagamento conforme o uso significa uma organização Enterprise cobrada por uso em vez de por assento de assinatura.

174 209 

175Claude Code pode fazer fallback automaticamente para Sonnet se você atingir um limite de uso com Opus.210Fable 5 não é o modelo padrão em nenhum tipo de conta. As sessões usam Fable 5 apenas depois que você o escolhe, com `/model fable`, uma configuração `model` ou o alias `best` onde Fable 5 está disponível. Escolhê-lo com `/model` o salva como o modelo selecionado em suas configurações de usuário, portanto as sessões posteriores começam em Fable 5 até que você altere os modelos.

176 211 

177<h3 id="opusplan-model-setting">212<h3 id="opusplan-model-setting">

178 Configuração do modelo `opusplan`213 Configuração do modelo `opusplan`


185 220 

186Isso oferece o melhor dos dois mundos: o raciocínio superior do Opus para planejamento e a eficiência do Sonnet para execução.221Isso oferece o melhor dos dois mundos: o raciocínio superior do Opus para planejamento e a eficiência do Sonnet para execução.

187 222 

188A fase Opus do Plan Mode é executada com a janela de contexto padrão de 200K. A atualização automática de 1M descrita em [Contexto estendido](#extended-context) se aplica à configuração do modelo `opus` e não se estende a `opusplan`.223A fase Opus do Plan Mode usa a mesma janela de contexto da configuração do modelo `opus`. Nos níveis de assinatura onde Opus é [automaticamente atualizado para contexto 1M](#extended-context), `opusplan` recebe a atualização em Plan Mode também. Para forçar contexto 1M para ambas as fases quando você não está em um nível de atualização automática, defina o modelo para `opusplan[1m]`.

224 

225Quando [`availableModels`](#restrict-model-selection) exclui Opus, `opusplan` permanece em Sonnet em Plan Mode em vez de alternar. Da mesma forma, uma sessão Haiku que normalmente seria atualizada para Sonnet em Plan Mode permanece em Haiku quando Sonnet é excluído.

226 

227Para uma abordagem híbrida onde Claude decide no meio da tarefa quando consultar um segundo modelo em vez de alternar no limite do plano, veja a [ferramenta advisor](/pt/advisor).

228 

229<h3 id="fallback-model-chains">

230 Cadeias de modelo de fallback

231</h3>

232 

233Quando o modelo primário está sobrecarregado, indisponível ou retorna outro erro de servidor não retentável, Claude Code pode alternar para um modelo de fallback em vez de falhar na solicitação. Erros de autenticação, faturamento, limite de taxa, tamanho de solicitação e transporte nunca acionam uma alternância; esses seguem sua manipulação de erro e retry normal.

234 

235Configure um ou mais modelos de fallback e Claude Code os tenta em ordem, mostrando um aviso quando alterna. A alternância dura apenas para a volta atual, portanto sua próxima mensagem tenta o modelo primário primeiro novamente. As cadeias são limitadas a três modelos após remoção de duplicatas, e entradas extras são ignoradas.

236 

237Defina uma cadeia para uma sessão com o sinalizador `--fallback-model`, que aceita uma lista separada por vírgulas:

238 

239```bash theme={null}

240claude --fallback-model sonnet,haiku

241```

242 

243Para persistir uma cadeia entre sessões, defina `fallbackModel` em [configurações](/pt/settings) como uma matriz:

244 

245```json theme={null}

246{

247 "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]

248}

249```

250 

251O sinalizador `--fallback-model` tem precedência sobre a configuração `fallbackModel`. Cada elemento aceita um nome de modelo ou alias, e `"default"` se expande para o modelo padrão.

252 

253Dois casos fazem um elemento ser ignorado:

254 

255* **Modelo indisponível**: um modelo que não pode ser alcançado, como um modelo aposentado fixado em configurações, é ignorado e Claude Code continua para o próximo elemento.

256* **Fora da lista de permissões**: um elemento não permitido por [`availableModels`](#restrict-model-selection) é descartado quando a cadeia é lida e nunca é tentado.

257 

258<h3 id="automatic-model-fallback">

259 Fallback automático de modelo

260</h3>

261 

262Esta seção cobre fallback baseado em conteúdo de Fable 5. Para fallback baseado em disponibilidade quando um modelo está sobrecarregado ou indisponível, veja [Cadeias de modelo de fallback](#fallback-model-chains).

263 

264Fable 5 é executado com classificadores de segurança para conteúdo de cibersegurança e biologia. Quando um classificador sinaliza uma solicitação, Claude Code executa novamente essa solicitação no modelo Opus padrão e mostra um aviso na transcrição: Opus 4.8 na API Anthropic e implantações de [gateway LLM](/pt/llm-gateway), ou Opus 4.7 na [Claude Platform na AWS](/pt/claude-platform-on-aws).

265 

266A sessão então continua nesse modelo Opus. Para retornar a Fable 5, execute `/model fable`.

267 

268<h4 id="check-what-triggered-fallback">

269 Verificar o que acionou fallback

270</h4>

271 

272O fallback pode ser acionado na primeira solicitação de uma sessão, antes de você enviar algo incomum, porque a primeira solicitação carrega contexto do espaço de trabalho, como seu conteúdo CLAUDE.md e status do git. Um repositório que contém material de segurança ou biologia pode acionar o classificador apenas nesse contexto.

273 

274Para verificar se as personalizações são o gatilho, inicie uma sessão com `claude --safe-mode`, que desabilita personalizações como CLAUDE.md, skills, servidores MCP e hooks. O status do git e nomes de diretórios não são personalizações e ainda estão inclusos.

275 

276<h4 id="ask-before-switching">

277 Perguntar antes de alternar

278</h4>

279 

280Para decidir o que acontece cada vez que uma solicitação é sinalizada, em vez de alternar automaticamente, execute `/config` e desative "switch models when a message is flagged". Uma solicitação sinalizada então pausa a sessão com duas opções: alternar para o modelo Opus ou editar o prompt e tentar novamente em Fable 5.

281 

282Alguns casos se comportam diferentemente:

283 

284* Se ambos os modelos sinalizarem a mesma solicitação, você pode editar o prompt e tentar novamente, ou iniciar uma nova sessão.

285* Em sessões móveis [Claude Code na web](/pt/claude-code-on-the-web), editar e tentar novamente não é suportado. Alterne modelos ou continue a sessão de um navegador de desktop ou do aplicativo de desktop.

286* Em [modo não interativo](/pt/cli-reference#cli-flags) e integrações SDK que não podem mostrar o prompt, uma solicitação sinalizada encerra a volta com uma recusa em vez disso.

287 

288<h4 id="enable-fallback-on-bedrock-vertex-ai-and-foundry">

289 Habilitar fallback em Bedrock, Vertex AI e Foundry

290</h4>

291 

292Em [Amazon Bedrock](/pt/amazon-bedrock), [Google Vertex AI](/pt/google-vertex-ai) e [Microsoft Foundry](/pt/microsoft-foundry), IDs de modelo são específicos do provedor, portanto o fallback automático opera apenas quando Claude Code pode identificar ambos os modelos envolvidos:

293 

294* Claude Code deve reconhecer o modelo atual como Fable 5: o ID do modelo contém `claude-fable-5`, corresponde ao valor de `ANTHROPIC_DEFAULT_FABLE_MODEL` ou é mapeado com [`modelOverrides`](#override-model-ids-per-version).

295* O alvo de fallback deve resolver para um modelo Opus: o valor de `ANTHROPIC_DEFAULT_OPUS_MODEL` se definido, caso contrário uma entrada Opus 4.8 na lista de modelos do provedor.

296 

297Se qualquer modelo não puder ser identificado, Claude Code não alterna automaticamente. A solicitação sinalizada termina com uma mensagem de recusa, e você pode alternar modelos com [`/model`](#setting-your-model) e tentar novamente. Para habilitar fallback automático nesses provedores, defina `ANTHROPIC_DEFAULT_FABLE_MODEL` para seu ID de modelo Fable 5 e `ANTHROPIC_DEFAULT_OPUS_MODEL` para seu ID de modelo Opus 4.8.

298 

299<h4 id="security-research-and-biology-workloads">

300 Pesquisa de segurança e cargas de trabalho de biologia

301</h4>

302 

303Cargas de trabalho em segurança ofensiva ou biologia, incluindo testes de penetração, exercícios Capture the Flag (CTF) e bases de código adjacentes à biologia, acionam fallback frequentemente, geralmente na primeira solicitação. Para trabalho substancial de biologia, espere que quase todas as solicitações sejam redirecionadas.

304 

305Este é o roteamento esperado para esses domínios, não uma sinalização de conta. Se sua organização precisa de capacidade de classe Fable para este trabalho, pergunte ao seu time de contas Anthropic sobre programas de acesso confiável.

189 306 

190<h3 id="adjust-effort-level">307<h3 id="adjust-effort-level">

191 Ajustar nível de esforço308 Ajustar nível de esforço


197 314 

198| Modelo | Níveis |315| Modelo | Níveis |

199| :-------------------- | :-------------------------------------- |316| :-------------------- | :-------------------------------------- |

317| Fable 5 | `low`, `medium`, `high`, `xhigh`, `max` |

200| Opus 4.8 e Opus 4.7 | `low`, `medium`, `high`, `xhigh`, `max` |318| Opus 4.8 e Opus 4.7 | `low`, `medium`, `high`, `xhigh`, `max` |

201| Opus 4.6 e Sonnet 4.6 | `low`, `medium`, `high`, `max` |319| Opus 4.6 e Sonnet 4.6 | `low`, `medium`, `high`, `max` |

202 320 

203Se você definir um nível que o modelo ativo não suporta, Claude Code volta para o nível mais alto suportado no ou abaixo do que você definiu. Por exemplo, `xhigh` é executado como `high` em Opus 4.6.321Se você definir um nível que o modelo ativo não suporta, Claude Code volta para o nível mais alto suportado no ou abaixo do que você definiu. Por exemplo, `xhigh` é executado como `high` em Opus 4.6.

204 322 

205O esforço padrão é `high` em Opus 4.8, Opus 4.6 e Sonnet 4.6, e `xhigh` em Opus 4.7.323O esforço padrão é `high` em Fable 5, Opus 4.8, Opus 4.6 e Sonnet 4.6, e `xhigh` em Opus 4.7.

206 324 

207Quando você executa Opus 4.8 ou Opus 4.7 pela primeira vez, Claude Code aplica o esforço padrão desse modelo mesmo que você tenha definido anteriormente um nível diferente para outro modelo: `high` em Opus 4.8 e `xhigh` em Opus 4.7. Execute `/effort` novamente para escolher um nível diferente após alternar.325Quando você executa Fable 5, Opus 4.8 ou Opus 4.7 pela primeira vez, Claude Code aplica o esforço padrão desse modelo mesmo que você tenha definido anteriormente um nível diferente para outro modelo: `high` em Fable 5 e Opus 4.8, e `xhigh` em Opus 4.7. Execute `/effort` novamente para escolher um nível diferente após alternar.

208 326 

209`low`, `medium`, `high` e `xhigh` persistem entre sessões. `max` fornece o raciocínio mais profundo sem restrição no gasto de tokens e se aplica apenas à sessão atual, exceto quando definido através da variável de ambiente `CLAUDE_CODE_EFFORT_LEVEL`.327`low`, `medium`, `high` e `xhigh` persistem entre sessões. `max` fornece o raciocínio mais profundo sem restrição no gasto de tokens e se aplica apenas à sessão atual, exceto quando definido através da variável de ambiente `CLAUDE_CODE_EFFORT_LEVEL`.

210 328 


220| :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |338| :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

221| `low` | Reserve para tarefas curtas, delimitadas, sensíveis à latência que não são sensíveis à inteligência |339| `low` | Reserve para tarefas curtas, delimitadas, sensíveis à latência que não são sensíveis à inteligência |

222| `medium` | Reduz o uso de tokens para trabalho sensível a custos que pode fazer concessões em inteligência |340| `medium` | Reduz o uso de tokens para trabalho sensível a custos que pode fazer concessões em inteligência |

223| `high` | Equilibra o uso de tokens e inteligência. Padrão em Opus 4.8, Opus 4.6 e Sonnet 4.6 |341| `high` | Equilibra o uso de tokens e inteligência. Padrão em Fable 5, Opus 4.8, Opus 4.6 e Sonnet 4.6 |

224| `xhigh` | Raciocínio mais profundo com gasto de tokens mais alto. Padrão em Opus 4.7 |342| `xhigh` | Raciocínio mais profundo com gasto de tokens mais alto. Padrão em Opus 4.7 |

225| `max` | Pode melhorar o desempenho em tarefas exigentes, mas pode mostrar retornos decrescentes e é propenso a pensar demais. Teste antes de adotar amplamente |343| `max` | Pode melhorar o desempenho em tarefas exigentes, mas pode mostrar retornos decrescentes e é propenso a pensar demais. Teste antes de adotar amplamente |

226| `ultracode` | Uma configuração de Claude Code que planeja um [fluxo de trabalho dinâmico](/pt/workflows) para cada tarefa substancial com raciocínio `xhigh` por mensagem. Apenas de sessão |344| `ultracode` | Uma configuração de Claude Code que planeja um [fluxo de trabalho dinâmico](/pt/workflows) para cada tarefa substancial com raciocínio `xhigh` por mensagem. Apenas de sessão |


256 374 

257O raciocínio adaptativo torna o pensamento opcional em cada etapa, portanto Claude pode responder mais rápido a prompts rotineiros e reservar pensamento mais profundo para etapas que se beneficiam dele. Se você quiser que Claude pense mais ou menos frequentemente do que o nível atual produz, você pode dizer isso diretamente em seu prompt ou em `CLAUDE.md`; o modelo responde a essa orientação dentro de sua configuração de esforço.375O raciocínio adaptativo torna o pensamento opcional em cada etapa, portanto Claude pode responder mais rápido a prompts rotineiros e reservar pensamento mais profundo para etapas que se beneficiam dele. Se você quiser que Claude pense mais ou menos frequentemente do que o nível atual produz, você pode dizer isso diretamente em seu prompt ou em `CLAUDE.md`; o modelo responde a essa orientação dentro de sua configuração de esforço.

258 376 

259Opus 4.7 e posterior sempre usam raciocínio adaptativo. O modo de orçamento de pensamento fixo e `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` não se aplicam a eles.377Opus 4.7 e posterior sempre usam raciocínio adaptativo, assim como Fable 5. O modo de orçamento de pensamento fixo e `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` não se aplicam a eles.

260 378 

261Em Opus 4.6 e Sonnet 4.6, você pode definir `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` para reverter para o orçamento de pensamento fixo anterior controlado por `MAX_THINKING_TOKENS`. Veja [variáveis de ambiente](/pt/env-vars).379Em Opus 4.6 e Sonnet 4.6, você pode definir `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` para reverter para o orçamento de pensamento fixo anterior controlado por `MAX_THINKING_TOKENS`. Veja [variáveis de ambiente](/pt/env-vars).

262 380 


267Pensamento estendido é o raciocínio que Claude emite antes de responder. Em modelos que suportam [raciocínio adaptativo](#adjust-effort-level), o nível de esforço é o controle principal para quanto pensamento acontece; as configurações abaixo ativam ou desativam o pensamento e controlam como ele é exibido.385Pensamento estendido é o raciocínio que Claude emite antes de responder. Em modelos que suportam [raciocínio adaptativo](#adjust-effort-level), o nível de esforço é o controle principal para quanto pensamento acontece; as configurações abaixo ativam ou desativam o pensamento e controlam como ele é exibido.

268 386 

269| Controle | Como defini-lo |387| Controle | Como defini-lo |

270| :--------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |388| :--------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

271| Alternar para a sessão atual | Pressione `Option+T` no macOS ou `Alt+T` no Windows e Linux |389| Alternar para a sessão atual | Pressione `Option+T` no macOS ou `Alt+T` no Windows e Linux |

272| Definir o padrão global | Execute `/config` e alterne o modo de pensamento. Salvo como `alwaysThinkingEnabled` em `~/.claude/settings.json` |390| Definir o padrão global | Execute `/config` e alterne o modo de pensamento. Salvo como `alwaysThinkingEnabled` em `~/.claude/settings.json` |

273| Desabilitar independentemente do esforço | Defina [`MAX_THINKING_TOKENS=0`](/pt/env-vars). Outros valores se aplicam apenas com um [orçamento de pensamento fixo](#adaptive-reasoning-and-fixed-thinking-budgets) |391| Desabilitar independentemente do esforço | Defina [`MAX_THINKING_TOKENS=0`](/pt/env-vars), que desativa o pensamento na API Anthropic exceto em Fable 5. Em [provedores de terceiros](/pt/third-party-integrations) isso omite o parâmetro `thinking` em vez disso, e modelos de raciocínio adaptativo ainda podem pensar. Outros valores se aplicam apenas com um [orçamento de pensamento fixo](#adaptive-reasoning-and-fixed-thinking-budgets) |

392 

393O pensamento não pode ser desativado em Fable 5. O alternador de sessão, `alwaysThinkingEnabled` e `MAX_THINKING_TOKENS=0` não têm efeito lá, e Fable 5 decide por etapa quanto pensar com base no nível de esforço.

274 394 

275A saída de pensamento é recolhida por padrão. Pressione `Ctrl+O` para alternar o modo verboso e ver o raciocínio como texto em itálico cinzento. Sessões interativas na API Anthropic recebem blocos de pensamento redigidos por padrão, portanto defina `showThinkingSummaries: true` em [configurações](/pt/settings) se você quiser os resumos completos disponíveis quando expandir. Você é cobrado por todos os tokens de pensamento gerados, mesmo quando recolhidos ou redigidos.395A saída de pensamento é recolhida por padrão. Pressione `Ctrl+O` para alternar o modo verboso e ver o raciocínio como texto em itálico cinzento. Sessões interativas na API Anthropic recebem blocos de pensamento redigidos por padrão, portanto defina `showThinkingSummaries: true` em [configurações](/pt/settings) se você quiser os resumos completos disponíveis quando expandir. Você é cobrado por todos os tokens de pensamento gerados, mesmo quando recolhidos ou redigidos.

276 396 


278 Contexto estendido398 Contexto estendido

279</h3>399</h3>

280 400 

281Opus 4.6 e posterior, e Sonnet 4.6, suportam uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas com grandes bases de código.401Fable 5, Opus 4.6 e posterior, e Sonnet 4.6, suportam uma [janela de contexto de 1 milhão de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#1m-token-context-window) para sessões longas com grandes bases de código.

282 402 

283A disponibilidade varia por modelo e plano. Nos planos Max, Team e Enterprise, Opus é automaticamente atualizado para contexto 1M sem configuração adicional. Isso se aplica aos assentos Team Standard e Team Premium. Sonnet com contexto 1M não faz parte da atualização automática e requer [créditos de uso](https://support.claude.com/pt/articles/12429409-extra-usage-for-paid-claude-plans) em todos os planos de assinatura, incluindo Max.403A disponibilidade varia por modelo e plano. Nos planos Max, Team e Enterprise, Opus é automaticamente atualizado para contexto 1M sem configuração adicional. Isso se aplica aos assentos Team Standard e Team Premium. Na API Anthropic, Fable 5, Opus 4.8 e Opus 4.7 sempre são executados com a janela 1M. Sonnet com contexto 1M não faz parte da atualização automática e requer [créditos de uso](https://support.claude.com/pt/articles/12429409-extra-usage-for-paid-claude-plans) em todos os planos de assinatura, incluindo Max.

284 404 

285| Plano | Opus com contexto 1M | Sonnet com contexto 1M |405| Plano | Opus com contexto 1M | Sonnet com contexto 1M |

286| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |406| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |


340 460 

341| Variável de ambiente | Descrição |461| Variável de ambiente | Descrição |

342| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |462| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

463| `ANTHROPIC_DEFAULT_FABLE_MODEL` | O modelo a usar para `fable`, e o ID de modelo que Claude Code reconhece como Fable 5 para [fallback automático de modelo](#automatic-model-fallback) em provedores de terceiros |

343| `ANTHROPIC_DEFAULT_OPUS_MODEL` | O modelo a usar para `opus`, ou para `opusplan` quando Plan Mode está ativo. |464| `ANTHROPIC_DEFAULT_OPUS_MODEL` | O modelo a usar para `opus`, ou para `opusplan` quando Plan Mode está ativo. |

344| `ANTHROPIC_DEFAULT_SONNET_MODEL` | O modelo a usar para `sonnet`, ou para `opusplan` quando Plan Mode não está ativo. |465| `ANTHROPIC_DEFAULT_SONNET_MODEL` | O modelo a usar para `sonnet`, ou para `opusplan` quando Plan Mode não está ativo. |

345| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | O modelo a usar para `haiku`, ou [funcionalidade de fundo](/pt/costs#background-token-usage) |466| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | O modelo a usar para `haiku`, ou [funcionalidade de fundo](/pt/costs#background-token-usage) |


353 474 

354Ao implantar Claude Code através de [Bedrock](/pt/amazon-bedrock), [Vertex AI](/pt/google-vertex-ai), [Foundry](/pt/microsoft-foundry) ou [Claude Platform on AWS](/pt/claude-platform-on-aws), fixe versões de modelo antes de lançar para usuários.475Ao implantar Claude Code através de [Bedrock](/pt/amazon-bedrock), [Vertex AI](/pt/google-vertex-ai), [Foundry](/pt/microsoft-foundry) ou [Claude Platform on AWS](/pt/claude-platform-on-aws), fixe versões de modelo antes de lançar para usuários.

355 476 

356Sem fixação, Claude Code usa aliases de modelo (`sonnet`, `opus`, `haiku`) que resolvem para a versão mais recente. Quando Anthropic lança um novo modelo que ainda não está habilitado na conta de um usuário, os usuários de Bedrock e Vertex AI veem um aviso e voltam para a versão anterior para essa sessão, enquanto os usuários de Foundry veem erros porque Foundry não tem verificação de inicialização equivalente.477Sem fixação, Claude Code usa aliases de modelo como `fable`, `opus`, `sonnet` e `haiku` que resolvem para um ID de modelo padrão integrado para cada provedor. Esse padrão pode ficar atrás da versão mais recente do Anthropic, e o modelo para o qual aponta pode ainda não estar habilitado na conta de um usuário. Quando o padrão não está disponível, os usuários de Bedrock e Vertex AI veem um aviso e voltam para a versão anterior para essa sessão, enquanto os usuários de Foundry veem erros porque Foundry não tem verificação de inicialização equivalente.

357 478 

358<Warning>479<Warning>

359 Defina todas as três variáveis de ambiente de modelo para IDs de versão específicos como parte de sua configuração inicial. Fixar permite que você controle quando seus usuários se movem para um novo modelo.480 Defina as variáveis de ambiente de modelo para IDs de versão específicos como parte de sua configuração inicial. Fixar permite que você controle quando seus usuários se movem para um novo modelo.

360</Warning>481</Warning>

361 482 

362Use as seguintes variáveis de ambiente com IDs de modelo específicos de versão para seu provedor:483Use as seguintes variáveis de ambiente com IDs de modelo específicos de versão para seu provedor:


367| Vertex AI | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'` |488| Vertex AI | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'` |

368| Foundry | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'` |489| Foundry | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'` |

369 490 

370Aplique o mesmo padrão para `ANTHROPIC_DEFAULT_SONNET_MODEL` e `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Para IDs de modelo atuais e legados em todos os provedores, veja [Visão geral de modelos](https://platform.claude.com/docs/en/about-claude/models/overview). Para atualizar usuários para uma nova versão de modelo, atualize essas variáveis de ambiente e reimplante.491Aplique o mesmo padrão para `ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL` e `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Para IDs de modelo atuais e legados em todos os provedores, veja [Visão geral de modelos](https://platform.claude.com/docs/en/about-claude/models/overview). Para atualizar usuários para uma nova versão de modelo, atualize essas variáveis de ambiente e reimplante.

371 492 

372Para habilitar [contexto estendido](#extended-context) para um modelo fixado, anexe `[1m]` ao ID do modelo em `ANTHROPIC_DEFAULT_OPUS_MODEL` ou `ANTHROPIC_DEFAULT_SONNET_MODEL`:493Para habilitar [contexto estendido](#extended-context) para um modelo fixado, anexe `[1m]` ao ID do modelo em `ANTHROPIC_DEFAULT_OPUS_MODEL` ou `ANTHROPIC_DEFAULT_SONNET_MODEL`:

373 494 


375export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8[1m]'496export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8[1m]'

376```497```

377 498 

378O sufixo `[1m]` aplica a janela de contexto 1M a todo o uso dos aliases `opus` e `sonnet`. Ele não estende a fase Opus do modo de plano de `opusplan`, que [permanece limitada a 200K](#opusplan-model-setting).499O sufixo `[1m]` aplica a janela de contexto 1M a todo o uso dos aliases `opus` e `sonnet`, incluindo a fase Opus do modo de plano de [`opusplan`](#opusplan-model-setting).

379 500 

380* Claude Code remove o sufixo antes de enviar o ID do modelo para seu provedor.501* Claude Code remove o sufixo antes de enviar o ID do modelo para seu provedor.

381* Apenas anexe `[1m]` quando o modelo subjacente [suportar contexto 1M](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window).502* Apenas anexe `[1m]` quando o modelo subjacente [suportar contexto 1M](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window).

382* O sufixo é lido por variável, não por modelo. No Bedrock, Vertex e Foundry, um ID de modelo sem `[1m]` em uma variável usa contexto 200K mesmo se outra variável define o mesmo modelo com o sufixo.503* O sufixo é lido por variável, não por modelo. No Bedrock, Vertex e Foundry, um ID de modelo sem `[1m]` em uma variável usa contexto 200K mesmo se outra variável define o mesmo modelo com o sufixo.

383 504 

384<Note>505<Note>

385 A lista de permissões `settings.availableModels` ainda se aplica ao usar provedores de terceiros. A filtragem corresponde ao alias de modelo (`opus`, `sonnet`, `haiku`), não ao ID de modelo específico do provedor.506 A lista de permissões `settings.availableModels` ainda se aplica ao usar provedores de terceiros. A filtragem corresponde ao alias de modelo como `opus`, o prefixo de versão como `claude-opus-4-8`, ou o ID de modelo completo. Qualquer sufixo `[1m]` é removido tanto da entrada da lista de permissões quanto do modelo solicitado antes da correspondência, então uma entrada de `claude-opus-4-8` permite tanto as linhas Opus padrão quanto as de contexto 1M. Prefixos específicos do provedor como `us.anthropic.` não são removidos: liste a mesma forma em `availableModels` que o seletor mostra, ou mapeie através de [`modelOverrides`](#override-model-ids-per-version).

386</Note>507</Note>

387 508 

388<h3 id="customize-pinned-model-display-and-capabilities">509<h3 id="customize-pinned-model-display-and-capabilities">


399| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Opus fixado no seletor `/model`. Padrão para `Custom Opus model` quando não definido |520| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | Descrição de exibição para o modelo Opus fixado no seletor `/model`. Padrão para `Custom Opus model` quando não definido |

400| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de capacidades que o modelo Opus fixado suporta |521| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | Lista separada por vírgulas de capacidades que o modelo Opus fixado suporta |

401 522 

402Os mesmos sufixos `_NAME`, `_DESCRIPTION` e `_SUPPORTED_CAPABILITIES` estão disponíveis para `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL` e `ANTHROPIC_CUSTOM_MODEL_OPTION`.523Os mesmos sufixos `_NAME`, `_DESCRIPTION` e `_SUPPORTED_CAPABILITIES` estão disponíveis para `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_FABLE_MODEL` e `ANTHROPIC_CUSTOM_MODEL_OPTION`.

403 524 

404Claude Code habilita recursos como [níveis de esforço](#adjust-effort-level) e [pensamento estendido](#extended-thinking) correspondendo o ID do modelo contra padrões conhecidos. IDs específicos do provedor, como ARNs Bedrock ou nomes de implantação personalizados, geralmente não correspondem a esses padrões, deixando recursos suportados desabilitados. Defina `_SUPPORTED_CAPABILITIES` para informar ao Claude Code quais recursos o modelo realmente suporta:525Claude Code habilita recursos como [níveis de esforço](#adjust-effort-level) e [pensamento estendido](#extended-thinking) correspondendo o ID do modelo contra padrões conhecidos. IDs específicos do provedor, como ARNs Bedrock ou nomes de implantação personalizados, geralmente não correspondem a esses padrões, deixando recursos suportados desabilitados. Defina `_SUPPORTED_CAPABILITIES` para informar ao Claude Code quais recursos o modelo realmente suporta:

405 526 


463| `DISABLE_PROMPT_CACHING_HAIKU` | Defina como `1` para desabilitar prompt caching apenas para modelos Haiku |584| `DISABLE_PROMPT_CACHING_HAIKU` | Defina como `1` para desabilitar prompt caching apenas para modelos Haiku |

464| `DISABLE_PROMPT_CACHING_SONNET` | Defina como `1` para desabilitar prompt caching apenas para modelos Sonnet |585| `DISABLE_PROMPT_CACHING_SONNET` | Defina como `1` para desabilitar prompt caching apenas para modelos Sonnet |

465| `DISABLE_PROMPT_CACHING_OPUS` | Defina como `1` para desabilitar prompt caching apenas para modelos Opus |586| `DISABLE_PROMPT_CACHING_OPUS` | Defina como `1` para desabilitar prompt caching apenas para modelos Opus |

587| `DISABLE_PROMPT_CACHING_FABLE` | Defina como `1` para desabilitar prompt caching apenas para modelos Fable |

466 588 

467Para alterar o TTL do cache ou aprender o que dispara uma falha de cache, veja [Como Claude Code usa prompt caching](/pt/prompt-caching).589Para alterar o TTL do cache ou aprender o que dispara uma falha de cache, veja [Como Claude Code usa prompt caching](/pt/prompt-caching).

monitoring-usage.md +300 −129

Details

8 8 

9Rastreie o uso, custos e atividade de ferramentas do Claude Code em toda a sua organização exportando dados de telemetria através do OpenTelemetry (OTel). Claude Code exporta métricas como dados de série temporal via protocolo de métricas padrão, eventos via protocolo de logs/eventos e, opcionalmente, rastreamentos distribuídos via [protocolo de rastreamentos](#traces-beta). Configure seus backends de métricas, logs e rastreamentos para corresponder aos seus requisitos de monitoramento.9Rastreie o uso, custos e atividade de ferramentas do Claude Code em toda a sua organização exportando dados de telemetria através do OpenTelemetry (OTel). Claude Code exporta métricas como dados de série temporal via protocolo de métricas padrão, eventos via protocolo de logs/eventos e, opcionalmente, rastreamentos distribuídos via [protocolo de rastreamentos](#traces-beta). Configure seus backends de métricas, logs e rastreamentos para corresponder aos seus requisitos de monitoramento.

10 10 

11## Início rápido11<h2 id="quick-start">

12 Início rápido

13</h2>

12 14 

13Configure OpenTelemetry usando variáveis de ambiente:15Configure OpenTelemetry usando variáveis de ambiente:

14 16 


41 43 

42Para opções de configuração completas, consulte a [especificação OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options).44Para opções de configuração completas, consulte a [especificação OpenTelemetry](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options).

43 45 

44## Configuração do administrador46<h2 id="administrator-configuration">

47 Configuração do administrador

48</h2>

45 49 

46Os administradores podem configurar as definições de OpenTelemetry para todos os usuários através do [arquivo de configurações gerenciadas](/pt/settings#settings-files). Isso permite controle centralizado das configurações de telemetria em toda a organização. Consulte a [precedência de configurações](/pt/settings#settings-precedence) para obter mais informações sobre como as configurações são aplicadas.50Os administradores podem configurar as definições de OpenTelemetry para todos os usuários através do [arquivo de configurações gerenciadas](/pt/settings#settings-files). Isso permite controle centralizado das configurações de telemetria em toda a organização. Consulte a [precedência de configurações](/pt/settings#settings-precedence) para obter mais informações sobre como as configurações são aplicadas.

47 51 


66 70 

67Claude Code não passa variáveis de ambiente `OTEL_*` para os subprocessos que ele gera, incluindo a ferramenta Bash, hooks, servidores MCP e servidores de linguagem. Um aplicativo instrumentado com OpenTelemetry que você executa através da ferramenta Bash não herda o endpoint do exportador ou cabeçalhos do Claude Code, então defina essas variáveis diretamente no comando se esse aplicativo precisar exportar sua própria telemetria.71Claude Code não passa variáveis de ambiente `OTEL_*` para os subprocessos que ele gera, incluindo a ferramenta Bash, hooks, servidores MCP e servidores de linguagem. Um aplicativo instrumentado com OpenTelemetry que você executa através da ferramenta Bash não herda o endpoint do exportador ou cabeçalhos do Claude Code, então defina essas variáveis diretamente no comando se esse aplicativo precisar exportar sua própria telemetria.

68 72 

69## Detalhes de configuração73<h2 id="configuration-details">

74 Detalhes de configuração

75</h2>

70 76 

71### Variáveis de configuração comuns77<h3 id="common-configuration-variables">

78 Variáveis de configuração comuns

79</h3>

72 80 

73| Variável de Ambiente | Descrição | Valores de Exemplo |81| Variável de Ambiente | Descrição | Valores de Exemplo |

74| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |82| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |


91| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Preferência de temporalidade de métricas (padrão: `delta`). Defina como `cumulative` se seu backend espera temporalidade cumulativa | `delta`, `cumulative` |99| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Preferência de temporalidade de métricas (padrão: `delta`). Defina como `cumulative` se seu backend espera temporalidade cumulativa | `delta`, `cumulative` |

92| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Intervalo para atualizar cabeçalhos dinâmicos (padrão: 1740000ms / 29 minutos) | `900000` |100| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Intervalo para atualizar cabeçalhos dinâmicos (padrão: 1740000ms / 29 minutos) | `900000` |

93 101 

94### Autenticação mTLS102<h3 id="mtls-authentication">

103 Autenticação mTLS

104</h3>

95 105 

96Como você configura certificados de cliente para o exportador OTLP depende do protocolo OTLP em uso para esse sinal, definido via `OTEL_EXPORTER_OTLP_PROTOCOL` ou a substituição por sinal. A mesma configuração se aplica a métricas, logs e rastreamentos.106Como você configura certificados de cliente para o exportador OTLP depende do protocolo OTLP em uso para esse sinal, definido via `OTEL_EXPORTER_OTLP_PROTOCOL` ou a substituição por sinal. A mesma configuração se aplica a métricas, logs e rastreamentos.

97 107 


102 112 

103Para `grpc`, o SDK OpenTelemetry lê as variáveis OTLP padrão diretamente, então as configurações existentes que definem as variáveis de métricas por sinal continuam funcionando.113Para `grpc`, o SDK OpenTelemetry lê as variáveis OTLP padrão diretamente, então as configurações existentes que definem as variáveis de métricas por sinal continuam funcionando.

104 114 

105### Controle de cardinalidade de métricas115<h3 id="metrics-cardinality-control">

116 Controle de cardinalidade de métricas

117</h3>

106 118 

107As seguintes variáveis de ambiente controlam quais atributos são incluídos nas métricas para gerenciar a cardinalidade:119As seguintes variáveis de ambiente controlam quais atributos são incluídos nas métricas para gerenciar a cardinalidade:

108 120 


116 128 

117Essas variáveis ajudam a controlar a cardinalidade das métricas, o que afeta os requisitos de armazenamento e o desempenho de consultas no seu backend de métricas. Cardinalidade mais baixa geralmente significa melhor desempenho e custos de armazenamento mais baixos, mas dados menos granulares para análise.129Essas variáveis ajudam a controlar a cardinalidade das métricas, o que afeta os requisitos de armazenamento e o desempenho de consultas no seu backend de métricas. Cardinalidade mais baixa geralmente significa melhor desempenho e custos de armazenamento mais baixos, mas dados menos granulares para análise.

118 130 

119### Rastreamentos (beta)131<h3 id="traces-beta">

132 Rastreamentos (beta)

133</h3>

120 134 

121O rastreamento distribuído exporta spans que vinculam cada prompt do usuário às solicitações de API e execuções de ferramentas que ele dispara, para que você possa visualizar uma solicitação completa como um único rastreamento no seu backend de rastreamento.135O rastreamento distribuído exporta spans que vinculam cada prompt do usuário às solicitações de API e execuções de ferramentas que ele dispara, para que você possa visualizar uma solicitação completa como um único rastreamento no seu backend de rastreamento.

122 136 

123O rastreamento está desativado por padrão. Para ativá-lo, defina tanto `CLAUDE_CODE_ENABLE_TELEMETRY=1` quanto `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, depois defina `OTEL_TRACES_EXPORTER` para escolher para onde os spans são enviados. Os rastreamentos reutilizam a [configuração OTLP comum](#variáveis-de-configuração-comuns) para endpoint, protocolo, cabeçalhos e [mTLS](#autenticação-mtls).137O rastreamento está desativado por padrão. Para ativá-lo, defina tanto `CLAUDE_CODE_ENABLE_TELEMETRY=1` quanto `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, depois defina `OTEL_TRACES_EXPORTER` para escolher para onde os spans são enviados. Os rastreamentos reutilizam a [configuração OTLP comum](#common-configuration-variables) para endpoint, protocolo, cabeçalhos e [mTLS](#mtls-authentication).

124 138 

125| Variável de Ambiente | Descrição | Valores de Exemplo |139| Variável de Ambiente | Descrição | Valores de Exemplo |

126| ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |140| ------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |


140 154 

141No Agent SDK e sessões não-interativas iniciadas com `-p`, Claude Code também lê `TRACEPARENT` e `TRACESTATE` de seu próprio ambiente ao iniciar cada span de interação. Isso permite que um processo de incorporação passe seu contexto de rastreamento W3C ativo para o subprocesso para que os spans do Claude Code apareçam como filhos do rastreamento distribuído do chamador. Sessões interativas ignoram `TRACEPARENT` de entrada para evitar herdar acidentalmente valores ambientes de CI ou ambientes de contêiner.155No Agent SDK e sessões não-interativas iniciadas com `-p`, Claude Code também lê `TRACEPARENT` e `TRACESTATE` de seu próprio ambiente ao iniciar cada span de interação. Isso permite que um processo de incorporação passe seu contexto de rastreamento W3C ativo para o subprocesso para que os spans do Claude Code apareçam como filhos do rastreamento distribuído do chamador. Sessões interativas ignoram `TRACEPARENT` de entrada para evitar herdar acidentalmente valores ambientes de CI ou ambientes de contêiner.

142 156 

143#### Hierarquia de span157<h4 id="span-hierarchy">

158 Hierarquia de span

159</h4>

144 160 

145Cada prompt do usuário inicia um span raiz `claude_code.interaction`. Chamadas de API, chamadas de ferramenta e execuções de hook são registradas como seus filhos. Os spans de ferramenta têm dois spans filhos próprios: um para o tempo gasto esperando uma decisão de permissão e outro para a execução em si. Quando a ferramenta Agent ou a ferramenta Task legada gera um subagente, os spans de API e ferramenta do subagente se aninham sob o span `claude_code.tool` do pai.161Cada prompt do usuário inicia um span raiz `claude_code.interaction`. Chamadas de API, chamadas de ferramenta e execuções de hook são registradas como seus filhos. Os spans de ferramenta têm dois spans filhos próprios: um para o tempo gasto esperando uma decisão de permissão e outro para a execução em si. Quando a ferramenta Agent ou a ferramenta Task legada gera um subagente, os spans de API e ferramenta do subagente se aninham sob o span `claude_code.tool` do pai.

146 162 


156 172 

157No Agent SDK e sessões `claude -p`, `claude_code.interaction` em si se torna um filho do span do chamador quando `TRACEPARENT` está definido no ambiente.173No Agent SDK e sessões `claude -p`, `claude_code.interaction` em si se torna um filho do span do chamador quando `TRACEPARENT` está definido no ambiente.

158 174 

159#### Atributos de span175<h4 id="span-attributes">

176 Atributos de span

177</h4>

160 178 

161Cada span carrega os [atributos padrão](#atributos-padrão) mais um atributo `span.type` correspondendo ao seu nome. As tabelas abaixo listam os atributos adicionais definidos em cada span. Os spans `llm_request`, `tool.execution` e `hook` definem status OpenTelemetry `ERROR` quando registram uma falha; os outros spans sempre terminam com status `UNSET`.179Cada span carrega os [atributos padrão](#standard-attributes) mais um atributo `span.type` correspondendo ao seu nome. As tabelas abaixo listam os atributos adicionais definidos em cada span. Os spans `llm_request`, `tool.execution` e `hook` definem status OpenTelemetry `ERROR` quando registram uma falha; os outros spans sempre terminam com status `UNSET`.

162 180 

163**`claude_code.interaction`**181**`claude_code.interaction`**

164 182 


203**`claude_code.tool`**221**`claude_code.tool`**

204 222 

205| Atributo | Descrição | Controlado Por |223| Atributo | Descrição | Controlado Por |

206| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------- |224| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |

207| `tool_name` | Nome da ferramenta | |225| `tool_name` | Nome da ferramenta | |

208| `duration_ms` | Duração de parede incluindo espera de permissão e execução | |226| `duration_ms` | Duração de parede incluindo espera de permissão e execução | |

209| `result_tokens` | Tamanho aproximado em tokens do resultado da ferramenta | |227| `result_tokens` | Tamanho aproximado em tokens do resultado da ferramenta | |

210| `agent_id` | Identificador do subagente ou colega que executou a ferramenta. Ausente na sessão principal | |228| `agent_id` | Identificador do subagente ou colega que executou a ferramenta. Ausente na sessão principal | |

211| `parent_agent_id` | Identificador do agente que gerou este. Ausente para a sessão principal e para agentes gerados diretamente a partir dela | |229| `parent_agent_id` | Identificador do agente que gerou este. Ausente para a sessão principal e para agentes gerados diretamente a partir dela | |

230| `tool_use_id` | O id do bloco `tool_use` do modelo para esta chamada. Corresponde ao `tool_use_id` nos eventos [tool\_result](#tool-result-event) e [tool\_decision](#tool-decision-event) e nas cargas de hook, para que você possa unir o span a esses registros | |

231| `gen_ai.tool.call.id` | Mesmo valor que `tool_use_id`. Convenção semântica GenAI OpenTelemetry | |

212| `file_path` | Caminho de arquivo alvo para ferramentas Read, Edit e Write | `OTEL_LOG_TOOL_DETAILS` |232| `file_path` | Caminho de arquivo alvo para ferramentas Read, Edit e Write | `OTEL_LOG_TOOL_DETAILS` |

213| `full_command` | String de comando para a ferramenta Bash | `OTEL_LOG_TOOL_DETAILS` |233| `full_command` | String de comando para a ferramenta Bash | `OTEL_LOG_TOOL_DETAILS` |

214| `skill_name` | Nome da skill para a ferramenta Skill | `OTEL_LOG_TOOL_DETAILS` |234| `skill_name` | Nome da skill para a ferramenta Skill | `OTEL_LOG_TOOL_DETAILS` |


219**`claude_code.tool.blocked_on_user`**239**`claude_code.tool.blocked_on_user`**

220 240 

221| Atributo | Descrição | Controlado Por |241| Atributo | Descrição | Controlado Por |

222| ------------- | ------------------------------------------------------------------------------------------------------- | -------------- |242| ------------- | ------------------------------------------------------------------------------------------- | -------------- |

223| `duration_ms` | Tempo gasto esperando a decisão de permissão | |243| `duration_ms` | Tempo gasto esperando a decisão de permissão | |

224| `decision` | `accept` ou `reject` | |244| `decision` | `accept` ou `reject` | |

225| `source` | Fonte de decisão, correspondendo ao [Evento de decisão da ferramenta](#evento-de-decisão-da-ferramenta) | |245| `source` | Fonte de decisão, correspondendo ao [Evento de decisão da ferramenta](#tool-decision-event) | |

226 246 

227**`claude_code.tool.execution`**247**`claude_code.tool.execution`**

228 248 

229| Atributo | Descrição | Controlado Por |249| Atributo | Descrição | Controlado Por |

230| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |250| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |

231| `duration_ms` | Tempo gasto executando o corpo da ferramenta | |251| `duration_ms` | Tempo gasto executando o corpo da ferramenta | |

252| `tool_use_id` | Mesmo valor que no span pai `claude_code.tool` | |

253| `gen_ai.tool.call.id` | Mesmo valor que `tool_use_id`. Convenção semântica GenAI OpenTelemetry | |

232| `success` | `true` ou `false` | |254| `success` | `true` ou `false` | |

233| `error` | String de categoria de erro quando a execução falhou, como `Error:ENOENT` ou `ShellError`. Contém a mensagem de erro completa em vez disso quando o gate está definido | `OTEL_LOG_TOOL_DETAILS` |255| `error` | String de categoria de erro quando a execução falhou, como `Error:ENOENT` ou `ShellError`. Contém a mensagem de erro completa em vez disso quando o gate está definido | `OTEL_LOG_TOOL_DETAILS` |

234 256 


252 Atributos adicionais que contêm conteúdo, como `new_context`, `system_prompt_preview`, `user_system_prompt`, `tool_input` e `response.model_output`, são emitidos apenas quando rastreamento beta detalhado está ativo. Eles não fazem parte do esquema de span estável. `user_system_prompt` também requer `OTEL_LOG_USER_PROMPTS=1`. Ele carrega apenas o texto do prompt do sistema que você fornece através da opção SDK `systemPrompt` ou dos sinalizadores `--system-prompt` e `--append-system-prompt`, truncado em 60 KB, e é emitido uma vez por sessão em vez de por solicitação.274 Atributos adicionais que contêm conteúdo, como `new_context`, `system_prompt_preview`, `user_system_prompt`, `tool_input` e `response.model_output`, são emitidos apenas quando rastreamento beta detalhado está ativo. Eles não fazem parte do esquema de span estável. `user_system_prompt` também requer `OTEL_LOG_USER_PROMPTS=1`. Ele carrega apenas o texto do prompt do sistema que você fornece através da opção SDK `systemPrompt` ou dos sinalizadores `--system-prompt` e `--append-system-prompt`, truncado em 60 KB, e é emitido uma vez por sessão em vez de por solicitação.

253</Note>275</Note>

254 276 

255### Cabeçalhos dinâmicos277<h3 id="dynamic-headers">

278 Cabeçalhos dinâmicos

279</h3>

256 280 

257Para ambientes corporativos que exigem autenticação dinâmica, você pode configurar um script para gerar cabeçalhos dinamicamente. Cabeçalhos dinâmicos se aplicam apenas aos protocolos `http/protobuf` e `http/json`. O exportador `grpc` usa apenas o valor estático `OTEL_EXPORTER_OTLP_HEADERS`.281Para ambientes corporativos que exigem autenticação dinâmica, você pode configurar um script para gerar cabeçalhos dinamicamente. Cabeçalhos dinâmicos se aplicam apenas aos protocolos `http/protobuf` e `http/json`. O exportador `grpc` usa apenas o valor estático `OTEL_EXPORTER_OTLP_HEADERS`.

258 282 

259#### Configuração de configurações283<h4 id="settings-configuration">

284 Configuração de configurações

285</h4>

260 286 

261Adicione ao seu `.claude/settings.json`:287Adicione ao seu `.claude/settings.json`:

262 288 


268 294 

269O valor pode ser o caminho para um arquivo executável, incluindo um caminho que contém espaços, ou uma linha de comando shell com argumentos. No Windows, o valor sempre é executado através do shell, então coloque entre aspas um caminho que contém espaços dentro do valor JSON.295O valor pode ser o caminho para um arquivo executável, incluindo um caminho que contém espaços, ou uma linha de comando shell com argumentos. No Windows, o valor sempre é executado através do shell, então coloque entre aspas um caminho que contém espaços dentro do valor JSON.

270 296 

271#### Requisitos do script297<h4 id="script-requirements">

298 Requisitos do script

299</h4>

272 300 

273O script deve gerar JSON válido com pares de chave-valor de string representando cabeçalhos HTTP:301O script deve gerar JSON válido com pares de chave-valor de string representando cabeçalhos HTTP:

274 302 


284* O log de depuração, ao executar com [`--debug`](/pt/cli-reference#cli-flags) ou após executar `/debug` na sessão312* O log de depuração, ao executar com [`--debug`](/pt/cli-reference#cli-flags) ou após executar `/debug` na sessão

285* stderr, em sessões não-interativas iniciadas com `-p`313* stderr, em sessões não-interativas iniciadas com `-p`

286 314 

287#### Comportamento de atualização315<h4 id="refresh-behavior">

316 Comportamento de atualização

317</h4>

288 318 

289O script auxiliar de cabeçalhos é executado na inicialização e periodicamente depois para suportar atualização de token. Por padrão, o script é executado a cada 29 minutos. Personalize o intervalo com a variável de ambiente `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`.319O script auxiliar de cabeçalhos é executado na inicialização e periodicamente depois para suportar atualização de token. Por padrão, o script é executado a cada 29 minutos. Personalize o intervalo com a variável de ambiente `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`.

290 320 

291### Suporte a organizações multi-equipe321<h3 id="multi-team-organization-support">

322 Suporte a organizações multi-equipe

323</h3>

292 324 

293Organizações com múltiplas equipes ou departamentos podem adicionar atributos personalizados para distinguir entre diferentes grupos usando a variável de ambiente `OTEL_RESOURCE_ATTRIBUTES`:325Organizações com múltiplas equipes ou departamentos podem adicionar atributos personalizados para distinguir entre diferentes grupos usando a variável de ambiente `OTEL_RESOURCE_ATTRIBUTES`:

294 326 


304* Crie dashboards específicos de equipe336* Crie dashboards específicos de equipe

305* Configure alertas para equipes específicas337* Configure alertas para equipes específicas

306 338 

307Claude Code anexa esses valores como atributos em cada ponto de dados de métrica e registro de evento, além de enviá-los no bloco de recurso OTLP. Como a maioria dos backends de métricas expõe atributos de ponto de dados como rótulos consultáveis, você pode agrupar e filtrar métricas por suas chaves personalizadas diretamente. Chaves personalizadas nunca substituem os [atributos padrão](#atributos-padrão) como `user.id` ou `session.id`: quando uma chave colide, Claude Code mantém o valor integrado.339Claude Code anexa esses valores como atributos em cada ponto de dados de métrica e registro de evento, além de enviá-los no bloco de recurso OTLP. Como a maioria dos backends de métricas expõe atributos de ponto de dados como rótulos consultáveis, você pode agrupar e filtrar métricas por suas chaves personalizadas diretamente. Chaves personalizadas nunca substituem os [atributos padrão](#standard-attributes) como `user.id` ou `session.id`: quando uma chave colide, Claude Code mantém o valor integrado.

308 340 

309Cada chave personalizada se torna um rótulo em cada série de métrica, então valores de alta cardinalidade aumentam o custo de armazenamento no seu backend de métricas. Para enviar atributos personalizados apenas no bloco de recurso e omiti-los dos rótulos de ponto de dados, defina `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`. Veja [Controle de cardinalidade de métricas](#controle-de-cardinalidade-de-métricas).341Cada chave personalizada se torna um rótulo em cada série de métrica, então valores de alta cardinalidade aumentam o custo de armazenamento no seu backend de métricas. Para enviar atributos personalizados apenas no bloco de recurso e omiti-los dos rótulos de ponto de dados, defina `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`. Veja [Controle de cardinalidade de métricas](#metrics-cardinality-control).

310 342 

311<Warning>343<Warning>

312 **Requisitos importantes de formatação para OTEL\_RESOURCE\_ATTRIBUTES:**344 **Requisitos importantes de formatação para OTEL\_RESOURCE\_ATTRIBUTES:**


335 Nota: envolver valores em aspas não escapa espaços. Por exemplo, `org.name="My Company"` resulta no valor literal `"My Company"` (com aspas incluídas), não `My Company`.367 Nota: envolver valores em aspas não escapa espaços. Por exemplo, `org.name="My Company"` resulta no valor literal `"My Company"` (com aspas incluídas), não `My Company`.

336</Warning>368</Warning>

337 369 

338### Configurações de exemplo370<h3 id="example-configurations">

371 Configurações de exemplo

372</h3>

339 373 

340Defina essas variáveis de ambiente antes de executar `claude`. Cada bloco mostra uma configuração completa para um exportador diferente ou cenário de implantação:374Defina essas variáveis de ambiente antes de executar `claude`. Cada bloco mostra uma configuração completa para um exportador diferente ou cenário de implantação:

341 375 


382export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317416export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

383```417```

384 418 

385## Métricas e eventos disponíveis419<h2 id="available-metrics-and-events">

420 Métricas e eventos disponíveis

421</h2>

386 422 

387### Atributos padrão423<h3 id="standard-attributes">

424 Atributos padrão

425</h3>

388 426 

389Todas as métricas e eventos compartilham esses atributos padrão:427Todas as métricas e eventos compartilham esses atributos padrão:

390 428 

391| Atributo | Descrição | Controlado Por |429| Atributo | Descrição | Controlado Por |

392| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |430| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |

393| `session.id` | Identificador de sessão único | `OTEL_METRICS_INCLUDE_SESSION_ID` (padrão: true) |431| `session.id` | Identificador de sessão único | `OTEL_METRICS_INCLUDE_SESSION_ID` (padrão: true) |

394| `app.version` | Versão atual do Claude Code | `OTEL_METRICS_INCLUDE_VERSION` (padrão: false) |432| `app.version` | Versão atual do Claude Code | `OTEL_METRICS_INCLUDE_VERSION` (padrão: false) |

395| `app.entrypoint` | Como a sessão foi iniciada, como `cli`, `sdk-cli`, `sdk-ts`, `sdk-py` ou `claude-vscode` | `OTEL_METRICS_INCLUDE_ENTRYPOINT` (padrão: false) |433| `app.entrypoint` | Como a sessão foi iniciada, como `cli`, `sdk-cli`, `sdk-ts`, `sdk-py` ou `claude-vscode` | `OTEL_METRICS_INCLUDE_ENTRYPOINT` (padrão: false) |

396| `organization.id` | UUID da organização (quando autenticado) | Sempre incluído quando disponível |434| `organization.id` | UUID da organização (quando autenticado) | Sempre incluído quando disponível |

397| `user.account_uuid` | UUID da conta (quando autenticado) | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (padrão: true) |435| `user.account_uuid` | UUID da conta (quando autenticado) | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (padrão: true) |

398| `user.account_id` | ID da conta em formato marcado correspondendo às APIs de administrador Anthropic (quando autenticado), como `user_01BWBeN28...` | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (padrão: true) |436| `user.account_id` | ID da conta em formato marcado correspondendo às APIs de administrador Anthropic (quando autenticado), como `user_01BWBeN28...` | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (padrão: true) |

399| `user.id` | Identificador anônimo de dispositivo/instalação, gerado por instalação do Claude Code | Sempre incluído |437| `user.id` | Identificador anônimo aleatório gerado na primeira execução e persistido em `~/.claude.json`. Não contém informações pessoais e não é derivado da sua conta Claude. Deletar o arquivo produz um novo valor não relacionado na próxima execução. | Sempre incluído |

400| `user.email` | Endereço de email do usuário (quando autenticado via OAuth) | Sempre incluído quando disponível |438| `user.email` | Endereço de email do usuário (quando autenticado via OAuth) | Sempre incluído quando disponível |

401| `terminal.type` | Tipo de terminal, como `iTerm.app`, `vscode`, `cursor` ou `tmux` | Sempre incluído quando detectado |439| `terminal.type` | Tipo de terminal, como `iTerm.app`, `vscode`, `cursor` ou `tmux` | Sempre incluído quando detectado |

402| Chaves de `OTEL_RESOURCE_ATTRIBUTES` | Atributos personalizados que você define, como `department` ou `team.id`. Veja [Suporte a organização multi-equipe](#suporte-a-organização-multi-equipe) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` (padrão: true) |440| Chaves de `OTEL_RESOURCE_ATTRIBUTES` | Atributos personalizados que você define, como `department` ou `team.id`. Veja [Suporte a organização multi-equipe](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` (padrão: true) |

403 441 

404Os eventos incluem adicionalmente os seguintes atributos. Estes nunca são anexados a métricas porque causariam cardinalidade ilimitada:442Os eventos incluem adicionalmente os seguintes atributos. Estes nunca são anexados a métricas porque causariam cardinalidade ilimitada:

405 443 

406* `prompt.id`: UUID correlacionando um prompt do usuário com todos os eventos subsequentes até o próximo prompt. Veja [Atributos de correlação de evento](#atributos-de-correlação-de-evento).444* `prompt.id`: UUID correlacionando um prompt do usuário com todos os eventos subsequentes até o próximo prompt. Veja [Atributos de correlação de evento](#event-correlation-attributes).

407* `workspace.host_paths`: diretórios de workspace do host selecionados no aplicativo desktop, como um array de string445* `workspace.host_paths`: diretórios de workspace do host selecionados no aplicativo desktop, como um array de string

408 446 

409### Métricas447<h3 id="metrics">

448 Métricas

449</h3>

410 450 

411Claude Code exporta as seguintes métricas:451Claude Code exporta as seguintes métricas:

412 452 


421| `claude_code.code_edit_tool.decision` | Contagem de decisões de permissão da ferramenta de edição de código | count |461| `claude_code.code_edit_tool.decision` | Contagem de decisões de permissão da ferramenta de edição de código | count |

422| `claude_code.active_time.total` | Tempo ativo total em segundos | s |462| `claude_code.active_time.total` | Tempo ativo total em segundos | s |

423 463 

424### Detalhes das métricas464<h3 id="metric-details">

465 Detalhes das métricas

466</h3>

425 467 

426Cada métrica inclui os atributos padrão listados acima. Métricas com atributos adicionais específicos do contexto são observadas abaixo.468Cada métrica inclui os atributos padrão listados acima. Métricas com atributos adicionais específicos do contexto são observadas abaixo.

427 469 

428#### Contador de sessão470<h4 id="session-counter">

471 Contador de sessão

472</h4>

429 473 

430Incrementado no início de cada sessão.474Incrementado no início de cada sessão.

431 475 

432**Atributos**:476**Atributos**:

433 477 

434* Todos os [atributos padrão](#atributos-padrão)478* Todos os [atributos padrão](#standard-attributes)

435* `start_type`: Como a sessão foi iniciada. Um de `"fresh"`, `"resume"` ou `"continue"`479* `start_type`: Como a sessão foi iniciada. Um de `"fresh"`, `"resume"` ou `"continue"`

436 480 

437#### Contador de linhas de código481<h4 id="lines-of-code-counter">

482 Contador de linhas de código

483</h4>

438 484 

439Incrementado quando código é adicionado ou removido.485Incrementado quando código é adicionado ou removido.

440 486 

441**Atributos**:487**Atributos**:

442 488 

443* Todos os [atributos padrão](#atributos-padrão)489* Todos os [atributos padrão](#standard-attributes)

444* `type`: (`"added"`, `"removed"`)490* `type`: (`"added"`, `"removed"`)

491* `model`: Identificador do modelo para o modelo que fez a alteração (por exemplo, "claude-sonnet-4-6"). {/* min-version: 2.1.172 */}Requer Claude Code v2.1.172 ou posterior

445 492 

446#### Contador de pull request493<h4 id="pull-request-counter">

494 Contador de pull request

495</h4>

447 496 

448Incrementado quando Claude Code cria um pull request ou merge request através de um comando shell ou uma ferramenta MCP.497Incrementado quando Claude Code cria um pull request ou merge request através de um comando shell ou uma ferramenta MCP.

449 498 

450**Atributos**:499**Atributos**:

451 500 

452* Todos os [atributos padrão](#atributos-padrão)501* Todos os [atributos padrão](#standard-attributes)

453 502 

454#### Contador de commit503<h4 id="commit-counter">

504 Contador de commit

505</h4>

455 506 

456Incrementado ao criar commits git via Claude Code.507Incrementado ao criar commits git via Claude Code.

457 508 

458**Atributos**:509**Atributos**:

459 510 

460* Todos os [atributos padrão](#atributos-padrão)511* Todos os [atributos padrão](#standard-attributes)

461 512 

462#### Contador de custo513<h4 id="cost-counter">

514 Contador de custo

515</h4>

463 516 

464Incrementado após cada solicitação de API.517Incrementado após cada solicitação de API.

465 518 

466**Atributos**:519**Atributos**:

467 520 

468* Todos os [atributos padrão](#atributos-padrão)521* Todos os [atributos padrão](#standard-attributes)

469* `model`: Identificador do modelo (por exemplo, "claude-sonnet-4-6")522* `model`: Identificador do modelo (por exemplo, "claude-sonnet-4-6")

470* `query_source`: Categoria do subsistema que emitiu a solicitação. Um de `"main"`, `"subagent"` ou `"auxiliary"`523* `query_source`: Categoria do subsistema que emitiu a solicitação. Um de `"main"`, `"subagent"` ou `"auxiliary"`

471* `speed`: `"fast"` quando a solicitação usou modo rápido. Ausente caso contrário524* `speed`: `"fast"` quando a solicitação usou modo rápido. Ausente caso contrário


477* `mcp_server.name`: Servidor MCP cuja ferramenta foi executada na rodada que produziu esta solicitação. Nomes de servidor integrados, proxied por claude.ai e do registro oficial aparecem verbatim. Nomes de servidor configurados pelo usuário são substituídos por `"custom"`. Ausente quando nenhuma ferramenta MCP foi executada.530* `mcp_server.name`: Servidor MCP cuja ferramenta foi executada na rodada que produziu esta solicitação. Nomes de servidor integrados, proxied por claude.ai e do registro oficial aparecem verbatim. Nomes de servidor configurados pelo usuário são substituídos por `"custom"`. Ausente quando nenhuma ferramenta MCP foi executada.

478* `mcp_tool.name`: Ferramenta MCP que foi executada na rodada que produziu esta solicitação, com a mesma redação que `mcp_server.name`. Ausente quando nenhuma ferramenta MCP foi executada.531* `mcp_tool.name`: Ferramenta MCP que foi executada na rodada que produziu esta solicitação, com a mesma redação que `mcp_server.name`. Ausente quando nenhuma ferramenta MCP foi executada.

479 532 

480#### Contador de token533<h4 id="token-counter">

534 Contador de token

535</h4>

481 536 

482Incrementado após cada solicitação de API.537Incrementado após cada solicitação de API.

483 538 

484**Atributos**:539**Atributos**:

485 540 

486* Todos os [atributos padrão](#atributos-padrão)541* Todos os [atributos padrão](#standard-attributes)

487* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)542* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)

488* `model`: Identificador do modelo (por exemplo, "claude-sonnet-4-6")543* `model`: Identificador do modelo (por exemplo, "claude-sonnet-4-6")

489* `query_source`: Categoria do subsistema que emitiu a solicitação. Um de `"main"`, `"subagent"` ou `"auxiliary"`544* `query_source`: Categoria do subsistema que emitiu a solicitação. Um de `"main"`, `"subagent"` ou `"auxiliary"`

490* `speed`: `"fast"` quando a solicitação usou modo rápido. Ausente caso contrário545* `speed`: `"fast"` quando a solicitação usou modo rápido. Ausente caso contrário

491* `effort`: [Nível de esforço](/pt/model-config#adjust-effort-level) aplicado à solicitação. Veja [Contador de custo](#contador-de-custo) para detalhes.546* `effort`: [Nível de esforço](/pt/model-config#adjust-effort-level) aplicado à solicitação. Veja [Contador de custo](#cost-counter) para detalhes.

492* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja [Contador de custo](#contador-de-custo) para definições e comportamento de redação.547* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja [Contador de custo](#cost-counter) para definições e comportamento de redação.

493 548 

494#### Contador de decisão da ferramenta de edição de código549<h4 id="code-edit-tool-decision-counter">

550 Contador de decisão da ferramenta de edição de código

551</h4>

495 552 

496Incrementado quando o usuário aceita ou rejeita o uso da ferramenta Edit, Write ou NotebookEdit.553Incrementado quando o usuário aceita ou rejeita o uso da ferramenta Edit, Write ou NotebookEdit.

497 554 

498**Atributos**:555**Atributos**:

499 556 

500* Todos os [atributos padrão](#atributos-padrão)557* Todos os [atributos padrão](#standard-attributes)

501* `tool_name`: Nome da ferramenta (`"Edit"`, `"Write"`, `"NotebookEdit"`)558* `tool_name`: Nome da ferramenta (`"Edit"`, `"Write"`, `"NotebookEdit"`)

502* `decision`: Decisão do usuário (`"accept"`, `"reject"`)559* `decision`: Decisão do usuário (`"accept"`, `"reject"`)

503* `source`: Onde a decisão veio. Um de `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"` ou `"user_reject"`. Veja o [Evento de decisão da ferramenta](#evento-de-decisão-da-ferramenta) para o que cada valor significa.560* `source`: Onde a decisão veio. Um de `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"` ou `"user_reject"`. Veja o [Evento de decisão da ferramenta](#tool-decision-event) para o que cada valor significa.

504* `language`: Linguagem de programação do arquivo editado, como `"TypeScript"`, `"Python"`, `"JavaScript"` ou `"Markdown"`. Retorna `"unknown"` para extensões de arquivo não reconhecidas.561* `language`: Linguagem de programação do arquivo editado, como `"TypeScript"`, `"Python"`, `"JavaScript"` ou `"Markdown"`. Retorna `"unknown"` para extensões de arquivo não reconhecidas.

505 562 

506#### Contador de tempo ativo563<h4 id="active-time-counter">

564 Contador de tempo ativo

565</h4>

507 566 

508Rastreia o tempo real gasto usando ativamente Claude Code, excluindo tempo ocioso. Essa métrica é incrementada durante interações do usuário (digitação, leitura de respostas) e durante processamento CLI (execução de ferramentas, geração de resposta de IA).567Rastreia o tempo real gasto usando ativamente Claude Code, excluindo tempo ocioso. Essa métrica é incrementada durante interações do usuário (digitação, leitura de respostas) e durante processamento CLI (execução de ferramentas, geração de resposta de IA).

509 568 

510**Atributos**:569**Atributos**:

511 570 

512* Todos os [atributos padrão](#atributos-padrão)571* Todos os [atributos padrão](#standard-attributes)

513* `type`: `"user"` para interações de teclado, `"cli"` para execução de ferramentas e respostas de IA572* `type`: `"user"` para interações de teclado, `"cli"` para execução de ferramentas e respostas de IA

514 573 

515### Eventos574<h3 id="events">

575 Eventos

576</h3>

516 577 

517Claude Code exporta os seguintes eventos via logs/eventos OpenTelemetry (quando `OTEL_LOGS_EXPORTER` está configurado):578Claude Code exporta os seguintes eventos via logs/eventos OpenTelemetry (quando `OTEL_LOGS_EXPORTER` está configurado):

518 579 

519#### Atributos de correlação de evento580<h4 id="event-correlation-attributes">

581 Atributos de correlação de evento

582</h4>

520 583 

521Quando um usuário envia um prompt, Claude Code pode fazer múltiplas chamadas de API e executar várias ferramentas. O atributo `prompt.id` permite vincular todos esses eventos de volta ao único prompt que os acionou.584Quando um usuário envia um prompt, Claude Code pode fazer múltiplas chamadas de API e executar várias ferramentas. O atributo `prompt.id` permite vincular todos esses eventos de volta ao único prompt que os acionou.

522 585 


530 `prompt.id` é intencionalmente excluído de métricas porque cada prompt gera um ID único, o que criaria um número sempre crescente de séries temporais. Use-o apenas para análise em nível de evento e trilhas de auditoria.593 `prompt.id` é intencionalmente excluído de métricas porque cada prompt gera um ID único, o que criaria um número sempre crescente de séries temporais. Use-o apenas para análise em nível de evento e trilhas de auditoria.

531</Note>594</Note>

532 595 

533#### Evento de prompt do usuário596<h4 id="user-prompt-event">

597 Evento de prompt do usuário

598</h4>

534 599 

535Registrado quando um usuário envia um prompt.600Registrado quando um usuário envia um prompt.

536 601 


538 603 

539**Atributos**:604**Atributos**:

540 605 

541* Todos os [atributos padrão](#atributos-padrão)606* Todos os [atributos padrão](#standard-attributes)

542* `event.name`: `"user_prompt"`607* `event.name`: `"user_prompt"`

543* `event.timestamp`: Timestamp ISO 8601608* `event.timestamp`: Timestamp ISO 8601

544* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão609* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


547* `command_name`: Nome do comando quando o prompt invoca um. Nomes de comando integrados e agrupados como `compact` ou `debug` são emitidos como estão; aliases como `reset` emitem como digitados em vez do nome canônico. Nomes de comando customizado, plugin e MCP colapsam para `custom` ou `mcp` a menos que `OTEL_LOG_TOOL_DETAILS=1` esteja definido612* `command_name`: Nome do comando quando o prompt invoca um. Nomes de comando integrados e agrupados como `compact` ou `debug` são emitidos como estão; aliases como `reset` emitem como digitados em vez do nome canônico. Nomes de comando customizado, plugin e MCP colapsam para `custom` ou `mcp` a menos que `OTEL_LOG_TOOL_DETAILS=1` esteja definido

548* `command_source`: Origem do comando quando presente: `builtin`, `custom` ou `mcp`. Comandos fornecidos por plugin relatam como `custom`613* `command_source`: Origem do comando quando presente: `builtin`, `custom` ou `mcp`. Comandos fornecidos por plugin relatam como `custom`

549 614 

550#### Evento de resultado da ferramenta615<h4 id="tool-result-event">

616 Evento de resultado da ferramenta

617</h4>

551 618 

552Registrado quando uma ferramenta conclui a execução. Não é emitido se a chamada da ferramenta foi rejeitada; veja o [Evento de decisão da ferramenta](#evento-de-decisão-da-ferramenta) para rejeições.619Registrado quando uma ferramenta conclui a execução. Não é emitido se a chamada da ferramenta foi rejeitada; veja o [Evento de decisão da ferramenta](#tool-decision-event) para rejeições.

553 620 

554**Nome do Evento**: `claude_code.tool_result`621**Nome do Evento**: `claude_code.tool_result`

555 622 

556**Atributos**:623**Atributos**:

557 624 

558* Todos os [atributos padrão](#atributos-padrão)625* Todos os [atributos padrão](#standard-attributes)

559* `event.name`: `"tool_result"`626* `event.name`: `"tool_result"`

560* `event.timestamp`: Timestamp ISO 8601627* `event.timestamp`: Timestamp ISO 8601

561* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão628* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


566* `error_type`: String de categoria de erro quando a ferramenta falhou, como `"Error:ENOENT"` ou `"ShellError"`633* `error_type`: String de categoria de erro quando a ferramenta falhou, como `"Error:ENOENT"` ou `"ShellError"`

567* `error` (quando `OTEL_LOG_TOOL_DETAILS=1`): Mensagem de erro completa quando a ferramenta falhou634* `error` (quando `OTEL_LOG_TOOL_DETAILS=1`): Mensagem de erro completa quando a ferramenta falhou

568* `decision_type`: Sempre `"accept"`, já que este evento é emitido apenas após a ferramenta ser executada (chamadas rejeitadas não produzem um resultado de ferramenta)635* `decision_type`: Sempre `"accept"`, já que este evento é emitido apenas após a ferramenta ser executada (chamadas rejeitadas não produzem um resultado de ferramenta)

569* `decision_source`: Onde a decisão de permissão veio. Um de `"config"`, `"hook"`, `"user_permanent"` ou `"user_temporary"`. Veja o [Evento de decisão da ferramenta](#evento-de-decisão-da-ferramenta) para o que cada valor significa. As fontes apenas de rejeição `"user_abort"` e `"user_reject"` nunca aparecem neste evento.636* `decision_source`: Onde a decisão de permissão veio. Um de `"config"`, `"hook"`, `"user_permanent"` ou `"user_temporary"`. Veja o [Evento de decisão da ferramenta](#tool-decision-event) para o que cada valor significa. As fontes apenas de rejeição `"user_abort"` e `"user_reject"` nunca aparecem neste evento.

570* `tool_input_size_bytes`: Tamanho da entrada da ferramenta serializada em JSON em bytes637* `tool_input_size_bytes`: Tamanho da entrada da ferramenta serializada em JSON em bytes

571* `tool_result_size_bytes`: Tamanho do resultado da ferramenta em bytes638* `tool_result_size_bytes`: Tamanho do resultado da ferramenta em bytes

572* `mcp_server_scope`: Identificador de escopo do servidor MCP (para ferramentas MCP)639* `mcp_server_scope`: Identificador de escopo do servidor MCP (para ferramentas MCP)


578 * Para ferramenta Agent ou ferramenta Task legada: inclui `subagent_type`645 * Para ferramenta Agent ou ferramenta Task legada: inclui `subagent_type`

579* `tool_input` (quando `OTEL_LOG_TOOL_DETAILS=1`): Argumentos de ferramenta serializados em JSON. Valores individuais com mais de 512 caracteres são truncados, e a carga útil completa é limitada a \~4 K caracteres. Aplica-se a todas as ferramentas, incluindo ferramentas MCP.646* `tool_input` (quando `OTEL_LOG_TOOL_DETAILS=1`): Argumentos de ferramenta serializados em JSON. Valores individuais com mais de 512 caracteres são truncados, e a carga útil completa é limitada a \~4 K caracteres. Aplica-se a todas as ferramentas, incluindo ferramentas MCP.

580 647 

581#### Evento de solicitação de API648<h4 id="api-request-event">

649 Evento de solicitação de API

650</h4>

582 651 

583Registrado para cada solicitação de API para Claude.652Registrado para cada solicitação de API para Claude.

584 653 


586 655 

587**Atributos**:656**Atributos**:

588 657 

589* Todos os [atributos padrão](#atributos-padrão)658* Todos os [atributos padrão](#standard-attributes)

590* `event.name`: `"api_request"`659* `event.name`: `"api_request"`

591* `event.timestamp`: Timestamp ISO 8601660* `event.timestamp`: Timestamp ISO 8601

592* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão661* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


601* `speed`: `"fast"` ou `"normal"`, indicando se o modo rápido estava ativo670* `speed`: `"fast"` ou `"normal"`, indicando se o modo rápido estava ativo

602* `query_source`: Subsistema que emitiu a solicitação, como `"repl_main_thread"`, `"compact"` ou um nome de subagente671* `query_source`: Subsistema que emitiu a solicitação, como `"repl_main_thread"`, `"compact"` ou um nome de subagente

603* `effort`: [Nível de esforço](/pt/model-config#adjust-effort-level) aplicado à solicitação: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Ausente quando o modelo não suporta esforço.672* `effort`: [Nível de esforço](/pt/model-config#adjust-effort-level) aplicado à solicitação: `"low"`, `"medium"`, `"high"`, `"xhigh"` ou `"max"`. Ausente quando o modelo não suporta esforço.

604* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja [Contador de custo](#contador-de-custo) para definições e comportamento de redação.673* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja [Contador de custo](#cost-counter) para definições e comportamento de redação.

605 674 

606#### Evento de erro de API675<h4 id="api-error-event">

676 Evento de erro de API

677</h4>

607 678 

608Registrado quando uma solicitação de API para Claude falha.679Registrado quando uma solicitação de API para Claude falha.

609 680 


611 682 

612**Atributos**:683**Atributos**:

613 684 

614* Todos os [atributos padrão](#atributos-padrão)685* Todos os [atributos padrão](#standard-attributes)

615* `event.name`: `"api_error"`686* `event.name`: `"api_error"`

616* `event.timestamp`: Timestamp ISO 8601687* `event.timestamp`: Timestamp ISO 8601

617* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão688* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


624* `speed`: `"fast"` ou `"normal"`, indicando se o modo rápido estava ativo695* `speed`: `"fast"` ou `"normal"`, indicando se o modo rápido estava ativo

625* `query_source`: Subsistema que emitiu a solicitação, como `"repl_main_thread"`, `"compact"` ou um nome de subagente696* `query_source`: Subsistema que emitiu a solicitação, como `"repl_main_thread"`, `"compact"` ou um nome de subagente

626* `effort`: [Nível de esforço](/pt/model-config#adjust-effort-level) aplicado à solicitação. Ausente quando o modelo não suporta esforço.697* `effort`: [Nível de esforço](/pt/model-config#adjust-effort-level) aplicado à solicitação. Ausente quando o modelo não suporta esforço.

627* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja [Contador de custo](#contador-de-custo) para definições e comportamento de redação.698* `agent.name`, `skill.name`, `plugin.name`, `marketplace.name`, `mcp_server.name`, `mcp_tool.name`: Atribuição de skill, plugin, agente e MCP para a solicitação. Veja [Contador de custo](#cost-counter) para definições e comportamento de redação.

628 699 

629#### Evento de corpo de solicitação de API700<h4 id="api-refusal-event">

701 Evento de recusa de API

702</h4>

703 

704Registrado quando uma solicitação de API retorna `stop_reason: "refusal"`. Recusas chegam em um fluxo de resposta bem-sucedido em vez de como um erro HTTP, então o evento `api_error` não dispara para elas. Este evento permite rastrear a frequência de recusa.

705 

706**Nome do Evento**: `claude_code.api_refusal`

707 

708**Atributos**:

709 

710* Todos os [atributos padrão](#standard-attributes)

711* `event.name`: `"api_refusal"`

712* `event.timestamp`: Timestamp ISO 8601

713* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão

714* `model`: Identificador do modelo da solicitação

715* `request_id`: ID de solicitação da API Anthropic do cabeçalho `request-id` da resposta, como `"req_011..."`. Presente apenas quando a API retorna um.

716 

717<h4 id="api-request-body-event">

718 Evento de corpo de solicitação de API

719</h4>

630 720 

631Registrado para cada tentativa de solicitação de API quando `OTEL_LOG_RAW_API_BODIES` está definido. Um evento é emitido por tentativa, então tentativas com parâmetros ajustados cada uma produzem seu próprio evento.721Registrado para cada tentativa de solicitação de API quando `OTEL_LOG_RAW_API_BODIES` está definido. Um evento é emitido por tentativa, então tentativas com parâmetros ajustados cada uma produzem seu próprio evento.

632 722 


634 724 

635**Atributos**:725**Atributos**:

636 726 

637* Todos os [atributos padrão](#atributos-padrão)727* Todos os [atributos padrão](#standard-attributes)

638* `event.name`: `"api_request_body"`728* `event.name`: `"api_request_body"`

639* `event.timestamp`: Timestamp ISO 8601729* `event.timestamp`: Timestamp ISO 8601

640* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão730* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


645* `model`: Identificador do modelo dos parâmetros de solicitação735* `model`: Identificador do modelo dos parâmetros de solicitação

646* `query_source`: Subsistema que emitiu a solicitação (por exemplo, `"compact"`)736* `query_source`: Subsistema que emitiu a solicitação (por exemplo, `"compact"`)

647 737 

648#### Evento de corpo de resposta de API738<h4 id="api-response-body-event">

739 Evento de corpo de resposta de API

740</h4>

649 741 

650Registrado para cada resposta de API bem-sucedida quando `OTEL_LOG_RAW_API_BODIES` está definido.742Registrado para cada resposta de API bem-sucedida quando `OTEL_LOG_RAW_API_BODIES` está definido.

651 743 


653 745 

654**Atributos**:746**Atributos**:

655 747 

656* Todos os [atributos padrão](#atributos-padrão)748* Todos os [atributos padrão](#standard-attributes)

657* `event.name`: `"api_response_body"`749* `event.name`: `"api_response_body"`

658* `event.timestamp`: Timestamp ISO 8601750* `event.timestamp`: Timestamp ISO 8601

659* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão751* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


665* `query_source`: Subsistema que emitiu a solicitação757* `query_source`: Subsistema que emitiu a solicitação

666* `request_id`: ID de solicitação da API Anthropic do cabeçalho `request-id` da resposta, como `"req_011..."`. Presente apenas quando a API retorna um.758* `request_id`: ID de solicitação da API Anthropic do cabeçalho `request-id` da resposta, como `"req_011..."`. Presente apenas quando a API retorna um.

667 759 

668#### Evento de decisão da ferramenta760<h4 id="tool-decision-event">

761 Evento de decisão da ferramenta

762</h4>

669 763 

670Registrado quando uma decisão de permissão da ferramenta é feita (aceitar/rejeitar).764Registrado quando uma decisão de permissão da ferramenta é feita (aceitar/rejeitar).

671 765 


673 767 

674**Atributos**:768**Atributos**:

675 769 

676* Todos os [atributos padrão](#atributos-padrão)770* Todos os [atributos padrão](#standard-attributes)

677* `event.name`: `"tool_decision"`771* `event.name`: `"tool_decision"`

678* `event.timestamp`: Timestamp ISO 8601772* `event.timestamp`: Timestamp ISO 8601

679* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão773* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


687 * `"user_temporary"`: Emitido quando o usuário escolheu "Sim" em um aviso de permissão para uma aprovação única, ou escolheu uma das opções "... durante esta sessão" em um aviso de edição ou leitura de arquivo. Na CLI interativa isso é emitido apenas para a escolha em si; chamadas posteriores permitidas por essa concessão com escopo de sessão emitem `"config"` em vez disso. No Agent SDK ou sessões não-interativas `-p`, tanto a escolha quanto correspondências posteriores emitem `"user_temporary"`. Tratado como uma aceitação.781 * `"user_temporary"`: Emitido quando o usuário escolheu "Sim" em um aviso de permissão para uma aprovação única, ou escolheu uma das opções "... durante esta sessão" em um aviso de edição ou leitura de arquivo. Na CLI interativa isso é emitido apenas para a escolha em si; chamadas posteriores permitidas por essa concessão com escopo de sessão emitem `"config"` em vez disso. No Agent SDK ou sessões não-interativas `-p`, tanto a escolha quanto correspondências posteriores emitem `"user_temporary"`. Tratado como uma aceitação.

688 * `"user_abort"`: Emitido quando o usuário descartou o aviso de permissão sem responder. Tratado como uma rejeição.782 * `"user_abort"`: Emitido quando o usuário descartou o aviso de permissão sem responder. Tratado como uma rejeição.

689 * `"user_reject"`: Emitido quando o usuário escolheu "Não" quando solicitado. Na CLI interativa isso é emitido apenas para essa escolha em si; chamadas que correspondem a uma regra de negação nas configurações pessoais do usuário emitem `"config"` em vez disso. No Agent SDK ou sessões não-interativas `-p`, chamadas que correspondem a uma regra de negação em configurações pessoais emitem `"user_reject"`. Tratado como uma rejeição.783 * `"user_reject"`: Emitido quando o usuário escolheu "Não" quando solicitado. Na CLI interativa isso é emitido apenas para essa escolha em si; chamadas que correspondem a uma regra de negação nas configurações pessoais do usuário emitem `"config"` em vez disso. No Agent SDK ou sessões não-interativas `-p`, chamadas que correspondem a uma regra de negação em configurações pessoais emitem `"user_reject"`. Tratado como uma rejeição.

690* `tool_parameters` (quando `OTEL_LOG_TOOL_DETAILS=1`): String JSON contendo parâmetros específicos da ferramenta. Mesma forma que o [Evento de resultado da ferramenta](#evento-de-resultado-da-ferramenta), menos campos pós-execução como `git_commit_id`. Os valores podem diferir de `tool_result` para uma chamada aceita se a decisão de permissão reescrever a entrada da ferramenta via `updatedInput`. Use este atributo para ver qual comando foi rejeitado quando `decision` é `"reject"`.784* `tool_parameters` (quando `OTEL_LOG_TOOL_DETAILS=1`): String JSON contendo parâmetros específicos da ferramenta. Mesma forma que o [Evento de resultado da ferramenta](#tool-result-event), menos campos pós-execução como `git_commit_id`. Os valores podem diferir de `tool_result` para uma chamada aceita se a decisão de permissão reescrever a entrada da ferramenta via `updatedInput`. Use este atributo para ver qual comando foi rejeitado quando `decision` é `"reject"`.

691 * Para ferramenta Bash: inclui `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`785 * Para ferramenta Bash: inclui `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`

692 * Para ferramenta WorkspaceBash: inclui `bash_command`, `full_command`, `timeout`786 * Para ferramenta WorkspaceBash: inclui `bash_command`, `full_command`, `timeout`

693 * Para ferramentas MCP: inclui `mcp_server_name`, `mcp_tool_name`787 * Para ferramentas MCP: inclui `mcp_server_name`, `mcp_tool_name`

694 * Para ferramenta Skill: inclui `skill_name`788 * Para ferramenta Skill: inclui `skill_name`

695 * Para ferramenta Agent ou ferramenta Task legada: inclui `subagent_type`789 * Para ferramenta Agent ou ferramenta Task legada: inclui `subagent_type`

696 790 

697#### Evento de modo de permissão alterado791<h4 id="permission-mode-changed-event">

792 Evento de modo de permissão alterado

793</h4>

698 794 

699Registrado quando o modo de permissão muda, por exemplo de ciclagem Shift+Tab, saída do Plan Mode ou verificação de gate de modo automático.795Registrado quando o modo de permissão muda, por exemplo de ciclagem Shift+Tab, saída do Plan Mode ou verificação de gate de modo automático.

700 796 


702 798 

703**Atributos**:799**Atributos**:

704 800 

705* Todos os [atributos padrão](#atributos-padrão)801* Todos os [atributos padrão](#standard-attributes)

706* `event.name`: `"permission_mode_changed"`802* `event.name`: `"permission_mode_changed"`

707* `event.timestamp`: Timestamp ISO 8601803* `event.timestamp`: Timestamp ISO 8601

708* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão804* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


710* `to_mode`: O novo modo de permissão806* `to_mode`: O novo modo de permissão

711* `trigger`: O que causou a mudança. Um de `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"` ou `"auto_opt_in"`. Ausente quando a transição se origina do SDK ou bridge807* `trigger`: O que causou a mudança. Um de `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"` ou `"auto_opt_in"`. Ausente quando a transição se origina do SDK ou bridge

712 808 

713#### Evento de autenticação809<h4 id="auth-event">

810 Evento de autenticação

811</h4>

714 812 

715Registrado quando `/login` ou `/logout` é concluído.813Registrado quando `/login` ou `/logout` é concluído.

716 814 


718 816 

719**Atributos**:817**Atributos**:

720 818 

721* Todos os [atributos padrão](#atributos-padrão)819* Todos os [atributos padrão](#standard-attributes)

722* `event.name`: `"auth"`820* `event.name`: `"auth"`

723* `event.timestamp`: Timestamp ISO 8601821* `event.timestamp`: Timestamp ISO 8601

724* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão822* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


728* `error_category`: Tipo de erro categórico quando a ação falhou. A mensagem de erro bruta nunca é incluída826* `error_category`: Tipo de erro categórico quando a ação falhou. A mensagem de erro bruta nunca é incluída

729* `status_code`: Código de status HTTP como string quando a ação falhou com um erro HTTP827* `status_code`: Código de status HTTP como string quando a ação falhou com um erro HTTP

730 828 

731#### Evento de conexão do servidor MCP829<h4 id="mcp-server-connection-event">

830 Evento de conexão do servidor MCP

831</h4>

732 832 

733Registrado quando um servidor MCP se conecta, desconecta ou falha ao conectar.833Registrado quando um servidor MCP se conecta, desconecta ou falha ao conectar.

734 834 


736 836 

737**Atributos**:837**Atributos**:

738 838 

739* Todos os [atributos padrão](#atributos-padrão)839* Todos os [atributos padrão](#standard-attributes)

740* `event.name`: `"mcp_server_connection"`840* `event.name`: `"mcp_server_connection"`

741* `event.timestamp`: Timestamp ISO 8601841* `event.timestamp`: Timestamp ISO 8601

742* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão842* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


745* `server_scope`: Escopo em que o servidor está configurado, como `"user"`, `"project"` ou `"local"`845* `server_scope`: Escopo em que o servidor está configurado, como `"user"`, `"project"` ou `"local"`

746* `duration_ms`: Duração da tentativa de conexão em milissegundos846* `duration_ms`: Duração da tentativa de conexão em milissegundos

747* `error_code`: Código de erro quando a conexão falhou847* `error_code`: Código de erro quando a conexão falhou

848* `is_plugin`: `true` quando o servidor é fornecido por um plugin, `false` caso contrário

849* `plugin_id_hash` (quando `is_plugin` é `true`): Hash estável do nome do plugin e marketplace, para agrupar eventos por plugin sem expor o nome

850* `plugin.name` (quando `is_plugin` é `true`): Nome do plugin que fornece o servidor. Para plugins de terceiros isso é a string literal `"third-party"` a menos que `OTEL_LOG_TOOL_DETAILS=1`; isso protege nomes de plugins de terceiros de aparecerem em logs por padrão. Plugins de fontes oficiais Anthropic são sempre identificados por nome. Os atributos `plugin_id_hash` e `plugin.name` fluem para seu próprio backend de monitoramento e não são enviados para Anthropic

748* `server_name` (quando `OTEL_LOG_TOOL_DETAILS=1`): Nome do servidor configurado851* `server_name` (quando `OTEL_LOG_TOOL_DETAILS=1`): Nome do servidor configurado

749* `error` (quando `OTEL_LOG_TOOL_DETAILS=1`): Mensagem de erro completa quando a conexão falhou852* `error` (quando `OTEL_LOG_TOOL_DETAILS=1`): Mensagem de erro completa quando a conexão falhou

750 853 

751#### Evento de erro interno854<h4 id="internal-error-event">

855 Evento de erro interno

856</h4>

752 857 

753Registrado quando Claude Code captura um erro interno inesperado. Apenas o nome da classe de erro e um código estilo errno são registrados. A mensagem de erro e rastreamento de pilha nunca são incluídos. Este evento não é emitido ao executar contra Bedrock, Vertex ou Foundry, ou quando `DISABLE_ERROR_REPORTING` está definido.858Registrado quando Claude Code captura um erro interno inesperado. Apenas o nome da classe de erro e um código estilo errno são registrados. A mensagem de erro e rastreamento de pilha nunca são incluídos. Este evento não é emitido ao executar contra Bedrock, Vertex ou Foundry, ou quando `DISABLE_ERROR_REPORTING` está definido.

754 859 


756 861 

757**Atributos**:862**Atributos**:

758 863 

759* Todos os [atributos padrão](#atributos-padrão)864* Todos os [atributos padrão](#standard-attributes)

760* `event.name`: `"internal_error"`865* `event.name`: `"internal_error"`

761* `event.timestamp`: Timestamp ISO 8601866* `event.timestamp`: Timestamp ISO 8601

762* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão867* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão

763* `error_name`: Nome da classe de erro, como `"TypeError"` ou `"SyntaxError"`868* `error_name`: Nome da classe de erro, como `"TypeError"` ou `"SyntaxError"`

764* `error_code`: Código errno Node.js como `"ENOENT"` quando presente no erro869* `error_code`: Código errno Node.js como `"ENOENT"` quando presente no erro

765 870 

766#### Evento de plugin instalado871<h4 id="plugin-installed-event">

872 Evento de plugin instalado

873</h4>

767 874 

768Registrado quando um plugin termina de instalar, tanto do comando CLI `claude plugin install` quanto da UI interativa `/plugin`.875Registrado quando um plugin termina de instalar, tanto do comando CLI `claude plugin install` quanto da UI interativa `/plugin`.

769 876 


771 878 

772**Atributos**:879**Atributos**:

773 880 

774* Todos os [atributos padrão](#atributos-padrão)881* Todos os [atributos padrão](#standard-attributes)

775* `event.name`: `"plugin_installed"`882* `event.name`: `"plugin_installed"`

776* `event.timestamp`: Timestamp ISO 8601883* `event.timestamp`: Timestamp ISO 8601

777* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão884* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


781* `plugin.version`: Versão do plugin quando declarada na entrada do marketplace. Para marketplaces de terceiros isso é incluído apenas quando `OTEL_LOG_TOOL_DETAILS=1`888* `plugin.version`: Versão do plugin quando declarada na entrada do marketplace. Para marketplaces de terceiros isso é incluído apenas quando `OTEL_LOG_TOOL_DETAILS=1`

782* `marketplace.name`: Marketplace do qual o plugin foi instalado. Para marketplaces de terceiros isso é incluído apenas quando `OTEL_LOG_TOOL_DETAILS=1`889* `marketplace.name`: Marketplace do qual o plugin foi instalado. Para marketplaces de terceiros isso é incluído apenas quando `OTEL_LOG_TOOL_DETAILS=1`

783 890 

784#### Evento de plugin carregado891<h4 id="plugin-loaded-event">

892 Evento de plugin carregado

893</h4>

785 894 

786Registrado uma vez por plugin ativado no início da sessão. Use este evento para inventariar quais plugins estão ativos em toda a sua frota, como complemento ao `plugin_installed` que registra a ação de instalação em si.895Registrado uma vez por plugin ativado no início da sessão. Use este evento para inventariar quais plugins estão ativos em toda a sua frota, como complemento ao `plugin_installed` que registra a ação de instalação em si.

787 896 


789 898 

790**Atributos**:899**Atributos**:

791 900 

792* Todos os [atributos padrão](#atributos-padrão)901* Todos os [atributos padrão](#standard-attributes)

793* `event.name`: `"plugin_loaded"`902* `event.name`: `"plugin_loaded"`

794* `event.timestamp`: Timestamp ISO 8601903* `event.timestamp`: Timestamp ISO 8601

795* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão904* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


801* `plugin_id_hash`: hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar quantos plugins de terceiros distintos são carregados em toda a sua frota sem registrar seus nomes910* `plugin_id_hash`: hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar quantos plugins de terceiros distintos são carregados em toda a sua frota sem registrar seus nomes

802* `has_hooks`: se o plugin contribui hooks911* `has_hooks`: se o plugin contribui hooks

803* `has_mcp`: se o plugin contribui servidores MCP912* `has_mcp`: se o plugin contribui servidores MCP

913* `host_owned_mcp`: `true` quando o host SDK gerencia as conexões MCP deste plugin e Claude Code pulou a leitura da configuração do servidor MCP do plugin, `false` caso contrário. {/* min-version: 2.1.172 */}Requer Claude Code v2.1.172 ou posterior

804* `skill_path_count`: número de diretórios de skill que o plugin declara914* `skill_path_count`: número de diretórios de skill que o plugin declara

805* `command_path_count`: número de diretórios de comando que o plugin declara915* `command_path_count`: número de diretórios de comando que o plugin declara

806* `agent_path_count`: número de diretórios de agente que o plugin declara916* `agent_path_count`: número de diretórios de agente que o plugin declara

917* `safe_mode`: `"true"` quando a sessão foi iniciada com [`--safe-mode`](/pt/cli-reference), `"false"` caso contrário. Em modo seguro este evento relata apenas inventário configurado; os comandos, skills, hooks e servidores MCP do plugin não carregam. {/* min-version: 2.1.169 */}Requer Claude Code v2.1.169 ou posterior

807 918 

808#### Evento de skill ativado919<h4 id="skill-activated-event">

920 Evento de skill ativado

921</h4>

809 922 

810Registrado quando uma skill é invocada, seja Claude a chama através da ferramenta Skill ou você a executa como um comando `/`.923Registrado quando uma skill é invocada, seja Claude a chama através da ferramenta Skill ou você a executa como um comando `/`.

811 924 


813 926 

814**Atributos**:927**Atributos**:

815 928 

816* Todos os [atributos padrão](#atributos-padrão)929* Todos os [atributos padrão](#standard-attributes)

817* `event.name`: `"skill_activated"`930* `event.name`: `"skill_activated"`

818* `event.timestamp`: Timestamp ISO 8601931* `event.timestamp`: Timestamp ISO 8601

819* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão932* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão

820* `skill.name`: Nome da skill. Para skills definidas pelo usuário e de plugin de terceiros o valor é o placeholder `"custom_skill"` a menos que `OTEL_LOG_TOOL_DETAILS=1`933* `skill.name`: Nome da skill. Para skills definidas pelo usuário e de plugin de terceiros o valor é o placeholder `"custom_skill"` a menos que `OTEL_LOG_TOOL_DETAILS=1`

821* `invocation_trigger`: Como a skill foi acionada (`"user-slash"`, `"claude-proactive"` ou `"nested-skill"`)934* `invocation_trigger`: Como a skill foi acionada (`"user-slash"`, `"claude-proactive"` ou `"nested-skill"`)

822* `skill.source`: De onde a skill foi carregada (por exemplo, `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)935* `skill.source`: De onde a skill foi carregada (por exemplo, `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)

936* `skill.kind`: `"workflow"` quando a skill é uma skill de workflow. Ausente caso contrário

823* `plugin.name` (quando `OTEL_LOG_TOOL_DETAILS=1` ou o plugin é de um marketplace oficial): Nome do plugin proprietário quando a skill é fornecida por um plugin937* `plugin.name` (quando `OTEL_LOG_TOOL_DETAILS=1` ou o plugin é de um marketplace oficial): Nome do plugin proprietário quando a skill é fornecida por um plugin

824* `marketplace.name` (quando `OTEL_LOG_TOOL_DETAILS=1` ou o plugin é de um marketplace oficial): Marketplace do qual o plugin proprietário foi instalado, quando a skill é fornecida por um plugin938* `marketplace.name` (quando `OTEL_LOG_TOOL_DETAILS=1` ou o plugin é de um marketplace oficial): Marketplace do qual o plugin proprietário foi instalado, quando a skill é fornecida por um plugin

825 939 

826#### Evento de menção @940<h4 id="at-mention-event">

941 Evento de menção @

942</h4>

827 943 

828Registrado quando Claude Code resolve uma menção `@` em um prompt. Nem toda menção emite um evento: caminhos de saída antecipada, como negações de permissão, arquivos superdimensionados, anexos de referência PDF e falhas de listagem de diretório retornam sem registrar.944Registrado quando Claude Code resolve uma menção `@` em um prompt. Nem toda menção emite um evento: caminhos de saída antecipada, como negações de permissão, arquivos superdimensionados, anexos de referência PDF e falhas de listagem de diretório retornam sem registrar.

829 945 


831 947 

832**Atributos**:948**Atributos**:

833 949 

834* Todos os [atributos padrão](#atributos-padrão)950* Todos os [atributos padrão](#standard-attributes)

835* `event.name`: `"at_mention"`951* `event.name`: `"at_mention"`

836* `event.timestamp`: Timestamp ISO 8601952* `event.timestamp`: Timestamp ISO 8601

837* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão953* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão

838* `mention_type`: Tipo de menção (`"file"`, `"directory"`, `"agent"`, `"mcp_resource"`)954* `mention_type`: Tipo de menção (`"file"`, `"directory"`, `"agent"`, `"mcp_resource"`)

839* `success`: Se a menção foi resolvida com sucesso (`"true"` ou `"false"`)955* `success`: Se a menção foi resolvida com sucesso (`"true"` ou `"false"`)

840 956 

841#### Evento de tentativas de API esgotadas957<h4 id="api-retries-exhausted-event">

958 Evento de tentativas de API esgotadas

959</h4>

842 960 

843Registrado uma vez quando uma solicitação de API falha após mais de uma tentativa. Emitido junto com o evento `api_error` final.961Registrado uma vez quando uma solicitação de API falha após mais de uma tentativa. Emitido junto com o evento `api_error` final.

844 962 


846 964 

847**Atributos**:965**Atributos**:

848 966 

849* Todos os [atributos padrão](#atributos-padrão)967* Todos os [atributos padrão](#standard-attributes)

850* `event.name`: `"api_retries_exhausted"`968* `event.name`: `"api_retries_exhausted"`

851* `event.timestamp`: Timestamp ISO 8601969* `event.timestamp`: Timestamp ISO 8601

852* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão970* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


857* `total_retry_duration_ms`: Tempo total de parede em todas as tentativas975* `total_retry_duration_ms`: Tempo total de parede em todas as tentativas

858* `speed`: `"fast"` ou `"normal"`976* `speed`: `"fast"` ou `"normal"`

859 977 

860#### Evento de hook registrado978<h4 id="hook-registered-event">

979 Evento de hook registrado

980</h4>

861 981 

862Registrado uma vez por hook configurado no início da sessão. Use este evento para inventariar quais hooks estão ativos em toda a sua frota, como complemento aos eventos `hook_execution_start` e `hook_execution_complete` por execução.982Registrado uma vez por hook configurado no início da sessão. Use este evento para inventariar quais hooks estão ativos em toda a sua frota, como complemento aos eventos `hook_execution_start` e `hook_execution_complete` por execução.

863 983 


865 985 

866**Atributos**:986**Atributos**:

867 987 

868* Todos os [atributos padrão](#atributos-padrão)988* Todos os [atributos padrão](#standard-attributes)

869* `event.name`: `"hook_registered"`989* `event.name`: `"hook_registered"`

870* `event.timestamp`: Timestamp ISO 8601990* `event.timestamp`: Timestamp ISO 8601

871* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão991* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão

872* `hook_event`: tipo de evento de hook, como `"PreToolUse"` ou `"PostToolUse"`992* `hook_event`: tipo de evento de hook, como `"PreToolUse"` ou `"PostToolUse"`

873* `hook_type`: tipo de implementação de hook: `"command"`, `"prompt"`, `"mcp_tool"`, `"http"` ou `"agent"`993* `hook_type`: tipo de implementação de hook: `"command"`, `"prompt"`, `"mcp_tool"`, `"http"` ou `"agent"`

874* `hook_source`: onde o hook é definido: `"userSettings"`, `"projectSettings"`, `"localSettings"`, `"flagSettings"`, `"policySettings"` ou `"pluginHook"`994* `hook_source`: onde o hook é definido: `"userSettings"`, `"projectSettings"`, `"localSettings"`, `"flagSettings"`, `"policySettings"` ou `"pluginHook"`

995* `safe_mode`: `"true"` quando a sessão foi iniciada com [`--safe-mode`](/pt/cli-reference), `"false"` caso contrário. {/* min-version: 2.1.169 */}Requer Claude Code v2.1.169 ou posterior

875* `hook_matcher` (quando `OTEL_LOG_TOOL_DETAILS=1`): a string matcher da configuração do hook, quando uma está definida996* `hook_matcher` (quando `OTEL_LOG_TOOL_DETAILS=1`): a string matcher da configuração do hook, quando uma está definida

876* `plugin.name` (quando `hook_source` é `"pluginHook"`): nome do plugin contribuidor. Para plugins fora do marketplace oficial e pacote integrado o valor é `"third-party"` a menos que `OTEL_LOG_TOOL_DETAILS=1`997* `plugin.name` (quando `hook_source` é `"pluginHook"`): nome do plugin contribuidor. Para plugins fora do marketplace oficial e pacote integrado o valor é `"third-party"` a menos que `OTEL_LOG_TOOL_DETAILS=1`

877* `plugin_id_hash` (quando `hook_source` é `"pluginHook"`): hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar plugins contribuidores distintos sem registrar seus nomes998* `plugin_id_hash` (quando `hook_source` é `"pluginHook"`): hash determinístico do nome do plugin e marketplace, enviado apenas para seu exportador configurado. Permite contar plugins contribuidores distintos sem registrar seus nomes

878 999 

879#### Evento de início de execução de hook1000<h4 id="hook-execution-start-event">

1001 Evento de início de execução de hook

1002</h4>

880 1003 

881Registrado quando um ou mais hooks começam a executar para um evento de hook.1004Registrado quando um ou mais hooks começam a executar para um evento de hook.

882 1005 


884 1007 

885**Atributos**:1008**Atributos**:

886 1009 

887* Todos os [atributos padrão](#atributos-padrão)1010* Todos os [atributos padrão](#standard-attributes)

888* `event.name`: `"hook_execution_start"`1011* `event.name`: `"hook_execution_start"`

889* `event.timestamp`: Timestamp ISO 86011012* `event.timestamp`: Timestamp ISO 8601

890* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão1013* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


893* `num_hooks`: Número de comandos de hook correspondentes1016* `num_hooks`: Número de comandos de hook correspondentes

894* `managed_only`: `"true"` quando apenas hooks de política gerenciada são permitidos1017* `managed_only`: `"true"` quando apenas hooks de política gerenciada são permitidos

895* `hook_source`: `"policySettings"` ou `"merged"`1018* `hook_source`: `"policySettings"` ou `"merged"`

1019* `safe_mode`: `"true"` quando a sessão foi iniciada com [`--safe-mode`](/pt/cli-reference), `"false"` caso contrário. {/* min-version: 2.1.169 */}Requer Claude Code v2.1.169 ou posterior

896* `hook_definitions`: Configuração de hook serializada em JSON. Incluído apenas quando rastreamento beta detalhado e `OTEL_LOG_TOOL_DETAILS=1` estão ambos ativados1020* `hook_definitions`: Configuração de hook serializada em JSON. Incluído apenas quando rastreamento beta detalhado e `OTEL_LOG_TOOL_DETAILS=1` estão ambos ativados

897 1021 

898#### Evento de conclusão de execução de hook1022<h4 id="hook-execution-complete-event">

1023 Evento de conclusão de execução de hook

1024</h4>

899 1025 

900Registrado quando todos os hooks para um evento de hook terminaram.1026Registrado quando todos os hooks para um evento de hook terminaram.

901 1027 


903 1029 

904**Atributos**:1030**Atributos**:

905 1031 

906* Todos os [atributos padrão](#atributos-padrão)1032* Todos os [atributos padrão](#standard-attributes)

907* `event.name`: `"hook_execution_complete"`1033* `event.name`: `"hook_execution_complete"`

908* `event.timestamp`: Timestamp ISO 86011034* `event.timestamp`: Timestamp ISO 8601

909* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão1035* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


917* `total_duration_ms`: Duração de parede de todos os hooks correspondentes1043* `total_duration_ms`: Duração de parede de todos os hooks correspondentes

918* `managed_only`: `"true"` quando apenas hooks de política gerenciada são permitidos1044* `managed_only`: `"true"` quando apenas hooks de política gerenciada são permitidos

919* `hook_source`: `"policySettings"` ou `"merged"`1045* `hook_source`: `"policySettings"` ou `"merged"`

1046* `safe_mode`: `"true"` quando a sessão foi iniciada com [`--safe-mode`](/pt/cli-reference), `"false"` caso contrário. {/* min-version: 2.1.169 */}Requer Claude Code v2.1.169 ou posterior

920* `hook_definitions`: Configuração de hook serializada em JSON. Incluído apenas quando rastreamento beta detalhado e `OTEL_LOG_TOOL_DETAILS=1` estão ambos ativados1047* `hook_definitions`: Configuração de hook serializada em JSON. Incluído apenas quando rastreamento beta detalhado e `OTEL_LOG_TOOL_DETAILS=1` estão ambos ativados

921 1048 

922#### Evento de métricas de plugin de hook1049<h4 id="hook-plugin-metrics-event">

1050 Evento de métricas de plugin de hook

1051</h4>

923 1052 

924Registrado quando um hook de plugin do marketplace oficial emite métricas por invocação. Apenas plugins instalados de um marketplace oficial Anthropic podem emitir esses dados. Plugins de marketplace de terceiros e hooks configurados pelo usuário não emitem para este evento. Use este evento para monitorar o comportamento do plugin, como taxas de descoberta, custos e durações de sua própria pilha de observabilidade.1053Registrado quando um hook de plugin do marketplace oficial emite métricas por invocação. Apenas plugins instalados de um marketplace oficial Anthropic podem emitir esses dados. Plugins de marketplace de terceiros e hooks configurados pelo usuário não emitem para este evento. Use este evento para monitorar o comportamento do plugin, como taxas de descoberta, custos e durações de sua própria pilha de observabilidade.

925 1054 


927 1056 

928**Atributos**:1057**Atributos**:

929 1058 

930* Todos os [atributos padrão](#atributos-padrão)1059* Todos os [atributos padrão](#standard-attributes)

931* `event.name`: `"hook_plugin_metrics"`1060* `event.name`: `"hook_plugin_metrics"`

932* `event.timestamp`: Timestamp ISO 86011061* `event.timestamp`: Timestamp ISO 8601

933* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão1062* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


935* `hook_event`: tipo de evento de hook que emitiu as métricas1064* `hook_event`: tipo de evento de hook que emitiu as métricas

936* Até 20 chaves de métrica emitidas pelo plugin. Os nomes correspondem a `^[a-z][a-z0-9_]{0,39}$`. Os valores são booleanos ou números.1065* Até 20 chaves de métrica emitidas pelo plugin. Os nomes correspondem a `^[a-z][a-z0-9_]{0,39}$`. Os valores são booleanos ou números.

937 1066 

938#### Evento de compactação1067<h4 id="compaction-event">

1068 Evento de compactação

1069</h4>

939 1070 

940Registrado quando a compactação de conversa é concluída.1071Registrado quando a compactação de conversa é concluída.

941 1072 


943 1074 

944**Atributos**:1075**Atributos**:

945 1076 

946* Todos os [atributos padrão](#atributos-padrão)1077* Todos os [atributos padrão](#standard-attributes)

947* `event.name`: `"compaction"`1078* `event.name`: `"compaction"`

948* `event.timestamp`: Timestamp ISO 86011079* `event.timestamp`: Timestamp ISO 8601

949* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão1080* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


955* `error`: Mensagem de erro quando a compactação falhou1086* `error`: Mensagem de erro quando a compactação falhou

956* `precompute_reuse`: Definido apenas quando `trigger` é `"manual"`. A compactação automática pode preparar um resumo em segundo plano antes da janela de contexto se encher, e este atributo registra se `/compact` reutilizou esse resumo preparado. `"hit"` significa que foi reutilizado; `"miss_custom_instructions"`, `"miss_hook"` e `"miss_not_ready"` dão a razão pela qual um resumo fresco foi computado em vez disso. {/* min-version: 2.1.153 */}Requer Claude Code v2.1.153 ou posterior1087* `precompute_reuse`: Definido apenas quando `trigger` é `"manual"`. A compactação automática pode preparar um resumo em segundo plano antes da janela de contexto se encher, e este atributo registra se `/compact` reutilizou esse resumo preparado. `"hit"` significa que foi reutilizado; `"miss_custom_instructions"`, `"miss_hook"` e `"miss_not_ready"` dão a razão pela qual um resumo fresco foi computado em vez disso. {/* min-version: 2.1.153 */}Requer Claude Code v2.1.153 ou posterior

957 1088 

958#### Evento de pesquisa de feedback1089<h4 id="feedback-survey-event">

1090 Evento de pesquisa de feedback

1091</h4>

959 1092 

960Registrado quando uma pesquisa de qualidade de sessão é mostrada ou respondida. Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) para o que as pesquisas coletam e como controlá-las.1093Registrado quando uma pesquisa de qualidade de sessão é mostrada ou respondida. Veja [Pesquisas de qualidade de sessão](/pt/data-usage#session-quality-surveys) para o que as pesquisas coletam e como controlá-las.

961 1094 


963 1096 

964**Atributos**:1097**Atributos**:

965 1098 

966* Todos os [atributos padrão](#atributos-padrão)1099* Todos os [atributos padrão](#standard-attributes)

967* `event.name`: `"feedback_survey"`1100* `event.name`: `"feedback_survey"`

968* `event.timestamp`: Timestamp ISO 86011101* `event.timestamp`: Timestamp ISO 8601

969* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão1102* `event.sequence`: Contador monotonicamente crescente para ordenar eventos dentro de uma sessão


973* `response`: A seleção do usuário em eventos `responded`1106* `response`: A seleção do usuário em eventos `responded`

974* `enabled_via_override`: `true` quando [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/pt/env-vars) está definido. Emitido como um booleano, não uma string. Presente em eventos de pesquisa `session`. Filtre neste atributo para confirmar que a substituição é aplicada em toda a frota1107* `enabled_via_override`: `true` quando [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/pt/env-vars) está definido. Emitido como um booleano, não uma string. Presente em eventos de pesquisa `session`. Filtre neste atributo para confirmar que a substituição é aplicada em toda a frota

975 1108 

976## Interpretar dados de métricas e eventos1109<h2 id="interpret-metrics-and-events-data">

1110 Interpretar dados de métricas e eventos

1111</h2>

977 1112 

978As métricas e eventos exportados suportam uma gama de análises:1113As métricas e eventos exportados suportam uma gama de análises:

979 1114 

980### Monitoramento de uso1115<h3 id="usage-monitoring">

1116 Monitoramento de uso

1117</h3>

981 1118 

982| Métrica | Oportunidade de Análise |1119| Métrica | Oportunidade de Análise |

983| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |1120| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |

984| `claude_code.token.usage` | Dividir por `type` (entrada/saída), usuário, equipe, modelo, `skill.name`, `plugin.name` ou `agent.name` |1121| `claude_code.token.usage` | Dividir por `type` (entrada/saída), usuário, equipe, modelo, `skill.name`, `plugin.name` ou `agent.name` |

985| `claude_code.session.count` | Rastrear adoção e engajamento ao longo do tempo |1122| `claude_code.session.count` | Rastrear adoção e engajamento ao longo do tempo |

986| `claude_code.lines_of_code.count` | Medir produtividade rastreando adições/remoções de código |1123| `claude_code.lines_of_code.count` | Medir produtividade rastreando adições e remoções de código, dividido por modelo |

987| `claude_code.commit.count` & `claude_code.pull_request.count` | Entender o impacto nos fluxos de trabalho de desenvolvimento |1124| `claude_code.commit.count` & `claude_code.pull_request.count` | Entender o impacto nos fluxos de trabalho de desenvolvimento |

988 1125 

989### Monitoramento de custo1126<h3 id="cost-monitoring">

1127 Monitoramento de custo

1128</h3>

990 1129 

991A métrica `claude_code.cost.usage` ajuda com:1130A métrica `claude_code.cost.usage` ajuda com:

992 1131 


998 As métricas de custo são aproximações. Para dados de faturamento oficiais, consulte seu provedor de API (Claude Console, Amazon Bedrock ou Google Cloud Vertex).1137 As métricas de custo são aproximações. Para dados de faturamento oficiais, consulte seu provedor de API (Claude Console, Amazon Bedrock ou Google Cloud Vertex).

999</Note>1138</Note>

1000 1139 

1001### Alertas e segmentação1140<h3 id="alerting-and-segmentation">

1141 Alertas e segmentação

1142</h3>

1002 1143 

1003Alertas comuns a considerar:1144Alertas comuns a considerar:

1004 1145 


1006* Consumo incomum de tokens1147* Consumo incomum de tokens

1007* Alto volume de sessão de usuários específicos1148* Alto volume de sessão de usuários específicos

1008 1149 

1009Todas as métricas podem ser segmentadas por `user.account_uuid`, `user.account_id`, `organization.id`, `session.id`, `model` e `app.version`.1150Todas as métricas podem ser segmentadas pelos [atributos padrão](#standard-attributes). O atributo `model` está disponível em `claude_code.token.usage`, `claude_code.cost.usage` e {/* min-version: 2.1.172 */}a partir da v2.1.172, `claude_code.lines_of_code.count`. Divisões por modelo de commits podem ser apenas aproximadas unindo contra as métricas de token ou custo em `session.id`, que uma sessão pode abranger vários modelos.

1010 1151 

1011### Detectar esgotamento de tentativas1152<h3 id="detect-retry-exhaustion">

1153 Detectar esgotamento de tentativas

1154</h3>

1012 1155 

1013Claude Code retenta solicitações de API falhadas internamente e emite um único evento `claude_code.api_error` apenas depois de desistir, então o evento em si é o sinal terminal para essa solicitação. Tentativas de repetição intermediárias não são registradas como eventos separados.1156Claude Code retenta solicitações de API falhadas internamente e emite um único evento `claude_code.api_error` apenas depois de desistir, então o evento em si é o sinal terminal para essa solicitação. Tentativas de repetição intermediárias não são registradas como eventos separados.

1014 1157 


1016 1159 

1017Para distinguir uma sessão que se recuperou de uma que travou, agrupe eventos por `session.id` e verifique se um evento `api_request` posterior existe após o erro.1160Para distinguir uma sessão que se recuperou de uma que travou, agrupe eventos por `session.id` e verifique se um evento `api_request` posterior existe após o erro.

1018 1161 

1019### Análise de eventos1162<h3 id="event-analysis">

1163 Análise de eventos

1164</h3>

1020 1165 

1021Os dados de eventos fornecem insights detalhados sobre interações do Claude Code:1166Os dados de eventos fornecem insights detalhados sobre interações do Claude Code:

1022 1167 


1029 1174 

1030**Monitoramento de Desempenho**: rastreie durações de solicitações de API e tempos de execução de ferramentas para identificar gargalos de desempenho.1175**Monitoramento de Desempenho**: rastreie durações de solicitações de API e tempos de execução de ferramentas para identificar gargalos de desempenho.

1031 1176 

1032## Auditar eventos de segurança1177<h2 id="audit-security-events">

1178 Auditar eventos de segurança

1179</h2>

1033 1180 

1034Os eventos OpenTelemetry são a fonte de dados de auditoria para atividade do Claude Code. Cada evento carrega atributos de identidade que vinculam chamadas de ferramenta, atividade MCP e decisões de permissão de volta ao usuário que as acionou, e o exportador de logs OTLP pode entregar esses eventos a qualquer plataforma Security Information and Event Management (SIEM) com um receptor OTLP ou a um OpenTelemetry Collector que encaminha para seu SIEM.1181Os eventos OpenTelemetry são a fonte de dados de auditoria para atividade do Claude Code. Cada evento carrega atributos de identidade que vinculam chamadas de ferramenta, atividade MCP e decisões de permissão de volta ao usuário que as acionou, e o exportador de logs OTLP pode entregar esses eventos a qualquer plataforma Security Information and Event Management (SIEM) com um receptor OTLP ou a um OpenTelemetry Collector que encaminha para seu SIEM.

1035 1182 

1036### Atribuir ações a usuários1183<h3 id="attribute-actions-to-users">

1184 Atribuir ações a usuários

1185</h3>

1037 1186 

1038Os [atributos padrão](#atributos-padrão) em cada evento incluem a identidade do usuário autenticado: `user.email`, `user.account_uuid`, `user.account_id` e `organization.id` quando conectado com uma conta Claude, mais o `user.id` com escopo de instalação e o `session.id` por sessão.1187Os [atributos padrão](#standard-attributes) em cada evento incluem a identidade do usuário autenticado: `user.email`, `user.account_uuid`, `user.account_id` e `organization.id` quando conectado com uma conta Claude, mais o `user.id` com escopo de instalação e o `session.id` por sessão.

1039 1188 

1040Chamadas de ferramenta MCP, comandos Bash e edições de arquivo são, portanto, atribuídas ao desenvolvedor que iniciou a sessão. Claude Code não atua sob uma conta de serviço separada; a identidade registrada em cada evento é a própria conta Claude do desenvolvedor.1189Chamadas de ferramenta MCP, comandos Bash e edições de arquivo são, portanto, atribuídas ao desenvolvedor que iniciou a sessão. Claude Code não atua sob uma conta de serviço separada; a identidade registrada em cada evento é a própria conta Claude do desenvolvedor.

1041 1190 

1042Quando Claude Code autentica com uma chave de API direta, ou contra Bedrock, Vertex AI ou Microsoft Foundry, não há conta Claude na sessão e apenas `user.id` e `session.id` são preenchidos. Nessas implantações, anexe identidade do usuário você mesmo com `OTEL_RESOURCE_ATTRIBUTES`, definido por usuário através do arquivo de [configurações gerenciadas](#configuração-do-administrador) ou um wrapper de inicialização:1191Quando Claude Code autentica com uma chave de API direta, ou contra Bedrock, Vertex AI ou Microsoft Foundry, não há conta Claude na sessão e apenas `user.id` e `session.id` são preenchidos. Nessas implantações, anexe identidade do usuário você mesmo com `OTEL_RESOURCE_ATTRIBUTES`, definido por usuário através do arquivo de [configurações gerenciadas](#administrator-configuration) ou um wrapper de inicialização:

1043 1192 

1044```bash theme={null}1193```bash theme={null}

1045export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."1194export OTEL_RESOURCE_ATTRIBUTES="enduser.id=jdoe@example.com,enduser.directory_id=S-1-5-21-..."

1046```1195```

1047 1196 

1048### Auditoria de atividade MCP1197<h3 id="audit-mcp-activity">

1198 Auditoria de atividade MCP

1199</h3>

1049 1200 

1050Para capturar atividade do servidor MCP com detalhe completo de chamada, ative o exportador de logs e defina `OTEL_LOG_TOOL_DETAILS=1`. Cada operação MCP então produz eventos estruturados que carregam o nome do servidor, nome da ferramenta e argumentos de chamada junto com os atributos de identidade padrão:1201Para capturar atividade do servidor MCP com detalhe completo de chamada, ative o exportador de logs e defina `OTEL_LOG_TOOL_DETAILS=1`. Cada operação MCP então produz eventos estruturados que carregam o nome do servidor, nome da ferramenta e argumentos de chamada junto com os atributos de identidade padrão:

1051 1202 


1059 1210 

1060* `tool_result`: mantém `tool_name` e `mcp_server_scope`, omite `mcp_server_name`, `mcp_tool_name` e argumentos1211* `tool_result`: mantém `tool_name` e `mcp_server_scope`, omite `mcp_server_name`, `mcp_tool_name` e argumentos

1061* `tool_decision`: mantém `tool_name`, omite `tool_parameters`1212* `tool_decision`: mantém `tool_name`, omite `tool_parameters`

1062* `mcp_server_connection`: omite `server_name` e a mensagem de erro1213* `mcp_server_connection`: omite `server_name` e a mensagem de erro, mas mantém `is_plugin`, `plugin_id_hash` e `plugin.name`, com nomes de plugins não-Anthropic reduzidos ao literal `"third-party"`, para que servidores fornecidos por plugins permaneçam distinguíveis sem registro detalhado

1063 1214 

1064### Mapear questões de segurança para eventos1215<h3 id="map-security-questions-to-events">

1216 Mapear questões de segurança para eventos

1217</h3>

1065 1218 

1066Ao construir regras de detecção, procure o sinal que você deseja monitorar e consulte seu backend para o evento correspondente e atributos:1219Ao construir regras de detecção, procure o sinal que você deseja monitorar e consulte seu backend para o evento correspondente e atributos:

1067 1220 


1071| Escalação de modo de permissão | `permission_mode_changed` | `from_mode`, `to_mode`, `trigger` |1224| Escalação de modo de permissão | `permission_mode_changed` | `from_mode`, `to_mode`, `trigger` |

1072| Hook de política bloqueou uma ação | `hook_execution_complete` | `hook_event`, `num_blocking` |1225| Hook de política bloqueou uma ação | `hook_execution_complete` | `hook_event`, `num_blocking` |

1073| Login, logout e falha de autenticação | `auth` | `action`, `success`, `error_category` |1226| Login, logout e falha de autenticação | `auth` | `action`, `success`, `error_category` |

1074| Conexão do servidor MCP ou falha | `mcp_server_connection` | `status`, `server_name`, `error_code` |1227| Conexão do servidor MCP ou falha | `mcp_server_connection` | `status`, `server_name`, `is_plugin`, `error_code` |

1075| Plugin instalado e sua origem | `plugin_installed` | `plugin.name`, `marketplace.name`, `marketplace.is_official` |1228| Plugin instalado e sua origem | `plugin_installed` | `plugin.name`, `marketplace.name`, `marketplace.is_official` |

1076| Comandos executados e arquivos tocados | `tool_result` (executado) ou `tool_decision` (rejeitado) com `OTEL_LOG_TOOL_DETAILS=1` | `tool_parameters`; `tool_input` (apenas `tool_result`) |1229| Comandos executados e arquivos tocados | `tool_result` (executado) ou `tool_decision` (rejeitado) com `OTEL_LOG_TOOL_DETAILS=1` | `tool_parameters`; `tool_input` (apenas `tool_result`) |

1077 1230 

1078Claude Code emite apenas o fluxo de eventos bruto. Detecção de anomalias, linha de base, correlação entre sessões e alertas são responsabilidade do seu SIEM ou backend de observabilidade.1231Claude Code emite apenas o fluxo de eventos bruto. Detecção de anomalias, linha de base, correlação entre sessões e alertas são responsabilidade do seu SIEM ou backend de observabilidade.

1079 1232 

1080### Enviar eventos para um SIEM1233<h3 id="send-events-to-a-siem">

1234 Enviar eventos para um SIEM

1235</h3>

1081 1236 

1082Aponte `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` para o receptor OTLP do seu SIEM, ou para um OpenTelemetry Collector que encaminha para a API de ingestão nativa do seu SIEM. O seguinte exemplo de configurações gerenciadas exporta apenas eventos, com detalhe completo de ferramenta ativado para auditoria MCP e Bash:1237Aponte `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` para o receptor OTLP do seu SIEM, ou para um OpenTelemetry Collector que encaminha para a API de ingestão nativa do seu SIEM. O seguinte exemplo de configurações gerenciadas exporta apenas eventos, com detalhe completo de ferramenta ativado para auditoria MCP e Bash:

1083 1238 


1094}1249}

1095```1250```

1096 1251 

1097## Considerações de backend1252<h2 id="backend-considerations">

1253 Considerações de backend

1254</h2>

1098 1255 

1099Sua escolha de backends de métricas, logs e rastreamentos determina os tipos de análises que você pode realizar:1256Sua escolha de backends de métricas, logs e rastreamentos determina os tipos de análises que você pode realizar:

1100 1257 

1101### Para métricas1258<h3 id="for-metrics">

1259 Para métricas

1260</h3>

1102 1261 

1103* **Bancos de dados de série temporal (por exemplo, Prometheus)**: Cálculos de taxa, métricas agregadas1262* **Bancos de dados de série temporal (por exemplo, Prometheus)**: Cálculos de taxa, métricas agregadas

1104* **Armazenamentos colunares (por exemplo, ClickHouse)**: Consultas complexas, análise de usuário único1263* **Armazenamentos colunares (por exemplo, ClickHouse)**: Consultas complexas, análise de usuário único

1105* **Plataformas de observabilidade completas (por exemplo, Honeycomb, Datadog)**: Consultas avançadas, visualização, alertas1264* **Plataformas de observabilidade completas (por exemplo, Honeycomb, Datadog, Grafana Cloud)**: Consultas avançadas, visualização, alertas

1106 1265 

1107### Para eventos/logs1266<h3 id="for-events/logs">

1267 Para eventos/logs

1268</h3>

1108 1269 

1109* **Sistemas de agregação de logs (por exemplo, Elasticsearch, Loki)**: Busca de texto completo, análise de logs1270* **Sistemas de agregação de logs (por exemplo, Elasticsearch, Loki)**: Busca de texto completo, análise de logs

1110* **Armazenamentos colunares (por exemplo, ClickHouse)**: Análise de eventos estruturados1271* **Armazenamentos colunares (por exemplo, ClickHouse)**: Análise de eventos estruturados

1111* **Plataformas de observabilidade completas (por exemplo, Honeycomb, Datadog)**: Correlação entre métricas e eventos1272* **Plataformas de observabilidade completas (por exemplo, Honeycomb, Datadog, Grafana Cloud)**: Correlação entre métricas e eventos

1112 1273 

1113### Para rastreamentos1274<h3 id="for-traces">

1275 Para rastreamentos

1276</h3>

1114 1277 

1115Escolha um backend que suporte armazenamento de rastreamento distribuído e correlação de span:1278Escolha um backend que suporte armazenamento de rastreamento distribuído e correlação de span:

1116 1279 

1117* **Sistemas de rastreamento distribuído (por exemplo, Jaeger, Zipkin, Grafana Tempo)**: Visualização de span, waterfalls de solicitação, análise de latência1280* **Sistemas de rastreamento distribuído (por exemplo, Jaeger, Zipkin, Grafana Tempo)**: Visualização de span, waterfalls de solicitação, análise de latência

1118* **Plataformas de observabilidade completas (por exemplo, Honeycomb, Datadog)**: Busca de rastreamento e correlação com métricas e logs1281* **Plataformas de observabilidade completas (por exemplo, Honeycomb, Datadog, Grafana Cloud)**: Busca de rastreamento e correlação com métricas e logs

1119 1282 

1120Para organizações que exigem métricas de Usuário Ativo Diário/Semanal/Mensal (DAU/WAU/MAU), considere backends que suportam consultas eficientes de valor único.1283Para organizações que exigem métricas de Usuário Ativo Diário/Semanal/Mensal (DAU/WAU/MAU), considere backends que suportam consultas eficientes de valor único.

1121 1284 

1122## Informações de serviço1285<h2 id="service-information">

1286 Informações de serviço

1287</h2>

1123 1288 

1124Todas as métricas e eventos são exportados com os seguintes atributos de recurso:1289Todas as métricas e eventos são exportados com os seguintes atributos de recurso:

1125 1290 


1131* `wsl.version`: Número de versão do WSL (apenas presente ao executar no Windows Subsystem for Linux)1296* `wsl.version`: Número de versão do WSL (apenas presente ao executar no Windows Subsystem for Linux)

1132* Nome do Medidor: `com.anthropic.claude_code`1297* Nome do Medidor: `com.anthropic.claude_code`

1133 1298 

1134## Recursos de medição de ROI1299<h2 id="roi-measurement-resources">

1300 Recursos de medição de ROI

1301</h2>

1135 1302 

1136Para um guia abrangente sobre como medir o retorno sobre investimento para Claude Code, incluindo configuração de telemetria, análise de custo, métricas de produtividade e relatórios automatizados, consulte o [Guia de Medição de ROI do Claude Code](https://github.com/anthropics/claude-code-monitoring-guide). Este repositório fornece configurações Docker Compose prontas para uso, configurações Prometheus e OpenTelemetry, e modelos para gerar relatórios de produtividade integrados com ferramentas como Linear.1303Para um guia abrangente sobre como medir o retorno sobre investimento para Claude Code, incluindo configuração de telemetria, análise de custo, métricas de produtividade e relatórios automatizados, consulte o [Guia de Medição de ROI do Claude Code](https://github.com/anthropics/claude-code-monitoring-guide). Este repositório fornece configurações Docker Compose prontas para uso, configurações Prometheus e OpenTelemetry, e modelos para gerar relatórios de produtividade integrados com ferramentas como Linear.

1137 1304 

1138## Segurança e privacidade1305<h2 id="security-and-privacy">

1306 Segurança e privacidade

1307</h2>

1139 1308 

1140* A exportação OpenTelemetry para seu backend é opt-in e requer configuração explícita. Para a telemetria operacional separada da Anthropic e como desabilitá-la, consulte [Uso de dados](/pt/data-usage#telemetry-services)1309* A exportação OpenTelemetry para seu backend é opt-in e requer configuração explícita. Para a telemetria operacional separada da Anthropic e como desabilitá-la, consulte [Uso de dados](/pt/data-usage#telemetry-services)

1141* Conteúdos de arquivo brutos e trechos de código não são incluídos em métricas ou eventos. Os spans de rastreamento são um caminho de dados separado: veja o ponto `OTEL_LOG_TOOL_CONTENT` abaixo1310* Conteúdos de arquivo brutos e trechos de código não são incluídos em métricas ou eventos. Os spans de rastreamento são um caminho de dados separado: veja o ponto `OTEL_LOG_TOOL_CONTENT` abaixo


1149* O conteúdo de entrada e saída de ferramenta não é registrado em spans de rastreamento por padrão. Para incluí-lo, defina `OTEL_LOG_TOOL_CONTENT=1`. Quando ativado, eventos de span incluem conteúdo completo de entrada e saída de ferramenta truncado em 60 KB por span. Isso pode incluir conteúdos de arquivo brutos de resultados da ferramenta Read e saída de comando Bash. Configure seu backend de telemetria para filtrar ou reduzir esses atributos conforme necessário1318* O conteúdo de entrada e saída de ferramenta não é registrado em spans de rastreamento por padrão. Para incluí-lo, defina `OTEL_LOG_TOOL_CONTENT=1`. Quando ativado, eventos de span incluem conteúdo completo de entrada e saída de ferramenta truncado em 60 KB por span. Isso pode incluir conteúdos de arquivo brutos de resultados da ferramenta Read e saída de comando Bash. Configure seu backend de telemetria para filtrar ou reduzir esses atributos conforme necessário

1150* Corpos de solicitação e resposta da API Anthropic Messages brutos não são registrados por padrão. Para incluí-los, defina `OTEL_LOG_RAW_API_BODIES`. Com `=1`, cada chamada de API emite eventos de log `api_request_body` e `api_response_body` cujo atributo `body` é a carga útil serializada em JSON, truncada em 60 KB. Com `=file:<dir>`, corpos não truncados são escritos em arquivos `.request.json` e `.response.json` sob esse diretório e os eventos carregam um caminho `body_ref` em vez do corpo inline. Envie o diretório com um coletor de log ou sidecar em vez de através do fluxo de telemetria. Em ambos os modos, os corpos contêm o histórico de conversa completo (prompt do sistema, cada turno anterior de usuário e assistente, resultados de ferramenta), então ativar isso implica consentimento para tudo que os outros sinalizadores de conteúdo `OTEL_LOG_*` revelariam. O conteúdo de pensamento estendido do Claude é sempre reduzido desses corpos independentemente de outras configurações1319* Corpos de solicitação e resposta da API Anthropic Messages brutos não são registrados por padrão. Para incluí-los, defina `OTEL_LOG_RAW_API_BODIES`. Com `=1`, cada chamada de API emite eventos de log `api_request_body` e `api_response_body` cujo atributo `body` é a carga útil serializada em JSON, truncada em 60 KB. Com `=file:<dir>`, corpos não truncados são escritos em arquivos `.request.json` e `.response.json` sob esse diretório e os eventos carregam um caminho `body_ref` em vez do corpo inline. Envie o diretório com um coletor de log ou sidecar em vez de através do fluxo de telemetria. Em ambos os modos, os corpos contêm o histórico de conversa completo (prompt do sistema, cada turno anterior de usuário e assistente, resultados de ferramenta), então ativar isso implica consentimento para tudo que os outros sinalizadores de conteúdo `OTEL_LOG_*` revelariam. O conteúdo de pensamento estendido do Claude é sempre reduzido desses corpos independentemente de outras configurações

1151 1320 

1152## Monitorar Claude Code no Amazon Bedrock1321<h2 id="monitor-claude-code-on-amazon-bedrock">

1322 Monitorar Claude Code no Amazon Bedrock

1323</h2>

1153 1324 

1154Para orientação detalhada de monitoramento de uso do Claude Code para Amazon Bedrock, consulte [Implementação de Monitoramento do Claude Code (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).1325Para orientação detalhada de monitoramento de uso do Claude Code para Amazon Bedrock, consulte [Implementação de Monitoramento do Claude Code (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).

Details

57 * Usuário: `~/.claude/output-styles`57 * Usuário: `~/.claude/output-styles`

58 * Projeto: `.claude/output-styles`58 * Projeto: `.claude/output-styles`

59 * Política gerenciada: `.claude/output-styles` dentro do [diretório de configurações gerenciadas](/pt/settings#settings-files)59 * Política gerenciada: `.claude/output-styles` dentro do [diretório de configurações gerenciadas](/pt/settings#settings-files)

60 

61 Os estilos de saída do projeto são carregados de cada `.claude/output-styles/` entre o diretório de trabalho e a raiz do repositório. {/* min-version: 2.1.178 */}A partir da v2.1.178, quando mais de um desses diretórios aninhados define um estilo com o mesmo nome, Claude Code usa o mais próximo do diretório de trabalho.

60 </Step>62 </Step>

61 63 

62 <Step title="Adicione frontmatter e instruções">64 <Step title="Adicione frontmatter e instruções">

overview.md +2 −2

Details

124 <Tab title="JetBrains">124 <Tab title="JetBrains">

125 Um plugin para IntelliJ IDEA, PyCharm, WebStorm e outras IDEs JetBrains com visualização de diff interativa e compartilhamento de contexto de seleção.125 Um plugin para IntelliJ IDEA, PyCharm, WebStorm e outras IDEs JetBrains com visualização de diff interativa e compartilhamento de contexto de seleção.

126 126 

127 Instale o [plugin Claude Code](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) do JetBrains Marketplace e reinicie sua IDE.127 Instale o [plugin Claude Code](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) do JetBrains Marketplace e reinicie sua IDE. O plugin requer o Claude Code CLI, instalado separadamente; veja as [etapas de configuração do JetBrains](/pt/jetbrains#installation).

128 128 

129 [Comece com JetBrains →](/pt/jetbrains)129 [Comece com JetBrains →](/pt/jetbrains)

130 </Tab>130 </Tab>


209 209 

210 * Afaste-se de sua mesa e continue trabalhando do seu telefone ou qualquer navegador com [Remote Control](/pt/remote-control)210 * Afaste-se de sua mesa e continue trabalhando do seu telefone ou qualquer navegador com [Remote Control](/pt/remote-control)

211 * Envie uma mensagem para [Dispatch](/pt/desktop#sessions-from-dispatch) com uma tarefa do seu telefone e abra a sessão Desktop que ela cria211 * Envie uma mensagem para [Dispatch](/pt/desktop#sessions-from-dispatch) com uma tarefa do seu telefone e abra a sessão Desktop que ela cria

212 * Inicie uma tarefa de longa duração na [web](/pt/claude-code-on-the-web) ou [aplicativo iOS](https://apps.apple.com/app/claude-by-anthropic/id6473753684), depois puxe-a para seu terminal com `claude --teleport`212 * Inicie uma tarefa de longa duração na [web](/pt/claude-code-on-the-web) ou [aplicativo iOS](https://apps.apple.com/app/claude-by-anthropic/id6473753684), depois puxe-a para seu terminal com `claude --teleport`. Teleport requer uma assinatura claude.ai.

213 * Entregue uma sessão de terminal para o [aplicativo Desktop](/pt/desktop) com `/desktop` para revisão visual de diff213 * Entregue uma sessão de terminal para o [aplicativo Desktop](/pt/desktop) com `/desktop` para revisão visual de diff

214 * Rotear tarefas do chat da equipe: mencione `@Claude` no [Slack](/pt/slack) com um relatório de bug e obtenha um pull request de volta214 * Rotear tarefas do chat da equipe: mencione `@Claude` no [Slack](/pt/slack) com um relatório de bug e obtenha um pull request de volta

215 </Accordion>215 </Accordion>

Details

25 25 

26Em todos os modos exceto `bypassPermissions`, escritas em [caminhos protegidos](#protected-paths) nunca são auto-aprovadas, protegendo o estado do repositório e a configuração própria de Claude contra corrupção acidental.26Em todos os modos exceto `bypassPermissions`, escritas em [caminhos protegidos](#protected-paths) nunca são auto-aprovadas, protegendo o estado do repositório e a configuração própria de Claude contra corrupção acidental.

27 27 

28Os modos definem a linha de base. Sobreponha [regras de permissão](/pt/permissions#manage-permissions) no topo para pré-aprovar ou bloquear ferramentas específicas em qualquer modo exceto `bypassPermissions`, que pula a camada de permissão inteiramente.28Os modos definem a linha de base. Sobreponha [regras de permissão](/pt/permissions#manage-permissions) no topo para pré-aprovar ou bloquear ferramentas específicas. Regras de negação e regras de solicitação explícita se aplicam em todos os modos, incluindo `bypassPermissions`. Regras de permissão não têm efeito nesse modo porque tudo mais já está aprovado.

29 29 

30<h2 id="switch-permission-modes">30<h2 id="switch-permission-modes">

31 Alternar modos de permissão31 Alternar modos de permissão


95 <Tab title="Web and mobile">95 <Tab title="Web and mobile">

96 Use o dropdown de modo ao lado da caixa de prompt em [claude.ai/code](https://claude.ai/code) ou no aplicativo móvel. Prompts de permissão aparecem em claude.ai para aprovação. Quais modos aparecem depende de onde a sessão é executada:96 Use o dropdown de modo ao lado da caixa de prompt em [claude.ai/code](https://claude.ai/code) ou no aplicativo móvel. Prompts de permissão aparecem em claude.ai para aprovação. Quais modos aparecem depende de onde a sessão é executada:

97 97 

98 * **Sessões em nuvem** em [Claude Code na web](/pt/claude-code-on-the-web): Auto accept edits e Plan mode. Ask permissions, Auto e Bypass permissions não estão disponíveis.98 * **Sessões em nuvem** em [Claude Code na web](/pt/claude-code-on-the-web): Accept edits, Plan mode e Auto mode. Accept edits corresponde ao modo `default`: o ambiente em nuvem pré-aprova edições de arquivo independentemente do modo, então o dropdown mostra Accept edits em vez de Ask permissions. `defaultMode: "acceptEdits"` das configurações ainda é respeitado. Auto mode aparece apenas quando sua organização o permite e o modelo selecionado o suporta. Bypass permissions não está disponível.

99 * **Sessões de [Remote Control](/pt/remote-control)** em sua máquina local: Ask permissions, Auto accept edits e Plan mode. Auto e Bypass permissions não estão disponíveis.99 * **Sessões de [Remote Control](/pt/remote-control)** em sua máquina local: Ask permissions, Auto accept edits e Plan mode. Auto e Bypass permissions não estão disponíveis.

100 100 

101 Para Remote Control, você também pode definir o modo inicial ao iniciar o host:101 Para Remote Control, você também pode definir o modo inicial ao iniciar o host:


176 Auto mode requer Claude Code v2.1.83 ou posterior.176 Auto mode requer Claude Code v2.1.83 ou posterior.

177</Note>177</Note>

178 178 

179Auto mode permite que Claude execute sem prompts de permissão. Um modelo classificador separado revisa ações antes de serem executadas, bloqueando qualquer coisa que escale além de sua solicitação, direcione infraestrutura não reconhecida ou pareça impulsionada por conteúdo hostil que Claude leu.179Auto mode permite que Claude execute sem prompts de permissão rotineiros. Um modelo classificador separado revisa ações antes de serem executadas, bloqueando qualquer coisa que escale além de sua solicitação, direcione infraestrutura não reconhecida ou pareça impulsionada por conteúdo hostil que Claude leu. [Regras ask](/pt/permissions#manage-permissions) explícitas ainda forçam um prompt.

180 180 

181Auto mode também instrui Claude a continuar trabalhando sem parar para fazer perguntas de esclarecimento, embora Claude ainda pergunte quando seu prompt ou uma skill depende explicitamente disso. Para obter um comportamento autônomo mais forte mantendo prompts de permissão, defina o [estilo de saída Proactive output style](/pt/output-styles) em vez disso.181Auto mode também instrui Claude a continuar trabalhando sem parar para fazer perguntas de esclarecimento, embora Claude ainda pergunte quando seu prompt ou uma skill depende explicitamente disso. Para obter um comportamento autônomo mais forte mantendo prompts de permissão, defina o [estilo de saída Proactive output style](/pt/output-styles) em vez disso.

182 182 


193 193 

194Se Claude Code relatar auto mode como indisponível, um desses requisitos não foi atendido; isso não é uma interrupção transitória. Uma mensagem separada que nomeia um modelo e diz que auto mode "não pode determinar a segurança" de uma ação é uma interrupção transitória do classificador; veja a [referência de erro](/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action).194Se Claude Code relatar auto mode como indisponível, um desses requisitos não foi atendido; isso não é uma interrupção transitória. Uma mensagem separada que nomeia um modelo e diz que auto mode "não pode determinar a segurança" de uma ação é uma interrupção transitória do classificador; veja a [referência de erro](/pt/errors#auto-mode-cannot-determine-the-safety-of-an-action).

195 195 

196Se você definir `defaultMode: "auto"` em [configurações](/pt/settings#available-settings) e a sessão começar em modo `default` sem erro, a configuração provavelmente está em `.claude/settings.json` ou `.claude/settings.local.json`. Claude Code ignora `auto` desses arquivos para que um repositório não possa se conceder auto mode. Mova-o para `~/.claude/settings.json`.196Se você definir `defaultMode: "auto"` em [configurações](/pt/settings#available-settings) e a sessão começar em modo `default` sem erro, a configuração provavelmente está em `.claude/settings.json` ou `.claude/settings.local.json`. Claude Code v2.1.142 e posterior ignoram `auto` desses arquivos para que um repositório não possa se conceder auto mode. Mova-o para `~/.claude/settings.json`.

197 197 

198<h3 id="enable-auto-mode-on-bedrock-vertex-ai-or-foundry">198<h3 id="enable-auto-mode-on-bedrock-vertex-ai-or-foundry">

199 Habilitar auto mode no Bedrock, Vertex AI ou Foundry199 Habilitar auto mode no Bedrock, Vertex AI ou Foundry

200</h3>200</h3>

201 201 

202No [Amazon Bedrock](/pt/amazon-bedrock), [Google Cloud Vertex AI](/pt/google-vertex-ai) e [Microsoft Foundry](/pt/microsoft-foundry), auto mode não aparece no ciclo `Shift+Tab` até que `CLAUDE_CODE_ENABLE_AUTO_MODE` seja definido como `1`. Apenas Claude Opus 4.7 e Opus 4.8 são suportados nesses provedores.202No [Amazon Bedrock](/pt/amazon-bedrock), [Google Cloud Vertex AI](/pt/google-vertex-ai) e [Microsoft Foundry](/pt/microsoft-foundry), auto mode não aparece no ciclo `Shift+Tab` até que `CLAUDE_CODE_ENABLE_AUTO_MODE` seja definido como `1`. A variável funciona em Claude Code v2.1.158 e posterior. Apenas Claude Opus 4.7 e Opus 4.8 são suportados nesses provedores.

203 203 

204Para habilitá-lo para um desenvolvedor, adicione a variável ao bloco `env` em `~/.claude/settings.json`:204Para habilitá-lo para um desenvolvedor, adicione a variável ao bloco `env` em `~/.claude/settings.json`:

205 205 


293 1. Antes de um subagente iniciar, a descrição da tarefa delegada é avaliada, então uma tarefa que parece perigosa é bloqueada no tempo de geração.293 1. Antes de um subagente iniciar, a descrição da tarefa delegada é avaliada, então uma tarefa que parece perigosa é bloqueada no tempo de geração.

294 2. Enquanto o subagente é executado, cada uma de suas ações passa pelo classificador com as mesmas regras que a sessão pai, e qualquer `permissionMode` no frontmatter do subagente é ignorado.294 2. Enquanto o subagente é executado, cada uma de suas ações passa pelo classificador com as mesmas regras que a sessão pai, e qualquer `permissionMode` no frontmatter do subagente é ignorado.

295 3. Quando o subagente termina, o classificador revisa seu histórico de ação completo; se essa verificação de retorno sinaliza uma preocupação, um aviso de segurança é adicionado aos resultados do subagente.295 3. Quando o subagente termina, o classificador revisa seu histórico de ação completo; se essa verificação de retorno sinaliza uma preocupação, um aviso de segurança é adicionado aos resultados do subagente.

296 

297 A etapa 1 requer Claude Code v2.1.178 ou posterior. Versões anteriores aplicaram o classificador nas etapas 2 e 3, mas não avaliaram a descrição da tarefa antes do subagente iniciar.

296 </Accordion>298 </Accordion>

297 299 

298 <Accordion title="Custo e latência">300 <Accordion title="Custo e latência">


304 Allow only pre-approved tools with dontAsk mode306 Allow only pre-approved tools with dontAsk mode

305</h2>307</h2>

306 308 

307O modo `dontAsk` auto-nega toda chamada de ferramenta que de outra forma solicitaria. Apenas ações correspondentes às suas regras `permissions.allow` e [comandos Bash somente leitura](/pt/permissions#read-only-commands) podem ser executadas; regras `ask` explícitas são negadas em vez de solicitar. Isso torna o modo totalmente não-interativo para pipelines CI ou ambientes restritos onde você pré-define exatamente o que Claude pode fazer.309O modo `dontAsk` auto-nega toda chamada de ferramenta que de outra forma solicitaria. Apenas ações correspondentes às suas regras `permissions.allow` e [comandos Bash somente leitura](/pt/permissions#read-only-commands) podem ser executadas; regras [`ask` explícitas](/pt/permissions#manage-permissions) são negadas em vez de solicitar. Isso torna o modo totalmente não-interativo para pipelines CI ou ambientes restritos onde você pré-define exatamente o que Claude pode fazer. Sessões em nuvem no [Claude Code na web](/pt/claude-code-on-the-web) ignoram `defaultMode: "dontAsk"`; consulte [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) para detalhes.

308 310 

309Defina-o na inicialização com a flag:311Defina-o na inicialização com a flag:

310 312 


316 Pule todas as verificações com o modo bypassPermissions318 Pule todas as verificações com o modo bypassPermissions

317</h2>319</h2>

318 320 

319O modo `bypassPermissions` desabilita prompts de permissão e verificações de segurança para que chamadas de ferramenta sejam executadas imediatamente. A partir da v2.1.126, isso inclui escritas em [caminhos protegidos](#protected-paths), que versões anteriores ainda solicitavam. Remoções direcionadas à raiz do sistema de arquivos ou diretório home, como `rm -rf /` e `rm -rf ~`, ainda solicitam como um disjuntor contra erro do modelo. Use este modo apenas em ambientes isolados como contêineres, VMs ou dev containers sem acesso à internet, onde Claude Code não pode danificar seu sistema host.321O modo `bypassPermissions` desabilita prompts de permissão e verificações de segurança para que chamadas de ferramenta sejam executadas imediatamente. A partir da v2.1.126, isso inclui escritas em [caminhos protegidos](#protected-paths), que versões anteriores ainda solicitavam. Regras [ask explícitas](/pt/permissions#manage-permissions) ainda forçam um prompt neste modo, e remoções direcionadas à raiz do sistema de arquivos ou diretório home, como `rm -rf /` e `rm -rf ~`, ainda solicitam como um disjuntor contra erro do modelo. Use este modo apenas em ambientes isolados como contêineres, VMs ou dev containers sem acesso à internet, onde Claude Code não pode danificar seu sistema host.

320 322 

321Você não pode entrar em `bypassPermissions` a partir de uma sessão que foi iniciada sem uma das flags de habilitação; reinicie com uma para habilitá-lo:323Você não pode entrar em `bypassPermissions` a partir de uma sessão que foi iniciada sem uma das flags de habilitação; reinicie com uma para habilitá-lo:

322 324 


334 336 

335A verificação é ignorada automaticamente dentro de uma sandbox reconhecida. Para executar autonomamente em um contêiner, use a configuração [dev container](/pt/devcontainer), que executa Claude Code como um usuário não-root.337A verificação é ignorada automaticamente dentro de uma sandbox reconhecida. Para executar autonomamente em um contêiner, use a configuração [dev container](/pt/devcontainer), que executa Claude Code como um usuário não-root.

336 338 

339[Claude Code na web](/pt/claude-code-on-the-web) não honra `defaultMode: "bypassPermissions"` ou `"dontAsk"` de seus arquivos de configuração, portanto as configurações verificadas de um repositório não podem iniciar uma sessão na nuvem no modo bypass-permissions. A configuração é ignorada silenciosamente e a sessão inicia no modo mostrado no menu suspenso de modo. Veja [Alternar modos de permissão](#switch-permission-modes) para quais modos as sessões na nuvem oferecem.

340 

337<Warning>341<Warning>

338 `bypassPermissions` não oferece proteção contra injeção de prompt ou ações não intencionais. Para verificações de segurança de fundo sem prompts, use [auto mode](#eliminate-prompts-with-auto-mode) em vez disso. Administradores podem bloquear este modo definindo `permissions.disableBypassPermissionsMode` para `"disable"` em [configurações gerenciadas](/pt/permissions#managed-settings).342 `bypassPermissions` não oferece proteção contra injeção de prompt ou ações não intencionais. Para verificações de segurança de fundo com muito menos prompts, use [auto mode](#eliminate-prompts-with-auto-mode) em vez disso. Administradores podem bloquear este modo definindo `permissions.disableBypassPermissionsMode` para `"disable"` em [configurações gerenciadas](/pt/permissions#managed-settings).

339</Warning>343</Warning>

340 344 

341<h2 id="protected-paths">345<h2 id="protected-paths">


351| `dontAsk` | Negadas |355| `dontAsk` | Negadas |

352| `bypassPermissions` | Permitidas |356| `bypassPermissions` | Permitidas |

353 357 

358As regras [`permissions.allow`](/pt/permissions#manage-permissions) em arquivos de configuração não pré-aprovam escritas em caminhos protegidos. A verificação de segurança é executada antes de Claude Code avaliar as regras de permissão dos arquivos de configuração, portanto uma entrada como `Edit(.claude/**)` em `~/.claude/settings.json` ou `.claude/settings.json` não altera o resultado por modo na tabela acima. Nos modos que solicitam, o prompt para uma escrita em `.claude/` oferece **Sim, e permitir que Claude edite suas próprias configurações para esta sessão**, o que aprova escritas posteriores em `.claude/` nessa sessão sem solicitar novamente.

359 

354Diretórios protegidos:360Diretórios protegidos:

355 361 

356* `.git`362* `.git`


362* `.devcontainer`368* `.devcontainer`

363* `.yarn`369* `.yarn`

364* `.mvn`370* `.mvn`

365* `.claude`, exceto para `.claude/commands`, `.claude/agents`, `.claude/skills` e `.claude/worktrees` onde Claude rotineiramente cria conteúdo371* `.claude`, exceto para `.claude/worktrees` onde Claude armazena seus próprios git worktrees

366 372 

367Arquivos protegidos:373Arquivos protegidos:

368 374 


377* `.mcp.json`, `.claude.json`383* `.mcp.json`, `.claude.json`

378 384 

379<h2 id="see-also">385<h2 id="see-also">

380 See also386 Veja também

381</h2>387</h2>

382 388 

383* [Permissions](/pt/permissions): regras de permitir, pedir e negar; políticas gerenciadas389* [Permissions](/pt/permissions): regras de permitir, pedir e negar; políticas gerenciadas

permissions.md +82 −10

Details

30* As regras **Ask** solicitam confirmação sempre que Claude Code tenta usar a ferramenta especificada.30* As regras **Ask** solicitam confirmação sempre que Claude Code tenta usar a ferramenta especificada.

31* As regras **Deny** impedem que Claude Code use a ferramenta especificada.31* As regras **Deny** impedem que Claude Code use a ferramenta especificada.

32 32 

33As regras são avaliadas em ordem: **deny -> ask -> allow**. A primeira regra correspondente vence, portanto as regras deny sempre têm precedência.33As regras são avaliadas em ordem: deny, depois ask, depois allow. A primeira correspondência nessa ordem determina o resultado, e a especificidade da regra não altera a ordem. Uma regra deny ampla como `Bash(aws *)` bloqueia cada chamada correspondente, incluindo chamadas que também correspondem a uma regra allow mais estreita como `Bash(aws s3 ls)`, portanto uma regra deny não pode carregar exceções de lista de permissões. A mesma precedência se aplica entre ask e allow: uma regra ask correspondente solicita confirmação mesmo quando uma regra allow mais específica também corresponde à mesma chamada.

34 34 

35As regras deny se comportam de forma diferente dependendo se nomeiam uma ferramenta ou definem o escopo de um padrão dentro de uma. Um nome de ferramenta simples como `Bash` remove a ferramenta do contexto do Claude completamente, então Claude nunca a vê. Uma regra com escopo como `Bash(rm *)` deixa a ferramenta disponível e bloqueia chamadas correspondentes quando Claude tenta usá-las.35As regras deny se comportam de forma diferente dependendo se nomeiam uma ferramenta ou definem o escopo de um padrão dentro de uma. Um nome de ferramenta simples como `Bash` remove a ferramenta do contexto do Claude completamente, então Claude nunca a vê. Uma regra com escopo como `Bash(rm *)` deixa a ferramenta disponível e bloqueia chamadas correspondentes quando Claude tenta usá-las.

36 36 


51| `plan` | Plan Mode: Claude lê arquivos e executa comandos shell somente leitura para explorar, mas não edita seus arquivos de origem |51| `plan` | Plan Mode: Claude lê arquivos e executa comandos shell somente leitura para explorar, mas não edita seus arquivos de origem |

52| `auto` | Aprova automaticamente chamadas de ferramentas com verificações de segurança em segundo plano que verificam se as ações se alinham com sua solicitação. Atualmente uma visualização de pesquisa |52| `auto` | Aprova automaticamente chamadas de ferramentas com verificações de segurança em segundo plano que verificam se as ações se alinham com sua solicitação. Atualmente uma visualização de pesquisa |

53| `dontAsk` | Nega automaticamente ferramentas a menos que pré-aprovadas via `/permissions` ou regras `permissions.allow` |53| `dontAsk` | Nega automaticamente ferramentas a menos que pré-aprovadas via `/permissions` ou regras `permissions.allow` |

54| `bypassPermissions` | Ignora todos os prompts de permissão. Remoções de diretório raiz e diretório inicial como `rm -rf /` ainda solicitam como um disjuntor |54| `bypassPermissions` | Ignora prompts de permissão, exceto aqueles forçados por regras `ask` explícitas. Remoções de diretório raiz e diretório inicial como `rm -rf /` também ainda solicitam como um disjuntor |

55 55 

56<Warning>56<Warning>

57 O modo `bypassPermissions` ignora todos os prompts de permissão, incluindo escritas em `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn` e `.mvn`. Remoções direcionadas ao diretório raiz do sistema de arquivos ou diretório inicial, como `rm -rf /` e `rm -rf ~`, ainda solicitam como um disjuntor contra erro do modelo. Use este modo apenas em ambientes isolados como contêineres ou VMs onde Claude Code não pode causar danos. Administradores podem impedir este modo definindo `permissions.disableBypassPermissionsMode` como `"disable"` em [configurações gerenciadas](#managed-settings).57 O modo `bypassPermissions` ignora prompts de permissão, incluindo escritas em `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn` e `.mvn`. Regras `ask` explícitas ainda forçam um prompt, e remoções direcionadas ao diretório raiz do sistema de arquivos ou diretório inicial, como `rm -rf /` e `rm -rf ~`, ainda solicitam como um disjuntor contra erro do modelo. Use este modo apenas em ambientes isolados como contêineres ou VMs onde Claude Code não pode causar danos. Administradores podem impedir este modo definindo `permissions.disableBypassPermissionsMode` como `"disable"` em [configurações gerenciadas](#managed-settings).

58</Warning>58</Warning>

59 59 

60Para evitar que o modo `bypassPermissions` ou `auto` seja usado, defina `permissions.disableBypassPermissionsMode` ou `permissions.disableAutoMode` como `"disable"` em qualquer [arquivo de configuração](/pt/settings#settings-files). Estes são mais úteis em [configurações gerenciadas](#managed-settings) onde não podem ser substituídos.60Para evitar que o modo `bypassPermissions` ou `auto` seja usado, defina `permissions.disableBypassPermissionsMode` ou `permissions.disableAutoMode` como `"disable"` em qualquer [arquivo de configuração](/pt/settings#settings-files). Estes são mais úteis em [configurações gerenciadas](#managed-settings) onde não podem ser substituídos.


91| `Read(./.env)` | Corresponde à leitura do arquivo `.env` no diretório atual |91| `Read(./.env)` | Corresponde à leitura do arquivo `.env` no diretório atual |

92| `WebFetch(domain:example.com)` | Corresponde a solicitações de busca para example.com |92| `WebFetch(domain:example.com)` | Corresponde a solicitações de busca para example.com |

93 93 

94<h3 id="match-by-input-parameter">

95 Corresponder por parâmetro de entrada

96</h3>

97 

98As regras de negação e pergunta podem corresponder a um parâmetro de entrada de nível superior em qualquer ferramenta com `Tool(param:value)`. A regra corresponde quando Claude chama a ferramenta com esse parâmetro definido para esse valor exato. Esta sintaxe é para regras de negação e pergunta; uma regra de permissão para um valor de parâmetro não estabeleceria que a chamada é segura em geral, portanto as regras de permissão continuam a usar a sintaxe de especificador própria de cada ferramenta. Isso funciona para qualquer parâmetro escalar que a ferramenta aceita:

99 

100| Regra | Corresponde |

101| :----------------------------- | :----------------------------------------------------- |

102| `Agent(model:opus)` | Chamadas de Agent que solicitam o nível de modelo Opus |

103| `Agent(isolation:worktree)` | Chamadas de Agent que solicitam um git worktree |

104| `Bash(run_in_background:true)` | Chamadas Bash que executam em segundo plano |

105 

106A correspondência de parâmetros segue estas regras:

107 

108* O nome do parâmetro deve ser um campo direto da entrada da ferramenta, como `model` na ferramenta Agent. Campos aninhados dentro de um objeto ou array não são correspondíveis

109* Cada regra nomeia um parâmetro. Para controlar tanto `model` quanto `isolation`, escreva duas regras, `Agent(model:opus)` e `Agent(isolation:worktree)`, em vez de combiná-las em uma regra

110* O valor suporta `*` como um caractere curinga que corresponde a qualquer sequência de caracteres, portanto `Agent(isolation:*)` corresponde a qualquer valor de isolamento explícito. Sem `*` a correspondência é exata

111* Um parâmetro que o modelo omite nunca é correspondido, portanto `Agent(model:*)` não corresponde a uma chamada que deixa `model` não definido

112* O valor é comparado com a entrada literal que Claude envia, antes de qualquer normalização. `Agent(model:opus)` corresponde ao alias `opus` mas não a um ID de modelo completo. Execute com [`--verbose`](/pt/cli-reference) para ver os nomes e valores exatos dos parâmetros em cada chamada de ferramenta

113* O espaço em branco ao redor do dois-pontos é ignorado

114 

115Campos que uma ferramenta já corresponde com suas próprias regras de canonicalização não são correspondíveis desta forma: `command` para Bash e PowerShell, `file_path` para Read, Edit e Write, `path` para Grep e Glob, `notebook_path` para NotebookEdit, e `url` para WebFetch. Uma regra como `Bash(command:rm *)` seria contornável por um comando composto, portanto Claude Code a ignora e emite um aviso de inicialização. Use `Bash(rm *)`, `Read(./path)` ou `WebFetch(domain:host)` em vez disso.

116 

94<h3 id="wildcard-patterns">117<h3 id="wildcard-patterns">

95 Padrões com caracteres curinga118 Padrões com caracteres curinga

96</h3>119</h3>


118 141 

119O diálogo de permissão escreve a forma separada por espaço quando você seleciona "Sim, não pergunte novamente" para um prefixo de comando. A forma `:*` é reconhecida apenas no final de um padrão. Em um padrão como `Bash(git:* push)`, o dois-pontos é tratado como um caractere literal e não corresponderá a comandos git.142O diálogo de permissão escreve a forma separada por espaço quando você seleciona "Sim, não pergunte novamente" para um prefixo de comando. A forma `:*` é reconhecida apenas no final de um padrão. Em um padrão como `Bash(git:* push)`, o dois-pontos é tratado como um caractere literal e não corresponderá a comandos git.

120 143 

144<h3 id="tool-name-wildcards">

145 Caracteres curinga no nome da ferramenta

146</h3>

147 

148As regras de negação e pergunta também aceitam padrões glob na posição do nome da ferramenta. O padrão deve corresponder ao nome completo da ferramenta: `"*"` corresponde a todas as ferramentas, e `"mcp__*"` corresponde a todas as ferramentas MCP em todos os servidores. Uma ferramenta correspondida por uma regra de negação glob com nome simples é removida do contexto do Claude, o mesmo que um nome de ferramenta simples. Esta configuração nega todas as ferramentas MCP:

149 

150```json theme={null}

151{

152 "permissions": {

153 "deny": [

154 "mcp__*"

155 ]

156 }

157}

158```

159 

160As regras de permissão aceitam globs de nome de ferramenta apenas após um prefixo literal `mcp__<server>__`. O segmento do servidor deve estar livre de glob para que a regra nomeie um servidor específico que você configurou. `mcp__puppeteer__*` corresponde a todas as ferramentas do servidor `puppeteer`, e `mcp__github__get_*` corresponde às suas ferramentas `get_`. Um glob de permissão desancorado como `"*"`, `"B*"` ou `"mcp__*"` é ignorado com um aviso e não aprova automaticamente nada.

161 

162Uma regra de negação ou pergunta cujo nome de ferramenta não corresponde a nenhuma ferramenta conhecida produz um aviso de inicialização para detectar erros de digitação. Nomes de ferramentas contendo `_` ou `*` estão isentos da verificação.

163 

164O rótulo mostrado para uma ferramenta na transcrição e diálogo de permissão pode diferir do seu nome canônico. Por exemplo, a ferramenta rotulada `Stop Task` na transcrição tem o nome canônico `TaskStop`. As regras de permissão e [correspondências de hook](/pt/hooks) correspondem apenas ao nome canônico, portanto uma regra escrita como `Stop Task` não corresponde. Para regras de negação e pergunta, o aviso de inicialização acima detecta a incompatibilidade. Use os nomes canônicos listados na [referência de ferramentas](/pt/tools-reference).

165 

121<h2 id="tool-specific-permission-rules">166<h2 id="tool-specific-permission-rules">

122 Regras de permissão específicas da ferramenta167 Regras de permissão específicas da ferramenta

123</h2>168</h2>


168 213 

169Padrões glob sem aspas são permitidos para comandos cujas todas as flags são somente leitura, portanto `ls *.ts` e `wc -l src/*.py` são executados sem um prompt. Comandos com flags capazes de escrita ou execução, como `find`, `sort`, `sed` e `git`, ainda solicitam quando um glob sem aspas está presente porque o glob poderia expandir para uma flag como `-delete`.214Padrões glob sem aspas são permitidos para comandos cujas todas as flags são somente leitura, portanto `ls *.ts` e `wc -l src/*.py` são executados sem um prompt. Comandos com flags capazes de escrita ou execução, como `find`, `sort`, `sed` e `git`, ainda solicitam quando um glob sem aspas está presente porque o glob poderia expandir para uma flag como `-delete`.

170 215 

171Um `cd` em um caminho dentro do seu diretório de trabalho ou um [diretório adicional](#working-directories) também é somente leitura. Um comando composto como `cd packages/api && ls` é executado sem um prompt quando cada parte se qualifica por conta própria. Combinar `cd` com `git` em um comando composto sempre solicita, independentemente do diretório de destino.216Um `cd` em um caminho dentro do seu diretório de trabalho ou um diretório adicional também é somente leitura. Um comando composto como `cd packages/api && ls` é executado sem um prompt quando cada parte se qualifica por conta própria. Combinar `cd` com `git` em um comando composto sempre solicita, independentemente do diretório de destino.

172 217 

173<Warning>218<Warning>

174 Padrões de permissão Bash que tentam restringir argumentos de comando são frágeis. Por exemplo, `Bash(curl http://github.com/ *)` pretende restringir curl a URLs do GitHub, mas não corresponderá a variações como:219 Padrões de permissão Bash que tentam restringir argumentos de comando são frágeis. Por exemplo, `Bash(curl http://github.com/ *)` pretende restringir curl a URLs do GitHub, mas não corresponderá a variações como:


216 Read e Edit261 Read e Edit

217</h3>262</h3>

218 263 

219As regras `Edit` se aplicam a todas as ferramentas integradas que editam arquivos. Claude faz uma tentativa de melhor esforço para aplicar regras `Read` a todas as ferramentas integradas que leem arquivos como Grep e Glob, a menções `@file` em seus prompts, e à seleção e contexto de arquivo aberto que um [IDE](/pt/vs-code#the-built-in-ide-mcp-server) conectado compartilha com Claude.264As regras `Edit` se aplicam a todas as ferramentas integradas que editam arquivos. Claude faz uma tentativa de melhor esforço para aplicar regras `Read` a todas as ferramentas integradas que leem arquivos como Grep e Glob, a menções `@file` em seus prompts, e à seleção e contexto de arquivo aberto que um IDE conectado compartilha com Claude.

220 265 

221<Warning>266<Warning>

222 As regras deny de Read e Edit se aplicam às ferramentas de arquivo integradas do Claude e aos comandos de arquivo que Claude Code reconhece em Bash, como `cat`, `head`, `tail` e `sed`. Elas não se aplicam a subprocessos arbitrários que leem ou escrevem arquivos indiretamente, como um script Python ou Node que abre arquivos por conta própria. Para imposição em nível de SO que bloqueia todos os processos de acessar um caminho, [ative o sandbox](/pt/sandboxing).267 As regras deny de Read e Edit se aplicam às ferramentas de arquivo integradas do Claude e aos comandos de arquivo que Claude Code reconhece em Bash, como `cat`, `head`, `tail` e `sed`. Elas não se aplicam a subprocessos arbitrários que leem ou escrevem arquivos indiretamente, como um script Python ou Node que abre arquivos por conta própria. Para imposição em nível de SO que bloqueia todos os processos de acessar um caminho, ative o sandbox.

223</Warning>268</Warning>

224 269 

225As regras Read e Edit seguem a especificação [gitignore](https://git-scm.com/docs/gitignore) com quatro tipos de padrão distintos:270As regras Read e Edit seguem a especificação [gitignore](https://git-scm.com/docs/gitignore) com quatro tipos de padrão distintos:


266 WebFetch311 WebFetch

267</h3>312</h3>

268 313 

269* `WebFetch(domain:example.com)` corresponde a solicitações de busca para example.com314As regras WebFetch usam um prefixo `domain:` e correspondem ao hostname da URL solicitada. A correspondência é insensível a maiúsculas e minúsculas, suporta caracteres curinga `*`, e remove um `.` final tanto da regra quanto do hostname para que `example.com.` e `example.com` sejam tratados da mesma forma.

315 

316* `WebFetch(domain:example.com)` corresponde a solicitações para `example.com`

317* `WebFetch(domain:*.example.com)` corresponde a qualquer subdomínio em qualquer profundidade, como `api.example.com` ou `a.b.example.com`, mas não a `example.com` em si

318* `WebFetch(domain:*)` corresponde a cada domínio e é equivalente a uma regra `WebFetch` simples

319 

320Em qualquer posição que não seja um `*.` inicial ou um `*` simples, o caractere curinga corresponde apenas ao texto entre dois pontos. `WebFetch(domain:example.*)` corresponde a `example.org`, onde `*` se torna `org`, mas não a `example.evil.com`, onde `*` teria que se tornar `evil.com` e cruzar um ponto. Isso impede que um caractere curinga final corresponda a domínios que um atacante poderia registrar.

270 321 

271<h3 id="mcp">322<h3 id="mcp">

272 MCP323 MCP


280 Agent (subagents)331 Agent (subagents)

281</h3>332</h3>

282 333 

283Use regras `Agent(AgentName)` para controlar quais [subagents](/pt/sub-agents) Claude pode usar:334Use regras `Agent(AgentName)` para controlar quais subagents Claude pode usar:

284 335 

285* `Agent(Explore)` corresponde ao subagent Explore336* `Agent(Explore)` corresponde ao subagent Explore

286* `Agent(Plan)` corresponde ao subagent Plan337* `Agent(Plan)` corresponde ao subagent Plan


296}347}

297```348```

298 349 

350<h3 id="cd">

351 Cd

352</h3>

353 

354As regras `Cd` controlam para quais diretórios o comando `/cd` pode mover a sessão. `Cd` não é uma ferramenta invocável pelo modelo: Claude não pode chamá-la, e as regras se aplicam apenas quando você executa `/cd` você mesmo.

355 

356Uma regra deny `Cd` simples desabilita `/cd` inteiramente. Uma regra deny `Cd(<path-pattern>)` bloqueia alvos correspondentes. As regras deny verificam cada grafia do alvo, incluindo cada salto de symlink que ele se resolve através, portanto uma regra escrita para um caminho também bloqueia alvos que se resolvem para ele.

357 

358Adicionar qualquer regra allow `Cd` muda `/cd` para modo de lista de permissões: o diretório alvo resolvido deve corresponder a uma de suas regras allow, ou `/cd` recusa. Sem regras `Cd` configuradas, `/cd` mantém seu comportamento padrão e solicita que você confie em um diretório desconhecido.

359 

360Os padrões de caminho compartilham as âncoras `//`, `~/` e `/` das regras Read e Edit, mas a correspondência é ancorada ao caminho do diretório inteiro em vez de estilo gitignore. `*` corresponde a exatamente um segmento de caminho e `**` corresponde entre segmentos. Um `/**` final também corresponde à sua raiz nomeada.

361 

362| Regra | Corresponde | Não corresponde |

363| --------------------- | ---------------------------------------------------------- | --------------------------- |

364| `Cd(~/code/*)` | `~/code/app` | `~/code/app/src`, `~/code` |

365| `Cd(~/code/**)` | `~/code` e qualquer diretório sob ele | diretórios fora de `~/code` |

366| `Cd(**/node_modules)` | qualquer diretório `node_modules` em qualquer profundidade | `node_modules/pkg` |

367 

299<h2 id="extend-permissions-with-hooks">368<h2 id="extend-permissions-with-hooks">

300 Estender permissões com hooks369 Estender permissões com hooks

301</h2>370</h2>


318 387 

319Arquivos em diretórios adicionais seguem as mesmas regras de permissão do diretório de trabalho original: eles se tornam legíveis sem prompts, e as permissões de edição de arquivo seguem o modo de permissão atual.388Arquivos em diretórios adicionais seguem as mesmas regras de permissão do diretório de trabalho original: eles se tornam legíveis sem prompts, e as permissões de edição de arquivo seguem o modo de permissão atual.

320 389 

390Para alterar o diretório de trabalho primário da sessão em vez de adicionar outro, use [`/cd`](/pt/commands). O comando `/cd` requer Claude Code v2.1.169 ou posterior. Diferentemente de `/add-dir`, ele realoca a sessão: o `CLAUDE.md` do novo diretório é carregado e `--resume` encontra a sessão a partir daí.

391 

321<h3 id="additional-directories-grant-file-access-not-configuration">392<h3 id="additional-directories-grant-file-access-not-configuration">

322 Diretórios adicionais concedem acesso a arquivos, não configuração393 Diretórios adicionais concedem acesso a arquivos, não configuração

323</h3>394</h3>


331| Configuração | Carregado de `--add-dir` |402| Configuração | Carregado de `--add-dir` |

332| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |403| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

333| [Skills](/pt/skills) em `.claude/skills/` | Sim, com recarga ao vivo |404| [Skills](/pt/skills) em `.claude/skills/` | Sim, com recarga ao vivo |

405| [Subagentes](/pt/sub-agents) em `.claude/agents/` | Sim |

334| Configurações de plugin em `.claude/settings.json` | Apenas `enabledPlugins` e `extraKnownMarketplaces` |406| Configurações de plugin em `.claude/settings.json` | Apenas `enabledPlugins` e `extraKnownMarketplaces` |

335| Arquivos [CLAUDE.md](/pt/memory), `.claude/rules/` e `CLAUDE.local.md` | Apenas quando `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` está definido. `CLAUDE.local.md` adicionalmente requer a fonte de configuração `local`, que é ativada por padrão |407| Arquivos [CLAUDE.md](/pt/memory), `.claude/rules/` e `CLAUDE.local.md` | Apenas quando `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` está definido. `CLAUDE.local.md` adicionalmente requer a fonte de configuração `local`, que é ativada por padrão |

336 408 

337Subagentes, comandos e estilos de saída são descobertos do diretório de trabalho atual e seus pais, seu diretório de usuário em `~/.claude/` e configurações gerenciadas. Hooks e outras chaves `settings.json` são carregadas da pasta `.claude/` do diretório de trabalho atual sem fallback de diretório pai, juntamente com seu `~/.claude/settings.json` de usuário e configurações gerenciadas. Para compartilhar essa configuração entre projetos, use uma destas abordagens:409Comandos e estilos de saída são descobertos do diretório de trabalho atual e seus pais, seu diretório de usuário em `~/.claude/` e configurações gerenciadas. Hooks e outras chaves `settings.json` são carregadas da pasta `.claude/` do diretório de trabalho atual sem fallback de diretório pai, juntamente com seu `~/.claude/settings.json` de usuário e configurações gerenciadas. Para compartilhar essa configuração entre projetos, use uma destas abordagens:

338 410 

339* **Configuração em nível de usuário**: coloque arquivos em `~/.claude/agents/`, `~/.claude/output-styles/` ou `~/.claude/settings.json` para torná-los disponíveis em cada projeto411* **Configuração em nível de usuário**: coloque arquivos em `~/.claude/agents/`, `~/.claude/output-styles/` ou `~/.claude/settings.json` para torná-los disponíveis em cada projeto

340* **Plugins**: empacote e distribua configuração como um [plugin](/pt/plugins) que as equipes podem instalar412* **Plugins**: empacote e distribua configuração como um [plugin](/pt/plugins) que as equipes podem instalar


356* As restrições de sistema de arquivos no sandbox combinam as configurações [`sandbox.filesystem`](/pt/sandboxing) com regras deny de Read e Edit; ambas são mescladas no limite final do sandbox428* As restrições de sistema de arquivos no sandbox combinam as configurações [`sandbox.filesystem`](/pt/sandboxing) com regras deny de Read e Edit; ambas são mescladas no limite final do sandbox

357* As restrições de rede combinam regras de permissão WebFetch com as listas `allowedDomains` e `deniedDomains` do sandbox429* As restrições de rede combinam regras de permissão WebFetch com as listas `allowedDomains` e `deniedDomains` do sandbox

358 430 

359Quando o sandboxing é ativado com `autoAllowBashIfSandboxed: true`, que é o padrão, comandos Bash em sandbox são executados sem solicitar mesmo se suas permissões incluem `ask: Bash(*)`. O limite do sandbox substitui o prompt por comando. Regras deny explícitas ainda se aplicam, e comandos `rm` ou `rmdir` que visam `/`, seu diretório inicial ou outros caminhos críticos do sistema ainda acionam um prompt. Veja [modos de sandbox](/pt/sandboxing#sandbox-modes) para alterar este comportamento.431Quando o sandboxing é ativado com `autoAllowBashIfSandboxed: true`, que é o padrão, comandos Bash em sandbox são executados sem solicitar mesmo se suas permissões incluem uma regra ask simples `Bash`, ou o [formulário equivalente `Bash(*)`](#match-all-uses-of-a-tool): o limite do sandbox substitui esse prompt de ferramenta inteira. Regras ask com escopo de conteúdo como `Bash(git push *)` ainda forçam um prompt, regras deny explícitas ainda se aplicam, e comandos `rm` ou `rmdir` que visam `/`, seu diretório inicial ou outros caminhos críticos do sistema ainda acionam um prompt. Comandos que não serão executados em sandbox, como comandos excluídos, respeitam a regra ask simples `Bash` como de costume. Veja [modos de sandbox](/pt/sandboxing#sandbox-modes) para alterar este comportamento.

360 432 

361<h2 id="managed-settings">433<h2 id="managed-settings">

362 Configurações gerenciadas434 Configurações gerenciadas

platforms.md +1 −1

Details

23| [Web](/pt/claude-code-on-the-web) | Tarefas de longa duração que não precisam de muito direcionamento, ou trabalho que deve continuar quando você estiver offline | Nuvem gerenciada pela Anthropic, continua após você se desconectar |23| [Web](/pt/claude-code-on-the-web) | Tarefas de longa duração que não precisam de muito direcionamento, ou trabalho que deve continuar quando você estiver offline | Nuvem gerenciada pela Anthropic, continua após você se desconectar |

24| Mobile | Iniciar e monitorar tarefas enquanto estiver longe de seu computador | Sessões em nuvem do aplicativo Claude para iOS e Android, [Remote Control](/pt/remote-control) para sessões locais, [Dispatch](/pt/desktop#sessions-from-dispatch) para Desktop em Pro e Max |24| Mobile | Iniciar e monitorar tarefas enquanto estiver longe de seu computador | Sessões em nuvem do aplicativo Claude para iOS e Android, [Remote Control](/pt/remote-control) para sessões locais, [Dispatch](/pt/desktop#sessions-from-dispatch) para Desktop em Pro e Max |

25 25 

26A CLI é a superfície mais completa para trabalho nativo de terminal: scripts e o Agent SDK são apenas CLI. Provedores de terceiros também funcionam em [VS Code](/pt/vs-code#use-third-party-providers). Implantações [Desktop](/pt/desktop) corporativas suportam Vertex AI e provedores de gateway; para Bedrock ou Foundry, use a CLI ou VS Code em vez de Desktop. Desktop e as extensões IDE trocam alguns recursos apenas CLI por revisão visual e integração mais estreita do editor. A web é executada na nuvem da Anthropic, portanto as tarefas continuam após você se desconectar. Mobile é um cliente fino nessas mesmas sessões em nuvem ou em uma sessão local via Remote Control, e pode enviar tarefas para Desktop com Dispatch.26A CLI é a superfície mais completa para trabalho nativo de terminal: scripts e o Agent SDK são apenas CLI. Provedores de terceiros também funcionam em [VS Code](/pt/vs-code#use-third-party-providers). Implantações [Desktop](/pt/desktop) corporativas suportam Vertex AI e provedores de gateway; para Bedrock ou Foundry, use a CLI ou VS Code, ou o [Cowork on 3P research preview](https://claude.com/docs/cowork/3p/overview), que executa a aba Code nesses provedores. Desktop e as extensões IDE trocam alguns recursos apenas CLI por revisão visual e integração mais estreita do editor. A web é executada na nuvem da Anthropic, portanto as tarefas continuam após você se desconectar. Mobile é um cliente fino nessas mesmas sessões em nuvem ou em uma sessão local via Remote Control, e pode enviar tarefas para Desktop com Dispatch.

27 27 

28Você pode misturar superfícies no mesmo projeto. Configuração, memória do projeto e servidores MCP são compartilhados entre as superfícies locais.28Você pode misturar superfícies no mesmo projeto. Configuração, memória do projeto e servidores MCP são compartilhados entre as superfícies locais.

29 29 

plugin-hints.md +7 −4

Details

16 Como funciona16 Como funciona

17</h2>17</h2>

18 18 

19Claude Code define a variável de ambiente [`CLAUDECODE`](/pt/env-vars) como `1` para cada comando que executa através das ferramentas Bash e PowerShell, e para comandos de [hook](/pt/hooks). Quando sua CLI vê essa variável, ela escreve uma tag auto-fechável `<claude-code-hint />` para stderr. Em comandos de hook, a tag de dica é removida e ignorada. Apenas a saída das ferramentas Bash e PowerShell dispara o prompt de instalação.19Claude Code define a variável de ambiente [`CLAUDECODE`](/pt/env-vars) como `1` para cada comando que executa através das ferramentas Bash e PowerShell, e para comandos de [hook](/pt/hooks). {/* min-version: 2.1.172 */}A partir da v2.1.172, também define [`CLAUDE_CODE_CHILD_SESSION`](/pt/env-vars) como `1` nesses mesmos subprocessos. Quando sua CLI vê uma dessas variáveis, ela escreve uma tag auto-fechável `<claude-code-hint />` para stderr. Em comandos de hook, a tag de dica é removida e ignorada. Apenas a saída das ferramentas Bash e PowerShell dispara o prompt de instalação.

20 20 

21Quando Claude Code recebe a saída do comando, ele:21Quando Claude Code recebe a saída do comando, ele:

22 22 


31 Emita a dica31 Emita a dica

32</h2>32</h2>

33 33 

34Gate a emissão na variável de ambiente `CLAUDECODE` para que o marcador nunca apareça no terminal de um usuário humano. Em seguida, escreva a tag para stderr em sua própria linha.34Gate a emissão em uma variável de ambiente para que o marcador seja improvável de aparecer quando um humano executa seu CLI diretamente, depois escreva a tag para stderr em sua própria linha. Escolha qual variável verificar:

35 35 

36Os exemplos a seguir emitem uma dica para um plugin chamado `example-cli` no marketplace oficial:36* `CLAUDECODE`: definida em todas as versões do Claude Code, portanto atinge a maioria das sessões. Também é definida em sessões tmux e subprocessos do servidor MCP stdio que Claude Code inicia. Extensões IDE também a definem em seus terminais integrados, onde um humano pode estar executando seu CLI diretamente.

37* {/* min-version: 2.1.172 */}`CLAUDE_CODE_CHILD_SESSION`: definida apenas em subprocessos que o próprio Claude Code gera, como chamadas de ferramenta, comandos hook e comandos da [linha de status](/pt/statusline), portanto a tag normalmente não atinge um terminal humano. Um processo de longa duração que foi iniciado dentro de uma sessão, como um servidor tmux, captura a variável, portanto shells iniciados posteriormente a partir desse processo ainda mostram a tag bruta. Requer Claude Code v2.1.172 ou posterior, portanto sessões em versões mais antigas perdem a dica.

38 

39Os exemplos a seguir fazem gate em `CLAUDECODE` para máximo alcance e emitem uma dica para um plugin chamado `example-cli` no marketplace oficial:

37 40 

38<CodeGroup>41<CodeGroup>

39 ```javascript Node.js theme={null}42 ```javascript Node.js theme={null}


147As orientações restantes são recomendadas, mas não obrigatórias. Claude Code não pode observar se sua CLI as segue:150As orientações restantes são recomendadas, mas não obrigatórias. Claude Code não pode observar se sua CLI as segue:

148 151 

149* **Escrever para stderr**: stderr mantém a tag fora de pipelines de shell, como `example-cli deploy | jq`. Claude Code verifica ambos os fluxos, portanto stdout também funciona.152* **Escrever para stderr**: stderr mantém a tag fora de pipelines de shell, como `example-cli deploy | jq`. Claude Code verifica ambos os fluxos, portanto stdout também funciona.

150* **Gate em `CLAUDECODE`**: emita apenas quando a variável de ambiente `CLAUDECODE` estiver definida. Isso evita que o marcador apareça para usuários que executam sua CLI diretamente.153* **Gate em uma variável de ambiente**: emita apenas quando `CLAUDECODE` ou `CLAUDE_CODE_CHILD_SESSION` estiver definido. Consulte [Emitir a dica](#emit-the-hint) para saber como as duas variáveis diferem.

151 154 

152<h2 id="get-your-plugin-into-the-official-marketplace">155<h2 id="get-your-plugin-into-the-official-marketplace">

153 Coloque seu plugin no marketplace oficial156 Coloque seu plugin no marketplace oficial

Details

171| `plugins` | array | Lista de plugins disponíveis | Veja abaixo |171| `plugins` | array | Lista de plugins disponíveis | Veja abaixo |

172 172 

173<Note>173<Note>

174 **Nomes reservados**: Os seguintes nomes de marketplace são reservados para uso oficial da Anthropic e não podem ser usados por marketplaces de terceiros: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`. Nomes que imitam marketplaces oficiais, como `official-claude-plugins` ou `anthropic-tools-v2`, também são bloqueados.174 **Nomes reservados**: Os seguintes nomes de marketplace são reservados para uso oficial da Anthropic e não podem ser usados por marketplaces de terceiros: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `claude-plugins-community`, `claude-community`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `anthropic-agent-skills`, `knowledge-work-plugins`, `life-sciences`, `claude-for-legal`, `claude-for-financial-services`, `financial-services-plugins`. Nomes que imitam marketplaces oficiais, como `official-claude-plugins` ou `anthropic-tools-v2`, também são bloqueados.

175</Note>175</Note>

176 176 

177<h3 id="owner-fields">177<h3 id="owner-fields">


269 Por exemplo, um marketplace hospedado em `acme-corp/plugin-catalog` (fonte de marketplace) pode listar um plugin buscado de `acme-corp/code-formatter` (fonte de plugin). A fonte de marketplace e a fonte de plugin apontam para repositórios diferentes e são fixadas independentemente.269 Por exemplo, um marketplace hospedado em `acme-corp/plugin-catalog` (fonte de marketplace) pode listar um plugin buscado de `acme-corp/code-formatter` (fonte de plugin). A fonte de marketplace e a fonte de plugin apontam para repositórios diferentes e são fixadas independentemente.

270</Note>270</Note>

271 271 

272Os tipos de fonte baseados em git abaixo são `github`, `url` e `git-subdir`. Quando tanto `ref` quanto `sha` são definidos em qualquer um deles, o `sha` é o pino efetivo. Claude Code busca e faz checkout do commit fixado diretamente, então a instalação é bem-sucedida mesmo se o branch ou tag nomeado por `ref` tenha sido deletado upstream, desde que o commit ainda seja alcançável a partir do repositório.

273 

272<h3 id="relative-paths">274<h3 id="relative-paths">

273 Caminhos relativos275 Caminhos relativos

274</h3>276</h3>


505* **`${CLAUDE_PLUGIN_ROOT}`**: use esta variável em hooks e configurações de MCP server para referenciar arquivos dentro do diretório de instalação do plugin. Isso é necessário porque os plugins são copiados para um local de cache quando instalados. Para dependências ou estado que devem sobreviver a atualizações de plugin, use [`${CLAUDE_PLUGIN_DATA}`](/pt/plugins-reference#persistent-data-directory) em vez disso.507* **`${CLAUDE_PLUGIN_ROOT}`**: use esta variável em hooks e configurações de MCP server para referenciar arquivos dentro do diretório de instalação do plugin. Isso é necessário porque os plugins são copiados para um local de cache quando instalados. Para dependências ou estado que devem sobreviver a atualizações de plugin, use [`${CLAUDE_PLUGIN_DATA}`](/pt/plugins-reference#persistent-data-directory) em vez disso.

506* **`strict: false`**: Como isso está definido como false, o plugin não precisa de seu próprio `plugin.json`. A entrada de marketplace define tudo. Veja [Strict mode](#strict-mode) abaixo.508* **`strict: false`**: Como isso está definido como false, o plugin não precisa de seu próprio `plugin.json`. A entrada de marketplace define tudo. Veja [Strict mode](#strict-mode) abaixo.

507 509 

510Por padrão, as skills de um plugin são carregadas do diretório `skills/` sob sua `source`, e quaisquer caminhos listados sob `skills` adicionam a essa varredura. A exceção é uma fonte de raiz de marketplace como `source: "./"`, onde várias entradas de plugin compartilham uma pasta `skills/`. Nesse caso, listar subdiretórios específicos sob `skills` torna essa lista o conjunto completo para a entrada, e outros diretórios sob `skills/` não são carregados. Listar o próprio diretório `skills/` ou a raiz do plugin mantém a varredura completa. Se nenhum dos caminhos listados existir, a varredura padrão é executada em vez disso.

511 

508<h3 id="strict-mode">512<h3 id="strict-mode">

509 Strict mode513 Strict mode

510</h3>514</h3>


1074* Verifique se os diretórios de plugin contêm arquivos obrigatórios1078* Verifique se os diretórios de plugin contêm arquivos obrigatórios

1075* Para fontes GitHub, garanta que repositórios são públicos ou você tem acesso1079* Para fontes GitHub, garanta que repositórios são públicos ou você tem acesso

1076* Teste fontes de plugin manualmente clonando/baixando1080* Teste fontes de plugin manualmente clonando/baixando

1081* Se a fonte fixa tanto `ref` quanto `sha`, uma branch ou tag upstream deletada não bloqueia a instalação. Se a instalação ainda falhar, confirme que o commit fixado ainda existe no repositório

1077 1082 

1078<h3 id="private-repository-authentication-fails">1083<h3 id="private-repository-authentication-fails">

1079 Falha de autenticação de repositório privado1084 Falha de autenticação de repositório privado

plugins.md +8 −4

Details

216| `bin/` | Raiz do plugin | Executáveis adicionados ao `PATH` da ferramenta Bash enquanto o plugin está habilitado |216| `bin/` | Raiz do plugin | Executáveis adicionados ao `PATH` da ferramenta Bash enquanto o plugin está habilitado |

217| `settings.json` | Raiz do plugin | [Configurações](/pt/settings) padrão aplicadas quando o plugin é habilitado |217| `settings.json` | Raiz do plugin | [Configurações](/pt/settings) padrão aplicadas quando o plugin é habilitado |

218 218 

219Um plugin que fornece exatamente um skill pode colocar `SKILL.md` diretamente na raiz do plugin em vez de criar um diretório `skills/`. Claude Code o carrega como um único skill e usa o campo `name` do frontmatter para o nome de invocação. Use o layout `skills/` para plugins que podem crescer para mais de um skill.

220 

219<Note>221<Note>

220 **Próximos passos**: Pronto para adicionar mais recursos? Vá para [Desenvolver plugins mais complexos](#develop-more-complex-plugins) para adicionar agents, hooks, MCP servers e LSP servers. Para especificações técnicas completas de todos os componentes do plugin, veja [Referência de plugins](/pt/plugins-reference).222 **Próximos passos**: Pronto para adicionar mais recursos? Vá para [Desenvolver plugins mais complexos](#develop-more-complex-plugins) para adicionar agents, hooks, MCP servers e LSP servers. Para especificações técnicas completas de todos os componentes do plugin, veja [Referência de plugins](/pt/plugins-reference).

221</Note>223</Note>


402 404 

403A Anthropic mantém dois marketplaces públicos para plugins do Claude Code:405A Anthropic mantém dois marketplaces públicos para plugins do Claude Code:

404 406 

405* **`claude-plugins-official`**: um conjunto curado de plugins mantidos pela Anthropic. Disponível automaticamente em toda instalação do Claude Code.407* **`claude-plugins-official`**: um conjunto curado de plugins mantidos pela Anthropic. Registrado automaticamente na primeira vez que você inicia Claude Code interativamente. Um script não-interativo que é executado antes desse primeiro lançamento deve adicioná-lo explicitamente com `claude plugin marketplace add anthropics/claude-plugins-official`.

406* **`claude-community`**: o marketplace público da comunidade onde envios de terceiros chegam após revisão. Os usuários o adicionam com `/plugin marketplace add anthropics/claude-plugins-community` e instalam a partir dele como `@claude-community`.408* **`claude-community`**: o marketplace público da comunidade onde envios de terceiros chegam após revisão. Os usuários o adicionam com `/plugin marketplace add anthropics/claude-plugins-community` e instalam a partir dele como `@claude-community`.

407 409 

408Para enviar seu plugin para revisão do marketplace da comunidade, use um dos formulários no aplicativo:410Para enviar seu plugin para revisão do marketplace da comunidade, use um dos formulários no aplicativo:

409 411 

410* **Claude.ai**: [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit)412* **claude.ai**: [claude.ai/admin-settings/directory/submissions/plugins/new](https://claude.ai/admin-settings/directory/submissions/plugins/new)

411* **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)413* **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)

412 414 

415O formulário claude.ai requer uma organização Team ou Enterprise e acesso ao gerenciamento de diretório; proprietários de organização têm esse acesso por padrão. Autores individuais que não fazem parte de uma organização Team ou Enterprise podem usar o formulário Console em vez disso.

416 

413Execute `claude plugin validate` localmente antes de enviar. O pipeline de revisão executa a mesma verificação em cada envio, junto com triagem de segurança automatizada.417Execute `claude plugin validate` localmente antes de enviar. O pipeline de revisão executa a mesma verificação em cada envio, junto com triagem de segurança automatizada.

414 418 

415Plugins aprovados são fixados a um SHA de commit específico no catálogo [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community), e CI aumenta o pino automaticamente conforme você envia novos commits para seu repositório. O catálogo público sincroniza todas as noites a partir do pipeline de revisão, então pode haver um atraso entre aprovação e seu plugin aparecer em `marketplace.json`. Para verificar se seu plugin já é instalável, procure por seu nome no [catálogo da comunidade](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json).419Plugins aprovados são fixados a um SHA de commit específico no catálogo [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community), e CI aumenta o pino automaticamente conforme você envia novos commits para seu repositório. O catálogo público sincroniza todas as noites a partir do pipeline de revisão, então pode haver um atraso entre aprovação e seu plugin aparecer em `marketplace.json`. Para verificar se seu plugin já é instalável, procure por seu nome no [catálogo da comunidade](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json).


496 claude --plugin-dir ./my-plugin500 claude --plugin-dir ./my-plugin

497 ```501 ```

498 502 

499 Teste cada componente: execute seus skills, verifique que agents aparecem em `/agents` e verifique que hooks disparam corretamente.503 Teste cada componente: execute seus comandos, verifique que agents aparecem em `/agents` e verifique que hooks disparam corretamente.

500 </Step>504 </Step>

501</Steps>505</Steps>

502 506 


512| Deve copiar manualmente para compartilhar | Instale com `/plugin install` |516| Deve copiar manualmente para compartilhar | Instale com `/plugin install` |

513 517 

514<Note>518<Note>

515 Após migrar, você pode remover os arquivos originais de `.claude/` para evitar duplicatas. A versão do plugin terá precedência quando carregada.519 Após migrar, remova os arquivos originais de `.claude/` para evitar duplicatas. As definições de agents em `.claude/agents/` do projeto e do usuário substituem agents com o mesmo nome do plugin, portanto a versão do plugin entra em vigor uma vez que os originais são removidos.

516</Note>520</Note>

517 521 

518<h2 id="next-steps">522<h2 id="next-steps">

Details

46* Claude pode invocá-los automaticamente com base no contexto da tarefa46* Claude pode invocá-los automaticamente com base no contexto da tarefa

47* Skills podem incluir arquivos de suporte ao lado de SKILL.md47* Skills podem incluir arquivos de suporte ao lado de SKILL.md

48 48 

49Se um plugin não tem diretório `skills/` e nenhum campo manifest `skills`, um `SKILL.md` na raiz do plugin é carregado como uma única skill. Defina o campo frontmatter `name` para controlar o nome de invocação da skill. Sem ele, Claude Code volta para o nome do diretório de instalação, que para plugins instalados do marketplace é uma string de versão que muda a cada atualização. Para plugins que fornecem mais de uma skill, use o layout de diretório `skills/` mostrado acima.

50 

49Para detalhes completos, veja [Skills](/pt/skills).51Para detalhes completos, veja [Skills](/pt/skills).

50 52 

51<h3 id="agents">53<h3 id="agents">


256**Campos opcionais:**258**Campos opcionais:**

257 259 

258| Campo | Descrição |260| Campo | Descrição |

259| :---------------------- | :------------------------------------------------------------------- |261| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

260| `args` | Argumentos de linha de comando para o servidor LSP |262| `args` | Argumentos de linha de comando para o servidor LSP |

261| `transport` | Transporte de comunicação: `stdio` (padrão) ou `socket` |263| `transport` | Transporte de comunicação: `stdio` (padrão) ou `socket` |

262| `env` | Variáveis de ambiente a definir ao iniciar o servidor |264| `env` | Variáveis de ambiente a definir ao iniciar o servidor |


265| `workspaceFolder` | Caminho da pasta de workspace para o servidor |267| `workspaceFolder` | Caminho da pasta de workspace para o servidor |

266| `startupTimeout` | Tempo máximo para aguardar inicialização do servidor (milissegundos) |268| `startupTimeout` | Tempo máximo para aguardar inicialização do servidor (milissegundos) |

267| `maxRestarts` | Número máximo de tentativas de reinicialização antes de desistir |269| `maxRestarts` | Número máximo de tentativas de reinicialização antes de desistir |

270| `diagnostics` | Se deve enviar diagnósticos para o contexto de Claude após edições (padrão `true`). Defina como `false` para manter navegação de código mas suprimir injeção automática de diagnósticos. |

268 271 

269<Warning>272<Warning>

270 **Você deve instalar o binário do servidor de linguagem separadamente.** Plugins LSP configuram como Claude Code se conecta a um servidor de linguagem, mas não incluem o servidor em si. Se você vir `Executable not found in $PATH` na aba Errors do `/plugin`, instale o binário necessário para sua linguagem.273 **Você deve instalar o binário do servidor de linguagem separadamente.** Plugins LSP configuram como Claude Code se conecta a um servidor de linguagem, mas não incluem o servidor em si. Se você vir `Executable not found in $PATH` na aba Errors do `/plugin`, instale o binário necessário para sua linguagem.


530</h3>533</h3>

531 534 

532| Campo | Tipo | Descrição | Exemplo |535| Campo | Tipo | Descrição | Exemplo |

533| :---------------------- | :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |536| :---------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

534| `skills` | string\|array | Diretórios de skill personalizados contendo `<name>/SKILL.md` (além do padrão `skills/`) | `"./custom/skills/"` |537| `skills` | string\|array | Diretórios de skill personalizados contendo `<name>/SKILL.md`. Adiciona ao padrão `skills/`. Veja [Regras de comportamento de caminho](#path-behavior-rules) para a exceção de raiz do marketplace | `"./custom/skills/"` |

535| `commands` | string\|array | Arquivos de skill `.md` planos personalizados ou diretórios (substitui padrão `commands/`) | `"./custom/cmd.md"` ou `["./cmd1.md"]` |538| `commands` | string\|array | Arquivos de skill `.md` planos personalizados ou diretórios (substitui padrão `commands/`) | `"./custom/cmd.md"` ou `["./cmd1.md"]` |

536| `agents` | string\|array | Arquivos de agent personalizados (substitui padrão `agents/`) | `"./custom/agents/reviewer.md"` |539| `agents` | string\|array | Arquivos de agent personalizados (substitui padrão `agents/`) | `"./custom/agents/reviewer.md"` |

537| `hooks` | string\|array\|object | Caminhos de configuração de hooks ou configuração inline | `"./my-extra-hooks.json"` |540| `hooks` | string\|array\|object | Caminhos de configuração de hooks ou configuração inline | `"./my-extra-hooks.json"` |


629Se um caminho personalizado substitui ou estende o diretório padrão do plugin depende do campo:632Se um caminho personalizado substitui ou estende o diretório padrão do plugin depende do campo:

630 633 

631* **Substitui o padrão**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. Por exemplo, quando o manifesto especifica `commands`, o diretório padrão `commands/` não é verificado. Para manter o padrão e adicionar mais, liste-o explicitamente: `"commands": ["./commands/", "./extras/"]`634* **Substitui o padrão**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. Por exemplo, quando o manifesto especifica `commands`, o diretório padrão `commands/` não é verificado. Para manter o padrão e adicionar mais, liste-o explicitamente: `"commands": ["./commands/", "./extras/"]`

632* **Adiciona ao padrão**: `skills`. O diretório padrão `skills/` é sempre verificado, e diretórios listados em `skills` são carregados junto com ele635* **Adiciona ao padrão**: `skills`. O diretório padrão `skills/` é sempre verificado, e diretórios listados em `skills` são carregados junto com ele. Exceção: para uma [entrada do marketplace cuja `source` resolve para a raiz do marketplace](/pt/plugin-marketplaces#advanced-plugin-entries), declarar subdiretórios específicos substitui a verificação

633* **Regras de mesclagem próprias**: [hooks](#hooks), [MCP servers](#mcp-servers) e [LSP servers](#lsp-servers). Veja cada seção para como múltiplas fontes se combinam636* **Regras de mesclagem próprias**: [hooks](#hooks), [MCP servers](#mcp-servers) e [LSP servers](#lsp-servers). Veja cada seção para como múltiplas fontes se combinam

634 637 

635Quando um plugin tem tanto uma pasta padrão quanto a chave de manifesto correspondente, Claude Code v2.1.140 e posterior sinaliza a pasta ignorada em `/doctor`, `claude plugin list` e a visualização de detalhes `/plugin`. O plugin ainda carrega usando os caminhos do manifesto. Nenhum aviso é mostrado quando a chave de manifesto aponta para a pasta padrão, por exemplo `"commands": ["./commands/deploy.md"]`, porque a pasta é abordada explicitamente nesse caso.638Quando um plugin tem tanto uma pasta padrão quanto a chave de manifesto correspondente, Claude Code v2.1.140 e posterior sinaliza a pasta ignorada em `/doctor`, `claude plugin list` e a visualização de detalhes `/plugin`. O plugin ainda carrega usando os caminhos do manifesto. Nenhum aviso é mostrado quando a chave de manifesto aponta para a pasta padrão, por exemplo `"commands": ["./commands/deploy.md"]`, porque a pasta é abordada explicitamente nesse caso.


1093| `--available` | Incluir plugins disponíveis de marketplaces. Requer `--json` | |1096| `--available` | Incluir plugins disponíveis de marketplaces. Requer `--json` | |

1094| `-h, --help` | Exibir ajuda para comando | |1097| `-h, --help` | Exibir ajuda para comando | |

1095 1098 

1099Dentro de uma sessão interativa, `/plugin list` imprime a mesma listagem inline. O formulário interativo aceita `--enabled` ou `--disabled` para mostrar apenas plugins nesse estado, e `ls` como abreviação para `list`.

1100 

1096<h3 id="plugin-details">1101<h3 id="plugin-details">

1097 plugin details1102 plugin details

1098</h3>1103</h3>

Details

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`](/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á.

83 

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

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

84</h3>86</h3>


101 Conectar ou desconectar um servidor MCP103 Conectar ou desconectar um servidor MCP

102</h3>104</h3>

103 105 

104As 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. 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:106As 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:

105 107 

106* **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.108* **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.

107* **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).109* **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).


118 120 

119A 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.121A 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.

120 122 

121As 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`.123As 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.

122 124 

123Desativar 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.125Desativar 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.

124 126 


128 130 

129Adicionar 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).131Adicionar 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).

130 132 

131Apenas um nome de ferramenta simples, ou a forma equivalente `Bash(*)`, tem esse efeito. 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.133Apenas 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.

132 134 

133<h3 id="compacting-the-conversation">135<h3 id="compacting-the-conversation">

134 Compactar a conversa136 Compactar a conversa


290| `DISABLE_PROMPT_CACHING_HAIKU` | Desabilitar para Haiku apenas |292| `DISABLE_PROMPT_CACHING_HAIKU` | Desabilitar para Haiku apenas |

291| `DISABLE_PROMPT_CACHING_SONNET` | Desabilitar para Sonnet apenas |293| `DISABLE_PROMPT_CACHING_SONNET` | Desabilitar para Sonnet apenas |

292| `DISABLE_PROMPT_CACHING_OPUS` | Desabilitar para Opus apenas |294| `DISABLE_PROMPT_CACHING_OPUS` | Desabilitar para Opus apenas |

295| `DISABLE_PROMPT_CACHING_FABLE` | Desabilitar para Fable apenas |

293 296 

294Para 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.297Para 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.

295 298 

quickstart.md +12 −5

Details

118claude118claude

119```119```

120 120 

121Você verá a tela de boas-vindas do Claude Code com as informações da sua sessão, conversas recentes e atualizações mais recentes. Digite `/help` para comandos disponíveis ou `/resume` para continuar uma conversa anterior.121Você verá o prompt do Claude Code com a versão, modelo atual e diretório de trabalho mostrados acima. Digite `/help` para comandos disponíveis ou `/resume` para continuar uma conversa anterior.

122 122 

123<Tip>123<Tip>

124 Depois de fazer login (Passo 2), suas credenciais são armazenadas em seu sistema. Saiba mais em [Gerenciamento de Credenciais](/pt/authentication#credential-management).124 Depois de fazer login (Passo 2), suas credenciais são armazenadas em seu sistema. Saiba mais em [Gerenciamento de Credenciais](/pt/authentication#credential-management).


278 Comandos essenciais278 Comandos essenciais

279</h2>279</h2>

280 280 

281Aqui estão os comandos mais importantes para uso diário:281Aqui estão os comandos mais importantes para uso diário. Comandos shell são executados a partir do seu terminal para iniciar ou retomar Claude Code. Comandos de sessão são executados dentro do Claude Code após ele iniciar.

282 

283**Comandos shell**

282 284 

283| Comando | O que faz | Exemplo |285| Comando | O que faz | Exemplo |

284| ------------------- | -------------------------------------------------- | ----------------------------------- |286| ------------------- | -------------------------------------------------- | ----------------------------------- |


287| `claude -p "query"` | Executar consulta única, depois sair | `claude -p "explain this function"` |289| `claude -p "query"` | Executar consulta única, depois sair | `claude -p "explain this function"` |

288| `claude -c` | Continuar conversa mais recente no diretório atual | `claude -c` |290| `claude -c` | Continuar conversa mais recente no diretório atual | `claude -c` |

289| `claude -r` | Retomar uma conversa anterior | `claude -r` |291| `claude -r` | Retomar uma conversa anterior | `claude -r` |

292 

293**Comandos de sessão**

294 

295| Comando | O que faz | Exemplo |

296| ----------------- | ---------------------------- | -------- |

290| `/clear` | Limpar histórico de conversa | `/clear` |297| `/clear` | Limpar histórico de conversa | `/clear` |

291| `/help` | Mostrar comandos disponíveis | `/help` |298| `/help` | Mostrar comandos disponíveis | `/help` |

292| `exit` ou Ctrl+D | Sair do Claude Code | `exit` |299| `/exit` ou Ctrl+D | Sair do Claude Code | `/exit` |

293 300 

294Veja a [referência CLI](/pt/cli-reference) para uma lista completa de comandos.301Veja a [referência CLI](/pt/cli-reference) para a lista completa de comandos shell e a [referência de comandos](/pt/commands) para a lista completa de comandos de sessão.

295 302 

296<h2 id="pro-tips-for-beginners">303<h2 id="pro-tips-for-beginners">

297 Dicas profissionais para iniciantes304 Dicas profissionais para iniciantes


336 </Accordion>343 </Accordion>

337</AccordionGroup>344</AccordionGroup>

338 345 

339<h2 id="what-s-next">346<h2 id="whats-next">

340 Próximos passos347 Próximos passos

341</h2>348</h2>

342 349 

remote-control.md +21 −10

Details

93 /remote-control My Project93 /remote-control My Project

94 ```94 ```

95 95 

96 Isso inicia uma sessão de Remote Control que carrega seu histórico de conversa atual e exibe uma URL de sessão e código QR que você pode usar para [conectar de outro dispositivo](#connect-from-another-device). As flags `--verbose`, `--sandbox` e `--no-sandbox` não estão disponíveis com este comando.96 Isso inicia uma sessão de Remote Control que carrega seu histórico de conversa atual.

97 

98 As flags `--verbose`, `--sandbox` e `--no-sandbox` não estão disponíveis com este comando.

97 </Tab>99 </Tab>

98 100 

99 <Tab title="VS Code">101 <Tab title="VS Code">


111 </Tab>113 </Tab>

112</Tabs>114</Tabs>

113 115 

116<h3 id="check-connection-status">

117 Verificar status da conexão

118</h3>

119 

120Em uma sessão de terminal interativa, um indicador `/rc active` fica no rodapé abaixo da caixa de entrada enquanto a conexão está ativa, e fica oculto se o terminal for muito estreito para ajustá-lo. O texto do indicador é um link para a sessão em claude.ai. Selecione-o com a tecla de seta para baixo e pressione Enter, ou execute `/remote-control` novamente, para abrir um painel de status com a URL da sessão e um código QR que você pode usar para [conectar de outro dispositivo](#connect-from-another-device).

121 

122Se a conexão falhar, o indicador fica vermelho e lê `/rc failed`. Selecione-o com a tecla de seta para baixo e pressione Enter para ver o motivo da falha e uma opção de descartar, ou execute `/remote-control` novamente para tentar novamente.

123 

114<h3 id="connect-from-another-device">124<h3 id="connect-from-another-device">

115 Conectar de outro dispositivo125 Conectar de outro dispositivo

116</h3>126</h3>


1283. A última mensagem significativa no histórico de conversa existente1383. A última mensagem significativa no histórico de conversa existente

1294. Um nome gerado automaticamente como `myhost-graceful-unicorn`, onde `myhost` é o nome do host da sua máquina ou o prefixo que você definiu com `--remote-control-session-name-prefix`1394. Um nome gerado automaticamente como `myhost-graceful-unicorn`, onde `myhost` é o nome do host da sua máquina ou o prefixo que você definiu com `--remote-control-session-name-prefix`

130 140 

131Se você não definir um nome explícito, o título será atualizado para refletir seu prompt assim que você enviar um. Renomear uma sessão a partir de claude.ai ou do aplicativo Claude também atualiza o título local mostrado em `claude --resume`.141Se você não definir um nome explícito, o título será atualizado para refletir seu prompt assim que você enviar um. {/* min-version: 2.1.176 */}A partir da Claude Code v2.1.176, títulos gerados automaticamente correspondem ao idioma da sua conversa, ou à configuração [`language`](/pt/settings#available-settings) se uma estiver configurada. Renomear uma sessão a partir de claude.ai ou do aplicativo Claude também atualiza o título local mostrado em `claude --resume`.

132 142 

133Se o ambiente já tiver uma sessão ativa, você será perguntado se deseja continuá-la ou iniciar uma nova.143Se o ambiente já tiver uma sessão ativa, você será perguntado se deseja continuá-la ou iniciar uma nova.

134 144 


164 174 

165Quando Remote Control está ativo, Claude pode enviar notificações push para seu telefone.175Quando Remote Control está ativo, Claude pode enviar notificações push para seu telefone.

166 176 

167Claude decide quando fazer push. Normalmente envia uma quando uma tarefa de longa duração termina ou quando precisa de uma decisão sua para continuar. Você também pode solicitar um push em seu prompt, por exemplo `notify me when the tests finish`. Além do toggle on/off abaixo, não há configuração por evento.177Claude decide quando fazer push. Normalmente envia uma quando uma tarefa de longa duração termina ou quando precisa de uma decisão sua para continuar. Você também pode solicitar um push em seu prompt, por exemplo `notify me when the tests finish`. Além dos dois toggles on/off abaixo, não há configuração por evento.

168 178 

169<Note>179<Note>

170 Notificações push móveis requerem Claude Code v2.1.110 ou posterior.180 Notificações push móveis requerem Claude Code v2.1.110 ou posterior.


186 </Step>196 </Step>

187 197 

188 <Step title="Ative push no Claude Code">198 <Step title="Ative push no Claude Code">

189 No seu terminal, execute `/config` e ative **Push when Claude decides**.199 No seu terminal, execute `/config` e ative **Push when Claude decides** para notificações proativas, **Push when actions required** para prompts de permissão e perguntas, ou ambas.

190 </Step>200 </Step>

191</Steps>201</Steps>

192 202 


204* **O processo local deve continuar em execução**: Remote Control é executado como um processo local. Se você fechar o terminal, sair do VS Code ou parar o processo `claude`, a sessão termina.214* **O processo local deve continuar em execução**: Remote Control é executado como um processo local. Se você fechar o terminal, sair do VS Code ou parar o processo `claude`, a sessão termina.

205* **Interrupção de rede estendida**: se sua máquina estiver ligada mas não conseguir alcançar a rede por mais de aproximadamente 10 minutos, a sessão expira e o processo sai. Execute `claude remote-control` novamente para iniciar uma nova sessão.215* **Interrupção de rede estendida**: se sua máquina estiver ligada mas não conseguir alcançar a rede por mais de aproximadamente 10 minutos, a sessão expira e o processo sai. Execute `claude remote-control` novamente para iniciar uma nova sessão.

206* **Ultraplan desconecta Remote Control**: iniciar uma sessão [ultraplan](/pt/ultraplan) desconecta qualquer sessão de Remote Control ativa porque ambos os recursos ocupam a interface claude.ai/code e apenas um pode estar conectado por vez.216* **Ultraplan desconecta Remote Control**: iniciar uma sessão [ultraplan](/pt/ultraplan) desconecta qualquer sessão de Remote Control ativa porque ambos os recursos ocupam a interface claude.ai/code e apenas um pode estar conectado por vez.

207* **Alguns comandos são apenas locais**: comandos que abrem um seletor interativo no terminal, como `/mcp`, `/plugin` ou `/resume`, funcionam apenas a partir da CLI local. Comandos que produzem saída de texto, incluindo `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap` e `/reload-plugins`, funcionam a partir de dispositivos móveis e web.217* **Alguns comandos são apenas locais**: comandos que abrem um seletor interativo no terminal, como `/plugin` ou `/resume`, funcionam apenas a partir da CLI local. Comandos que produzem saída de texto, incluindo `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap` e `/reload-plugins`, funcionam a partir de dispositivos móveis e web. {/* min-version: 2.1.166 */}A partir da v2.1.166, `/mcp` também funciona a partir de dispositivos móveis e web: ele retorna um resumo de texto do status do servidor em vez de abrir o seletor, e aceita os mesmos [subcomandos](/pt/commands#all-commands) da CLI local, com uma diferença: a partir de dispositivos móveis e web, `/mcp reconnect` sem nome de servidor reconecta todos os servidores que falharam ou precisam de autenticação, enquanto a CLI local requer um nome de servidor para `reconnect`.

208 218 

209<h2 id="troubleshooting">219<h2 id="troubleshooting">

210 Solução de problemas220 Solução de problemas


232 "Remote Control is not yet enabled for your account"242 "Remote Control is not yet enabled for your account"

233</h3>243</h3>

234 244 

235A verificação de elegibilidade pode falhar com certas variáveis de ambiente presentes:245A verificação de Remote Control não atingiu sua conta, ou seus direitos em cache estão desatualizados. Se você mudou de plano recentemente, execute `claude auth logout` e depois `claude auth login` para atualizá-los. Execute `claude doctor` para ver qual verificação de elegibilidade individual falhou. Conflitos de variáveis de ambiente, verificações inacessíveis e política organizacional cada um produzem sua própria mensagem, então este erro significa o próprio portão de verificação.

236 246 

237* `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` ou `DISABLE_TELEMETRY`: desative-as e tente novamente.247<h3 id="couldn’t-verify-remote-control-eligibility">

238* `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX` ou `CLAUDE_CODE_USE_FOUNDRY`: Remote Control requer autenticação claude.ai e não funciona com provedores de terceiros.248 "Couldn't verify Remote Control eligibility"

249</h3>

239 250 

240Se nenhuma delas estiver definida, execute `/logout` e depois `/login` para atualizar.251Claude Code não conseguiu alcançar o serviço de sinalizador de recurso para verificar se Remote Control está habilitado para sua conta, normalmente porque você está offline ou um proxy está bloqueando a solicitação. Tente novamente quando tiver acesso à rede, ou execute `claude doctor` para obter detalhes. A mensagem relacionada "Couldn't verify your organization's Remote Control policy" tem a mesma causa e a mesma solução. Ambas as mensagens foram adicionadas na v2.1.178.

241 252 

242<h3 id="remote-control-is-disabled-by-your-organization-s-policy">253<h3 id="remote-control-is-disabled-by-your-organizations-policy">

243 "Remote Control is disabled by your organization's policy"254 "Remote Control is disabled by your organization's policy"

244</h3>255</h3>

245 256 

routines.md +76 −26

Details

26 26 

27Esta página aborda a criação de uma rotina, a configuração de cada tipo de acionador, o gerenciamento de execuções e como os limites de uso se aplicam.27Esta página aborda a criação de uma rotina, a configuração de cada tipo de acionador, o gerenciamento de execuções e como os limites de uso se aplicam.

28 28 

29## Exemplos de casos de uso29<h2 id="example-use-cases">

30 Exemplos de casos de uso

31</h2>

30 32 

31Cada exemplo emparelha um tipo de acionador com o tipo de trabalho para o qual as rotinas são adequadas: sem supervisão, repetível e vinculado a um resultado claro.33Cada exemplo emparelha um tipo de acionador com o tipo de trabalho para o qual as rotinas são adequadas: sem supervisão, repetível e vinculado a um resultado claro.

32 34 


44 46 

45As seções abaixo descrevem como criar uma rotina e configurar cada um desses tipos de acionadores.47As seções abaixo descrevem como criar uma rotina e configurar cada um desses tipos de acionadores.

46 48 

47## Criar uma rotina49<h2 id="create-a-routine">

50 Criar uma rotina

51</h2>

48 52 

49Crie uma rotina a partir da web em [claude.ai/code/routines](https://claude.ai/code/routines), do aplicativo Desktop ou da CLI. Todas as três superfícies escrevem na mesma conta em nuvem, portanto uma rotina que você cria em uma aparece nas outras imediatamente. No aplicativo Desktop, clique em **Routines** na barra lateral, depois em **New routine**, e escolha **Remote**; escolher **Local** em vez disso cria uma [tarefa agendada do Desktop](/pt/desktop-scheduled-tasks), que é executada em sua máquina em vez de na nuvem.53Crie uma rotina a partir da web em [claude.ai/code/routines](https://claude.ai/code/routines), do aplicativo Desktop ou da CLI. Todas as três superfícies escrevem na mesma conta em nuvem, portanto uma rotina que você cria em uma aparece nas outras imediatamente. No aplicativo Desktop, clique em **Routines** na barra lateral, depois em **New routine**, e escolha **Remote**; escolher **Local** em vez disso cria uma [tarefa agendada do Desktop](/pt/desktop-scheduled-tasks), que é executada em sua máquina em vez de na nuvem.

50 54 


54 58 

55As rotinas pertencem à sua conta individual claude.ai. Elas não são compartilhadas com colegas de equipe e contam contra a permissão de execução diária da sua conta. Qualquer coisa que uma rotina faz através de sua identidade do GitHub conectada ou conectores aparece como você: commits e pull requests carregam seu usuário do GitHub, e mensagens do Slack, tickets do Linear ou outras ações de conector usam suas contas vinculadas para esses serviços.59As rotinas pertencem à sua conta individual claude.ai. Elas não são compartilhadas com colegas de equipe e contam contra a permissão de execução diária da sua conta. Qualquer coisa que uma rotina faz através de sua identidade do GitHub conectada ou conectores aparece como você: commits e pull requests carregam seu usuário do GitHub, e mensagens do Slack, tickets do Linear ou outras ações de conector usam suas contas vinculadas para esses serviços.

56 60 

57### Criar a partir da web61<h3 id="create-from-the-web">

62 Criar a partir da web

63</h3>

58 64 

59<Steps>65<Steps>

60 <Step title="Abrir o formulário de criação">66 <Step title="Abrir o formulário de criação">


114 </Step>120 </Step>

115</Steps>121</Steps>

116 122 

117### Criar a partir da CLI123<h3 id="create-from-the-cli">

124 Criar a partir da CLI

125</h3>

118 126 

119Execute `/schedule` em qualquer sessão para criar uma rotina agendada conversacionalmente. Você também pode passar uma descrição diretamente, para uma rotina recorrente como `/schedule daily PR review at 9am` ou uma única como `/schedule clean up feature flag in one week`. Claude percorre as mesmas informações que o formulário web coleta e salva a rotina em sua conta.127Execute `/schedule` em qualquer sessão para criar uma rotina agendada conversacionalmente. Você também pode passar uma descrição diretamente, para uma rotina recorrente como `/schedule daily PR review at 9am` ou uma única como `/schedule clean up feature flag in one week`. Claude percorre as mesmas informações que o formulário web coleta e salva a rotina em sua conta.

120 128 


122 130 

123A CLI também suporta o gerenciamento de rotinas existentes. Execute `/schedule list` para ver todas as rotinas, `/schedule update` para alterar uma ou `/schedule run` para acioná-la imediatamente.131A CLI também suporta o gerenciamento de rotinas existentes. Execute `/schedule list` para ver todas as rotinas, `/schedule update` para alterar uma ou `/schedule run` para acioná-la imediatamente.

124 132 

125## Configurar acionadores133<h2 id="configure-triggers">

134 Configurar acionadores

135</h2>

126 136 

127Uma rotina inicia quando um de seus acionadores corresponde. Você pode anexar qualquer combinação de cronograma, API e acionadores do GitHub à mesma rotina e adicioná-los ou removê-los a qualquer momento na seção **Selecionar um acionador** do formulário de edição da rotina.137Uma rotina inicia quando um de seus acionadores corresponde. Você pode anexar qualquer combinação de cronograma, API e acionadores do GitHub à mesma rotina e adicioná-los ou removê-los a qualquer momento na seção **Selecionar um acionador** do formulário de edição da rotina.

128 138 

129### Adicionar um acionador de cronograma139<h3 id="add-a-schedule-trigger">

140 Adicionar um acionador de cronograma

141</h3>

130 142 

131Um acionador de cronograma executa a rotina em uma cadência recorrente ou uma única vez em um momento futuro específico. Escolha uma frequência predefinida na seção **Selecionar um acionador**: horária, diária, dias da semana ou semanal. Os horários são inseridos em seu fuso horário local e convertidos automaticamente, portanto a rotina é executada naquele horário de parede independentemente de onde a infraestrutura em nuvem está localizada.143Um acionador de cronograma executa a rotina em uma cadência recorrente ou uma única vez em um momento futuro específico. Escolha uma frequência predefinida na seção **Selecionar um acionador**: horária, diária, dias da semana ou semanal. Os horários são inseridos em seu fuso horário local e convertidos automaticamente, portanto a rotina é executada naquele horário de parede independentemente de onde a infraestrutura em nuvem está localizada.

132 144 


134 146 

135Para um intervalo personalizado, como a cada duas horas ou no primeiro de cada mês, escolha a predefinição mais próxima no formulário e execute `/schedule update` na CLI para definir uma expressão cron específica. O intervalo mínimo é uma hora; expressões que são executadas com mais frequência são rejeitadas.147Para um intervalo personalizado, como a cada duas horas ou no primeiro de cada mês, escolha a predefinição mais próxima no formulário e execute `/schedule update` na CLI para definir uma expressão cron específica. O intervalo mínimo é uma hora; expressões que são executadas com mais frequência são rejeitadas.

136 148 

137#### Agendar uma execução única149<h4 id="schedule-a-one-off-run">

150 Agendar uma execução única

151</h4>

138 152 

139Um cronograma único dispara a rotina uma única vez em um timestamp específico. Use-o para lembrá-lo mais tarde na semana, para abrir um PR de limpeza após um rollout terminar ou para iniciar uma tarefa de acompanhamento quando uma mudança upstream chegar. Após a rotina disparar, ela se desativa automaticamente e a interface web a marca como **Executada**. Para executá-la novamente, edite a rotina e defina um novo horário único.153Um cronograma único dispara a rotina uma única vez em um timestamp específico. Use-o para lembrá-lo mais tarde na semana, para abrir um PR de limpeza após um rollout terminar ou para iniciar uma tarefa de acompanhamento quando uma mudança upstream chegar. Após a rotina disparar, ela se desativa automaticamente e a interface web a marca como **Executada**. Para executá-la novamente, edite a rotina e defina um novo horário único.

140 154 


152 166 

153As execuções únicas não contam contra o limite diário de execução de rotina. Elas consomem o uso de assinatura regular do seu plano como qualquer outra sessão. Consulte [Uso e limites](#usage-and-limits) para obter detalhes.167As execuções únicas não contam contra o limite diário de execução de rotina. Elas consomem o uso de assinatura regular do seu plano como qualquer outra sessão. Consulte [Uso e limites](#usage-and-limits) para obter detalhes.

154 168 

155### Adicionar um acionador de API169<h3 id="add-an-api-trigger">

170 Adicionar um acionador de API

171</h3>

156 172 

157Um acionador de API fornece a uma rotina um endpoint HTTP dedicado. POSTando para o endpoint com o token de portador da rotina inicia uma nova sessão e retorna uma URL de sessão. Use isso para conectar Claude Code em sistemas de alerta, pipelines de implantação, ferramentas internas ou em qualquer lugar onde você possa fazer uma solicitação HTTP autenticada.173Um acionador de API fornece a uma rotina um endpoint HTTP dedicado. POSTando para o endpoint com o token de portador da rotina inicia uma nova sessão e retorna uma URL de sessão. Use isso para conectar Claude Code em sistemas de alerta, pipelines de implantação, ferramentas internas ou em qualquer lugar onde você possa fazer uma solicitação HTTP autenticada.

158 174 


178 194 

179Cada rotina tem seu próprio token, limitado ao acionamento apenas dessa rotina. Para rotacioná-lo ou revogá-lo, retorne ao mesmo modal e clique em **Regenerar** ou **Revogar**.195Cada rotina tem seu próprio token, limitado ao acionamento apenas dessa rotina. Para rotacioná-lo ou revogá-lo, retorne ao mesmo modal e clique em **Regenerar** ou **Revogar**.

180 196 

181#### Acionar uma rotina197<h4 id="trigger-a-routine">

198 Acionar uma rotina

199</h4>

182 200 

183Envie uma solicitação POST para o endpoint `/fire` com o token de portador no cabeçalho `Authorization`. O corpo da solicitação aceita um campo `text` opcional para contexto específico da execução, como um corpo de alerta ou um log com falha, passado para a rotina junto com seu prompt salvo. O valor é texto livre e não é analisado: se você enviar JSON ou outra carga estruturada, a rotina a recebe como uma string literal.201Envie uma solicitação POST para o endpoint `/fire` com o token de portador no cabeçalho `Authorization`. O corpo da solicitação aceita um campo `text` opcional para contexto específico da execução, como um corpo de alerta ou um log com falha, passado para a rotina junto com seu prompt salvo. O valor é texto livre e não é analisado: se você enviar JSON ou outra carga estruturada, a rotina a recebe como uma string literal.

184 202 


209 O endpoint `/fire` é enviado sob o cabeçalho beta `experimental-cc-routine-2026-04-01`. As formas de solicitação e resposta, limites de taxa e semântica de token podem mudar enquanto o recurso está em visualização de pesquisa. As alterações significativas são enviadas atrás de novas versões de cabeçalho beta datadas, e as duas versões de cabeçalho anteriores mais recentes continuam funcionando para que os chamadores tenham tempo para migrar.227 O endpoint `/fire` é enviado sob o cabeçalho beta `experimental-cc-routine-2026-04-01`. As formas de solicitação e resposta, limites de taxa e semântica de token podem mudar enquanto o recurso está em visualização de pesquisa. As alterações significativas são enviadas atrás de novas versões de cabeçalho beta datadas, e as duas versões de cabeçalho anteriores mais recentes continuam funcionando para que os chamadores tenham tempo para migrar.

210</Warning>228</Warning>

211 229 

212#### Referência de API230<h4 id="api-reference">

231 Referência de API

232</h4>

213 233 

214Para a referência completa da API, incluindo todas as respostas de erro, regras de validação e limites de campo, consulte [Acionar uma rotina via API](https://platform.claude.com/docs/pt/api/claude-code/routines-fire) na documentação da Plataforma Claude.234Para a referência completa da API, incluindo todas as respostas de erro, regras de validação e limites de campo, consulte [Acionar uma rotina via API](https://platform.claude.com/docs/pt/api/claude-code/routines-fire) na documentação da Plataforma Claude.

215 235 

216O endpoint `/fire` está disponível apenas para usuários de claude.ai e não faz parte da superfície da API da Plataforma Claude.236O endpoint `/fire` está disponível apenas para usuários de claude.ai e não faz parte da superfície da API da Plataforma Claude.

217 237 

218### Adicionar um acionador do GitHub238<h3 id="add-a-github-trigger">

239 Adicionar um acionador do GitHub

240</h3>

219 241 

220Um acionador do GitHub inicia uma nova sessão automaticamente quando um evento correspondente ocorre em um repositório conectado. Cada evento correspondente inicia sua própria sessão.242Um acionador do GitHub inicia uma nova sessão automaticamente quando um evento correspondente ocorre em um repositório conectado. Cada evento correspondente inicia sua própria sessão.

221 243 


247 </Step>269 </Step>

248</Steps>270</Steps>

249 271 

250#### Eventos suportados272<h4 id="supported-events">

273 Eventos suportados

274</h4>

251 275 

252Os acionadores do GitHub podem se inscrever em uma das seguintes categorias de eventos. Dentro de cada categoria, você pode escolher uma ação específica, como `pull_request.opened`, ou reagir a todas as ações na categoria.276Os acionadores do GitHub podem se inscrever em uma das seguintes categorias de eventos. Dentro de cada categoria, você pode escolher uma ação específica, como `pull_request.opened`, ou reagir a todas as ações na categoria.

253 277 


256| Pull request | Um PR é aberto, fechado, atribuído, rotulado, sincronizado ou atualizado de outra forma |280| Pull request | Um PR é aberto, fechado, atribuído, rotulado, sincronizado ou atualizado de outra forma |

257| Lançamento | Um lançamento é criado, publicado, editado ou excluído |281| Lançamento | Um lançamento é criado, publicado, editado ou excluído |

258 282 

259#### Filtrar pull requests283<h4 id="filter-pull-requests">

284 Filtrar pull requests

285</h4>

260 286 

261Use filtros para restringir quais pull requests iniciam uma nova sessão. Todas as condições de filtro devem corresponder para a rotina ser acionada. Os campos de filtro disponíveis são:287Use filtros para restringir quais pull requests iniciam uma nova sessão. Todas as condições de filtro devem corresponder para a rotina ser acionada. Os campos de filtro disponíveis são:

262 288 


281* **Pronto para revisão apenas**: é rascunho é `false`. Pula rascunhos para que a rotina seja executada apenas quando o PR estiver pronto para revisão.307* **Pronto para revisão apenas**: é rascunho é `false`. Pula rascunhos para que a rotina seja executada apenas quando o PR estiver pronto para revisão.

282* **Backport com portão de rótulo**: rótulos incluem `needs-backport`. Aciona uma rotina de porta para outro branch apenas quando um mantenedor marca o PR.308* **Backport com portão de rótulo**: rótulos incluem `needs-backport`. Aciona uma rotina de porta para outro branch apenas quando um mantenedor marca o PR.

283 309 

284#### Como as sessões mapeiam para eventos310<h4 id="how-sessions-map-to-events">

311 Como as sessões mapeiam para eventos

312</h4>

285 313 

286Cada evento do GitHub correspondente inicia uma nova sessão. A reutilização de sessão entre eventos não está disponível para rotinas acionadas pelo GitHub, portanto duas atualizações de PR produzem duas sessões independentes.314Cada evento do GitHub correspondente inicia uma nova sessão. A reutilização de sessão entre eventos não está disponível para rotinas acionadas pelo GitHub, portanto duas atualizações de PR produzem duas sessões independentes.

287 315 

288## Gerenciar rotinas316<h2 id="manage-routines">

317 Gerenciar rotinas

318</h2>

289 319 

290Clique em uma rotina na lista para abrir sua página de detalhes. A página de detalhes mostra os repositórios da rotina, conectores, prompt, cronograma, tokens de API, acionadores do GitHub e uma lista de execuções anteriores.320Clique em uma rotina na lista para abrir sua página de detalhes. A página de detalhes mostra os repositórios da rotina, conectores, prompt, cronograma, tokens de API, acionadores do GitHub e uma lista de execuções anteriores.

291 321 

292### Visualizar e interagir com execuções322<h3 id="view-and-interact-with-runs">

323 Visualizar e interagir com execuções

324</h3>

293 325 

294Clique em qualquer execução para abri-la como uma sessão completa. De lá você pode ver o que Claude fez, revisar alterações, criar um pull request ou continuar a conversa. Cada sessão de execução funciona como qualquer outra sessão: use o menu suspenso ao lado do título da sessão para renomear, arquivar ou excluir.326Clique em qualquer execução para abri-la como uma sessão completa. De lá você pode ver o que Claude fez, revisar alterações, criar um pull request ou continuar a conversa. Cada sessão de execução funciona como qualquer outra sessão: use o menu suspenso ao lado do título da sessão para renomear, arquivar ou excluir.

295 327 


297 Um status verde na lista de execuções significa que a sessão iniciou e saiu sem um erro de infraestrutura. Isso não significa que a tarefa em seu prompt foi bem-sucedida. Abra a execução para ler a transcrição e confirmar o que Claude realmente fez. Solicitações de rede bloqueadas, ferramentas de conectores ausentes e falhas no nível da tarefa aparecem lá em vez de no indicador de status.329 Um status verde na lista de execuções significa que a sessão iniciou e saiu sem um erro de infraestrutura. Isso não significa que a tarefa em seu prompt foi bem-sucedida. Abra a execução para ler a transcrição e confirmar o que Claude realmente fez. Solicitações de rede bloqueadas, ferramentas de conectores ausentes e falhas no nível da tarefa aparecem lá em vez de no indicador de status.

298</Note>330</Note>

299 331 

300### Editar e controlar rotinas332<h3 id="edit-and-control-routines">

333 Editar e controlar rotinas

334</h3>

301 335 

302Na página de detalhes da rotina você pode:336Na página de detalhes da rotina você pode:

303 337 


306* Clique no ícone de lápis para abrir **Editar rotina** e alterar o nome, prompt, repositórios, ambiente, conectores ou qualquer um dos acionadores da rotina. A seção **Selecionar um acionador** é onde você adiciona ou remove cronogramas, tokens de API e acionadores de eventos do GitHub.340* Clique no ícone de lápis para abrir **Editar rotina** e alterar o nome, prompt, repositórios, ambiente, conectores ou qualquer um dos acionadores da rotina. A seção **Selecionar um acionador** é onde você adiciona ou remove cronogramas, tokens de API e acionadores de eventos do GitHub.

307* Clique no ícone de exclusão para remover a rotina. As sessões anteriores criadas pela rotina permanecem em sua lista de sessões.341* Clique no ícone de exclusão para remover a rotina. As sessões anteriores criadas pela rotina permanecem em sua lista de sessões.

308 342 

309### Repositórios e permissões de branch343<h3 id="repositories-and-branch-permissions">

344 Repositórios e permissões de branch

345</h3>

310 346 

311As rotinas precisam de acesso ao GitHub para clonar repositórios. Quando você cria uma rotina a partir da CLI com `/schedule`, Claude verifica se sua conta tem o GitHub conectado e solicita que você execute `/web-setup` se não tiver. Consulte [Opções de autenticação do GitHub](/pt/claude-code-on-the-web#github-authentication-options) para as duas maneiras de conceder acesso.347As rotinas precisam de acesso ao GitHub para clonar repositórios. Quando você cria uma rotina a partir da CLI com `/schedule`, Claude verifica se sua conta tem o GitHub conectado e solicita que você execute `/web-setup` se não tiver. Consulte [Opções de autenticação do GitHub](/pt/claude-code-on-the-web#github-authentication-options) para as duas maneiras de conceder acesso.

312 348 


314 350 

315Por padrão, Claude pode apenas fazer push para branches com prefixo `claude/`. Isso evita que as rotinas modifiquem acidentalmente branches protegidos ou de longa duração. Para remover essa restrição para um repositório específico, ative **Permitir pushes de branch sem restrições** para esse repositório ao criar ou editar a rotina.351Por padrão, Claude pode apenas fazer push para branches com prefixo `claude/`. Isso evita que as rotinas modifiquem acidentalmente branches protegidos ou de longa duração. Para remover essa restrição para um repositório específico, ative **Permitir pushes de branch sem restrições** para esse repositório ao criar ou editar a rotina.

316 352 

317### Conectores353<h3 id="connectors">

354 Conectores

355</h3>

318 356 

319As rotinas podem usar seus conectores MCP conectados para ler e escrever em serviços externos durante cada execução. Por exemplo, uma rotina que faz triagem de solicitações de suporte pode ler de um canal do Slack e criar problemas no Linear.357As rotinas podem usar seus conectores MCP conectados para ler e escrever em serviços externos durante cada execução. Por exemplo, uma rotina que faz triagem de solicitações de suporte pode ler de um canal do Slack e criar problemas no Linear.

320 358 


324 362 

325Para gerenciar ou adicionar conectores fora do formulário de rotina, visite **Configurações > Conectores** em claude.ai ou use `/schedule update` na CLI.363Para gerenciar ou adicionar conectores fora do formulário de rotina, visite **Configurações > Conectores** em claude.ai ou use `/schedule update` na CLI.

326 364 

327### Ambientes e acesso à rede365<h3 id="environments-and-network-access">

366 Ambientes e acesso à rede

367</h3>

328 368 

329Cada rotina é executada em um [ambiente em nuvem](/pt/claude-code-on-the-web#the-cloud-environment) que controla acesso à rede, variáveis de ambiente e scripts de configuração. A rotina herda a política de rede do ambiente em cada execução.369Cada rotina é executada em um [ambiente em nuvem](/pt/claude-code-on-the-web#the-cloud-environment) que controla acesso à rede, variáveis de ambiente e scripts de configuração. A rotina herda a política de rede do ambiente em cada execução.

330 370 

331O ambiente **Padrão** usa acesso à rede **Confiável**: a [lista de permissões padrão](/pt/claude-code-on-the-web#default-allowed-domains) de registros de pacotes, APIs de provedores de nuvem, registros de contêineres e domínios de desenvolvimento comuns é acessível, mas domínios arbitrários não são. Solicitações de saída para outros hosts falham com `403` e `x-deny-reason: host_not_allowed`. O tráfego do conector MCP é roteado através dos servidores da Anthropic, portanto os conectores que você adiciona à rotina funcionam sem adicionar seus hosts aos **Domínios permitidos**. Remova qualquer conectores que você não precise em [Conectores](#conectores).371O ambiente **Padrão** usa acesso à rede **Confiável**: a [lista de permissões padrão](/pt/claude-code-on-the-web#default-allowed-domains) de registros de pacotes, APIs de provedores de nuvem, registros de contêineres e domínios de desenvolvimento comuns é acessível, mas domínios arbitrários não são. Solicitações de saída para outros hosts falham com `403` e `x-deny-reason: host_not_allowed`. O tráfego do conector MCP é roteado através dos servidores da Anthropic, portanto os conectores que você adiciona à rotina funcionam sem adicionar seus hosts aos **Domínios permitidos**. Remova qualquer conectores que você não precise em [Conectores](#connectors).

332 372 

333Para permitir domínios adicionais:373Para permitir domínios adicionais:

334 374 


356 396 

357Consulte [Acesso à rede](/pt/claude-code-on-the-web#network-access) para detalhes sobre níveis de acesso e a lista de permissões padrão.397Consulte [Acesso à rede](/pt/claude-code-on-the-web#network-access) para detalhes sobre níveis de acesso e a lista de permissões padrão.

358 398 

359## Uso e limites399<h2 id="usage-and-limits">

400 Uso e limites

401</h2>

360 402 

361As rotinas reduzem o uso da assinatura da mesma forma que as sessões interativas. Além dos limites de assinatura padrão, as rotinas têm um limite diário de quantas execuções podem começar por conta. Veja seu consumo atual e execuções de rotina diárias restantes em [claude.ai/code/routines](https://claude.ai/code/routines) ou [claude.ai/settings/usage](https://claude.ai/settings/usage).403As rotinas reduzem o uso da assinatura da mesma forma que as sessões interativas. Além dos limites de assinatura padrão, as rotinas têm um limite diário de quantas execuções podem começar por conta. Veja seu consumo atual e execuções de rotina diárias restantes em [claude.ai/code/routines](https://claude.ai/code/routines) ou [claude.ai/settings/usage](https://claude.ai/settings/usage).

362 404 


364 406 

365As execuções únicas não contam contra o limite diário de execução de rotina. Elas reduzem seu uso de assinatura regular como qualquer outra sessão, mas estão isentas da permissão de execução de rotina diária por conta.407As execuções únicas não contam contra o limite diário de execução de rotina. Elas reduzem seu uso de assinatura regular como qualquer outra sessão, mas estão isentas da permissão de execução de rotina diária por conta.

366 408 

367## Solução de problemas409<h2 id="troubleshooting">

410 Solução de problemas

411</h2>

368 412 

369### `/schedule` retorna "Unknown command"413<h3 id="/schedule-returns-unknown-command">

414 `/schedule` retorna "Unknown command"

415</h3>

370 416 

371A CLI oculta `/schedule` quando um de seus requisitos não é atendido. A causa geralmente é uma das seguintes:417A CLI oculta `/schedule` quando um de seus requisitos não é atendido. A causa geralmente é uma das seguintes:

372 418 


377 423 

378Você sempre pode criar e gerenciar rotinas em [claude.ai/code/routines](https://claude.ai/code/routines) independentemente de como a CLI está configurada.424Você sempre pode criar e gerenciar rotinas em [claude.ai/code/routines](https://claude.ai/code/routines) independentemente de como a CLI está configurada.

379 425 

380### "As rotinas estão desabilitadas pela política da sua organização"426<h3 id="routines-are-disabled-by-your-organization’s-policy">

427 "As rotinas estão desabilitadas pela política da sua organização"

428</h3>

381 429 

382Seu administrador de Team ou Enterprise provavelmente desativou o botão de alternância **Routines** em [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code). Esta é uma configuração de organização no servidor, portanto não pode ser substituída pela sua configuração local. Entre em contato com seu administrador para solicitar que as rotinas sejam habilitadas para sua organização.430Seu administrador de Team ou Enterprise provavelmente desativou o botão de alternância **Routines** em [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code). Esta é uma configuração de organização no servidor, portanto não pode ser substituída pela sua configuração local. Entre em contato com seu administrador para solicitar que as rotinas sejam habilitadas para sua organização.

383 431 

384## Recursos relacionados432<h2 id="related-resources">

433 Recursos relacionados

434</h2>

385 435 

386* [`/loop` e agendamento em sessão](/pt/scheduled-tasks): agende tarefas locais dentro de uma sessão CLI aberta436* [`/loop` e agendamento em sessão](/pt/scheduled-tasks): agende tarefas locais dentro de uma sessão CLI aberta

387* [Tarefas agendadas do Desktop](/pt/desktop-scheduled-tasks): tarefas agendadas locais que são executadas em sua máquina com acesso a arquivos locais437* [Tarefas agendadas do Desktop](/pt/desktop-scheduled-tasks): tarefas agendadas locais que são executadas em sua máquina com acesso a arquivos locais

Details

43</Warning>43</Warning>

44 44 

45<h2 id="choose-an-approach">45<h2 id="choose-an-approach">

46 Choose an approach46 Escolha uma abordagem

47</h2>47</h2>

48 48 

49Combine seu objetivo com uma linha abaixo e leia a seção de detalhes que segue.49Combine seu objetivo com uma linha abaixo e leia a seção de detalhes que segue.


60| Trabalhar em um host Windows nativo | Um container ou VM, ou executar o sandbox Bash dentro do WSL2 |60| Trabalhar em um host Windows nativo | Um container ou VM, ou executar o sandbox Bash dentro do WSL2 |

61 61 

62<h3 id="how-isolation-relates-to-permission-modes">62<h3 id="how-isolation-relates-to-permission-modes">

63 How isolation relates to permission modes63 Como o isolamento se relaciona com os modos de permissão

64</h3>64</h3>

65 65 

66Os [Permission modes](/pt/permission-modes) decidem se uma chamada de ferramenta é executada e se você é solicitado primeiro. O isolamento restringe o que um comando pode acessar uma vez que é executado. Os dois trabalham juntos: quando um modo de permissão permite que ações sejam executadas sem pedir a você, um limite de isolamento restringe o que essas ações podem alcançar.66Os [Permission modes](/pt/permission-modes) decidem se uma chamada de ferramenta é executada e se você é solicitado primeiro. O isolamento restringe o que um comando pode acessar uma vez que é executado. Os dois trabalham juntos: quando um modo de permissão permite que ações sejam executadas sem pedir a você, um limite de isolamento restringe o que essas ações podem alcançar.

67 67 

68`--dangerously-skip-permissions` remove a revisão por ação completamente, portanto um limite de isolamento é a única coisa limitando o que o Claude pode fazer. Sempre execute-o dentro de um container, uma VM, ou o [sandbox runtime](#sandbox-runtime), para que ferramentas de arquivo, servidores MCP e hooks também estejam dentro do limite.68`--dangerously-skip-permissions` remove a revisão por ação, exceto por [ask rules](/pt/permissions#manage-permissions) explícitas, portanto um limite de isolamento é a única coisa limitando o que o Claude pode fazer. Sempre execute-o dentro de um container, uma VM, ou o [sandbox runtime](#sandbox-runtime), para que ferramentas de arquivo, servidores MCP e hooks também estejam dentro do limite.

69 69 

70[Auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode) substitui o prompt por um classificador que revisa ações e bloqueia aquelas que escalam além da solicitação, visam infraestrutura não reconhecida, ou parecem impulsionadas por conteúdo hostil que o Claude leu. O classificador é um controle por ação, não um limite de isolamento, portanto um limite de isolamento ainda adiciona defesa em profundidade para execuções sem supervisão, e não é necessário da forma que é para `--dangerously-skip-permissions`.70[Auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode) substitui o prompt por um classificador que revisa ações e bloqueia aquelas que escalam além da solicitação, visam infraestrutura não reconhecida, ou parecem impulsionadas por conteúdo hostil que o Claude leu. O classificador é um controle por ação, não um limite de isolamento, portanto um limite de isolamento ainda adiciona defesa em profundidade para execuções sem supervisão, e não é necessário da forma que é para `--dangerously-skip-permissions`.

71 71 


151* **Custom containers and VMs**: distribua o Claude Code através da imagem aprovada e use as ferramentas de gerenciamento de dispositivos ou software allowlisting da sua organização para impedir a instalação fora dela.151* **Custom containers and VMs**: distribua o Claude Code através da imagem aprovada e use as ferramentas de gerenciamento de dispositivos ou software allowlisting da sua organização para impedir a instalação fora dela.

152 152 

153<h2 id="see-also">153<h2 id="see-also">

154 See also154 Veja também

155</h2>155</h2>

156 156 

157Estas páginas cobrem detalhes de configuração e política para as abordagens acima.157Estas páginas cobrem detalhes de configuração e política para as abordagens acima.

158 158 

159* [Sandboxing](/pt/sandboxing): configure a sandboxed Bash tool integrada159* [Sandboxing](/pt/sandboxing): configure a ferramenta Bash sandboxed integrada

160* [Dev container](/pt/devcontainer): o container de desenvolvimento Docker pré-configurado160* [Dev container](/pt/devcontainer): o container de desenvolvimento Docker pré-configurado

161* [Security](/pt/security): o modelo de segurança completo do Claude Code161* [Security](/pt/security): o modelo de segurança completo do Claude Code

162* [Secure deployment](/pt/agent-sdk/secure-deployment): orientação de isolamento para aplicações do Agent SDK162* [Secure deployment](/pt/agent-sdk/secure-deployment): orientação de isolamento para aplicações do Agent SDK

sandboxing.md +23 −20

Details

49 </Step>49 </Step>

50 50 

51 <Step title="Run a Bash command">51 <Step title="Run a Bash command">

52 Peça ao Claude para executar um comando, como uma compilação ou um conjunto de testes. Por padrão, os comandos dentro do sandbox podem escrever apenas no diretório de trabalho. Na primeira vez que um comando precisa de um novo domínio de rede, Claude Code solicita aprovação.52 Peça ao Claude para executar um comando, como uma compilação ou um conjunto de testes. Por padrão, os comandos dentro do sandbox podem escrever apenas no diretório de trabalho e no diretório temporário da sessão. Na primeira vez que um comando precisa de um novo domínio de rede, Claude Code solicita aprovação.

53 53 

54 Comandos que não podem ser executados em sandbox voltam ao fluxo de permissão regular. Para ampliar ou estreitar esses limites, consulte [Configure sandboxing](#configure-sandboxing).54 Comandos que não podem ser executados em sandbox voltam ao fluxo de permissão regular. Para ampliar ou estreitar esses limites, consulte [Configure sandboxing](#configure-sandboxing).

55 </Step>55 </Step>


134 134 

135* [Deny rules](/pt/permissions) explícitas são sempre respeitadas135* [Deny rules](/pt/permissions) explícitas são sempre respeitadas

136* Comandos `rm` ou `rmdir` que visam `/`, seu diretório home ou outros caminhos críticos do sistema ainda acionam um prompt de permissão136* Comandos `rm` ou `rmdir` que visam `/`, seu diretório home ou outros caminhos críticos do sistema ainda acionam um prompt de permissão

137* [Ask rules](/pt/permissions) se aplicam a comandos que voltam ao fluxo de permissão regular137* [Ask rules](/pt/permissions) com escopo de conteúdo como `Bash(git push *)` ainda forçam um prompt mesmo para comandos em sandbox

138* Uma regra ask `Bash` simples, ou o formulário equivalente `Bash(*)`, é ignorada para comandos executados em sandbox; ainda se aplica a comandos que voltam ao fluxo de permissão regular

138 139 

139**Modo regular permissions**: Todos os comandos Bash passam pelo fluxo de permissão regular, mesmo quando em sandbox. Isso fornece mais controle, mas requer mais aprovações.140**Modo regular permissions**: Todos os comandos Bash passam pelo fluxo de permissão regular, mesmo quando em sandbox. Isso fornece mais controle, mas requer mais aprovações.

140 141 

141Em ambos os modos, o sandbox impõe as mesmas restrições de sistema de arquivos e rede. A diferença é apenas se os comandos em sandbox são aprovados automaticamente ou requerem permissão explícita.142Em ambos os modos, o sandbox impõe as mesmas restrições de sistema de arquivos e rede. A diferença é apenas se os comandos em sandbox são aprovados automaticamente ou requerem permissão explícita.

142 143 

144O diretório temporário da sessão é gravável dentro do sandbox por padrão, junto com o diretório de trabalho. Claude Code define `$TMPDIR` para este diretório para comandos em sandbox, portanto ferramentas que escrevem arquivos temporários funcionam sem configuração extra. Comandos não em sandbox herdam o `$TMPDIR` do seu shell inalterado, o que significa que comandos em sandbox e não em sandbox resolvem `$TMPDIR` para diretórios diferentes. Para passar arquivos temporários entre os dois, escreva-os no diretório de trabalho em vez disso.

145 

143Alguns comandos não podem ser executados dentro do sandbox, como ferramentas que são incompatíveis com ele ou que precisam de um host que você não permitiu. Em vez de falhar na tarefa ou exigir que você desative o sandboxing, Claude Code inclui um escape hatch: quando um comando falha por causa de restrições de sandbox, Claude analisa a falha e pode tentar novamente o comando com o parâmetro `dangerouslyDisableSandbox`. O comando retentado é executado fora do sandbox, portanto passa pelo fluxo de permissão regular e requer sua aprovação.146Alguns comandos não podem ser executados dentro do sandbox, como ferramentas que são incompatíveis com ele ou que precisam de um host que você não permitiu. Em vez de falhar na tarefa ou exigir que você desative o sandboxing, Claude Code inclui um escape hatch: quando um comando falha por causa de restrições de sandbox, Claude analisa a falha e pode tentar novamente o comando com o parâmetro `dangerouslyDisableSandbox`. O comando retentado é executado fora do sandbox, portanto passa pelo fluxo de permissão regular e requer sua aprovação.

144 147 

145Você pode desabilitar esse escape hatch definindo `"allowUnsandboxedCommands": false` em suas [sandbox settings](/pt/settings#sandbox-settings). Quando desabilitado, que a aba Overrides do `/sandbox` mostra como **Strict sandbox mode**, o parâmetro `dangerouslyDisableSandbox` é completamente ignorado e todos os comandos devem ser executados em sandbox ou estar explicitamente listados em `excludedCommands`.148Você pode desabilitar esse escape hatch definindo `"allowUnsandboxedCommands": false` em suas [sandbox settings](/pt/settings#sandbox-settings). Quando desabilitado, que a aba Overrides do `/sandbox` mostra como **Strict sandbox mode**, o parâmetro `dangerouslyDisableSandbox` é completamente ignorado e todos os comandos devem ser executados em sandbox ou estar explicitamente listados em `excludedCommands`.


154 157 

155Personalize o comportamento do sandbox através de seu arquivo `settings.json`. Consulte [Settings](/pt/settings#sandbox-settings) para a referência de configuração completa.158Personalize o comportamento do sandbox através de seu arquivo `settings.json`. Consulte [Settings](/pt/settings#sandbox-settings) para a referência de configuração completa.

156 159 

157Por padrão, comandos em sandbox podem apenas escrever no diretório de trabalho atual. Se comandos de subprocesso como `kubectl`, `terraform` ou `npm` precisarem escrever fora do diretório do projeto, use `sandbox.filesystem.allowWrite` para conceder acesso a caminhos específicos:160Por padrão, comandos em sandbox podem escrever apenas no diretório de trabalho atual e no diretório temporário da sessão. Se comandos de subprocesso como `kubectl`, `terraform` ou `npm` precisarem escrever fora desses diretórios, use `sandbox.filesystem.allowWrite` para conceder acesso a caminhos específicos:

158 161 

159```json theme={null}162```json theme={null}

160{163{


209 212 

210A ferramenta Bash em sandbox restringe o acesso ao sistema de arquivos a diretórios específicos:213A ferramenta Bash em sandbox restringe o acesso ao sistema de arquivos a diretórios específicos:

211 214 

212* **Comportamento padrão de escrita**: acesso de leitura e escrita ao diretório de trabalho atual e seus subdiretórios215* **Comportamento padrão de escrita**: acesso de leitura e escrita ao diretório de trabalho atual e seus subdiretórios, além do diretório temporário da sessão para o qual `$TMPDIR` aponta

213* **Comportamento padrão de leitura**: acesso de leitura a todo o computador, exceto certos diretórios negados. Observe que esse padrão ainda permite ler arquivos de credenciais como `~/.aws/credentials` e `~/.ssh/`. Adicione-os a `denyRead` para bloqueá-los.216* **Comportamento padrão de leitura**: acesso de leitura a todo o computador, exceto certos diretórios negados. Observe que esse padrão ainda permite ler arquivos de credenciais como `~/.aws/credentials` e `~/.ssh/`. Adicione-os a `denyRead` para bloqueá-los.

214* **Acesso bloqueado**: não é possível modificar arquivos fora do diretório de trabalho atual sem permissão explícita, incluindo arquivos de configuração de shell como `~/.bashrc` e binários do sistema em `/bin/`217* **Acesso bloqueado**: não é possível modificar arquivos fora do diretório de trabalho atual e do diretório temporário da sessão sem permissão explícita, incluindo arquivos de configuração de shell como `~/.bashrc` e binários do sistema em `/bin/`

215* **Git worktrees**: quando o diretório de trabalho é um [git worktree vinculado](/pt/worktrees), o sandbox também permite escritas no diretório `.git` compartilhado do repositório principal para que comandos como `git commit` possam atualizar refs e o índice. As escritas em `hooks/` e `config` dentro desse diretório permanecem negadas.218* **Git worktrees**: quando o diretório de trabalho é um [git worktree vinculado](/pt/worktrees), o sandbox também permite escritas no diretório `.git` compartilhado do repositório principal para que comandos como `git commit` possam atualizar refs e o índice. As escritas em `hooks/` e `config` dentro desse diretório permanecem negadas.

216* **Configurável**: defina caminhos permitidos e negados personalizados através de configurações219* **Configurável**: defina caminhos permitidos e negados personalizados através de configurações

217 220 


247Esses mesmos primitivos estão disponíveis como o pacote autônomo [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime), que a página [Sandbox environments](/pt/sandbox-environments#sandbox-runtime) aborda como uma abordagem separada para envolver todo o processo do Claude Code.250Esses mesmos primitivos estão disponíveis como o pacote autônomo [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime), que a página [Sandbox environments](/pt/sandbox-environments#sandbox-runtime) aborda como uma abordagem separada para envolver todo o processo do Claude Code.

248 251 

249<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">252<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">

250 How sandboxing relates to permissions and permission modes253 Como sandboxing se relaciona com permissões e modos de permissão

251</h2>254</h2>

252 255 

253Sandboxing, [permission rules](/pt/permissions) e [permission modes](/pt/permission-modes) são camadas complementares. As seções abaixo abrangem como o sandbox interage com cada uma.256Sandboxing, [regras de permissão](/pt/permissions) e [modos de permissão](/pt/permission-modes) são camadas complementares. As seções abaixo abrangem como o sandbox interage com cada uma.

254 257 

255<h3 id="permission-rules">258<h3 id="permission-rules">

256 Permission rules259 Regras de permissão

257</h3>260</h3>

258 261 

259Regras de permissão e sandboxing controlam coisas diferentes:262Regras de permissão e sandboxing controlam coisas diferentes:


281O [diretório de exemplos do repositório claude-code](https://github.com/anthropics/claude-code/tree/main/examples/settings) inclui configurações de configurações iniciais para cenários de implantação comuns, incluindo exemplos específicos de sandbox. Use-os como pontos de partida e ajuste-os para suas necessidades.284O [diretório de exemplos do repositório claude-code](https://github.com/anthropics/claude-code/tree/main/examples/settings) inclui configurações de configurações iniciais para cenários de implantação comuns, incluindo exemplos específicos de sandbox. Use-os como pontos de partida e ajuste-os para suas necessidades.

282 285 

283<h3 id="permission-modes">286<h3 id="permission-modes">

284 Permission modes287 Modos de permissão

285</h3>288</h3>

286 289 

287`/sandbox` não é um [permission mode](/pt/permission-modes). Modos de permissão decidem se uma chamada de ferramenta é executada e se você é solicitado primeiro, enquanto o sandbox restringe o que um comando Bash pode acessar uma vez que é executado. Eles diferem no que controlam e o que substitui o prompt por ação:290`/sandbox` não é um [modo de permissão](/pt/permission-modes). Modos de permissão decidem se uma chamada de ferramenta é executada e se você é solicitado primeiro, enquanto o sandbox restringe o que um comando Bash pode acessar uma vez que é executado. Eles diferem no que controlam e o que substitui o prompt por ação:

288 291 

289| | O que controla | O que substitui o prompt |292| | O que controla | O que substitui o prompt |

290| :----------------------------------------------------------------- | :--------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |293| :----------------------------------------------------------------- | :--------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |

291| `/sandbox` | O que um comando Bash pode acessar uma vez que é executado | O limite do sandbox em si, no [modo auto-allow](#sandbox-modes) |294| `/sandbox` | O que um comando Bash pode acessar uma vez que é executado | O limite do sandbox em si, no [modo auto-allow](#sandbox-modes) |

292| [Auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode) | Se cada chamada de ferramenta é executada | Um classificador que revisa ações |295| [Modo auto](/pt/permission-modes#eliminate-prompts-with-auto-mode) | Se cada chamada de ferramenta é executada | Um classificador que revisa ações |

293| `--dangerously-skip-permissions` | Se cada chamada de ferramenta é executada | Nada. Verificações de [protected path](/pt/permission-modes#protected-paths) também são ignoradas; apenas remover `/` ou seu diretório home ainda solicita |296| `--dangerously-skip-permissions` | Se cada chamada de ferramenta é executada | Nada. Verificações de [caminho protegido](/pt/permission-modes#protected-paths) também são ignoradas; apenas remover `/` ou seu diretório home ainda solicita |

294 297 

295O [modo auto-allow](#sandbox-modes) do sandbox é separado do [auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode): auto-allow aprova comandos Bash porque o limite do sandbox os contém, enquanto auto mode usa um classificador para revisar ações. Os dois funcionam independentemente e podem ser combinados. Para escolher um limite de isolamento para execuções autônomas, consulte [Sandbox environments](/pt/sandbox-environments#how-isolation-relates-to-permission-modes).298O [modo auto-allow](#sandbox-modes) do sandbox é separado do [modo auto](/pt/permission-modes#eliminate-prompts-with-auto-mode): auto-allow aprova comandos Bash porque o limite do sandbox os contém, enquanto modo auto usa um classificador para revisar ações. Os dois funcionam independentemente e podem ser combinados. Para escolher um limite de isolamento para execuções autônomas, consulte [Ambientes de sandbox](/pt/sandbox-environments#how-isolation-relates-to-permission-modes).

296 299 

297<h2 id="configure-the-sandbox-for-your-organization">300<h2 id="configure-the-sandbox-for-your-organization">

298 Configure the sandbox for your organization301 Configure the sandbox for your organization


376* **`--dangerously-skip-permissions` falha como root**: este sinalizador é bloqueado ao executar como root ou via sudo no Linux e macOS, porque acesso root combinado com nenhum prompt de permissão pode modificar qualquer arquivo ou serviço no sistema. A verificação é ignorada automaticamente dentro de um sandbox reconhecido. Para executar autonomamente em um container, use a configuração [dev container](/pt/devcontainer), que executa Claude Code como um usuário não-root.379* **`--dangerously-skip-permissions` falha como root**: este sinalizador é bloqueado ao executar como root ou via sudo no Linux e macOS, porque acesso root combinado com nenhum prompt de permissão pode modificar qualquer arquivo ou serviço no sistema. A verificação é ignorada automaticamente dentro de um sandbox reconhecido. Para executar autonomamente em um container, use a configuração [dev container](/pt/devcontainer), que executa Claude Code como um usuário não-root.

377 380 

378<h2 id="limitations">381<h2 id="limitations">

379 Limitations382 Limitações

380</h2>383</h2>

381 384 

382Sandboxing reduz risco, mas não é um limite de isolamento completo. Revise as limitações abaixo antes de confiar nele como um controle de segurança difícil.385Sandboxing reduz risco, mas não é um limite de isolamento completo. Revise as limitações abaixo antes de confiar nele como um controle de segurança difícil.

383 386 

384<h3 id="security-limitations">387<h3 id="security-limitations">

385 Security limitations388 Limitações de segurança

386</h3>389</h3>

387 390 

388* **Filtragem de rede**: o sistema de filtragem de rede funciona restringindo os domínios aos quais os processos podem se conectar. O proxy integrado não termina ou realiza inspeção TLS no tráfego de saída, portanto o conteúdo de conexões criptografadas não é examinado. Você é responsável por garantir que apenas domínios confiáveis sejam permitidos em sua política.391* **Filtragem de rede**: o sistema de filtragem de rede funciona restringindo os domínios aos quais os processos podem se conectar. O proxy integrado não termina ou realiza inspeção TLS no tráfego de saída, portanto o conteúdo de conexões criptografadas não é examinado. Você é responsável por garantir que apenas domínios confiáveis sejam permitidos em sua política.


397* **Arquivos de configurações protegidos**: o sandbox automaticamente nega acesso de escrita aos arquivos `settings.json` do Claude Code em cada escopo e ao diretório de configurações gerenciadas, portanto um comando em sandbox não pode modificar sua própria política.400* **Arquivos de configurações protegidos**: o sandbox automaticamente nega acesso de escrita aos arquivos `settings.json` do Claude Code em cada escopo e ao diretório de configurações gerenciadas, portanto um comando em sandbox não pode modificar sua própria política.

398 401 

399<h3 id="platform-and-tool-compatibility">402<h3 id="platform-and-tool-compatibility">

400 Platform and tool compatibility403 Compatibilidade de plataforma e ferramentas

401</h3>404</h3>

402 405 

403* **Suporte de plataforma**: suporta macOS, Linux e WSL2. WSL1 e Windows nativo não são suportados.406* **Suporte de plataforma**: suporta macOS, Linux e WSL2. WSL1 e Windows nativo não são suportados.


405* **Compatibilidade de ferramentas**: algumas ferramentas que exigem padrões de acesso específicos do sistema podem precisar de ajustes de configuração, ou podem precisar ser executadas fora do sandbox.408* **Compatibilidade de ferramentas**: algumas ferramentas que exigem padrões de acesso específicos do sistema podem precisar de ajustes de configuração, ou podem precisar ser executadas fora do sandbox.

406 409 

407<h3 id="scope">410<h3 id="scope">

408 Scope411 Escopo

409</h3>412</h3>

410 413 

411O sandbox isola subprocessos Bash. Outras ferramentas operam sob limites diferentes:414O sandbox isola subprocessos Bash. Outras ferramentas operam sob limites diferentes:


416* **Subagents**: [subagents](/pt/sub-agents) são executados no mesmo processo que a sessão pai e usam a mesma configuração de sandbox. Comandos Bash dentro de um subagent são colocados em sandbox quando sandboxing está habilitado na sessão pai.419* **Subagents**: [subagents](/pt/sub-agents) são executados no mesmo processo que a sessão pai e usam a mesma configuração de sandbox. Comandos Bash dentro de um subagent são colocados em sandbox quando sandboxing está habilitado na sessão pai.

417 420 

418<Warning>421<Warning>

419 Sandboxing eficaz requer isolamento **tanto** de sistema de arquivos quanto de rede. Sem isolamento de rede, um agente comprometido poderia exfiltrar arquivos sensíveis como chaves SSH. Sem isolamento de sistema de arquivos, um agente comprometido poderia fazer backdoor de recursos do sistema para obter acesso à rede. Quando você amplia os padrões, verifique que um caminho `allowWrite`, uma entrada `allowedDomains` ampla ou uma exceção `excludedCommands` não desfaz uma restrição no outro lado.422 Sandboxing eficaz requer isolamento tanto de sistema de arquivos quanto de rede. Sem isolamento de rede, um agente comprometido poderia exfiltrar arquivos sensíveis como chaves SSH. Sem isolamento de sistema de arquivos, um agente comprometido poderia fazer backdoor de recursos do sistema para obter acesso à rede. Quando você amplia os padrões, verifique que um caminho `allowWrite`, uma entrada `allowedDomains` ampla ou uma exceção `excludedCommands` não desfaz uma restrição no outro lado.

420</Warning>423</Warning>

421 424 

422<h2 id="see-also">425<h2 id="see-also">

423 See also426 Veja também

424</h2>427</h2>

425 428 

426* [Sandbox environments](/pt/sandbox-environments): compare o sandbox integrado com dev containers, containers e VMs429* [Sandbox environments](/pt/sandbox-environments): compare o sandbox integrado com dev containers, containers e VMs

Details

15As tarefas têm escopo de sessão: elas vivem na conversa atual e param quando você inicia uma nova. Retomar com `--resume` ou `--continue` traz de volta qualquer tarefa que não tenha [expirado](#seven-day-expiry): uma tarefa recorrente criada nos últimos 7 dias, ou uma única cujo tempo agendado ainda não passou. Para agendamento que sobreviva independentemente de qualquer sessão, use [Routines](/pt/routines) para criar uma rotina na infraestrutura gerenciada pela Anthropic, configure uma [tarefa agendada do Desktop](/pt/desktop-scheduled-tasks) ou use [GitHub Actions](/pt/github-actions).15As tarefas têm escopo de sessão: elas vivem na conversa atual e param quando você inicia uma nova. Retomar com `--resume` ou `--continue` traz de volta qualquer tarefa que não tenha [expirado](#seven-day-expiry): uma tarefa recorrente criada nos últimos 7 dias, ou uma única cujo tempo agendado ainda não passou. Para agendamento que sobreviva independentemente de qualquer sessão, use [Routines](/pt/routines) para criar uma rotina na infraestrutura gerenciada pela Anthropic, configure uma [tarefa agendada do Desktop](/pt/desktop-scheduled-tasks) ou use [GitHub Actions](/pt/github-actions).

16 16 

17<h2 id="compare-scheduling-options">17<h2 id="compare-scheduling-options">

18 Compare opções de agendamento18 Comparar opções de agendamento

19</h2>19</h2>

20 20 

21Claude Code offers three ways to schedule recurring or one-off work:21Claude Code offers three ways to schedule recurring or one-off work:

security.md +4 −4

Details

22 22 

23Claude Code usa permissões somente leitura rigorosas por padrão. Quando ações adicionais são necessárias (editar arquivos, executar testes, executar comandos), Claude Code solicita permissão explícita. Os usuários controlam se devem aprovar ações uma única vez ou permitir automaticamente.23Claude Code usa permissões somente leitura rigorosas por padrão. Quando ações adicionais são necessárias (editar arquivos, executar testes, executar comandos), Claude Code solicita permissão explícita. Os usuários controlam se devem aprovar ações uma única vez ou permitir automaticamente.

24 24 

25Projetamos Claude Code para ser transparente e seguro. Por exemplo, exigimos aprovação para comandos bash antes de executá-los, dando a você controle direto. Esta abordagem permite que usuários e organizações configurem permissões diretamente.25Claude Code requer aprovação antes de executar comandos Bash que podem modificar seu sistema. Um conjunto integrado de comandos somente leitura como `ls`, `cat` e `git status` é executado sem um prompt. Esta abordagem permite que usuários e organizações configurem permissões diretamente.

26 26 

27Para configuração detalhada de permissões, consulte [Permissions](/pt/permissions).27Para configuração detalhada de permissões, consulte [Permissions](/pt/permissions).

28 28 


56* **Sistema de permissões**: Operações sensíveis requerem aprovação explícita56* **Sistema de permissões**: Operações sensíveis requerem aprovação explícita

57* **Análise com reconhecimento de contexto**: Detecta instruções potencialmente prejudiciais analisando a solicitação completa57* **Análise com reconhecimento de contexto**: Detecta instruções potencialmente prejudiciais analisando a solicitação completa

58* **Sanitização de entrada**: Previne injeção de comando processando entradas do usuário58* **Sanitização de entrada**: Previne injeção de comando processando entradas do usuário

59* **Lista de bloqueio de comandos**: Bloqueia comandos arriscados que buscam conteúdo arbitrário da web como `curl` e `wget` por padrão. Quando explicitamente permitido, esteja ciente das [limitações do padrão de permissão](/pt/permissions#tool-specific-permission-rules)59* **Aprovação de comando de rede**: Comandos que buscam conteúdo da web como `curl` e `wget` não são aprovados automaticamente por padrão. Eles solicitam aprovação como qualquer outro comando Bash não somente leitura, portanto você ainda pode aprovar uma vez ou adicionar uma regra de permissão explícita como `Bash(curl *)`. Para bloqueá-los completamente, adicione-os a [`permissions.deny`](/pt/permissions#tool-specific-permission-rules)

60 60 

61<h3 id="privacy-safeguards">61<h3 id="privacy-safeguards">

62 Proteções de privacidade62 Proteções de privacidade


77* **Aprovação de solicitação de rede**: Ferramentas que fazem solicitações de rede requerem aprovação do usuário por padrão77* **Aprovação de solicitação de rede**: Ferramentas que fazem solicitações de rede requerem aprovação do usuário por padrão

78* **Janelas de contexto isoladas**: Web fetch usa uma janela de contexto separada para evitar injetar prompts potencialmente maliciosos78* **Janelas de contexto isoladas**: Web fetch usa uma janela de contexto separada para evitar injetar prompts potencialmente maliciosos

79* **Verificação de confiança**: Primeiras execuções de base de código e novos MCP servers requerem verificação de confiança79* **Verificação de confiança**: Primeiras execuções de base de código e novos MCP servers requerem verificação de confiança

80 * Nota: A verificação de confiança é desabilitada ao executar de forma não interativa com a flag `-p`. A exceção é [`--worktree`](/pt/worktrees), que ainda requer que a confiança tenha sido aceita para o diretório80 * Nota: A verificação de confiança é desabilitada ao executar de forma não interativa com a flag `-p`

81 * Nota: Quando você inicia Claude Code diretamente no seu diretório inicial, a aceitação de confiança é mantida apenas para a sessão atual e não é gravada em disco, portanto o prompt reaparece a cada inicialização. Não há configuração para persistir isso. Inicie Claude Code a partir de um subdiretório do projeto, onde a aceitação de confiança é salva por diretório81 * Nota: Quando você inicia Claude Code diretamente no seu diretório inicial, a aceitação de confiança é mantida apenas para a sessão atual e não é gravada em disco, portanto o prompt reaparece a cada inicialização. Não há configuração para persistir isso. Inicie Claude Code a partir de um subdiretório do projeto, onde a aceitação de confiança é salva por diretório

82* **Detecção de injeção de comando**: Comandos bash suspeitos requerem aprovação manual mesmo se previamente permitidos82* **Detecção de injeção de comando**: Comandos bash suspeitos requerem aprovação manual mesmo se previamente permitidos

83* **Correspondência fail-closed**: Comandos não correspondidos padrão para exigir aprovação manual83* **Correspondência fail-closed**: Comandos não correspondidos padrão para exigir aprovação manual

84* **Descrições em linguagem natural**: Comandos bash complexos incluem explicações para compreensão do usuário84* **Descrições em linguagem natural**: Comandos bash complexos incluem explicações para compreensão do usuário

85* **Armazenamento seguro de credenciais**: Chaves de API e tokens são criptografados. Consulte [Credential Management](/pt/authentication#credential-management)85* **Armazenamento seguro de credenciais**: Chaves de API e tokens são armazenados no Keychain do macOS quando disponível, e protegidos por permissões de arquivo no Windows e Linux. Consulte [Credential Management](/pt/authentication#credential-management)

86 86 

87<Warning>87<Warning>

88 **Risco de segurança do WebDAV no Windows**: Ao executar Claude Code no Windows, recomendamos contra ativar WebDAV ou permitir que Claude Code acesse caminhos como `\\*` que podem conter subdiretórios WebDAV. [WebDAV foi descontinuado pela Microsoft](https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features#:~:text=The%20Webclient%20\(WebDAV\)%20service%20is%20deprecated) devido a riscos de segurança. Ativar WebDAV pode permitir que Claude Code dispare solicitações de rede para hosts remotos, contornando o sistema de permissões.88 **Risco de segurança do WebDAV no Windows**: Ao executar Claude Code no Windows, recomendamos contra ativar WebDAV ou permitir que Claude Code acesse caminhos como `\\*` que podem conter subdiretórios WebDAV. [WebDAV foi descontinuado pela Microsoft](https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features#:~:text=The%20Webclient%20\(WebDAV\)%20service%20is%20deprecated) devido a riscos de segurança. Ativar WebDAV pode permitir que Claude Code dispare solicitações de rede para hosts remotos, contornando o sistema de permissões.

Details

174 174 

175O Claude Code aplica atualizações de configurações automaticamente sem reinicialização, exceto para configurações avançadas como configuração OpenTelemetry, que exigem uma reinicialização completa para entrar em vigor.175O Claude Code aplica atualizações de configurações automaticamente sem reinicialização, exceto para configurações avançadas como configuração OpenTelemetry, que exigem uma reinicialização completa para entrar em vigor.

176 176 

177<h3 id="invalid-entries-in-delivered-settings">

178 Entradas inválidas em configurações entregues

179</h3>

180 

181Os payloads entregues são analisados com tolerância usando as mesmas regras que as outras fontes gerenciadas. Quando um payload contém uma entrada que falha na validação do esquema, o Claude Code remove essa entrada, exibe um erro de validação e aplica todas as configurações válidas restantes. Consulte [Entradas inválidas em configurações gerenciadas](/pt/settings#invalid-entries-in-managed-settings) para o comportamento em nível de campo, incluindo como os campos de aplicação de segurança são tratados. Requer Claude Code v2.1.169 ou posterior.

182 

183A entrega gerenciada pelo servidor adiciona esses comportamentos:

184 

185* O cache em `~/.claude/remote-settings.json` armazena o payload salvo com entradas inválidas removidas. O payload inválido bruto nunca é persistido.

186* Quando nenhum campo no payload pode ser salvo, o Claude Code mantém as últimas configurações em cache aceitas e registra um erro fatal.

187* A [caixa de diálogo de aprovação de segurança](#security-approval-dialogs) avalia o payload salvo, portanto uma entrada inválida removida nunca é apresentada para aprovação e nunca é executada.

188 

189Para depurar problemas de entrega, execute `claude --debug-file <path>` e procure no log por `Remote settings`. Valide uma alteração de payload com `claude doctor` em uma máquina de teste antes de implantá-la na organização.

190 

177<h3 id="enforce-fail-closed-startup">191<h3 id="enforce-fail-closed-startup">

178 Impor inicialização com falha fechada192 Impor inicialização com falha fechada

179</h3>193</h3>

sessions.md +5 −5

Details

30| `claude --from-pr <number>` | Retoma a sessão vinculada a esse pull request |30| `claude --from-pr <number>` | Retoma a sessão vinculada a esse pull request |

31| `/resume` | Alterna para uma conversa diferente de dentro de uma sessão ativa |31| `/resume` | Alterna para uma conversa diferente de dentro de uma sessão ativa |

32 32 

33As sessões criadas com [`claude -p`](/pt/headless) ou o [Agent SDK](/pt/agent-sdk/overview) não aparecem no seletor de sessão, mas você ainda pode retomar uma passando seu ID de sessão para `claude --resume <session-id>`.33As sessões criadas com [`claude -p`](/pt/headless) ou o [Agent SDK](/pt/agent-sdk/overview) não aparecem no seletor de sessão, mas você ainda pode retomar uma passando seu ID de sessão para `claude --resume <session-id>`. Execute isto a partir do diretório em que a sessão foi iniciada: a busca de ID de sessão é limitada ao diretório do projeto atual e seus git worktrees, portanto uma sessão criada em outro lugar relata `No conversation found with session ID: <session-id>`.

34 34 

35<h3 id="where-the-session-picker-looks">35<h3 id="where-the-session-picker-looks">

36 Onde o seletor de sessão procura36 Onde o seletor de sessão procura

37</h3>37</h3>

38 38 

39As sessões são armazenadas por diretório de projeto. Por padrão, o seletor de sessão mostra sessões interativas da worktree atual, além de sessões iniciadas em outro lugar que adicionaram o diretório atual com `/add-dir`. Use `Ctrl+W` para expandir para todas as worktrees do repositório ou `Ctrl+A` para expandir para cada projeto nesta máquina.39As sessões são armazenadas por diretório de projeto. Por padrão, o seletor de sessão mostra sessões interativas da worktree atual, além de sessões iniciadas em outro lugar que adicionaram o diretório atual com `/add-dir`. A partir da v2.1.169, mover uma sessão com [`/cd`](/pt/commands) a relocata para o armazenamento de projeto do novo diretório, para que apareça no seletor desse diretório depois. Use `Ctrl+W` para expandir para todas as worktrees do repositório ou `Ctrl+A` para expandir para cada projeto nesta máquina.

40 40 

41Selecionar uma sessão de outra worktree do mesmo repositório a retoma no local. Selecionar uma sessão de um projeto não relacionado copia um comando `cd` e retoma para sua área de transferência.41Selecionar uma sessão de outra worktree do mesmo repositório a retoma no local. Selecionar uma sessão de um projeto não relacionado copia um comando `cd` e retoma para sua área de transferência.

42 42 


54Dê às sessões nomes descritivos para que sejam encontráveis no seletor de sessão e retomáveis por nome. Isso é mais importante quando você está trabalhando em várias tarefas em paralelo.54Dê às sessões nomes descritivos para que sejam encontráveis no seletor de sessão e retomáveis por nome. Isso é mais importante quando você está trabalhando em várias tarefas em paralelo.

55 55 

56| Quando | Como definir o nome |56| Quando | Como definir o nome |

57| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |57| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

58| Na inicialização | `claude -n auth-refactor` |58| Na inicialização | `claude -n auth-refactor` |

59| Durante uma sessão | `/rename auth-refactor`. O nome também aparece na barra de prompt |59| Durante uma sessão | `/rename auth-refactor`. O nome também aparece na barra de prompt |

60| Do seletor de sessão | Destaque uma sessão e pressione `Ctrl+R` |60| Do seletor de sessão | Destaque uma sessão e pressione `Ctrl+R` |

61| Na aceitação do plano | Aceitar um plano no [modo plano](/pt/permission-modes#analyze-before-you-edit-with-plan-mode) nomeia a sessão a partir do conteúdo do plano, a menos que você já tenha definido um |61| Na aceitação do plano | Aceitar um plano no [Plan Mode](/pt/permission-modes#analyze-before-you-edit-with-plan-mode) nomeia a sessão a partir do conteúdo do plano, a menos que você já tenha definido um |

62 62 

63Depois que uma sessão é nomeada, retorne a ela com `claude --resume <name>` ou `/resume <name>`. Veja [Retomar uma sessão](#resume-a-session) para saber como a resolução de nomes se comporta entre worktrees.63Depois que uma sessão é nomeada, retorne a ela com `claude --resume <name>` ou `/resume <name>`. Veja [Retomar uma sessão](#resume-a-session) para saber como a resolução de nomes se comporta entre worktrees.

64 64 


127 127 

128Os transcritos são armazenados como JSONL em `~/.claude/projects/<project>/<session-id>.jsonl`, onde `<project>` é derivado do caminho do seu diretório de trabalho. Cada linha é um objeto JSON para uma mensagem, uso de ferramenta ou entrada de metadados. Para armazenar sessões em algum lugar diferente de `~/.claude`, defina [`CLAUDE_CONFIG_DIR`](/pt/env-vars). Esses arquivos locais são removidos após 30 dias por padrão; altere isso com [`cleanupPeriodDays`](/pt/settings#available-settings).128Os transcritos são armazenados como JSONL em `~/.claude/projects/<project>/<session-id>.jsonl`, onde `<project>` é derivado do caminho do seu diretório de trabalho. Cada linha é um objeto JSON para uma mensagem, uso de ferramenta ou entrada de metadados. Para armazenar sessões em algum lugar diferente de `~/.claude`, defina [`CLAUDE_CONFIG_DIR`](/pt/env-vars). Esses arquivos locais são removidos após 30 dias por padrão; altere isso com [`cleanupPeriodDays`](/pt/settings#available-settings).

129 129 

130Para suprimir gravações de transcrição inteiramente, defina [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars) ou no modo não interativo use `--no-session-persistence`.130Para suprimir gravações de transcrição inteiramente, defina [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/pt/env-vars), ou no modo não interativo use `--no-session-persistence`.

131 131 

132<h2 id="see-also">132<h2 id="see-also">

133 Veja também133 Veja também

settings.md +111 −24

Details

19</h3>19</h3>

20 20 

21| Escopo | Localização | Quem afeta | Compartilhado com a equipe? |21| Escopo | Localização | Quem afeta | Compartilhado com a equipe? |

22| :---------- | :-------------------------------------------------------------------------------------------------------- | :--------------------------------------- | :-------------------------- |22| :---------- | :-------------------------------------------------------------------------------------------------------- | :--------------------------------------- | :------------------------------------------------ |

23| **Managed** | Configurações gerenciadas pelo servidor, plist / registro, ou `managed-settings.json` em nível de sistema | Todos os usuários na máquina | Sim (implantado por TI) |23| **Managed** | Configurações gerenciadas pelo servidor, plist / registro, ou `managed-settings.json` em nível de sistema | Todos os usuários na máquina | Sim (implantado por TI) |

24| **User** | Diretório `~/.claude/` | Você, em todos os projetos | Não |24| **User** | Diretório `~/.claude/` | Você, em todos os projetos | Não |

25| **Project** | `.claude/` no repositório | Todos os colaboradores neste repositório | Sim (confirmado no git) |25| **Project** | `.claude/` no repositório | Todos os colaboradores neste repositório | Sim (confirmado no git) |

26| **Local** | `.claude/settings.local.json` | Você, apenas neste repositório | Não (ignorado pelo git) |26| **Local** | `.claude/settings.local.json` | Você, apenas neste repositório | Não (ignorado pelo git quando Claude Code o cria) |

27 27 

28<h3 id="when-to-use-each-scope">28<h3 id="when-to-use-each-scope">

29 Quando usar cada escopo29 Quando usar cada escopo


94* As **configurações do usuário** são definidas em `~/.claude/settings.json` e se aplicam a todos os projetos.94* As **configurações do usuário** são definidas em `~/.claude/settings.json` e se aplicam a todos os projetos.

95* As **configurações do projeto** são salvas no diretório do seu projeto:95* As **configurações do projeto** são salvas no diretório do seu projeto:

96 * `.claude/settings.json` para configurações que são verificadas no controle de origem e compartilhadas com sua equipe96 * `.claude/settings.json` para configurações que são verificadas no controle de origem e compartilhadas com sua equipe

97 * `.claude/settings.local.json` para configurações que não são verificadas, úteis para preferências pessoais e experimentação. O Claude Code configurará o git para ignorar `.claude/settings.local.json` quando for criado.97 * `.claude/settings.local.json` para configurações que não são verificadas, úteis para preferências pessoais e experimentação. Quando o Claude Code cria `.claude/settings.local.json`, ele configura o git para ignorar o arquivo. Se você criar o arquivo você mesmo, adicione-o ao seu gitignore manualmente.

98* **Configurações gerenciadas**: Para organizações que precisam de controle centralizado, o Claude Code suporta múltiplos mecanismos de entrega para configurações gerenciadas. Todos usam o mesmo formato JSON e não podem ser substituídos por configurações de usuário ou projeto:98* **Configurações gerenciadas**: Para organizações que precisam de controle centralizado, o Claude Code suporta múltiplos mecanismos de entrega para configurações gerenciadas. Todos usam o mesmo formato JSON e não podem ser substituídos por configurações de usuário ou projeto:

99 99 

100 * **Configurações gerenciadas pelo servidor**: entregues dos servidores da Anthropic através do console de administração do Claude.ai. Veja [configurações gerenciadas pelo servidor](/pt/server-managed-settings).100 * **Configurações gerenciadas pelo servidor**: entregues dos servidores da Anthropic através do console de administração do Claude.ai. Veja [configurações gerenciadas pelo servidor](/pt/server-managed-settings).


174* `model`: use [`/model`](/pt/model-config#setting-your-model) para mudar no meio da sessão174* `model`: use [`/model`](/pt/model-config#setting-your-model) para mudar no meio da sessão

175* [`outputStyle`](/pt/output-styles): parte do prompt do sistema, que é reconstruído em `/clear` ou reinicialização175* [`outputStyle`](/pt/output-styles): parte do prompt do sistema, que é reconstruído em `/clear` ou reinicialização

176 176 

177<h3 id="invalid-entries-in-managed-settings">

178 Entradas inválidas em configurações gerenciadas

179</h3>

180 

181Configurações gerenciadas analisam com tolerância. Quando uma configuração gerenciada contém uma entrada que falha na validação de esquema, o Claude Code remove essa entrada, registra um aviso, e aplica todas as políticas válidas restantes. Um único erro de digitação não pode desabilitar o resto da política da sua organização. Este comportamento é consistente em todos os três mecanismos de entrega: [configurações gerenciadas pelo servidor](/pt/server-managed-settings), políticas de plist e registro implantadas através de MDM, e arquivos `managed-settings.json`. Requer Claude Code v2.1.169 ou posterior.

182 

183Campos de aplicação de segurança são tratados por campo em vez de serem removidos no atacado quando estão presentes mas inválidos:

184 

185| Campo | Comportamento quando presente mas inválido |

186| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

187| `allowedMcpServers` | Aplicado como uma lista de permissões vazia, então nenhum MCP server é admitido até que o valor seja corrigido. Uma entrada individual inválida é removida e o subconjunto válido é aplicado. |

188| `allowManagedMcpServersOnly` | Tratado como `true`. |

189| `availableModels` | {/* min-version: 2.1.175 */}Aplicado como uma lista de permissões vazia, então apenas o modelo Padrão está disponível até que o valor seja corrigido. Uma entrada individual não-string é removida e o subconjunto válido é aplicado. Se aplica em v2.1.175 e posterior. |

190| `enforceAvailableModels` | {/* min-version: 2.1.175 */}Tratado como `true`. Se aplica em v2.1.175 e posterior. |

191| `forceLoginOrgUUID` | Nenhuma organização é permitida fazer login até que o valor seja corrigido. |

192| `deniedMcpServers` | Uma entrada individual inválida é removida e o subconjunto válido é aplicado. Um valor totalmente inválido é descartado com um aviso, já que negar cada servidor bloquearia servidores que a política nunca nomeou. |

193 

194`requiredMinimumVersion` e `requiredMaximumVersion` falham abertos por design: um valor inválido é removido em vez de ser aplicado, então um push de política ruim não pode impedir que o Claude Code inicie.

195 

196Erros de validação aparecem em três lugares:

197 

198* Sessões interativas mostram um diálogo na inicialização listando as entradas inválidas.

199* Execuções headless com `-p` imprimem um resumo para stderr.

200* [`claude doctor`](/pt/debug-your-config) lista cada entrada inválida com sua fonte e campo.

201 

202Valide mudanças de política executando `claude doctor` em uma máquina de teste antes de implantá-las em toda a frota.

203 

204Esta tolerância se aplica apenas a configurações gerenciadas. Arquivos de configuração de usuário, projeto e local permanecem rigorosos: um arquivo que falha na validação é rejeitado como um todo e relatado.

205 

177<h3 id="available-settings">206<h3 id="available-settings">

178 Configurações disponíveis207 Configurações disponíveis

179</h3>208</h3>


181`settings.json` suporta várias opções:210`settings.json` suporta várias opções:

182 211 

183| Chave | Descrição | Exemplo |212| Chave | Descrição | Exemplo |

184| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- |213| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |

214| `advisorModel` | {/* min-version: 2.1.98 */}Modelo para a [ferramenta advisor](/pt/advisor) do lado do servidor. Aceita um alias de modelo como `"opus"`, `"sonnet"`, ou `"fable"` ({/* min-version: 2.1.170 */}v2.1.170+), ou um ID de modelo completo. Escrito automaticamente quando você executa `/advisor`. Desdefina para desabilitar o advisor. Requer Claude Code v2.1.98 ou posterior | `"opus"` |

185| `agent` | Executar a thread principal como um subagent nomeado, e definir o agente padrão para sessões despachadas de `claude agents`. Aplica o prompt do sistema, restrições de ferramenta e modelo do subagent. Veja [Invocar subagents explicitamente](/pt/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |215| `agent` | Executar a thread principal como um subagent nomeado, e definir o agente padrão para sessões despachadas de `claude agents`. Aplica o prompt do sistema, restrições de ferramenta e modelo do subagent. Veja [Invocar subagents explicitamente](/pt/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |

216| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}Quando [Controle Remoto](/pt/remote-control) está conectado, permitir que Claude envie notificações push proativas para seu telefone, por exemplo quando uma tarefa longa termina. Padrão: `false`. Aparece em `/config` como **Push when Claude decides**. Veja [Notificações push móveis](/pt/remote-control#mobile-push-notifications). Requer Claude Code v2.1.119 ou posterior | `true` |

186| `allowAllClaudeAiMcps` | (Apenas configurações gerenciadas) Carregar conectores claude.ai ao lado de um `managed-mcp.json` implantado, que de outra forma assume controle exclusivo e os suprime. Veja [Configuração MCP gerenciada](/pt/managed-mcp) | `true` |217| `allowAllClaudeAiMcps` | (Apenas configurações gerenciadas) Carregar conectores claude.ai ao lado de um `managed-mcp.json` implantado, que de outra forma assume controle exclusivo e os suprime. Veja [Configuração MCP gerenciada](/pt/managed-mcp) | `true` |

187| `allowedChannelPlugins` | (Apenas configurações gerenciadas) Lista de permissões de plugins de canal que podem enviar mensagens. Substitui a lista de permissões padrão da Anthropic quando definido. Indefinido = voltar para o padrão, array vazio = bloquear todos os plugins de canal. Requer `channelsEnabled: true`. Veja [Restringir quais plugins de canal podem executar](/pt/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |218| `allowedChannelPlugins` | (Apenas configurações gerenciadas) Lista de permissões de plugins de canal que podem enviar mensagens. Substitui a lista de permissões padrão da Anthropic quando definido. Indefinido = voltar para o padrão, array vazio = bloquear todos os plugins de canal. Requer `channelsEnabled: true`. Veja [Restringir quais plugins de canal podem executar](/pt/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |

188| `allowedHttpHookUrls` | Lista de permissões de padrões de URL que hooks HTTP podem almejar. Suporta `*` como curinga. Quando definido, hooks com URLs não correspondentes são bloqueados. Indefinido = sem restrição, array vazio = bloquear todos os hooks HTTP. Arrays se mesclam entre fontes de configuração. Veja [Configuração de hooks](#hook-configuration) | `["https://hooks.example.com/*"]` |219| `allowedHttpHookUrls` | Lista de permissões de padrões de URL que hooks HTTP podem almejar. Suporta `*` como curinga. Quando definido, hooks com URLs não correspondentes são bloqueados. Indefinido = sem restrição, array vazio = bloquear todos os hooks HTTP. Arrays se mesclam entre fontes de configuração. Veja [Configuração de hooks](#hook-configuration) | `["https://hooks.example.com/*"]` |


190| `allowManagedHooksOnly` | (Apenas configurações gerenciadas) Apenas hooks gerenciados, hooks SDK, e hooks de plugins força-habilitados em configurações gerenciadas `enabledPlugins` são carregados. Hooks de usuário, projeto e todos os outros plugins são bloqueados. Veja [Configuração de hooks](#hook-configuration) | `true` |221| `allowManagedHooksOnly` | (Apenas configurações gerenciadas) Apenas hooks gerenciados, hooks SDK, e hooks de plugins força-habilitados em configurações gerenciadas `enabledPlugins` são carregados. Hooks de usuário, projeto e todos os outros plugins são bloqueados. Veja [Configuração de hooks](#hook-configuration) | `true` |

191| `allowManagedMcpServersOnly` | (Apenas configurações gerenciadas) Apenas `allowedMcpServers` de configurações gerenciadas são respeitados. `deniedMcpServers` ainda se mescla de todas as fontes. Usuários ainda podem adicionar MCP servers, mas apenas a lista de permissões definida pelo administrador se aplica. Veja [Configuração MCP gerenciada](/pt/managed-mcp) | `true` |222| `allowManagedMcpServersOnly` | (Apenas configurações gerenciadas) Apenas `allowedMcpServers` de configurações gerenciadas são respeitados. `deniedMcpServers` ainda se mescla de todas as fontes. Usuários ainda podem adicionar MCP servers, mas apenas a lista de permissões definida pelo administrador se aplica. Veja [Configuração MCP gerenciada](/pt/managed-mcp) | `true` |

192| `allowManagedPermissionRulesOnly` | (Apenas configurações gerenciadas) Impedir que configurações de usuário e projeto definam regras de permissão `allow`, `ask` ou `deny`. Apenas regras em configurações gerenciadas se aplicam. Veja [Configurações apenas gerenciadas](/pt/permissions#managed-only-settings) | `true` |223| `allowManagedPermissionRulesOnly` | (Apenas configurações gerenciadas) Impedir que configurações de usuário e projeto definam regras de permissão `allow`, `ask` ou `deny`. Apenas regras em configurações gerenciadas se aplicam. Veja [Configurações apenas gerenciadas](/pt/permissions#managed-only-settings) | `true` |

193| `alwaysThinkingEnabled` | Ativar [pensamento estendido](/pt/model-config#extended-thinking) por padrão para todas as sessões. Tipicamente configurado via comando `/config` em vez de editar diretamente. Para forçar o pensamento desligado independentemente desta configuração, defina [`CLAUDE_CODE_DISABLE_THINKING`](/pt/env-vars) em `env` | `true` |224| `alwaysThinkingEnabled` | Ativar [pensamento estendido](/pt/model-config#extended-thinking) por padrão para todas as sessões. Tipicamente configurado via comando `/config` em vez de editar diretamente. Para forçar o pensamento desligado independentemente desta configuração, defina [`MAX_THINKING_TOKENS=0`](/pt/env-vars) em `env`, que desabilita o pensamento na API Anthropic exceto em Fable 5, que não pode ter o pensamento desligado. Em [provedores de terceiros](/pt/third-party-integrations) isto omite o parâmetro `thinking` em vez disso, e modelos de raciocínio adaptativo ainda podem pensar | `true` |

194| `apiKeyHelper` | Script personalizado, a ser executado em `/bin/sh`, para gerar um valor de autenticação. Este valor será enviado como cabeçalhos `X-Api-Key` e `Authorization: Bearer` para solicitações de modelo. Defina o intervalo de atualização com [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/pt/env-vars) | `/bin/generate_temp_api_key.sh` |225| `apiKeyHelper` | Script personalizado, a ser executado em `/bin/sh`, para gerar um valor de autenticação. Este valor será enviado como cabeçalhos `X-Api-Key` e `Authorization: Bearer` para solicitações de modelo. Defina o intervalo de atualização com [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/pt/env-vars) | `/bin/generate_temp_api_key.sh` |

195| `attribution` | Personalizar atribuição para commits git e pull requests. Veja [Configurações de atribuição](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |226| `attribution` | Personalizar atribuição para commits git e pull requests. Veja [Configurações de atribuição](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

227| `autoCompactEnabled` | {/* min-version: 2.1.119 */}Compactar automaticamente a conversa quando o contexto se aproxima do limite. Padrão: `true`. Aparece em `/config` como **Auto-compact**. Para desabilitar via variável de ambiente, defina [`DISABLE_AUTO_COMPACT`](/pt/env-vars) em `env` | `false` |

196| `autoMemoryDirectory` | Diretório personalizado para armazenamento de [memória automática](/pt/memory#storage-location). Aceita um caminho absoluto ou um caminho com prefixo `~/`. A partir de configurações de projeto ou local, isto é honrado apenas após você aceitar o diálogo de confiança do workspace, já que um repositório clonado pode fornecer este arquivo | `"~/my-memory-dir"` |228| `autoMemoryDirectory` | Diretório personalizado para armazenamento de [memória automática](/pt/memory#storage-location). Aceita um caminho absoluto ou um caminho com prefixo `~/`. A partir de configurações de projeto ou local, isto é honrado apenas após você aceitar o diálogo de confiança do workspace, já que um repositório clonado pode fornecer este arquivo | `"~/my-memory-dir"` |

197| `autoMemoryEnabled` | Ativar [memória automática](/pt/memory#enable-or-disable-auto-memory). Quando `false`, Claude não lê ou escreve no diretório de memória automática. Padrão: `true`. Você também pode alternar isto com `/memory` durante uma sessão. Para desabilitar via variável de ambiente, defina [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/pt/env-vars) em `env` | `false` |229| `autoMemoryEnabled` | Ativar [memória automática](/pt/memory#enable-or-disable-auto-memory). Quando `false`, Claude não lê ou escreve no diretório de memória automática. Padrão: `true`. Você também pode alternar isto com `/memory` durante uma sessão. Para desabilitar via variável de ambiente, defina [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/pt/env-vars) em `env` | `false` |

198| `autoMode` | Personalizar o que o classificador de [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) bloqueia e permite. Contém arrays `environment`, `allow`, `soft_deny`, e `hard_deny` de regras em prosa. Inclua a string literal `"$defaults"` em um array para herdar as regras integradas nessa posição. Veja [Configurar modo automático](/pt/auto-mode-config). Não lido de configurações de projeto compartilhadas | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |230| `autoMode` | Personalizar o que o classificador de [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) bloqueia e permite. Contém arrays `environment`, `allow`, `soft_deny`, e `hard_deny` de regras em prosa. Inclua a string literal `"$defaults"` em um array para herdar as regras integradas nessa posição. Veja [Configurar modo automático](/pt/auto-mode-config). Não lido de configurações de projeto compartilhadas | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

199| `autoScrollEnabled` | Em [renderização fullscreen](/pt/fullscreen), seguir nova saída até o fundo da conversa. Padrão: `true`. Aparece em `/config` como **Auto-scroll**. Prompts de permissão ainda rolam para a vista quando isto está desligado | `false` |231| `autoScrollEnabled` | Em [renderização fullscreen](/pt/fullscreen), seguir nova saída até o fundo da conversa. Padrão: `true`. Aparece em `/config` como **Auto-scroll**. Prompts de permissão ainda rolam para a vista quando isto está desligado | `false` |

200| `autoUpdatesChannel` | Canal de lançamento a seguir para atualizações. Use `"stable"` para uma versão que é tipicamente cerca de uma semana antiga e pula versões com regressões maiores, ou `"latest"` (padrão) para o lançamento mais recente. Para desabilitar auto-atualizações completamente, defina [`DISABLE_AUTOUPDATER`](/pt/setup#disable-auto-updates) em `env` | `"stable"` |232| `autoUpdatesChannel` | Canal de lançamento a seguir para atualizações. Use `"stable"` para uma versão que é tipicamente cerca de uma semana antiga e pula versões com regressões maiores, ou `"latest"` (padrão) para o lançamento mais recente. Para desabilitar auto-atualizações completamente, defina [`DISABLE_AUTOUPDATER`](/pt/setup#disable-auto-updates) em `env` | `"stable"` |

201| `availableModels` | Restringir quais modelos os usuários podem selecionar via `/model`, `--model`, ou `ANTHROPIC_MODEL`. Não afeta a opção Padrão. Veja [Restringir seleção de modelo](/pt/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |233| `availableModels` | Restringir quais modelos os usuários podem selecionar para a sessão principal, [subagents](/pt/sub-agents), e o [advisor](/pt/advisor). Veja [Restringir seleção de modelo](/pt/model-config#restrict-model-selection). Veja `enforceAvailableModels` para também restringir Padrão | `["sonnet", "haiku"]` |

202| `awaySummaryEnabled` | Mostrar um resumo de sessão de uma linha quando você retorna ao terminal após alguns minutos ausente. Defina como `false` ou desative Resumo de sessão em `/config` para desabilitar. Mesmo que [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/pt/env-vars) | `true` |234| `awaySummaryEnabled` | Mostrar um resumo de sessão de uma linha quando você retorna ao terminal após alguns minutos ausente. Defina como `false` ou desative Resumo de sessão em `/config` para desabilitar. Mesmo que [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/pt/env-vars) | `true` |

203| `awsAuthRefresh` | Script personalizado que modifica o diretório `.aws` (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |235| `awsAuthRefresh` | Script personalizado que modifica o diretório `.aws` (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

204| `awsCredentialExport` | Script personalizado que produz JSON com credenciais AWS (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |236| `awsCredentialExport` | Script personalizado que produz JSON com credenciais AWS (veja [configuração avançada de credenciais](/pt/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |


213| `disableAgentView` | Defina como `true` para desligar [agentes em background e visualização de agente](/pt/agent-view): `claude agents`, `--bg`, `/background`, e o supervisor sob demanda. Tipicamente definido em [configurações gerenciadas](/pt/permissions#managed-settings). Equivalente a definir `CLAUDE_CODE_DISABLE_AGENT_VIEW` como `1` | `true` |245| `disableAgentView` | Defina como `true` para desligar [agentes em background e visualização de agente](/pt/agent-view): `claude agents`, `--bg`, `/background`, e o supervisor sob demanda. Tipicamente definido em [configurações gerenciadas](/pt/permissions#managed-settings). Equivalente a definir `CLAUDE_CODE_DISABLE_AGENT_VIEW` como `1` | `true` |

214| `disableAllHooks` | Desabilitar todos os [hooks](/pt/hooks) e qualquer [linha de status](/pt/statusline) personalizada | `true` |246| `disableAllHooks` | Desabilitar todos os [hooks](/pt/hooks) e qualquer [linha de status](/pt/statusline) personalizada | `true` |

215| `disableAutoMode` | Defina como `"disable"` para impedir que o [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) seja ativado. Remove `auto` do ciclo `Shift+Tab` e rejeita `--permission-mode auto` na inicialização. Mais útil em [configurações gerenciadas](/pt/permissions#managed-settings) onde os usuários não podem substituir | `"disable"` |247| `disableAutoMode` | Defina como `"disable"` para impedir que o [modo automático](/pt/permission-modes#eliminate-prompts-with-auto-mode) seja ativado. Remove `auto` do ciclo `Shift+Tab` e rejeita `--permission-mode auto` na inicialização. Mais útil em [configurações gerenciadas](/pt/permissions#managed-settings) onde os usuários não podem substituir | `"disable"` |

248| `disableBundledSkills` | Defina como `true` para desabilitar as [skills](/pt/skills) e workflows que vêm com o Claude Code: skills agrupadas e workflows são removidos completamente, enquanto comandos slash integrados como `/init` permanecem digitáveis mas são ocultados do modelo. Skills de plugins, `.claude/skills/`, e `.claude/commands/` não são afetadas. Equivalente a definir `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` como `1` | `true` |

216| `disableDeepLinkRegistration` | Defina como `"disable"` para impedir que o Claude Code registre o manipulador de protocolo `claude-cli://` com o sistema operacional na inicialização. [Deep links](/pt/deep-links) permitem que ferramentas externas abram uma sessão do Claude Code com um prompt pré-preenchido. Útil em ambientes onde o registro de manipulador de protocolo é restrito ou gerenciado separadamente | `"disable"` |249| `disableDeepLinkRegistration` | Defina como `"disable"` para impedir que o Claude Code registre o manipulador de protocolo `claude-cli://` com o sistema operacional na inicialização. [Deep links](/pt/deep-links) permitem que ferramentas externas abram uma sessão do Claude Code com um prompt pré-preenchido. Útil em ambientes onde o registro de manipulador de protocolo é restrito ou gerenciado separadamente | `"disable"` |

217| `disabledMcpjsonServers` | Lista de MCP servers específicos de arquivos `.mcp.json` para rejeitar | `["filesystem"]` |250| `disabledMcpjsonServers` | Lista de MCP servers específicos de arquivos `.mcp.json` para rejeitar | `["filesystem"]` |

218| `disableRemoteControl` | {/* min-version: 2.1.128 */}Desabilitar [Controle Remoto](/pt/remote-control): bloqueia `claude remote-control`, a flag `--remote-control`, auto-start, e o toggle em sessão. Tipicamente colocado em [configurações gerenciadas](/pt/permissions#managed-settings) para aplicação de MDM por dispositivo, mas funciona de qualquer escopo. Requer Claude Code v2.1.128 ou posterior | `true` |251| `disableRemoteControl` | {/* min-version: 2.1.128 */}Desabilitar [Controle Remoto](/pt/remote-control): bloqueia `claude remote-control`, a flag `--remote-control`, auto-start, e o toggle em sessão. Tipicamente colocado em [configurações gerenciadas](/pt/permissions#managed-settings) para aplicação de MDM por dispositivo, mas funciona de qualquer escopo. Requer Claude Code v2.1.128 ou posterior | `true` |


222| `effortLevel` | Persistir o [nível de esforço](/pt/model-config#adjust-effort-level) entre sessões. Aceita `"low"`, `"medium"`, `"high"`, ou `"xhigh"`. Escrito automaticamente quando você executa `/effort` com um desses valores. `--effort` e [`CLAUDE_CODE_EFFORT_LEVEL`](/pt/env-vars) substituem isto para uma sessão. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) para modelos suportados | `"xhigh"` |255| `effortLevel` | Persistir o [nível de esforço](/pt/model-config#adjust-effort-level) entre sessões. Aceita `"low"`, `"medium"`, `"high"`, ou `"xhigh"`. Escrito automaticamente quando você executa `/effort` com um desses valores. `--effort` e [`CLAUDE_CODE_EFFORT_LEVEL`](/pt/env-vars) substituem isto para uma sessão. Veja [Ajustar nível de esforço](/pt/model-config#adjust-effort-level) para modelos suportados | `"xhigh"` |

223| `enableAllProjectMcpServers` | Aprovar automaticamente todos os MCP servers definidos em arquivos `.mcp.json` do projeto | `true` |256| `enableAllProjectMcpServers` | Aprovar automaticamente todos os MCP servers definidos em arquivos `.mcp.json` do projeto | `true` |

224| `enabledMcpjsonServers` | Lista de MCP servers específicos de arquivos `.mcp.json` para aprovar | `["memory", "github"]` |257| `enabledMcpjsonServers` | Lista de MCP servers específicos de arquivos `.mcp.json` para aprovar | `["memory", "github"]` |

258| `enforceAvailableModels` | {/* min-version: 2.1.175 */}Quando `true` e `availableModels` é uma lista não-vazia em configurações gerenciadas ou de política, o modelo Padrão também é restringido à lista de permissões. Veja [Restringir seleção de modelo](/pt/model-config#restrict-model-selection) para detalhes e o [comportamento de mesclagem](/pt/model-config#merge-behavior) quando `availableModels` é definido em múltiplos níveis. Requer Claude Code v2.1.175 ou posterior | `true` |

225| `env` | Variáveis de ambiente aplicadas a cada sessão e a subprocessos que Claude Code gera a partir dela. {/* min-version: 2.1.143 */}A partir da v2.1.143, `NO_COLOR` e `FORCE_COLOR` definidos aqui são passados para subprocessos mas não mudam as cores da interface do Claude Code. Defina estes em seu shell antes de lançar `claude` para mudar as cores da interface | `{"FOO": "bar"}` |259| `env` | Variáveis de ambiente aplicadas a cada sessão e a subprocessos que Claude Code gera a partir dela. {/* min-version: 2.1.143 */}A partir da v2.1.143, `NO_COLOR` e `FORCE_COLOR` definidos aqui são passados para subprocessos mas não mudam as cores da interface do Claude Code. Defina estes em seu shell antes de lançar `claude` para mudar as cores da interface | `{"FOO": "bar"}` |

260| `fallbackModel` | Modelo(s) de fallback para tentar em ordem quando o modelo primário está sobrecarregado ou indisponível. O Claude Code muda para o próximo modelo disponível na cadeia para o resto do turno e mostra um aviso. `"default"` expande para o modelo padrão. Cadeias são limitadas a três modelos; entradas extras são ignoradas. Ao contrário da maioria das configurações de array, esta chave não se mescla entre arquivos de configuração: o arquivo de precedência mais alta que a define fornece a cadeia inteira. A flag [`--fallback-model`](/pt/cli-reference#cli-flags) substitui isto para uma sessão. Veja [Cadeias de modelo de fallback](/pt/model-config#fallback-model-chains) | `["claude-sonnet-4-6", "claude-haiku-4-5"]` |

226| `fastModePerSessionOptIn` | Quando `true`, o modo rápido não persiste entre sessões. Cada sessão começa com modo rápido desligado, exigindo que os usuários o habilitem com `/fast`. A preferência de modo rápido do usuário ainda é salva. Veja [Exigir opt-in por sessão](/pt/fast-mode#require-per-session-opt-in) | `true` |261| `fastModePerSessionOptIn` | Quando `true`, o modo rápido não persiste entre sessões. Cada sessão começa com modo rápido desligado, exigindo que os usuários o habilitem com `/fast`. A preferência de modo rápido do usuário ainda é salva. Veja [Exigir opt-in por sessão](/pt/fast-mode#require-per-session-opt-in) | `true` |

227| `feedbackSurveyRate` | Probabilidade (0–1) que a [pesquisa de qualidade de sessão](/pt/data-usage#session-quality-surveys) aparece quando elegível. Defina como `0` para suprimir completamente, ou defina [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/pt/env-vars) em `env`. Útil ao usar Bedrock, Vertex, ou Foundry onde a taxa de amostra padrão não se aplica | `0.05` |262| `feedbackSurveyRate` | Probabilidade (0–1) que a [pesquisa de qualidade de sessão](/pt/data-usage#session-quality-surveys) aparece quando elegível. Defina como `0` para suprimir completamente, ou defina [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/pt/env-vars) em `env`. Útil ao usar Bedrock, Vertex, ou Foundry onde a taxa de amostra padrão não se aplica | `0.05` |

263| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}Fazer snapshot de arquivos antes de cada edição para que [`/rewind`](/pt/checkpointing) possa restaurá-los. Padrão: `true`. Aparece em `/config` como **Rewind code (checkpoints)**. Para desabilitar via variável de ambiente, defina [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/pt/env-vars) em `env` | `false` |

228| `fileSuggestion` | Configure um script personalizado para preenchimento automático de arquivo `@`. Veja [Configurações de sugestão de arquivo](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |264| `fileSuggestion` | Configure um script personalizado para preenchimento automático de arquivo `@`. Veja [Configurações de sugestão de arquivo](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

265| `footerLinksRegexes` | {/* min-version: 2.1.176 */}Renderizar badges clicáveis extras no rodapé quando uma regex corresponde à saída de turno. Cada entrada tem um `pattern`, um modelo de URL `url` com placeholders `{name}` preenchidos de grupos de captura nomeados, e um `label` opcional. Lido apenas de configurações de usuário, flag `--settings`, e configurações gerenciadas. Veja [Badges de link de rodapé](#footer-link-badges) para restrições de URL, lista de permissões de esquema, e limites. Requer Claude Code v2.1.176 ou posterior | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |

229| `forceLoginMethod` | Use `claudeai` para restringir login a contas Claude.ai, `console` para restringir login a contas Claude Console. Quando definido em configurações gerenciadas, sessões autenticadas por `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ou `apiKeyHelper` são bloqueadas na inicialização, já que nenhum valor pode ser satisfeito sem OAuth de primeira parte. Sessões de provedor de terceiros como Bedrock, Vertex, e Foundry não são bloqueadas: elas autenticam contra seu provedor de nuvem em vez de Anthropic | `claudeai` |266| `forceLoginMethod` | Use `claudeai` para restringir login a contas Claude.ai, `console` para restringir login a contas Claude Console. Quando definido em configurações gerenciadas, sessões autenticadas por `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ou `apiKeyHelper` são bloqueadas na inicialização, já que nenhum valor pode ser satisfeito sem OAuth de primeira parte. Sessões de provedor de terceiros como Bedrock, Vertex, e Foundry não são bloqueadas: elas autenticam contra seu provedor de nuvem em vez de Anthropic | `claudeai` |

230| `forceLoginOrgUUID` | Exigir que o login pertença a uma organização Anthropic específica. Aceita uma string UUID única, que também pré-seleciona essa organização durante o login, ou um array de UUIDs onde qualquer organização listada é aceita sem pré-seleção. Quando definido em configurações gerenciadas, o login falha se a conta autenticada não pertencer a uma organização listada, e sessões autenticadas por `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ou `apiKeyHelper` são bloqueadas na inicialização já que a associação à organização não pode ser verificada para elas. Sessões de provedor de terceiros como Bedrock, Vertex, e Foundry não são bloqueadas: use seu IAM de nuvem para restringir quais contas de nuvem podem ser usadas. Um array vazio falha fechado e bloqueia o login com uma mensagem de configuração incorreta | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` ou `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |267| `forceLoginOrgUUID` | Exigir que o login pertença a uma organização Anthropic específica. Aceita uma string UUID única, que também pré-seleciona essa organização durante o login, ou um array de UUIDs onde qualquer organização listada é aceita sem pré-seleção. Quando definido em configurações gerenciadas, o login falha se a conta autenticada não pertencer a uma organização listada, e sessões autenticadas por `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, ou `apiKeyHelper` são bloqueadas na inicialização já que a associação à organização não pode ser verificada para elas. Sessões de provedor de terceiros como Bedrock, Vertex, e Foundry não são bloqueadas: use seu IAM de nuvem para restringir quais contas de nuvem podem ser usadas. Um array vazio falha fechado e bloqueia o login com uma mensagem de configuração incorreta | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` ou `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

231| `forceRemoteSettingsRefresh` | (Apenas configurações gerenciadas) Bloquear inicialização da CLI até que configurações gerenciadas remotas sejam buscadas recentemente do servidor. Se a busca falhar, a CLI sai em vez de continuar com configurações em cache ou sem configurações. Quando não definido, a inicialização continua sem esperar por configurações remotas. Veja [aplicação fail-closed](/pt/server-managed-settings#enforce-fail-closed-startup) | `true` |268| `forceRemoteSettingsRefresh` | (Apenas configurações gerenciadas) Bloquear inicialização da CLI até que configurações gerenciadas remotas sejam buscadas recentemente do servidor. Se a busca falhar, a CLI sai em vez de continuar com configurações em cache ou sem configurações. Quando não definido, a inicialização continua sem esperar por configurações remotas. Veja [aplicação fail-closed](/pt/server-managed-settings#enforce-fail-closed-startup) | `true` |


234| `httpHookAllowedEnvVars` | Lista de permissões de nomes de variáveis de ambiente que hooks HTTP podem interpolar em cabeçalhos. Quando definido, o `allowedEnvVars` efetivo de cada hook é a interseção com esta lista. Indefinido = sem restrição. Arrays se mesclam entre fontes de configuração. Veja [Configuração de hooks](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |271| `httpHookAllowedEnvVars` | Lista de permissões de nomes de variáveis de ambiente que hooks HTTP podem interpolar em cabeçalhos. Quando definido, o `allowedEnvVars` efetivo de cada hook é a interseção com esta lista. Indefinido = sem restrição. Arrays se mesclam entre fontes de configuração. Veja [Configuração de hooks](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |

235| `includeCoAuthoredBy` | **Descontinuado**: Use `attribution` em vez disso. Se deve incluir a linha `co-authored-by Claude` em commits git e pull requests (padrão: `true`) | `false` |272| `includeCoAuthoredBy` | **Descontinuado**: Use `attribution` em vez disso. Se deve incluir a linha `co-authored-by Claude` em commits git e pull requests (padrão: `true`) | `false` |

236| `includeGitInstructions` | Incluir instruções de workflow de commit e PR integradas e o snapshot de status git no prompt do sistema do Claude (padrão: `true`). Defina como `false` para remover ambos, por exemplo ao usar suas próprias skills de workflow git. A variável de ambiente `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` tem precedência sobre esta configuração quando definida | `false` |273| `includeGitInstructions` | Incluir instruções de workflow de commit e PR integradas e o snapshot de status git no prompt do sistema do Claude (padrão: `true`). Defina como `false` para remover ambos, por exemplo ao usar suas próprias skills de workflow git. A variável de ambiente `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` tem precedência sobre esta configuração quando definida | `false` |

237| `language` | Configure o idioma de resposta preferido do Claude (por exemplo, `"japanese"`, `"spanish"`, `"french"`). Claude responderá neste idioma por padrão. Também define o idioma de [ditado por voz](/pt/voice-dictation#change-the-dictation-language) | `"japanese"` |274| `inputNeededNotifEnabled` | {/* min-version: 2.1.119 */}Quando [Controle Remoto](/pt/remote-control) está conectado, enviar uma notificação push para seu telefone quando um prompt de permissão ou pergunta está aguardando sua entrada. Padrão: `false`. Aparece em `/config` como **Push when actions required**. Veja [Notificações push móveis](/pt/remote-control#mobile-push-notifications). Requer Claude Code v2.1.119 ou posterior | `true` |

238| `maxSkillDescriptionChars` | {/* min-version: 2.1.105 */}Limite de caracteres por skill no texto combinado `description` e `when_to_use` na [listagem de skills](/pt/skills#skill-descriptions-are-cut-short) que Claude vê a cada turno (padrão: `1536`). Texto mais longo que isto é truncado. Aumente para manter descrições longas intactas ao custo de mais contexto por turno; diminua para caber mais skills sob [`skillListingBudgetFraction`](#available-settings). `/doctor` mostra a contagem de truncamento atual e quais skills são afetadas. Requer Claude Code v2.1.105 ou posterior | `2048` |275| `language` | Configure o idioma de resposta preferido do Claude (por exemplo, `"japanese"`, `"spanish"`, `"french"`). Claude responderá neste idioma por padrão. Também define o idioma de [ditado por voz](/pt/voice-dictation#change-the-dictation-language) e títulos de sessão gerados automaticamente. {/* min-version: 2.1.176 */}A partir de v2.1.176, quando não definido, títulos de sessão correspondem ao idioma de sua conversa | `"japanese"` |

239| `minimumVersion` | Piso que impede auto-atualizações em background e `claude update` de instalar uma versão abaixo desta. Mudar do canal `"latest"` para `"stable"` via `/config` solicita que você fique na versão atual ou permita o downgrade. Escolher ficar define este valor. Também útil em [configurações gerenciadas](/pt/permissions#managed-settings) para fixar um mínimo em toda a organização | `"2.1.100"` |276| `maxSkillDescriptionChars` | {/* min-version: 2.1.105 */}Limite de caracteres por skill no texto combinado `description` e `when_to_use` na [listagem de skills](/pt/skills#skill-descriptions-are-cut-short) que Claude a cada turno (padrão: `1536`). Texto mais longo que isto é truncado. Aumente para manter descrições longas intactas ao custo de mais contexto por turno; diminua para caber mais skills sob [`skillListingBudgetFraction`](#available-settings). Requer Claude Code v2.1.105 ou posterior | `2048` |

277| `minimumVersion` | Piso que impede auto-atualizações em background e `claude update` de instalar uma versão abaixo desta. Mudar do canal `"latest"` para `"stable"` via `/config` solicita que você fique na versão atual ou permita o downgrade. Escolher ficar define este valor. Também útil em [configurações gerenciadas](/pt/permissions#managed-settings) para fixar um mínimo em toda a organização. Para um piso duro que bloqueia a inicialização completamente, veja `requiredMinimumVersion` | `"2.1.100"` |

240| `model` | Substituir o modelo padrão a usar para Claude Code. `--model` e [`ANTHROPIC_MODEL`](/pt/model-config#environment-variables) substituem isto para uma sessão | `"claude-sonnet-4-6"` |278| `model` | Substituir o modelo padrão a usar para Claude Code. `--model` e [`ANTHROPIC_MODEL`](/pt/model-config#environment-variables) substituem isto para uma sessão | `"claude-sonnet-4-6"` |

241| `modelOverrides` | Mapear IDs de modelo Anthropic para IDs de modelo específicos do provedor, como ARNs de perfil de inferência Bedrock. Cada entrada do seletor de modelo usa seu valor mapeado ao chamar a API do provedor. Veja [Substituir IDs de modelo por versão](/pt/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |279| `modelOverrides` | Mapear IDs de modelo Anthropic para IDs de modelo específicos do provedor, como ARNs de perfil de inferência Bedrock. Cada entrada do seletor de modelo usa seu valor mapeado ao chamar a API do provedor. Veja [Substituir IDs de modelo por versão](/pt/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

242| `otelHeadersHelper` | Script para gerar cabeçalhos OpenTelemetry dinâmicos. Executa na inicialização e periodicamente. Defina o intervalo de atualização com [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/pt/env-vars). Veja [Cabeçalhos dinâmicos](/pt/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |280| `otelHeadersHelper` | Script para gerar cabeçalhos OpenTelemetry dinâmicos. Executa na inicialização e periodicamente. Defina o intervalo de atualização com [`CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS`](/pt/env-vars). Veja [Cabeçalhos dinâmicos](/pt/monitoring-usage#dynamic-headers) | `/bin/generate_otel_headers.sh` |


244| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}(Apenas configurações gerenciadas) Controla se configurações gerenciadas fornecidas programaticamente por um processo host de incorporação, como o Agent SDK ou uma extensão IDE, se aplicam quando um nível gerenciado implantado por administrador também está presente. `"first-wins"`: as configurações fornecidas pelo pai são descartadas e apenas o nível de administrador se aplica. `"merge"`: as configurações fornecidas pelo pai se aplicam sob o nível de administrador, filtradas para que possam apertar a política mas não afrouxá-la. Não tem efeito quando nenhum nível de administrador é implantado. Padrão: `"first-wins"`. Requer Claude Code v2.1.133 ou posterior | `"merge"` |282| `parentSettingsBehavior` | {/* min-version: 2.1.133 */}(Apenas configurações gerenciadas) Controla se configurações gerenciadas fornecidas programaticamente por um processo host de incorporação, como o Agent SDK ou uma extensão IDE, se aplicam quando um nível gerenciado implantado por administrador também está presente. `"first-wins"`: as configurações fornecidas pelo pai são descartadas e apenas o nível de administrador se aplica. `"merge"`: as configurações fornecidas pelo pai se aplicam sob o nível de administrador, filtradas para que possam apertar a política mas não afrouxá-la. Não tem efeito quando nenhum nível de administrador é implantado. Padrão: `"first-wins"`. Requer Claude Code v2.1.133 ou posterior | `"merge"` |

245| `permissions` | Veja a tabela abaixo para a estrutura de permissões. | |283| `permissions` | Veja a tabela abaixo para a estrutura de permissões. | |

246| `plansDirectory` | Personalizar onde os arquivos de plano são armazenados. O caminho é relativo à raiz do projeto. Padrão: `~/.claude/plans` | `"./plans"` |284| `plansDirectory` | Personalizar onde os arquivos de plano são armazenados. O caminho é relativo à raiz do projeto. Padrão: `~/.claude/plans` | `"./plans"` |

247| `pluginSuggestionMarketplaces` | (Apenas configurações gerenciadas) Nomes de marketplace cujos plugins podem aparecer como sugestões de instalação contextual, além do marketplace oficial. Sugestões vêm da declaração `relevance` de cada plugin em sua entrada de marketplace. Um nome só tem efeito quando o marketplace está registrado na máquina e sua fonte registrada também é declarada em configurações gerenciadas, seja como a entrada `extraKnownMarketplaces` para esse nome ou como uma entrada de `strictKnownMarketplaces`. Um marketplace registrado de uma fonte diferente sob um nome na lista de permissões é ignorado. | `["acme-corp-plugins"]` |285| `pluginSuggestionMarketplaces` | (Apenas configurações gerenciadas) Nomes de marketplace cujos plugins podem aparecer como sugestões de instalação contextual. Nenhuma sugestão declarada por marketplace aparece sem esta lista de permissões; a dica integrada de design de frontend de primeira parte não é afetada. Sugestões vêm da declaração `relevance` de cada plugin em sua entrada de marketplace. Um nome só tem efeito quando o marketplace está registrado na máquina e sua fonte registrada também é declarada em configurações gerenciadas, seja como a entrada `extraKnownMarketplaces` para esse nome ou como uma entrada de `strictKnownMarketplaces`. Um marketplace registrado de uma fonte diferente sob um nome na lista de permissões é ignorado. O marketplace oficial é isento do requisito de fonte: permitir seu nome sozinho é suficiente, já que esse nome só pode se registrar da fonte Anthropic oficial. | `["acme-corp-plugins"]` |

248| `pluginTrustMessage` | (Apenas configurações gerenciadas) Mensagem personalizada anexada ao aviso de confiança de plugin mostrado antes da instalação. Use isto para adicionar contexto específico da organização, por exemplo para confirmar que plugins do seu marketplace interno são verificados. | `"All plugins from our marketplace are approved by IT"` |286| `pluginTrustMessage` | (Apenas configurações gerenciadas) Mensagem personalizada anexada ao aviso de confiança de plugin mostrado antes da instalação. Use isto para adicionar contexto específico da organização, por exemplo para confirmar que plugins do seu marketplace interno são verificados. | `"All plugins from our marketplace are approved by IT"` |

249| `policyHelper` | {/* min-version: 2.1.136 */}Executável implantado por administrador que calcula configurações gerenciadas dinamicamente na inicialização. Apenas honrado de MDM ou um arquivo `managed-settings.json` do sistema. Veja [Calcular configurações gerenciadas com um auxiliar de política](#compute-managed-settings-with-a-policy-helper). Requer Claude Code v2.1.136 ou posterior | `{"path": "/usr/local/bin/claude-policy"}` |287| `policyHelper` | {/* min-version: 2.1.136 */}Executável implantado por administrador que calcula configurações gerenciadas dinamicamente na inicialização. Apenas honrado de MDM ou um arquivo `managed-settings.json` do sistema. Veja [Calcular configurações gerenciadas com um auxiliar de política](#compute-managed-settings-with-a-policy-helper). Requer Claude Code v2.1.136 ou posterior | `{"path": "/usr/local/bin/claude-policy"}` |

250| `preferredNotifChannel` | Método para notificações de conclusão de tarefa e prompt de permissão: `"auto"`, `"terminal_bell"`, `"iterm2"`, `"iterm2_with_bell"`, `"kitty"`, `"ghostty"`, ou `"notifications_disabled"`. Padrão: `"auto"`, que envia uma notificação de desktop em iTerm2, Ghostty, e Kitty e não faz nada em outros terminais. Defina `"terminal_bell"` para tocar o caractere de sino em qualquer terminal. Aparece em `/config` como **Notifications**. Veja [Obter um sino de terminal ou notificação](/pt/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |288| `preferredNotifChannel` | Método para notificações de conclusão de tarefa e prompt de permissão: `"auto"`, `"terminal_bell"`, `"iterm2"`, `"iterm2_with_bell"`, `"kitty"`, `"ghostty"`, ou `"notifications_disabled"`. Padrão: `"auto"`, que envia uma notificação de desktop em iTerm2, Ghostty, e Kitty e não faz nada em outros terminais. Defina `"terminal_bell"` para tocar o caractere de sino em qualquer terminal. Aparece em `/config` como **Notifications**. Veja [Obter um sino de terminal ou notificação](/pt/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |

251| `prefersReducedMotion` | Reduzir ou desabilitar animações de UI (spinners, shimmer, efeitos de flash) para acessibilidade | `true` |289| `prefersReducedMotion` | Reduzir ou desabilitar animações de UI (spinners, shimmer, efeitos de flash) para acessibilidade | `true` |

252| `prUrlTemplate` | Modelo de URL para o badge de PR mostrado no rodapé e em resumos de resultado de ferramenta. Substitui `{host}`, `{owner}`, `{repo}`, `{number}`, e `{url}` da URL de PR relatada por `gh`. Use para apontar links de PR para uma ferramenta de revisão de código interna em vez de `github.com`. Não afeta autolinks `#123` na prosa do Claude | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |290| `prUrlTemplate` | Modelo de URL para o badge de PR mostrado no rodapé e em resumos de resultado de ferramenta. Substitui `{host}`, `{owner}`, `{repo}`, `{number}`, e `{url}` da URL de PR relatada por `gh`. Use para apontar links de PR para uma ferramenta de revisão de código interna em vez de `github.com`. Não afeta autolinks `#123` na prosa do Claude | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |

291| `requiredMaximumVersion` | Apenas configurações gerenciadas. Versão máxima do Claude Code permitida para iniciar. Se a versão em execução for mais nova, o Claude Code sai na inicialização e instrui o usuário a instalar uma versão aprovada através do método aprovado da organização; `claude install <version>` também pode funcionar. Auto-atualizações em background e `claude update` pulam versões acima do teto, então uma instalação dentro do intervalo permanece dentro do intervalo. `claude update`, `claude install`, e `claude doctor` continuam funcionando acima do teto para que os usuários possam se recuperar. Versões que antecedem esta configuração a ignoram | `"2.1.150"` |

292| `requiredMinimumVersion` | Apenas configurações gerenciadas. Versão mínima do Claude Code necessária para iniciar. Se a versão em execução for mais antiga, o Claude Code sai na inicialização e instrui o usuário a atualizar através do método aprovado da organização. `claude update`, `claude install`, e `claude doctor` continuam funcionando abaixo do piso para que os usuários possam se recuperar. Difere de `minimumVersion`, que impede downgrades mas nunca bloqueia a inicialização. Versões que antecedem esta configuração a ignoram | `"2.1.150"` |

253| `respectGitignore` | Controlar se o seletor de arquivo `@` respeita padrões `.gitignore`. Quando `true` (padrão), arquivos correspondentes a padrões `.gitignore` são excluídos das sugestões | `false` |293| `respectGitignore` | Controlar se o seletor de arquivo `@` respeita padrões `.gitignore`. Quando `true` (padrão), arquivos correspondentes a padrões `.gitignore` são excluídos das sugestões | `false` |

254| `showClearContextOnPlanAccept` | Mostrar a opção "limpar contexto" na tela de aceitação do plano. Padrão: `false`. Defina como `true` para restaurar a opção | `true` |294| `showClearContextOnPlanAccept` | Mostrar a opção "limpar contexto" na tela de aceitação do plano. Padrão: `false`. Defina como `true` para restaurar a opção | `true` |

255| `showThinkingSummaries` | Mostrar resumos de [pensamento estendido](/pt/model-config#extended-thinking) em sessões interativas. Quando indefinido ou `false` (padrão em modo interativo), blocos de pensamento são redatados pela API e mostrados como um stub recolhido. A redação apenas muda o que você vê, não o que o modelo gera: para reduzir gastos de pensamento, [reduza o orçamento ou desabilite o pensamento](/pt/model-config#extended-thinking) em vez disso. Esta configuração não tem efeito em modo não interativo (`-p`), no Agent SDK, ou em extensões IDE como VS Code | `true` |295| `showThinkingSummaries` | Mostrar resumos de [pensamento estendido](/pt/model-config#extended-thinking) em sessões interativas. Quando indefinido ou `false` (padrão em modo interativo), blocos de pensamento são redatados pela API e mostrados como um stub recolhido. A redação apenas muda o que você vê, não o que o modelo gera: para reduzir gastos de pensamento, [reduza o orçamento ou desabilite o pensamento](/pt/model-config#extended-thinking) em vez disso. Esta configuração não tem efeito em modo não interativo (`-p`), no Agent SDK, ou em extensões IDE como VS Code | `true` |


265| `strictKnownMarketplaces` | (Apenas configurações gerenciadas) Lista de permissões de marketplaces de plugin. Indefinido = sem restrições, array vazio = bloqueio. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |305| `strictKnownMarketplaces` | (Apenas configurações gerenciadas) Lista de permissões de marketplaces de plugin. Indefinido = sem restrições, array vazio = bloqueio. Aplicado em adição de marketplace e em instalação, atualização, atualização e auto-atualização de plugin, então um marketplace adicionado antes da política ser definida não pode ser usado para buscar plugins. Veja [Restrições de marketplace gerenciado](/pt/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

266| `strictPluginOnlyCustomization` | (Apenas configurações gerenciadas) Bloquear skills, agents, hooks, e MCP servers de fontes de usuário e projeto, para que possam vir apenas de plugins ou configurações gerenciadas. `true` bloqueia todas as quatro superfícies; um array bloqueia apenas as nomeadas. Veja [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |306| `strictPluginOnlyCustomization` | (Apenas configurações gerenciadas) Bloquear skills, agents, hooks, e MCP servers de fontes de usuário e projeto, para que possam vir apenas de plugins ou configurações gerenciadas. `true` bloqueia todas as quatro superfícies; um array bloqueia apenas as nomeadas. Veja [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) | `["skills", "hooks"]` |

267| `syntaxHighlightingDisabled` | Desabilitar destaque de sintaxe em diffs, blocos de código e visualizações de arquivo | `true` |307| `syntaxHighlightingDisabled` | Desabilitar destaque de sintaxe em diffs, blocos de código e visualizações de arquivo | `true` |

268| `teammateMode` | Como [colegas de equipe de agente](/pt/agent-teams) são exibidos: `auto` (escolhe painéis divididos em tmux ou iTerm2, em processo caso contrário), `in-process`, ou `tmux`. `--teammate-mode` substitui isto para uma sessão. Veja [escolher um modo de exibição](/pt/agent-teams#choose-a-display-mode) | `"in-process"` |308| `teammateMode` | Como [colegas de equipe de agente](/pt/agent-teams) são exibidos: `auto` (escolhe painéis divididos em tmux ou iTerm2, em processo caso contrário), `in-process`, ou `tmux` (painéis divididos usando tmux ou iTerm2, detectado do seu terminal). `--teammate-mode` substitui isto para uma sessão. Veja [escolher um modo de exibição](/pt/agent-teams#choose-a-display-mode) | `"in-process"` |

269| `terminalProgressBarEnabled` | Mostrar a barra de progresso do terminal em terminais suportados: ConEmu, Ghostty 1.2.0+, e iTerm2 3.6.6+. Padrão: `true`. Aparece em `/config` como **Terminal progress bar** | `false` |309| `terminalProgressBarEnabled` | Mostrar a barra de progresso do terminal em terminais suportados: ConEmu, Ghostty 1.2.0+, e iTerm2 3.6.6+. Padrão: `true`. Aparece em `/config` como **Terminal progress bar** | `false` |

310| `theme` | {/* min-version: 2.1.119 */}Tema de cor para a interface: `"auto"`, `"dark"`, `"light"`, `"dark-daltonized"`, `"light-daltonized"`, `"dark-ansi"`, `"light-ansi"`, ou uma referência de tema personalizado como `"custom:<slug>"` ou `"custom:<plugin-name>:<slug>"`. Padrão: `"dark"`. Veja [Criar um tema personalizado](/pt/terminal-config#create-a-custom-theme). Aparece em `/config` como **Theme** | `"dark"` |

270| `tui` | Renderizador de UI de terminal. Use `"fullscreen"` para o renderizador [alt-screen](/pt/fullscreen) sem cintilação com scrollback virtualizado. Use `"default"` para o renderizador clássico de tela principal. Defina via `/tui`. Você também pode definir a variável de ambiente [`CLAUDE_CODE_NO_FLICKER`](/pt/env-vars) | `"fullscreen"` |311| `tui` | Renderizador de UI de terminal. Use `"fullscreen"` para o renderizador [alt-screen](/pt/fullscreen) sem cintilação com scrollback virtualizado. Use `"default"` para o renderizador clássico de tela principal. Defina via `/tui`. Você também pode definir a variável de ambiente [`CLAUDE_CODE_NO_FLICKER`](/pt/env-vars) | `"fullscreen"` |

271| `ultracode` | Ativar [ultracode](/pt/workflows#let-claude-decide-with-ultracode) para a sessão. Apenas sessão e não lido de `settings.json`. Defina através de `/effort ultracode`, `--settings`, ou uma solicitação de controle do Agent SDK | `true` |312| `ultracode` | Ativar [ultracode](/pt/workflows#let-claude-decide-with-ultracode) para a sessão. Apenas sessão e não lido de `settings.json`. Defina através de `/effort ultracode`, `--settings`, ou uma solicitação de controle do Agent SDK | `true` |

272| `useAutoModeDuringPlan` | Se Plan Mode usa semântica de modo automático quando o modo automático está disponível. Padrão: `true`. Não lido de configurações de projeto compartilhadas. Aparece em `/config` como "Use auto mode during plan" | `false` |313| `useAutoModeDuringPlan` | Se Plan Mode usa semântica de modo automático quando o modo automático está disponível. Padrão: `true`. Não lido de configurações de projeto compartilhadas. Aparece em `/config` como "Use auto mode during plan" | `false` |

273| `viewMode` | Modo de visualização de transcrição padrão na inicialização: `"default"`, `"verbose"`, ou `"focus"`. Substitui a seleção pegajosa `/focus` quando definido. O flag `--verbose` substitui isto para uma sessão | `"verbose"` |314| `verbose` | {/* min-version: 2.1.119 */}Mostrar saída completa de ferramenta em vez de resumos truncados. Padrão: `false`. Aparece em `/config` como **Verbose output**. A flag `--verbose` substitui isto para uma sessão | `true` |

315| `viewMode` | Modo de visualização de transcrição padrão na inicialização: `"default"`, `"verbose"`, ou `"focus"`. Substitui a seleção pegajosa `/focus` quando definido. A flag `--verbose` substitui isto para uma sessão | `"verbose"` |

274| `voice` | Configurações de [ditado por voz](/pt/voice-dictation): `enabled` ativa ditado, `mode` seleciona `"hold"` ou `"tap"`, e `autoSubmit` envia o prompt ao soltar a tecla em modo hold. Escrito automaticamente quando você executa `/voice`. Requer uma conta Claude.ai | `{ "enabled": true, "mode": "tap" }` |316| `voice` | Configurações de [ditado por voz](/pt/voice-dictation): `enabled` ativa ditado, `mode` seleciona `"hold"` ou `"tap"`, e `autoSubmit` envia o prompt ao soltar a tecla em modo hold. Escrito automaticamente quando você executa `/voice`. Requer uma conta Claude.ai | `{ "enabled": true, "mode": "tap" }` |

275| `voiceEnabled` | Alias legado para `voice.enabled`. Prefira o objeto `voice` | `true` |317| `voiceEnabled` | Alias legado para `voice.enabled`. Prefira o objeto `voice` | `true` |

318| `wheelScrollAccelerationEnabled` | {/* min-version: 2.1.174 */}Em [renderização fullscreen](/pt/fullscreen#mouse-wheel-scrolling), acelerar velocidade de scroll de roda do mouse durante scrolls rápidos. Padrão: `true`. Defina como `false` para uma taxa de scroll constante por entalhe de roda. Requer Claude Code v2.1.174 ou posterior | `false` |

276| `workflowKeywordTriggerEnabled` | {/* min-version: 2.1.157 */}Se a palavra-chave `ultracode` em um prompt dispara um [workflow dinâmico](/pt/workflows#ask-for-a-workflow-in-your-prompt). Defina como `false` para digitar a palavra sem disparar um. A configuração de esforço ultracode, `/workflows`, e comandos de workflow salvos não são afetados. Padrão: `true`. Aparece em `/config` como **Ultracode keyword trigger**. Adicionado em v2.1.157; antes de v2.1.160 a palavra-chave de disparo era `workflow` | `false` |319| `workflowKeywordTriggerEnabled` | {/* min-version: 2.1.157 */}Se a palavra-chave `ultracode` em um prompt dispara um [workflow dinâmico](/pt/workflows#ask-for-a-workflow-in-your-prompt). Defina como `false` para digitar a palavra sem disparar um. A configuração de esforço ultracode, `/workflows`, e comandos de workflow salvos não são afetados. Padrão: `true`. Aparece em `/config` como **Ultracode keyword trigger**. Adicionado em v2.1.157; antes de v2.1.160 a palavra-chave de disparo era `workflow` | `false` |

277| `wslInheritsWindowsSettings` | (Apenas configurações gerenciadas do Windows) Quando `true`, Claude Code no WSL lê configurações gerenciadas da cadeia de política do Windows além de `/etc/claude-code`, com fontes do Windows tendo prioridade. Apenas honrado quando definido na chave de registro HKLM ou `C:\Program Files\ClaudeCode\managed-settings.json`, ambos exigindo admin do Windows para escrever. Para que a política HKCU também se aplique no WSL, a flag deve ser adicionalmente definida no HKCU em si. Não tem efeito no Windows nativo | `true` |320| `wslInheritsWindowsSettings` | (Apenas configurações gerenciadas do Windows) Quando `true`, Claude Code no WSL lê configurações gerenciadas da cadeia de política do Windows além de `/etc/claude-code`, com fontes do Windows tendo prioridade. Apenas honrado quando definido na chave de registro HKLM ou `C:\Program Files\ClaudeCode\managed-settings.json`, ambos exigindo admin do Windows para escrever. Para que a política HKCU também se aplique no WSL, a flag deve ser adicionalmente definida no HKCU em si. Não tem efeito no Windows nativo | `true` |

278 321 


283Estas configurações são armazenadas em `~/.claude.json` em vez de `settings.json`. Adicioná-las a `settings.json` acionará um erro de validação de esquema.326Estas configurações são armazenadas em `~/.claude.json` em vez de `settings.json`. Adicioná-las a `settings.json` acionará um erro de validação de esquema.

284 327 

285<Note>328<Note>

286 Versões antes da v2.1.119 também armazenam `autoScrollEnabled`, `editorMode`, `showTurnDuration`, `teammateMode`, e `terminalProgressBarEnabled` aqui em vez de em `settings.json`.329 Versões antes da v2.1.119 também armazenam um número de chaves de preferência `/config` aqui em vez de em `settings.json`, incluindo `theme`, `verbose`, `editorMode`, `autoCompactEnabled`, e `preferredNotifChannel`.

287</Note>330</Note>

288 331 

289| Chave | Descrição | Exemplo |332| Chave | Descrição | Exemplo |


314 357 

315| Chaves | Descrição | Exemplo |358| Chaves | Descrição | Exemplo |

316| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |359| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |

317| `allow` | Array de regras de permissão para permitir uso de ferramenta. Veja [Sintaxe de regra de permissão](#permission-rule-syntax) abaixo para detalhes de correspondência de padrão | `[ "Bash(git diff *)" ]` |360| `allow` | Array de regras de permissão para permitir uso de ferramenta. Nomes de ferramenta globs são suportados apenas na posição de ferramenta após um prefixo literal `mcp__<server>__`, como `mcp__github__get_*`; o segmento de servidor deve estar livre de glob. Veja [Sintaxe de regra de permissão](#permission-rule-syntax) abaixo para detalhes de correspondência de padrão | `[ "Bash(git diff *)" ]` |

318| `ask` | Array de regras de permissão para pedir confirmação ao usar ferramenta. Veja [Sintaxe de regra de permissão](#permission-rule-syntax) abaixo | `[ "Bash(git push *)" ]` |361| `ask` | Array de regras de permissão para pedir confirmação ao usar ferramenta. Veja [Sintaxe de regra de permissão](#permission-rule-syntax) abaixo | `[ "Bash(git push *)" ]` |

319| `deny` | Array de regras de permissão para negar uso de ferramenta. Use isto para excluir arquivos sensíveis do acesso do Claude Code. Veja [Sintaxe de regra de permissão](#permission-rule-syntax) e [Limitações de permissão Bash](/pt/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |362| `deny` | Array de regras de permissão para negar uso de ferramenta. Use isto para excluir arquivos sensíveis do acesso do Claude Code. Nomes de ferramenta aceitam padrões glob: `"*"` nega cada ferramenta e `"mcp__*"` nega todas as ferramentas MCP. Veja [Sintaxe de regra de permissão](#permission-rule-syntax) e [Limitações de permissão Bash](/pt/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

320| `additionalDirectories` | [Diretórios de trabalho](/pt/permissions#working-directories) adicionais para acesso a arquivos. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) destes diretórios | `[ "../docs/" ]` |363| `additionalDirectories` | [Diretórios de trabalho](/pt/permissions#working-directories) adicionais para acesso a arquivos. A maioria da configuração `.claude/` [não é descoberta](/pt/permissions#additional-directories-grant-file-access-not-configuration) destes diretórios | `[ "../docs/" ]` |

321| `defaultMode` | [Modo de permissão](/pt/permission-modes) padrão ao abrir Claude Code. Valores válidos: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`. {/* min-version: 2.1.142 */}A partir do Claude Code v2.1.142, `auto` é ignorado quando definido em configurações de projeto ou local (`.claude/settings.json`, `.claude/settings.local.json`) para que um repositório não possa se conceder modo automático. Defina-o em `~/.claude/settings.json` em vez disso. A flag CLI `--permission-mode` substitui esta configuração para uma única sessão | `"acceptEdits"` |364| `defaultMode` | [Modo de permissão](/pt/permission-modes) padrão ao abrir Claude Code. Valores válidos: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`. {/* min-version: 2.1.142 */}A partir do Claude Code v2.1.142, `auto` é ignorado quando definido em configurações de projeto ou local (`.claude/settings.json`, `.claude/settings.local.json`) para que um repositório não possa se conceder modo automático. Defina-o em `~/.claude/settings.json` em vez disso. A flag CLI `--permission-mode` substitui esta configuração para uma única sessão | `"acceptEdits"` |

322| `disableBypassPermissionsMode` | Defina como `"disable"` para impedir que o modo `bypassPermissions` seja ativado. Isto desabilita a flag de linha de comando `--dangerously-skip-permissions`. Tipicamente colocado em [configurações gerenciadas](/pt/permissions#managed-settings) para aplicar política organizacional, mas funciona de qualquer escopo | `"disable"` |365| `disableBypassPermissionsMode` | Defina como `"disable"` para impedir que o modo `bypassPermissions` seja ativado. Isto desabilita a flag de linha de comando `--dangerously-skip-permissions`. Tipicamente colocado em [configurações gerenciadas](/pt/permissions#managed-settings) para aplicar política organizacional, mas funciona de qualquer escopo | `"disable"` |


326 Sintaxe de regra de permissão369 Sintaxe de regra de permissão

327</h3>370</h3>

328 371 

329Regras de permissão seguem o formato `Tool` ou `Tool(specifier)`. Regras são avaliadas em ordem: regras de negação primeiro, depois ask, depois allow. A primeira regra correspondente vence.372Regras de permissão seguem o formato `Tool` ou `Tool(specifier)`. Regras são avaliadas em ordem: regras de negação primeiro, depois ask, depois allow. A primeira regra correspondente determina o resultado independentemente da especificidade da regra. Veja a [ordem de avaliação de regra de permissão](/pt/permissions#manage-permissions) para detalhes.

330 373 

331Exemplos rápidos:374Exemplos rápidos:

332 375 


431**Atribuição de commit padrão:**474**Atribuição de commit padrão:**

432 475 

433```text theme={null}476```text theme={null}

434🤖 Generated with [Claude Code](https://claude.com/claude-code)477Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

435 

436 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

437```478```

438 479 

480O nome do modelo no trailer reflete o modelo ativo para a sessão.

481 

439**Atribuição de pull request padrão:**482**Atribuição de pull request padrão:**

440 483 

441```text theme={null}484```text theme={null}


491```bash theme={null}534```bash theme={null}

492#!/bin/bash535#!/bin/bash

493query=$(cat | jq -r '.query')536query=$(cat | jq -r '.query')

537# Substitua your-repo-file-index pelo seu próprio comando de busca de arquivo

494your-repo-file-index --query "$query" | head -20538your-repo-file-index --query "$query" | head -20

495```539```

496 540 

541<h3 id="footer-link-badges">

542 Badges de link de rodapé

543</h3>

544 

545A configuração `footerLinksRegexes` renderiza badges clicáveis extras no rodapé abaixo da caixa de entrada. Use-a para transformar IDs impressos por CLIs de projeto, como ferramentas de revisão e rastreadores de problemas, em links de sessão.

546 

547Cada regex `pattern` de entrada é correspondida contra a saída de turno: resultados de ferramenta, incluindo conteúdo de arquivo e páginas buscadas, e respostas do próprio Claude. Placeholders `{name}` em `url` e `label` são preenchidos de grupos de captura nomeados no padrão.

548 

549O exemplo a seguir renderiza um badge sempre que uma chave de problema como `PROJ-1234` aparece na saída de turno. O grupo nomeado `(?<key>...)` captura a chave, e `{key}` a substitui na URL e label:

550 

551```json ~/.claude/settings.json theme={null}

552{

553 "footerLinksRegexes": [

554 {

555 "type": "regex",

556 "pattern": "\\b(?<key>PROJ-\\d+)\\b",

557 "url": "https://issues.example.com/browse/{key}",

558 "label": "{key}"

559 }

560 ]

561}

562```

563 

564Com isto configurado, quando `PROJ-1234` aparece em um resultado de ferramenta ou na resposta do Claude, um chip `PROJ-1234` aparece no rodapé ligando para `https://issues.example.com/browse/PROJ-1234`.

565 

566As seguintes restrições se aplicam a cada entrada:

567 

568| Restrição | Comportamento |

569| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

570| Origem de URL | Valores capturados são codificados em URL e a URL construída deve compartilhar a origem literal do modelo. Uma captura pode preencher um segmento de caminho ou valor de query mas não pode mudar para onde o link aponta |

571| Comprimento de URL | URLs construídas mais longas que 2048 caracteres são descartadas |

572| Esquema de URL | Deve ser `https`, `http`, ou um esquema de deep-link reconhecido de editor ou workspace: `vscode`, `vscode-insiders`, `cursor`, `windsurf`, `zed`, `jetbrains`, `idea`, `slack`, `linear`, `notion`, `figma` |

573| Label | Padrão para o texto correspondido e é truncado para 28 colunas de exibição |

574| Contagem de badge | No máximo 5 badges renderizam. O mais antigo é deslocado por correspondências mais novas e `/clear` os remove |

575| Escopo de configuração | Lido apenas de configurações de usuário, flag `--settings`, e configurações gerenciadas. Ignorado em `.claude/settings.json` de projeto e `.claude/settings.local.json` local |

576 

577Quando um turno é concluído, Claude Code corresponde cada regex `pattern` de entrada contra a saída de turno na thread principal, então uma regex lenta bloqueia a UI até terminar. Quantificadores aninhados como `(a+)+$` podem levar exponencialmente tempo contra certas entradas e congelar a sessão, então mantenha cada `pattern` linear e evite aninhar `+` ou `*`.

578 

579Badges de rodapé renderizam ao lado de uma [linha de status personalizada](/pt/statusline) quando uma está configurada; nenhuma substitui a outra. Use uma linha de status para uma linha acionada por script que calcula seu próprio conteúdo a partir de dados de sessão, e badges de rodapé para transformar IDs da conversa em links sem um script.

580 

497<h3 id="hook-configuration">581<h3 id="hook-configuration">

498 Configuração de hooks582 Configuração de hooks

499</h3>583</h3>


564 * Políticas implantadas por TI através de entrega de servidor, perfis de configuração MDM, políticas de registro, ou arquivos de configurações gerenciadas648 * Políticas implantadas por TI através de entrega de servidor, perfis de configuração MDM, políticas de registro, ou arquivos de configurações gerenciadas

565 * Não podem ser substituídas por qualquer outro nível, incluindo argumentos de linha de comando649 * Não podem ser substituídas por qualquer outro nível, incluindo argumentos de linha de comando

566 * Dentro do nível gerenciado, a precedência é: gerenciadas pelo servidor > políticas de nível MDM/SO > baseadas em arquivo (`managed-settings.d/*.json` + `managed-settings.json`) > registro HKCU (apenas Windows). Apenas uma fonte gerenciada é usada; fontes não se mesclam entre camadas. Dentro da camada baseada em arquivo, arquivos drop-in e o arquivo base são mesclados juntos.650 * Dentro do nível gerenciado, a precedência é: gerenciadas pelo servidor > políticas de nível MDM/SO > baseadas em arquivo (`managed-settings.d/*.json` + `managed-settings.json`) > registro HKCU (apenas Windows). Apenas uma fonte gerenciada é usada; fontes não se mesclam entre camadas. Dentro da camada baseada em arquivo, arquivos drop-in e o arquivo base são mesclados juntos.

651 * Hosts de incorporação como Claude Desktop podem fornecer política via opção SDK `managedSettings`. Por padrão isto é ignorado quando qualquer nível gerenciado está presente. Administradores podem optar por definir [`parentSettingsBehavior`](#available-settings) como `"merge"`. Os valores do incorporador são filtrados para que possam apertar a política gerenciada mas não afrouxá-la.

567 652 

5682. **Argumentos de linha de comando**6532. **Argumentos de linha de comando**

569 * Substituições temporárias para uma sessão específica. JSON passado via `--settings <file-or-json>` se mescla com configurações baseadas em arquivo usando as mesmas regras que as outras camadas: uma chave definida aqui substitui a mesma chave em configurações local, projeto, ou usuário, e omitir uma chave deixa o valor da camada inferior no lugar654 * Substituições temporárias para uma sessão específica. JSON passado via `--settings <file-or-json>` se mescla com configurações baseadas em arquivo usando as mesmas regras que as outras camadas: uma chave definida aqui substitui a mesma chave em configurações local, projeto, ou usuário, e omitir uma chave deixa o valor da camada inferior no lugar


582Por exemplo, se suas configurações de usuário definem `permissions.defaultMode` como `acceptEdits` e as configurações compartilhadas de um projeto definem como `default`, o valor do projeto se aplica. O exemplo abaixo cobre como configurações com valor de array como regras de permissão se combinam em vez disso.667Por exemplo, se suas configurações de usuário definem `permissions.defaultMode` como `acceptEdits` e as configurações compartilhadas de um projeto definem como `default`, o valor do projeto se aplica. O exemplo abaixo cobre como configurações com valor de array como regras de permissão se combinam em vez disso.

583 668 

584<Note>669<Note>

585 **Configurações de array se mesclam entre escopos.** Quando a mesma configuração com valor de array (como `sandbox.filesystem.allowWrite` ou `permissions.allow`) aparece em múltiplos escopos, os arrays são **concatenados e desduplicados**, não substituídos. Isto significa que escopos de prioridade mais baixa podem adicionar entradas sem substituir aquelas definidas por escopos de prioridade mais alta, e vice-versa. Por exemplo, se configurações gerenciadas definem `allowWrite` como `["/opt/company-tools"]` e um usuário adiciona `["~/.kube"]`, ambos os caminhos são incluídos na configuração final.670 **Configurações de array se mesclam entre escopos.** Quando a mesma configuração com valor de array (como `sandbox.filesystem.allowWrite` ou `permissions.allow`) aparece em múltiplos escopos, os arrays são **concatenados e desduplicados**, não substituídos. Isto significa que escopos de prioridade mais baixa podem adicionar entradas sem substituir aquelas definidas por escopos de prioridade mais alta, e vice-versa. Por exemplo, se configurações gerenciadas definem `allowWrite` como `["/opt/company-tools"]` e um usuário adiciona `["~/.kube"]`, ambos os caminhos são incluídos na configuração final. Duas exceções: [`fallbackModel`](#available-settings), uma cadeia ordenada onde a posição carrega significado então o arquivo de precedência mais alta que a define fornece o valor inteiro, e {/* min-version: 2.1.175 */}a partir de v2.1.175, [`availableModels`](#available-settings), onde um valor gerenciado ou de política substitui entradas de precedência mais baixa completamente. Veja [Comportamento de mesclagem](/pt/model-config#merge-behavior).

586</Note>671</Note>

587 672 

588<h3 id="verify-active-settings">673<h3 id="verify-active-settings">

589 Verificar configurações ativas674 Verificar configurações ativas

590</h3>675</h3>

591 676 

592Execute `/status` dentro do Claude Code para ver quais fontes de configuração estão ativas. A aba Status inclui uma linha `Setting sources` que lista cada camada que Claude Code carregou para a sessão atual, como `User settings` ou `Project local settings`. Quando [configurações gerenciadas](/pt/admin-setup#decide-how-settings-reach-devices) estão em efeito, a entrada mostra o canal de entrega entre parênteses, por exemplo `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)`, ou `(file)`. Uma camada aparece na lista apenas quando essa fonte é carregada com pelo menos uma chave, então uma lista vazia significa que nenhuma fonte de configuração foi encontrada.677Execute `/status` dentro do Claude Code para ver quais fontes de configuração estão ativas. Dentro do menu, a aba **Status** inclui uma linha `Setting sources` que lista cada camada que Claude Code carregou para a sessão atual, como `User settings` ou `Project local settings`. Quando [configurações gerenciadas](/pt/admin-setup#decide-how-settings-reach-devices) estão em efeito, a entrada mostra o canal de entrega entre parênteses, por exemplo `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)`, ou `(file)`. Uma camada aparece na lista apenas quando essa fonte é carregada com pelo menos uma chave, então uma lista vazia significa que nenhuma fonte de configuração foi encontrada.

678 

679A linha `Setting sources` confirma quais fontes estão sendo lidas. Ela não mostra qual camada forneceu cada chave individual. A aba **Config** no mesmo diálogo é um editor para um conjunto fixo de toggles como tema e saída verbose, não uma visualização do conteúdo do seu `settings.json`.

593 680 

594A linha `Setting sources` confirma quais fontes estão sendo lidas. Ela não mostra qual camada forneceu cada chave individual. A aba Config no mesmo diálogo é um editor para um conjunto fixo de toggles como tema e saída verbose, não uma visualização do conteúdo do seu `settings.json`. Se um arquivo de configuração contém erros, como JSON inválido ou um valor que falha na validação, `/status` relata o problema para que você possa corrigi-lo.681Se um arquivo de configuração contém erros, como JSON inválido ou um valor que falha na validação, Claude Code mostra um aviso de problemas de configuração na inicialização e `/status` lista os arquivos afetados. Execute `/doctor` para ver os detalhes de cada erro.

595 682 

596<h3 id="key-points-about-the-configuration-system">683<h3 id="key-points-about-the-configuration-system">

597 Pontos-chave sobre o sistema de configuração684 Pontos-chave sobre o sistema de configuração


602* **Skills**: Prompts personalizados que podem ser invocados com `/skill-name` ou carregados pelo Claude automaticamente689* **Skills**: Prompts personalizados que podem ser invocados com `/skill-name` ou carregados pelo Claude automaticamente

603* **MCP servers**: Estender Claude Code com ferramentas e integrações adicionais690* **MCP servers**: Estender Claude Code com ferramentas e integrações adicionais

604* **Precedência**: Configurações de nível mais alto (Managed) substituem as de nível mais baixo (User/Project)691* **Precedência**: Configurações de nível mais alto (Managed) substituem as de nível mais baixo (User/Project)

605* **Herança**: Configurações são mescladas entre escopos; valores escalares de escopos de prioridade mais alta substituem, e arrays se concatenam692* **Herança**: Configurações são mescladas entre escopos; valores escalares de escopos de prioridade mais alta substituem, e arrays se concatenam. Exceções: `fallbackModel`, onde o escopo de precedência mais alta fornece a cadeia inteira, e `availableModels`, onde um valor gerenciado ou de política substitui entradas de precedência mais baixa

606 693 

607<h3 id="system-prompt">694<h3 id="system-prompt">

608 Prompt do sistema695 Prompt do sistema


683 770 

684* **Configurações de usuário** (`~/.claude/settings.json`): Preferências pessoais de plugin771* **Configurações de usuário** (`~/.claude/settings.json`): Preferências pessoais de plugin

685* **Configurações de projeto** (`.claude/settings.json`): Plugins específicos do projeto compartilhados com equipe772* **Configurações de projeto** (`.claude/settings.json`): Plugins específicos do projeto compartilhados com equipe

686* **Configurações locais** (`.claude/settings.local.json`): Substituições por máquina (não confirmadas)773* **Configurações locais** (`.claude/settings.local.json`): Substituições por máquina, gitignored quando Claude Code as cria

687* **Configurações gerenciadas** (`managed-settings.json`): Substituições de política em toda a organização que bloqueiam instalação em todos os escopos e ocultam o plugin do marketplace774* **Configurações gerenciadas** (`managed-settings.json`): Substituições de política em toda a organização que bloqueiam instalação em todos os escopos e ocultam o plugin do marketplace

688 775 

689<Note>776<Note>

setup.md +26 −4

Details

258 258 

259Em [configurações gerenciadas](/pt/permissions#managed-settings), isso impõe um mínimo em toda a organização que as configurações de usuário e projeto não podem substituir.259Em [configurações gerenciadas](/pt/permissions#managed-settings), isso impõe um mínimo em toda a organização que as configurações de usuário e projeto não podem substituir.

260 260 

261O pino `minimumVersion` apenas restringe atualizações. Para fazer Claude Code recusar iniciar fora de um intervalo de versão, use as configurações gerenciadas `requiredMinimumVersion` e `requiredMaximumVersion` em vez disso. As atualizações também respeitam o teto `requiredMaximumVersion`. Consulte [configurações disponíveis](/pt/settings#available-settings).

262 

261<h3 id="disable-auto-updates">263<h3 id="disable-auto-updates">

262 Desabilitar atualizações automáticas264 Desabilitar atualizações automáticas

263</h3>265</h3>


366 Instalar com gerenciadores de pacotes Linux368 Instalar com gerenciadores de pacotes Linux

367</h3>369</h3>

368 370 

369Claude Code publica repositórios apt, dnf e apk assinados. Substitua `stable` por `latest` para o canal contínuo. As instalações do gerenciador de pacotes não são atualizadas automaticamente através do Claude Code; as atualizações chegam através do seu fluxo de trabalho de atualização do sistema normal.371Claude Code publica repositórios apt, dnf e apk assinados. Cada repositório oferece dois canais: `stable` oferece uma versão que é tipicamente cerca de uma semana antiga, pulando lançamentos com regressões maiores, e `latest` oferece cada lançamento assim que é lançado. Os comandos abaixo configuram o canal `stable`, que se adequa à maioria dos usuários; cada aba também mostra a URL do repositório `latest`. As instalações do gerenciador de pacotes não são atualizadas automaticamente através do Claude Code; as atualizações chegam através do seu fluxo de trabalho de atualização do sistema normal.

370 372 

371Todos os repositórios são assinados com a [chave de assinatura de lançamento do Claude Code](#binary-integrity-and-code-signing). Antes de confiar na chave, verifique-a conforme descrito em cada aba.373Todos os repositórios são assinados com a [chave de assinatura de lançamento do Claude Code](#binary-integrity-and-code-signing). Antes de confiar na chave, verifique-a conforme descrito em cada aba.

372 374 

373<Tabs>375<Tabs>

374 <Tab title="apt">376 <Tab title="apt">

375 Para Debian e Ubuntu. Para usar o canal contínuo, altere ambas as ocorrências de `stable` na linha `deb`: o caminho da URL e o nome do suite.377 Para Debian e Ubuntu. Os comandos a seguir configuram o canal `stable`:

376 378 

377 ```bash theme={null}379 ```bash theme={null}

378 sudo install -d -m 0755 /etc/apt/keyrings380 sudo install -d -m 0755 /etc/apt/keyrings


384 sudo apt install claude-code386 sudo apt install claude-code

385 ```387 ```

386 388 

389 Para usar o canal `latest` em vez disso, tanto o caminho da URL quanto o nome do suite mudam. Use esta linha `deb`:

390 

391 ```bash theme={null}

392 echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/latest latest main" \

393 | sudo tee /etc/apt/sources.list.d/claude-code.list

394 ```

395 

387 Verifique a impressão digital da chave GPG antes de confiar nela: `gpg --show-keys /etc/apt/keyrings/claude-code.asc` deve relatar `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE`.396 Verifique a impressão digital da chave GPG antes de confiar nela: `gpg --show-keys /etc/apt/keyrings/claude-code.asc` deve relatar `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE`.

388 397 

389 Para atualizar mais tarde, execute `sudo apt update && sudo apt upgrade claude-code`.398 Para atualizar mais tarde, execute `sudo apt update && sudo apt upgrade claude-code`.

390 </Tab>399 </Tab>

391 400 

392 <Tab title="dnf">401 <Tab title="dnf">

393 Para Fedora e RHEL:402 Para Fedora e RHEL. Os comandos a seguir configuram o canal `stable`:

394 403 

395 ```bash theme={null}404 ```bash theme={null}

396 sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'405 sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'


404 sudo dnf install claude-code413 sudo dnf install claude-code

405 ```414 ```

406 415 

416 Para usar o canal `latest` em vez disso, defina `baseurl` para o repositório `latest`:

417 

418 ```ini theme={null}

419 baseurl=https://downloads.claude.ai/claude-code/rpm/latest

420 ```

421 

407 dnf baixa a chave na primeira instalação e solicita que você confirme a impressão digital. Verifique se ela corresponde a `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE` antes de aceitar.422 dnf baixa a chave na primeira instalação e solicita que você confirme a impressão digital. Verifique se ela corresponde a `31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE` antes de aceitar.

408 423 

409 Para atualizar mais tarde, execute `sudo dnf upgrade claude-code`.424 Para atualizar mais tarde, execute `sudo dnf upgrade claude-code`.

410 </Tab>425 </Tab>

411 426 

412 <Tab title="apk">427 <Tab title="apk">

413 Para Alpine Linux:428 Para Alpine Linux. Os comandos a seguir configuram o canal `stable`:

414 429 

415 ```sh theme={null}430 ```sh theme={null}

416 wget -O /etc/apk/keys/claude-code.rsa.pub \431 wget -O /etc/apk/keys/claude-code.rsa.pub \


419 apk add claude-code434 apk add claude-code

420 ```435 ```

421 436 

437 Para mudar para o canal `latest`, remova a linha do repositório `stable` e adicione o repositório `latest`:

438 

439 ```sh theme={null}

440 sed -i '\|downloads.claude.ai/claude-code/apk/stable|d' /etc/apk/repositories

441 echo "https://downloads.claude.ai/claude-code/apk/latest" >> /etc/apk/repositories

442 ```

443 

422 Verifique a chave baixada com `sha256sum /etc/apk/keys/claude-code.rsa.pub`, que deve relatar `395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6`.444 Verifique a chave baixada com `sha256sum /etc/apk/keys/claude-code.rsa.pub`, que deve relatar `395759c1f7449ef4cdef305a42e820f3c766d6090d142634ebdb049f113168b6`.

423 445 

424 Para atualizar mais tarde, execute `apk update && apk upgrade claude-code`.446 Para atualizar mais tarde, execute `apk update && apk upgrade claude-code`.

skills.md +20 −7

Details

22 Skills agrupadas22 Skills agrupadas

23</h2>23</h2>

24 24 

25Claude Code inclui um conjunto de skills agrupadas que estão disponíveis em cada sessão, incluindo `/code-review`, `/batch`, `/debug`, `/loop`, e `/claude-api`. Diferentemente da maioria dos comandos integrados, que executam lógica fixa diretamente, skills agrupadas são baseadas em prompt: elas dão ao Claude instruções detalhadas e deixam que ele orquestre o trabalho usando suas ferramentas. Você invoca elas da mesma forma que qualquer outra skill, digitando `/` seguido do nome da skill.25Claude Code inclui um conjunto de skills agrupadas que estão disponíveis em cada sessão, a menos que desabilitadas com a configuração [`disableBundledSkills`](/pt/settings#available-settings), incluindo `/code-review`, `/batch`, `/debug`, `/loop`, e `/claude-api`. Diferentemente da maioria dos comandos integrados, que executam lógica fixa diretamente, skills agrupadas são baseadas em prompt: elas dão ao Claude instruções detalhadas e deixam que ele orquestre o trabalho usando suas ferramentas. Você invoca elas da mesma forma que qualquer outra skill, digitando `/` seguido do nome da skill.

26 26 

27Skills agrupadas estão listadas junto com comandos integrados na [referência de comandos](/pt/commands), marcadas como **Skill** na coluna Propósito.27Skills agrupadas estão listadas junto com comandos integrados na [referência de comandos](/pt/commands), marcadas como **Skill** na coluna Propósito.

28 28 


117| Projeto | `.claude/skills/<skill-name>/SKILL.md` | Apenas este projeto |117| Projeto | `.claude/skills/<skill-name>/SKILL.md` | Apenas este projeto |

118| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Onde o plugin está habilitado |118| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Onde o plugin está habilitado |

119 119 

120Quando skills compartilham o mesmo nome em diferentes níveis, enterprise substitui pessoal, e pessoal substitui projeto. Skills de plugin usam um namespace `plugin-name:skill-name`, então não podem conflitar com outros níveis. Se você tem arquivos em `.claude/commands/`, eles funcionam da mesma forma, mas se uma skill e um comando compartilham o mesmo nome, a skill tem precedência.120Quando skills compartilham o mesmo nome em diferentes níveis, enterprise substitui pessoal, e pessoal substitui projeto. Uma skill em qualquer um desses níveis também substitui uma skill agrupada com o mesmo nome. Por exemplo, uma skill `code-review` na `.claude/skills/` do seu projeto substitui a `/code-review` agrupada. Skills de plugin usam um namespace `plugin-name:skill-name`, então não podem conflitar com outros níveis. Se você tem arquivos em `.claude/commands/`, eles funcionam da mesma forma, mas se uma skill e um comando compartilham o mesmo nome, a skill tem precedência.

121 

122Skills também carregam de diretórios `.claude/skills/` aninhados abaixo de seu diretório de trabalho. Quando Claude lê ou edita um arquivo em um subdiretório, skills do `.claude/skills/` desse subdiretório se tornam disponíveis. Isso permite que um pacote de monorepo forneça suas próprias skills que se aplicam ao trabalhar nesse pacote, mesmo que a sessão tenha começado na raiz do repositório.

123 

124Se uma skill aninhada compartilha um nome com outra skill, ambas permanecem disponíveis. Por exemplo, com uma skill `deploy` na raiz do projeto e outra em `apps/web/.claude/skills/`:

125 

126* A aninhada aparece sob um nome qualificado por diretório, `apps/web:deploy`.

127* Sua descrição diz qual diretório ela se aplica.

128* Claude escolhe a variante que corresponde aos arquivos em que está trabalhando.

129 

130Digitar `/deploy` executa a skill da raiz do projeto. Digite o nome qualificado `/apps/web:deploy` para executar a variante aninhada explicitamente.

121 131 

122<Note>132<Note>

123 Adicione um `.claude-plugin/plugin.json` a uma pasta de skill e ela carrega como um [plugin](/pt/plugins-reference#skills-directory-plugins) nomeado `<name>@skills-dir`, para que possa agrupar agents, hooks e servidores MCP. Em um `.claude/skills/` de projeto, isso requer aceitar o diálogo de confiança do workspace primeiro.133 Adicione um `.claude-plugin/plugin.json` a uma pasta de skill e ela carrega como um [plugin](/pt/plugins-reference#skills-directory-plugins) nomeado `<name>@skills-dir`, para que possa agrupar agents, hooks e servidores MCP. Em um `.claude/skills/` de projeto, isso requer aceitar o diálogo de confiança do workspace primeiro.


243| `arguments` | Não | Argumentos posicionais nomeados para [substituição `$name`](#available-string-substitutions) no conteúdo da skill. Aceita uma string separada por espaços ou uma lista YAML. Nomes mapeiam para posições de argumento em ordem. |253| `arguments` | Não | Argumentos posicionais nomeados para [substituição `$name`](#available-string-substitutions) no conteúdo da skill. Aceita uma string separada por espaços ou uma lista YAML. Nomes mapeiam para posições de argumento em ordem. |

244| `disable-model-invocation` | Não | Defina como `true` para evitar que Claude carregue automaticamente esta skill. Use para fluxos de trabalho que você quer disparar manualmente com `/name`. Também evita que a skill seja [pré-carregada em subagents](/pt/sub-agents#preload-skills-into-subagents). Padrão: `false`. |254| `disable-model-invocation` | Não | Defina como `true` para evitar que Claude carregue automaticamente esta skill. Use para fluxos de trabalho que você quer disparar manualmente com `/name`. Também evita que a skill seja [pré-carregada em subagents](/pt/sub-agents#preload-skills-into-subagents). Padrão: `false`. |

245| `user-invocable` | Não | Defina como `false` para ocultar do menu `/`. Use para conhecimento de fundo que usuários não devem invocar diretamente. Padrão: `true`. |255| `user-invocable` | Não | Defina como `false` para ocultar do menu `/`. Use para conhecimento de fundo que usuários não devem invocar diretamente. Padrão: `true`. |

246| `allowed-tools` | Não | Ferramentas que Claude pode usar sem pedir permissão quando esta skill está ativa. Aceita uma string separada por espaços ou uma lista YAML. |256| `allowed-tools` | Não | Ferramentas que Claude pode usar sem pedir permissão quando esta skill está ativa. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. |

247| `disallowed-tools` | Não | Ferramentas removidas do pool disponível de Claude enquanto esta skill está ativa. Use para skills autônomas que nunca devem chamar certas ferramentas, como `AskUserQuestion` para um loop de fundo. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. A restrição é limpa quando você envia sua próxima mensagem. |257| `disallowed-tools` | Não | Ferramentas removidas do pool disponível de Claude enquanto esta skill está ativa. Use para skills autônomas que nunca devem chamar certas ferramentas, como `AskUserQuestion` para um loop de fundo. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. A restrição é limpa quando você envia sua próxima mensagem. |

248| `model` | Não | Modelo a usar quando esta skill está ativa. A sobrescrita se aplica pelo resto da volta atual e não é salva em configurações; o modelo de sessão retoma em seu próximo prompt. Aceita os mesmos valores que [`/model`](/pt/model-config), ou `inherit` para manter o modelo ativo. |258| `model` | Não | Modelo a usar quando esta skill está ativa. A sobrescrita se aplica pelo resto da volta atual e não é salva em configurações; o modelo de sessão retoma em seu próximo prompt. Aceita os mesmos valores que [`/model`](/pt/model-config), ou `inherit` para manter o modelo ativo. |

249| `effort` | Não | [Nível de esforço](/pt/model-config#adjust-effort-level) quando esta skill está ativa. Sobrescreve o nível de esforço da sessão. Padrão: herda da sessão. Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo. |259| `effort` | Não | [Nível de esforço](/pt/model-config#adjust-effort-level) quando esta skill está ativa. Sobrescreve o nível de esforço da sessão. Padrão: herda da sessão. Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo. |


262A tabela abaixo mostra de onde o nome do comando vem para cada layout:272A tabela abaixo mostra de onde o nome do comando vem para cada layout:

263 273 

264| Localização da skill | Fonte do nome do comando | Exemplo |274| Localização da skill | Fonte do nome do comando | Exemplo |

265| :-------------------------------------------------------------- | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ |275| :---------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |

266| Diretório de skill sob `~/.claude/skills/` ou `.claude/skills/` | Nome do diretório | `.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging` |276| Diretório de skill sob `~/.claude/skills/` ou `.claude/skills/` | Nome do diretório | `.claude/skills/deploy-staging/SKILL.md` → `/deploy-staging` |

277| [Diretório `.claude/skills/` aninhado](#where-skills-live), quando o nome entra em conflito com outra skill | Caminho do subdiretório relativo ao diretório de trabalho, depois o nome do diretório de skill | `apps/web/.claude/skills/deploy/SKILL.md` → `/apps/web:deploy` |

267| Arquivo sob `.claude/commands/` | Nome do arquivo sem extensão | `.claude/commands/deploy.md` → `/deploy` |278| Arquivo sob `.claude/commands/` | Nome do arquivo sem extensão | `.claude/commands/deploy.md` → `/deploy` |

268| Subdiretório `skills/` do plugin | Nome do diretório, com namespace pelo plugin | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review` |279| Subdiretório `skills/` do plugin | Nome do diretório, com namespace pelo plugin | `my-plugin/skills/review/SKILL.md` → `/my-plugin:review` |

269| `SKILL.md` raiz do plugin | Frontmatter `name`, com o nome do diretório do plugin como fallback | `my-plugin/SKILL.md` com `name: review` → `/my-plugin:review`. Consulte [Regras de comportamento de caminho](/pt/plugins-reference#path-behavior-rules) |280| `SKILL.md` raiz do plugin | Frontmatter `name`, com o nome do diretório do plugin como fallback | `my-plugin/SKILL.md` com `name: review` → `/my-plugin:review`. Consulte [Regras de comportamento de caminho](/pt/plugins-reference#path-behavior-rules) |


288 299 

289Argumentos indexados usam quoting no estilo shell, então envolva valores de múltiplas palavras em aspas para passá-los como um único argumento. Por exemplo, `/my-skill "hello world" second` faz `$0` expandir para `hello world` e `$1` para `second`. O placeholder `$ARGUMENTS` sempre expande para a string de argumento completa conforme digitada.300Argumentos indexados usam quoting no estilo shell, então envolva valores de múltiplas palavras em aspas para passá-los como um único argumento. Por exemplo, `/my-skill "hello world" second` faz `$0` expandir para `hello world` e `$1` para `second`. O placeholder `$ARGUMENTS` sempre expande para a string de argumento completa conforme digitada.

290 301 

302Para incluir um `$` literal antes de um dígito, `ARGUMENTS`, ou um nome de argumento declarado, como `$1.00` em prosa, escape-o com uma barra invertida: `\$1.00`. Uma barra invertida antes de qualquer outro `$` é deixada inalterada. Apenas uma única barra invertida diretamente antes do token a escapa. Uma barra invertida duplicada como `\\$1` deixa ambas as barras invertidas no lugar, e `$1` ainda expande para o valor do argumento.

303 

291**Exemplo usando substituições:**304**Exemplo usando substituições:**

292 305 

293```yaml theme={null}306```yaml theme={null}


395---408---

396```409```

397 410 

398Para bloquear uma skill de usar certas ferramentas, adicione regras de negação em suas [configurações de permissão](/pt/permissions) em vez disso.411Para remover ferramentas do pool disponível de Claude enquanto uma skill está ativa, liste-as em `disallowed-tools` no frontmatter da skill. A restrição é limpa quando você envia sua próxima mensagem. Para bloquear ferramentas em todas as skills e prompts, adicione regras de negação em suas [configurações de permissão](/pt/permissions).

399 412 

400<h3 id="pass-arguments-to-skills">413<h3 id="pass-arguments-to-skills">

401 Passe argumentos para skills414 Passe argumentos para skills


557 570 

558O campo `agent` especifica qual configuração de subagent usar. As opções incluem agents integrados (`Explore`, `Plan`, `general-purpose`) ou qualquer subagent personalizado de `.claude/agents/`. Se omitido, usa `general-purpose`.571O campo `agent` especifica qual configuração de subagent usar. As opções incluem agents integrados (`Explore`, `Plan`, `general-purpose`) ou qualquer subagent personalizado de `.claude/agents/`. Se omitido, usa `general-purpose`.

559 572 

560<h3 id="restrict-claude-s-skill-access">573<h3 id="restrict-claudes-skill-access">

561 Restrinja acesso de skill do Claude574 Restrinja acesso de skill do Claude

562</h3>575</h3>

563 576 


850 Descrições de skills são cortadas863 Descrições de skills são cortadas

851</h3>864</h3>

852 865 

853Descrições de skills são carregadas em contexto para que Claude saiba o que está disponível. Todos os nomes de skills são sempre incluídos, mas se você tem muitas skills, descrições são encurtadas para caber no orçamento de caracteres, o que pode remover as palavras-chave que Claude precisa para corresponder sua solicitação. O orçamento escala em 1% da janela de contexto do modelo. Quando transborda, descrições para as skills que você invoca menos são removidas primeiro, então as skills que você realmente usa mantêm seu texto completo. Execute `/doctor` para ver se o orçamento está transbordando e quais skills são afetadas.866Descrições de skills são carregadas em contexto para que Claude saiba o que está disponível. Todos os nomes de skills são sempre incluídos, mas se você tem muitas skills, descrições são encurtadas para caber no orçamento de caracteres, o que pode remover as palavras-chave que Claude precisa para corresponder sua solicitação. O orçamento escala em 1% da janela de contexto do modelo. Quando transborda, descrições para as skills que você invoca menos são removidas primeiro, então as skills que você realmente usa mantêm seu texto completo. Execute `/doctor` para ver quantas descrições de skills estão sendo encurtadas ou removidas e quais skills são afetadas.

854 867 

855Para aumentar o orçamento, defina a configuração [`skillListingBudgetFraction`](/pt/settings#available-settings) (por exemplo, `0.02` = 2%) ou a variável de ambiente `SLASH_COMMAND_TOOL_CHAR_BUDGET` para uma contagem de caracteres fixa. Para liberar orçamento para outras skills, defina entradas de baixa prioridade como `"name-only"` em [`skillOverrides`](#override-skill-visibility-from-settings) para que sejam listadas sem uma descrição. Você também pode aparar o texto de `description` e `when_to_use` na fonte: coloque o caso de uso principal na frente, já que o texto combinado de cada entrada é limitado a 1.536 caracteres independentemente do orçamento. O limite é configurável com [`maxSkillDescriptionChars`](/pt/settings#available-settings).868Para aumentar o orçamento, defina a configuração [`skillListingBudgetFraction`](/pt/settings#available-settings) (por exemplo, `0.02` = 2%) ou a variável de ambiente `SLASH_COMMAND_TOOL_CHAR_BUDGET` para uma contagem de caracteres fixa. Para liberar orçamento para outras skills, defina entradas de baixa prioridade como `"name-only"` em [`skillOverrides`](#override-skill-visibility-from-settings) para que sejam listadas sem uma descrição. Você também pode aparar o texto de `description` e `when_to_use` na fonte: coloque o caso de uso principal na frente, já que o texto combinado de cada entrada é limitado a 1.536 caracteres independentemente do orçamento. O limite é configurável com [`maxSkillDescriptionChars`](/pt/settings#available-settings).

856 869 

slack.md +1 −1

Details

182 182 

183Este modelo baseado em canal permite que as equipes restrinjam o uso de Claude Code a canais específicos, fornecendo uma camada adicional de controle de acesso além das permissões no nível do espaço de trabalho.183Este modelo baseado em canal permite que as equipes restrinjam o uso de Claude Code a canais específicos, fornecendo uma camada adicional de controle de acesso além das permissões no nível do espaço de trabalho.

184 184 

185<h2 id="what-s-accessible-where">185<h2 id="whats-accessible-where">

186 O que é acessível onde186 O que é acessível onde

187</h2>187</h2>

188 188 

statusline.md +64 −22

Details

15* Trabalha em várias sessões e precisa distingui-las15* Trabalha em várias sessões e precisa distingui-las

16* Quer que a ramificação git e o status estejam sempre visíveis16* Quer que a ramificação git e o status estejam sempre visíveis

17 17 

18O Claude Code também pode renderizar [crachás de links de rodapé](/pt/settings#footer-link-badges): chips clicáveis que aparecem no rodapé quando uma regex configurada corresponde ao texto na conversa. Estes são independentes da linha de status e não interagem com seu script; configure-os com a configuração [`footerLinksRegexes`](/pt/settings#footer-link-badges).

19 

18Aqui está um exemplo de uma [linha de status de múltiplas linhas](#display-multiple-lines) que exibe informações do git na primeira linha e uma barra de contexto codificada por cores na segunda.20Aqui está um exemplo de uma [linha de status de múltiplas linhas](#display-multiple-lines) que exibe informações do git na primeira linha e uma barra de contexto codificada por cores na segunda.

19 21 

20<Frame>22<Frame>


23 25 

24Esta página orienta você sobre [configurar uma linha de status básica](#set-up-a-status-line), explica [como os dados fluem](#how-status-lines-work) do Claude Code para seu script, lista [todos os campos que você pode exibir](#available-data) e fornece [exemplos prontos para usar](#examples) para padrões comuns como status do git, rastreamento de custos e barras de progresso.26Esta página orienta você sobre [configurar uma linha de status básica](#set-up-a-status-line), explica [como os dados fluem](#how-status-lines-work) do Claude Code para seu script, lista [todos os campos que você pode exibir](#available-data) e fornece [exemplos prontos para usar](#examples) para padrões comuns como status do git, rastreamento de custos e barras de progresso.

25 27 

26## Configurar uma linha de status28<h2 id="set-up-a-status-line">

29 Configurar uma linha de status

30</h2>

27 31 

28Use o [comando `/statusline`](#use-the-statusline-command) para fazer com que o Claude Code gere um script para você, ou [crie manualmente um script](#manually-configure-a-status-line) e adicione-o às suas configurações.32Use o [comando `/statusline`](#use-the-%2Fstatusline-command) para fazer com que o Claude Code gere um script para você, ou [crie manualmente um script](#manually-configure-a-status-line) e adicione-o às suas configurações.

29 33 

30### Use o comando /statusline34<h3 id="use-the-/statusline-command">

35 Use o comando /statusline

36</h3>

31 37 

32O comando `/statusline` aceita instruções em linguagem natural descrevendo o que você quer exibir. O Claude Code gera um arquivo de script em `~/.claude/` e atualiza suas configurações automaticamente:38O comando `/statusline` aceita instruções em linguagem natural descrevendo o que você quer exibir. O Claude Code gera um arquivo de script em `~/.claude/` e atualiza suas configurações automaticamente:

33 39 


35/statusline show model name and context percentage with a progress bar41/statusline show model name and context percentage with a progress bar

36```42```

37 43 

38### Configure manualmente uma linha de status44<h3 id="manually-configure-a-status-line">

45 Configure manualmente uma linha de status

46</h3>

39 47 

40Adicione um campo `statusLine` às suas configurações de usuário (`~/.claude/settings.json`, onde `~` é seu diretório inicial) ou [configurações de projeto](/pt/settings#settings-files). Defina `type` como `"command"` e aponte `command` para um caminho de script ou um comando de shell inline. Para um passo a passo completo de criação de um script, consulte [Construir uma linha de status passo a passo](#build-a-status-line-step-by-step).48Adicione um campo `statusLine` às suas configurações de usuário (`~/.claude/settings.json`, onde `~` é seu diretório inicial) ou [configurações de projeto](/pt/settings#settings-files). Defina `type` como `"command"` e aponte `command` para um caminho de script ou um comando de shell inline. Para um passo a passo completo de criação de um script, consulte [Construir uma linha de status passo a passo](#build-a-status-line-step-by-step).

41 49 


66 74 

67O campo `hideVimModeIndicator` opcional suprime o texto integrado `-- INSERT --` abaixo do prompt. Defina isto como `true` quando seu script renderizar [`vim.mode`](#available-data) em si, para que o modo não seja exibido duas vezes.75O campo `hideVimModeIndicator` opcional suprime o texto integrado `-- INSERT --` abaixo do prompt. Defina isto como `true` quando seu script renderizar [`vim.mode`](#available-data) em si, para que o modo não seja exibido duas vezes.

68 76 

69### Desabilitar a linha de status77<h3 id="disable-the-status-line">

78 Desabilitar a linha de status

79</h3>

70 80 

71Execute `/statusline` e peça para remover ou limpar sua linha de status (por exemplo, `/statusline delete`, `/statusline clear`, `/statusline remove it`). Você também pode excluir manualmente o campo `statusLine` do seu settings.json.81Execute `/statusline` e peça para remover ou limpar sua linha de status (por exemplo, `/statusline delete`, `/statusline clear`, `/statusline remove it`). Você também pode excluir manualmente o campo `statusLine` do seu settings.json.

72 82 

73## Construir uma linha de status passo a passo83<h2 id="build-a-status-line-step-by-step">

84 Construir uma linha de status passo a passo

85</h2>

74 86 

75Este passo a passo mostra o que está acontecendo nos bastidores criando manualmente uma linha de status que exibe o modelo atual, diretório de trabalho e porcentagem de uso da janela de contexto.87Este passo a passo mostra o que está acontecendo nos bastidores criando manualmente uma linha de status que exibe o modelo atual, diretório de trabalho e porcentagem de uso da janela de contexto.

76 88 

77<Note>Executar [`/statusline`](#use-the-statusline-command) com uma descrição do que você quer configura tudo isso automaticamente para você.</Note>89<Note>Executar [`/statusline`](#use-the-%2Fstatusline-command) com uma descrição do que você quer configura tudo isso automaticamente para você.</Note>

78 90 

79Estes exemplos usam scripts Bash, que funcionam no macOS e Linux. No Windows, consulte [Configuração do Windows](#windows-configuration) para exemplos de PowerShell e Git Bash.91Estes exemplos usam scripts Bash, que funcionam no macOS e Linux. No Windows, consulte [Configuração do Windows](#windows-configuration) para exemplos de PowerShell e Git Bash.

80 92 


128 </Step>140 </Step>

129</Steps>141</Steps>

130 142 

131## Como as linhas de status funcionam143<h2 id="how-status-lines-work">

144 Como as linhas de status funcionam

145</h2>

132 146 

133O Claude Code executa seu script e envia [dados de sessão JSON](#available-data) para ele via stdin. Seu script lê o JSON, extrai o que precisa e imprime texto para stdout. O Claude Code exibe tudo o que seu script imprime.147O Claude Code executa seu script e envia [dados de sessão JSON](#available-data) para ele via stdin. Seu script lê o JSON, extrai o que precisa e imprime texto para stdout. O Claude Code exibe tudo o que seu script imprime.

134 148 


150 164 

151<Note>A linha de status é executada localmente e não consome tokens de API. Ela se oculta temporariamente durante certas interações da interface, incluindo sugestões de preenchimento automático, o menu de ajuda e prompts de permissão.</Note>165<Note>A linha de status é executada localmente e não consome tokens de API. Ela se oculta temporariamente durante certas interações da interface, incluindo sugestões de preenchimento automático, o menu de ajuda e prompts de permissão.</Note>

152 166 

153## Dados disponíveis167<h2 id="available-data">

168 Dados disponíveis

169</h2>

154 170 

155O Claude Code envia os seguintes campos JSON para seu script via stdin:171O Claude Code envia os seguintes campos JSON para seu script via stdin:

156 172 


297 Trate campos ausentes com acesso condicional e valores nulos com padrões de fallback em seus scripts.313 Trate campos ausentes com acesso condicional e valores nulos com padrões de fallback em seus scripts.

298</Accordion>314</Accordion>

299 315 

300### Campos de janela de contexto316<h3 id="context-window-fields">

317 Campos de janela de contexto

318</h3>

301 319 

302O objeto `context_window` descreve a janela de contexto em tempo real da resposta de API mais recente. A partir da v2.1.132, `total_input_tokens` e `total_output_tokens` refletem o uso de contexto atual, não totais cumulativos de sessão.320O objeto `context_window` descreve a janela de contexto em tempo real da resposta de API mais recente. A partir da v2.1.132, `total_input_tokens` e `total_output_tokens` refletem o uso de contexto atual, não totais cumulativos de sessão.

303 321 


319 337 

320O objeto `current_usage` é `null` antes da primeira chamada de API em uma sessão, e novamente imediatamente após `/compact` até que a próxima chamada de API a repopule.338O objeto `current_usage` é `null` antes da primeira chamada de API em uma sessão, e novamente imediatamente após `/compact` até que a próxima chamada de API a repopule.

321 339 

322## Exemplos340<h2 id="examples">

341 Exemplos

342</h2>

323 343 

324Estes exemplos mostram padrões comuns de linha de status. Para usar qualquer exemplo:344Estes exemplos mostram padrões comuns de linha de status. Para usar qualquer exemplo:

325 345 


329 349 

330Os exemplos de Bash usam [`jq`](https://jqlang.github.io/jq/) para analisar JSON. Python e Node.js têm análise JSON integrada.350Os exemplos de Bash usam [`jq`](https://jqlang.github.io/jq/) para analisar JSON. Python e Node.js têm análise JSON integrada.

331 351 

332### Uso da janela de contexto352<h3 id="context-window-usage">

353 Uso da janela de contexto

354</h3>

333 355 

334Exiba o modelo atual e o uso da janela de contexto com uma barra de progresso visual. Cada script lê JSON de stdin, extrai o campo `used_percentage` e constrói uma barra de 10 caracteres onde blocos preenchidos (▓) representam o uso:356Exiba o modelo atual e o uso da janela de contexto com uma barra de progresso visual. Cada script lê JSON de stdin, extrai o campo `used_percentage` e constrói uma barra de 10 caracteres onde blocos preenchidos (▓) representam o uso:

335 357 


396 ```418 ```

397</CodeGroup>419</CodeGroup>

398 420 

399### Status do git com cores421<h3 id="git-status-with-colors">

422 Status do git com cores

423</h3>

400 424 

401Mostre a ramificação git com indicadores codificados por cores para arquivos preparados e modificados. Este script usa [códigos de escape ANSI](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) para cores de terminal: `\033[32m` é verde, `\033[33m` é amarelo e `\033[0m` redefine para padrão.425Mostre a ramificação git com indicadores codificados por cores para arquivos preparados e modificados. Este script usa [códigos de escape ANSI](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) para cores de terminal: `\033[32m` é verde, `\033[33m` é amarelo e `\033[0m` redefine para padrão.

402 426 


490 ```514 ```

491</CodeGroup>515</CodeGroup>

492 516 

493### Rastreamento de custo e duração517<h3 id="cost-and-duration-tracking">

518 Rastreamento de custo e duração

519</h3>

494 520 

495Rastreie os custos de API e o tempo decorrido da sua sessão. O campo `cost.total_cost_usd` acumula o custo estimado de todas as chamadas de API na sessão atual. O campo `cost.total_duration_ms` mede o tempo total decorrido desde o início da sessão, enquanto `cost.total_api_duration_ms` rastreia apenas o tempo gasto aguardando respostas de API.521Rastreie os custos de API e o tempo decorrido da sua sessão. O campo `cost.total_cost_usd` acumula o custo estimado de todas as chamadas de API na sessão atual. O campo `cost.total_duration_ms` mede o tempo total decorrido desde o início da sessão, enquanto `cost.total_api_duration_ms` rastreia apenas o tempo gasto aguardando respostas de API.

496 522 


551 ```577 ```

552</CodeGroup>578</CodeGroup>

553 579 

554### Exibir múltiplas linhas580<h3 id="display-multiple-lines">

581 Exibir múltiplas linhas

582</h3>

555 583 

556Seu script pode exibir múltiplas linhas para criar uma exibição mais rica. Cada instrução `echo` produz uma linha separada na área de status.584Seu script pode exibir múltiplas linhas para criar uma exibição mais rica. Cada instrução `echo` produz uma linha separada na área de status.

557 585 


658 ```686 ```

659</CodeGroup>687</CodeGroup>

660 688 

661### Links clicáveis689<h3 id="clickable-links">

690 Links clicáveis

691</h3>

662 692 

663Este exemplo cria um link clicável para seu repositório GitHub. Ele lê a URL remota do git, converte o formato SSH para HTTPS com `sed` e envolve o nome do repositório em códigos de escape OSC 8. Mantenha Cmd (macOS) ou Ctrl (Windows/Linux) pressionado e clique para abrir o link em seu navegador.693Este exemplo cria um link clicável para seu repositório GitHub. Ele lê a URL remota do git, converte o formato SSH para HTTPS com `sed` e envolve o nome do repositório em códigos de escape OSC 8. Mantenha Cmd (macOS) ou Ctrl (Windows/Linux) pressionado e clique para abrir o link em seu navegador.

664 694 


738 ```768 ```

739</CodeGroup>769</CodeGroup>

740 770 

741### Uso de limite de taxa771<h3 id="rate-limit-usage">

772 Uso de limite de taxa

773</h3>

742 774 

743Exiba o uso do limite de taxa de assinatura Claude.ai na linha de status. O objeto `rate_limits` contém `five_hour` (janela móvel de 5 horas) e `seven_day` (janelas semanais). Cada janela fornece `used_percentage` (0-100) e `resets_at` (segundos de época Unix quando a janela é redefinida).775Exiba o uso do limite de taxa de assinatura Claude.ai na linha de status. O objeto `rate_limits` contém `five_hour` (janela móvel de 5 horas) e `seven_day` (janelas semanais). Cada janela fornece `used_percentage` (0-100) e `resets_at` (segundos de época Unix quando a janela é redefinida).

744 776 


804 ```836 ```

805</CodeGroup>837</CodeGroup>

806 838 

807### Cache de operações caras839<h3 id="cache-expensive-operations">

840 Cache de operações caras

841</h3>

808 842 

809Seu script de linha de status é executado frequentemente durante sessões ativas. Comandos como `git status` ou `git diff` podem ser lentos, especialmente em repositórios grandes. Este exemplo armazena em cache informações do git em um arquivo temporário e apenas as atualiza a cada 5 segundos.843Seu script de linha de status é executado frequentemente durante sessões ativas. Comandos como `git status` ou `git diff` podem ser lentos, especialmente em repositórios grandes. Este exemplo armazena em cache informações do git em um arquivo temporário e apenas as atualiza a cada 5 segundos.

810 844 


935 ```969 ```

936</CodeGroup>970</CodeGroup>

937 971 

938### Configuração do Windows972<h3 id="windows-configuration">

973 Configuração do Windows

974</h3>

939 975 

940No Windows, o Claude Code executa comandos de linha de status através do Git Bash quando o Git Bash está instalado, ou através do PowerShell quando o Git Bash está ausente.976No Windows, o Claude Code executa comandos de linha de status através do Git Bash quando o Git Bash está instalado, ou através do PowerShell quando o Git Bash está ausente.

941 977 


990 ```1026 ```

991</CodeGroup>1027</CodeGroup>

992 1028 

993## Linhas de status de subagente1029<h2 id="subagent-status-lines">

1030 Linhas de status de subagente

1031</h2>

994 1032 

995A configuração `subagentStatusLine` renderiza um corpo de linha personalizado para cada [subagente](/pt/sub-agents) mostrado no painel de agente abaixo do prompt. Use-a para substituir a linha padrão `name · description · token count` pela sua própria formatação.1033A configuração `subagentStatusLine` renderiza um corpo de linha personalizado para cada [subagente](/pt/sub-agents) mostrado no painel de agente abaixo do prompt. Use-a para substituir a linha padrão `name · description · token count` pela sua própria formatação.

996 1034 


1009 1047 

1010Os mesmos portões de confiança e `disableAllHooks` que se aplicam a `statusLine` se aplicam aqui. Plugins podem enviar um `subagentStatusLine` padrão em seu [`settings.json`](/pt/plugins-reference#standard-plugin-layout).1048Os mesmos portões de confiança e `disableAllHooks` que se aplicam a `statusLine` se aplicam aqui. Plugins podem enviar um `subagentStatusLine` padrão em seu [`settings.json`](/pt/plugins-reference#standard-plugin-layout).

1011 1049 

1012## Dicas1050<h2 id="tips">

1051 Dicas

1052</h2>

1013 1053 

1014* **Teste com entrada simulada**: `echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh`1054* **Teste com entrada simulada**: `echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh`

1015* **Mantenha a saída curta**: a barra de status tem largura limitada, então saída longa pode ser truncada ou quebrada de forma estranha1055* **Mantenha a saída curta**: a barra de status tem largura limitada, então saída longa pode ser truncada ou quebrada de forma estranha


1017 1057 

1018Projetos comunitários como [ccstatusline](https://github.com/sirmalloc/ccstatusline) e [starship-claude](https://github.com/martinemde/starship-claude) fornecem configurações pré-construídas com temas e recursos adicionais.1058Projetos comunitários como [ccstatusline](https://github.com/sirmalloc/ccstatusline) e [starship-claude](https://github.com/martinemde/starship-claude) fornecem configurações pré-construídas com temas e recursos adicionais.

1019 1059 

1020## Solução de problemas1060<h2 id="troubleshooting">

1061 Solução de problemas

1062</h2>

1021 1063 

1022**Linha de status não aparecendo**1064**Linha de status não aparecendo**

1023 1065 

sub-agents.md +50 −20

Details

61 * **Tools**: Ferramentas somente leitura (acesso negado a ferramentas Write e Edit)61 * **Tools**: Ferramentas somente leitura (acesso negado a ferramentas Write e Edit)

62 * **Purpose**: Pesquisa de base de código para planejamento62 * **Purpose**: Pesquisa de base de código para planejamento

63 63 

64 Quando você está em plan mode e Claude precisa entender sua base de código, ele delega a pesquisa para o subagente Plan. Isso evita aninhamento infinito (subagentes não podem gerar outros subagentes) enquanto ainda reúne o contexto necessário.64 Quando você está em plan mode e Claude precisa entender sua base de código, ele delega a pesquisa para o subagente Plan para que a saída de exploração permaneça em uma janela de contexto separada enquanto a conversa principal permanece somente leitura.

65 </Tab>65 </Tab>

66 66 

67 <Tab title="General-purpose">67 <Tab title="General-purpose">


84 </Tab>84 </Tab>

85</Tabs>85</Tabs>

86 86 

87Os subagentes integrados são sempre registrados em sessões interativas. Para bloquear um tipo integrado específico, adicione-o a `permissions.deny` conforme mostrado em [Desabilitar subagentes específicos](#disable-specific-subagents). Para impedir que Claude delegue a qualquer subagente, negue a ferramenta `Agent` em si com [`permissions.deny`](/pt/permissions#tool-specific-permission-rules). Em [modo não interativo](/pt/headless) e no [Agent SDK](/pt/agent-sdk/overview), defina [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/pt/env-vars) para remover todos os tipos integrados e fornecer apenas os seus próprios.

88 

87Além desses subagentes integrados, você pode criar os seus próprios com prompts personalizados, restrições de ferramentas, modos de permissão, hooks e skills. As seções a seguir mostram como começar e personalizar subagentes.89Além desses subagentes integrados, você pode criar os seus próprios com prompts personalizados, restrições de ferramentas, modos de permissão, hooks e skills. As seções a seguir mostram como começar e personalizar subagentes.

88 90 

89<h2 id="quickstart-create-your-first-subagent">91<h2 id="quickstart-create-your-first-subagent">


158 Usar o comando /agents160 Usar o comando /agents

159</h3>161</h3>

160 162 

161O comando `/agents` abre uma interface com abas para gerenciar subagentes. A aba **Running** mostra subagentes ao vivo e permite que você os abra ou pare. A aba **Library** permite que você:163O comando `/agents` abre uma interface com abas para gerenciar subagentes. A aba **Running** lista subagentes ao vivo e recentemente finalizados e permite que você os abra ou pare. A aba **Library** permite que você:

162 164 

163* Visualize todos os subagentes disponíveis (integrados, usuário, projeto e plugin)165* Visualize todos os subagentes disponíveis (integrados, usuário, projeto e plugin)

164* Crie novos subagentes com configuração guiada ou geração por Claude166* Crie novos subagentes com configuração guiada ou geração por Claude


184 186 

185**Subagentes de projeto** (`.claude/agents/`) são ideais para subagentes específicos de uma base de código. Verifique-os no controle de versão para que sua equipe possa usá-los e melhorá-los colaborativamente.187**Subagentes de projeto** (`.claude/agents/`) são ideais para subagentes específicos de uma base de código. Verifique-os no controle de versão para que sua equipe possa usá-los e melhorá-los colaborativamente.

186 188 

187Subagentes de projeto são descobertos caminhando para cima a partir do diretório de trabalho atual. Diretórios adicionados com `--add-dir` [concedem apenas acesso a arquivos](/pt/permissions#additional-directories-grant-file-access-not-configuration) e não são verificados para subagentes. Para compartilhar subagentes entre projetos, use `~/.claude/agents/` ou um [plugin](/pt/plugins).189Subagentes de projeto são descobertos caminhando para cima a partir do diretório de trabalho atual, portanto cada `.claude/agents/` entre e a raiz do repositório é verificado. {/* min-version: 2.1.178 */}A partir da v2.1.178, quando mais de um desses diretórios aninhados define o mesmo `name`, Claude Code usa a definição mais próxima do diretório de trabalho.

190 

191Diretórios adicionados com `--add-dir` também são verificados: uma pasta `.claude/agents/` dentro de um diretório adicionado carrega junto com subagentes de projeto. Veja [Diretórios adicionais](/pt/permissions#additional-directories-grant-file-access-not-configuration) para quais outros tipos de configuração carregam de `--add-dir`. Para compartilhar subagentes entre projetos sem `--add-dir`, use `~/.claude/agents/` ou um [plugin](/pt/plugins).

188 192 

189**Subagentes de usuário** (`~/.claude/agents/`) são subagentes pessoais disponíveis em todos os seus projetos.193**Subagentes de usuário** (`~/.claude/agents/`) são subagentes pessoais disponíveis em todos os seus projetos.

190 194 


282| `description` | Yes | Quando Claude deve delegar para este subagente |286| `description` | Yes | Quando Claude deve delegar para este subagente |

283| `tools` | No | [Ferramentas](#available-tools) que o subagente pode usar. Herda todas as ferramentas se omitido. Para pré-carregar Skills no contexto, use o campo `skills` em vez de listar `Skill` aqui |287| `tools` | No | [Ferramentas](#available-tools) que o subagente pode usar. Herda todas as ferramentas se omitido. Para pré-carregar Skills no contexto, use o campo `skills` em vez de listar `Skill` aqui |

284| `disallowedTools` | No | Ferramentas a negar, removidas da lista herdada ou especificada |288| `disallowedTools` | No | Ferramentas a negar, removidas da lista herdada ou especificada |

285| `model` | No | [Modelo](#choose-a-model) a usar: `sonnet`, `opus`, `haiku`, um ID de modelo completo (por exemplo, `claude-opus-4-8`), ou `inherit`. Padrão: `inherit` |289| `model` | No | [Modelo](#choose-a-model) a usar: `sonnet`, `opus`, `haiku`, `fable`, um ID de modelo completo (por exemplo, `claude-opus-4-8`), ou `inherit`. Padrão: `inherit` |

286| `permissionMode` | No | [Modo de permissão](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, ou `plan`. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |290| `permissionMode` | No | [Modo de permissão](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, ou `plan`. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |

287| `maxTurns` | No | Número máximo de turnos de agente antes do subagente parar |291| `maxTurns` | No | Número máximo de turnos de agente antes do subagente parar |

288| `skills` | No | [Skills](/pt/skills) a pré-carregar no contexto do subagente na inicialização. O conteúdo completo da skill é injetado, não apenas a descrição. Subagentes ainda podem invocar skills de projeto, usuário e plugin não listadas através da ferramenta Skill |292| `skills` | No | [Skills](/pt/skills) a pré-carregar no contexto do subagente na inicialização. O conteúdo completo da skill é injetado, não apenas a descrição. Subagentes ainda podem invocar skills de projeto, usuário e plugin não listadas através da ferramenta Skill |


301 305 

302O campo `model` controla qual [modelo de IA](/pt/model-config) o subagente usa:306O campo `model` controla qual [modelo de IA](/pt/model-config) o subagente usa:

303 307 

304* **Alias de modelo**: Use um dos aliases disponíveis: `sonnet`, `opus`, ou `haiku`308* **Alias de modelo**: Use um dos aliases disponíveis: `sonnet`, `opus`, `haiku`, ou `fable`

305* **ID de modelo completo**: Use um ID de modelo completo como `claude-opus-4-8` ou `claude-sonnet-4-6`. Aceita os mesmos valores que o flag `--model`309* **ID de modelo completo**: Use um ID de modelo completo como `claude-opus-4-8` ou `claude-sonnet-4-6`. Aceita os mesmos valores que o flag `--model`

306* **inherit**: Use o mesmo modelo que a conversa principal310* **inherit**: Use o mesmo modelo que a conversa principal

307* **Omitido**: Se não especificado, padrão é `inherit` (usa o mesmo modelo que a conversa principal)311* **Omitido**: Se não especificado, padrão é `inherit` (usa o mesmo modelo que a conversa principal)


325 329 

326Subagentes herdam as [ferramentas internas](/pt/tools-reference) e ferramentas MCP disponíveis na conversa principal por padrão. As seguintes ferramentas dependem da interface ou estado de sessão da conversa principal e não estão disponíveis para subagentes, mesmo quando listadas no campo `tools`:330Subagentes herdam as [ferramentas internas](/pt/tools-reference) e ferramentas MCP disponíveis na conversa principal por padrão. As seguintes ferramentas dependem da interface ou estado de sessão da conversa principal e não estão disponíveis para subagentes, mesmo quando listadas no campo `tools`:

327 331 

328* `Agent`

329* `AskUserQuestion`332* `AskUserQuestion`

330* `EnterPlanMode`333* `EnterPlanMode`

331* `ExitPlanMode`, a menos que o [`permissionMode`](#permission-modes) do subagente seja `plan`334* `ExitPlanMode`, a menos que o [`permissionMode`](#permission-modes) do subagente seja `plan`


354 357 

355Se ambos forem definidos, `disallowedTools` é aplicado primeiro, depois `tools` é resolvido contra o pool restante. Uma ferramenta listada em ambos é removida.358Se ambos forem definidos, `disallowedTools` é aplicado primeiro, depois `tools` é resolvido contra o pool restante. Uma ferramenta listada em ambos é removida.

356 359 

360Ambos os campos aceitam padrões de nível de servidor MCP além de nomes de ferramentas exatos: `mcp__<server>` ou `mcp__<server>__*` concede ou remove todas as ferramentas do servidor nomeado. Em `disallowedTools`, `mcp__*` também remove todas as ferramentas MCP de qualquer servidor. Este exemplo remove todas as ferramentas do servidor MCP `github` enquanto mantém ferramentas de outros servidores e todas as ferramentas integradas:

361 

362```yaml theme={null}

363---

364name: local-only

365description: Inherits every tool except those from the github MCP server

366disallowedTools: mcp__github

367---

368```

369 

357<h4 id="restrict-which-subagents-can-be-spawned">370<h4 id="restrict-which-subagents-can-be-spawned">

358 Restringir quais subagentes podem ser gerados371 Restringir quais subagentes podem ser gerados

359</h4>372</h4>


378tools: Agent, Read, Bash391tools: Agent, Read, Bash

379```392```

380 393 

381Se `Agent` for omitido da lista `tools` inteiramente, o agente não pode gerar nenhum subagente. Esta restrição se aplica apenas a agentes executados como thread principal com `claude --agent`. Subagentes não podem gerar outros subagentes, então `Agent(agent_type)` não tem efeito em definições de subagente.394Se `Agent` for omitido da lista `tools` inteiramente, o agente não pode gerar nenhum subagente.

395 

396A sintaxe de lista de permissões `Agent(agent_type)` se aplica apenas a um agente executado como thread principal com `claude --agent`. Em uma definição de subagente, listar `Agent` em `tools` permite que esse subagente [gere subagentes aninhados](#spawn-nested-subagents), mas qualquer lista de tipo dentro dos parênteses é ignorada.

382 397 

383<h4 id="scope-mcp-servers-to-a-subagent">398<h4 id="scope-mcp-servers-to-a-subagent">

384 Escopo de MCP servers para um subagente399 Escopo de MCP servers para um subagente


444| `plan` | Plan mode (exploração somente leitura) |459| `plan` | Plan mode (exploração somente leitura) |

445 460 

446<Warning>461<Warning>

447 Use `bypassPermissions` com cuidado. Ele pula prompts de permissão, permitindo que o subagente execute operações sem aprovação, incluindo escritas em `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn` e `.mvn`. Remoções de diretório raiz e home como `rm -rf /` ainda solicitam como um disjuntor de circuito. Veja [modos de permissão](/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) para detalhes.462 Use `bypassPermissions` com cuidado. Ele pula prompts de permissão, permitindo que o subagente execute operações sem aprovação, incluindo escritas em `.git`, `.config/git`, `.claude`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn` e `.mvn`. Regras [`ask`](/pt/permissions#manage-permissions) explícitas e remoções de diretório raiz e home como `rm -rf /` ainda solicitam. Veja [modos de permissão](/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode) para detalhes.

448</Warning>463</Warning>

449 464 

450Se o pai usar `bypassPermissions` ou `acceptEdits`, isso tem precedência e não pode ser sobrescrito. Se o pai usar [auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode), o subagente herda auto mode e qualquer `permissionMode` em seu frontmatter é ignorado: o classificador avalia as chamadas de ferramentas do subagente com as mesmas regras de bloqueio e permissão que a sessão pai.465Se o pai usar `bypassPermissions` ou `acceptEdits`, isso tem precedência e não pode ser sobrescrito. Se o pai usar [auto mode](/pt/permission-modes#eliminate-prompts-with-auto-mode), o subagente herda auto mode e qualquer `permissionMode` em seu frontmatter é ignorado: o classificador avalia as chamadas de ferramentas do subagente com as mesmas regras de bloqueio e permissão que a sessão pai.


761 776 

762Para desabilitar toda a funcionalidade de tarefa em background, defina a variável de ambiente `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` para `1`. Veja [Variáveis de ambiente](/pt/env-vars).777Para desabilitar toda a funcionalidade de tarefa em background, defina a variável de ambiente `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` para `1`. Veja [Variáveis de ambiente](/pt/env-vars).

763 778 

764Quando [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) está definido, cada spawn de subagente é executado em background independentemente do campo `background`. Forks ainda exibem prompts de permissão em seu terminal conforme ocorrem; subagentes nomeados auto-negam qualquer coisa que solicitaria, conforme descrito acima.779Quando [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) está definido para `1`, cada spawn de subagente é executado em background independentemente do campo `background`. Forks ainda exibem prompts de permissão em seu terminal conforme ocorrem; subagentes nomeados auto-negam qualquer coisa que solicitaria, conforme descrito acima.

765 780 

766<h3 id="common-patterns">781<h3 id="common-patterns">

767 Padrões comuns782 Padrões comuns


826 841 

827Para uma pergunta rápida sobre algo já em sua conversa, use [`/btw`](/pt/interactive-mode#side-questions-with-%2Fbtw) em vez de um subagente. Ele vê seu contexto completo mas não tem acesso a ferramentas, e a resposta é descartada em vez de adicionada ao histórico.842Para uma pergunta rápida sobre algo já em sua conversa, use [`/btw`](/pt/interactive-mode#side-questions-with-%2Fbtw) em vez de um subagente. Ele vê seu contexto completo mas não tem acesso a ferramentas, e a resposta é descartada em vez de adicionada ao histórico.

828 843 

829<Note>844<h3 id="spawn-nested-subagents">

830 Subagentes não podem gerar outros subagentes. Se seu fluxo de trabalho requer delegação aninhada, use [Skills](/pt/skills) ou [encadeie subagentes](#chain-subagents) da conversa principal.845 Gerar subagentes aninhados

831</Note>846</h3>

847 

848{/* min-version: 2.1.172 */}A partir do Claude Code v2.1.172, um subagente pode gerar seus próprios subagentes. Use isso quando uma tarefa delegada em si se divide em subtarefas paralelas, como um subagente revisor que distribui um verificador por descoberta, para que a saída intermediária nunca alcance sua conversa principal. Apenas o resumo do subagente de nível superior retorna para você.

849 

850Um subagente aninhado é configurado da mesma forma que um de nível superior e é resolvido dos mesmos [escopos](#choose-the-subagent-scope). O painel de subagente abaixo da entrada de prompt mostra a árvore completa: cada linha exibe uma contagem `(+N)` de descendentes, e abrir uma linha mostra os filhos diretos desse subagente com um caminho de volta para `main`. A aba Running em [`/agents`](#use-the-%2Fagents-command) lista subagentes em execução como uma lista plana.

851 

852A profundidade é contada como o número de níveis de subagente abaixo da conversa principal, independentemente de cada nível ser executado em [foreground ou background](#run-subagents-in-foreground-or-background):

853 

854* **Subagentes em foreground**: podem gerar em qualquer profundidade. Cada nível bloqueia seu pai até retornar, então a cadeia é auto-limitante: a conversa principal aguarda toda a cadeia.

855* **Subagentes em background**: um subagente em background na profundidade cinco não recebe a ferramenta Agent e não pode gerar mais. O limite é fixo e não configurável, e existe para prevenir árvores concorrentes descontroladas.

856 

857Para prevenir um subagente específico de gerar outros, omita `Agent` de sua lista [`tools`](#available-tools) ou adicione-o a `disallowedTools`.

858 

859Um [fork](#fork-the-current-conversation) ainda não pode gerar outro fork. Pode gerar outros tipos de subagente, e esses contam para o limite de profundidade.

832 860 

833<h3 id="manage-subagent-context">861<h3 id="manage-subagent-context">

834 Gerenciar contexto de subagente862 Gerenciar contexto de subagente


860 888 

861Subagentes retomados retêm seu histórico de conversa completo, incluindo todas as chamadas de ferramentas anteriores, resultados e raciocínio. O subagente continua exatamente de onde parou em vez de começar do zero.889Subagentes retomados retêm seu histórico de conversa completo, incluindo todas as chamadas de ferramentas anteriores, resultados e raciocínio. O subagente continua exatamente de onde parou em vez de começar do zero.

862 890 

863Quando um subagente completa, Claude recebe seu ID de agente. Claude usa a ferramenta `SendMessage` com o ID do agente como campo `to` para retomá-lo. A ferramenta `SendMessage` está disponível apenas quando [equipes de agentes](/pt/agent-teams) estão habilitadas via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.891Quando um subagente completa, Claude recebe seu ID de agente. Os agentes integrados Explore e Plan são de uma única execução e não retornam ID de agente, então eles não podem ser retomados; use `general-purpose` ou um subagente personalizado quando você precisar continuar o trabalho. Claude usa a ferramenta `SendMessage` com o ID do agente como campo `to` para retomá-lo. A ferramenta `SendMessage` está disponível apenas quando [equipes de agentes](/pt/agent-teams) estão habilitadas via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.

864 892 

865Para retomar um subagente, peça a Claude para continuar o trabalho anterior:893Para retomar um subagente, peça a Claude para continuar o trabalho anterior:

866 894 


886 Auto-compactação914 Auto-compactação

887</h4>915</h4>

888 916 

889Subagentes suportam compactação automática usando a mesma lógica que a conversa principal. Por padrão, auto-compactação é acionada em aproximadamente 95% de capacidade. Para acionar compactação mais cedo, defina `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` para uma porcentagem mais baixa (por exemplo, `50`). Veja [variáveis de ambiente](/pt/env-vars) para detalhes.917Subagentes suportam compactação automática usando a mesma lógica que a conversa principal. A compactação é acionada sob as mesmas condições, e `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` se aplica a subagentes também. Veja [variáveis de ambiente](/pt/env-vars) para quando a sobrescrita entra em efeito.

890 918 

891Eventos de compactação são registrados em arquivos de transcrição de subagente:919Eventos de compactação são registrados em arquivos de transcrição de subagente:

892 920 


908</h2>936</h2>

909 937 

910<Note>938<Note>

911 Subagentes bifurcados requerem Claude Code v2.1.117 ou posterior. {/* min-version: 2.1.161 */}A partir da v2.1.161, o comando `/fork` está habilitado por padrão; em versões anteriores, requer definir a variável de ambiente [`CLAUDE_CODE_FORK_SUBAGENT`](/pt/env-vars) para `1`. Tornar bifurcações o comportamento de spawn *padrão* do modelo é experimental e pode mudar em versões futuras; habilite-o definindo a mesma variável. A variável é respeitada em modo interativo e via SDK ou `claude -p`.939 Subagentes bifurcados requerem Claude Code v2.1.117 ou posterior. {/* min-version: 2.1.161 */}A partir da v2.1.161, o comando `/fork` está habilitado por padrão; em versões anteriores, requer definir a variável de ambiente [`CLAUDE_CODE_FORK_SUBAGENT`](/pt/env-vars) para `1`. Deixar Claude gerar bifurcações é experimental e pode mudar em versões futuras. Esta capacidade também pode ser habilitada em sessões interativas como parte de um lançamento em fases.

912</Note>940</Note>

913 941 

914Uma bifurcação é um subagente que herda toda a conversa até agora em vez de começar do zero. Isso remove o isolamento de entrada que subagentes de outra forma fornecem: uma bifurcação vê o mesmo prompt de sistema, ferramentas, modelo e histórico de mensagens que a sessão principal, para que você possa entregar uma tarefa secundária sem re-explicar a situação. As chamadas de ferramentas da bifurcação ainda ficam fora de sua conversa e apenas seu resultado final volta, para que sua janela de contexto principal permaneça limpa. Use uma bifurcação quando um subagente nomeado precisaria de muito contexto para ser útil, ou quando você quer tentar várias abordagens em paralelo a partir do mesmo ponto de partida.942Uma bifurcação é um subagente que herda toda a conversa até agora em vez de começar do zero. Isso remove o isolamento de entrada que subagentes de outra forma fornecem: uma bifurcação vê o mesmo prompt de sistema, ferramentas, modelo e histórico de mensagens que a sessão principal, para que você possa entregar uma tarefa secundária sem re-explicar a situação. As chamadas de ferramentas da bifurcação ainda ficam fora de sua conversa e apenas seu resultado final volta, para que sua janela de contexto principal permaneça limpa. Use uma bifurcação quando um subagente nomeado precisaria de muito contexto para ser útil, ou quando você quer tentar várias abordagens em paralelo a partir do mesmo ponto de partida.

915 943 

916Definir `CLAUDE_CODE_FORK_SUBAGENT` muda Claude Code de duas formas:944Para controlar o modo de bifurcação independentemente do lançamento em fases, defina [`CLAUDE_CODE_FORK_SUBAGENT`](/pt/env-vars) para `1` para habilitá-lo explicitamente ou para `0` para desabilitá-lo. A variável é respeitada em modo interativo e via SDK ou `claude -p`.

945 

946Habilitar o modo de bifurcação muda Claude Code de duas formas:

917 947 

918* Claude gera uma bifurcação sempre que usaria o subagente [general-purpose](#built-in-subagents). Subagentes nomeados como Explore ainda geram como antes.948* Claude pode gerar uma bifurcação solicitando explicitamente o tipo de subagente `fork`. Gerações sem um tipo de subagente ainda usam o subagente [general-purpose](#built-in-subagents), e subagentes nomeados como Explore ainda geram como antes.

919* Cada spawn de subagente é executado em [background](#run-subagents-in-foreground-or-background), seja uma bifurcação ou um subagente nomeado. Defina `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` para `1` para manter spawns síncronos.949* Cada geração de subagente é executada em [background](#run-subagents-in-foreground-or-background), seja uma bifurcação ou um subagente nomeado. Defina `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` para `1` para manter gerações síncronas.

920 950 

921Você pode iniciar uma bifurcação você mesmo com `/fork` seguido de uma diretiva, com ou sem a variável definida. Claude Code nomeia a bifurcação a partir das primeiras palavras da diretiva. O exemplo a seguir bifurca a conversa para rascunhar casos de teste enquanto você continua com a implementação na sessão principal:951Você pode iniciar uma bifurcação você mesmo com `/fork` seguido de uma diretiva, com ou sem a variável definida. Claude Code nomeia a bifurcação a partir das primeiras palavras da diretiva. O exemplo a seguir bifurca a conversa para rascunhar casos de teste enquanto você continua com a implementação na sessão principal:

922 952 


953| Permissions | Prompts aparecem em seu terminal | [Auto-negados](#run-subagents-in-foreground-or-background) quando em execução em background |983| Permissions | Prompts aparecem em seu terminal | [Auto-negados](#run-subagents-in-foreground-or-background) quando em execução em background |

954| Prompt cache | Compartilhado com a sessão principal | Cache separado |984| Prompt cache | Compartilhado com a sessão principal | Cache separado |

955 985 

956Porque o prompt de sistema de uma bifurcação e as definições de ferramentas são idênticas ao pai, sua primeira solicitação reutiliza o cache de prompt do pai. Isso torna bifurcação mais barata do que gerar um subagente fresco para tarefas que precisam do mesmo contexto.986Porque o prompt de sistema de uma bifurcação e as definições de ferramentas são idênticas ao pai, sua primeira solicitação reutiliza o [prompt cache](/pt/prompt-caching#subagents-and-the-cache) do pai. Isso torna bifurcação mais barata do que gerar um subagente fresco para tarefas que precisam do mesmo contexto.

957 987 

958Quando Claude gera uma bifurcação através da ferramenta Agent, ele pode passar `isolation: "worktree"` para que as edições de arquivo da bifurcação sejam escritas em um git worktree separado em vez de seu checkout.988Quando Claude gera uma bifurcação através da ferramenta Agent, ele pode passar `isolation: "worktree"` para que as edições de arquivo da bifurcação sejam escritas em um git worktree separado em vez de seu checkout.

959 989 


961 Limitações991 Limitações

962</h3>992</h3>

963 993 

964Definir `CLAUDE_CODE_FORK_SUBAGENT=1` habilita fork mode em sessões interativas, [modo não-interativo](/pt/headless) e o Agent SDK. Uma bifurcação não pode gerar bifurcações adicionais.994Definir `CLAUDE_CODE_FORK_SUBAGENT=1` habilita fork mode em sessões interativas, [modo não-interativo](/pt/headless) e o Agent SDK; definir para `0` desabilita fork mode em todos os lugares, incluindo qualquer lançamento no servidor. Uma bifurcação não pode gerar bifurcações adicionais.

965 995 

966<h2 id="example-subagents">996<h2 id="example-subagents">

967 Subagentes de exemplo997 Subagentes de exemplo

Details

291</Accordion>291</Accordion>

292 292 

293<h2 id="switch-to-fullscreen-rendering">293<h2 id="switch-to-fullscreen-rendering">

294 Switch to fullscreen rendering294 Mudar para renderização em tela cheia

295</h2>295</h2>

296 296 

297Se a exibição piscar ou a posição de rolagem pular enquanto Claude está trabalhando, mude para o [modo de renderização em tela cheia](/pt/fullscreen). Ele desenha em uma tela separada que o terminal reserva para aplicativos em tela cheia em vez de anexar ao seu scrollback normal, o que mantém o uso de memória plano e adiciona suporte a mouse para rolagem e seleção. Neste modo você rola com o mouse ou PageUp dentro do Claude Code em vez de com o scrollback nativo do seu terminal; consulte a [página de tela cheia](/pt/fullscreen#search-and-review-the-conversation) para saber como pesquisar e copiar.297Se a exibição piscar ou a posição de rolagem pular enquanto Claude está trabalhando, mude para o [modo de renderização em tela cheia](/pt/fullscreen). Ele desenha em uma tela separada que o terminal reserva para aplicativos em tela cheia em vez de anexar ao seu scrollback normal, o que mantém o uso de memória plano e adiciona suporte a mouse para rolagem e seleção. Neste modo você rola com o mouse ou PageUp dentro do Claude Code em vez de com o scrollback nativo do seu terminal; consulte a [página de tela cheia](/pt/fullscreen#search-and-review-the-conversation) para saber como pesquisar e copiar.


317</CodeGroup>317</CodeGroup>

318 318 

319<h2 id="paste-large-content">319<h2 id="paste-large-content">

320 Paste large content320 Colar conteúdo grande

321</h2>321</h2>

322 322 

323Quando você cola mais de 10.000 caracteres no prompt, Claude Code reduz a entrada para um placeholder `[Pasted text]` para que a caixa de entrada permaneça utilizável. O conteúdo completo ainda é enviado para Claude quando você envia.323Quando você cola mais de 10.000 caracteres no prompt, Claude Code reduz a entrada para um placeholder `[Pasted text]` para que a caixa de entrada permaneça utilizável. O conteúdo completo ainda é enviado para Claude quando você envia.


335Pressionar Enter ainda envia seu prompt no modo INSERT, diferentemente do Vim padrão. Use `o` ou `O` no modo NORMAL, ou Ctrl+J, para inserir uma quebra de linha em vez disso.335Pressionar Enter ainda envia seu prompt no modo INSERT, diferentemente do Vim padrão. Use `o` ou `O` no modo NORMAL, ou Ctrl+J, para inserir uma quebra de linha em vez disso.

336 336 

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

338 Related resources338 Recursos relacionados

339</h2>339</h2>

340 340 

341* [Interactive mode](/pt/interactive-mode): referência completa de atalhos de teclado e a tabela de teclas Vim341* [Interactive mode](/pt/interactive-mode): referência completa de atalhos de teclado e a tabela de teclas Vim

Details

6 6 

7> Saiba como Claude Code pode se integrar com vários serviços de terceiros e infraestrutura para atender aos requisitos de implantação empresarial.7> Saiba como Claude Code pode se integrar com vários serviços de terceiros e infraestrutura para atender aos requisitos de implantação empresarial.

8 8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

9As organizações podem implantar Claude Code através da Anthropic diretamente ou através de um provedor de nuvem. Esta página ajuda você a escolher a configuração correta.79As organizações podem implantar Claude Code através da Anthropic diretamente ou através de um provedor de nuvem. Esta página ajuda você a escolher a configuração correta.

10 80 

81<ContactSalesCard surface="third_party_overview" />

82 

11<h2 id="compare-deployment-options">83<h2 id="compare-deployment-options">

12 Comparar opções de implantação84 Comparar opções de implantação

13</h2>85</h2>


271 Fixar versões de modelo para provedores de nuvem343 Fixar versões de modelo para provedores de nuvem

272</h3>344</h3>

273 345 

274Se você implantar através de [Bedrock](/pt/amazon-bedrock), [Vertex AI](/pt/google-vertex-ai), [Foundry](/pt/microsoft-foundry), ou [Claude Platform on AWS](/pt/claude-platform-on-aws), fixe versões de modelo específicas usando `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, e `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Sem fixação, os aliases de modelo resolvem para a versão mais recente, o que pode não estar ainda ativado em sua conta quando a Anthropic lança uma atualização. Fixar permite que você controle quando seus usuários passam para um novo modelo. Veja [Configuração de modelo](/pt/model-config#pin-models-for-third-party-deployments) para o que cada provedor faz quando a versão mais recente não está disponível.346Se você implantar através de [Bedrock](/pt/amazon-bedrock), [Vertex AI](/pt/google-vertex-ai), [Foundry](/pt/microsoft-foundry), ou [Claude Platform on AWS](/pt/claude-platform-on-aws), fixe versões de modelo específicas usando `ANTHROPIC_DEFAULT_FABLE_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, e `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Sem fixação, os aliases de modelo resolvem para o padrão integrado de Claude Code para esse provedor, o que pode ficar atrás da versão mais recente e pode ainda não estar ativado em sua conta. Fixar permite que você controle quando seus usuários passam para um novo modelo. Veja [Configuração de modelo](/pt/model-config#pin-models-for-third-party-deployments) para o que cada provedor faz quando o padrão não está disponível.

275 347 

276<h3 id="configure-security-policies">348<h3 id="configure-security-policies">

277 Configurar políticas de segurança349 Configurar políticas de segurança

Details

44| `TaskOutput` | (Descontinuado) Recupera saída de uma tarefa em segundo plano. Prefira `Read` no caminho do arquivo de saída da tarefa | Não |44| `TaskOutput` | (Descontinuado) Recupera saída de uma tarefa em segundo plano. Prefira `Read` no caminho do arquivo de saída da tarefa | Não |

45| `TaskStop` | Mata uma tarefa em segundo plano em execução por ID | Não |45| `TaskStop` | Mata uma tarefa em segundo plano em execução por ID | Não |

46| `TaskUpdate` | Atualiza status da tarefa, dependências, detalhes ou deleta tarefas | Não |46| `TaskUpdate` | Atualiza status da tarefa, dependências, detalhes ou deleta tarefas | Não |

47| `TeamCreate` | Cria uma [equipe de agentes](/pt/agent-teams) com múltiplos membros. Disponível apenas quando `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` está definido | Não |

48| `TeamDelete` | Dissolve uma equipe de agentes e limpa processos de membros. Disponível apenas quando `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` está definido | Não |

49| `TodoWrite` | {/* min-version: 2.1.142 */}Gerencia a lista de verificação de tarefas da sessão. Desabilitado por padrão a partir de v2.1.142 em favor de `TaskCreate`, `TaskGet`, `TaskList` e `TaskUpdate`. Defina `CLAUDE_CODE_ENABLE_TASKS=0` para reabilitar | Não |47| `TodoWrite` | {/* min-version: 2.1.142 */}Gerencia a lista de verificação de tarefas da sessão. Desabilitado por padrão a partir de v2.1.142 em favor de `TaskCreate`, `TaskGet`, `TaskList` e `TaskUpdate`. Defina `CLAUDE_CODE_ENABLE_TASKS=0` para reabilitar | Não |

50| `ToolSearch` | Pesquisa e carrega ferramentas diferidas quando [pesquisa de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está ativada | Não |48| `ToolSearch` | Pesquisa e carrega ferramentas diferidas quando [pesquisa de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está ativada | Não |

51| `WaitForMcpServers` | {/* min-version: 2.1.142 */}Aguarda um ou mais [servidores MCP](/pt/mcp) que ainda estão se conectando em segundo plano, para que uma solicitação possa usar suas ferramentas sem reiniciar a sessão. Claude a chama quando um servidor necessário ainda não está conectado. Aparece apenas quando [pesquisa de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está desabilitada, já que `ToolSearch` lida com a espera quando está ativada | Não |49| `WaitForMcpServers` | {/* min-version: 2.1.142 */}Aguarda um ou mais [servidores MCP](/pt/mcp) que ainda estão se conectando em segundo plano, para que uma solicitação possa usar suas ferramentas sem reiniciar a sessão. Claude a chama quando um servidor necessário ainda não está conectado. Aparece apenas quando [pesquisa de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está desabilitada, já que `ToolSearch` lida com a espera quando está ativada | Não |


70Todos esses aceitam o mesmo formato de regra, `ToolName(specifier)`. O especificador depende da ferramenta, e várias ferramentas compartilham um formato:68Todos esses aceitam o mesmo formato de regra, `ToolName(specifier)`. O especificador depende da ferramenta, e várias ferramentas compartilham um formato:

71 69 

72| Formato de regra | Aplica-se a | Detalhes |70| Formato de regra | Aplica-se a | Detalhes |

73| :----------------------------- | :------------------------ | :---------------------------------------------------------------------------- |71| :----------------------------- | :------------------------ | :------------------------------------------------------------------------------------ |

74| `Bash(npm run *)` | Bash, Monitor | [Correspondência de padrão de comando](/pt/permissions#bash) |72| `Bash(npm run *)` | Bash, Monitor | [Correspondência de padrão de comando](/pt/permissions#bash) |

75| `PowerShell(Get-ChildItem *)` | PowerShell | [Correspondência de padrão de comando](/pt/permissions#powershell) |73| `PowerShell(Get-ChildItem *)` | PowerShell | [Correspondência de padrão de comando](/pt/permissions#powershell) |

76| `Read(~/secrets/**)` | Read, Grep, Glob, LSP | [Correspondência de padrão de caminho](/pt/permissions#read-and-edit) |74| `Read(~/secrets/**)` | Read, Grep, Glob, LSP | [Correspondência de padrão de caminho](/pt/permissions#read-and-edit) |

77| `Edit(/src/**)` | Edit, Write, NotebookEdit | [Correspondência de padrão de caminho](/pt/permissions#read-and-edit) |75| `Edit(/src/**)` | Edit, Write, NotebookEdit | [Correspondência de padrão de caminho](/pt/permissions#read-and-edit) |

78| `Skill(deploy *)` | Skill | [Correspondência de nome de skill](/pt/skills#restrict-claude's-skill-access) |76| `Skill(deploy *)` | Skill | [Correspondência de nome de skill](/pt/skills#restrict-claude%E2%80%99s-skill-access) |

79| `Agent(Explore)` | Agent | [Correspondência de tipo de subagent](/pt/permissions#agent-subagents) |77| `Agent(Explore)` | Agent | [Correspondência de tipo de subagent](/pt/permissions#agent-subagents) |

80| `WebFetch(domain:example.com)` | WebFetch | [Correspondência de domínio](/pt/permissions#webfetch) |78| `WebFetch(domain:example.com)` | WebFetch | [Correspondência de domínio](/pt/permissions#webfetch) |

81| `WebSearch` | WebSearch | Sem especificador; permitir ou negar a ferramenta como um todo |79| `WebSearch` | WebSearch | Sem especificador; permitir ou negar a ferramenta como um todo |


186* Ir para a definição de um símbolo184* Ir para a definição de um símbolo

187* Encontrar todas as referências a um símbolo185* Encontrar todas as referências a um símbolo

188* Obter informações de tipo em uma posição186* Obter informações de tipo em uma posição

189* Listar símbolos em um arquivo ou workspace187* Listar símbolos em um arquivo

188* Pesquisar um símbolo por nome em todo o workspace

190* Encontrar implementações de uma interface189* Encontrar implementações de uma interface

191* Rastrear hierarquias de chamadas190* Rastrear hierarquias de chamadas

192 191 


305* Respostas são armazenadas em cache por 15 minutos, portanto buscas repetidas da mesma URL retornam rapidamente.304* Respostas são armazenadas em cache por 15 minutos, portanto buscas repetidas da mesma URL retornam rapidamente.

306* Quando uma URL redireciona para um host diferente, WebFetch retorna um resultado de texto que nomeia a URL original e o alvo de redirecionamento em vez de segui-lo. Claude então busca a nova URL com uma segunda chamada WebFetch.305* Quando uma URL redireciona para um host diferente, WebFetch retorna um resultado de texto que nomeia a URL original e o alvo de redirecionamento em vez de segui-lo. Claude então busca a nova URL com uma segunda chamada WebFetch.

307 306 

308Nos modos de permissão padrão e `acceptEdits`, WebFetch solicita a primeira vez que atinge um novo domínio. Para permitir um domínio antecipadamente sem um prompt, adicione uma regra de permissão como `WebFetch(domain:example.com)`. Os modos de permissão `auto` e `bypassPermissions` [permission modes](/pt/permissions#permission-modes) pulam o prompt inteiramente.307Nos modos de permissão padrão e `acceptEdits`, WebFetch solicita a primeira vez que atinge um novo domínio, exceto por um conjunto integrado de domínios de documentação pré-aprovados que buscam sem um prompt. Para permitir outro domínio antecipadamente sem um prompt, adicione uma regra de permissão como `WebFetch(domain:example.com)`. Os modos de permissão `auto` e `bypassPermissions` [permission modes](/pt/permissions#permission-modes) pulam o prompt inteiramente.

308 

309Uma regra explícita `WebFetch(domain:...)` em `deny`, `ask` ou `allow` tem precedência sobre o conjunto pré-aprovado, portanto você pode bloquear um domínio pré-aprovado ou exigir um prompt para ele.

309 310 

310WebFetch define um cabeçalho `User-Agent` começando com `Claude-User` e um cabeçalho `Accept` que prefere Markdown sobre HTML para que servidores que suportam negociação de conteúdo possam retornar Markdown diretamente. [Sandbox](/pt/sandboxing) regras de rede são configuradas separadamente, portanto um domínio que você quer que um processo em sandbox alcance ainda precisa de uma regra de permissão de sandbox explícita.311WebFetch define um cabeçalho `User-Agent` começando com `Claude-User` e um cabeçalho `Accept` que prefere Markdown sobre HTML para que servidores que suportam negociação de conteúdo possam retornar Markdown diretamente. [Sandbox](/pt/sandboxing) regras de rede são configuradas separadamente, portanto um domínio que você quer que um processo em sandbox alcance ainda precisa de uma regra de permissão de sandbox explícita.

311 312 


313 Comportamento da ferramenta WebSearch314 Comportamento da ferramenta WebSearch

314</h2>315</h2>

315 316 

316WebSearch executa uma consulta contra o backend de [pesquisa na web](/pt/docs/en/agents-and-tools/tool-use/web-search-tool) da Anthropic e retorna títulos e URLs de resultados. Ela não busca as páginas de resultado. Para ler uma página que Claude encontra em resultados de pesquisa, ele segue com [WebFetch](#webfetch-tool-behavior).317WebSearch executa uma consulta contra o backend de [pesquisa na web](https://platform.claude.com/docs/pt/agents-and-tools/tool-use/web-search-tool) da Anthropic e retorna títulos e URLs de resultados. Ela não busca as páginas de resultado. Para ler uma página que Claude encontra em resultados de pesquisa, ele segue com [WebFetch](#webfetch-tool-behavior).

317 318 

318A ferramenta pode emitir até oito pesquisas de backend por chamada, refinando a pesquisa internamente antes de retornar resultados. Claude pode escopar resultados com `allowed_domains` para incluir apenas certos hosts, ou `blocked_domains` para excluí-los. As duas listas não podem ser combinadas em uma única chamada.319A ferramenta pode emitir até oito pesquisas de backend por chamada, refinando a pesquisa internamente antes de retornar resultados. Claude pode escopar resultados com `allowed_domains` para incluir apenas certos hosts, ou `blocked_domains` para excluí-los. As duas listas não podem ser combinadas em uma única chamada.

319 320 


349 350 

350Claude fornece um resumo conversacional. Para nomes exatos de ferramentas MCP, execute `/mcp`.351Claude fornece um resumo conversacional. Para nomes exatos de ferramentas MCP, execute `/mcp`.

351 352 

353<Note>

354 A [ferramenta advisor](/pt/advisor) é uma [ferramenta de servidor](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) que a API executa, em vez de uma ferramenta que Claude Code implementa. Ela não tem um nome que você possa referenciar em regras de permissão ou correspondências de hook.

355</Note>

356 

352<h2 id="see-also">357<h2 id="see-also">

353 Veja também358 Veja também

354</h2>359</h2>

Details

24| `TLS connect error` ou `SSL/TLS secure channel` | [Atualize os certificados CA](#tls-or-ssl-connection-errors) |24| `TLS connect error` ou `SSL/TLS secure channel` | [Atualize os certificados CA](#tls-or-ssl-connection-errors) |

25| `Failed to fetch version` ou não consegue alcançar o servidor de download | [Verifique as configurações de rede e proxy](#check-network-connectivity) |25| `Failed to fetch version` ou não consegue alcançar o servidor de download | [Verifique as configurações de rede e proxy](#check-network-connectivity) |

26| `irm is not recognized` ou `&& is not valid` | [Use o comando correto para seu shell](#wrong-install-command-on-windows) |26| `irm is not recognized` ou `&& is not valid` | [Use o comando correto para seu shell](#wrong-install-command-on-windows) |

27| `Cask 'claude-code' is unavailable: No Cask with this name exists` | [Atualize o Homebrew](#homebrew-cask-unavailable-or-outdated) |

27| `'bash' is not recognized as the name of a cmdlet` | [Use o comando do instalador do Windows](#wrong-install-command-on-windows) |28| `'bash' is not recognized as the name of a cmdlet` | [Use o comando do instalador do Windows](#wrong-install-command-on-windows) |

28| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [Instale um shell](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |29| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [Instale um shell](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |

29| `Claude Code does not support 32-bit Windows` | [Abra o Windows PowerShell, não a entrada x86](#claude-code-does-not-support-32-bit-windows) |30| `Claude Code does not support 32-bit Windows` | [Abra o Windows PowerShell, não a entrada x86](#claude-code-does-not-support-32-bit-windows) |


61curl -sI https://downloads.claude.ai/claude-code-releases/latest62curl -sI https://downloads.claude.ai/claude-code-releases/latest

62```63```

63 64 

65No PowerShell, execute `curl.exe -sI` em vez disso. O PowerShell cria um alias de `curl` para `Invoke-WebRequest`, que rejeita os sinalizadores `-sI`.

66 

64Uma linha `HTTP/2 200` significa que você alcançou o servidor. Se você vir nenhuma saída, `Could not resolve host`, ou um tempo limite de conexão, sua rede está bloqueando a conexão. Causas comuns:67Uma linha `HTTP/2 200` significa que você alcançou o servidor. Se você vir nenhuma saída, `Could not resolve host`, ou um tempo limite de conexão, sua rede está bloqueando a conexão. Causas comuns:

65 68 

66* Firewalls corporativos ou proxies bloqueando `downloads.claude.ai`69* Firewalls corporativos ou proxies bloqueando `downloads.claude.ai`


95 98 

96Se a instalação foi bem-sucedida mas você recebe um erro `command not found` ou `not recognized` ao executar `claude`, o diretório de instalação não está em seu PATH. Seu shell procura por programas em diretórios listados em PATH, e o instalador coloca `claude` em `~/.local/bin/claude` no macOS/Linux ou `%USERPROFILE%\.local\bin\claude.exe` no Windows.99Se a instalação foi bem-sucedida mas você recebe um erro `command not found` ou `not recognized` ao executar `claude`, o diretório de instalação não está em seu PATH. Seu shell procura por programas em diretórios listados em PATH, e o instalador coloca `claude` em `~/.local/bin/claude` no macOS/Linux ou `%USERPROFILE%\.local\bin\claude.exe` no Windows.

97 100 

101<Note>

102 A [extensão VS Code](/pt/vs-code) não coloca `claude` neste local. Ela agrupa uma cópia privada da CLI dentro do diretório da extensão para seu próprio painel de chat e não a adiciona ao PATH. Se você tiver instalado apenas a extensão, `~/.local/bin/claude` não existirá. Execute a [instalação autônoma](/pt/setup) para usar `claude` a partir de um terminal, depois continue abaixo.

103</Note>

104 

98Verifique se o diretório de instalação está em seu PATH listando suas entradas de PATH e filtrando por `local/bin`:105Verifique se o diretório de instalação está em seu PATH listando suas entradas de PATH e filtrando por `local/bin`:

99 106 

100<Tabs>107<Tabs>


188 ls -la ~/.local/bin/claude195 ls -la ~/.local/bin/claude

189 ```196 ```

190 197 

198 Se algum comando `ls` imprimir `No such file or directory`, isso não é um erro. Significa que nada está instalado naquele local, então passe para a próxima verificação.

199 

191 ```bash theme={null}200 ```bash theme={null}

192 ls -la ~/.claude/local/201 ls -la ~/.claude/local/

193 ```202 ```


390 winget install Anthropic.ClaudeCode399 winget install Anthropic.ClaudeCode

391 ```400 ```

392 401 

402<h3 id="homebrew-cask-unavailable-or-outdated">

403 Homebrew cask unavailable or outdated

404</h3>

405 

406Homebrew relata `Error: Cask 'claude-code' is unavailable: No Cask with this name exists` quando sua cópia local do índice de cask do Homebrew é anterior à publicação do cask. Atualize o índice e tente novamente:

407 

408```bash theme={null}

409brew update

410brew install --cask claude-code

411```

412 

413Se Homebrew instalar uma versão mais antiga do Claude Code do que você espera, o mesmo índice desatualizado é geralmente a causa. O cask `claude-code` rastreia o canal estável e é tipicamente cerca de uma semana atrás da versão mais recente; para a versão mais recente execute `brew install --cask claude-code@latest` em vez disso. Consulte [Configure release channel](/pt/setup#configure-release-channel) para a diferença entre os dois casks.

414 

393<h3 id="tls-or-ssl-connection-errors">415<h3 id="tls-or-ssl-connection-errors">

394 TLS or SSL connection errors416 TLS or SSL connection errors

395</h3>417</h3>


592 614 

593Se seu Git estiver instalado em outro lugar, encontre o caminho executando `where.exe git` no PowerShell e use o caminho `bin\bash.exe` desse diretório.615Se seu Git estiver instalado em outro lugar, encontre o caminho executando `where.exe git` no PowerShell e use o caminho `bin\bash.exe` desse diretório.

594 616 

617**Se o caminho estiver correto e o arquivo existir** mas Claude Code ainda relatar que não foi encontrado, o software de segurança de endpoint como AppLocker, políticas de restrição de software de Política de Grupo ou agentes EDR podem estar interferindo. Em versões anteriores a v2.1.116, Claude Code gerava um processo filho (`cmd.exe`) para verificar o caminho, que essas políticas podem bloquear — um sinal comum é que `cmd.exe /c dir "C:\Program Files\Git\bin\bash.exe"` funciona quando você o executa diretamente no PowerShell mas falha silenciosamente quando iniciado por `claude.exe`.

618 

619Claude Code v2.1.116 e posterior verificam o sistema de arquivos diretamente, então atualize primeiro. Se o erro persistir em uma versão atual, peça à sua equipe de TI para colocar na lista de permissões `claude.exe` e os processos que ele gera, incluindo `cmd.exe` e `bash.exe`, em sua política de proteção de endpoint.

620 

595<h3 id="claude-code-does-not-support-32-bit-windows">621<h3 id="claude-code-does-not-support-32-bit-windows">

596 Claude Code does not support 32-bit Windows622 Claude Code does not support 32-bit Windows

597</h3>623</h3>

Details

361. Use `/compact` regularmente para reduzir o tamanho do contexto361. Use `/compact` regularmente para reduzir o tamanho do contexto

372. Feche e reinicie Claude Code entre tarefas principais372. Feche e reinicie Claude Code entre tarefas principais

383. Considere adicionar grandes diretórios de compilação ao seu arquivo `.gitignore`383. Considere adicionar grandes diretórios de compilação ao seu arquivo `.gitignore`

394. Reinicie com [`claude --safe-mode`](/pt/cli-reference#cli-flags) para verificar se um plugin, servidor MCP ou hook é a origem. Isso desabilita todas as personalizações para a sessão; se o uso diminuir, veja [Debug your configuration](/pt/debug-your-config#test-against-a-clean-configuration) para encontrar qual é

39 40 

40Se o uso de memória permanecer alto após essas etapas, execute `/heapdump` para escrever um snapshot de heap JavaScript e um detalhamento de memória para `~/Desktop`. No Linux sem uma pasta Desktop, os arquivos são escritos em seu diretório home.41Se o uso de memória permanecer alto após essas etapas, execute `/heapdump` para escrever um snapshot de heap JavaScript e um detalhamento de memória para `~/Desktop`. No Linux sem uma pasta Desktop, os arquivos são escritos em seu diretório home.

41 42 


65 66 

66Reiniciar não perde sua conversa. Execute `claude --resume` no mesmo diretório para retomar a sessão.67Reiniciar não perde sua conversa. Execute `claude --resume` no mesmo diretório para retomar a sessão.

67 68 

68<h3 id="garbled-or-corrupted-text-in-an-editor-s-integrated-terminal">69<h3 id="garbled-or-corrupted-text-in-an-editors-integrated-terminal">

69 Texto garbled ou corrompido no terminal integrado de um editor70 Texto garbled ou corrompido no terminal integrado de um editor

70</h3>71</h3>

71 72 


1303. **Use Windows nativo em vez disso**: considere executar Claude Code nativamente no Windows em vez de através de WSL, para melhor desempenho do sistema de arquivos.1313. **Use Windows nativo em vez disso**: considere executar Claude Code nativamente no Windows em vez de através de WSL, para melhor desempenho do sistema de arquivos.

131 132 

132<h2 id="get-more-help">133<h2 id="get-more-help">

133 Get more help134 Obtenha mais ajuda

134</h2>135</h2>

135 136 

136Se você está experimentando problemas não cobertos aqui:137Se você está experimentando problemas não cobertos aqui:

Details

62A transcrição é ajustada para vocabulário de codificação em ambos os modos. Termos de desenvolvimento comuns como `regex`, `OAuth`, `JSON` e `localhost` são reconhecidos corretamente, e o nome do seu projeto atual e o nome da ramificação git são adicionados automaticamente como dicas de reconhecimento.62A transcrição é ajustada para vocabulário de codificação em ambos os modos. Termos de desenvolvimento comuns como `regex`, `OAuth`, `JSON` e `localhost` são reconhecidos corretamente, e o nome do seu projeto atual e o nome da ramificação git são adicionados automaticamente como dicas de reconhecimento.

63 63 

64<h2 id="hold-to-record">64<h2 id="hold-to-record">

65 Hold to record65 Manter pressionado para gravar

66</h2>66</h2>

67 67 

68O modo de manutenção é push-to-talk: a gravação é executada enquanto você mantém a tecla pressionada e para quando você a solta. Este é o modo padrão.68O modo de manutenção é push-to-talk: a gravação é executada enquanto você mantém a tecla pressionada e para quando você a solta. Este é o modo padrão.


207 Veja também207 Veja também

208</h2>208</h2>

209 209 

210* [Customize keyboard shortcuts](/pt/keybindings): revinculação `voice:pushToTalk` e outras ações de teclado CLI210* [Personalize atalhos de teclado](/pt/keybindings): revinculação `voice:pushToTalk` e outras ações de teclado CLI

211* [Configure settings](/pt/settings): referência completa para `voice`, `language` e outras chaves de configurações211* [Configure configurações](/pt/settings): referência completa para `voice`, `language` e outras chaves de configurações

212* [Interactive mode](/pt/interactive-mode): atalhos de teclado, modos de entrada e controles de sessão212* [Modo interativo](/pt/interactive-mode): atalhos de teclado, modos de entrada e controles de sessão

213* [Commands](/pt/commands): referência para `/voice`, `/config` e todos os outros comandos213* [Comandos](/pt/commands): referência para `/voice`, `/config` e todos os outros comandos

vs-code.md +45 −19

Details

19Antes de instalar, certifique-se de que você tem:19Antes de instalar, certifique-se de que você tem:

20 20 

21* VS Code 1.98.0 ou superior21* VS Code 1.98.0 ou superior

22* Uma conta Anthropic (você fará login quando abrir a extensão pela primeira vez). Se você estiver usando um provedor de terceiros como Amazon Bedrock ou Google Vertex AI, consulte [Use third-party providers](#use-third-party-providers) em vez disso.22* Uma conta Anthropic: qualquer assinatura paga do Claude (Pro, Max, Team ou Enterprise) ou uma conta Claude Console funciona, e nenhuma chave de API é necessária. Você fará [login](/pt/authentication#log-in-to-claude-code) com essa conta quando abrir a extensão pela primeira vez. Se você acessar Claude através de um provedor de terceiros como Amazon Bedrock ou Google Vertex AI, consulte [Use third-party providers](#use-third-party-providers) para instruções de configuração.

23 23 

24<Tip>24<Tip>

25 A extensão inclui a CLI (interface de linha de comando), que você pode acessar do terminal integrado do VS Code para recursos avançados. Consulte [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) para detalhes.25 A extensão inclui sua própria cópia da CLI (interface de linha de comando) para o painel de chat. Para executar `claude` no terminal integrado do VS Code, você também precisa da [instalação da CLI autônoma](/pt/setup). Consulte [VS Code extension vs. Claude Code CLI](#vs-code-extension-vs-claude-code-cli) para detalhes.

26</Tip>26</Tip>

27 27 

28<h2 id="install-the-extension">28<h2 id="install-the-extension">


36 36 

37Ou no VS Code, pressione `Cmd+Shift+X` (Mac) ou `Ctrl+Shift+X` (Windows/Linux) para abrir a visualização de Extensões, procure por "Claude Code" e clique em **Instalar**.37Ou no VS Code, pressione `Cmd+Shift+X` (Mac) ou `Ctrl+Shift+X` (Windows/Linux) para abrir a visualização de Extensões, procure por "Claude Code" e clique em **Instalar**.

38 38 

39A extensão também é instalada em outros forks do VS Code como Devin Desktop ou Kiro. Procure por "Claude Code" na visualização de Extensões do editor, ou instale a partir do [registro Open VSX](https://open-vsx.org/extension/Anthropic/claude-code). Se o seu editor não conseguir instalar a extensão, execute `claude` no seu terminal integrado. A [CLI](/pt/quickstart) funciona em qualquer terminal.39A extensão também é instalada em outros forks do VS Code como Devin Desktop ou Kiro. Procure por "Claude Code" na visualização de Extensões do editor, ou instale a partir do [registro Open VSX](https://open-vsx.org/extension/Anthropic/claude-code). Se o seu editor não conseguir instalar a extensão, [instale a CLI](/pt/quickstart) e execute `claude` no seu terminal integrado. A CLI funciona em qualquer terminal.

40 40 

41<Note>Se a extensão não aparecer após a instalação, reinicie o VS Code ou execute "Developer: Reload Window" na Paleta de Comandos.</Note>41<Note>Se a extensão não aparecer após a instalação, reinicie o VS Code ou execute "Developer: Reload Window" na Paleta de Comandos.</Note>

42 42 


60 * **Command Palette**: `Cmd+Shift+P` (Mac) ou `Ctrl+Shift+P` (Windows/Linux), digite "Claude Code" e selecione uma opção como "Open in New Tab"60 * **Command Palette**: `Cmd+Shift+P` (Mac) ou `Ctrl+Shift+P` (Windows/Linux), digite "Claude Code" e selecione uma opção como "Open in New Tab"

61 * **Status Bar**: clique em **✱ Claude Code** no canto inferior direito da janela. Isso funciona mesmo quando nenhum arquivo está aberto.61 * **Status Bar**: clique em **✱ Claude Code** no canto inferior direito da janela. Isso funciona mesmo quando nenhum arquivo está aberto.

62 62 

63 Você pode arrastar o painel Claude para reposicioná-lo em qualquer lugar do VS Code. Consulte [Customize your workflow](#customize-your-workflow) para detalhes.63 Você pode arrastar o painel Claude para reposicioná-lo em qualquer lugar do VS Code. Consulte [Personalize seu fluxo de trabalho](#customize-your-workflow) para detalhes.

64 </Step>64 </Step>

65 65 

66 <Step title="Faça login">66 <Step title="Faça login">


90 </Step>90 </Step>

91</Steps>91</Steps>

92 92 

93Para mais ideias sobre o que você pode fazer com Claude Code, consulte [Common workflows](/pt/common-workflows).93Para mais ideias sobre o que você pode fazer com Claude Code, consulte [Fluxos de trabalho comuns](/pt/common-workflows).

94 94 

95<Tip>95<Tip>

96 Execute "Claude Code: Open Walkthrough" na Paleta de Comandos para um tour guiado dos conceitos básicos.96 Execute "Claude Code: Open Walkthrough" na Paleta de Comandos para um tour guiado dos conceitos básicos.


131 131 

132Clique no botão **Session history** na parte superior do painel Claude Code para acessar seu histórico de conversas. Você pode pesquisar por palavra-chave ou navegar por tempo (Today, Yesterday, Last 7 days, etc.). Clique em qualquer conversa para retomá-la com o histórico completo de mensagens. Novas sessões recebem títulos gerados por IA com base em sua primeira mensagem. Passe o mouse sobre uma sessão para revelar ações de renomear e remover: renomeie para dar um título descritivo, ou remova para deletá-la da lista. Para mais sobre retomar sessões, consulte [Manage sessions](/pt/sessions).132Clique no botão **Session history** na parte superior do painel Claude Code para acessar seu histórico de conversas. Você pode pesquisar por palavra-chave ou navegar por tempo (Today, Yesterday, Last 7 days, etc.). Clique em qualquer conversa para retomá-la com o histórico completo de mensagens. Novas sessões recebem títulos gerados por IA com base em sua primeira mensagem. Passe o mouse sobre uma sessão para revelar ações de renomear e remover: renomeie para dar um título descritivo, ou remova para deletá-la da lista. Para mais sobre retomar sessões, consulte [Manage sessions](/pt/sessions).

133 133 

134<h3 id="resume-remote-sessions-from-claude-ai">134<h3 id="resume-cloud-sessions-from-claude-ai">

135 Resume remote sessions from Claude.ai135 Resume cloud sessions from Claude.ai

136</h3>136</h3>

137 137 

138Se você usar [Claude Code on the web](/pt/claude-code-on-the-web), você pode retomar essas sessões remotas diretamente no VS Code. Isso requer fazer login com **Claude.ai Subscription**, não Anthropic Console.138Se você usar [Claude Code on the web](/pt/claude-code-on-the-web), você pode retomar essas sessões remotas diretamente no VS Code. Isso requer fazer login com **Claude.ai Subscription**, não Anthropic Console.


155 Apenas sessões web iniciadas com um repositório GitHub aparecem na aba Remote. Retomar carrega o histórico de conversas localmente; as alterações não são sincronizadas de volta para claude.ai.155 Apenas sessões web iniciadas com um repositório GitHub aparecem na aba Remote. Retomar carrega o histórico de conversas localmente; as alterações não são sincronizadas de volta para claude.ai.

156</Note>156</Note>

157 157 

158<h3 id="check-account-and-usage">

159 Check account and usage

160</h3>

161 

162Execute `/usage` no menu de comandos para abrir o diálogo Account & usage. Ele mostra sua conta conectada, plano e barras de uso para a sessão atual e semana com quanto tempo falta até cada limite ser redefinido.

163 

164O diálogo também detalha o que está contribuindo para seus limites de plano. Ele sinaliza comportamentos que representam 10% ou mais do uso recente, como falhas de cache, contexto longo e sessões com muitos subagentes ou altamente paralelas, cada uma com uma dica para reduzi-la. Tabelas de atribuição mostram quanto uso veio de cada skill, subagente, plugin e servidor MCP. Requer Claude Code v2.1.174 ou posterior.

165 

166Use o alternador Day e Week para alternar entre as últimas 24 horas e os últimos 7 dias. Os números são aproximados e calculados a partir de sessões locais nesta máquina, portanto o uso de outros dispositivos ou claude.ai não está incluído. Para mais sobre rastreamento e redução de uso, consulte [Track your costs](/pt/costs#track-your-costs).

167 

158<h2 id="customize-your-workflow">168<h2 id="customize-your-workflow">

159 Customize your workflow169 Personalize seu fluxo de trabalho

160</h2>170</h2>

161 171 

162Depois que você estiver funcionando, você pode reposicionar o painel Claude, executar múltiplas sessões ou alternar para modo terminal.172Depois que você estiver funcionando, você pode reposicionar o painel Claude, executar múltiplas sessões ou alternar para modo terminal.

163 173 

164<h3 id="choose-where-claude-lives">174<h3 id="choose-where-claude-lives">

165 Choose where Claude lives175 Escolha onde Claude fica

166</h3>176</h3>

167 177 

168Você pode arrastar o painel Claude para reposicioná-lo em qualquer lugar do VS Code. Pegue a aba ou barra de título do painel e arraste para:178Você pode arrastar o painel Claude para reposicioná-lo em qualquer lugar do VS Code. Pegue a aba ou barra de título do painel e arraste para:


176</Tip>186</Tip>

177 187 

178<h3 id="run-multiple-conversations">188<h3 id="run-multiple-conversations">

179 Run multiple conversations189 Execute múltiplas conversas

180</h3>190</h3>

181 191 

182Use **Open in New Tab** ou **Open in New Window** na Paleta de Comandos para iniciar conversas adicionais. Cada conversa mantém seu próprio histórico e contexto, permitindo que você trabalhe em diferentes tarefas em paralelo.192Use **Open in New Tab** ou **Open in New Window** na Paleta de Comandos para iniciar conversas adicionais. Cada conversa mantém seu próprio histórico e contexto, permitindo que você trabalhe em diferentes tarefas em paralelo.


184Ao usar abas, um pequeno ponto colorido no ícone spark indica status: azul significa que uma solicitação de permissão está pendente, laranja significa que Claude terminou enquanto a aba estava oculta.194Ao usar abas, um pequeno ponto colorido no ícone spark indica status: azul significa que uma solicitação de permissão está pendente, laranja significa que Claude terminou enquanto a aba estava oculta.

185 195 

186<h3 id="switch-to-terminal-mode">196<h3 id="switch-to-terminal-mode">

187 Switch to terminal mode197 Alterne para modo terminal

188</h3>198</h3>

189 199 

190Por padrão, a extensão abre um painel de chat gráfico. Se você preferir a interface estilo CLI, abra a [Use Terminal setting](vscode://settings/claudeCode.useTerminal) e marque a caixa.200Por padrão, a extensão abre um painel de chat gráfico. Se você preferir a interface estilo CLI, abra a [Use Terminal setting](vscode://settings/claudeCode.useTerminal) e marque a caixa.


366 VS Code extension vs. Claude Code CLI376 VS Code extension vs. Claude Code CLI

367</h2>377</h2>

368 378 

369Claude Code está disponível tanto como uma extensão VS Code (painel gráfico) quanto como uma CLI (interface de linha de comando no terminal). Alguns recursos estão disponíveis apenas na CLI. Se você precisar de um recurso apenas da CLI, execute `claude` no terminal integrado do VS Code.379Claude Code está disponível tanto como uma extensão VS Code (painel gráfico) quanto como uma CLI (interface de linha de comando no terminal). Alguns recursos estão disponíveis apenas na CLI. Se você precisar de um recurso apenas da CLI, execute `claude` no terminal integrado do VS Code. Isso requer a [instalação da CLI autônoma](/pt/setup): a extensão não adiciona `claude` ao seu PATH. Consulte [Executar CLI no VS Code](#run-cli-in-vs-code).

370 380 

371| Feature | CLI | VS Code Extension |381| Feature | CLI | VS Code Extension |

372| ------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |382| ------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |


394 404 

395Para usar a CLI enquanto permanece no VS Code, abra o terminal integrado (`` Ctrl+` `` no Windows/Linux ou `` Cmd+` `` no Mac) e execute `claude`. A CLI se integra automaticamente ao seu IDE para recursos como visualização de diff e compartilhamento de diagnósticos.405Para usar a CLI enquanto permanece no VS Code, abra o terminal integrado (`` Ctrl+` `` no Windows/Linux ou `` Cmd+` `` no Mac) e execute `claude`. A CLI se integra automaticamente ao seu IDE para recursos como visualização de diff e compartilhamento de diagnósticos.

396 406 

397Se usar um terminal externo, execute `/ide` dentro de Claude Code para conectá-lo ao VS Code.407Instalar a extensão não coloca `claude` no PATH do seu shell. A extensão agrupa uma cópia privada da CLI para seu painel de chat, mas digitar `claude` em um terminal requer a [instalação da CLI autônoma](/pt/setup). Execute a instalação uma vez e os comandos nesta página, incluindo `claude mcp add` e `claude --resume`, funcionam em qualquer terminal. Se `claude` ainda não for encontrado após a instalação, [verifique seu PATH](/pt/troubleshoot-install#verify-your-path).

408 

409Se estiver usando um terminal externo, execute `/ide` dentro de Claude Code para conectá-lo ao VS Code.

398 410 

399<h3 id="switch-between-extension-and-cli">411<h3 id="switch-between-extension-and-cli">

400 Switch between extension and CLI412 Switch between extension and CLI


530 Corrigir problemas comuns542 Corrigir problemas comuns

531</h2>543</h2>

532 544 

533<h3 id="extension-won-t-install">545<h3 id="extension-wont-install">

534 Extension won't install546 Extension won't install

535</h3>547</h3>

536 548 


577Se os problemas persistirem, [file an issue on GitHub](https://github.com/anthropics/claude-code/issues) com detalhes sobre o erro.589Se os problemas persistirem, [file an issue on GitHub](https://github.com/anthropics/claude-code/issues) com detalhes sobre o erro.

578 590 

579<h2 id="uninstall-the-extension">591<h2 id="uninstall-the-extension">

580 Uninstall the extension592 Desinstalar a extensão

581</h2>593</h2>

582 594 

583Para desinstalar a extensão Claude Code:595Para desinstalar a extensão Claude Code:


5862. Pesquise por "Claude Code"5982. Pesquise por "Claude Code"

5873. Clique em **Uninstall**5993. Clique em **Uninstall**

588 600 

589Para também remover dados de extensão e redefinir todas as configurações:601Para também remover dados de extensão e redefinir todas as configurações, delete o diretório de armazenamento da extensão para sua plataforma.

602 

603No macOS:

590 604 

591```bash theme={null}605```bash theme={null}

592rm -rf ~/.vscode/globalStorage/anthropic.claude-code606rm -rf ~/Library/"Application Support"/Code/User/globalStorage/anthropic.claude-code

607```

608 

609No Linux:

610 

611```bash theme={null}

612rm -rf ~/.config/Code/User/globalStorage/anthropic.claude-code

613```

614 

615No Windows, no PowerShell:

616 

617```powershell theme={null}

618Remove-Item -Recurse -Force "$env:APPDATA\Code\User\globalStorage\anthropic.claude-code"

593```619```

594 620 

595Para ajuda adicional, consulte o [troubleshooting guide](/pt/troubleshooting).621Para ajuda adicional, consulte o [guia de solução de problemas](/pt/troubleshooting).

596 622 

597<h2 id="next-steps">623<h2 id="next-steps">

598 Next steps624 Próximos passos

599</h2>625</h2>

600 626 

601Agora que você tem Claude Code configurado no VS Code:627Agora que você tem Claude Code configurado no VS Code:

Details

49| **Usa sua configuração local** | Não, apenas repositório | Sim | Sim | Sim para local, não para nuvem |49| **Usa sua configuração local** | Não, apenas repositório | Sim | Sim | Sim para local, não para nuvem |

50| **Requer GitHub** | Sim, ou [agrupe um repositório local](/pt/claude-code-on-the-web#send-local-repositories-without-github) via `--remote` | Não | Não | Apenas para sessões em nuvem |50| **Requer GitHub** | Sim, ou [agrupe um repositório local](/pt/claude-code-on-the-web#send-local-repositories-without-github) via `--remote` | Não | Não | Apenas para sessões em nuvem |

51| **Continua funcionando se você desconectar** | Sim | Enquanto o terminal permanecer aberto | Não | Depende do tipo de sessão |51| **Continua funcionando se você desconectar** | Sim | Enquanto o terminal permanecer aberto | Não | Depende do tipo de sessão |

52| **[Modos de permissão](/pt/permission-modes)** | Aceitar edições automaticamente, Plan | Perguntar, Aceitar edições automaticamente, Plan | Todos os modos | Depende do tipo de sessão |52| **[Modos de permissão](/pt/permission-modes)** | Aceitar edições, Plan, Auto | Perguntar, Aceitar edições automaticamente, Plan | Todos os modos | Depende do tipo de sessão |

53| **Acesso à rede** | Configurável por ambiente | Rede da sua máquina | Rede da sua máquina | Depende do tipo de sessão |53| **Acesso à rede** | Configurável por ambiente | Rede da sua máquina | Rede da sua máquina | Depende do tipo de sessão |

54 54 

55Consulte a documentação do [quickstart do terminal](/pt/quickstart), [aplicativo Desktop](/pt/desktop) ou [Remote Control](/pt/remote-control) para configurá-los.55Consulte a documentação do [quickstart do terminal](/pt/quickstart), [aplicativo Desktop](/pt/desktop) ou [Remote Control](/pt/remote-control) para configurá-los.

whats-new.md +16 −0

Details

8 8 

9O resumo semanal para desenvolvedores destaca os recursos com maior probabilidade de mudar a forma como você trabalha. Cada entrada inclui código executável, uma breve demonstração e um link para a documentação completa. Para cada correção de bug e melhoria menor, consulte o [changelog](/pt/changelog).9O resumo semanal para desenvolvedores destaca os recursos com maior probabilidade de mudar a forma como você trabalha. Cada entrada inclui código executável, uma breve demonstração e um link para a documentação completa. Para cada correção de bug e melhoria menor, consulte o [changelog](/pt/changelog).

10 10 

11<Update label="Week 24" description="8–12 de junho de 2026" tags={["v2.1.166–v2.1.176"]}>

12 **`/cd`**: mova a sessão atual para um novo diretório de trabalho no meio da conversa sem reconstruir o cache de prompt.

13 

14 Também esta semana: **sub-agentes podem gerar seus próprios sub-agentes** (cadeias de fundo são limitadas a cinco níveis de profundidade); **`--safe-mode`** inicia Claude Code com todas as personalizações desabilitadas para solução de problemas; e **`fallbackModel`** configura até três modelos de fallback tentados em ordem.

15 

16 [Leia o resumo da Week 24 →](/pt/whats-new/2026-w24)

17</Update>

18 

19<Update label="Week 23" description="1–5 de junho de 2026" tags={["v2.1.158–v2.1.165"]}>

20 **Auto mode no Bedrock, Vertex e Foundry**: auto mode agora está disponível em provedores de terceiros para Opus 4.7 e Opus 4.8, substituindo prompts de permissão por verificações de segurança em segundo plano.

21 

22 Também esta semana: **edições automáticas mais seguras** solicitam antes de escrever arquivos que podem executar código no modo `acceptEdits`; **`/plugin list`** imprime seus plugins instalados inline; e **requisitos de versão** permitem que implantações gerenciadas exijam um intervalo de versão aprovado do Claude Code.

23 

24 [Leia o resumo da Week 23 →](/pt/whats-new/2026-w23)

25</Update>

26 

11<Update label="Week 22" description="25–29 de maio de 2026" tags={["v2.1.150–v2.1.157"]}>27<Update label="Week 22" description="25–29 de maio de 2026" tags={["v2.1.150–v2.1.157"]}>

12 **Claude Opus 4.8**: o novo modelo padrão para Max, Team Premium, Enterprise pay-as-you-go e contas da API Anthropic, com alto esforço por padrão e `/effort xhigh` para as tarefas mais difíceis.28 **Claude Opus 4.8**: o novo modelo padrão para Max, Team Premium, Enterprise pay-as-you-go e contas da API Anthropic, com alto esforço por padrão e `/effort xhigh` para as tarefas mais difíceis.

13 29 

whats-new/2026-w23.md +100 −0 created

Details

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# Semana 23 · 1–5 de junho de 2026

6 

7> Execute o modo auto no Bedrock, Vertex e Foundry, solicite confirmação antes de escrever arquivos que podem executar código no modo acceptEdits, liste plugins instalados com /plugin list e exija um intervalo de versão aprovado para implantações gerenciadas.

8 

9<div className="digest-meta">

10 <span>Releases <a href="/docs/pt/changelog#2-1-158">v2.1.158 → v2.1.165</a></span>

11 <span>4 recursos · 1–5 de junho</span>

12</div>

13 

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Modo auto no Bedrock, Vertex e Foundry</span>

17 <span className="digest-feature-pill">v2.1.158</span>

18 </div>

19 

20 <p className="digest-feature-lede">O modo auto agora está disponível no Bedrock, Vertex e Foundry para Opus 4.7 e Opus 4.8, substituindo prompts de permissão por verificações de segurança em segundo plano em provedores de terceiros. Ative definindo <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE=1</code>.</p>

21 

22 <p className="digest-feature-try">Ative em um provedor de terceiros e alterne para o modo auto com Shift+Tab:</p>

23 

24 ```bash terminal theme={null}

25 export CLAUDE_CODE_ENABLE_AUTO_MODE=1

26 ```

27 

28 <a className="digest-feature-link" href="/docs/pt/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry">Ative o modo auto em provedores de terceiros</a>

29</div>

30 

31<div className="digest-feature">

32 <div className="digest-feature-header">

33 <span className="digest-feature-title">Edições automáticas mais seguras</span>

34 <span className="digest-feature-pill">v2.1.160</span>

35 </div>

36 

37 <p className="digest-feature-lede">Claude Code agora solicita confirmação antes de escrever arquivos que podem executar código, mesmo no modo <code>acceptEdits</code>. O conjunto protegido cobre arquivos de inicialização de shell como <code>.zshenv</code> e <code>.bash\_login</code>, configuração git em <code>\~/.config/git/</code> e configurações de ferramentas de compilação como <code>.npmrc</code>, <code>.bazelrc</code> e <code>.pre-commit-config.yaml</code>. Essas gravações nunca são aprovadas automaticamente em nenhum modo, exceto <code>bypassPermissions</code>.</p>

38 

39 <p className="digest-feature-try">Trabalhe no modo acceptEdits; Claude agora pausa antes de escrever esses arquivos:</p>

40 

41 ```bash terminal theme={null}

42 claude --permission-mode acceptEdits

43 ```

44 

45 <a className="digest-feature-link" href="/docs/pt/permission-modes#protected-paths">Caminhos protegidos</a>

46</div>

47 

48<div className="digest-feature">

49 <div className="digest-feature-header">

50 <span className="digest-feature-title">Liste plugins instalados com /plugin list</span>

51 <span className="digest-feature-pill">v2.1.163</span>

52 </div>

53 

54 <p className="digest-feature-lede">O novo comando <code>/plugin list</code> imprime seus plugins instalados inline, sem abrir o menu <code>/plugin</code>, e também está disponível como <code>claude plugin list</code> no shell. Na forma interativa, adicione `--enabled` ou `--disabled` para mostrar apenas plugins nesse estado.</p>

55 

56 <p className="digest-feature-try">Liste os plugins que estão atualmente ativados:</p>

57 

58 ```text Claude Code theme={null}

59 > /plugin list --enabled

60 ```

61 

62 <a className="digest-feature-link" href="/docs/pt/plugins-reference#plugin-list">Comandos de plugin</a>

63</div>

64 

65<div className="digest-feature">

66 <div className="digest-feature-header">

67 <span className="digest-feature-title">Requisitos de versão para implantações gerenciadas</span>

68 <span className="digest-feature-pill">v2.1.163</span>

69 </div>

70 

71 <p className="digest-feature-lede">Duas configurações gerenciadas, <code>requiredMinimumVersion</code> e <code>requiredMaximumVersion</code>, permitem que sua organização exija um intervalo de versão aprovado do Claude Code. Um cliente fora do intervalo sai na inicialização e informa ao usuário para atualizar através do método da organização. <code>claude update</code>, <code>claude install</code> e <code>claude doctor</code> continuam funcionando para que os usuários ainda possam se recuperar.</p>

72 

73 <p className="digest-feature-try">Adicione um limite mínimo às suas configurações gerenciadas para que clientes antigos se recusem a iniciar:</p>

74 

75 ```json managed-settings.json theme={null}

76 "requiredMinimumVersion": "2.1.163"

77 ```

78 

79 <a className="digest-feature-link" href="/docs/pt/admin-setup#decide-what-to-enforce">Decida o que aplicar</a>

80</div>

81 

82<div className="digest-wins">

83 <p className="digest-wins-title">Outras melhorias</p>

84 

85 <div className="digest-wins-grid">

86 <div>A palavra-chave de acionamento para <a href="/docs/pt/workflows">workflows dinâmicos</a> mudou de <code>workflow</code> para <code>ultracode</code>; pedir um workflow com suas próprias palavras ainda funciona, e a palavra-chave é destacada em violeta no prompt</div>

87 <div>Os hooks <a href="/docs/pt/hooks">Stop e SubagentStop</a> podem retornar <code>hookSpecificOutput.additionalContext</code> para dar feedback ao Claude e manter o turno em andamento em vez de ser tratado como um erro</div>

88 <div><code>claude mcp</code> list, get e add não imprimem mais segredos: referências de variáveis de ambiente não são expandidas e cabeçalhos de credenciais e segredos de URL são redatados</div>

89 <div>Um comando Bash com falha em um lote de ferramentas paralelas não cancela mais os outros; cada ferramenta retorna seu próprio resultado independentemente</div>

90 <div>Editar um arquivo não precisa mais de um Read separado quando você o visualizou com um <code>grep</code>, <code>egrep</code> ou <code>fgrep</code> de arquivo único</div>

91 <div>Clicar em um comando no menu de preenchimento automático agora o preenche no seu prompt em vez de executá-lo imediatamente; pressione Enter para executar</div>

92 <div>Listar <code>Grep</code> ou <code>Glob</code> em `--tools` agora fornece as ferramentas de busca dedicadas em compilações nativas com busca incorporada, em vez de ignorar silenciosamente esses nomes</div>

93 <div><code>/effort</code> agora confirma quando seu nível escolhido persistirá como padrão para novas sessões</div>

94 <div>Os valores de <code>OTEL\_RESOURCE\_ATTRIBUTES</code> agora são anexados como rótulos em pontos de dados de métrica, para que você possa dividir métricas de uso por dimensões personalizadas como equipe ou repositório</div>

95 <div>Windsurf é renomeado para Devin Desktop em <code>/ide</code>, <code>/terminal-setup</code> e <code>/scroll-speed</code>, seguindo a reformulação do editor</div>

96 <div><code>/btw</code> ganha um atalho <code>c to copy</code> que copia a resposta markdown bruta para a área de transferência</div>

97 </div>

98</div>

99 

100[Changelog completo para v2.1.158–v2.1.165 →](/pt/changelog#2-1-158)

whats-new/2026-w24.md +84 −0 created

Details

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# Semana 24 · 8–12 de junho de 2026

6 

7> Mova uma sessão para um novo diretório com /cd, deixe sub-agentes gerarem seus próprios sub-agentes e solucione problemas de uma configuração quebrada com modo seguro.

8 

9<div className="digest-meta">

10 <span>Versões <a href="/docs/pt/changelog#2-1-166">v2.1.166 → v2.1.176</a></span>

11 <span>3 recursos · 8–12 de junho</span>

12</div>

13 

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Mova uma sessão com /cd</span>

17 <span className="digest-feature-pill">v2.1.169</span>

18 </div>

19 

20 <p className="digest-feature-lede">O novo comando <code>/cd</code> move a sessão atual para um diretório de trabalho diferente sem reconstruir o cache de prompt: o <code>CLAUDE.md</code> do novo diretório é anexado como uma mensagem em vez de substituir o prompt do sistema. A sessão é relocada para o armazenamento de projeto do novo diretório, portanto `--resume` e `--continue` o encontram lá. Claude solicita que você confie no diretório se você não tiver trabalhado nele antes.</p>

21 

22 <p className="digest-feature-try">Mova a sessão para outro projeto sem reiniciar:</p>

23 

24 ```text Claude Code theme={null}

25 > /cd ../other-project

26 ```

27 

28 <a className="digest-feature-link" href="/docs/pt/commands#all-commands">Referência de comandos</a>

29</div>

30 

31<div className="digest-feature">

32 <div className="digest-feature-header">

33 <span className="digest-feature-title">Sub-agentes podem gerar sub-agentes</span>

34 <span className="digest-feature-pill">v2.1.172</span>

35 </div>

36 

37 <p className="digest-feature-lede">Sub-agentes agora podem gerar seus próprios sub-agentes. O painel de subagente abaixo do prompt mostra a árvore completa: cada linha carrega uma contagem de seus descendentes e um caminho de volta para <code>main</code>. Sub-agentes em segundo plano são limitados a cinco níveis de profundidade para evitar árvores concorrentes descontroladas; cadeias em primeiro plano podem gerar em qualquer profundidade e são auto-limitantes.</p>

38 

39 <p className="digest-feature-try">Abra a visualização de agentes para observar a árvore aninhada conforme o trabalho se expande:</p>

40 

41 ```text Claude Code theme={null}

42 > /agents

43 ```

44 

45 <a className="digest-feature-link" href="/docs/pt/sub-agents#spawn-nested-subagents">Gerar sub-agentes aninhados</a>

46</div>

47 

48<div className="digest-feature">

49 <div className="digest-feature-header">

50 <span className="digest-feature-title">Solucione problemas com modo seguro</span>

51 <span className="digest-feature-pill">v2.1.169</span>

52 </div>

53 

54 <p className="digest-feature-lede">Inicie Claude Code com `--safe-mode`, ou defina <code>CLAUDE\_CODE\_SAFE\_MODE</code>, para iniciar com todas as personalizações desabilitadas: <code>CLAUDE.md</code>, skills, plugins, hooks, servidores MCP e comandos e agentes personalizados não são carregados. Autenticação, seleção de modelo, ferramentas integradas e permissões ainda funcionam. Se um problema desaparecer em modo seguro, uma dessas superfícies é a causa.</p>

55 

56 <p className="digest-feature-try">Inicie uma sessão limpa para isolar uma configuração quebrada:</p>

57 

58 ```bash terminal theme={null}

59 claude --safe-mode

60 ```

61 

62 <a className="digest-feature-link" href="/docs/pt/debug-your-config#test-against-a-clean-configuration">Teste contra uma configuração limpa</a>

63</div>

64 

65<div className="digest-wins">

66 <p className="digest-wins-title">Outras vitórias</p>

67 

68 <div className="digest-wins-grid">

69 <div><a href="/docs/pt/model-config#fallback-model-chains"><code>fallbackModel</code></a> configura até três modelos de fallback tentados em ordem quando o primário está sobrecarregado ou indisponível, e `--fallback-model` agora se aplica a sessões interativas também</div>

70 <div>Os títulos de sessão agora são gerados no idioma de sua conversa; fixe um específico com a configuração <code>language</code></div>

71 <div>`claude agents --json` adiciona `--all` para incluir sessões concluídas mais novos campos <code>id</code> e <code>state</code>, e não omite mais sessões bloqueadas ou recém-despachadas</div>

72 <div>Navegar pelos plugins de um marketplace em <code>/plugin</code> agora tem uma barra de pesquisa</div>

73 <div>Nova configuração <code>disableBundledSkills</code> e <code>CLAUDE\_CODE\_DISABLE\_BUNDLED\_SKILLS</code> ocultam skills agrupados, fluxos de trabalho e comandos integrados do modelo</div>

74 <div>Regras de negação aceitam um glob na posição do nome da ferramenta, portanto <code>"\*"</code> nega todas as ferramentas, e nomes de ferramentas desconhecidos em regras de negação agora avisam na inicialização</div>

75 <div>Mensagens entre sessões são endurecidas: mensagens retransmitidas via <code>SendMessage</code> de outras sessões não carregam mais autoridade do usuário, e o modo automático as bloqueia</div>

76 <div>Amazon Bedrock lê a região AWS de arquivos de configuração `~/.aws` quando <code>AWS\_REGION</code> não está definido, e `/status` mostra de onde a região veio</div>

77 <div>Nova configuração gerenciada <code>enforceAvailableModels</code> faz a lista de permissões <code>availableModels</code> também restringir o modelo Padrão</div>

78 <div>Claude em ferramentas de navegador Chrome agora carregam em uma única chamada em lote em vez de uma por ferramenta</div>

79 <div><code>claude update</code> anuncia a versão de destino antes de fazer download em vez de ficar silencioso</div>

80 <div>Nova configuração <code>footerLinksRegexes</code> adiciona crachás de link correspondidos por regex à linha de rodapé</div>

81 </div>

82</div>

83 

84[Changelog completo para v2.1.166–v2.1.176 →](/pt/changelog#2-1-166)

workflows.md +3 −1

Details

9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}9{/* plan-availability: feature=workflows plans=pro,max,team,enterprise providers=all */}

10 10 

11<Note>11<Note>

12 Fluxos de trabalho dinâmicos estão em visualização de pesquisa. Eles exigem Claude Code v2.1.154 ou posterior e estão disponíveis em todos os planos pagos, com acesso à API Anthropic, e no Amazon Bedrock, Google Cloud Vertex AI e Microsoft Foundry. No Pro, ative-os na linha Dynamic workflows em `/config`.12 Fluxos de trabalho dinâmicos exigem Claude Code v2.1.154 ou posterior e estão disponíveis em todos os planos pagos, com acesso à API Anthropic, e no Amazon Bedrock, Google Cloud Vertex AI e Microsoft Foundry. No Pro, ative-os na linha Dynamic workflows em `/config`.

13</Note>13</Note>

14 14 

15Um fluxo de trabalho dinâmico é um script JavaScript que orquestra [subagentos](/pt/sub-agents) em escala. Claude escreve o script para a tarefa que você descreve, e um runtime o executa em segundo plano enquanto sua sessão permanece responsiva.15Um fluxo de trabalho dinâmico é um script JavaScript que orquestra [subagentos](/pt/sub-agents) em escala. Claude escreve o script para a tarefa que você descreve, e um runtime o executa em segundo plano enquanto sua sessão permanece responsiva.


198 198 

199Pressione Enter para salvar. O fluxo de trabalho é executado como `/<name>` em futuras sessões de qualquer local.199Pressione Enter para salvar. O fluxo de trabalho é executado como `/<name>` em futuras sessões de qualquer local.

200 200 

201{/* min-version: 2.1.178 */}A partir da v2.1.178, salvar no local do projeto escreve no diretório `.claude/workflows/` mais próximo que já existe entre seu diretório de trabalho e a raiz do repositório, ou para a raiz do repositório se nenhum existir ainda. Os fluxos de trabalho do projeto também carregam de cada `.claude/workflows/` ao longo desse caminho, e quando mais de um define o mesmo nome Claude Code executa o mais próximo do diretório de trabalho.

202 

201Se um fluxo de trabalho de projeto e um fluxo de trabalho pessoal compartilham um nome, o do projeto é executado.203Se um fluxo de trabalho de projeto e um fluxo de trabalho pessoal compartilham um nome, o do projeto é executado.

202 204 

203<h3 id="pass-input-to-a-saved-workflow">205<h3 id="pass-input-to-a-saved-workflow">

worktrees.md +4 −2

Details

36 36 

37Você também pode pedir ao Claude para "trabalhar em uma worktree" durante uma sessão, e ele criará uma com a ferramenta [`EnterWorktree`](/pt/tools-reference). Uma vez em uma worktree, Claude pode alternar diretamente para outra em `.claude/worktrees/` chamando `EnterWorktree` com o caminho de destino. A worktree anterior permanece no disco intacta.37Você também pode pedir ao Claude para "trabalhar em uma worktree" durante uma sessão, e ele criará uma com a ferramenta [`EnterWorktree`](/pt/tools-reference). Uma vez em uma worktree, Claude pode alternar diretamente para outra em `.claude/worktrees/` chamando `EnterWorktree` com o caminho de destino. A worktree anterior permanece no disco intacta.

38 38 

39Antes de usar `--worktree` em um diretório pela primeira vez, aceite o diálogo de confiança do workspace executando `claude` uma vez nesse diretório. Se a confiança ainda não foi aceita, `--worktree` sai com um erro e solicita que você execute `claude` no diretório primeiro, inclusive quando combinado com `-p`.39Antes de usar `--worktree` interativamente em um diretório pela primeira vez, aceite o diálogo de confiança do workspace executando `claude` uma vez nesse diretório. Se a confiança ainda não foi aceita, `--worktree` sai com um erro e solicita que você execute `claude` no diretório primeiro. Execuções não interativas com `-p` pulam a [verificação de confiança](/pt/security), então `claude -p --worktree` prossegue sem ela.

40 40 

41<Tip>41<Tip>

42 Adicione `.claude/worktrees/` ao seu `.gitignore` para que o conteúdo da worktree não apareça como arquivos não rastreados no seu checkout principal.42 Adicione `.claude/worktrees/` ao seu `.gitignore` para que o conteúdo da worktree não apareça como arquivos não rastreados no seu checkout principal.


102 102 

103Worktrees que Claude criou para subagentes e [sessões em segundo plano](/pt/agent-view#how-file-edits-are-isolated) são removidas automaticamente uma vez que são mais antigas que sua configuração [`cleanupPeriodDays`](/pt/settings#available-settings), desde que não tenham alterações não confirmadas, nenhum arquivo não rastreado e nenhum commit não enviado. Worktrees que você cria com `--worktree` nunca são removidas por esta varredura.103Worktrees que Claude criou para subagentes e [sessões em segundo plano](/pt/agent-view#how-file-edits-are-isolated) são removidas automaticamente uma vez que são mais antigas que sua configuração [`cleanupPeriodDays`](/pt/settings#available-settings), desde que não tenham alterações não confirmadas, nenhum arquivo não rastreado e nenhum commit não enviado. Worktrees que você cria com `--worktree` nunca são removidas por esta varredura.

104 104 

105Enquanto um agente está em execução, Claude executa `git worktree lock` em sua worktree para que a limpeza simultânea não possa removê-la. O bloqueio é liberado quando o agente termina. Para limpar uma worktree que a varredura mantém, execute `git worktree remove`, adicionando `--force` se a worktree tiver alterações não confirmadas ou arquivos não rastreados.

106 

105<h2 id="manage-worktrees-manually">107<h2 id="manage-worktrees-manually">

106 Gerencie worktrees manualmente108 Gerencie worktrees manualmente

107</h2>109</h2>


144 Controle de versão não-git146 Controle de versão não-git

145</h2>147</h2>

146 148 

147Isolamento de worktree usa git por padrão. Para SVN, Perforce, Mercurial, ou outros sistemas, configure hooks [`WorktreeCreate` e `WorktreeRemove`](/pt/hooks#worktreecreate) para fornecer lógica de criação e limpeza personalizada. Como o hook substitui o comportamento padrão do git, [`.worktreeinclude`](#copy-gitignored-files-into-worktrees) não é processado quando você usa `--worktree`. Copie quaisquer arquivos de configuração local dentro do seu script de hook.149Isolamento de worktrees usa git por padrão. Para SVN, Perforce, Mercurial, ou outros sistemas, configure os hooks [`WorktreeCreate` e `WorktreeRemove`](/pt/hooks#worktreecreate) para fornecer lógica de criação e limpeza personalizada. Como o hook substitui o comportamento padrão do git, [`.worktreeinclude`](#copy-gitignored-files-into-worktrees) não é processado quando você usa `--worktree`. Copie quaisquer arquivos de configuração local dentro do seu script de hook.

148 150 

149Este hook `WorktreeCreate` lê o nome da worktree de stdin, faz checkout de uma cópia de trabalho SVN fresca, e imprime o caminho do diretório para que Claude Code possa usá-lo como o diretório de trabalho da sessão:151Este hook `WorktreeCreate` lê o nome da worktree de stdin, faz checkout de uma cópia de trabalho SVN fresca, e imprime o caminho do diretório para que Claude Code possa usá-lo como o diretório de trabalho da sessão:

150 152 

Details

4 4 

5# Retenção zero de dados5# Retenção zero de dados

6 6 

7> Saiba mais sobre Retenção Zero de Dados (ZDR) para Claude Code no Claude for Enterprise, incluindo escopo, recursos desabilitados e como solicitar ativação.7> Saiba mais sobre Retenção Zero de Dados (ZDR) para Claude Code, disponível para contas qualificadas no Claude for Enterprise, incluindo escopo, recursos desabilitados e como solicitar ativação.

8 8 

9Retenção Zero de Dados (ZDR) está disponível para Claude Code quando usado através do Claude for Enterprise. Quando ZDR está ativado, prompts e respostas do modelo geradas durante sessões do Claude Code são processadas em tempo real e não são armazenadas pela Anthropic após a resposta ser retornada, exceto quando necessário para cumprir a lei ou combater uso indevido.9Retenção Zero de Dados (ZDR) para Claude Code está disponível para contas qualificadas no Claude for Enterprise. Quando ZDR está ativado, prompts e respostas do modelo geradas durante sessões do Claude Code são processadas em tempo real e não são armazenadas pela Anthropic após a resposta ser retornada, exceto quando necessário para cumprir a lei ou combater uso indevido.

10 

11<Note>

12 ZDR não está incluído no plano padrão do Claude for Enterprise e não pode ser ativado nas suas configurações de administrador. Está disponível para contas qualificadas e requer ativação separada pela Anthropic. Se sua organização requer ZDR, [entre em contato com vendas](https://www.anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=zero_data_retention_request) ou com sua equipe de conta da Anthropic para confirmar elegibilidade.

13</Note>

10 14 

11ZDR no Claude for Enterprise oferece aos clientes empresariais a capacidade de usar Claude Code com retenção zero de dados e acesso a recursos administrativos:15ZDR no Claude for Enterprise oferece aos clientes empresariais a capacidade de usar Claude Code com retenção zero de dados e acesso a recursos administrativos:

12 16 


31 O que ZDR cobre35 O que ZDR cobre

32</h3>36</h3>

33 37 

34ZDR cobre chamadas de inferência do modelo feitas através do Claude Code no Claude for Enterprise. Quando você usa Claude Code em seu terminal, os prompts que você envia e as respostas que Claude gera não são retidas pela Anthropic. Isso se aplica independentemente de qual modelo Claude é usado.38ZDR cobre chamadas de inferência do modelo feitas através do Claude Code no Claude for Enterprise. Quando você usa Claude Code em seu terminal, os prompts que você envia e as respostas que Claude gera não são retidas pela Anthropic. Isso se aplica a todos os modelos disponíveis para organizações ZDR. Alguns modelos requerem retenção de dados e não estão disponíveis sob ZDR; consulte [Disponibilidade de modelos sob ZDR](#model-availability-under-zdr).

35 39 

36<h3 id="what-zdr-does-not-cover">40<h3 id="what-zdr-does-not-cover">

37 O que ZDR não cobre41 O que ZDR não cobre


54Quando ZDR está ativado para uma organização do Claude Code no Claude for Enterprise, certos recursos que requerem armazenamento de prompts ou conclusões são automaticamente desabilitados no nível do backend:58Quando ZDR está ativado para uma organização do Claude Code no Claude for Enterprise, certos recursos que requerem armazenamento de prompts ou conclusões são automaticamente desabilitados no nível do backend:

55 59 

56| Recurso | Motivo |60| Recurso | Motivo |

57| -------------------------------------------------------------------- | --------------------------------------------------------------------- |61| ------------------------------------------------------------------- | --------------------------------------------------------------------- |

58| [Claude Code na Web](/pt/claude-code-on-the-web) | Requer armazenamento no servidor do histórico de conversas. |62| [Claude Code na Web](/pt/claude-code-on-the-web) | Requer armazenamento no servidor do histórico de conversas. |

59| [Sessões remotas](/pt/desktop#remote-sessions) do aplicativo Desktop | Requer dados de sessão persistentes que incluem prompts e conclusões. |63| [Sessões remotas](/pt/desktop#cloud-sessions) do aplicativo Desktop | Requer dados de sessão persistentes que incluem prompts e conclusões. |

60| Envio de feedback (`/feedback`) | Enviar feedback envia dados de conversas para a Anthropic. |64| Envio de feedback (`/feedback`) | Enviar feedback envia dados de conversas para a Anthropic. |

61 65 

62Esses recursos são bloqueados no backend independentemente da exibição no lado do cliente. Se você vir um recurso desabilitado no terminal do Claude Code durante a inicialização, tentar usá-lo retorna um erro indicando que as políticas da organização não permitem essa ação.66Esses recursos são bloqueados no backend independentemente da exibição no lado do cliente. Se você vir um recurso desabilitado no terminal do Claude Code durante a inicialização, tentar usá-lo retorna um erro indicando que as políticas da organização não permitem essa ação.

63 67 

64Recursos futuros também podem ser desabilitados se exigirem armazenamento de prompts ou conclusões.68Recursos futuros também podem ser desabilitados se exigirem armazenamento de prompts ou conclusões.

65 69 

70<h3 id="model-availability-under-zdr">

71 Disponibilidade de modelos sob ZDR

72</h3>

73 

74Claude Fable 5 não está disponível para organizações com retenção zero de dados ativada. Esta classe de modelo [requer retenção de dados](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements), portanto, solicitações de organizações ZDR não podem ser atendidas por ela. O modelo está ausente do seletor `/model` para organizações ZDR ou é exibido como desabilitado com um aviso de que desabilitar ZDR é necessário, e o servidor rejeita solicitações para ele independentemente da configuração do cliente.

75 

76Outros modelos permanecem disponíveis sob ZDR. Fable 5 não é o modelo padrão, e o alias `best`, que resolve para Fable 5 onde está disponível, resolve para Opus para organizações onde não está, incluindo organizações ZDR.

77 

66<h2 id="data-retention-for-policy-violations">78<h2 id="data-retention-for-policy-violations">

67 Retenção de dados para violações de política79 Retenção de dados para violações de política

68</h2>80</h2>