SpyBara
Go Premium

Documentation 2026-11-03 23:58 UTC to 2026-11-04 23:59 UTC

33 files changed +554 −196. View all changes and history on the product overview
2026
Thu 12 23:02 Wed 11 22:59 Tue 10 21:57 Mon 9 23:02 Sun 8 22:58 Sat 7 23:58 Fri 6 23:01 Thu 5 23:03 Wed 4 23:59 Tue 3 23:58 Mon 2 23:57 Sun 1 23:57
Details

231| Modo | Comportamento | Caso de uso |231| Modo | Comportamento | Caso de uso |

232| :- | :- | :- |232| :- | :- | :- |

233| `"default"` | Chamadas de ferramentas que precisam de aprovação e não são cobertas por regras de permissão acionam seu callback `canUseTool`; nenhum callback significa negar | Aplicações interativas com um callback de aprovação personalizado |233| `"default"` | Chamadas de ferramentas que precisam de aprovação e não são cobertas por regras de permissão acionam seu callback `canUseTool`; nenhum callback significa negar | Aplicações interativas com um callback de aprovação personalizado |

234| `"acceptEdits"` | Aprova automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.); outros comandos Bash seguem as regras padrão | Você confia nas edições do Claude e quer iteração mais rápida, como durante prototipagem ou ao trabalhar em um diretório isolado |234| `"acceptEdits"` | Aprova automaticamente edições de arquivo e comandos comuns do sistema de arquivos (`mkdir`, `touch`, `mv`, `cp`, etc.) dentro de seus [diretórios de trabalho](https://code.claude.com/docs/pt/permissions.md#working-directories); outros comandos Bash seguem as regras padrão | Você confia nas edições do Claude e quer iteração mais rápida, como durante prototipagem ou ao trabalhar em um diretório isolado |

235| `"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` | 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 de serem feitas |235| `"plan"` | Claude explora e planeja. Edições feitas com as ferramentas de arquivo do Claude vão para seu callback `canUseTool` mesmo quando uma regra allow corresponde a elas | Você quer que Claude produza um plano primeiro, como durante revisão de código ou antes de uma grande mudança |

236| `"dontAsk"` | Nunca solicita. Ferramentas pré-aprovadas por [regras de permissão](https://code.claude.com/docs/pt/settings-reference.md#permission-settings) são executadas, assim como chamadas que não precisam de aprovação no modo `default`, como leituras de arquivo dentro de seus diretórios de trabalho. Toda chamada que de outra forma solicitaria é negada, embora um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) que você instalou ainda possa aprovar [algumas dessas chamadas](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods). Algumas chamadas, como [leituras de caminhos de rede](https://code.claude.com/docs/pt/permissions.md#network-paths), são negadas mesmo que você as tenha permitido. Para a lista, veja [Don't ask mode](https://code.claude.com/docs/pt/agent-sdk/permissions.md#don’t-ask-mode-dontask) | Agentes headless sem ninguém para aprovar chamadas |236| `"dontAsk"` | Nunca solicita. Ferramentas pré-aprovadas por [regras de permissão](https://code.claude.com/docs/pt/settings-reference.md#permission-settings) são executadas, assim como chamadas que não precisam de aprovação no modo `default`, como leituras de arquivo dentro de seus diretórios de trabalho. Toda chamada que de outra forma solicitaria é negada, embora um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) que você instalou ainda possa aprovar [algumas dessas chamadas](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods). Algumas chamadas, como [leituras de caminhos de rede](https://code.claude.com/docs/pt/permissions.md#network-paths), são negadas mesmo que você as tenha permitido. Para a lista, veja [Don't ask mode](https://code.claude.com/docs/pt/agent-sdk/permissions.md#don’t-ask-mode-dontask) | Agentes headless sem ninguém para aprovar chamadas |

237| `"auto"` | Usa um classificador de modelo para revisar ações como comandos shell e solicitações de rede, permitindo ou bloqueando cada uma que revisa. Veja [Auto mode](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) para disponibilidade e a ordem de decisão | Agentes autônomos que ainda querem proteções de segurança no uso de ferramentas |237| `"auto"` | Usa um classificador de modelo para revisar ações como comandos shell e solicitações de rede, permitindo ou bloqueando cada uma que revisa. Veja [Auto mode](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) para disponibilidade e a ordem de decisão | Agentes autônomos que ainda querem proteções de segurança no uso de ferramentas |

238| `"bypassPermissions"` | Executa chamadas de ferramenta sem pedir aprovação, incluindo chamadas a ferramentas que você não listou em `allowedTools`. Algumas chamadas ainda vão para seu callback `canUseTool`, listadas em [Bypass permissions mode](https://code.claude.com/docs/pt/agent-sdk/permissions.md#bypass-permissions-mode-bypasspermissions). No SDK TypeScript, também requer `allowDangerouslySkipPermissions: true` em `options`. Não pode ser usado ao executar como root no Unix. Use apenas em ambientes isolados onde as ações do agente não podem afetar sistemas que você se importa | CI, contêineres ou outros ambientes isolados |238| `"bypassPermissions"` | Executa chamadas de ferramenta sem pedir aprovação, incluindo chamadas a ferramentas que você não listou em `allowedTools`. Algumas chamadas ainda vão para seu callback `canUseTool`, listadas em [Bypass permissions mode](https://code.claude.com/docs/pt/agent-sdk/permissions.md#bypass-permissions-mode-bypasspermissions). No SDK TypeScript, também requer `allowDangerouslySkipPermissions: true` em `options`. Não pode ser usado ao executar como root no Unix. Use apenas em ambientes isolados onde as ações do agente não podem afetar sistemas que você se importa | CI, contêineres ou outros ambientes isolados |

239 239 

240Para aplicações interativas, use `"default"` com um callback de aprovação de ferramenta para exibir solicitações 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 [Permissions](https://code.claude.com/docs/pt/agent-sdk/permissions.md) para detalhes completos.240Para aplicações interativas, use `"default"` com um callback de aprovação de ferramenta para exibir prompts de aprovação. Para agentes que editam arquivos em uma máquina de desenvolvimento, use `"acceptEdits"`. Reserve `"bypassPermissions"` para CI, contêineres ou outros ambientes isolados. Veja [Permissions](https://code.claude.com/docs/pt/agent-sdk/permissions.md) para detalhes completos.

241 241 

242### Modelo242### Modelo

243 243 

Details

14>14>

15> Se você carregar um plugin que contém um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md), consulte [onde as decisões de um mod se encaixam entre regras e hooks](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods).15> Se você carregar um plugin que contém um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md), consulte [onde as decisões de um mod se encaixam entre regras e hooks](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods).

16 16 

17Quando Claude solicita uma ferramenta, o SDK verifica as permissões nesta ordem:17Quando Claude solicita uma ferramenta, Claude Code verifica a chamada nestas etapas. Cada etapa pode decidir a chamada, enviá-la para seu callback `canUseTool` ou passá-la adiante:

18 18 

19**1. Hooks**19**1. Hooks**

20 20 

21Execute [hooks](https://code.claude.com/docs/pt/agent-sdk/hooks.md) primeiro. Um hook pode negar a chamada completamente ou deixá-la passar. Um hook que retorna `allow` não ignora as regras de negação e pergunta abaixo; essas são avaliadas independentemente do resultado do hook.21Execute [hooks](https://code.claude.com/docs/pt/agent-sdk/hooks.md). Um hook pode negar a chamada completamente ou passá-la adiante. Um hook que retorna `allow` não ignora as regras de negação e pergunta abaixo; essas são avaliadas independentemente do resultado do hook.

22 22 

23Um hook `PreToolUse` que retorna `allow` também não pode aprovar um comando `rm` ou `rmdir` cujo alvo Claude Code reconhece como um [caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#critical-paths), como `rm -rf ~`. Para saber o que esse `allow` faz no modo de planejamento, consulte [Aprovações de hooks no modo de planejamento](https://code.claude.com/docs/pt/permissions.md#hook-approvals-in-plan-mode).23Um hook `PreToolUse` que retorna `allow` também não pode aprovar um comando `rm` ou `rmdir` cujo alvo Claude Code reconhece como um [caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#critical-paths), como `rm -rf ~`. Para saber o que esse `allow` faz no modo de planejamento, consulte [Aprovações de hooks no modo de planejamento](https://code.claude.com/docs/pt/permissions.md#hook-approvals-in-plan-mode).

24 24 

25**2. Regras de negação**25**2. Regras de negação**

26 26 

27Se uma regra de negação de `disallowed_tools` ou de [settings.json](https://code.claude.com/docs/pt/settings-reference.md#permission-settings) corresponder, a chamada é negada e [`canUseTool`](https://code.claude.com/docs/pt/agent-sdk/user-input) não é chamado, mesmo no modo [`bypassPermissions`](#bypass-permissions-mode-bypasspermissions) e mesmo quando um hook retornou `allow`.27Se uma regra de negação de `disallowed_tools` ou de um [arquivo de configurações que o SDK carrega](#rules-in-settings-files) corresponder, a chamada é negada e [`canUseTool`](https://code.claude.com/docs/pt/agent-sdk/user-input) não é chamado. A chamada é negada dessa forma mesmo no modo [`bypassPermissions`](#bypass-permissions-mode-bypasspermissions) e quando um hook retornou `allow`.

28 28 

29No SDK TypeScript, se você definir a `permission_policy` de uma [ferramenta personalizada](https://code.claude.com/docs/pt/agent-sdk/custom-tools.md#require-approval-for-specific-tools) como [`always_deny`](https://code.claude.com/docs/pt/agent-sdk/typescript#mcpservertoolpolicy), uma chamada a essa ferramenta é negada nesta etapa.29No SDK TypeScript, se você definir a `permission_policy` de uma [ferramenta personalizada](https://code.claude.com/docs/pt/agent-sdk/custom-tools.md#require-approval-for-specific-tools) como [`always_deny`](https://code.claude.com/docs/pt/agent-sdk/typescript#mcpservertoolpolicy), uma chamada a essa ferramenta é negada nesta etapa.

30 30 


32 32 

33Verifique as regras `ask` de [settings.json](https://code.claude.com/docs/pt/settings-reference.md#permission-settings). Se uma regra de pergunta corresponder, a chamada passa para seu callback [`canUseTool`](https://code.claude.com/docs/pt/agent-sdk/user-input) para confirmação, mesmo no modo `bypassPermissions`.33Verifique as regras `ask` de [settings.json](https://code.claude.com/docs/pt/settings-reference.md#permission-settings). Se uma regra de pergunta corresponder, a chamada passa para seu callback [`canUseTool`](https://code.claude.com/docs/pt/agent-sdk/user-input) para confirmação, mesmo no modo `bypassPermissions`.

34 34 

35Ferramentas que requerem interação do usuário se comportam da mesma forma: `AskUserQuestion` e ferramentas MCP cujo servidor define [`_meta["anthropic/requiresUserInteraction"]`](https://code.claude.com/docs/pt/mcp#require-approval-for-a-specific-tool) sempre passam para o callback, mesmo quando uma regra de permissão corresponde. No modo `dontAsk` ambos os casos são negados, porque esse modo nunca solicita. A anotação MCP requer Claude Code v2.1.199 ou posterior.35Ferramentas que requerem interação do usuário se comportam da mesma forma. `AskUserQuestion` e ferramentas MCP cujo servidor define [`_meta["anthropic/requiresUserInteraction"]`](https://code.claude.com/docs/pt/mcp#require-approval-for-a-specific-tool) passam para o callback, mesmo quando uma regra de permissão corresponde. No modo `dontAsk` ambos os casos são negados, porque esse modo transforma cada prompt em uma negação. A anotação MCP requer Claude Code v2.1.199 ou posterior.

36 36 

37Ferramentas do conector [claude.ai](https://code.claude.com/docs/pt/mcp.md#organization-controls-on-connector-tools) que sua organização definiu como `ask` também saem do fluxo nesta etapa. Cada chamada passa para o callback, mesmo no modo `bypassPermissions` e mesmo quando uma regra de permissão corresponde. O callback recebe o motivo `Your organization requires approval for this tool`. No modo `dontAsk` a chamada é negada, porque esse modo nunca solicita.37Ferramentas do conector [claude.ai](https://code.claude.com/docs/pt/mcp.md#organization-controls-on-connector-tools) que sua organização definiu como `ask` também saem do fluxo nesta etapa. Cada chamada passa para o callback, mesmo no modo `bypassPermissions` e mesmo quando uma regra de permissão corresponde. O callback recebe o motivo `Your organization requires approval for this tool`. No modo `dontAsk` a chamada é negada, porque esse modo nunca solicita.

38 38 


42 42 

43Aplique o [modo de permissão](#permission-modes) ativo:43Aplique o [modo de permissão](#permission-modes) ativo:

44 44 

45* No modo `bypassPermissions`, Claude Code aprova tudo que chega a esta etapa, exceto [remoções de caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#critical-paths) reconhecidas e comandos Bash sinalizados com [`Dangerous rm operation not ruled out`](https://code.claude.com/docs/pt/permission-modes#dangerous-rm-operation-not-ruled-out), que passam para a próxima etapa.45* No modo `bypassPermissions`, Claude Code aprova cada chamada que chega a esta etapa, a menos que seja uma das [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves). Para saber quais dessas ações vão para seu callback `canUseTool`, consulte [Modo bypass permissions](#bypass-permissions-mode-bypasspermissions).

46 * Para executar essas remoções sem prompt, consulte [Desativar o prompt de remoção de caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#turn-off-the-critical-path-removal-prompt-in-bypasspermissions-mode).

47* No modo `acceptEdits`, Claude Code aprova as operações de arquivo listadas em [Modo Accept edits](#accept-edits-mode-acceptedits).46* No modo `acceptEdits`, Claude Code aprova as operações de arquivo listadas em [Modo Accept edits](#accept-edits-mode-acceptedits).

48* No modo `plan`, Claude Code envia ferramentas de edição de arquivo para seu callback `canUseTool` independentemente das regras de permissão.47* No modo `plan`, algumas chamadas chegam ao seu callback e, quando o modo auto está disponível, outras vão para o classificador dele. Para mais informações, consulte [Modo de planejamento](#plan-mode-plan).

49* Em outros modos, a solicitação passa para a próxima etapa.48* Nos modos `default` e `dontAsk`, a chamada segue para as regras de permissão.

49* Para o modo `auto`, consulte [Modo auto](#auto-mode-auto).

50 50 

51**5. Regras de permissão**51**5. Regras de permissão**

52 52 


91 91 

92As 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_`. Uma entrada não ancorada como `allowed_tools=["*"]` ou `allowed_tools=["mcp__*"]` é ignorada e não aprova automaticamente nada.92As 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_`. Uma entrada não ancorada como `allowed_tools=["*"]` ou `allowed_tools=["mcp__*"]` é ignorada e não aprova automaticamente nada.

93 93 

94As regras com escopo para `Read` e `Edit` usam um padrão de caminho. As regras `Edit(path)` governam todas as ferramentas integradas que escrevem arquivos, incluindo `Write` e `NotebookEdit`; uma regra `Write(path)` nunca é correspondida pelas verificações de permissão de arquivo.

95 

96Use `//path` para um caminho absoluto do sistema de arquivos: uma regra de negação de `Edit(//secrets/**)` bloqueia escritas em qualquer lugar sob `/secrets` no disco. Com uma única barra inicial, `Edit(/secrets/**)` ancora na fonte da regra. Para regras passadas através de `allowed_tools` ou `disallowed_tools`, isso significa o diretório de trabalho da sessão, portanto a regra não bloqueia `/secrets` no disco. Veja [Regras Read e Edit](https://code.claude.com/docs/pt/permissions.md#read-and-edit) para as quatro formas de âncora e como as regras dos arquivos de configuração são resolvidas.

97 

98> [!WARNING]94> [!WARNING]

99>95>

100> **Ferramentas aprovadas automaticamente nunca chegam a `canUseTool`.** Uma chamada de ferramenta aprovada em qualquer etapa anterior, por `acceptEdits` ou `bypassPermissions`, ou por uma regra de permissão, ignora seu callback `canUseTool`, portanto as verificações de permissão que você coloca lá são silenciosamente ignoradas para essa ferramenta.96> **Ferramentas aprovadas automaticamente nunca chegam a `canUseTool`.** Uma chamada de ferramenta aprovada em qualquer etapa anterior, por `acceptEdits` ou `bypassPermissions`, ou por uma regra de permissão, ignora seu callback `canUseTool`, portanto as verificações de permissão que você coloca lá são silenciosamente ignoradas para essa ferramenta.


105>101>

106> * Ferramentas personalizadas que sua aplicação marca como [`always_ask`](https://code.claude.com/docs/pt/agent-sdk/custom-tools#require-approval-for-specific-tools): decida a chamada no callback. Para impedir que essas chamadas cheguem, [altere a política no meio da sessão](https://code.claude.com/docs/pt/agent-sdk/typescript.md#mcpsdkserverconfigwithinstance). Nos modos `auto`, `plan` e `bypassPermissions`, a chamada pode, em vez disso, ser aprovada antes do callback, nos casos listados em [Modos de permissão que podem aprovar uma chamada `always_ask`](https://code.claude.com/docs/pt/agent-sdk/typescript#permission-modes-that-can-approve-an-always_ask-call)102> * Ferramentas personalizadas que sua aplicação marca como [`always_ask`](https://code.claude.com/docs/pt/agent-sdk/custom-tools#require-approval-for-specific-tools): decida a chamada no callback. Para impedir que essas chamadas cheguem, [altere a política no meio da sessão](https://code.claude.com/docs/pt/agent-sdk/typescript.md#mcpsdkserverconfigwithinstance). Nos modos `auto`, `plan` e `bypassPermissions`, a chamada pode, em vez disso, ser aprovada antes do callback, nos casos listados em [Modos de permissão que podem aprovar uma chamada `always_ask`](https://code.claude.com/docs/pt/agent-sdk/typescript#permission-modes-that-can-approve-an-always_ask-call)

107>103>

108> * [Remoções de caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#critical-paths) reconhecidas com `rm` e `rmdir`: nos modos `default`, `acceptEdits` e `bypassPermissions`, permita ou negue a remoção no callback, onde [`decisionReason`](https://code.claude.com/docs/pt/agent-sdk/typescript#canusetool) começa com `Dangerous rm`. Para os modos `auto` e `plan`, veja [Remoções de caminho crítico em cada modo de permissão](https://code.claude.com/docs/pt/permission-modes.md#critical-path-removals-in-each-permission-mode). A verificação que reconhece essas remoções [pode deixar passar alguns comandos](https://code.claude.com/docs/pt/permission-modes.md#critical-paths)104> * [Remoções de caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#critical-paths) reconhecidas com `rm` e `rmdir`: nos modos `default`, `acceptEdits` e `bypassPermissions`, permita ou negue a remoção no callback, onde [`decisionReason`](https://code.claude.com/docs/pt/agent-sdk/typescript#canusetool) começa com `Dangerous rm`. Para os modos `auto` e `plan`, veja [Remoções de caminho crítico em cada modo de permissão](https://code.claude.com/docs/pt/permission-modes.md#critical-path-removals-in-each-permission-mode)

109>105>

110> * **Nome simples**: uma entrada como `Read` ou `mcp__github__get_issue` aprova automaticamente todas as chamadas a essa ferramenta, exceto as [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves) e as [leituras de caminhos de rede](https://code.claude.com/docs/pt/permissions.md#network-paths).106> * **Nome simples**: uma entrada como `Read` ou `mcp__github__get_issue` aprova automaticamente todas as chamadas a essa ferramenta, exceto as [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves) e as [leituras de caminhos de rede](https://code.claude.com/docs/pt/permissions.md#network-paths).

111>107>

112> * **Regra com escopo**: uma entrada como `Bash(npm test *)` aprova automaticamente apenas chamadas correspondentes, e outras chamadas `Bash` que precisam de aprovação ainda passam para o callback.108> * **Regra com escopo**: uma entrada como `Bash(npm test *)` aprova automaticamente as chamadas correspondentes a ela, e outras chamadas `Bash` que precisam de aprovação passam para o modo de permissão.

113>109>

114> Para verificações que devem ser executadas em todas as chamadas de ferramenta, use um [hook `PreToolUse`](https://code.claude.com/docs/pt/agent-sdk/hooks): hooks são executados antes de qualquer outra etapa, e uma negação de hook se aplica mesmo no modo `bypassPermissions`.110> Para verificar chamadas que uma regra de permissão, `acceptEdits` ou `bypassPermissions` aprova, use um [hook `PreToolUse`](https://code.claude.com/docs/pt/agent-sdk/hooks), que também é executado para essas chamadas. Uma negação de hook se aplica mesmo no modo `bypassPermissions`.

115 111 

116Para um agente bloqueado, combine `allowedTools` com `permissionMode: "dontAsk"`:112Para um agente bloqueado, combine `allowedTools` com `permissionMode: "dontAsk"`:

117 113 


128 124 

129> [!WARNING]125> [!WARNING]

130>126>

131> **`allowed_tools` não restringe `bypassPermissions`.** `allowed_tools` aprova previamente as ferramentas que você lista. Outras ferramentas não listadas não são correspondidas por nenhuma regra de permissão e passam para o modo de permissão, onde `bypassPermissions` as aprova. Definir `allowed_tools=["Read"]` junto com `permission_mode="bypassPermissions"` ainda aprova todas as ferramentas, incluindo `Bash`, `Write` e `Edit`. Se você precisar de `bypassPermissions` mas quiser ferramentas específicas bloqueadas, use `disallowed_tools`.127> **`allowed_tools` não restringe `bypassPermissions`.** `allowed_tools` aprova previamente as ferramentas que você lista. No modo `bypassPermissions`, Claude Code aprova uma chamada a uma ferramenta não listada, a menos que seja uma das [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves).

128>

129> Se você definir `allowed_tools=["Read"]` com `permission_mode="bypassPermissions"`, Claude Code ainda aprova chamadas a ferramentas como `Bash`, `Write` e `Edit`. Se você precisar de `bypassPermissions` mas quiser ferramentas específicas bloqueadas, use `disallowed_tools`. Para as chamadas que ainda chegam ao seu callback `canUseTool` nesse modo, veja [Modo de bypass de permissões](#bypass-permissions-mode-bypasspermissions).

132 130 

133Você também pode configurar regras de permissão, negação e solicitação de forma declarativa em `.claude/settings.json`. Essas regras são lidas quando a fonte de configuração `project` está habilitada, o que é o padrão para opções `query()`. Se você definir `setting_sources` (TypeScript: `settingSources`) explicitamente, inclua `"project"` para que se apliquem. Veja [Configurações de permissão](https://code.claude.com/docs/pt/settings-reference.md#permission-settings) para a sintaxe das regras.131Você também pode configurar regras de permissão, negação e solicitação de forma declarativa em `.claude/settings.json`. Essas regras são lidas quando a fonte de configuração `project` está habilitada, o que é o padrão para opções `query()`. Se você definir `setting_sources` (TypeScript: `settingSources`) explicitamente, inclua `"project"` para que se apliquem. Veja [Configurações de permissão](https://code.claude.com/docs/pt/settings-reference.md#permission-settings) para a sintaxe das regras.

134 132 

133Para saber quando as regras de permissão no `.claude/settings.json` de um projeto se aplicam, veja [Regras de permissão do projeto e confiança do workspace](https://code.claude.com/docs/pt/permissions.md#project-allow-rules-and-workspace-trust).

134 

135### Padrões de caminho em regras

136 

137As regras com escopo para `Read` e `Edit` usam um padrão de caminho. As regras `Edit(path)` governam todas as ferramentas integradas que escrevem arquivos, incluindo `Write` e `NotebookEdit`, portanto escreva uma regra de caminho para qualquer uma delas como `Edit(path)`. Se você escrever uma regra de caminho como `Write(path)` ou `NotebookEdit(path)`, ela [não corresponde a nenhuma chamada](https://code.claude.com/docs/pt/permissions.md#path-rules-that-never-match) e não tem efeito.

138 

139Em `allowed_tools` e `disallowed_tools`, inicie um padrão de caminho com `//` para um caminho absoluto, ou com uma única `/` para um caminho dentro do diretório de trabalho da sessão:

140 

141* **`//path`**: com uma regra de negação de `Edit(//secrets/**)`, Claude Code bloqueia escritas sob `/secrets` no disco feitas pelas ferramentas de arquivo de Claude e por [comandos Bash como `tee` e redirecionamento `> file`](https://code.claude.com/docs/pt/permissions#what-read-and-edit-rules-cover). Um script que Claude executa e que abre arquivos por conta própria ainda pode escrever sob `/secrets`. Para imposição pelo sistema operacional, veja [Configurar a ferramenta Bash em sandbox](https://code.claude.com/docs/pt/sandboxing.md).

142* **`/path`**: `Edit(/secrets/**)` corresponde ao diretório `secrets` dentro do diretório de trabalho.

143 

144Para outras formas de iniciar um padrão de caminho, veja [Regras Read e Edit](https://code.claude.com/docs/pt/permissions.md#read-and-edit).

145 

135## Modos de permissão146## Modos de permissão

136 147 

137Os modos de permissão fornecem controle global sobre como Claude usa ferramentas. Você pode definir o modo de permissão ao chamar `query()` ou alterá-lo dinamicamente durante sessões de streaming.148Os modos de permissão fornecem controle global sobre como Claude usa ferramentas. Você pode definir o modo de permissão ao chamar `query()` ou alterá-lo dinamicamente durante sessões de streaming.


146| :- | :- | :- |157| :- | :- | :- |

147| `default` | Comportamento de permissão padrão | Sem aprovações automáticas baseadas em modo; chamadas que precisam de aprovação e não correspondem a nenhuma regra de permissão acionam seu callback `canUseTool` |158| `default` | Comportamento de permissão padrão | Sem aprovações automáticas baseadas em modo; chamadas que precisam de aprovação e não correspondem a nenhuma regra de permissão acionam seu callback `canUseTool` |

148| `dontAsk` | Negar em vez de solicitar | Qualquer chamada que de outra forma solicitaria é negada sem chamar `canUseTool`, embora um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) que você instalou ainda possa aprovar [algumas dessas chamadas](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods). Chamadas aprovadas por `allowed_tools` ou por regras de permissão em `settings.json` são executadas, assim como chamadas que não precisam de aprovação no modo `default`. Algumas chamadas, como [leituras de caminhos de rede](https://code.claude.com/docs/pt/permissions.md#network-paths), são negadas mesmo quando `allowed_tools` ou uma regra de permissão corresponde a elas. Para a lista, consulte [Modo não perguntar](#don’t-ask-mode-dontask) |159| `dontAsk` | Negar em vez de solicitar | Qualquer chamada que de outra forma solicitaria é negada sem chamar `canUseTool`, embora um [mod](https://code.claude.com/docs/pt/plugins/mods/overview.md) que você instalou ainda possa aprovar [algumas dessas chamadas](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods). Chamadas aprovadas por `allowed_tools` ou por regras de permissão em `settings.json` são executadas, assim como chamadas que não precisam de aprovação no modo `default`. Algumas chamadas, como [leituras de caminhos de rede](https://code.claude.com/docs/pt/permissions.md#network-paths), são negadas mesmo quando `allowed_tools` ou uma regra de permissão corresponde a elas. Para a lista, consulte [Modo não perguntar](#don’t-ask-mode-dontask) |

149| `acceptEdits` | Aceitar automaticamente edições de arquivo | Edições de arquivo e [operações do sistema de arquivos](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) são automaticamente aprovadas |160| `acceptEdits` | Aceitar automaticamente edições de arquivo | Edições de arquivo e [operações do sistema de arquivos](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) dentro de seus [diretórios de trabalho](https://code.claude.com/docs/pt/permissions.md#working-directories) são automaticamente aprovadas |

150| `bypassPermissions` | Contornar verificações de permissão | As ferramentas são executadas sem prompts de permissão, exceto pelas [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves) e, fora de uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), ferramentas personalizadas que sua aplicação [marca como `always_ask`](https://code.claude.com/docs/pt/agent-sdk/custom-tools#require-approval-for-specific-tools). Use com cuidado |161| `bypassPermissions` | Contornar verificações de permissão | As ferramentas são executadas sem prompts de permissão, exceto pelas [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves) e, fora de uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), ferramentas personalizadas que sua aplicação [marca como `always_ask`](https://code.claude.com/docs/pt/agent-sdk/custom-tools#require-approval-for-specific-tools). Use com cuidado |

151| `plan` | Modo de planejamento | 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` |162| `plan` | Modo de planejamento | Claude explora e planeja. Edições feitas com as ferramentas de arquivo de Claude vão para seu callback `canUseTool` mesmo quando uma regra de permissão corresponde a elas |

152| `auto` | Aprovações classificadas pelo modelo | Um classificador de modelo revisa ações como comandos shell e solicitações de rede, permitindo ou bloqueando cada uma que revisa. Consulte [Modo Auto](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) para disponibilidade e a ordem de decisão |163| `auto` | Aprovações classificadas pelo modelo | Um classificador de modelo revisa ações como comandos shell e solicitações de rede, permitindo ou bloqueando cada uma que revisa. Consulte [Modo Auto](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) para disponibilidade e a ordem de decisão |

153 164 

154> [!WARNING]165> [!WARNING]


267 278 

268**Operações aprovadas automaticamente:**279**Operações aprovadas automaticamente:**

269 280 

270* Edições de arquivo (ferramentas Edit, Write)281* Edições de arquivo com as ferramentas Edit, Write e NotebookEdit

271* Comandos do sistema de arquivos: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`282* Comandos do sistema de arquivos: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`

272 283 

273Ambos se aplicam apenas a caminhos dentro do diretório de trabalho ou `additionalDirectories`. No modo `acceptEdits`, Claude Code não aprova automaticamente a solicitação quando Claude:284Ambos se aplicam a caminhos dentro do diretório de trabalho ou de um diretório que você adiciona. Em Python, adicione um com `add_dirs` e, em TypeScript, com `additionalDirectories`. No modo `acceptEdits`, Claude Code não aprova automaticamente a solicitação quando Claude:

274 285 

275* Trabalha em um caminho fora desse escopo286* Trabalha em um caminho fora desse escopo

276* Escreve em um caminho protegido287* Escreve em um [caminho protegido](https://code.claude.com/docs/pt/permission-modes.md#protected-paths)

277* Remove com `rm` ou `rmdir` um caminho que Claude Code reconhece como um [caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#critical-paths)288* Remove com `rm` ou `rmdir` um caminho que Claude Code reconhece como um [caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#critical-paths)

278* Executa [`touch`](https://code.claude.com/docs/pt/permission-modes#auto-approve-file-edits-with-acceptedits-mode) com, por exemplo, uma opção, um glob ou um prefixo `timeout 5` ou `LANG=C`289* Executa [`touch`](https://code.claude.com/docs/pt/permission-modes#auto-approve-file-edits-with-acceptedits-mode) com, por exemplo, uma opção, um glob ou um prefixo `timeout 5` ou `LANG=C`

279 290 


293 304 

294Se seu hook `PreToolUse` retornar `allow` para uma remoção de caminho crítico reconhecida, uma leitura de um caminho de rede ou uma chamada a uma ferramenta marcada como `always_ask`, a chamada ainda é negada. A verificação que reconhece essas remoções [pode deixar passar alguns comandos](https://code.claude.com/docs/pt/permission-modes.md#critical-paths).305Se seu hook `PreToolUse` retornar `allow` para uma remoção de caminho crítico reconhecida, uma leitura de um caminho de rede ou uma chamada a uma ferramenta marcada como `always_ask`, a chamada ainda é negada. A verificação que reconhece essas remoções [pode deixar passar alguns comandos](https://code.claude.com/docs/pt/permission-modes.md#critical-paths).

295 306 

296**Use quando:** você deseja uma superfície de ferramenta fixa e explícita para um agente sem interface e prefere uma negação definitiva em vez de depender silenciosamente de `canUseTool` estar ausente.307**Use quando:** você executa um agente sem interface e deseja uma negação definitiva para cada chamada que de outra forma solicitaria.

297 308 

298#### Modo contornar permissões (`bypassPermissions`)309#### Modo contornar permissões (`bypassPermissions`)

299 310 


303>314>

304> Use com extrema cautela. Claude tem acesso completo ao sistema neste modo. Use apenas em ambientes controlados onde você confia em todas as operações possíveis.315> Use com extrema cautela. Claude tem acesso completo ao sistema neste modo. Use apenas em ambientes controlados onde você confia em todas as operações possíveis.

305>316>

306> `allowed_tools` não restringe este modo. Cada ferramenta é aprovada, não apenas as que você listou. Estes controles ainda se aplicam:317> `allowed_tools` não restringe este modo, e chamadas a ferramentas que você não listou também são aprovadas. Estes controles ainda se aplicam:

307>318>

308> * Regras de negação, regras explícitas `ask` e hooks são avaliados antes da verificação de modo e ainda podem bloquear uma ferramenta.319> * Regras de negação, regras explícitas `ask` e hooks são avaliados antes da verificação de modo e ainda podem bloquear uma ferramenta.

309> * Ferramentas de conector [que sua organização definiu como `ask`](https://code.claude.com/docs/pt/mcp#organization-controls-on-connector-tools), ferramentas que exigem interação do usuário e [remoções de caminhos críticos](https://code.claude.com/docs/pt/permission-modes.md#critical-paths) reconhecidas ainda caem para seu callback `canUseTool`. A verificação que reconhece essas remoções [pode deixar passar alguns comandos](https://code.claude.com/docs/pt/permission-modes.md#critical-paths), e você pode [desativar o prompt de remoção de caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#turn-off-the-critical-path-removal-prompt-in-bypasspermissions-mode). Fora de uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), chamadas a ferramentas personalizadas que sua aplicação [marca como `always_ask`](https://code.claude.com/docs/pt/agent-sdk/custom-tools#require-approval-for-specific-tools) também caem para o callback.320> * Ferramentas de conector [que sua organização definiu como `ask`](https://code.claude.com/docs/pt/mcp#organization-controls-on-connector-tools), ferramentas que exigem interação do usuário, [remoções de caminhos críticos](https://code.claude.com/docs/pt/permission-modes.md#critical-paths) reconhecidas e comandos Bash sinalizados com [`Dangerous rm operation not ruled out`](https://code.claude.com/docs/pt/permission-modes#dangerous-rm-operation-not-ruled-out) ainda caem para seu callback `canUseTool`. A verificação que reconhece remoções de caminhos críticos [pode deixar passar alguns comandos](https://code.claude.com/docs/pt/permission-modes.md#critical-paths), e você pode [desativar o prompt de remoção de caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#turn-off-the-critical-path-removal-prompt-in-bypasspermissions-mode). Fora de uma [sessão na nuvem](https://code.claude.com/docs/pt/claude-code-on-the-web.md), chamadas a ferramentas personalizadas que sua aplicação [marca como `always_ask`](https://code.claude.com/docs/pt/agent-sdk/custom-tools#require-approval-for-specific-tools) também caem para o callback.

310> * Os [salvaguardas de mensagens entre sessões](https://code.claude.com/docs/pt/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) ainda se aplicam.321> * Os [salvaguardas de mensagens entre sessões](https://code.claude.com/docs/pt/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) ainda se aplicam.

311 322 

312#### Modo plano (`plan`)323#### Modo plano (`plan`)

313 324 

314Claude explora a base de código e produz um plano sem editar seus arquivos de origem. Edições de arquivo nunca são aprovadas automaticamente no modo de planejamento, mesmo quando uma regra de permissão corresponde ou um hook `PreToolUse` retorna `allow`. Em vez disso, elas solicitam através de seu callback `canUseTool`.325Claude explora a base de código e produz um plano. Durante o planejamento, edições feitas com as ferramentas de arquivo de Claude fora de [caminhos protegidos](https://code.claude.com/docs/pt/permission-modes.md#protected-paths) chegam ao seu callback `canUseTool`, mesmo quando uma regra de permissão corresponde ou um hook `PreToolUse` retorna `allow`. Chamadas a [`AskUserQuestion`](https://code.claude.com/docs/pt/agent-sdk/user-input#handle-clarifying-questions) também chegam ao seu callback, mesmo quando uma regra de permissão nomeia a ferramenta.

326 

327Quando o [modo auto](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) está disponível, Claude Code envia estas chamadas durante o planejamento ao [classificador do modo auto](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode) para revisão, em vez de ao seu callback, quando nenhuma regra de permissão as aprova:

328 

329* Comandos shell

330* Buscas na web

331* Pesquisas na web

332* Chamadas a ferramentas MCP que seu servidor marca como somente leitura

333 

334Essa revisão vem ativada por padrão. Para desativá-la, defina [`useAutoModeDuringPlan`](https://code.claude.com/docs/pt/settings-reference#useautomodeduringplan) como `false` na opção `settings` que você passa para `query()`, ou nas suas configurações de usuário. Enquanto a revisão estiver desativada, pesquisas na web e chamadas a ferramentas MCP marcadas como somente leitura chegam ao seu callback.

315 335 

316Enquanto o modo auto estiver disponível para a sessão, os comandos que Claude executa durante o planejamento não chegam ao seu callback por padrão, porque o modelo classificador que o [modo auto](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) usa [os revisa em vez disso](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode). Com essa revisão ativada, o classificador também pode aprovar chamadas somente leitura que de outra forma chegariam ao seu callback, como uma chamada `WebFetch` sem regra de permissão.336Para comandos shell e buscas na web, a tabela mostra se cada chamada chega ao seu callback:

337 

338| Chamada durante o planejamento | Revisão ativada | Revisão desativada, ou modo auto não disponível |

339| :- | :- | :- |

340| Um comando shell [somente leitura](https://code.claude.com/docs/pt/permissions.md#read-only-commands), como `ls` | É executado sem chegar ao seu callback | É executado sem chegar ao seu callback |

341| Qualquer outro comando shell que nenhuma regra de permissão aprova, exceto uma [remoção de caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#critical-paths) | Vai para o classificador, que o aprova ou recusa sem o seu callback | Chega ao seu callback |

342| Uma chamada `WebFetch` para um [domínio de documentação pré-aprovado](https://code.claude.com/docs/pt/tools-reference.md#webfetch-tool-behavior) | É executada sem chegar ao seu callback | É executada sem chegar ao seu callback |

343| Qualquer outra chamada `WebFetch` que nenhuma regra de permissão aprova | Vai para o classificador, que a aprova ou recusa sem o seu callback | Chega ao seu callback |

344 

345Para saber o que acontece depois que o classificador recusa várias chamadas seguidas, consulte [Limites de bloqueios repetidos](https://code.claude.com/docs/pt/permission-modes.md#repeated-block-thresholds).

317 346 

318> [!NOTE]347> [!NOTE]

319>348>

320> No SDK TypeScript, se você definir `allowDangerouslySkipPermissions: true` junto com `permissionMode: 'plan'`, edições de arquivo ainda chegam ao seu callback `canUseTool`. Para alternar mais tarde uma sessão que inicia no modo de planejamento para `bypassPermissions` com `setPermissionMode()`, você precisa ter `allowDangerouslySkipPermissions` definido desde o início.349> No SDK TypeScript, se você definir `allowDangerouslySkipPermissions: true` junto com `permissionMode: 'plan'`, edições de arquivo ainda chegam ao seu callback `canUseTool`. Para alternar mais tarde uma sessão que inicia no modo de planejamento para `bypassPermissions` com `setPermissionMode()`, você precisa ter `allowDangerouslySkipPermissions` definido desde o início.

321 350 

322Claude pode usar `AskUserQuestion` para esclarecer requisitos antes de finalizar o plano. Consulte [Lidar com aprovações e entrada do usuário](https://code.claude.com/docs/pt/agent-sdk/user-input.md#handle-clarifying-questions) para lidar com esses prompts.351**Use quando:** você deseja que Claude produza um plano primeiro, como durante revisão de código ou antes de uma grande alteração.

323 

324**Use quando:** você deseja que Claude proponha alterações sem executá-las, como durante revisão de código ou quando você precisa aprovar alterações antes que sejam feitas.

325 352 

326#### Modo auto (`auto`)353#### Modo auto (`auto`)

327 354 

Details

1175PermissionMode = Literal[1175PermissionMode = Literal[

1176 "default", # Comportamento de permissão padrão1176 "default", # Comportamento de permissão padrão

1177 "acceptEdits", # Auto-aceitar edições de arquivo1177 "acceptEdits", # Auto-aceitar edições de arquivo

1178 "plan", # Modo de planejamento - explorar sem editar1178 "plan", # Modo de planejamento - Claude explora e planeja

1179 "dontAsk", # Negar qualquer coisa não pré-aprovada em vez de solicitar1179 "dontAsk", # Negar qualquer coisa não pré-aprovada em vez de solicitar

1180 "bypassPermissions", # Contornar verificações de permissão; regras de ask explícitas ainda solicitam (use com cuidado)1180 "bypassPermissions", # Contornar verificações de permissão; regras de ask explícitas ainda solicitam (use com cuidado)

1181 "auto", # Um classificador de modelo revisa ações como comandos de shell e requisições de rede1181 "auto", # Um classificador de modelo revisa ações como comandos de shell e requisições de rede


1214 1214 

1215Retorna um `PermissionResult` (ou `PermissionResultAllow` ou `PermissionResultDeny`).1215Retorna um `PermissionResult` (ou `PermissionResultAllow` ou `PermissionResultDeny`).

1216 1216 

1217O callback é a substituição SDK para o prompt de permissão interativo: é invocado apenas quando o [fluxo de avaliação de permissão](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) se resolve em um prompt. Chamadas de ferramenta já aprovadas por uma entrada `allowed_tools`, uma regra de permissão de configurações, ou o modo de permissão, como `acceptEdits` ou `bypassPermissions`, nunca o invocam. Para controlar cada chamada de ferramenta, use um [hook `PreToolUse`](https://code.claude.com/docs/pt/agent-sdk/hooks) em vez disso.1217O callback substitui o prompt de permissão interativo. O SDK chama `can_use_tool` quando o [fluxo de avaliação de permissão](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) se resolve em um prompt. Chamadas aprovadas de qualquer uma destas formas são executadas sem chamar `can_use_tool`:

1218 

1219* Uma chamada que uma entrada `allowed_tools` ou uma regra de permissão de configurações aprova

1220* Uma chamada que o modo de permissão aprova, como uma edição de arquivo no modo `acceptEdits`

1221 

1222Para verificar essas chamadas, use um [hook `PreToolUse`](https://code.claude.com/docs/pt/agent-sdk/hooks), que também é executado para elas.

1218 1223 

1219Uma regra de permissão não pré-aprova as [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves); veja [Como permissões são avaliadas](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) para qual delas chega ao callback e o que acontece em modo `dontAsk` e `auto`.1224Uma regra de permissão não pré-aprova as [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves); veja [Como permissões são avaliadas](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) para qual delas chega ao callback e o que acontece em modo `dontAsk` e `auto`.

1220 1225 


3659 3664 

3660> [!NOTE]3665> [!NOTE]

3661>3666>

3662> O proxy de sandbox integrado aplica a lista de permissões de rede com base no nome de host solicitado e não encerra ou inspeciona tráfego TLS, portanto técnicas como [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) podem potencialmente contorná-lo. Veja [Limitações de segurança de Sandboxing](https://code.claude.com/docs/pt/sandboxing.md#security-limitations) para detalhes e [Implantação segura](https://code.claude.com/docs/pt/agent-sdk/secure-deployment.md#traffic-forwarding) para configurar um proxy que encerra TLS.3667> O proxy de sandbox integrado aplica a allowlist de rede com base no nome de host solicitado. Por padrão, o proxy não encerra nem inspeciona tráfego TLS, portanto técnicas como [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) podem potencialmente contornar a allowlist. Veja [Limitações de segurança de Sandboxing](https://code.claude.com/docs/pt/sandboxing.md#security-limitations) para detalhes e [Implantação segura](https://code.claude.com/docs/pt/agent-sdk/secure-deployment.md#traffic-forwarding) para configurar um proxy que encerra TLS.

3663 3668 

3664### `SandboxIgnoreViolations`3669### `SandboxIgnoreViolations`

3665 3670 

Details

22 22 

23Claude Code inclui vários recursos de segurança que abordam preocupações comuns. Consulte a [documentação de segurança](https://code.claude.com/docs/pt/security.md) para detalhes completos.23Claude Code inclui vários recursos de segurança que abordam preocupações comuns. Consulte a [documentação de segurança](https://code.claude.com/docs/pt/security.md) para detalhes completos.

24 24 

25* **Sistema de permissões**: Cada ferramenta e comando bash pode ser configurado para permitir, bloquear ou solicitar aprovação do usuário. Use padrões glob para criar regras como "permitir todos os comandos npm" ou "bloquear qualquer comando com sudo". As organizações podem definir políticas que se aplicam a todos os usuários. Consulte [permissões](https://code.claude.com/docs/pt/permissions.md).25* **Sistema de permissões**: As regras de permissão decidem se uma chamada de ferramenta é executada, bloqueada ou solicita aprovação primeiro. Para as formas que uma regra de Bash não captura e como as regras se combinam com os modos de permissão, consulte [O que uma regra de Bash não corresponde](https://code.claude.com/docs/pt/permissions.md#bash-rule-limits) e [Configurar permissões](https://code.claude.com/docs/pt/agent-sdk/permissions.md). Os administradores também podem definir regras em [configurações gerenciadas](https://code.claude.com/docs/pt/permissions.md#managed-settings).

26* **Análise de comando para permissões**: Antes de executar comandos bash, Claude Code os analisa em uma AST e compara o resultado com suas regras de permissão. Comandos que não podem ser analisados corretamente ou que não correspondem a uma regra de permissão requerem aprovação explícita. Um pequeno conjunto de construções como `eval` sempre requer aprovação independentemente das regras de permissão. Esta é uma porta de permissão, não uma sandbox; além das verificações de segurança integradas, como a [verificação de caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#critical-paths) em `rm` e `rmdir` e a lista de [caminhos protegidos](https://code.claude.com/docs/pt/permission-modes.md#protected-paths), ela não infere se um comando é perigoso a partir de seu caminho de destino ou efeitos.26* **Remoções de caminho crítico**: Com o modo de permissão definido como `default`, um comando `rm` ou `rmdir` reconhecido como removendo seu diretório de trabalho ou outro [caminho crítico](https://code.claude.com/docs/pt/permission-modes.md#critical-paths) requer aprovação. Uma regra de permissão allow correspondente não dispensa essa aprovação. Esta é uma porta de permissão, não um sandbox. Para controlar o que o agente pode gravar, use [controles do sistema de arquivos](#filesystem-configuration).

27* **Resumo de pesquisa na web**: Os resultados da pesquisa são resumidos em vez de passar o conteúdo bruto diretamente para o contexto, reduzindo o risco de injeção de prompt de conteúdo web malicioso.27* **Resumo de pesquisa na web**: Os resultados da pesquisa são resumidos em vez de passar o conteúdo bruto diretamente para o contexto, reduzindo o risco de injeção de prompt de conteúdo web malicioso.

28* **Modo sandbox**: Comandos Bash podem ser executados em um ambiente sandboxed que restringe acesso ao sistema de arquivos e rede. Consulte a [documentação de sandboxing](https://code.claude.com/docs/pt/sandboxing.md) para detalhes.28* **Modo sandbox**: Comandos Bash podem ser executados em um ambiente sandboxed que restringe acesso ao sistema de arquivos e rede. Consulte a [documentação de sandboxing](https://code.claude.com/docs/pt/sandboxing.md) para detalhes.

29 29 


61 61 

62## Tecnologias de isolamento62## Tecnologias de isolamento

63 63 

64Diferentes tecnologias de isolamento oferecem diferentes compensações entre força de segurança, desempenho e complexidade operacional.64Diferentes tecnologias de isolamento oferecem diferentes compensações entre nível de segurança, desempenho e complexidade operacional.

65 65 

66> [!NOTE]66> [!NOTE]

67>67>

68> Em todas essas configurações, Claude Code (ou sua aplicação Agent SDK) é executado dentro do limite de isolamento (a sandbox, contêiner ou VM). Os controles de segurança descritos abaixo restringem o que o agente pode acessar de dentro desse limite.68> Em todas essas configurações, o Claude Code (ou sua aplicação do Agent SDK) é executado dentro da fronteira de isolamento (o sandbox, o contêiner ou a VM). Os controles de segurança descritos abaixo restringem o que o agente pode acessar a partir dessa fronteira.

69 69 

70| Tecnologia | Força de isolamento | Sobrecarga de desempenho | Complexidade |70| Tecnologia | Nível de isolamento | Sobrecarga de desempenho | Complexidade |

71| - | - | - | - |71| - | - | - | - |

72| Sandbox runtime | Boa (padrões seguros) | Muito baixa | Baixa |72| Sandbox runtime | Bom (padrões seguros) | Muito baixa | Baixa |

73| Contêineres (Docker) | Dependente da configuração | Baixa | Média |73| Contêineres (Docker) | Depende da configuração | Baixa | Média |

74| gVisor | Excelente (com configuração correta) | Média/Alta | Média |74| gVisor | Excelente (com configuração correta) | Média/Alta | Média |

75| VMs (Firecracker, QEMU) | Excelente (com configuração correta) | Alta | Média/Alta |75| VMs (Firecracker, QEMU) | Excelente (com configuração correta) | Alta | Média/Alta |

76 76 

77### Sandbox runtime77### Sandbox runtime

78 78 

79Para isolamento leve sem contêineres, [sandbox-runtime](https://github.com/anthropics/sandbox-runtime) impõe restrições de sistema de arquivos e rede no nível do SO.79Para um isolamento leve sem contêineres, o [sandbox-runtime](https://github.com/anthropics/sandbox-runtime) aplica restrições de sistema de arquivos e de rede no nível do sistema operacional.

80 80 

81A principal vantagem é a simplicidade: nenhuma configuração Docker, imagens de contêiner ou configuração de rede necessária. O proxy e as restrições de sistema de arquivos são integrados.81A principal vantagem é a simplicidade: não é necessária configuração do Docker, imagens de contêiner nem configuração de rede. O proxy e as restrições de sistema de arquivos já vêm integrados.

82 82 

83**Como funciona:**83**Como funciona:**

84 84 

85* **Sistema de arquivos**: Usa primitivos do SO (`bubblewrap` no Linux, `sandbox-exec` no macOS) para restringir acesso de leitura/escrita a caminhos configurados85* **Sistema de arquivos**: usa primitivas do sistema operacional (`bubblewrap` no Linux, `sandbox-exec` no macOS) para restringir o acesso de leitura/gravação aos caminhos configurados

86* **Rede**: Remove namespace de rede (Linux) ou usa perfis Seatbelt (macOS) para rotear tráfego de rede através de um proxy integrado86* **Rede**: executa os comandos em seu próprio namespace de rede (Linux) ou sob um perfil Seatbelt (macOS) e roteia o tráfego deles por um proxy integrado que permite os domínios configurados. Uma conexão com um host externo que ignora o proxy falha.

87* **Configuração**: Listas de permissão baseadas em JSON para domínios e caminhos do sistema de arquivos87* **Configuração**: allowlists baseadas em JSON para domínios e caminhos do sistema de arquivos

88 88 

89**Configuração:**89**Configuração inicial:**

90 90 

91```bash theme={null}91Para as etapas de instalação, configuração e inicialização, consulte [Configurar e iniciar o runtime](https://code.claude.com/docs/pt/sandbox-environments.md#set-up-and-launch-the-runtime).

92npm install @anthropic-ai/sandbox-runtime

93```

94 

95Em seguida, crie um arquivo de configuração especificando caminhos e domínios permitidos.

96 92 

97**Considerações de segurança:**93**Considerações de segurança:**

98 94 

991. **Kernel no mesmo host**: Ao contrário das VMs, processos sandboxed compartilham o kernel do host. Uma vulnerabilidade do kernel poderia teoricamente permitir escape. Para alguns modelos de ameaça isso é aceitável, mas se você precisar de isolamento no nível do kernel, use gVisor ou uma VM separada.951. **Kernel do mesmo host**: diferentemente das VMs, os processos em sandbox compartilham o kernel do host. Uma vulnerabilidade no kernel poderia, teoricamente, permitir uma fuga. Para alguns modelos de ameaça isso é aceitável, mas se você precisar de isolamento no nível do kernel, use gVisor ou uma VM separada.

96 

972. **Sem inspeção de TLS**: por padrão, o proxy filtra os domínios com base na allowlist usando o nome de host fornecido pelo cliente e não encerra nem inspeciona o tráfego criptografado. O código executado dentro do sandbox pode potencialmente usar [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) ou técnicas semelhantes para alcançar hosts fora da allowlist. Se o seu modelo de ameaça exigir garantias mais fortes, use um proxy que encerre o TLS e inspecione o tráfego, conforme descrito em [Encaminhamento de tráfego](#traffic-forwarding). Para mais informações, consulte as [limitações de segurança do sandboxing](https://code.claude.com/docs/pt/sandboxing.md#security-limitations).

100 98 

1012. **Sem inspeção TLS**: O proxy lista domínios permitidos com base no nome do host fornecido pelo cliente e não termina ou inspeciona tráfego criptografado. O código executado dentro da sandbox pode potencialmente usar [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) ou técnicas semelhantes para alcançar hosts fora da lista de permissões. Se seu modelo de ameaça requer garantias mais fortes, configure um [proxy que termina TLS](#traffic-forwarding). Consulte as [limitações de segurança de sandboxing](https://code.claude.com/docs/pt/sandboxing.md#security-limitations) para mais detalhes. Separadamente, se o agente tiver credenciais permissivas para um domínio permitido, certifique-se de que ele não possa usar esse domínio para disparar outras solicitações de rede ou para exfiltrar dados.993. **Credenciais para domínios permitidos**: se o agente tiver credenciais permissivas para um domínio permitido, certifique-se de que ele não possa usar esse domínio para disparar outras requisições de rede ou para exfiltrar dados.

102 100 

103Para muitos casos de uso de desenvolvedor único e CI/CD, sandbox-runtime aumenta significativamente a barra com configuração mínima. As seções abaixo cobrem contêineres e VMs para implantações que requerem isolamento mais forte.101Para muitos casos de uso de desenvolvedor individual e de CI/CD, o sandbox-runtime eleva significativamente o nível de segurança com configuração mínima. As seções abaixo abordam contêineres e VMs para implantações que exigem um isolamento mais forte.

104 102 

105### Contêineres103### Contêineres

106 104 

107Contêineres fornecem isolamento através de namespaces Linux. Cada contêiner tem sua própria visão do sistema de arquivos, árvore de processos e pilha de rede, enquanto compartilha o kernel do host.105Os contêineres oferecem isolamento por meio de namespaces do Linux. Cada contêiner tem sua própria visão do sistema de arquivos, da árvore de processos e da pilha de rede, enquanto compartilha o kernel do host.

108 106 

109Uma configuração de contêiner endurecida para segurança pode parecer assim:107Uma configuração de contêiner com segurança reforçada pode ser assim:

110 108 

111```bash theme={null}109```bash theme={null}

112docker run \110docker run \


126 agent-image124 agent-image

127```125```

128 126 

129Aqui está o que cada opção faz:127Veja o que cada opção faz:

130 128 

131| Opção | Propósito |129| Opção | Finalidade |

132| - | - |130| - | - |

133| `--cap-drop ALL` | Remove capacidades Linux como `NET_ADMIN` e `SYS_ADMIN` que poderiam permitir escalação de privilégio |131| `--cap-drop ALL` | Remove capabilities do Linux como `NET_ADMIN` e `SYS_ADMIN`, que poderiam permitir escalonamento de privilégios |

134| `--security-opt no-new-privileges` | Impede que processos ganhem privilégios através de binários setuid |132| `--security-opt no-new-privileges` | Impede que processos obtenham privilégios por meio de binários setuid |

135| `--security-opt seccomp=...` | Restringe syscalls disponíveis; o padrão do Docker bloqueia \~44, perfis personalizados podem bloquear mais |133| `--security-opt seccomp=...` | Restringe as syscalls disponíveis; o padrão do Docker bloqueia cerca de 44, e perfis personalizados podem bloquear mais |

136| `--read-only` | Torna o sistema de arquivos raiz do contêiner imutável, impedindo que o agente persista mudanças |134| `--read-only` | Torna o sistema de arquivos raiz do contêiner imutável, impedindo que o agente persista alterações |

137| `--tmpfs /tmp:...` | Fornece um diretório temporário gravável que é limpo quando o contêiner para |135| `--tmpfs /tmp:...` | Fornece um diretório temporário gravável que é limpo quando o contêiner para |

138| `--network none` | Remove todas as interfaces de rede; o agente se comunica através do socket Unix montado abaixo |136| `--network none` | Isola o contêiner das redes externas |

139| `--memory 2g` | Limita o uso de memória para evitar esgotamento de recursos |137| `--memory 2g` | Limita o uso de memória RAM para evitar esgotamento de recursos |

140| `--pids-limit 100` | Limita a contagem de processos para evitar fork bombs |138| `--pids-limit 100` | Limita a quantidade de processos para evitar fork bombs |

141| `--user 1000:1000` | Executa como um usuário não-root |139| `--user 1000:1000` | Executa como um usuário não root |

142| `-v ...:/workspace:ro` | Monta código somente leitura para que o agente possa analisar mas não modificar. **Evite montar diretórios sensíveis do host como `~/.ssh`, `~/.aws`, ou `~/.config`** |140| `-v ...:/workspace:ro` | Monta o código como somente leitura para que o agente possa analisá-lo, mas não modificá-lo. **Evite montar diretórios sensíveis do host, como `~/.ssh`, `~/.aws` ou `~/.config`** |

143| `-v .../proxy.sock:...` | Monta um socket Unix conectado a um proxy executado fora do contêiner (veja abaixo) |141| `-v .../proxy.sock:...` | Monta um socket Unix conectado a um proxy executado fora do contêiner (veja abaixo) |

144 142 

145**Arquitetura de socket Unix:**143**Arquitetura de socket Unix:**

146 144 

147Com `--network none`, o contêiner não tem interfaces de rede. A única maneira para o agente alcançar o mundo externo é através do socket Unix montado, que se conecta a um proxy executado no host. Este proxy pode impor listas de permissão de domínio, injetar credenciais e registrar todo o tráfego.145Com `--network none`, uma consulta DNS ou uma conexão direta com outro host falha dentro do contêiner. Para permitir que o código no contêiner alcance outros hosts, execute um proxy no host e monte o socket Unix dele no contêiner. Se você apontar `ANTHROPIC_BASE_URL` ou `HTTP_PROXY` para uma porta em `localhost`, como mostrado em [Configurar o Claude Code para usar um proxy](#configuring-claude-code-to-use-a-proxy), retransmita essa porta dentro do contêiner para o socket.

148 146 

149Esta é a mesma arquitetura usada por [sandbox-runtime](https://github.com/anthropics/sandbox-runtime). Mesmo que o agente seja comprometido via injeção de prompt, ele não pode exfiltrar dados para servidores arbitrários. Ele só pode se comunicar através do proxy, que controla quais domínios são alcançáveis. Para mais detalhes, consulte o [blog de sandboxing do Claude Code](https://www.anthropic.com/engineering/claude-code-sandboxing).147Você pode configurar esse proxy para aplicar allowlists de domínios, injetar credenciais e registrar todo o tráfego em log.

148 

149> [!WARNING]

150>

151> Dentro da allowlist do seu proxy, o agente pode enviar dados para qualquer domínio permitido. Permita apenas os domínios de que o agente precisa.

150 152 

151**Opções de endurecimento adicional:**153**Opções adicionais de reforço de segurança:**

152 154 

153| Opção | Propósito |155| Opção | Finalidade |

154| - | - |156| - | - |

155| `--userns-remap` | Mapeia root do contêiner para usuário host sem privilégios; requer configuração do daemon mas limita danos de escape de contêiner |157| `--userns-remap` | Mapeia o root do contêiner para um usuário sem privilégios no host; requer configuração do daemon, mas limita os danos de uma fuga do contêiner |

156| `--ipc private` | Isola comunicação entre processos para evitar ataques entre contêineres |158| `--ipc private` | Isola a comunicação entre processos para evitar ataques entre contêineres |

157 159 

158### gVisor160### gVisor

159 161 

160Contêineres padrão compartilham o kernel do host: quando código dentro de um contêiner faz uma chamada de sistema, ela vai diretamente para o mesmo kernel que executa o host. Isso significa que uma vulnerabilidade do kernel poderia permitir escape de contêiner. gVisor aborda isso interceptando chamadas de sistema no espaço do usuário antes de chegarem ao kernel do host, implementando sua própria camada de compatibilidade que lida com a maioria das syscalls sem envolver o kernel real.162Contêineres padrão compartilham o kernel do host: quando o código dentro de um contêiner faz uma chamada de sistema, ela vai diretamente para o mesmo kernel que executa o host. Isso significa que uma vulnerabilidade no kernel poderia permitir a fuga do contêiner. O gVisor resolve isso interceptando as chamadas de sistema no espaço do usuário antes que cheguem ao kernel do host, implementando sua própria camada de compatibilidade que trata a maioria das syscalls sem envolver o kernel real.

161 163 

162Se um agente executa código malicioso (talvez devido a injeção de prompt), esse código é executado no contêiner e poderia tentar exploits do kernel. Com gVisor, a superfície de ataque é muito menor: o código malicioso precisaria explorar a implementação do espaço do usuário do gVisor primeiro e teria acesso limitado ao kernel real.164Se um agente executar código malicioso (talvez devido a uma injeção de prompt), esse código será executado no contêiner e poderá tentar explorar o kernel. Com o gVisor, a superfície de ataque é muito menor: o código malicioso precisaria primeiro explorar a implementação do gVisor no espaço do usuário e teria acesso limitado ao kernel real.

163 165 

164Para usar gVisor com Docker, instale o runtime `runsc` e configure o daemon:166Para usar o gVisor com o Docker, instale o runtime `runsc` e configure o daemon:

165 167 

166```json /etc/docker/daemon.json theme={null}168```json /etc/docker/daemon.json theme={null}

167{169{


173}175}

174```176```

175 177 

176Em seguida, execute contêineres com:178Em seguida, execute os contêineres com:

177 179 

178```bash theme={null}180```bash theme={null}

179docker run --runtime=runsc agent-image181docker run --runtime=runsc agent-image


183 185 

184| Carga de trabalho | Sobrecarga |186| Carga de trabalho | Sobrecarga |

185| - | - |187| - | - |

186| Computação vinculada à CPU | \~0% (sem interceptação de syscall) |188| Computação limitada por CPU | \~0% (sem interceptação de syscalls) |

187| Syscalls simples | \~2× mais lento |189| Syscalls simples | \~2× mais lento |

188| Intensivo em I/O de arquivo | Até 10-200× mais lento para padrões pesados de open/close |190| Uso intensivo de E/S de arquivos | Até 10-200× mais lento para padrões intensos de abertura/fechamento |

189 191 

190Para ambientes multi-tenant ou ao processar conteúdo não confiável, o isolamento adicional geralmente vale a sobrecarga.192Para ambientes multilocatário ou ao processar conteúdo não confiável, o isolamento adicional geralmente compensa a sobrecarga.

191 193 

192### Máquinas virtuais194### Máquinas virtuais

193 195 

194VMs fornecem isolamento no nível de hardware através de extensões de virtualização de CPU. Cada VM executa seu próprio kernel, criando um limite forte. Uma vulnerabilidade no kernel convidado não compromete diretamente o host. No entanto, VMs não são automaticamente "mais seguras" do que alternativas como gVisor. A segurança da VM depende muito do hipervisor e do código de emulação de dispositivo.196As VMs oferecem isolamento no nível de hardware por meio de extensões de virtualização da CPU. Cada VM executa seu próprio kernel, criando uma fronteira forte. Uma vulnerabilidade no kernel convidado não compromete diretamente o host. No entanto, as VMs não são automaticamente "mais seguras" do que alternativas como o gVisor. A segurança das VMs depende muito do hipervisor e do código de emulação de dispositivos.

195 197 

196Firecracker é projetado para isolamento leve de microVM. Pode inicializar VMs em menos de 125ms com menos de 5 MiB de sobrecarga de memória, removendo emulação de dispositivo desnecessária para reduzir a superfície de ataque.198O Firecracker foi projetado para isolamento leve com microVMs. Ele consegue inicializar VMs em menos de 125 ms com menos de 5 MiB de sobrecarga de memória RAM, eliminando a emulação de dispositivos desnecessária para reduzir a superfície de ataque.

197 199 

198Com essa abordagem, a VM do agente não tem interface de rede externa. Em vez disso, ela se comunica através de `vsock` (sockets virtuais). Todo o tráfego é roteado através de vsock para um proxy no host, que impõe listas de permissão e injeta credenciais antes de encaminhar solicitações.200Com essa abordagem, a VM do agente não tem interface de rede externa. Em vez disso, ela se comunica por meio de `vsock` (sockets virtuais). Todo o tráfego é roteado pelo vsock até um proxy no host, que aplica as allowlists e injeta credenciais antes de encaminhar as requisições.

199 201 

200### Implantações em nuvem202### Implantações em nuvem

201 203 

202Para implantações em nuvem, você pode combinar qualquer uma das tecnologias de isolamento acima com controles de rede nativos da nuvem:204Para implantações em nuvem, você pode combinar qualquer uma das tecnologias de isolamento acima com controles de rede nativos da nuvem:

203 205 

2041. Execute contêineres de agente em uma sub-rede privada sem gateway de internet2061. Execute os contêineres do agente em uma sub-rede privada sem gateway de internet

2052. Configure regras de firewall em nuvem (AWS Security Groups, firewall VPC do GCP) para bloquear toda saída exceto para seu proxy2072. Configure regras de firewall da nuvem (AWS Security Groups, firewall de VPC do GCP) para bloquear todo o tráfego de saída, exceto para o seu proxy

2063. Execute um proxy (como [Envoy](https://www.envoyproxy.io/) com seu filtro `credential_injector`) que valida solicitações, impõe listas de permissão de domínio, injeta credenciais e encaminha para APIs externas2083. Execute um proxy (como o [Envoy](https://www.envoyproxy.io/) com seu filtro `credential_injector`) que valide as requisições, aplique allowlists de domínios, injete credenciais e encaminhe para APIs externas

2074. Atribua permissões IAM mínimas à conta de serviço do agente, roteando acesso sensível através do proxy quando possível2094. Atribua permissões mínimas de IAM à conta de serviço do agente, roteando o acesso sensível pelo proxy sempre que possível

2085. Registre todo o tráfego no proxy para fins de auditoria2105. Registre todo o tráfego em log no proxy para fins de auditoria

209 211 

210## Gerenciamento de credenciais212## Gerenciamento de credenciais

211 213 

Details

1340 | "default" // Standard permission behavior1340 | "default" // Standard permission behavior

1341 | "acceptEdits" // Auto-accept file edits1341 | "acceptEdits" // Auto-accept file edits

1342 | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt1342 | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt

1343 | "plan" // Planning mode - explore without editing1343 | "plan" // Planning mode - Claude explores and plans

1344 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved1344 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved

1345 | "auto"; // A model classifier reviews actions such as shell commands and network requests1345 | "auto"; // A model classifier reviews actions such as shell commands and network requests

1346```1346```


1349 1349 

1350Tipo de função de permissão personalizada para controlar o uso de ferramentas.1350Tipo de função de permissão personalizada para controlar o uso de ferramentas.

1351 1351 

1352A função é a substituta no SDK para o prompt de permissão interativo: ela é invocada somente quando o [fluxo de avaliação de permissões](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) resulta em um prompt. Chamadas de ferramenta já aprovadas por uma entrada de `allowedTools`, por uma regra de permissão nas configurações ou pelo modo de permissão, como `acceptEdits` ou `bypassPermissions`, nunca a invocam. Para controlar todas as chamadas de ferramenta, use um [hook `PreToolUse`](https://code.claude.com/docs/pt/agent-sdk/hooks).1352A função substitui o prompt de permissão interativo. O SDK chama `canUseTool` quando o [fluxo de avaliação de permissões](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) resulta em um prompt. Chamadas aprovadas de uma destas maneiras são executadas sem chamar `canUseTool`:

1353 

1354* Uma chamada que uma entrada de `allowedTools` ou uma regra de permissão das configurações aprova

1355* Uma chamada que o modo de permissão aprova, como uma edição de arquivo no modo `acceptEdits`

1356 

1357Para verificar essas chamadas, use um [hook `PreToolUse`](https://code.claude.com/docs/pt/agent-sdk/hooks), que também é executado para elas.

1353 1358 

1354Uma regra de permissão não pré-aprova as [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves); consulte [Como as permissões são avaliadas](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) para saber quais delas chegam ao callback e o que acontece nos modos `dontAsk` e `auto`.1359Uma regra de permissão não pré-aprova as [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves); consulte [Como as permissões são avaliadas](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) para saber quais delas chegam ao callback e o que acontece nos modos `dontAsk` e `auto`.

1355 1360 


2006* Uma retomada que Claude Code interrompe porque [não consegue retornar a sessão ao seu worktree](https://code.claude.com/docs/pt/worktrees.md#the-session-resumes-outside-its-worktree), com `worktree_unverified` ou `worktree_resume_refused`. Essa seção diz qual erro carrega qual valor.2011* Uma retomada que Claude Code interrompe porque [não consegue retornar a sessão ao seu worktree](https://code.claude.com/docs/pt/worktrees.md#the-session-resumes-outside-its-worktree), com `worktree_unverified` ou `worktree_resume_refused`. Essa seção diz qual erro carrega qual valor.

2007* Um [`continue`](#options) recusado de uma conversa que uma sessão em segundo plano mantém, com `session_held_by_background`. Para um [`resume`](#options) recusado de tal conversa, Claude Code escreve o resultado apenas quando a variável está definida.2012* Um [`continue`](#options) recusado de uma conversa que uma sessão em segundo plano mantém, com `session_held_by_background`. Para um [`resume`](#options) recusado de tal conversa, Claude Code escreve o resultado apenas quando a variável está definida.

2008* Uma inicialização que o Claude Code recusa porque [`failIfUnavailable`](#sandboxsettings) está ativado e o sandbox não consegue iniciar, com `sandbox_required_unavailable`.2013* Uma inicialização que o Claude Code recusa porque [`failIfUnavailable`](#sandboxsettings) está ativado e o sandbox não consegue iniciar, com `sandbox_required_unavailable`.

2014* Uma inicialização que o Claude Code recusa porque `~/.claude.json` não é um JSON válido, com `config_file_invalid`.

2009 2015 

2010O tipo `SDKStartupFailureReason` lista os valores que `startup_failure_reason` pode conter:2016O tipo `SDKStartupFailureReason` lista os valores que `startup_failure_reason` pode conter:

2011 2017 


2030 | "bypass_root"2036 | "bypass_root"

2031 | "org_config_required_unavailable"2037 | "org_config_required_unavailable"

2032 | "org_config_refused"2038 | "org_config_refused"

2033 | "sandbox_required_unavailable";2039 | "sandbox_required_unavailable"

2040 | "config_file_invalid";

2034```2041```

2035 2042 

2036Cada valor nomeia uma recusa:2043Cada valor nomeia uma recusa:


2057| `org_config_required_unavailable` | A sessão precisa das políticas e configurações gerenciadas da organização antes de poder iniciar, e elas não puderam ser carregadas, por exemplo por causa de uma falha de rede ou de um erro no servidor da Anthropic. Requer o Agent SDK v0.3.293 ou posterior |2064| `org_config_required_unavailable` | A sessão precisa das políticas e configurações gerenciadas da organização antes de poder iniciar, e elas não puderam ser carregadas, por exemplo por causa de uma falha de rede ou de um erro no servidor da Anthropic. Requer o Agent SDK v0.3.293 ou posterior |

2058| `org_config_refused` | A Anthropic se recusou a fornecer as políticas e configurações gerenciadas da organização para este login, por exemplo porque o login expirou ou foi revogado, ou porque a organização não permite o Claude Code para esta conta. Requer o Agent SDK v0.3.293 ou posterior |2065| `org_config_refused` | A Anthropic se recusou a fornecer as políticas e configurações gerenciadas da organização para este login, por exemplo porque o login expirou ou foi revogado, ou porque a organização não permite o Claude Code para esta conta. Requer o Agent SDK v0.3.293 ou posterior |

2059| `sandbox_required_unavailable` | [`failIfUnavailable`](#sandboxsettings) está ativado e o sandbox não consegue iniciar. O texto em `errors` termina com `Set sandbox.failIfUnavailable=false to allow unsandboxed execution.` Requer Agent SDK v0.3.314 ou posterior |2066| `sandbox_required_unavailable` | [`failIfUnavailable`](#sandboxsettings) está ativado e o sandbox não consegue iniciar. O texto em `errors` termina com `Set sandbox.failIfUnavailable=false to allow unsandboxed execution.` Requer Agent SDK v0.3.314 ou posterior |

2067| `config_file_invalid` | `~/.claude.json` não é um JSON válido. O Claude Code mantém o arquivo inalterado, então uma nova tentativa falha da mesma forma até que alguém o repare. `errors` nomeia o arquivo e informa como restaurá-lo ou repará-lo. Consulte [Configuration error in \~/.claude.json](https://code.claude.com/docs/pt/errors.md#configuration-error-in-claude-json). Requer TypeScript Agent SDK v0.3.318 ou posterior e Claude Code v2.1.318 ou posterior |

2060 2068 

2061### `SDKSystemMessage`2069### `SDKSystemMessage`

2062 2070 


6108 6116 

6109> [!NOTE]6117> [!NOTE]

6110>6118>

6111> O proxy de sandbox integrado aplica `allowedDomains` com base no nome de host solicitado e não encerra ou inspeciona tráfego TLS, então técnicas como [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) podem potencialmente contorná-lo. Veja [Limitações de segurança do sandboxing](https://code.claude.com/docs/pt/sandboxing.md#security-limitations) para detalhes e [Implantação segura](https://code.claude.com/docs/pt/agent-sdk/secure-deployment.md#traffic-forwarding) para configurar um proxy que encerra TLS.6119> O proxy de sandbox integrado aplica `allowedDomains` com base no nome de host solicitado. Por padrão, o proxy não encerra nem inspeciona tráfego TLS, então técnicas como [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) podem potencialmente contornar `allowedDomains`. Veja [Limitações de segurança do sandboxing](https://code.claude.com/docs/pt/sandboxing.md#security-limitations) para detalhes e [Implantação segura](https://code.claude.com/docs/pt/agent-sdk/secure-deployment.md#traffic-forwarding) para configurar um proxy que encerra TLS.

6112 6120 

6113### `SandboxFilesystemConfig`6121### `SandboxFilesystemConfig`

6114 6122 

Details

47O callback é acionado em dois casos:47O callback é acionado em dois casos:

48 48 

491. **Ferramenta precisa de aprovação**: Claude quer usar uma ferramenta que não é aprovada automaticamente por uma [regra de permissão](https://code.claude.com/docs/pt/agent-sdk/permissions.md) ou modo de permissão. Verifique `tool_name` para a ferramenta (por exemplo, `"Bash"`, `"Write"`).491. **Ferramenta precisa de aprovação**: Claude quer usar uma ferramenta que não é aprovada automaticamente por uma [regra de permissão](https://code.claude.com/docs/pt/agent-sdk/permissions.md) ou modo de permissão. Verifique `tool_name` para a ferramenta (por exemplo, `"Bash"`, `"Write"`).

502. **Claude faz uma pergunta**: Claude chama a ferramenta `AskUserQuestion`. Verifique se `tool_name == "AskUserQuestion"` para tratá-la diferentemente. Se você especificar um array `tools`, inclua `AskUserQuestion` para que isso funcione. Veja [Lidar com perguntas de esclarecimento](#handle-clarifying-questions) para detalhes.502. **Claude faz uma pergunta**: Claude chama a ferramenta `AskUserQuestion`. Verifique se `tool_name == "AskUserQuestion"` para tratá-la diferentemente. Se você especificar um array `tools`, inclua `AskUserQuestion` para que isso funcione. Para mais informações, veja [Lidar com perguntas de esclarecimento](#handle-clarifying-questions).

51 51 

52> [!WARNING]52> [!WARNING]

53>53>

54> **O callback nunca é acionado para ferramentas aprovadas automaticamente.** Qualquer aprovação anterior no [fluxo de avaliação de permissões](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated), uma regra de permissão ou um modo como `acceptEdits` ou `bypassPermissions`, resolve a chamada antes que `canUseTool` seja consultado. Se você listar uma ferramenta diretamente em `allowed_tools`, uma verificação `canUseTool` para essa ferramenta é executada apenas quando o [fluxo de avaliação](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) roteia a chamada de volta para um prompt, como uma regra de pergunta ou modo `plan`. Para lógica que deve se aplicar a cada chamada de ferramenta, use um [hook `PreToolUse`](https://code.claude.com/docs/pt/agent-sdk/hooks), que é executado antes do resto do fluxo e pode permitir, negar ou modificar solicitações.54> **Uma etapa anterior pode permitir ou negar uma chamada antes que `canUseTool` seja executado.** O [fluxo de avaliação de permissões](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) verifica as regras de negação, o modo de permissão e as regras de permissão antes do seu callback.

55>55>

56> Uma regra de permissão não aprova previamente as [ações que nenhum modo aprova automaticamente](https://code.claude.com/docs/pt/permission-modes.md#actions-no-mode-auto-approves); veja [Como as permissões são avaliadas](https://code.claude.com/docs/pt/agent-sdk/permissions.md#how-permissions-are-evaluated) para saber quais delas chegam ao callback e o que acontece nos modos `dontAsk` e `auto`.56> Para executar suas verificações em chamadas que uma regra ou o modo de permissão já permitiu, use um [hook `PreToolUse`](https://code.claude.com/docs/pt/agent-sdk/hooks), que é executado para essas chamadas e pode permiti-las, negá-las ou modificá-las.

57 57 

58Você também pode usar o [hook `PermissionRequest`](https://code.claude.com/docs/pt/agent-sdk/hooks#available-hooks) para enviar notificações externas (Slack, email, push) quando Claude está aguardando aprovação.58Você também pode usar o [hook `PermissionRequest`](https://code.claude.com/docs/pt/agent-sdk/hooks#available-hooks) para enviar notificações externas (Slack, email, push) quando Claude está aguardando aprovação.

59 59 

agent-view.md +2 −2

Details

1020 1020 

1021No macOS, o host da sessão em background é executado como seu próprio processo e solicita acesso a pastas protegidas separadamente do seu terminal. Se uma sessão em background relatar `Operation not permitted` ao ler `~/Desktop`, `~/Documents`, `~/Downloads` ou outro local protegido, conceda acesso em Configurações do Sistema em Privacidade e Segurança > Arquivos e Pastas, ou ative Acesso Total ao Disco para a entrada.1021No macOS, o host da sessão em background é executado como seu próprio processo e solicita acesso a pastas protegidas separadamente do seu terminal. Se uma sessão em background relatar `Operation not permitted` ao ler `~/Desktop`, `~/Documents`, `~/Downloads` ou outro local protegido, conceda acesso em Configurações do Sistema em Privacidade e Segurança > Arquivos e Pastas, ou ative Acesso Total ao Disco para a entrada.

1022 1022 

1023Com o instalador nativo, a entrada aparece como Claude Code e a concessão persiste entre atualizações. Com outros métodos de instalação, como Homebrew ou npm, a entrada mostra o caminho do binário e pode precisar ser concedida novamente após atualizar.1023Em qualquer uma das listas, procure uma entrada chamada Claude Code, ou uma nomeada com o caminho ou o nome de arquivo do binário `claude`. Esse nome de arquivo pode ser um número de versão como `2.1.316`. Se `Operation not permitted` voltar a aparecer depois que Claude Code for atualizado, procure uma nova entrada, como uma nomeada com a nova versão. Se houver uma, conceda acesso a ela.

1024 1024 

1025### Background sessions can't reach local-network hosts on macOS1025### Background sessions can't reach local-network hosts on macOS

1026 1026 


1067| v2.1.296 | Um prompt ou comando shell `!` que você insere [enquanto a sessão se move para o background](#switch-sessions-without-leaving-the-terminal) é interrompido ou fica sem ser enviado, e seu texto é mantido no histórico de prompts. Antes desta versão, a resposta ou o comando continuava em execução onde você não podia mais vê-lo, e um prompt enviado logo após `←` poderia ser executado uma segunda vez sem ser visto. Um prompt digitado enquanto hooks `SessionStart` ainda estavam em execução era perdido: não era enviado e não ficava no histórico de prompts. |1067| v2.1.296 | Um prompt ou comando shell `!` que você insere [enquanto a sessão se move para o background](#switch-sessions-without-leaving-the-terminal) é interrompido ou fica sem ser enviado, e seu texto é mantido no histórico de prompts. Antes desta versão, a resposta ou o comando continuava em execução onde você não podia mais vê-lo, e um prompt enviado logo após `←` poderia ser executado uma segunda vez sem ser visto. Um prompt digitado enquanto hooks `SessionStart` ainda estavam em execução era perdido: não era enviado e não ficava no histórico de prompts. |

1068| v2.1.295 | `Ctrl+C` no prompt ocioso de uma [sessão em background anexada](#attach-to-a-session) deixa intacto o despertar pendente de um [`/loop` com ritmo próprio](https://code.claude.com/docs/pt/scheduled-tasks#let-claude-choose-the-interval), então pressioná-lo duas vezes desanexa e o loop continua em execução. `Esc` nesse prompt [para o loop com ritmo próprio](https://code.claude.com/docs/pt/scheduled-tasks.md#stop-a-loop) e mostra um aviso `Pending wakeup cancelled`. Antes desta versão, o primeiro `Ctrl+C` podia encerrar um loop com ritmo próprio sem avisar, e `Esc` não parava um loop que tinha se movido para o background com a sessão. |1068| v2.1.295 | `Ctrl+C` no prompt ocioso de uma [sessão em background anexada](#attach-to-a-session) deixa intacto o despertar pendente de um [`/loop` com ritmo próprio](https://code.claude.com/docs/pt/scheduled-tasks#let-claude-choose-the-interval), então pressioná-lo duas vezes desanexa e o loop continua em execução. `Esc` nesse prompt [para o loop com ritmo próprio](https://code.claude.com/docs/pt/scheduled-tasks.md#stop-a-loop) e mostra um aviso `Pending wakeup cancelled`. Antes desta versão, o primeiro `Ctrl+C` podia encerrar um loop com ritmo próprio sem avisar, e `Esc` não parava um loop que tinha se movido para o background com a sessão. |

1069| v2.1.295 | No macOS e Linux, quando `claude agents` sai enquanto nenhum [supervisor](#keep-sessions-running-after-the-supervisor-stops) está em execução, ele não inicia um novo por conta própria. As sessões em execução então param cerca de um minuto depois, a menos que você execute `claude agents` novamente, e agent view pode imprimir um aviso dizendo isso ao sair. Antes desta versão, o `claude agents` que estava saindo iniciava um novo supervisor. |1069| v2.1.295 | No macOS e Linux, quando `claude agents` sai enquanto nenhum [supervisor](#keep-sessions-running-after-the-supervisor-stops) está em execução, ele não inicia um novo por conta própria. As sessões em execução então param cerca de um minuto depois, a menos que você execute `claude agents` novamente, e agent view pode imprimir um aviso dizendo isso ao sair. Antes desta versão, o `claude agents` que estava saindo iniciava um novo supervisor. |

1070| v2.1.295 | No macOS com o instalador nativo, sessões em background que reiniciam juntas após uma atualização são executadas sob a mesma entrada do Claude Code que detém o [acesso a pastas protegidas](#background-sessions-can’t-read-desktop-documents-or-downloads-on-macos) que você concedeu. Antes desta versão, essas sessões podiam ser executadas sob o caminho do próprio binário. O macOS lista esse caminho como uma entrada separada, então as solicitações de acesso a pastas podiam voltar após uma atualização. |1070| v2.1.295 | No macOS com o instalador nativo, sessões em background que reiniciam juntas após uma atualização executam seus processos host a partir da mesma pasta `~/.local/share/claude/ClaudeCode.app`. Antes desta versão, esses processos podiam ser executados a partir do caminho do próprio binário. O macOS pode listar esse caminho como uma entrada separada, então as [solicitações de acesso a pastas](#background-sessions-can’t-read-desktop-documents-or-downloads-on-macos) podiam voltar após uma atualização. |

1071| v2.1.290 | [`claude attach` e `claude logs`](#manage-sessions-from-the-shell) podem receber parte do nome de uma sessão no lugar do ID. |1071| v2.1.290 | [`claude attach` e `claude logs`](#manage-sessions-from-the-shell) podem receber parte do nome de uma sessão no lugar do ID. |

1072| v2.1.290 | `/model`, `/effort`, `/rename` e `/usage` enviados como uma [resposta pela espiada](#peek-and-reply) para uma sessão em funcionamento são executados imediatamente. |1072| v2.1.290 | `/model`, `/effort`, `/rename` e `/usage` enviados como uma [resposta pela espiada](#peek-and-reply) para uma sessão em funcionamento são executados imediatamente. |

1073| v2.1.290 | Uma [resposta pela espiada](#peek-and-reply) que não pode ser entregue não é mais salva para o próximo reinício quando começa com `/`, ou quando responde a uma pergunta com opções predefinidas enquanto o processo da sessão está em execução. |1073| v2.1.290 | Uma [resposta pela espiada](#peek-and-reply) que não pode ser entregue não é mais salva para o próximo reinício quando começa com `/`, ou quando responde a uma pergunta com opções predefinidas enquanto o processo da sessão está em execução. |

Details

459export ANTHROPIC_BEDROCK_SERVICE_TIER=priority459export ANTHROPIC_BEDROCK_SERVICE_TIER=priority

460```460```

461 461 

462Claude Code envia isso como o cabeçalho `X-Amzn-Bedrock-Service-Tier` em cada solicitação. A disponibilidade de camada varia por modelo e região. A capacidade reservada usa um [ARN de throughput provisionado](https://docs.aws.amazon.com/bedrock/latest/userguide/prov-throughput.html) como o ID do modelo em vez desta configuração.462Claude Code envia isso como o cabeçalho `X-Amzn-Bedrock-Service-Tier` em cada requisição da [Invoke API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) feita por uma sessão que tenha a variável, exceto em suas [verificações de acesso ao modelo](#startup-model-checks). Defini-la não tem efeito em requisições para o [endpoint Mantle](#use-the-mantle-endpoint) ou feitas por meio de um [gateway de apps Claude](https://code.claude.com/docs/pt/claude-apps-gateway). A disponibilidade de camada varia por modelo e região. A capacidade reservada usa um ARN de [throughput provisionado](https://docs.aws.amazon.com/bedrock/latest/userguide/prov-throughput.html) como o ID do modelo em vez desta configuração.

463 

464Para abranger [sessões em segundo plano](https://code.claude.com/docs/pt/agent-view.md#settings-and-provider) que você inicia a partir de um terminal, defina `ANTHROPIC_BEDROCK_SERVICE_TIER` no bloco [`env`](https://code.claude.com/docs/pt/settings-reference#env) das suas configurações. Essas sessões recebem o valor que você exporta somente quando o shell que iniciou o [supervisor](https://code.claude.com/docs/pt/agent-view.md#the-supervisor-process) o exportou.

463 465 

464## AWS Guardrails466## AWS Guardrails

465 467 


487 489 

488### Habilitar Mantle490### Habilitar Mantle

489 491 

490Com credenciais AWS já configuradas, defina `CLAUDE_CODE_USE_MANTLE` para rotear solicitações para o endpoint Mantle:492Com credenciais AWS já configuradas, defina `CLAUDE_CODE_USE_MANTLE` e sua região AWS:

491 493 

492```bash theme={null}494```bash theme={null}

493export CLAUDE_CODE_USE_MANTLE=1495export CLAUDE_CODE_USE_MANTLE=1


587 589 

588* Especifique o modelo como um ID de [perfil de inferência](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)590* Especifique o modelo como um ID de [perfil de inferência](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)

589 591 

590Claude Code usa a [API Invoke](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html) do Amazon Bedrock e não suporta a API Converse.

591 

592### Erros de streaming atrás de um gateway ou proxy592### Erros de streaming atrás de um gateway ou proxy

593 593 

594Amazon Bedrock transmite respostas `InvokeModelWithResponseStream` em um formato de evento binário event-stream com o cabeçalho `Content-Type: application/vnd.amazon.eventstream`. Um gateway ou proxy entre Claude Code e Amazon Bedrock deve encaminhar o corpo da resposta e seus cabeçalhos, incluindo `Content-Type`, exatamente como Amazon Bedrock os enviou.594Amazon Bedrock transmite respostas `InvokeModelWithResponseStream` em um formato de evento binário event-stream com o cabeçalho `Content-Type: application/vnd.amazon.eventstream`. Um gateway ou proxy entre Claude Code e Amazon Bedrock deve encaminhar o corpo da resposta e seus cabeçalhos, incluindo `Content-Type`, exatamente como Amazon Bedrock os enviou.


618* Se o erro nomeia uma ação `bedrock-mantle:`, conceda à sua identidade IAM essa ação.618* Se o erro nomeia uma ação `bedrock-mantle:`, conceda à sua identidade IAM essa ação.

619* Se o erro não nomeia nenhuma ação e suas credenciais são válidas, sua conta AWS não foi concedida acesso ao modelo que você solicitou. Entre em contato com sua equipe de conta AWS para solicitar acesso.619* Se o erro não nomeia nenhuma ação e suas credenciais são válidas, sua conta AWS não foi concedida acesso ao modelo que você solicitou. Entre em contato com sua equipe de conta AWS para solicitar acesso.

620 620 

621Um `400` que nomeia o ID do modelo significa que esse modelo não é servido no Mantle. Mantle tem seu próprio lineup de modelo separado do catálogo Amazon Bedrock padrão, então IDs de perfil de inferência como `us.anthropic.claude-sonnet-4-6` não funcionarão. Use um ID de formato Mantle, ou habilite [ambos os endpoints](#run-mantle-alongside-the-invoke-api) para que Claude Code roteia cada solicitação para o endpoint onde o modelo está disponível.621Um `400` que nomeia o ID do modelo significa que esse modelo não é servido no Mantle. Mantle tem seu próprio lineup de modelo separado do catálogo Amazon Bedrock padrão, então IDs de perfil de inferência como `us.anthropic.claude-sonnet-4-6` não funcionam. Use um ID de formato Mantle, ou habilite [ambos os endpoints](#run-mantle-alongside-the-invoke-api) para que Claude Code envie IDs de perfil de inferência para a API Invoke.

622 622 

623## Recursos adicionais623## Recursos adicionais

624 624 

Details

155- Integration tests need DATABASE_URL set, see .env.example155- Integration tests need DATABASE_URL set, see .env.example

156```156```

157 157 

158Em uma sessão, execute `/context` para confirmar que Claude carregou o arquivo.158Em uma sessão, execute [`/context all`](https://code.claude.com/docs/pt/commands#all-commands) para confirmar que Claude carregou o arquivo.

159 159 

160Observe que a linha de typecheck é apenas o comando. Claude precisa conhecer o comando para poder verificar o próprio trabalho à medida que avança. Se você também quiser que o Claude Code *imponha* um typecheck aprovado antes que Claude termine, isso é tarefa para um [hook `Stop`](#enforce-the-check-with-a-stop-hook). Uma linha como `Always typecheck before you finish` neste arquivo funciona na maioria das vezes, não em todas.160Observe que a linha de typecheck é apenas o comando. Claude precisa conhecer o comando para poder verificar o próprio trabalho à medida que avança. Se você também quiser que o Claude Code *imponha* um typecheck aprovado antes que Claude termine, isso é tarefa para um [hook `Stop`](#enforce-the-check-with-a-stop-hook). Uma linha como `Always typecheck before you finish` neste arquivo funciona na maioria das vezes, não em todas.

161 161 


544Em um script, você quase sempre vai querer mais algumas flags:544Em um script, você quase sempre vai querer mais algumas flags:

545 545 

546* [`--bare`](https://code.claude.com/docs/pt/headless#start-faster-with-bare-mode) ignora hooks, skills, plugins, servidores MCP e arquivos `CLAUDE.md`, tanto os do repositório quanto os da máquina, para que a execução faça a mesma coisa onde quer que seja executada. Ela também nunca toca no seu login do claude.ai: a autenticação vem de `ANTHROPIC_API_KEY`, de um `apiKeyHelper` no arquivo que você passa com `--settings` ou das credenciais do seu provedor de nuvem.546* [`--bare`](https://code.claude.com/docs/pt/headless#start-faster-with-bare-mode) ignora hooks, skills, plugins, servidores MCP e arquivos `CLAUDE.md`, tanto os do repositório quanto os da máquina, para que a execução faça a mesma coisa onde quer que seja executada. Ela também nunca toca no seu login do claude.ai: a autenticação vem de `ANTHROPIC_API_KEY`, de um `apiKeyHelper` no arquivo que você passa com `--settings` ou das credenciais do seu provedor de nuvem.

547* `--append-system-prompt`, `--mcp-config` e `--settings` passam explicitamente o que a execução *de fato* precisa.547* `--append-system-prompt`, `--mcp-config` e `--settings` passam explicitamente o que a execução *de fato* precisa. Hooks que você passa com `--settings` [não são executados com `--bare`](https://code.claude.com/docs/pt/headless#start-faster-with-bare-mode), então não use `--bare` em uma execução que precise deles.

548* `--allowedTools` pré-aprova as ferramentas dela, e [`--permission-mode dontAsk`](https://code.claude.com/docs/pt/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) recusa qualquer outra coisa que teria gerado um prompt.548* `--allowedTools` pré-aprova as ferramentas dela, e [`--permission-mode dontAsk`](https://code.claude.com/docs/pt/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) recusa qualquer outra coisa que teria gerado um prompt.

549* `--output-format json` fornece um único objeto de resultado para analisar, e `stream-json` com `--verbose` transmite eventos à medida que acontecem.549* `--output-format json` fornece um único objeto de resultado para analisar, e `stream-json` com `--verbose` transmite eventos à medida que acontecem.

550 550 

Details

494 494 

495* Se o STS recusar ou estiver inacessível, o gateway não envia a requisição com as credenciais próprias do upstream. Ele registra o erro do STS com o que verificar e então tenta o próximo upstream que você listou. [Mensagens de erro do upstream](#upstream-error-messages) explica o que o cliente recebe quando nenhum upstream tem sucesso. Um upstream posterior sem `assume_role` serviria a requisição com suas próprias credenciais, então liste um somente se for isso o que você deseja.495* Se o STS recusar ou estiver inacessível, o gateway não envia a requisição com as credenciais próprias do upstream. Ele registra o erro do STS com o que verificar e então tenta o próximo upstream que você listou. [Mensagens de erro do upstream](#upstream-error-messages) explica o que o cliente recebe quando nenhum upstream tem sucesso. Um upstream posterior sem `assume_role` serviria a requisição com suas próprias credenciais, então liste um somente se for isso o que você deseja.

496* O gateway chama o endpoint regional do STS `sts.<region>.amazonaws.com`, que sua rede deve alcançar. Para o endpoint FIPS, defina `AWS_USE_FIPS_ENDPOINT=true` no ambiente do gateway, em vez de `use_fips_endpoint` em um arquivo de configuração da AWS.496* O gateway chama o endpoint regional do STS `sts.<region>.amazonaws.com`, que sua rede deve alcançar. Para o endpoint FIPS, defina `AWS_USE_FIPS_ENDPOINT=true` no ambiente do gateway, em vez de `use_fips_endpoint` em um arquivo de configuração da AWS.

497* `assume_role` se aplica apenas a `provider: bedrock` e precisa de credenciais de origem SigV4: o gateway se recusa a iniciar quando ele é definido ao lado de `aws_bearer_token`.497* `assume_role` precisa de credenciais de origem SigV4: o gateway se recusa a iniciar quando ele é definido junto com `aws_bearer_token`.

498* Sem uma [lista `groups`](#send-each-team-to-its-own-upstream), todo desenvolvedor que o gateway admite pode usar este upstream. Para limitar quais modelos um desenvolvedor pode usar, defina `availableModels` em uma política [`managed`](#managed).498* Sem uma [lista `groups`](#send-each-team-to-its-own-upstream), todo desenvolvedor que o gateway admite pode usar este upstream. Para limitar quais modelos um desenvolvedor pode usar, defina `availableModels` em uma política [`managed`](#managed).

499* Para evitar que um modelo servido pelo papel também seja servido por outra conta, dê a ele um id personalizado cujo mapa `upstream_model` tenha apenas o nome deste upstream. Para esse id, o gateway ignora todos os outros upstreams, então nem a requisição nem a contagem de tokens de uma requisição abortada podem fazer failover para outra conta.499* Para evitar que um modelo servido pelo papel também seja servido por outra conta, dê a ele um id personalizado cujo mapa `upstream_model` tenha apenas o nome deste upstream. Para esse id, o gateway ignora todos os outros upstreams, então nem a requisição nem a contagem de tokens de uma requisição abortada podem fazer failover para outra conta.

500* Uma requisição para um nome de modelo integrado ainda pode [chegar a este upstream](#multiple-upstreams), e o gateway a assina com o mesmo papel. Liste este upstream por último, a menos que a conta dele também deva servir esses modelos.500* Uma requisição para um nome de modelo integrado ainda pode [chegar a este upstream](#multiple-upstreams), e o gateway a assina com o mesmo papel. Liste este upstream por último, a menos que a conta dele também deva servir esses modelos.


556| `region` | Sim | Região da AWS. O gateway deriva o endpoint dela como `https://bedrock-mantle.<region>.api.aws/anthropic`. |556| `region` | Sim | Região da AWS. O gateway deriva o endpoint dela como `https://bedrock-mantle.<region>.api.aws/anthropic`. |

557| `models` | Sim | Os modelos aos quais sua conta da AWS recebeu acesso no Mantle, nomeados como os clientes os enviam, como `claude-haiku-4-5`. Apenas estes vão para este upstream, e todos os outros modelos passam para o próximo. |557| `models` | Sim | Os modelos aos quais sua conta da AWS recebeu acesso no Mantle, nomeados como os clientes os enviam, como `claude-haiku-4-5`. Apenas estes vão para este upstream, e todos os outros modelos passam para o próximo. |

558| `auth` | Não | Aceita as mesmas chaves do bloco `auth` do upstream [Amazon Bedrock](#amazon-bedrock), sob as mesmas regras. |558| `auth` | Não | Aceita as mesmas chaves do bloco `auth` do upstream [Amazon Bedrock](#amazon-bedrock), sob as mesmas regras. |

559| `assume_role` | Não | A função pela qual passam as requisições desse upstream, com as mesmas chaves que [em um upstream `bedrock`](#bedrock-in-another-aws-account), incluindo `session_name` para [atribuição por desenvolvedor](#per-developer-aws-cost-attribution). Dê à função as ações IAM do Mantle. Requer um gateway executando Claude Code v2.1.318 ou posterior. Um gateway anterior encerra na inicialização com `Unrecognized key(s) in object: 'assume_role'`. |

559| `base_url` | Não | Sobrescreve o endpoint derivado. Mantenha o caminho `/anthropic` no final. |560| `base_url` | Não | Sobrescreve o endpoint derivado. Mantenha o caminho `/anthropic` no final. |

560 561 

561Conceda à identidade da AWS do upstream as próprias ações do IAM do Mantle para inferência e contagem de tokens, listadas em [Usar o endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#use-the-mantle-endpoint).562Conceda à identidade da AWS do upstream as próprias ações do IAM do Mantle para inferência e contagem de tokens, listadas em [Usar o endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#use-the-mantle-endpoint).


565As configurações `guardrail` e `assume_role` de um upstream `bedrock` não se estendem às requisições que o Mantle serve:566As configurações `guardrail` e `assume_role` de um upstream `bedrock` não se estendem às requisições que o Mantle serve:

566 567 

567* **`guardrail`**: o gateway não aplica nenhum [guardrail do Bedrock](#apply-an-amazon-bedrock-guardrail) às requisições que envia ao Mantle, então se recusa a iniciar quando um upstream `mantle` está listado enquanto algum upstream `bedrock` define `guardrail`.568* **`guardrail`**: o gateway não aplica nenhum [guardrail do Bedrock](#apply-an-amazon-bedrock-guardrail) às requisições que envia ao Mantle, então se recusa a iniciar quando um upstream `mantle` está listado enquanto algum upstream `bedrock` define `guardrail`.

568* **`assume_role`**: um upstream `mantle` não aceita [`assume_role`](#bedrock-in-another-aws-account). As requisições que o Mantle serve são enviadas com as próprias credenciais `auth` do upstream `mantle` e não são [atribuídas por desenvolvedor](#per-developer-aws-cost-attribution).569* **`assume_role`**: defina-o no próprio upstream `mantle`. Sem ele, as requisições que o Mantle serve são enviadas com as credenciais `auth` próprias do upstream `mantle`.

569 570 

570Para saber o que significam as próprias respostas de erro do Mantle, consulte [Erros do endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#mantle-endpoint-errors).571Para saber o que significam as próprias respostas de erro do Mantle, consulte [Erros do endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#mantle-endpoint-errors).

571 572 

Details

424| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e desenvolvedores veem `Cloud gateway session expired` a cada `session.ttl_hours` | O IdP aceitou o token de atualização mas não retornou id\_token com ele, então o gateway perguntou ao endpoint userinfo do IdP pelas reivindicações do usuário. O IdP rejeitou o token de acesso atualizado lá. O gateway responde `temporarily_unavailable`, então Claude Code mantém o token de atualização mas não consegue renovar a sessão. Versões do gateway anteriores a v2.1.260 registram a mesma linha sem o detalhe `(at …)`. | Defina [`oidc.scope_on_refresh: true`](https://code.claude.com/docs/pt/claude-apps-gateway-config#oidc), disponível no gateway v2.1.260 ou posterior, para que a requisição de atualização peça por `openid` novamente. Alguns IdPs, como Okta, retornam um id\_token na atualização apenas quando solicitado. No PingFederate, ative **Return ID Token On Refresh Grant** sob **Applications > OAuth > OpenID Connect Policy Management** em vez disso. A chave não muda o comportamento do PingFederate. Para outros IdPs que ainda o omitem, verifique se o endpoint userinfo aceita tokens de acesso emitidos por uma atualização. Como uma solução temporária, aumente [`session.ttl_hours`](https://code.claude.com/docs/pt/claude-apps-gateway-config#session). Veja [Identity provider setup](#identity-provider-setup) para o tradeoff de desprovisionamento. |424| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e desenvolvedores veem `Cloud gateway session expired` a cada `session.ttl_hours` | O IdP aceitou o token de atualização mas não retornou id\_token com ele, então o gateway perguntou ao endpoint userinfo do IdP pelas reivindicações do usuário. O IdP rejeitou o token de acesso atualizado lá. O gateway responde `temporarily_unavailable`, então Claude Code mantém o token de atualização mas não consegue renovar a sessão. Versões do gateway anteriores a v2.1.260 registram a mesma linha sem o detalhe `(at …)`. | Defina [`oidc.scope_on_refresh: true`](https://code.claude.com/docs/pt/claude-apps-gateway-config#oidc), disponível no gateway v2.1.260 ou posterior, para que a requisição de atualização peça por `openid` novamente. Alguns IdPs, como Okta, retornam um id\_token na atualização apenas quando solicitado. No PingFederate, ative **Return ID Token On Refresh Grant** sob **Applications > OAuth > OpenID Connect Policy Management** em vez disso. A chave não muda o comportamento do PingFederate. Para outros IdPs que ainda o omitem, verifique se o endpoint userinfo aceita tokens de acesso emitidos por uma atualização. Como uma solução temporária, aumente [`session.ttl_hours`](https://code.claude.com/docs/pt/claude-apps-gateway-config#session). Veja [Identity provider setup](#identity-provider-setup) para o tradeoff de desprovisionamento. |

425| Um desenvolvedor faz login, e então cada requisição dessa sessão falha com um erro `431` | O token de sessão no cabeçalho `Authorization` de cada requisição lista os grupos do IdP do desenvolvedor, então para um desenvolvedor em muitos grupos os cabeçalhos podem totalizar mais do que o gateway aceita | Veja [Cabeçalhos de requisição grandes demais após o login](#request-headers-too-large-after-sign-in) para saber qual limite se aplica e o que alterar |425| Um desenvolvedor faz login, e então cada requisição dessa sessão falha com um erro `431` | O token de sessão no cabeçalho `Authorization` de cada requisição lista os grupos do IdP do desenvolvedor, então para um desenvolvedor em muitos grupos os cabeçalhos podem totalizar mais do que o gateway aceita | Veja [Cabeçalhos de requisição grandes demais após o login](#request-headers-too-large-after-sign-in) para saber qual limite se aplica e o que alterar |

426| Toda requisição ao Amazon Bedrock retorna 502; o log mostra `Could not load credentials from any providers` | No EC2, o hop limit padrão do IMDSv2 de 1 bloqueia a requisição de metadados de instância de dentro do container. A inicialização e `/readyz` passam mesmo assim porque o AWS SDK resolve credenciais de instância na primeira requisição, não na construção do cliente | Aumente o hop limit com `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`, ou defina-o no modelo de lançamento. A mudança se aplica a cada container na instância. Prefira funções de tarefa ECS onde disponível, que leem credenciais do endpoint de credenciais do container ECS e evitam a mudança inteiramente, ou aplique a mudança em uma instância de gateway dedicada para limitar a exposição. |426| Toda requisição ao Amazon Bedrock retorna 502; o log mostra `Could not load credentials from any providers` | No EC2, o hop limit padrão do IMDSv2 de 1 bloqueia a requisição de metadados de instância de dentro do container. A inicialização e `/readyz` passam mesmo assim porque o AWS SDK resolve credenciais de instância na primeira requisição, não na construção do cliente | Aumente o hop limit com `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`, ou defina-o no modelo de lançamento. A mudança se aplica a cada container na instância. Prefira funções de tarefa ECS onde disponível, que leem credenciais do endpoint de credenciais do container ECS e evitam a mudança inteiramente, ou aplique a mudança em uma instância de gateway dedicada para limitar a exposição. |

427| Log: um aviso que contém `upstream <name>: Google issued an access token that expires in <N>s`, em um upstream cujo arquivo de credenciais do Google tem o tipo `external_account` | As requisições são bem-sucedidas até que esse token de acesso expire, e depois falham, a menos que o token para o qual `credential_source` aponta tenha sido renovado antes. | Se um processo grava esse token em um arquivo, faça com que ele grave um novo mais de cinco minutos antes de o antigo expirar |

427| No pico de carga, as respostas demoram a começar ou parecem travar, ou falham com um 502 `all upstreams failed` enquanto o upstream está saudável | Uma réplica tem mais requisições abertas do que envia upstream de uma vez, então as requisições extras esperam dentro do gateway. Em um upstream `provider: anthropic`, uma requisição que espera mais tempo que `timeouts.upstream_ttfb_ms` desiste desse upstream, o que produz o 502 quando nenhum upstream posterior a serve. O log mostra um aviso que contém `client requests are open`. | Adicione réplicas, ou aumente o limite em cada réplica. Veja [Concurrent upstream requests](#concurrent-upstream-requests). |428| No pico de carga, as respostas demoram a começar ou parecem travar, ou falham com um 502 `all upstreams failed` enquanto o upstream está saudável | Uma réplica tem mais requisições abertas do que envia upstream de uma vez, então as requisições extras esperam dentro do gateway. Em um upstream `provider: anthropic`, uma requisição que espera mais tempo que `timeouts.upstream_ttfb_ms` desiste desse upstream, o que produz o 502 quando nenhum upstream posterior a serve. O log mostra um aviso que contém `client requests are open`. | Adicione réplicas, ou aumente o limite em cada réplica. Veja [Concurrent upstream requests](#concurrent-upstream-requests). |

428| Em um upstream diferente de `provider: anthropic`, um turno com uma longa pausa de pensamento falha. O proxy na frente do gateway registra uma requisição que permanece aberta por cerca de 12,5 minutos, depois uma sequência de erros `504` | Claude Code encerrou um stream que havia entregado seu primeiro evento de resposta e depois carregou apenas pings de keepalive. Ele reenviou a requisição sem streaming, e cada resposta leva mais tempo do que o timeout do proxy. | Aumente `CLAUDE_STREAM_IDLE_TIMEOUT_MS` para seus desenvolvedores. Veja [Pensamento longo termina em timeouts do proxy](#long-thinking-ends-in-proxy-timeouts). |429| Em um upstream diferente de `provider: anthropic`, um turno com uma longa pausa de pensamento falha. O proxy na frente do gateway registra uma requisição que permanece aberta por cerca de 12,5 minutos, depois uma sequência de erros `504` | Claude Code encerrou um stream que havia entregado seu primeiro evento de resposta e depois carregou apenas pings de keepalive. Ele reenviou a requisição sem streaming, e cada resposta leva mais tempo do que o timeout do proxy. | Aumente `CLAUDE_STREAM_IDLE_TIMEOUT_MS` para seus desenvolvedores. Veja [Pensamento longo termina em timeouts do proxy](#long-thinking-ends-in-proxy-timeouts). |

429| Em `provider: anthropic`, um turno com uma longa pausa de pensamento falha. O proxy registra uma requisição aberta por cerca de 20 minutos, depois erros `502` ou `504` | Claude Code encerrou um stream que havia entregado seu primeiro evento de resposta e depois carregou apenas pings de keepalive. Ele reenviou a requisição sem streaming, e cada resposta leva mais tempo do que a espera do gateway pelo upstream, `timeouts.upstream_ttfb_ms`, ou do que o timeout do proxy. | Aumente `CLAUDE_STREAM_IDLE_TIMEOUT_MS` para seus desenvolvedores. Veja [Pensamento longo em um upstream da Anthropic API](#long-thinking-on-an-anthropic-api-upstream). |430| Em `provider: anthropic`, um turno com uma longa pausa de pensamento falha. O proxy registra uma requisição aberta por cerca de 20 minutos, depois erros `502` ou `504` | Claude Code encerrou um stream que havia entregado seu primeiro evento de resposta e depois carregou apenas pings de keepalive. Ele reenviou a requisição sem streaming, e cada resposta leva mais tempo do que a espera do gateway pelo upstream, `timeouts.upstream_ttfb_ms`, ou do que o timeout do proxy. | Aumente `CLAUDE_STREAM_IDLE_TIMEOUT_MS` para seus desenvolvedores. Veja [Pensamento longo em um upstream da Anthropic API](#long-thinking-on-an-anthropic-api-upstream). |

Details

131| `session-env/` | Metadados de ambiente por sessão |131| `session-env/` | Metadados de ambiente por sessão |

132| `tasks/` | Listas de tarefas escritas pelas ferramentas de tarefa, um diretório por lista |132| `tasks/` | Listas de tarefas escritas pelas ferramentas de tarefa, um diretório por lista |

133| `shell-snapshots/` | Aliases, funções e opções de shell capturadas na inicialização e aplicadas pela [ferramenta Bash](https://code.claude.com/docs/pt/tools-reference.md#bash-tool-behavior) a cada comando. Removidas na saída limpa. A varredura limpa qualquer uma deixada após um crash. |133| `shell-snapshots/` | Aliases, funções e opções de shell capturadas na inicialização e aplicadas pela [ferramenta Bash](https://code.claude.com/docs/pt/tools-reference.md#bash-tool-behavior) a cada comando. Removidas na saída limpa. A varredura limpa qualquer uma deixada após um crash. |

134| `backups/` | Versões anteriores de `~/.claude.json`, copiadas quando Claude Code reescreve o arquivo. Claude Code mantém as cinco mais novas, mais uma cópia de qualquer versão que não conseguiu analisar. |134| `backups/` | Versões anteriores de `~/.claude.json`, copiadas quando Claude Code reescreve o arquivo. Claude Code mantém as cinco mais novas, mais uma cópia de qualquer versão que não conseguiu analisar. Após o limite de idade, a última cópia que contém sua configuração também é deletada. Se o arquivo atual puder ser analisado, contiver sua configuração e tiver menos de 8 MiB, você fica com uma nova cópia dele. |

135| `feedback-bundles/` | Arquivos de transcrição reduzidos escritos por `/feedback` em provedores de terceiros ou quando nenhuma credencial Anthropic está configurada, para enviar à sua equipe de conta Anthropic |135| `feedback-bundles/` | Arquivos de transcrição reduzidos escritos por `/feedback` em provedores de terceiros ou quando nenhuma credencial Anthropic está configurada, para enviar à sua equipe de conta Anthropic |

136| `feedback/drafts/` | [Feedback redigido por Claude](https://code.claude.com/docs/pt/tools-reference.md#sendfeedback-tool-behavior) enfileirado aguardando sua revisão em `/feedback`. Varrido após `cleanupPeriodDays` ou 30 dias, o que for menor. Quando a fila está no seu limite de 10 rascunhos, Claude Code deleta o rascunho mais antigo para liberar espaço. |136| `feedback/drafts/` | [Feedback redigido por Claude](https://code.claude.com/docs/pt/tools-reference.md#sendfeedback-tool-behavior) enfileirado aguardando sua revisão em `/feedback`. Varrido após `cleanupPeriodDays` ou 30 dias, o que for menor. Quando a fila está no seu limite de 10 rascunhos, Claude Code deleta o rascunho mais antigo para liberar espaço. |

137| `usage-data/` | `report.html` e cópias de relatório com timestamp escritas por [`/insights`](https://code.claude.com/docs/pt/costs#analyze-your-usage-patterns), mais dados de análise em cache por sessão usados para construí-los |137| `usage-data/` | `report.html` e cópias de relatório com timestamp escritas por [`/insights`](https://code.claude.com/docs/pt/costs#analyze-your-usage-patterns), mais dados de análise em cache por sessão usados para construí-los |


288| `~/.claude/tasks/` | Suas [listas de tarefas](https://code.claude.com/docs/pt/interactive-mode.md#task-list), incluindo as que ainda estão em uso |288| `~/.claude/tasks/` | Suas [listas de tarefas](https://code.claude.com/docs/pt/interactive-mode.md#task-list), incluindo as que ainda estão em uso |

289| `~/.claude/skills/.trash/`, `~/.claude/plugins/.trash/` | A chance de recuperar [skills sincronizadas](https://code.claude.com/docs/pt/skills.md#how-synced-skills-behave) e [plugins sincronizados](https://code.claude.com/docs/pt/plugins/loading.md#synced-plugins) que Claude Code removeu |289| `~/.claude/skills/.trash/`, `~/.claude/plugins/.trash/` | A chance de recuperar [skills sincronizadas](https://code.claude.com/docs/pt/skills.md#how-synced-skills-behave) e [plugins sincronizados](https://code.claude.com/docs/pt/plugins/loading.md#synced-plugins) que Claude Code removeu |

290| `~/.claude/plugins/installed_plugins.set-aside.<date>.<hash>.json`, `~/.claude/plugins/installed_plugins.unreadable.<date>.<hash>.kept` | As cópias dos registros de instalação de plugin que Claude Code descartou ou não conseguiu ler. Nada as lê de volta |290| `~/.claude/plugins/installed_plugins.set-aside.<date>.<hash>.json`, `~/.claude/plugins/installed_plugins.unreadable.<date>.<hash>.kept` | As cópias dos registros de instalação de plugin que Claude Code descartou ou não conseguiu ler. Nada as lê de volta |

291| `~/.claude/debug/`, `~/.claude/plans/`, `~/.claude/session-env/`, `~/.claude/shell-snapshots/`, `~/.claude/backups/` | Nada voltado para o usuário |291| `~/.claude/debug/`, `~/.claude/plans/`, `~/.claude/session-env/`, `~/.claude/shell-snapshots/` | Nada voltado para o usuário |

292| `~/.claude/backups/` | As cópias anteriores a partir das quais você pode [restaurar `~/.claude.json`](https://code.claude.com/docs/pt/errors#configuration-error-in-claude-json) |

292| `~/.claude/todos/`, `~/.claude/statsig/`, `~/.claude/logs/`, `~/.claude/image-cache/` | Nada. Diretórios legados não escritos pelas versões atuais. |293| `~/.claude/todos/`, `~/.claude/statsig/`, `~/.claude/logs/`, `~/.claude/image-cache/` | Nada. Diretórios legados não escritos pelas versões atuais. |

293 294 

294Não delete `~/.claude.json`, `~/.claude/settings.json` ou `~/.claude/plugins/`: esses mantêm os detalhes da sua conta, preferências e plugins instalados.295Não delete `~/.claude.json`, `~/.claude/settings.json` ou `~/.claude/plugins/`: esses mantêm os detalhes da sua conta, preferências e plugins instalados.

Details

480* **"Unable to access your repository"**, relatado por uma thread quando seu clone falha: GitHub rejeitou o clone, o repositório não foi encontrado sob o nome que o projeto tem, ou o branch do qual a thread foi pedida para começar não existe.480* **"Unable to access your repository"**, relatado por uma thread quando seu clone falha: GitHub rejeitou o clone, o repositório não foi encontrado sob o nome que o projeto tem, ou o branch do qual a thread foi pedida para começar não existe.

481* **"Claude can't access"** um repositório, mostrado quando você salva repositórios no diálogo **New project** ou **Project settings**. A mensagem continua com um link de instalação e um link de reconexão. Use o link de instalação se o Claude GitHub App não estiver nesse repositório, e o link de reconexão se estiver, já que o GitHub App pode ser instalado no GitHub sem estar vinculado à conta que você conectou a Claude. Se a mensagem disser que o GitHub App está suspenso ou não inclui esse repositório, siga seu link para o GitHub para corrigir isso.481* **"Claude can't access"** um repositório, mostrado quando você salva repositórios no diálogo **New project** ou **Project settings**. A mensagem continua com um link de instalação e um link de reconexão. Use o link de instalação se o Claude GitHub App não estiver nesse repositório, e o link de reconexão se estiver, já que o GitHub App pode ser instalado no GitHub sem estar vinculado à conta que você conectou a Claude. Se a mensagem disser que o GitHub App está suspenso ou não inclui esse repositório, siga seu link para o GitHub para corrigir isso.

482 482 

483Para corrigir qualquer um deles, clique no botão que a mensagem oferece, como **Install GitHub App** ou **Select repositories on GitHub**, depois **Check again**. Quando o bloqueio está no lado da organização GitHub, como um proprietário que não aprovou o app ou uma lista de permissão de IP que exclui Claude, a mensagem mostra um link **See how to fix**. Se não houver botão, siga [Configurar acesso ao GitHub](#set-up-github-access), depois envie outra mensagem para tentar novamente.483Para corrigir o acesso ao GitHub em "Couldn't start the session" ou "Unable to access your repository", clique no botão que a mensagem oferece, como **Install on GitHub** ou **Select repositories**. Se não houver botão, siga [Configurar acesso ao GitHub](#set-up-github-access). Após a correção, peça a Claude na conversa do projeto para iniciar uma nova thread para o mesmo trabalho.

484 484 

485### Uma thread atingiu o limite de uso485### Uma thread atingiu o limite de uso

486 486 


505 505 

506| Mensagem | O que fazer |506| Mensagem | O que fazer |

507| :- | :- |507| :- | :- |

508| "Unable to connect to repository" com "Claude couldn't reach GitHub to fetch your repository" | Aguarde um momento, depois envie outra mensagem para tentar novamente |508| "Unable to connect to repository" com "Claude couldn't reach GitHub to fetch your repository" | Aguarde um momento, depois peça a Claude na conversa do projeto para iniciar uma nova thread para o mesmo trabalho |

509| "Unable to connect to repository" com "Claude couldn't access your repository or environment" | Sua conta GitHub precisa de acesso push ao repositório, e o ambiente ainda deve existir. Verifique ambos em **Project settings > Environment**, depois tente novamente |509| "Unable to connect to repository" com "Claude couldn't access your repository or environment" | Sua conta GitHub precisa de acesso push ao repositório, e o ambiente ainda deve existir. Verifique ambos em **Project settings > Environment**, depois tente novamente |

510| "Couldn't show the setup proposal" | O app que você tem aberto é mais antigo que as **Setup recommendations** que Claude enviou. Atualize a página ou reinicie o aplicativo desktop, ou peça a Claude para propor a configuração novamente |510| "Couldn't show the setup proposal" | O app que você tem aberto é mais antigo que as **Setup recommendations** que Claude enviou. Atualize a página ou reinicie o aplicativo desktop, ou peça a Claude para propor a configuração novamente |

511| "The project's environment was removed" | Escolha um ambiente diferente em **Project settings > Environment**; a mudança se aplica a novas threads |511| "The project's environment was removed" | Escolha um ambiente diferente em **Project settings > Environment**; a mudança se aplica a novas threads |

Details

12 12 

13## Veja o que foi carregado no contexto13## Veja o que foi carregado no contexto

14 14 

15O comando `/context` mostra tudo que ocupa a janela de contexto para a sessão atual, dividido por categoria: prompt do sistema, ferramentas do sistema, ferramentas MCP, subagentes personalizados com a fonte de cada um carregado, arquivos de memória, skills e mensagens de conversa. Execute-o primeiro para confirmar se seu `CLAUDE.md`, regras ou descrições de skill estão presentes. A seção de skills em `/context` também inclui [skills agrupadas](https://code.claude.com/docs/pt/skills.md#bundled-skills), que `/skills` não lista.15O comando `/context` mostra tudo que ocupa a janela de contexto para a sessão atual. Ele divide isso por categoria: system prompt, ferramentas do sistema, ferramentas MCP, subagentes personalizados com a fonte de onde cada um foi carregado, arquivos de memória, skills e mensagens de conversa. Execute-o primeiro para confirmar se seu `CLAUDE.md`, regras ou descrições de skill estão presentes. A seção de skills em `/context` também inclui [skills incluídas](https://code.claude.com/docs/pt/skills.md#bundled-skills), que `/skills` não lista.

16 

17No [modo de tela cheia](https://code.claude.com/docs/pt/fullscreen.md), `/context` recolhe a divisão por item, então execute `/context all` para expandi-la.

16 18 

17Para detalhes sobre uma categoria específica, acompanhe com o comando dedicado:19Para detalhes sobre uma categoria específica, acompanhe com o comando dedicado:

18 20 

desktop.md +71 −14

Details

84 84 

85Os 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 de permissão a qualquer momento usando o seletor de modo na linha abaixo da caixa de prompt. Para aprovar cada alteração você mesmo, mude para Manual.85Os 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 de permissão a qualquer momento usando o seletor de modo na linha abaixo da caixa de prompt. Para aprovar cada alteração você mesmo, mude para Manual.

86 86 

87Para definir um modo padrão para novas sessões locais, adicione `permissions.defaultMode` ao seu [arquivo de configurações](https://code.claude.com/docs/pt/settings.md#where-settings-live). O aplicativo desktop lê os mesmos arquivos de configurações que o CLI. Um modo que você escolhe no seletor é lembrado por pasta e tem precedência sobre `defaultMode` para essa pasta, exceto Plan, que se aplica apenas à sessão atual.87Para definir um modo de permissão padrão para novas sessões locais, adicione `permissions.defaultMode` ao seu [arquivo de configurações](https://code.claude.com/docs/pt/settings.md#where-settings-live). Um modo que você escolhe em uma sessão local é lembrado por pasta e tem precedência sobre um `defaultMode` nas configurações `.claude/` do projeto. Uma nova sessão local ainda pode iniciar em um `defaultMode` de `~/.claude/settings.json` ou das configurações gerenciadas, então verifique o seletor antes da sua primeira mensagem. Se você escolher Plan, ele se aplica apenas a esta sessão.

88 88 

89| Modo | Chave de configuração | Comportamento |89| Modo | Chave de configuração | Comportamento |

90| - | - | - |90| - | - | - |


1289 1289 

1290> [!WARNING]1290> [!WARNING]

1291>1291>

1292> Se você faz login no Desktop com uma conta Claude, não conte com uma tarefa sendo executada durante a noite. O Desktop renova esse login para a tarefa apenas enquanto está em execução e conectado, portanto o login da tarefa pode expirar depois que você se desconecta, e a tarefa então para. O tempo restante quando você se desconecta varia e pode ser de apenas alguns minutos.1292> Se você faz login no Desktop com uma conta Claude, não conte com uma tarefa sendo executada durante a noite. O Desktop renova esse login para a tarefa somente enquanto o Desktop está em execução, conectado e com login feito, então o login da tarefa pode expirar depois que você se desconecta, e a tarefa então para. O tempo restante quando você se desconecta varia e pode ser de apenas alguns minutos.

1293>1293>

1294> O trabalho feito até então permanece na máquina remota, e você pode continuar com uma mensagem quando voltar.1294> O trabalho feito até então permanece na máquina remota, e você pode continuar com uma mensagem quando voltar.

1295>1295>

1296> Se a tarefa precisar ser executada durante a noite:1296> Se a tarefa precisar ser executada durante a noite:

1297>1297>

1298> * [Mantenha seu computador ativo](https://code.claude.com/docs/pt/desktop-scheduled-tasks.md#how-scheduled-tasks-run) e online, com a tampa aberta e o Desktop em execução1298> * [Mantenha seu computador ativo](https://code.claude.com/docs/pt/desktop-scheduled-tasks.md#how-scheduled-tasks-run) e online, com a tampa aberta e o Desktop em execução e com login feito

1299> * Use um login que funcione sem prompt, como uma chave mantida pelo seu agente SSH, para a máquina remota e para qualquer jump host no caminho. O Desktop pode então se reconectar sozinho após uma queda.1299> * Use um login que funcione sem prompt, como uma chave mantida pelo seu agente SSH, para a máquina remota e para qualquer jump host no caminho. O Desktop pode então se reconectar sozinho após uma queda.

1300>1300>

1301> Para uma tarefa que precisa ser executada enquanto seu computador está em suspensão ou desligado, inicie uma [sessão na nuvem](#run-long-running-tasks-in-the-cloud) em vez disso.1301> Para uma tarefa que precisa ser executada enquanto seu computador está em suspensão ou desligado, inicie uma [sessão na nuvem](#run-long-running-tasks-in-the-cloud) em vez disso.


1303* **Após suspensão ou perda de rede**: você recupera a tarefa em execução se o processo [ainda estiver em execução](#limits-while-desktop-is-disconnected) e o Desktop puder fazer login sem prompt. Se não puder, [envie uma mensagem](#reconnect-after-sleep-or-a-network-loss).1303* **Após suspensão ou perda de rede**: você recupera a tarefa em execução se o processo [ainda estiver em execução](#limits-while-desktop-is-disconnected) e o Desktop puder fazer login sem prompt. Se não puder, [envie uma mensagem](#reconnect-after-sleep-or-a-network-loss).

1304* **Após sair**: a tarefa continua em execução, mas você a perde quando a sessão é aberta novamente, a menos que o Desktop consiga se reconectar ao processo dela. Verifique [quando o Desktop consegue se reconectar](#reopen-a-session-after-you-quit-desktop) antes de sair. Se você perdeu a tarefa, envie uma mensagem para continuar.1304* **Após sair**: a tarefa continua em execução, mas você a perde quando a sessão é aberta novamente, a menos que o Desktop consiga se reconectar ao processo dela. Verifique [quando o Desktop consegue se reconectar](#reopen-a-session-after-you-quit-desktop) antes de sair. Se você perdeu a tarefa, envie uma mensagem para continuar.

1305 1305 

1306Quando você voltar e a tarefa não estiver concluída, verifique se há um aviso de que o Desktop não consegue se reconectar, um erro de autenticação ou uma solicitação pendente:1306Quando você voltar e a tarefa não estiver concluída, verifique se há a página de login do Desktop, um aviso de que o Desktop não consegue se reconectar, um erro de autenticação ou uma solicitação aguardando:

1307 1307 

1308* **Página de login**: faça login. Se a tarefa parou, envie uma mensagem para continuar. Em um plano Enterprise, sua organização pode [desconectar você um número definido de dias depois que você faz login](https://support.claude.com/en/articles/13163631-configuring-session-security-settings), por mais ativo que você esteja. Com uma conta Claude, o Desktop não renova o login da tarefa enquanto você está desconectado, então a tarefa pode parar.

1308* **O Desktop não consegue se reconectar**: a sessão informa o motivo, e uma notificação também pode informá-lo. O Desktop pode [precisar que você faça login](#reconnect-after-sleep-or-a-network-loss).1309* **O Desktop não consegue se reconectar**: a sessão informa o motivo, e uma notificação também pode informá-lo. O Desktop pode [precisar que você faça login](#reconnect-after-sleep-or-a-network-loss).

1309* **Erro de autenticação**: o [token de login ou a credencial](#limits-while-desktop-is-disconnected) pode ter expirado. Com uma conta Claude, envie uma mensagem para continuar. Com um provedor terceirizado, consulte [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).1310* **Erro de autenticação**: o [token de login ou a credencial](#limits-while-desktop-is-disconnected) pode ter expirado. Com uma conta Claude, envie uma mensagem para continuar. Com um provedor terceirizado, consulte [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).

1310* **Solicitação pendente**: [responda a ela](#handle-requests-that-arrive-while-you-are-away)1311* **Solicitação pendente**: [responda a ela](#handle-requests-that-arrive-while-you-are-away)


1602 1603 

1603> [!NOTE]1604> [!NOTE]

1604>1605>

1605> Conexões a partir de um comando exigem o Claude Desktop v3.6556.0 ou posterior no macOS ou Linux, conectado com uma conta Claude. Os administradores podem [distribuir comandos para uma equipe](#distribute-commands-to-your-team).1606> Conexões a partir de um comando requerem o Claude Desktop v3.6556.0 ou posterior no macOS ou Linux, ou v4.16336.0 ou posterior no Windows, com login feito com uma conta Claude. No Windows, o Desktop também precisa [se conectar pelo cliente OpenSSH](#use-your-ssh-configuration). Administradores podem [distribuir comandos para uma equipe](#distribute-commands-to-your-team).

1606 1607 

1607O Desktop executa o comando apenas quando você cria a conexão ou [cria outra máquina](#create-another-machine), e não a cada vez que você se conecta. Cada entrada é uma conexão, que aponta para o host que o Desktop salvou por último a partir do comando da entrada.1608O Desktop executa o comando apenas quando você cria a conexão ou [cria outra máquina](#create-another-machine), e não a cada vez que você se conecta. Cada entrada é uma conexão, que aponta para o host que o Desktop salvou por último a partir do comando da entrada.

1608 1609 


1632}1633}

1633```1634```

1634 1635 

1636No Windows, um nome simples como `acme-dev` não funciona, então [comece o comando com o caminho completo do programa](#write-the-command-on-windows).

1637 

1635Cada entrada aceita estes campos, e `id`, `name` e `command` são obrigatórios:1638Cada entrada aceita estes campos, e `id`, `name` e `command` são obrigatórios:

1636 1639 

1637| Campo | Valor |1640| Campo | Valor |


1646 1649 

1647##### Escrever o comando1650##### Escrever o comando

1648 1651 

1649O Desktop inicia o programa diretamente, sem shell e sem terminal:1652No Windows, comece com [Escrever o comando no Windows](#write-the-command-on-windows), que diz quais destas regras se aplicam ali.

1653 

1654No macOS e Linux, o Desktop inicia o programa diretamente, sem shell e sem terminal:

1650 1655 

1651* **Programa**: escreva seu nome, ou seu caminho completo a partir de `/`, sem espaços. O Desktop procura um nome simples no `PATH` que seu shell de login exporta. Caminhos relativos como `./acme-dev`, caminhos que começam com `~` e aliases e funções do shell não funcionam.1656* **Programa**: escreva seu nome ou seu caminho completo a partir de `/`. O Desktop procura um nome simples no `PATH` que seu shell de login exporta. Caminhos relativos como `./acme-dev`, caminhos que começam com `~` e aliases e funções de shell não funcionam.

1652* **Argumentos**: separe argumentos simples com espaços. O comando pode conter apenas espaços, letras ASCII, dígitos e os caracteres `+,-./:=@_~`, e nenhuma palavra pode começar com `~`.1657* **Espaços no caminho**: coloque o caminho completo do programa entre aspas simples, como `'/Users/you/My Tools/make-devbox' create`. Aspas, simples ou duplas, requerem o Claude Desktop v4.16336.0 ou posterior, e funcionam apenas em torno do caminho do programa.

1653* **Scripts**: se o comando precisar de qualquer outra coisa, como aspas, pipes, variáveis ou uma URL com `?` ou `&`, coloque-o em um script. Torne o script executável, comece-o com uma linha `#!` e defina `command` como seu caminho completo, como `/Users/you/bin/make-devbox`. No macOS, mantenha o script fora das pastas Documents, Desktop e Downloads, onde o macOS pode bloqueá-lo.1658* **Argumentos**: separe os argumentos com espaços. Fora das aspas, o comando pode conter apenas espaços, letras ASCII, dígitos e os caracteres `+,-./:=@_~`, e nenhuma palavra pode começar com `~`. Um caminho entre aspas também pode conter alguns outros caracteres, como `(`, `)` e `&`.

1659* **Scripts**: se o comando precisar de qualquer outra coisa, como argumentos entre aspas, pipes, variáveis ou uma URL com `?` ou `&`, coloque-o em um script. Torne o script executável, comece-o com uma linha `#!` e defina `command` como seu caminho completo, como `/Users/you/bin/make-devbox`. No macOS, mantenha o script fora das pastas Documents, Desktop e Downloads, onde o macOS pode bloqueá-lo.

1654* **Entrada**: o programa não recebe entrada nem terminal, então não pode solicitar nada a você por ali. Se sua ferramenta faz login por meio de um navegador ou de um prompt, faça login primeiro em um terminal, e novamente sempre que esse login expirar.1660* **Entrada**: o programa não recebe entrada nem terminal, então não pode solicitar nada a você por ali. Se sua ferramenta faz login por meio de um navegador ou de um prompt, faça login primeiro em um terminal, e novamente sempre que esse login expirar.

1655* **Ambiente**: o programa é executado no seu diretório pessoal com as variáveis que seu shell de login exporta. O Desktop as lê ao iniciar, assim como faz para [um `ProxyCommand`](#use-variables-from-your-shell-in-a-proxycommand), então encerre e reabra o Desktop depois de alterá-las.1661* **Ambiente**: o programa é executado no seu diretório pessoal com as variáveis que seu shell de login exporta. O Desktop as lê ao iniciar, assim como faz para [um `ProxyCommand`](#use-variables-from-your-shell-in-a-proxycommand), então encerre e reabra o Desktop depois de alterá-las.

1656* **Limite de tempo**: o Desktop interrompe um programa que ainda esteja em execução após 10 minutos. A mensagem de progresso do Desktop não mostra a saída do programa. Para interromper o programa antes, selecione **Cancel** ao lado dessa mensagem.1662* **Limite de tempo**: o Desktop interrompe um programa que ainda esteja em execução após 10 minutos. A mensagem de progresso do Desktop não mostra a saída do programa. Para interromper o programa antes, selecione **Cancel** ao lado dessa mensagem.


1680 1686 

1681Se o comando falhar, **View details** na mensagem do Desktop mostra a última linha que o comando escreveu na saída de erro padrão, se houver.1687Se o comando falhar, **View details** na mensagem do Desktop mostra a última linha que o comando escreveu na saída de erro padrão, se houver.

1682 1688 

1689##### Escrever o comando no Windows

1690 

1691No Windows, comece `command` com o caminho completo de um arquivo `.exe`, `.cmd` ou `.bat`, a partir da letra da unidade. O Desktop não procura um nome simples no seu `PATH`, então uma entrada cujo `command` é `acme-dev create` fica [cinza](#if-a-command-is-missing-or-gray).

1692 

1693A entrada a seguir em `%USERPROFILE%\.claude\settings.json` executa `C:\Program Files\Acme\acme-dev.exe` com o argumento `create`. Em JSON, escreva cada barra invertida duas vezes, ou escreva `/` em vez disso. As aspas simples estão ali porque o caminho tem um espaço:

1694 

1695```json settings.json theme={null}

1696{

1697 "sshHostCommands": [

1698 {

1699 "id": "devbox",

1700 "name": "Dev box",

1701 "command": "'C:\\Program Files\\Acme\\acme-dev.exe' create"

1702 }

1703 ]

1704}

1705```

1706 

1707Siga as regras de [Escrever o comando](#write-the-command) sobre espaços no caminho, entrada, limite de tempo e o que o programa imprime. No lugar de suas outras regras, siga estas:

1708 

1709* **Programa**: não use um caminho de rede como `\\server\share`, uma variável como `%USERPROFILE%` ou uma letra fora do ASCII. Com qualquer um deles no caminho, a entrada fica cinza. Se o nome da sua pasta de usuário tiver uma letra assim, mantenha o programa fora dessa pasta.

1710* **Argumentos**: siga a regra de Argumentos em Escrever o comando. O comando também pode conter `\`, mas nenhuma palavra pode terminar com ele.

1711* **Scripts**: use um arquivo `.cmd` ou `.bat`, que o Desktop executa por meio do `cmd.exe`. Mesmo entre aspas, o caminho do arquivo não pode conter `&`, `^` ou `;`. Em um arquivo que você escreve, leia os argumentos com `%*`, porque `%1` a `%9` dividem um argumento em `,` e `=`.

1712* **Ambiente**: o programa recebe as variáveis de ambiente do app Desktop, não as de um perfil de shell. Depois de alterar uma variável, saia e reabra o Desktop.

1713* **Teste**: para ver a saída que o Desktop lê, execute o comando no Prompt de Comando. Coloque um caminho que tenha espaço entre aspas duplas e use `NUL` para nenhuma entrada, como em `"C:\Program Files\Acme\acme-dev.exe" create < NUL > host.txt`. O arquivo precisa conter apenas o host. O teste também cria uma máquina, então exclua-a com sua ferramenta depois.

1714 

1715##### Envolver uma ferramenta do Windows que imprime outras linhas

1716 

1717Se sua ferramenta imprime outras linhas antes do host, como mensagens de progresso, envolva-a em um arquivo batch que imprima apenas o host. O arquivo a seguir imprime a última linha da saída da sua ferramenta e sai com o código da sua ferramenta se ela falhar:

1718 

1719```batch make-devbox.cmd theme={null}

1720@echo off

1721setlocal

1722set "host="

1723set "out=%TEMP%\acme-dev-%RANDOM%.txt"

1724call "C:\Program Files\Acme\acme-dev.exe" create > "%out%"

1725set "code=%ERRORLEVEL%"

1726for /f "usebackq delims=" %%L in ("%out%") do set "host=%%L"

1727del "%out%"

1728if not "%code%"=="0" exit /b %code%

1729setlocal EnableDelayedExpansion

1730echo(!host!

1731```

1732 

1733Defina `command` como o caminho completo do arquivo, como `C:\\tools\\make-devbox.cmd` em JSON. Mantenha suas duas últimas linhas como estão, porque elas imprimem o host sem executá-lo como um comando.

1734 

1683##### Conectar a um novo host1735##### Conectar a um novo host

1684 1736 

1685Responda a duas perguntas na primeira vez que você se conectar a cada novo host:1737Responda a duas perguntas na primeira vez que você se conectar a cada novo host:

1686 1738 

1687* **Chave do host**: com a verificação de chave de host padrão do OpenSSH, confira a impressão digital da chave e então escolha se deseja se conectar. Para pular a pergunta, faça com que seu comando adicione a chave a `~/.ssh/known_hosts` antes de imprimir o host, usando uma chave que sua ferramenta obteve ao criar a máquina. Para uma porta diferente de 22, essa linha começa com `[host]:port`. Se sua ferramenta reutiliza nomes de host, remova também a linha da chave antiga.1739* **Chave do host**: com a verificação de chave de host padrão do OpenSSH, verifique a impressão digital da chave e então escolha se deseja se conectar. Para pular a pergunta, faça seu comando adicionar a chave a `~/.ssh/known_hosts`, ou `%USERPROFILE%\.ssh\known_hosts` no Windows, antes de imprimir o host:

1740 * Use uma chave que sua ferramenta obteve ao criar a máquina

1741 * Para uma porta diferente da 22, comece a linha com `[host]:port`

1742 * Se sua ferramenta reutiliza nomes de host, remova também a linha da chave antiga

1688* **Pasta**: escolha se você confia na pasta que abre lá1743* **Pasta**: escolha se você confia na pasta que abre lá

1689 1744 

1690Mantenha a verificação de chave de host ativada para esses hosts e mantenha um arquivo `known_hosts` para eles. Se `StrictHostKeyChecking` for `no` ou `accept-new` e `UserKnownHostsFile` também for `/dev/null` ou `none`, nada registra a chave. Quando sua ferramenta reutiliza um nome, você pode se conectar a uma máquina diferente sem aviso.1745Mantenha a verificação de chave de host ativada para esses hosts e mantenha um arquivo `known_hosts` para eles. Se `StrictHostKeyChecking` for `no` ou `accept-new` e `UserKnownHostsFile` também for `/dev/null` ou `none`, nada registra a chave. Quando sua ferramenta reutiliza um nome, você pode se conectar a uma máquina diferente sem aviso.


1746 1801 

1747* **Onde colocar a chave**: se sua política MDM para o Claude Code já define uma [chave de política](https://code.claude.com/docs/pt/managed-settings.md#how-claude-code-combines-managed-sources), coloque-a lá. Caso contrário, coloque-a no arquivo de configurações gerenciadas. Por padrão, essa política tem precedência sobre o arquivo, e o Desktop então ignora as entradas do arquivo. Defina-a no computador mesmo onde [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md) se aplicam: o Desktop ignora a chave lá, e também nas configurações de projeto e locais.1802* **Onde colocar a chave**: se sua política MDM para o Claude Code já define uma [chave de política](https://code.claude.com/docs/pt/managed-settings.md#how-claude-code-combines-managed-sources), coloque-a lá. Caso contrário, coloque-a no arquivo de configurações gerenciadas. Por padrão, essa política tem precedência sobre o arquivo, e o Desktop então ignora as entradas do arquivo. Defina-a no computador mesmo onde [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md) se aplicam: o Desktop ignora a chave lá, e também nas configurações de projeto e locais.

1748* **O `id`**: se a entrada `sshHostCommands` de um usuário tiver o seu `id`, apenas a sua funciona. Se qualquer outra conexão SSH o tiver, como uma no `sshConfigs` de um usuário, sua entrada fica cinza. Escolha um `id` que os usuários dificilmente escolheriam.1803* **O `id`**: se a entrada `sshHostCommands` de um usuário tiver o seu `id`, apenas a sua funciona. Se qualquer outra conexão SSH o tiver, como uma no `sshConfigs` de um usuário, sua entrada fica cinza. Escolha um `id` que os usuários dificilmente escolheriam.

1749* **O programa**: informe seu caminho completo, porque o Desktop procura um nome simples no `PATH` de cada usuário. O programa é executado como o usuário, com as variáveis que o shell de login dele exporta.1804* **O programa**: forneça seu caminho completo, porque no macOS e Linux o Desktop procura um nome simples no `PATH` de cada usuário, e no Windows uma entrada com um nome simples fica cinza. O programa é executado como o usuário, com [as variáveis desse usuário](#write-the-command).

1805* **Cada plataforma**: implante uma entrada nos computadores Windows e outra nos computadores macOS e Linux. Uma entrada com um [caminho do Windows](#write-the-command-on-windows) fica cinza no macOS e Linux, e uma com um caminho do macOS ou Linux fica cinza no Windows.

1750* **Entradas próprias dos usuários**: o Desktop trata a entrada de um usuário como um [hook](https://code.claude.com/docs/pt/hooks.md), porque ambos executam um programa no computador. Para permitir apenas as suas entradas, defina [`strictPluginOnlyCustomization`](https://code.claude.com/docs/pt/settings-reference#strictpluginonlycustomization) como `["hooks"]`, ou adicione `"hooks"` à lista dela. Você também bloqueia os hooks do Claude Code das configurações de usuário, de projeto e locais, sem forma de mantê-los. Se, em vez disso, você definir essa chave ou [`allowManagedHooksOnly`](https://code.claude.com/docs/pt/settings-reference#allowmanagedhooksonly) como `true`, você bloqueia mais, conforme a entrada de cada chave descreve.1806* **Entradas próprias dos usuários**: o Desktop trata a entrada de um usuário como um [hook](https://code.claude.com/docs/pt/hooks.md), porque ambos executam um programa no computador. Para permitir apenas as suas entradas, defina [`strictPluginOnlyCustomization`](https://code.claude.com/docs/pt/settings-reference#strictpluginonlycustomization) como `["hooks"]`, ou adicione `"hooks"` à lista dela. Você também bloqueia os hooks do Claude Code das configurações de usuário, de projeto e locais, sem forma de mantê-los. Se, em vez disso, você definir essa chave ou [`allowManagedHooksOnly`](https://code.claude.com/docs/pt/settings-reference#allowmanagedhooksonly) como `true`, você bloqueia mais, conforme a entrada de cada chave descreve.

1751* **Todas as entradas**: para desativar também suas entradas, defina [`disableAllHooks`](https://code.claude.com/docs/pt/settings-reference#disableallhooks) nas configurações gerenciadas. Se você definir [`disableDesktopLocalSessions`](https://code.claude.com/docs/pt/settings-reference#disabledesktoplocalsessions), ou uma `sshHostAllowlist` que não permite nenhum host, o seletor não lista nenhum item **Create** ou **Create another**.1807* **Todas as entradas**: para desativar também suas entradas, defina [`disableAllHooks`](https://code.claude.com/docs/pt/settings-reference#disableallhooks) nas configurações gerenciadas. Se você definir [`disableDesktopLocalSessions`](https://code.claude.com/docs/pt/settings-reference#disabledesktoplocalsessions), ou uma `sshHostAllowlist` que não permite nenhum host, o seletor não lista nenhum item **Create** ou **Create another**.

1752* **Onde os bloqueios contam**: para essas entradas, o Desktop lê `allowManagedHooksOnly`, `strictPluginOnlyCustomization` e `disableAllHooks` das configurações gerenciadas pelo servidor e do arquivo ou política do próprio computador, e aplica o resultado mais restritivo. Todas as entradas ficam cinza até que o Desktop tenha verificado as configurações gerenciadas pelo servidor no claude.ai, mesmo que sua organização não tenha nenhuma.1808* **Onde os bloqueios contam**: para essas entradas, o Desktop lê `allowManagedHooksOnly`, `strictPluginOnlyCustomization` e `disableAllHooks` das configurações gerenciadas pelo servidor e do arquivo ou política do próprio computador, e aplica o resultado mais restritivo. Todas as entradas ficam cinza até que o Desktop tenha verificado as configurações gerenciadas pelo servidor no claude.ai, mesmo que sua organização não tenha nenhuma.


1759O seletor de ambiente não lista nenhum item **Create** ou **Create another** nestes casos:1815O seletor de ambiente não lista nenhum item **Create** ou **Create another** nestes casos:

1760 1816 

1761* **O arquivo**: `~/.claude/settings.json` tem [JSON inválido ou um valor que o esquema rejeita](https://code.claude.com/docs/pt/settings.md#fix-a-broken-settings-file), você digitou a chave incorretamente, ou a colocou nas configurações de um projeto. Corrija o arquivo.1817* **O arquivo**: `~/.claude/settings.json` tem [JSON inválido ou um valor que o esquema rejeita](https://code.claude.com/docs/pt/settings.md#fix-a-broken-settings-file), você digitou a chave incorretamente, ou a colocou nas configurações de um projeto. Corrija o arquivo.

1762* **Plataforma e conta**: você usa Windows, ou um [provedor terceirizado](https://code.claude.com/docs/pt/third-party-integrations.md) em vez de uma conta Claude. Adicione cada host como uma [conexão SSH](#ssh-sessions) você mesmo.1818* **Conta**: você usa um [provedor terceirizado](https://code.claude.com/docs/pt/third-party-integrations.md) em vez de uma conta Claude. Adicione você mesmo cada host como uma [conexão SSH](#ssh-sessions).

1819* **Windows**: o Desktop é anterior à v4.16336.0, ou não se conecta pelo cliente OpenSSH. Atualize o Desktop e atenda [aos requisitos do cliente OpenSSH](#use-your-ssh-configuration), depois saia e reabra o Desktop.

1763* **Configurações da sua organização**: seu administrador desativou as sessões locais ou desativou as sessões SSH. Pergunte a ele se você pode usar comandos.1820* **Configurações da sua organização**: seu administrador desativou as sessões locais ou desativou as sessões SSH. Pergunte a ele se você pode usar comandos.

1764* **Nenhum programa `ssh`**: o Desktop não conseguiu iniciar o cliente OpenSSH no seu computador. Instale-o, ou peça ao seu administrador para permiti-lo, e então reinicie o Desktop.1821* **Nenhum programa `ssh`**: o Desktop não conseguiu iniciar o cliente OpenSSH no seu computador. Instale-o, ou peça ao seu administrador para permiti-lo, e então reinicie o Desktop.

1765 1822 

1766Uma entrada que você não consegue selecionar fica cinza. Passe o mouse sobre ela para ver o motivo:1823Uma entrada que você não consegue selecionar fica cinza. Passe o mouse sobre ela para ver o motivo:

1767 1824 

1768* **Um erro na entrada**: corrija o campo ou o comando que a mensagem nomeia. Se o `id` estiver em uso, dê outro à entrada.1825* **Um erro na entrada**: corrija o campo ou o comando que a mensagem nomeia. Se o `id` estiver em uso, dê outro à entrada. No Windows, o comando precisa [começar com o caminho completo do programa](#write-the-command-on-windows).

1769* **Um arquivo de configurações corrompido**: enquanto seu próprio arquivo de configurações estiver corrompido, as entradas do seu administrador podem ficar cinza, com uma mensagem que nomeia o arquivo. [Corrija o arquivo](https://code.claude.com/docs/pt/settings.md#fix-a-broken-settings-file).1826* **Um arquivo de configurações corrompido**: enquanto seu próprio arquivo de configurações estiver corrompido, as entradas do seu administrador podem ficar cinza, com uma mensagem que nomeia o arquivo. [Corrija o arquivo](https://code.claude.com/docs/pt/settings.md#fix-a-broken-settings-file).

1770* **Um novo host**: [**Create another**](#create-another-machine) fica cinza por um minuto depois que o Desktop salva um host. Selecione-o após esse minuto. Antes do Claude Desktop v4.4212.0, **Replace Dev box's host** fica cinza por 10 minutos.1827* **Um novo host**: [**Create another**](#create-another-machine) fica cinza por um minuto depois que o Desktop salva um host. Selecione-o após esse minuto. Antes do Claude Desktop v4.4212.0, **Replace Dev box's host** fica cinza por 10 minutos.

1771* **Os hooks estão desativados ou restritos**: suas próprias entradas funcionam apenas onde seus próprios hooks podem ser executados. Remova `disableAllHooks` das suas configurações ou pergunte ao seu administrador.1828* **Os hooks estão desativados ou restritos**: suas próprias entradas funcionam apenas onde seus próprios hooks podem ser executados. Remova `disableAllHooks` das suas configurações ou pergunte ao seu administrador.


1940| `disableMobileSimulatorTools` | defina como `true` para bloquear as ferramentas de Claude para controlar e capturar dispositivos no [painel iOS Simulator](https://code.claude.com/docs/pt/desktop-ios-simulator.md#turn-off-simulator-access). O painel permanece utilizável para os toques do próprio usuário; apenas o acesso de Claude é removido. O valor deve ser o booleano JSON `true`; a string `"true"` é ignorada. |1997| `disableMobileSimulatorTools` | defina como `true` para bloquear as ferramentas de Claude para controlar e capturar dispositivos no [painel iOS Simulator](https://code.claude.com/docs/pt/desktop-ios-simulator.md#turn-off-simulator-access). O painel permanece utilizável para os toques do próprio usuário; apenas o acesso de Claude é removido. O valor deve ser o booleano JSON `true`; a string `"true"` é ignorada. |

1941| `disableBrowserExternalNavigation` | defina como `true` para desativar a navegação externa no [painel Browser](#browse-external-sites) inteiramente. Nem usuários nem Claude podem navegar para sites externos, e as visualizações do servidor localhost dev não são afetadas. O valor deve ser o booleano JSON `true`; a string `"true"` é ignorada. |1998| `disableBrowserExternalNavigation` | defina como `true` para desativar a navegação externa no [painel Browser](#browse-external-sites) inteiramente. Nem usuários nem Claude podem navegar para sites externos, e as visualizações do servidor localhost dev não são afetadas. O valor deve ser o booleano JSON `true`; a string `"true"` é ignorada. |

1942| `sshConfigs` | pré-configure [conexões SSH](#pre-configure-ssh-connections-for-your-team) que aparecem no seletor de ambiente. Usuários não podem excluir conexões gerenciadas nem editar nada além de sua própria **Worktree folder**. |1999| `sshConfigs` | pré-configure [conexões SSH](#pre-configure-ssh-connections-for-your-team) que aparecem no seletor de ambiente. Usuários não podem excluir conexões gerenciadas nem editar nada além de sua própria **Worktree folder**. |

1943| `sshHostCommands` | ofereça aos usuários [conexões SSH cujo host vem de um comando](#distribute-commands-to-your-team), junto com as suas próprias. O Desktop a lê do arquivo de configurações gerenciadas ou da política MDM no computador, e a ignora em [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md). Requer Claude Desktop v3.6556.0 ou posterior no macOS ou Linux, conectado com uma conta Claude. |2000| `sshHostCommands` | ofereça aos usuários [conexões SSH cujo host vem de um comando](#distribute-commands-to-your-team), junto com as suas próprias. O Desktop a lê do arquivo de configurações gerenciadas ou da política MDM no computador, e a ignora em [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md). Requer Claude Desktop v3.6556.0 ou posterior no macOS ou Linux, ou v4.16336.0 ou posterior no Windows, conectado com uma conta Claude. No Windows, o Desktop também precisa [conectar-se através do cliente OpenSSH](#use-your-ssh-configuration). |

1944| `sshHostAllowlist` | restrinja [sessões SSH](#restrict-which-ssh-hosts-users-can-connect-to) a hosts cujo nome de host resolvido corresponde a um desses padrões. Lido apenas de configurações gerenciadas. |2001| `sshHostAllowlist` | restrinja [sessões SSH](#restrict-which-ssh-hosts-users-can-connect-to) a hosts cujo nome de host resolvido corresponde a um desses padrões. Lido apenas de configurações gerenciadas. |

1945| `disableDesktopLocalSessions` | defina como `true` para desativar [sessões Code que são executadas no dispositivo](#local-sessions-on-managed-devices), deixando sessões SSH para outros hosts e sessões na nuvem disponíveis. O valor deve ser o booleano JSON `true`. Lido apenas de configurações gerenciadas. Requer Claude Desktop v1.37937.0 ou posterior. |2002| `disableDesktopLocalSessions` | defina como `true` para desativar [sessões Code que são executadas no dispositivo](#local-sessions-on-managed-devices), deixando sessões SSH para outros hosts e sessões na nuvem disponíveis. O valor deve ser o booleano JSON `true`. Lido apenas de configurações gerenciadas. Requer Claude Desktop v1.37937.0 ou posterior. |

1946| `disableSshSavedPasswords` | defina como `true` para impedir que o Desktop ofereça lembrar senhas SSH e que use ou mostre as que salvou anteriormente. Ativá-la não as exclui. Lido apenas de configurações gerenciadas. Requer Claude Desktop v1.49585.0 ou posterior. |2003| `disableSshSavedPasswords` | defina como `true` para impedir que o Desktop ofereça lembrar senhas SSH e que use ou mostre as que salvou anteriormente. Ativá-la não as exclui. Lido apenas de configurações gerenciadas. Requer Claude Desktop v1.49585.0 ou posterior. |

env-vars.md +3 −2

Details

139| `ANTHROPIC_BEDROCK_BASE_URL` | Sobrescreve a URL do endpoint do Amazon Bedrock. Use para endpoints personalizados do Amazon Bedrock ou ao rotear por meio de um [gateway de LLM](https://code.claude.com/docs/pt/llm-gateway). Consulte [Amazon Bedrock](https://code.claude.com/docs/pt/amazon-bedrock.md) |139| `ANTHROPIC_BEDROCK_BASE_URL` | Sobrescreve a URL do endpoint do Amazon Bedrock. Use para endpoints personalizados do Amazon Bedrock ou ao rotear por meio de um [gateway de LLM](https://code.claude.com/docs/pt/llm-gateway). Consulte [Amazon Bedrock](https://code.claude.com/docs/pt/amazon-bedrock.md) |

140| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | Sobrescreve a URL do endpoint do Amazon Bedrock Mantle. Consulte [Endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#use-the-mantle-endpoint) |140| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | Sobrescreve a URL do endpoint do Amazon Bedrock Mantle. Consulte [Endpoint Mantle](https://code.claude.com/docs/pt/amazon-bedrock.md#use-the-mantle-endpoint) |

141| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Prefixo do perfil de inferência entre regiões (`us`, `eu`, `apac`, `jp`, `au` ou `global`) que o Claude Code tenta primeiro, em vez daquele derivado da região da AWS. Ignorado nas regiões AWS GovCloud. Requer o Claude Code v2.1.224 ou posterior. Consulte [Amazon Bedrock](https://code.claude.com/docs/pt/amazon-bedrock.md#cross-region-inference-profile-prefixes) |141| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Prefixo do perfil de inferência entre regiões (`us`, `eu`, `apac`, `jp`, `au` ou `global`) que o Claude Code tenta primeiro, em vez daquele derivado da região da AWS. Ignorado nas regiões AWS GovCloud. Requer o Claude Code v2.1.224 ou posterior. Consulte [Amazon Bedrock](https://code.claude.com/docs/pt/amazon-bedrock.md#cross-region-inference-profile-prefixes) |

142| `ANTHROPIC_BEDROCK_SERVICE_TIER` | [Nível de serviço](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html) do Amazon Bedrock (`default`, `flex` ou `priority`). Enviado como o cabeçalho `X-Amzn-Bedrock-Service-Tier`. Consulte [Amazon Bedrock](https://code.claude.com/docs/pt/amazon-bedrock.md#service-tiers) |142| `ANTHROPIC_BEDROCK_SERVICE_TIER` | [Nível de serviço](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html) do Amazon Bedrock (`default`, `flex` ou `priority`). Consulte [Amazon Bedrock](https://code.claude.com/docs/pt/amazon-bedrock.md#service-tiers) |

143| `ANTHROPIC_BETAS` | Lista separada por vírgulas de valores adicionais do cabeçalho `anthropic-beta` a incluir nas requisições de API. O Claude Code já envia os cabeçalhos beta de que precisa; use isto para aderir a um [beta da Anthropic API](https://platform.claude.com/docs/en/api/beta-headers) antes que o Claude Code adicione suporte nativo. Diferentemente da [flag `--betas`](https://code.claude.com/docs/pt/cli-reference#cli-flags), que requer autenticação por chave de API, esta variável funciona com todos os métodos de autenticação, incluindo a assinatura do Claude.ai |143| `ANTHROPIC_BETAS` | Lista separada por vírgulas de valores adicionais do cabeçalho `anthropic-beta` a incluir nas requisições de API. O Claude Code já envia os cabeçalhos beta de que precisa; use isto para aderir a um [beta da Anthropic API](https://platform.claude.com/docs/en/api/beta-headers) antes que o Claude Code adicione suporte nativo. Diferentemente da [flag `--betas`](https://code.claude.com/docs/pt/cli-reference#cli-flags), que requer autenticação por chave de API, esta variável funciona com todos os métodos de autenticação, incluindo a assinatura do Claude.ai |

144| `ANTHROPIC_CUSTOM_HEADERS` | Cabeçalhos personalizados a adicionar às requisições (formato `Name: Value`, separados por nova linha para vários cabeçalhos). Se um nome ou valor contiver um caractere que um cabeçalho HTTP não pode transportar, como uma aspa curva ou um espaço de largura zero, a requisição falha com um erro que identifica o par pela posição. Requer o Claude Code v2.1.227 ou posterior. [Invalid request header value](https://code.claude.com/docs/pt/errors.md#invalid-request-header-value) lista o conjunto exato de caracteres e onde a verificação é executada. Um valor que define um cabeçalho de credencial, organização ou tenant, roteamento ou comportamento da API, como `Authorization` ou `Host`, conta como uma [configuração que precisa de aprovação](https://code.claude.com/docs/pt/server-managed-settings.md#environment-variables-and-the-approval-dialog) quando configurações gerenciadas pelo servidor o entregam. A partir de configurações de projeto ou locais, esse valor segue as [regras sobre quando os valores de `env` se aplicam](https://code.claude.com/docs/pt/settings-reference#when-claude-code-applies-env-values) |144| `ANTHROPIC_CUSTOM_HEADERS` | Cabeçalhos personalizados a adicionar às requisições (formato `Name: Value`, separados por nova linha para vários cabeçalhos). Se um nome ou valor contiver um caractere que um cabeçalho HTTP não pode transportar, como uma aspa curva ou um espaço de largura zero, a requisição falha com um erro que identifica o par pela posição. Requer o Claude Code v2.1.227 ou posterior. [Invalid request header value](https://code.claude.com/docs/pt/errors.md#invalid-request-header-value) lista o conjunto exato de caracteres e onde a verificação é executada. Um valor que define um cabeçalho de credencial, organização ou tenant, roteamento ou comportamento da API, como `Authorization` ou `Host`, conta como uma [configuração que precisa de aprovação](https://code.claude.com/docs/pt/server-managed-settings.md#environment-variables-and-the-approval-dialog) quando configurações gerenciadas pelo servidor o entregam. A partir de configurações de projeto ou locais, esse valor segue as [regras sobre quando os valores de `env` se aplicam](https://code.claude.com/docs/pt/settings-reference#when-claude-code-applies-env-values) |

145| `ANTHROPIC_CUSTOM_MODEL_OPTION` | ID do modelo a adicionar como entrada personalizada no seletor `/model`. Use isto para tornar selecionável um modelo não padrão ou específico de um gateway sem substituir os aliases integrados. Consulte [Configuração de modelos](https://code.claude.com/docs/pt/model-config.md#add-a-custom-model-option) |145| `ANTHROPIC_CUSTOM_MODEL_OPTION` | ID do modelo a adicionar como entrada personalizada no seletor `/model`. Use isto para tornar selecionável um modelo não padrão ou específico de um gateway sem substituir os aliases integrados. Consulte [Configuração de modelos](https://code.claude.com/docs/pt/model-config.md#add-a-custom-model-option) |


238| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | Defina como `1` para ignorar a verificação de que uma resposta por streaming do [Amazon Bedrock](https://code.claude.com/docs/pt/amazon-bedrock.md) tem o content-type `application/vnd.amazon.eventstream`. Sem esta variável, quando uma resposta tem um content-type diferente, o Claude Code faz a requisição falhar com um erro que indica esse tipo, o que significa que um [gateway ou proxy está transformando a resposta](https://code.claude.com/docs/pt/amazon-bedrock.md#streaming-errors-behind-a-gateway-or-proxy). Configure o gateway para encaminhar o cabeçalho `Content-Type` e o corpo sem modificações, em vez de definir esta variável. Requer o Claude Code v2.1.208 ou posterior |238| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | Defina como `1` para ignorar a verificação de que uma resposta por streaming do [Amazon Bedrock](https://code.claude.com/docs/pt/amazon-bedrock.md) tem o content-type `application/vnd.amazon.eventstream`. Sem esta variável, quando uma resposta tem um content-type diferente, o Claude Code faz a requisição falhar com um erro que indica esse tipo, o que significa que um [gateway ou proxy está transformando a resposta](https://code.claude.com/docs/pt/amazon-bedrock.md#streaming-errors-behind-a-gateway-or-proxy). Configure o gateway para encaminhar o cabeçalho `Content-Type` e o corpo sem modificações, em vez de definir esta variável. Requer o Claude Code v2.1.208 ou posterior |

239| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | Defina como `1` para interromper o trabalho em andamento de uma [sessão em segundo plano](https://code.claude.com/docs/pt/agent-view.md) quando o [supervisor](https://code.claude.com/docs/pt/agent-view.md#the-supervisor-process) parar, reiniciar ou atualizar o processo dessa sessão, em vez de entregá-lo ao próximo processo da sessão. Esse trabalho consiste nos comandos de shell em segundo plano em execução da sessão, além dos subagentes em segundo plano a partir da v2.1.198. Afeta apenas essa transferência: enviar uma sessão para segundo plano com `←` ou [`/background`](https://code.claude.com/docs/pt/agent-view#from-inside-a-session) continua transferindo o trabalho em segundo plano em andamento. Requer o Claude Code v2.1.196 ou posterior |239| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | Defina como `1` para interromper o trabalho em andamento de uma [sessão em segundo plano](https://code.claude.com/docs/pt/agent-view.md) quando o [supervisor](https://code.claude.com/docs/pt/agent-view.md#the-supervisor-process) parar, reiniciar ou atualizar o processo dessa sessão, em vez de entregá-lo ao próximo processo da sessão. Esse trabalho consiste nos comandos de shell em segundo plano em execução da sessão, além dos subagentes em segundo plano a partir da v2.1.198. Afeta apenas essa transferência: enviar uma sessão para segundo plano com `←` ou [`/background`](https://code.claude.com/docs/pt/agent-view#from-inside-a-session) continua transferindo o trabalho em segundo plano em andamento. Requer o Claude Code v2.1.196 ou posterior |

240| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | Defina como `1` para impedir que o Claude Code encerre [comandos de shell em segundo plano](https://code.claude.com/docs/pt/interactive-mode.md#background-bash-commands) sob pressão de memória. Por padrão, no macOS e no Linux, o Claude Code encerra shells em segundo plano quando o sistema operacional reporta pressão crítica de memória RAM e a sessão está ociosa há 30 minutos, sem turno nem subagente em execução. O Windows não tem um sinal de pressão de memória, então esta variável não tem efeito nele. Requer o Claude Code v2.1.193 ou posterior |240| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | Defina como `1` para impedir que o Claude Code encerre [comandos de shell em segundo plano](https://code.claude.com/docs/pt/interactive-mode.md#background-bash-commands) sob pressão de memória. Por padrão, no macOS e no Linux, o Claude Code encerra shells em segundo plano quando o sistema operacional reporta pressão crítica de memória RAM e a sessão está ociosa há 30 minutos, sem turno nem subagente em execução. O Windows não tem um sinal de pressão de memória, então esta variável não tem efeito nele. Requer o Claude Code v2.1.193 ou posterior |

241| `CLAUDE_CODE_DISABLE_BG_STABLE_PATH` | No macOS com o instalador nativo, defina como `1` para executar o processo host de cada [sessão em segundo plano](https://code.claude.com/docs/pt/agent-view.md) a partir do binário instalado, e não de `~/.local/share/claude/ClaudeCode.app`. O macOS pode então pedir novamente permissões como [acesso a pastas](https://code.claude.com/docs/pt/agent-view.md#background-sessions-can’t-read-desktop-documents-or-downloads-on-macos), inclusive após cada atualização. Defina-a no [bloco `env`](#in-settings-files) das configurações de usuário, em um arquivo de configurações gerenciadas ou em uma política de MDM, não no seu shell. Para remover `ClaudeCode.app`, exclua-o você mesmo. Requer o Claude Code v2.1.295 ou posterior |

241| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Defina como `1` para desativar as [skills](https://code.claude.com/docs/pt/skills.md) e os workflows incluídos com o Claude Code: skills incluídas e workflows incluídos são removidos completamente, enquanto comandos integrados como `/init` continuam podendo ser digitados, mas ficam ocultos para o modelo. `/doctor` continua podendo ser digitado, como os comandos integrados; oculte-o com `DISABLE_DOCTOR_COMMAND`. Skills de plugins, `.claude/skills/` e `.claude/commands/` não são afetadas. Equivalente à configuração [`disableBundledSkills`](https://code.claude.com/docs/pt/settings-reference#disablebundledskills) |242| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | Defina como `1` para desativar as [skills](https://code.claude.com/docs/pt/skills.md) e os workflows incluídos com o Claude Code: skills incluídas e workflows incluídos são removidos completamente, enquanto comandos integrados como `/init` continuam podendo ser digitados, mas ficam ocultos para o modelo. `/doctor` continua podendo ser digitado, como os comandos integrados; oculte-o com `DISABLE_DOCTOR_COMMAND`. Skills de plugins, `.claude/skills/` e `.claude/commands/` não são afetadas. Equivalente à configuração [`disableBundledSkills`](https://code.claude.com/docs/pt/settings-reference#disablebundledskills) |

242| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | Para hosts que incorporam o Claude Code e fornecem suas próprias orientações de navegador. Defina como `1` para manter as ferramentas de navegador do [Claude in Chrome](https://code.claude.com/docs/pt/chrome.md) disponíveis, omitindo a seção do Chrome do system prompt e a [skill incluída](https://code.claude.com/docs/pt/skills.md#bundled-skills) `/claude-in-chrome`. No VS Code, a extensão na v2.1.314 ou posterior também deixa as instruções do Claude in Chrome fora das mensagens de uma sessão. Requer Claude Code v2.1.257 ou posterior |243| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | Para hosts que incorporam o Claude Code e fornecem suas próprias orientações de navegador. Defina como `1` para manter as ferramentas de navegador do [Claude in Chrome](https://code.claude.com/docs/pt/chrome.md) disponíveis, omitindo a seção do Chrome do system prompt e a [skill incluída](https://code.claude.com/docs/pt/skills.md#bundled-skills) `/claude-in-chrome`. No VS Code, a extensão na v2.1.314 ou posterior também deixa as instruções do Claude in Chrome fora das mensagens de uma sessão. Requer Claude Code v2.1.257 ou posterior |

243| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Defina como `1` para impedir o carregamento de quaisquer arquivos de memória CLAUDE.md no contexto, incluindo arquivos de memória de usuário, de projeto e de memória automática |244| `CLAUDE_CODE_DISABLE_CLAUDE_MDS` | Defina como `1` para impedir o carregamento de quaisquer arquivos de memória CLAUDE.md no contexto, incluindo arquivos de memória de usuário, de projeto e de memória automática |


312| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | Defina como `0` para desativar a compactação gzip dos corpos de requisição da Claude API, de telemetria e de publicação de [artefatos](https://code.claude.com/docs/pt/artifacts.md) enviados para `api.anthropic.com`. Por padrão, o Claude Code compacta corpos de requisição grandes em conexões diretas e ignora a compactação quando você envia requisições por meio de um proxy, configura um certificado de cliente ou define `NODE_EXTRA_CA_CERTS`. Use `0` se um [proxy com inspeção de TLS](https://code.claude.com/docs/pt/network-config.md#ca-certificate-store) que o Claude Code não consegue detectar tratar incorretamente requisições compactadas |313| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | Defina como `0` para desativar a compactação gzip dos corpos de requisição da Claude API, de telemetria e de publicação de [artefatos](https://code.claude.com/docs/pt/artifacts.md) enviados para `api.anthropic.com`. Por padrão, o Claude Code compacta corpos de requisição grandes em conexões diretas e ignora a compactação quando você envia requisições por meio de um proxy, configura um certificado de cliente ou define `NODE_EXTRA_CA_CERTS`. Use `0` se um [proxy com inspeção de TLS](https://code.claude.com/docs/pt/network-config.md#ca-certificate-store) que o Claude Code não consegue detectar tratar incorretamente requisições compactadas |

313| `CLAUDE_CODE_HIDE_CWD` | Defina como `1` para ocultar o diretório de trabalho no logotipo de inicialização. Útil para compartilhamentos de tela ou gravações em que o caminho expõe seu nome de usuário do sistema operacional |314| `CLAUDE_CODE_HIDE_CWD` | Defina como `1` para ocultar o diretório de trabalho no logotipo de inicialização. Útil para compartilhamentos de tela ou gravações em que o caminho expõe seu nome de usuário do sistema operacional |

314| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | Sobrescreve o endereço do host usado para se conectar à extensão do IDE. Por padrão, o Claude Code detecta automaticamente o endereço correto, incluindo o roteamento de WSL para Windows |315| `CLAUDE_CODE_IDE_HOST_OVERRIDE` | Sobrescreve o endereço do host usado para se conectar à extensão do IDE. Por padrão, o Claude Code detecta automaticamente o endereço correto, incluindo o roteamento de WSL para Windows |

315| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Defina como `1` para ignorar a instalação automática de extensões do IDE. Equivalente a definir [`autoInstallIdeExtension`](https://code.claude.com/docs/pt/settings-reference#autoinstallideextension) como `false` |316| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Defina como `1` para impedir que `/ide` instale a extensão do IDE. Equivalente a definir [`autoInstallIdeExtension`](https://code.claude.com/docs/pt/settings-reference#autoinstallideextension) como `false` |

316| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | Defina como `1` para ignorar a validação das entradas do lockfile do IDE durante a conexão. Use quando a conexão automática não encontrar seu IDE apesar de ele estar em execução |317| `CLAUDE_CODE_IDE_SKIP_VALID_CHECK` | Defina como `1` para ignorar a validação das entradas do lockfile do IDE durante a conexão. Use quando a conexão automática não encontrar seu IDE apesar de ele estar em execução |

317| `CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` | Tamanho do contexto, em tokens, a partir do qual a [compactação ociosa](https://code.claude.com/docs/pt/settings-reference.md#idlecompaction) se aplica a uma conversa (padrão: `200000`). Aceita um número inteiro positivo, e qualquer outro valor é ignorado. Valores abaixo de `100000` são elevados para `100000`, o limite mais baixo. A compactação ociosa está ativada por padrão para conversas que atendem às suas condições. Para desativá-la, defina `idleCompaction` como `false`. Requer Claude Code v2.1.290 ou posterior |318| `CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS` | Tamanho do contexto, em tokens, a partir do qual a [compactação ociosa](https://code.claude.com/docs/pt/settings-reference.md#idlecompaction) se aplica a uma conversa (padrão: `200000`). Aceita um número inteiro positivo, e qualquer outro valor é ignorado. Valores abaixo de `100000` são elevados para `100000`, o limite mais baixo. A compactação ociosa está ativada por padrão para conversas que atendem às suas condições. Para desativá-la, defina `idleCompaction` como `false`. Requer Claude Code v2.1.290 ou posterior |

318| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | Quantos [subagentes](https://code.claude.com/docs/pt/sub-agents.md#concurrent-subagent-limit) podem estar em execução em uma sessão antes que a ferramenta Agent se recuse a criar outro (padrão: 20). Aceita um número inteiro positivo em dígitos simples; qualquer outro valor é ignorado, então a variável pode ajustar o limite, mas não desativá-lo. Requer Claude Code v2.1.217 ou posterior |319| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | Quantos [subagentes](https://code.claude.com/docs/pt/sub-agents.md#concurrent-subagent-limit) podem estar em execução em uma sessão antes que a ferramenta Agent se recuse a criar outro (padrão: 20). Aceita um número inteiro positivo em dígitos simples; qualquer outro valor é ignorado, então a variável pode ajustar o limite, mas não desativá-lo. Requer Claude Code v2.1.217 ou posterior |

errors.md +144 −4

Details

55| `spend limit reached` / `spend limit unavailable` | [Usage limits](#spend-limit-reached) |55| `spend limit reached` / `spend limit unavailable` | [Usage limits](#spend-limit-reached) |

56| `Not logged in · Please run /login` | [Authentication](#not-logged-in) |56| `Not logged in · Please run /login` | [Authentication](#not-logged-in) |

57| `Couldn't save your login` | [Authentication](#couldnt-save-your-login) |57| `Couldn't save your login` | [Authentication](#couldnt-save-your-login) |

58| `Sign in again to take your previous account or API key off the config file.` | [Autenticação](#sign-in-again-to-take-your-previous-account-or-api-key-off-the-config-file) |

59| `Your account or API key may still be in the config file. Run claude auth logout.` | [Autenticação](#your-account-or-api-key-may-still-be-in-the-config-file) |

58| `Authentication required · Sign in again to continue` | [Authentication](#not-logged-in) |60| `Authentication required · Sign in again to continue` | [Authentication](#not-logged-in) |

59| `Could not resolve authentication method` | [Authentication](#could-not-resolve-authentication-method) |61| `Could not resolve authentication method` | [Authentication](#could-not-resolve-authentication-method) |

60| `Invalid API key` | [Authentication](#invalid-api-key) |62| `Invalid API key` | [Authentication](#invalid-api-key) |


82| `Couldn't verify your organization's policy for remote control` | [Troubleshoot Remote Control](https://code.claude.com/docs/pt/remote-control.md#couldnt-verify-your-organizations-policy-for-remote-control) |84| `Couldn't verify your organization's policy for remote control` | [Troubleshoot Remote Control](https://code.claude.com/docs/pt/remote-control.md#couldnt-verify-your-organizations-policy-for-remote-control) |

83| `Remote Control is disabled by your organization's policy` | [Troubleshoot Remote Control](https://code.claude.com/docs/pt/remote-control.md#remote-control-is-disabled-by-your-organizations-policy) |85| `Remote Control is disabled by your organization's policy` | [Troubleshoot Remote Control](https://code.claude.com/docs/pt/remote-control.md#remote-control-is-disabled-by-your-organizations-policy) |

84| `Remote Control was turned off by your organization's policy` | [Troubleshoot Remote Control](https://code.claude.com/docs/pt/remote-control.md#remote-control-was-turned-off-by-your-organizations-policy) |86| `Remote Control was turned off by your organization's policy` | [Troubleshoot Remote Control](https://code.claude.com/docs/pt/remote-control.md#remote-control-was-turned-off-by-your-organizations-policy) |

87| `Session failed: working folder not found:` | [Solucionar problemas do Remote Control](https://code.claude.com/docs/pt/remote-control.md#working-folder-not-found) |

88| `The program file this Remote Control started from is gone` | [Solucionar problemas do Remote Control](https://code.claude.com/docs/pt/remote-control.md#program-file-is-gone) |

89| `Session failed: spawn error:` seguido de uma mensagem `ENOENT` | [Solucionar problemas do Remote Control](https://code.claude.com/docs/pt/remote-control.md#program-file-is-gone) |

85| `OAuth token revoked` / `OAuth token has expired` | [Authentication](#oauth-token-revoked-or-expired) |90| `OAuth token revoked` / `OAuth token has expired` | [Authentication](#oauth-token-revoked-or-expired) |

86| `Failed to authenticate: OAuth token revoked` | [Authentication](#oauth-token-revoked-or-expired) |91| `Failed to authenticate: OAuth token revoked` | [Authentication](#oauth-token-revoked-or-expired) |

87| `Your account does not have access to Claude. Please login again or contact your administrator.` | [Authentication](#oauth-token-revoked-or-expired) |92| `Your account does not have access to Claude. Please login again or contact your administrator.` | [Authentication](#oauth-token-revoked-or-expired) |


165| `Request too large for the API's 32MB request limit` | [Request errors](#request-too-large) |170| `Request too large for the API's 32MB request limit` | [Request errors](#request-too-large) |

166| `Image was too large` | [Request errors](#image-was-too-large) |171| `Image was too large` | [Request errors](#image-was-too-large) |

167| `API Error: an image in the conversation could not be processed and was removed` | [Request errors](#image-was-too-large) |172| `API Error: an image in the conversation could not be processed and was removed` | [Request errors](#image-was-too-large) |

173| `An image in the conversation exceeds the dimension limit for many-image requests` | [Erros de requisição](#image-was-too-large) |

168| `Unable to resize image` | [Request errors](#unable-to-resize-image) |174| `Unable to resize image` | [Request errors](#unable-to-resize-image) |

169| `Request rejected as unprocessable by the model` | [Request errors](#request-rejected-as-unprocessable-by-the-model) |175| `Request rejected as unprocessable by the model` | [Request errors](#request-rejected-as-unprocessable-by-the-model) |

170| `PDF too large` / `PDF is password protected` / `pdftoppm is not installed` | [Request errors](#pdf-errors) |176| `PDF too large` / `PDF is password protected` / `pdftoppm is not installed` | [Request errors](#pdf-errors) |


229| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [Command-line errors](#invalid-agents-configuration) |235| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [Command-line errors](#invalid-agents-configuration) |

230| `Error: --agents file not found` | [Command-line errors](#invalid-agents-configuration) |236| `Error: --agents file not found` | [Command-line errors](#invalid-agents-configuration) |

231| `Error: Settings file exceeds the 2MiB limit` | [Command-line errors](#settings-file-exceeds-the-2mib-limit) |237| `Error: Settings file exceeds the 2MiB limit` | [Command-line errors](#settings-file-exceeds-the-2mib-limit) |

238| `Configuration error in` | [Erros de linha de comando](#configuration-error-in-claude-json) |

239| `Claude configuration file at <path> was empty and no backup holds anything: starting with defaults.` | [Erros de linha de comando](#claude-configuration-file-was-empty) |

232| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [Command-line errors](#the-current-directory-no-longer-exists) |240| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [Command-line errors](#the-current-directory-no-longer-exists) |

233| `Temp directory <dir> ... Refusing to use it` / `Claude Code's temporary directory <dir> could not be created` | [Command-line errors](#temp-directory-refused-or-cannot-be-created) |241| `Temp directory <dir> ... Refusing to use it` / `Claude Code's temporary directory <dir> could not be created` | [Command-line errors](#temp-directory-refused-or-cannot-be-created) |

234| `ENOSPC: no space left on device, mkdir '<dir>'` | [Command-line errors](#temp-directory-refused-or-cannot-be-created) |242| `ENOSPC: no space left on device, mkdir '<dir>'` | [Command-line errors](#temp-directory-refused-or-cannot-be-created) |


334| `cannot contain null bytes (\0)` | [Tool errors](#path-cannot-contain-null-bytes) |342| `cannot contain null bytes (\0)` | [Tool errors](#path-cannot-contain-null-bytes) |

335| `Path contains null bytes` | [Tool errors](#path-cannot-contain-null-bytes) |343| `Path contains null bytes` | [Tool errors](#path-cannot-contain-null-bytes) |

336| `command contains the invisible character U+FEFF (byte order mark) or U+180E (Mongolian vowel separator), and was not run` | [Erros de ferramenta](#command-contains-an-invisible-character) |344| `command contains the invisible character U+FEFF (byte order mark) or U+180E (Mongolian vowel separator), and was not run` | [Erros de ferramenta](#command-contains-an-invisible-character) |

345| `This call was not run. The command was approved before Claude Code restarted` | [Erros de ferramenta](#command-approved-before-a-restart-was-not-run) |

337| `File is too large to read as an image (the limit is 128MB)` | [Tool errors](#file-is-too-large-to-read-as-an-image) |346| `File is too large to read as an image (the limit is 128MB)` | [Tool errors](#file-is-too-large-to-read-as-an-image) |

338| `Cannot read this as an image: <path> is a pipe or a device` | [Tool errors](#file-is-too-large-to-read-as-an-image) |347| `Cannot read this as an image: <path> is a pipe or a device` | [Tool errors](#file-is-too-large-to-read-as-an-image) |

339| `subagent_type is required: the general-purpose agent is not available in this session` | [Tool errors](#subagent-type-is-required) |348| `subagent_type is required: the general-purpose agent is not available in this session` | [Tool errors](#subagent-type-is-required) |


420| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [Configuration warnings](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |429| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [Configuration warnings](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |

421| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [Configuration warnings](#skill-or-command-name-refused) |430| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [Configuration warnings](#skill-or-command-name-refused) |

422| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Configuration warnings](#workspace-has-not-been-trusted) |431| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [Configuration warnings](#workspace-has-not-been-trusted) |

432| `Make this change again later: <path> could not be updated, so it applies to this session only` | [Avisos de configuração](#make-this-change-again-later) |

423| `is a network path, which cannot be added as a working directory` | [Configuration warnings](#working-directory-is-a-network-path) |433| `is a network path, which cannot be added as a working directory` | [Configuration warnings](#working-directory-is-a-network-path) |

424| `Remote managed settings failed to load (<cause>)` | [Configuration warnings](#remote-managed-settings-failed-to-load) |434| `Remote managed settings failed to load (<cause>)` | [Configuration warnings](#remote-managed-settings-failed-to-load) |

435| `Your organization requires remote managed settings to load, but they could not be loaded` | [Impor inicialização fail-closed](https://code.claude.com/docs/pt/server-managed-settings.md#enforce-fail-closed-startup) |

436| `Remote managed settings are still loading` | [Avisos de configuração](#remote-managed-settings-failed-to-load) |

437| `Remote managed settings did not load` | [Avisos de configuração](#remote-managed-settings-failed-to-load) |

438| `Claude Code couldn't load your organization's settings` / `Claude Code couldn't reach Anthropic to load your organization's settings` / `requires them before a session can start` | [Avisos de configuração](#couldnt-load-your-organizations-settings) |

439| `Claude Code can't start this session yet` | [Avisos de configuração](#couldnt-load-your-organizations-settings) |

440| `Your Claude session has expired. Sign in again to continue (claude auth login).` | [Avisos de configuração](#couldnt-load-your-organizations-settings) |

425| `Managed settings were not approved; exiting without applying them.` | [Configuration warnings](#managed-settings-were-not-approved) |441| `Managed settings were not approved; exiting without applying them.` | [Configuration warnings](#managed-settings-were-not-approved) |

426| `Your organization's managed settings need your approval, which couldn't be asked for here.` | [Configuration warnings](#managed-settings-need-your-approval) |442| `Your organization's managed settings need your approval, which couldn't be asked for here.` | [Configuration warnings](#managed-settings-need-your-approval) |

427| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [Configuration warnings](#managed-settings-block-the-default-model) |443| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [Configuration warnings](#managed-settings-block-the-default-model) |


454| `is ignored — managed settings set allowManagedReadPathsOnly` / `is ignored — managed settings set allowManagedDomainsOnly` | [Configuration warnings](#sandbox-allow-entries-are-ignored-under-a-managed-lock) |470| `is ignored — managed settings set allowManagedReadPathsOnly` / `is ignored — managed settings set allowManagedDomainsOnly` | [Configuration warnings](#sandbox-allow-entries-are-ignored-under-a-managed-lock) |

455| `Sandbox mask files left behind at write-deny paths` | [Configuration warnings](#stale-sandbox-mask-files-left-by-a-killed-session) |471| `Sandbox mask files left behind at write-deny paths` | [Configuration warnings](#stale-sandbox-mask-files-left-by-a-killed-session) |

456| `Stale sandbox mask files left by a killed session` | [Configuration warnings](#stale-sandbox-mask-files-left-by-a-killed-session) |472| `Stale sandbox mask files left by a killed session` | [Configuration warnings](#stale-sandbox-mask-files-left-by-a-killed-session) |

473| `Ubuntu's AppArmor restriction on user namespaces stops bubblewrap here` | [Solução de problemas de sandboxing](https://code.claude.com/docs/pt/sandboxing.md#apparmor-restriction-stops-bubblewrap) |

474| `bwrap: setting up uid map: Permission denied` / `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` | [Solução de problemas de sandboxing](https://code.claude.com/docs/pt/sandboxing.md#bwrap-uid-map-permission-denied) |

457| As respostas parecem ter qualidade inferior ao normal | [Response quality](#responses-seem-lower-quality-than-usual) |475| As respostas parecem ter qualidade inferior ao normal | [Response quality](#responses-seem-lower-quality-than-usual) |

458 476 

459## Tentativas automáticas477## Tentativas automáticas


1031* Execute `/login` para se autenticar com sua assinatura Claude ou conta do Console1049* Execute `/login` para se autenticar com sua assinatura Claude ou conta do Console

1032* Se você esperava que uma variável de ambiente o autenticasse, confirme que `ANTHROPIC_API_KEY` está definida e exportada no shell onde você iniciou o `claude`1050* Se você esperava que uma variável de ambiente o autenticasse, confirme que `ANTHROPIC_API_KEY` está definida e exportada no shell onde você iniciou o `claude`

1033* Para CI ou automação em que o login interativo não é possível, configure um script [`apiKeyHelper`](https://code.claude.com/docs/pt/settings-reference#apikeyhelper) que obtenha uma chave na inicialização1051* Para CI ou automação em que o login interativo não é possível, configure um script [`apiKeyHelper`](https://code.claude.com/docs/pt/settings-reference#apikeyhelper) que obtenha uma chave na inicialização

1052* Se jobs `claude -p` encerram com esta mensagem quando alguém entra novamente na mesma conta e organização claude.ai, atualize o Claude Code onde esse login é executado. Antes da v2.1.318, o Claude Code removia o login armazenado durante esse login, antes de salvar o novo.

1034* Consulte [Precedência de autenticação](https://code.claude.com/docs/pt/authentication.md#authentication-precedence) para entender qual credencial o Claude Code usa quando várias estão presentes1053* Consulte [Precedência de autenticação](https://code.claude.com/docs/pt/authentication.md#authentication-precedence) para entender qual credencial o Claude Code usa quando várias estão presentes

1035 1054 

1036Se for solicitado que você faça login repetidamente, consulte [Não conectado ou token expirado](https://code.claude.com/docs/pt/troubleshoot-install.md#not-logged-in-or-token-expired) para verificações do relógio do sistema e etapas de recuperação do armazenamento de credenciais do macOS.1055Se for solicitado que você faça login repetidamente, consulte [Não conectado ou token expirado](https://code.claude.com/docs/pt/troubleshoot-install.md#not-logged-in-or-token-expired) para verificações do relógio do sistema e etapas de recuperação do armazenamento de credenciais do macOS.


1441* Em outras plataformas, execute `/login` novamente1460* Em outras plataformas, execute `/login` novamente

1442* Se o login ainda não for salvo, consulte [Não conectado ou token expirado](https://code.claude.com/docs/pt/troubleshoot-install.md#not-logged-in-or-token-expired) para o comando de desbloqueio do keychain e outras etapas de recuperação do armazenamento de credenciais1461* Se o login ainda não for salvo, consulte [Não conectado ou token expirado](https://code.claude.com/docs/pt/troubleshoot-install.md#not-logged-in-or-token-expired) para o comando de desbloqueio do keychain e outras etapas de recuperação do armazenamento de credenciais

1443 1462 

1463### Sign in again to take your previous account or API key off the config file

1464 

1465Este aviso após você entrar significa que qualquer conta com a qual você estava conectado antes ainda pode estar armazenada em [`~/.claude.json`](https://code.claude.com/docs/pt/claude-directory#ce-claude-json):

1466 

1467```text theme={null}

1468Sign in again to take your previous account or API key off the config file.

1469```

1470 

1471Uma chave de API também pode ainda estar em `~/.claude.json` se um login do Console tiver criado uma no Linux ou no Windows.

1472 

1473**O que fazer:**

1474 

1475* Execute `claude auth login` no seu shell para entrar novamente. O Claude Code então tenta novamente o salvamento que remove do arquivo a conta ou a chave de API substituída.

1476 

1477### Your account or API key may still be in the config file

1478 

1479Você executou `/logout` ou `claude auth logout`, e o Claude Code desconectou este processo, mas não conseguiu confirmar que [`~/.claude.json`](https://code.claude.com/docs/pt/claude-directory#ce-claude-json) não contém mais sua conta. Ou o salvamento não foi concluído, ou o arquivo não pôde ser lido de volta para verificação.

1480 

1481```text theme={null}

1482Your account or API key may still be in the config file. Run claude auth logout.

1483```

1484 

1485Uma chave de API também pode ainda estar em `~/.claude.json` se um login do Console tiver criado uma no Linux ou no Windows.

1486 

1487**O que fazer:**

1488 

1489* Execute `claude auth logout` no seu shell para tentar o salvamento novamente. Quando o salvamento for concluído, o comando imprime `Successfully logged out from your Anthropic account.`

1490 

1444### Couldn't start the local listener that receives the browser sign-in1491### Couldn't start the local listener that receives the browser sign-in

1445 1492 

1446Cada uma destas mensagens de `/login`, `claude auth login` ou `claude setup-token` significa que o Claude Code não conseguiu abrir a porta em `127.0.0.1` para onde seu navegador retorna o resultado do login.1493Cada uma destas mensagens de `/login`, `claude auth login` ou `claude setup-token` significa que o Claude Code não conseguiu abrir a porta em `127.0.0.1` para onde seu navegador retorna o resultado do login.


2420Image was too large. Double press esc to go back and try again with a smaller image.2467Image was too large. Double press esc to go back and try again with a smaller image.

2421API Error: 400 ... image dimensions exceed max allowed size2468API Error: 400 ... image dimensions exceed max allowed size

2422API Error: an image in the conversation could not be processed and was removed.2469API Error: an image in the conversation could not be processed and was removed.

2470An image in the conversation exceeds the dimension limit for many-image requests (3000px). Run /compact to remove old images from context, or start a new session.

2423```2471```

2424 2472 

2425A linha `could not be processed and was removed` significa que a API recusou uma imagem na conversa, como uma acima dos limites de tamanho ou de dimensão.2473A linha `could not be processed and was removed` significa que a API recusou uma imagem na conversa, como uma acima dos limites de tamanho ou de dimensão.


2434 2482 

2435* Redimensione a imagem antes de colá-la. A API aceita imagens de até 8000 pixels no lado mais longo para uma única imagem, ou 3000 pixels quando há mais de 20 imagens no contexto.2483* Redimensione a imagem antes de colá-la. A API aceita imagens de até 8000 pixels no lado mais longo para uma única imagem, ou 3000 pixels quando há mais de 20 imagens no contexto.

2436* Faça uma captura de tela mais recortada da região relevante em vez da tela inteira2484* Faça uma captura de tela mais recortada da região relevante em vez da tela inteira

2485* Para a mensagem `dimension limit for many-image requests`, execute `/compact` no prompt do Claude Code se a mensagem o mencionar, ou inicie uma nova sessão com menos imagens

2486 

2487A mensagem `dimension limit for many-image requests` mostra o limite de pixels informado no erro da API.

2437 2488 

2438### Unable to resize image2489### Unable to resize image

2439 2490 


3223 3274 

3224* Aponte `--settings` para um arquivo de configurações JSON regular com menos de 2 MiB. Consulte [Configurações](https://code.claude.com/docs/pt/settings.md) para ver o formato.3275* Aponte `--settings` para um arquivo de configurações JSON regular com menos de 2 MiB. Consulte [Configurações](https://code.claude.com/docs/pt/settings.md) para ver o formato.

3225 3276 

3277### Configuration error in \~/.claude.json

3278 

3279O Claude Code não conseguiu analisar `~/.claude.json`, o arquivo que contém os detalhes da sua conta, os servidores MCP e o estado por projeto. Seu arquivo não foi alterado. Uma inicialização [não interativa](https://code.claude.com/docs/pt/headless.md), como `claude -p`, sai com o código 1 toda vez até que você repare o arquivo.

3280 

3281Quando o Claude Code encontra um [backup](https://code.claude.com/docs/pt/claude-directory.md#cleaned-up-automatically), a saída o menciona e imprime uma linha `cp` que o copia de volta:

3282 

3283```text wrap theme={null}

3284Claude configuration file at /home/user/.claude.json is corrupted: <JSON parser's message>

3285The corrupted file has been backed up to: /home/user/.claude/backups/.claude.json.corrupted.1793664000000

3286A backup file exists at: /home/user/.claude/backups/.claude.json.backup.1793660400000

3287You can manually restore it by running: cp -f "/home/user/.claude/backups/.claude.json.backup.1793660400000" "/home/user/.claude.json"

3288 

3289Configuration error in /home/user/.claude.json: <JSON parser's message>

3290```

3291 

3292**O que fazer:**

3293 

3294* **A saída tem uma linha `cp`**: execute essa linha no seu terminal. No Windows, execute-a no PowerShell. Ela substitui o arquivo corrompido pelo backup, uma versão anterior de `~/.claude.json`.

3295* **A saída não tem uma linha `cp`, ou o erro volta depois que você a executa**: corrija o JSON em `~/.claude.json`, copie outro arquivo `.claude.json.backup.<timestamp>` de [`~/.claude/backups/`](https://code.claude.com/docs/pt/claude-directory#cleaned-up-automatically) por cima dele, se houver um, ou renomeie-o. Sem arquivo em `~/.claude.json`, o Claude Code inicia com as configurações padrão e sem nada do que o arquivo continha.

3296 

3297Antes da v2.1.318, você ficava com os padrões em `~/.claude.json` depois que uma inicialização não interativa imprimia esse erro, então a próxima inicialização era executada sem a sua configuração.

3298 

3299### Claude configuration file was empty and no backup holds anything

3300 

3301Esta mensagem na inicialização significa que o arquivo mencionado estava vazio e nenhuma das [cópias `.backup`](https://code.claude.com/docs/pt/claude-directory#cleaned-up-automatically) do arquivo contém nada. O Claude Code iniciou com os padrões para o que esse arquivo contém. Seus arquivos `settings.json` e `.mcp.json` são arquivos separados.

3302 

3303```text wrap theme={null}

3304Claude configuration file at /home/user/.claude.json was empty and no backup holds anything: starting with defaults.

3305```

3306 

3307**O que fazer:**

3308 

3309* Configure novamente o que você tinha configurado nesse arquivo. Por exemplo, adicione seus [servidores MCP](https://code.claude.com/docs/pt/mcp.md#mcp-installation-scopes) de escopo `user` e `local` com `claude mcp add` no seu terminal.

3310* Faça login novamente se o Claude Code solicitar

3311 

3312Antes da v2.1.318, o Claude Code informava um arquivo vazio sem backup como [corrompido](#configuration-error-in-claude-json).

3313 

3226### O diretório atual não existe mais3314### O diretório atual não existe mais

3227 3315 

3228Você iniciou `claude` a partir de um diretório que foi excluído ou movido depois que seu shell entrou nele, por exemplo um worktree ou um diretório temporário que outro shell removeu. O Claude Code não consegue ler seu diretório de trabalho, então sai com código 1 antes de iniciar a sessão, tanto no modo interativo quanto no [não interativo](https://code.claude.com/docs/pt/headless.md). Antes da v2.1.239, o Claude Code travava com o código-fonte do bundle minificado e uma stack `ENOENT ... uv_cwd` bruta no stderr em vez desta mensagem.3316Você iniciou `claude` a partir de um diretório que foi excluído ou movido depois que seu shell entrou nele, por exemplo um worktree ou um diretório temporário que outro shell removeu. O Claude Code não consegue ler seu diretório de trabalho, então sai com código 1 antes de iniciar a sessão, tanto no modo interativo quanto no [não interativo](https://code.claude.com/docs/pt/headless.md). Antes da v2.1.239, o Claude Code travava com o código-fonte do bundle minificado e uma stack `ENOENT ... uv_cwd` bruta no stderr em vez desta mensagem.


3334* **`Error: Workspace not trusted. <folder> is your home directory`**: como a confiança para seu diretório pessoal nunca é salva, executar `claude` ali primeiro não ajuda. Execute `claude ultrareview` a partir de um diretório de projeto, depois de executar `claude` ali uma vez para aceitar a caixa de diálogo de confiança, ou acrescente `--trust-workspace`.3422* **`Error: Workspace not trusted. <folder> is your home directory`**: como a confiança para seu diretório pessoal nunca é salva, executar `claude` ali primeiro não ajuda. Execute `claude ultrareview` a partir de um diretório de projeto, depois de executar `claude` ali uma vez para aceitar a caixa de diálogo de confiança, ou acrescente `--trust-workspace`.

3335* **`No answer in time.` seguido de `Error: Workspace not trusted`**: a pergunta `Trust <folder>? [y/N]` ficou sem resposta por 5 minutos. Execute `claude ultrareview` novamente e responda.3423* **`No answer in time.` seguido de `Error: Workspace not trusted`**: a pergunta `Trust <folder>? [y/N]` ficou sem resposta por 5 minutos. Execute `claude ultrareview` novamente e responda.

3336* **`Ultrareview did not start: <folder> is not trusted`**: você recusou na pergunta `Trust <folder>? [y/N]`, por exemplo respondendo `n` ou pressionando Enter. Para iniciar a revisão, execute `claude ultrareview` novamente e responda `y`.3424* **`Ultrareview did not start: <folder> is not trusted`**: você recusou na pergunta `Trust <folder>? [y/N]`, por exemplo respondendo `n` ou pressionando Enter. Para iniciar a revisão, execute `claude ultrareview` novamente e responda `y`.

3337* **``Ultrareview did not start: `--trust-workspace` takes no value``**: algo que não é uma flag vem após `--trust-workspace`, como um número de PR ou `false`. Se você não confia na pasta, omita a flag. Para confiar nela durante esta execução, coloque o número do PR ou o branch base antes da flag: `claude ultrareview 1234 --trust-workspace`.3425* **``Ultrareview did not start: `--trust-workspace` takes no value``**: algo que não é uma flag vem depois de `--trust-workspace`, como um número de PR ou `false`. Se você não confia na pasta, omita a flag. Para confiar nela nesta execução, coloque o número do PR ou o branch base antes da flag: `claude ultrareview 1234 --trust-workspace`.

3338 3426 

3339Antes da v2.1.309, `claude ultrareview` não aceitava `--trust-workspace`.3427Antes da v2.1.309, `claude ultrareview` não aceitava `--trust-workspace`.

3340 3428 


3627Mensagens semelhantes são disparadas antes mesmo de o comando ser executado:3715Mensagens semelhantes são disparadas antes mesmo de o comando ser executado:

3628 3716 

3629* `Shell command permission check failed for pattern "..."`: a verificação de permissão do comando não o permitiu. [Permission checks on injected commands](https://code.claude.com/docs/pt/skills.md#permission-checks-on-injected-commands) explica quais resultados abortam em cada modo de permissão e como pré-aprovar um comando com `allowed-tools`3717* `Shell command permission check failed for pattern "..."`: a verificação de permissão do comando não o permitiu. [Permission checks on injected commands](https://code.claude.com/docs/pt/skills.md#permission-checks-on-injected-commands) explica quais resultados abortam em cada modo de permissão e como pré-aprovar um comando com `allowed-tools`

3630* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: o frontmatter da skill exige bash em uma máquina sem ele. Instale o Git for Windows ou altere o frontmatter para `shell: powershell`. Consulte [How injected commands run](https://code.claude.com/docs/pt/skills.md#how-injected-commands-run)3718* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: o frontmatter da skill exige bash em uma máquina que não o tem. Instale o Git for Windows ou altere o frontmatter para `shell: powershell`. Consulte [How injected commands run](https://code.claude.com/docs/pt/skills.md#how-injected-commands-run)

3631 3719 

3632**O que fazer:**3720**O que fazer:**

3633 3721 


3780 3868 

3781* **Você não passou um branch base**: o Claude Code comparou com o branch padrão do repositório e sugere passar seu branch base explicitamente, como no exemplo acima3869* **Você não passou um branch base**: o Claude Code comparou com o branch padrão do repositório e sugere passar seu branch base explicitamente, como no exemplo acima

3782* **Você passou um branch base que já estava no seu clone**: a dica diz ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``3870* **Você passou um branch base que já estava no seu clone**: a dica diz ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``

3783* **Você passou um branch base que não estava no seu clone**: o Claude Code o buscou de origin antes de comparar. A dica diz ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``; quando o Claude Code não consegue determinar se o seu clone é shallow, ele sugere `git fetch --unshallow origin` em vez disso. Antes da v2.1.221, a dica sugeria `git fetch --unshallow origin` para todo branch base buscado, e em um clone completo esse comando falha com `fatal: --unshallow on a complete repository does not make sense`.3871* **Você passou um branch base que não estava no seu clone**: o Claude Code o buscou da origin antes de comparar. A dica diz ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``; quando o Claude Code não consegue determinar se seu clone é shallow, ele sugere `git fetch --unshallow origin` em vez disso. Antes da v2.1.221, a dica sugeria `git fetch --unshallow origin` para todo branch base buscado, e em um clone completo esse comando falha com `fatal: --unshallow on a complete repository does not make sense`.

3784 3872 

3785**O que fazer:**3873**O que fazer:**

3786 3874 


4666* **Para um comando que Claude escreveu**: você não tem nada a corrigir. A mensagem diz ao Claude como reescrever o comando.4754* **Para um comando que Claude escreveu**: você não tem nada a corrigir. A mensagem diz ao Claude como reescrever o comando.

4667* **Para um arquivo de skill ou de comando**: a mensagem vem após `No shell command in <name> was run`. Veja [onde encontrar o caractere e removê-lo](#no-shell-command-was-run).4755* **Para um arquivo de skill ou de comando**: a mensagem vem após `No shell command in <name> was run`. Veja [onde encontrar o caractere e removê-lo](#no-shell-command-was-run).

4668 4756 

4757### Comando aprovado antes de o Claude Code reiniciar não foi executado

4758 

4759Um comando de shell que você aprovou não foi executado, e Claude recebe esta mensagem como o resultado do comando:

4760 

4761```text wrap theme={null}

4762This call was not run. The command was approved before Claude Code restarted, and Claude Code could not confirm that the shell is back in the directory where it was approved. That directory may be gone or replaced, lie outside the directory where the session started, or be one that Claude Code needs approval to enter or is not allowed to examine. The shell's directory is <directory>. If the command still makes sense, cd to the directory it was meant for and make the call again; it may need approval again.

4763```

4764 

4765A terceira frase da mensagem pode, em vez disso, dizer `It does not keep track of that directory across a restart in a session that has been in a worktree.`

4766 

4767**O que fazer:**

4768 

4769* Deixe Claude continuar e responda ao prompt se for solicitado que você aprove o comando novamente.

4770 

4669### File is too large to read as an image4771### File is too large to read as an image

4670 4772 

4671Claude tentou ler um arquivo como imagem com a [ferramenta Read](https://code.claude.com/docs/pt/tools-reference.md#read-tool-behavior), e o arquivo é maior que 128 MB, o máximo que Read carrega de um arquivo de imagem. Nada foi lido, e Claude recebe este erro como o resultado da ferramenta:4773Claude tentou ler um arquivo como imagem com a [ferramenta Read](https://code.claude.com/docs/pt/tools-reference.md#read-tool-behavior), e o arquivo é maior que 128 MB, o máximo que Read carrega de um arquivo de imagem. Nada foi lido, e Claude recebe este erro como o resultado da ferramenta:


5818 5920 

5819### Falha ao carregar configurações gerenciadas remotamente5921### Falha ao carregar configurações gerenciadas remotamente

5820 5922 

5821Sua sessão é elegível para [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md), mas Claude Code não conseguiu buscá-las ou não conseguiu aplicar o que o servidor retornou, então mostra este aviso em sessões interativas.5923Sua sessão é elegível para [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md), mas Claude Code não conseguiu buscá-las ou não conseguiu aplicar o que o servidor retornou, então mostra este aviso em sessões interativas e na aba Code do Claude Desktop.

5822 5924 

5823A causa entre parênteses nomeia o que falhou, como `network error`, `request timed out` ou `authentication rejected (401)`. A causa `no setting in the server response could be applied as written` significa que o servidor respondeu mas nenhuma das configurações que retornou passou na [validação](https://code.claude.com/docs/pt/server-managed-settings.md#invalid-entries-in-delivered-settings). Antes da v2.1.282, esta causa lia `server returned invalid settings`.5925A causa entre parênteses nomeia o que falhou, como `network error`, `request timed out` ou `authentication rejected (401)`. A causa `no setting in the server response could be applied as written` significa que o servidor respondeu mas nenhuma das configurações que retornou passou na [validação](https://code.claude.com/docs/pt/server-managed-settings.md#invalid-entries-in-delivered-settings). Antes da v2.1.282, esta causa lia `server returned invalid settings`.

5824 5926 


5827* **Configurações em cache de uma busca anterior bem-sucedida**: Claude Code executa a sessão nessa política em cache, exceto as [variáveis de ambiente retidas](https://code.claude.com/docs/pt/server-managed-settings.md#fetch-and-caching-behavior), e a linha lê `using cached policy`.5929* **Configurações em cache de uma busca anterior bem-sucedida**: Claude Code executa a sessão nessa política em cache, exceto as [variáveis de ambiente retidas](https://code.claude.com/docs/pt/server-managed-settings.md#fetch-and-caching-behavior), e a linha lê `using cached policy`.

5828* **Sem cache**: Claude Code executa a sessão sem configurações gerenciadas pelo servidor, e a linha lê `no remote policy applied`.5930* **Sem cache**: Claude Code executa a sessão sem configurações gerenciadas pelo servidor, e a linha lê `no remote policy applied`.

5829 5931 

5932Na aba Code, o aviso aparece como uma linha na conversa quando você envia uma mensagem, e uma nova linha aparece quando o estado da busca muda. Três mensagens relacionadas aparecem da mesma forma:

5933 

5934* `Remote managed settings are still loading`: a busca ainda estava em execução quando a sessão prosseguiu

5935* `Remote managed settings did not load`: a busca terminou sem resposta

5936* `Remote managed settings have now loaded`: as configurações foram carregadas após um desses avisos, e o resto da linha diz se uma política remota se aplica

5937 

5830**O que fazer:**5938**O que fazer:**

5831 5939 

5832* Aja sobre a causa que a mensagem nomeia: para uma causa de rede, verifique se esta máquina pode alcançar `api.anthropic.com`; para uma causa de autenticação, verifique seu login com `/status`5940* Aja sobre a causa que a mensagem nomeia: para uma causa de rede, verifique se esta máquina pode alcançar `api.anthropic.com`; para uma causa de autenticação, verifique seu login com `/status`


5835 5943 

5836Antes da v2.1.248, Claude Code relatava uma busca de configurações falhada apenas no log de depuração.5944Antes da v2.1.248, Claude Code relatava uma busca de configurações falhada apenas no log de depuração.

5837 5945 

5946### Claude Code não conseguiu carregar as configurações da sua organização

5947 

5948Sua sessão não foi iniciada porque as configurações da sua organização, incluindo suas [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md), precisam ser carregadas primeiro e Claude Code não conseguiu carregá-las. Por exemplo:

5949 

5950```text theme={null}

5951Claude Code couldn't reach Anthropic to load your organization's settings (could not connect). <Organization name> requires them before a session can start.

5952```

5953 

5954Se a mensagem estiver em uma caixa de diálogo intitulada `Claude Code can't start this session yet`, a caixa de diálogo se fecha e a sessão inicia assim que as configurações são carregadas.

5955 

5956No [modo não interativo](https://code.claude.com/docs/pt/headless.md) e em [sessões em segundo plano](https://code.claude.com/docs/pt/agent-view.md), Claude Code imprime a mensagem e sai com status 1 em vez disso.

5957 

5958**O que fazer:**

5959 

5960* **`could not connect` ou `the reply came from a network proxy, not Anthropic`**: verifique sua conexão de rede e, em uma rede corporativa, peça à equipe de TI para permitir HTTPS para `api.anthropic.com/api/claude_code/policy_limits` e `api.anthropic.com/api/claude_code/settings`. Depois selecione **Retry now** ou execute seu comando novamente.

5961* **`timed out`, `Anthropic returned an error` ou `Anthropic asked it to retry shortly`**: deixe a caixa de diálogo tentar novamente ou execute seu comando novamente mais tarde. Verifique [status.anthropic.com](https://status.anthropic.com) se isso continuar acontecendo.

5962* **`still loading` ou `couldn't verify your sign-in with Anthropic yet`**: deixe a caixa de diálogo tentar novamente ou execute seu comando novamente. Se a mensagem de login continuar voltando, faça login novamente executando `claude auth login` no seu shell.

5963* **`Your Claude session has expired`**: o login armazenado nesta máquina não é mais válido, então tentar novamente não ajudará. Na caixa de diálogo, selecione **Sign in again** para fechar Claude Code; depois, no seu shell, execute `claude auth login`, que funciona mesmo enquanto as sessões não podem iniciar.

5964* **`none of the settings the server returned could be applied as written`**: peça ao seu administrador para corrigir as [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md#invalid-entries-in-delivered-settings) da organização e depois tente novamente.

5965 

5838### As configurações gerenciadas não foram aprovadas5966### As configurações gerenciadas não foram aprovadas

5839 5967 

5840As [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md) de sua organização incluem configurações que precisam de sua aprovação, e você recusou a [caixa de diálogo de aprovação de segurança](https://code.claude.com/docs/pt/server-managed-settings.md#security-approval-dialogs), então Claude Code sai sem aplicá-las:5968As [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md) de sua organização incluem configurações que precisam de sua aprovação, e você recusou a [caixa de diálogo de aprovação de segurança](https://code.claude.com/docs/pt/server-managed-settings.md#security-approval-dialogs), então Claude Code sai sem aplicá-las:


6294 6422 

6295Antes da v2.1.257, `claude doctor` não sinalizava esses arquivos; versões anteriores deixam os mesmos espaços reservados para trás quando uma sessão é morta.6423Antes da v2.1.257, `claude doctor` não sinalizava esses arquivos; versões anteriores deixam os mesmos espaços reservados para trás quando uma sessão é morta.

6296 6424 

6425### Make this change again later: \~/.claude.json could not be updated

6426 

6427Este aviso em stderr significa que uma alteração em [`~/.claude.json`](https://code.claude.com/docs/pt/claude-directory#ce-claude-json), como um login ou uma resposta a um prompt de confiança, não foi salva no arquivo:

6428 

6429```text theme={null}

6430Make this change again later: /home/user/.claude.json could not be updated, so it applies to this session only.

6431```

6432 

6433**O que fazer:**

6434 

6435* Faça a alteração novamente em uma sessão posterior. Por exemplo, execute `/login` novamente ou responda ao prompt de confiança novamente.

6436 

6297## As respostas parecem ter qualidade inferior ao usual6437## As respostas parecem ter qualidade inferior ao usual

6298 6438 

6299Se as respostas do Claude parecerem menos capazes do que você espera, mas nenhum erro for exibido, a causa geralmente é o estado da conversa em vez do modelo em si. Claude Code não muda silenciosamente versões de modelo. Ele pode mudar para um modelo de fallback nestes casos:6439Se as respostas do Claude parecerem menos capazes do que você espera, mas nenhum erro for exibido, a causa geralmente é o estado da conversa em vez do modelo em si. Claude Code não muda silenciosamente versões de modelo. Ele pode mudar para um modelo de fallback nestes casos:

headless.md +3 −1

Details

48 48 

49No modo bare, Claude Code nunca lê credenciais OAuth ou o keychain do sistema. Para a API Anthropic, defina `ANTHROPIC_API_KEY` no ambiente, com uma chave criada no [Claude Console](https://platform.claude.com), ou forneça um `apiKeyHelper` no JSON `--settings`. Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry continuam a ler suas próprias credenciais de provedor como de costume.49No modo bare, Claude Code nunca lê credenciais OAuth ou o keychain do sistema. Para a API Anthropic, defina `ANTHROPIC_API_KEY` no ambiente, com uma chave criada no [Claude Console](https://platform.claude.com), ou forneça um `apiKeyHelper` no JSON `--settings`. Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry continuam a ler suas próprias credenciais de provedor como de costume.

50 50 

51No modo bare Claude tem acesso às ferramentas Bash, leitura de arquivo e edição de arquivo. Passe qualquer contexto que você precise com uma flag:51No modo bare Claude tem acesso às ferramentas Bash, leitura de arquivo e edição de arquivo. Passe o contexto de que você precisa com uma flag:

52 52 

53| Para carregar | Use |53| Para carregar | Use |

54| - | - |54| - | - |


58| [Agentes personalizados](https://code.claude.com/docs/pt/sub-agents.md#choose-the-subagent-scope) | `--agents <file-or-json>` |58| [Agentes personalizados](https://code.claude.com/docs/pt/sub-agents.md#choose-the-subagent-scope) | `--agents <file-or-json>` |

59| Um plugin | `--plugin-dir <path>`, `--plugin-url <url>` |59| Um plugin | `--plugin-dir <path>`, `--plugin-url <url>` |

60 60 

61Os hooks ainda não são executados no modo bare quando você os passa com `--settings`, ou no [`hooks/hooks.json`](https://code.claude.com/docs/pt/plugins/components#hooks) ou na [chave de manifesto `hooks`](https://code.claude.com/docs/pt/plugins/manifest-reference#hooks) de um plugin que você carrega com uma flag. Não use o modo bare para uma execução que precise deles.

62 

61O modo bare também limita o que acontece enquanto a sessão é executada:63O modo bare também limita o que acontece enquanto a sessão é executada:

62 64 

63* **Servidores MCP**: apenas os servidores fornecidos na linha de comando se conectam, por exemplo com `--mcp-config`. Em uma sessão interativa, Claude Code também pula a conexão automática com o IDE, a menos que você passe `--ide`.65* **Servidores MCP**: apenas os servidores fornecidos na linha de comando se conectam, por exemplo com `--mcp-config`. Em uma sessão interativa, Claude Code também pula a conexão automática com o IDE, a menos que você passe `--ide`.

Details

96Never edit a migration after it has merged. Add a new migration instead.96Never edit a migration after it has merged. Add a new migration instead.

97```97```

98 98 

99Quando você inicia Claude de `packages/api/`, ele carrega tanto `packages/api/CLAUDE.md` quanto o `CLAUDE.md` raiz. Claude vê as instruções locais ao lado das regras de todo o repositório, sem instruções de `packages/web/` no contexto. O mesmo vale para qualquer subdiretório em uma árvore não-monorepo. Para confirmar quais arquivos carregaram, execute `/context` e verifique a lista sob **Memory files**.99Quando você inicia Claude de `packages/api/`, ele carrega tanto `packages/api/CLAUDE.md` quanto o `CLAUDE.md` raiz. Claude vê as instruções locais ao lado das regras de todo o repositório, sem instruções de `packages/web/` no contexto. O mesmo vale para qualquer subdiretório em uma árvore não-monorepo. Para confirmar quais arquivos carregaram, execute [`/context all`](https://code.claude.com/docs/pt/commands#all-commands) e verifique a lista sob **Memory files**.

100 100 

101Algumas maneiras de manter os arquivos atualizados conforme a base de código e os modelos mudam:101Algumas maneiras de manter os arquivos atualizados conforme a base de código e os modelos mudam:

102 102 

memory.md +6 −4

Details

67 67 

68### Configure um CLAUDE.md de projeto68### Configure um CLAUDE.md de projeto

69 69 

70Um 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, portanto, concentre-se em padrões em nível de projeto em vez de preferências pessoais. Para confirmar que o arquivo foi carregado, execute `/context` em uma sessão e verifique a lista em **Memory files**.70Um 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, portanto, concentre-se em padrões em nível de projeto em vez de preferências pessoais.

71 

72Para confirmar que o arquivo foi carregado, execute [`/context all`](https://code.claude.com/docs/pt/commands#all-commands) em uma sessão e verifique a lista em **Memory files**. No [modo de tela cheia](https://code.claude.com/docs/pt/fullscreen.md), `/context` sozinho recolhe essa lista.

71 73 

72> [!TIP]74> [!TIP]

73>75>


461* **Edição**: Claude lê `CLAUDE.md` através do link, mas as ferramentas Edit e Write [recusam-se a escrever através de um symlink](https://code.claude.com/docs/pt/errors.md#refusing-after-a-symlink-changed), e a recusa direciona Claude para editar o alvo do link, `AGENTS.md`, em vez disso463* **Edição**: Claude lê `CLAUDE.md` através do link, mas as ferramentas Edit e Write [recusam-se a escrever através de um symlink](https://code.claude.com/docs/pt/errors.md#refusing-after-a-symlink-changed), e a recusa direciona Claude para editar o alvo do link, `AGENTS.md`, em vez disso

462* **Windows**: se você ou qualquer pessoa que clona o repositório trabalha no Windows, use a importação `@AGENTS.md` em vez disso. Criar um symlink lá precisa de privilégios de Administrador ou Modo de Desenvolvedor, e Git verifica um symlink confirmado como um arquivo de texto simples a menos que `core.symlinks` esteja habilitado, o que deixa esse clone com um `CLAUDE.md` de uma linha no lugar de suas instruções464* **Windows**: se você ou qualquer pessoa que clona o repositório trabalha no Windows, use a importação `@AGENTS.md` em vez disso. Criar um symlink lá precisa de privilégios de Administrador ou Modo de Desenvolvedor, e Git verifica um symlink confirmado como um arquivo de texto simples a menos que `core.symlinks` esteja habilitado, o que deixa esse clone com um `CLAUDE.md` de uma linha no lugar de suas instruções

463 465 

464Com qualquer uma das abordagens, execute `/context` em sua próxima sessão e confirme que `CLAUDE.md` aparece em **Memory files**.466Com qualquer uma das abordagens, execute `/context all` em sua próxima sessão e confirme que `CLAUDE.md` aparece em **Memory files**.

465 467 

466### Migrate instructions from other tools468### Migrate instructions from other tools

467 469 


567 569 

568## Visualize e edite com `/memory`570## Visualize e edite com `/memory`

569 571 

570O comando `/memory` lista seus arquivos CLAUDE.md, CLAUDE.local.md e outros locais de arquivo de memória em escopos de usuário e projeto, incluindo entradas CLAUDE.md de usuário e projeto para arquivos que ainda não existem. Também permite que você alterne a memória automática ativada ou desativada e fornece uma opção para abrir a pasta de memória automática. Selecione qualquer arquivo para abri-lo no seu editor; selecionar um que ainda não existe o cria primeiro. Para verificar quais arquivos `CLAUDE.md` e arquivos de regras foram carregados na inicialização, execute `/context`.572O comando `/memory` lista seus arquivos CLAUDE.md, CLAUDE.local.md e outros locais de arquivo de memória em escopos de usuário e projeto. A lista inclui entradas CLAUDE.md de usuário e projeto para arquivos que ainda não existem. O comando também permite que você ative ou desative a memória automática e fornece uma opção para abrir a pasta de memória automática. Selecione qualquer arquivo para abri-lo no seu editor; selecionar um que ainda não existe o cria primeiro.

571 573 

572Editores GUI como VS Code abrem o arquivo em uma janela separada, e você pode continuar usando a sessão enquanto está aberta. Editores de terminal como Vim assumem o controle do terminal até você sair.574Editores GUI como VS Code abrem o arquivo em uma janela separada, e você pode continuar usando a sessão enquanto está aberta. Editores de terminal como Vim assumem o controle do terminal até você sair.

573 575 


583 585 

584Para depurar:586Para depurar:

585 587 

586* Execute `/context` e verifique a lista sob **Memory files** para conferir os arquivos CLAUDE.md e CLAUDE.local.md que devem ser carregados na inicialização. Se um deles estiver faltando lá, Claude não pode vê-lo. Use `/memory` para abrir e editar os arquivos.588* Execute `/context all` e verifique a lista sob **Memory files** para conferir os arquivos CLAUDE.md e CLAUDE.local.md que devem ser carregados na inicialização. Se um deles estiver faltando lá, Claude não pode vê-lo. Use `/memory` para abrir e editar os arquivos.

587* Se um aviso `Instruction file not loaded` aparecer, veja [o que ele significa e o que fazer a respeito](https://code.claude.com/docs/pt/errors.md#instruction-file-not-loaded).589* Se um aviso `Instruction file not loaded` aparecer, veja [o que ele significa e o que fazer a respeito](https://code.claude.com/docs/pt/errors.md#instruction-file-not-loaded).

588* Um `CLAUDE.md` em um subdiretório do seu diretório de trabalho não aparece sob **Memory files**, porque ele é carregado sob demanda em vez de na inicialização. Quando ele é carregado, uma linha `Loaded` com seu caminho aparece no terminal. Para testar um novo, crie-o a partir do seu shell em vez de pedir a Claude que o escreva, e depois peça a Claude que leia um arquivo nesse subdiretório.590* Um `CLAUDE.md` em um subdiretório do seu diretório de trabalho não aparece sob **Memory files**, porque ele é carregado sob demanda em vez de na inicialização. Quando ele é carregado, uma linha `Loaded` com seu caminho aparece no terminal. Para testar um novo, crie-o a partir do seu shell em vez de pedir a Claude que o escreva, e depois peça a Claude que leia um arquivo nesse subdiretório.

589* Verifique se o CLAUDE.md relevante está em um local que é carregado para sua sessão (veja [Escolha onde colocar arquivos CLAUDE.md](#choose-where-to-put-claude-md-files)).591* Verifique se o CLAUDE.md relevante está em um local que é carregado para sua sessão (veja [Escolha onde colocar arquivos CLAUDE.md](#choose-where-to-put-claude-md-files)).

Details

245>245>

246> **Como padrão**: defina `defaultMode` em [configurações](https://code.claude.com/docs/pt/settings.md#where-settings-live). O aplicativo de desktop lê os mesmos arquivos de configurações que a CLI e aplica o modo de permissão a novas sessões locais.246> **Como padrão**: defina `defaultMode` em [configurações](https://code.claude.com/docs/pt/settings.md#where-settings-live). O aplicativo de desktop lê os mesmos arquivos de configurações que a CLI e aplica o modo de permissão a novas sessões locais.

247>247>

248> Um modo que você escolhe no seletor de modo é lembrado por pasta e tem precedência sobre `defaultMode` para essa pasta. Plan é a exceção: escolhê-lo se aplica apenas à sessão atual.248> Um modo que você escolhe no seletor de modo em uma sessão local é lembrado por pasta e tem precedência sobre um `defaultMode` nas configurações `.claude/` do projeto. Uma nova sessão local ainda pode iniciar em um `defaultMode` de `~/.claude/settings.json` ou de configurações gerenciadas, então verifique o seletor antes da sua primeira mensagem. Se você escolher Plan, ele se aplica apenas a esta sessão.

249>249>

250> Para onde `defaultMode` vai em um arquivo de configurações, veja o exemplo em [Inicie em um modo de permissão diferente](#start-in-a-different-mode).250> Para onde `defaultMode` vai em um arquivo de configurações, veja o exemplo em [Inicie em um modo de permissão diferente](#start-in-a-different-mode).

251 251 


372 372 

373* **Uma conexão direta com a API Anthropic**: em sessões de terminal interativo e em sessões `-p`, Agent SDK, [extensão VS Code](https://code.claude.com/docs/pt/vs-code.md) e [aplicativo desktop](https://code.claude.com/docs/pt/desktop.md), qualquer que seja seu plano ou tipo de conta, conforme a Anthropic disponibiliza o recurso. Verifique seu tipo de sessão segundo estas versões mínimas de Claude Code:373* **Uma conexão direta com a API Anthropic**: em sessões de terminal interativo e em sessões `-p`, Agent SDK, [extensão VS Code](https://code.claude.com/docs/pt/vs-code.md) e [aplicativo desktop](https://code.claude.com/docs/pt/desktop.md), qualquer que seja seu plano ou tipo de conta, conforme a Anthropic disponibiliza o recurso. Verifique seu tipo de sessão segundo estas versões mínimas de Claude Code:

374 * Em sessões de terminal interativo, pedir ao servidor requer Claude Code v2.1.271 ou posterior nos planos Pro, Max, Ultra e Team. Nos planos Enterprise e contas da API Claude, essas sessões requerem v2.1.278 ou posterior.374 * Em sessões de terminal interativo, pedir ao servidor requer Claude Code v2.1.271 ou posterior nos planos Pro, Max, Ultra e Team. Nos planos Enterprise e contas da API Claude, essas sessões requerem v2.1.278 ou posterior.

375 * Em sessões `-p`, Agent SDK, extensão VS Code e aplicativo desktop, pedir ao servidor requer Claude Code v2.1.281 ou posterior375 * Em sessões `-p` e da extensão VS Code, pedir ao servidor requer Claude Code v2.1.278 ou posterior

376 * Em sessões do Agent SDK e do aplicativo desktop, pedir ao servidor requer Claude Code v2.1.281 ou posterior

376 * A partir da v2.1.282, uma sessão que [não busca feature flags](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching), por exemplo porque você desativou a telemetria, pede ao servidor por padrão em qualquer tipo de sessão377 * A partir da v2.1.282, uma sessão que [não busca feature flags](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching), por exemplo porque você desativou a telemetria, pede ao servidor por padrão em qualquer tipo de sessão

377* **Um provedor de nuvem, ou um gateway de LLM ou proxy**: em [Claude Platform on AWS](https://code.claude.com/docs/pt/claude-platform-on-aws.md), Amazon Bedrock, Agent Platform do Google Cloud e Microsoft Foundry, e sempre que você aponta `ANTHROPIC_BASE_URL` para um [gateway de LLM ou proxy](https://code.claude.com/docs/pt/llm-gateway), qualquer que seja seu plano. Pedir por padrão requer Claude Code v2.1.278 ou posterior.378* **Um provedor de nuvem, ou um gateway de LLM ou proxy**: em [Claude Platform on AWS](https://code.claude.com/docs/pt/claude-platform-on-aws.md), Amazon Bedrock, Agent Platform do Google Cloud e Microsoft Foundry, e sempre que você aponta `ANTHROPIC_BASE_URL` para um [gateway de LLM ou proxy](https://code.claude.com/docs/pt/llm-gateway), qualquer que seja seu plano. Pedir por padrão requer Claude Code v2.1.278 ou posterior.

378* **Uma sessão [gateway de aplicativos Claude](https://code.claude.com/docs/pt/claude-apps-gateway) conectada**: requer Claude Code v2.1.280 ou posterior379* **Uma sessão [gateway de aplicativos Claude](https://code.claude.com/docs/pt/claude-apps-gateway) conectada**: requer Claude Code v2.1.280 ou posterior

permissions.md +1 −1

Details

69 69 

70## Modos de permissão70## Modos de permissão

71 71 

72Claude Code suporta vários modos de permissão que controlam como ele aprova chamadas de ferramentas. Veja [Modos de permissão](https://code.claude.com/docs/pt/permission-modes.md) para quando usar cada um. Para alterar o modo em que as sessões começam, defina `defaultMode` em seus [arquivos de configuração](https://code.claude.com/docs/pt/settings.md#where-settings-live). [Qual modo uma sessão começa](https://code.claude.com/docs/pt/permission-modes.md#which-mode-a-session-starts-in) cobre o padrão integrado para cada plano e o que a extensão VS Code lê.72Claude Code suporta vários modos de permissão que controlam como ele aprova chamadas de ferramentas. Veja [Modos de permissão](https://code.claude.com/docs/pt/permission-modes.md) para quando usar cada um. Para alterar o modo de permissão padrão para novas sessões, defina `defaultMode` em seus [arquivos de configuração](https://code.claude.com/docs/pt/settings.md#where-settings-live). [Qual modo uma sessão começa](https://code.claude.com/docs/pt/permission-modes.md#which-mode-a-session-starts-in) cobre o padrão integrado para cada plano e o que a extensão VS Code lê.

73 73 

74| Modo | Descrição |74| Modo | Descrição |

75| :- | :- |75| :- | :- |

Details

571| :- | :- | :- |571| :- | :- | :- |

572| Comandos de hook | Em qualquer lugar em `command` e `args` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PROJECT_DIR` e `CLAUDE_PLUGIN_OPTION_<KEY>` |572| Comandos de hook | Em qualquer lugar em `command` e `args` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PROJECT_DIR` e `CLAUDE_PLUGIN_OPTION_<KEY>` |

573| Comandos de monitor | Em qualquer lugar em `command` | Não exportado |573| Comandos de monitor | Em qualquer lugar em `command` | Não exportado |

574| Servidores MCP `stdio` | `command`, `args`, `env` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA` |574| Servidores MCP `stdio` | `command`, `args`, `env` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PROJECT_DIR` |

575| Servidores MCP `http`, `sse`, `ws` | `url`, `headers`, `headersHelper` | Não aplicável |575| Servidores MCP `http`, `sse`, `ws` | `url`, `headers`, `headersHelper` | Não aplicável |

576| Servidores LSP | `command`, `args`, `env`, `workspaceFolder` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PROJECT_DIR` |576| Servidores LSP | `command`, `args`, `env`, `workspaceFolder` | `CLAUDE_PLUGIN_ROOT`, `CLAUDE_PLUGIN_DATA`, `CLAUDE_PROJECT_DIR` |

577| Conteúdo de skill, comando e agente | Em qualquer lugar no corpo Markdown | Não aplicável |577| Conteúdo de skill, comando e agente | Em qualquer lugar no corpo Markdown | Não aplicável |

Details

154| Evento | Dispara quando | Um hook pode retornar |154| Evento | Dispara quando | Um hook pode retornar |

155| :- | :- | :- |155| :- | :- | :- |

156| `agent.offer` | Um tipo de subagente é oferecido ao Claude | `{ isOffered: false }` para retê-lo |156| `agent.offer` | Um tipo de subagente é oferecido ao Claude | `{ isOffered: false }` para retê-lo |

157| `agent.spawn` | Um subagente ou um colega de uma [equipe de agentes](https://code.claude.com/docs/pt/agent-teams.md) está prestes a iniciar. Para um colega de equipe, `e.isTeammate` é `true`. | `next({ ...e, model })` para escolher seu modelo, ou `{ deny: reason }` |157| `agent.spawn` | Um subagente ou um colega de uma [equipe de agentes](https://code.claude.com/docs/pt/agent-teams.md) está prestes a iniciar, ou um subagente que terminou ou foi interrompido está prestes a ser executado novamente. Para um colega de equipe, `e.isTeammate` é `true`. Para uma execução retomada, `e.resume` é definido. | `next({ ...e, model })` para escolher o modelo de um que está iniciando, ou `{ deny: reason }` |

158 158 

159Quando o Claude retoma um subagente com a ferramenta [`SendMessage`](https://code.claude.com/docs/pt/sub-agents#resume-subagents), seu hook `agent.spawn` não é executado novamente. Para recusar as chamadas de `SendMessage` que retomam um subagente, faça a correspondência dessa ferramenta em um hook [`tool.call`](https://code.claude.com/docs/pt/plugins/mods/events#guard-or-change-a-tool-call).159Seu hook `agent.spawn` também é executado quando um subagente que terminou ou foi interrompido está prestes a ser executado novamente, como quando o Claude envia a ele uma mensagem com a ferramenta [`SendMessage`](https://code.claude.com/docs/pt/sub-agents#resume-subagents). Nesse evento, `e.resume` é `{ agentId }`. Se o seu hook conta subagentes, ignore os eventos em que `e.resume` está definido, para que um subagente retomado não seja contado novamente.

160 

161Retorne `{ deny: reason }` para recusar uma execução retomada. A execução não começa, e o subagente permanece como estava. Quando uma chamada de `SendMessage` solicitou a execução, o Claude lê `a plugin declined the resume:` seguido do seu motivo como o resultado dessa chamada. Se você passar um evento alterado para `next` em uma execução retomada, como um `model` diferente, o Claude Code ignora a alteração.

162 

163> [!NOTE]

164>

165> O evento para uma execução retomada requer o Claude Code v2.1.299 ou posterior. Antes da v2.1.299, seu hook `agent.spawn` não era executado quando um subagente era retomado. Nessas versões, para recusar as chamadas de `SendMessage` que retomam um subagente, faça a correspondência dessa ferramenta em um hook [`tool.call`](https://code.claude.com/docs/pt/plugins/mods/events#guard-or-change-a-tool-call).

160 166 

161### Interface167### Interface

162 168 

Details

502* Problema de rede ou proxy: um firewall ou proxy pode estar bloqueando a requisição HTTPS de saída. O Remote Control requer acesso à API da Anthropic na porta 443.502* Problema de rede ou proxy: um firewall ou proxy pode estar bloqueando a requisição HTTPS de saída. O Remote Control requer acesso à API da Anthropic na porta 443.

503* Falha na criação da sessão: se você também vir `Session creation failed — see debug log`, a falha ocorreu mais cedo na configuração. Verifique se sua assinatura está ativa.503* Falha na criação da sessão: se você também vir `Session creation failed — see debug log`, a falha ocorreu mais cedo na configuração. Verifique se sua assinatura está ativa.

504 504 

505### "working folder not found"

506 

507No terminal que executa [`claude remote-control`](#start-a-remote-control-session), `Session failed: working folder not found:` seguido de um caminho entre aspas significa que uma sessão não pôde ser iniciada porque não existe nenhuma pasta nesse caminho.

508 

509* **O servidor ainda está em execução**: restaure a pasta e inicie a sessão novamente, ou pare o servidor

510* **O servidor foi encerrado**: execute `claude remote-control` novamente a partir de uma pasta que exista

511 

512Antes da v2.1.318, uma sessão que falhava dessa forma mostrava `Session failed: spawn error:` e uma mensagem `ENOENT` que nomeava um arquivo de programa em vez da pasta ausente.

513 

514### "The program file this Remote Control started from is gone"

515 

516Este aviso no terminal que executa [`claude remote-control`](#start-a-remote-control-session) significa que o arquivo de programa a partir do qual o servidor foi iniciado está ausente, e as novas sessões executam a versão mais recente que o substituiu. Para mover o servidor também para essa versão, pare-o e execute `claude remote-control` novamente. Se o Claude Code estiver instalado em um armazenamento de rede, reinicie o servidor agora e siga [Instalar em armazenamento de rede](https://code.claude.com/docs/pt/setup.md#install-on-network-storage). Caso contrário, as novas sessões iniciam sem necessidade de reinicialização.

517 

518Quando o arquivo de programa está ausente e o Claude Code não encontra nenhuma versão mais recente para executar, as novas sessões falham. O terminal mostra um erro como `Session failed: spawn error:` seguido de uma mensagem `ENOENT`. Pare o servidor, [instale o Claude Code](https://code.claude.com/docs/pt/setup.md#install-claude-code) novamente se `claude` não for executado no seu shell, e execute `claude remote-control` novamente. Antes da v2.1.318, as novas sessões falhavam dessa forma mesmo com uma versão mais recente instalada.

519 

505### "Couldn't reconnect to your Remote Control session"520### "Couldn't reconnect to your Remote Control session"

506 521 

507Quando você retoma uma conversa com `claude --resume` ou `claude --continue`, o Claude Code se reconecta à sessão de Remote Control registrada nessa conversa. Esta mensagem significa que a reconexão falhou por um motivo que pode ser temporário, como uma interrupção de rede ou um erro do servidor, então o Claude Code não consegue confirmar se a sessão remota ainda existe.522Quando você retoma uma conversa com `claude --resume` ou `claude --continue`, o Claude Code se reconecta à sessão de Remote Control registrada nessa conversa. Esta mensagem significa que a reconexão falhou por um motivo que pode ser temporário, como uma interrupção de rede ou um erro do servidor, então o Claude Code não consegue confirmar se a sessão remota ainda existe.

sandboxing.md +59 −27

Details

71* **Overrides**: escolha se os comandos que falham no sandbox podem recorrer à execução fora do sandbox. Esta é a configuração [`allowUnsandboxedCommands`](https://code.claude.com/docs/pt/settings-reference#sandbox-allowunsandboxedcommands)71* **Overrides**: escolha se os comandos que falham no sandbox podem recorrer à execução fora do sandbox. Esta é a configuração [`allowUnsandboxedCommands`](https://code.claude.com/docs/pt/settings-reference#sandbox-allowunsandboxedcommands)

72* **Config**: visualize as configurações resolvidas do sandbox72* **Config**: visualize as configurações resolvidas do sandbox

73 73 

74Se o painel mostrar apenas uma aba Dependencies, um pacote obrigatório está faltando. Instale-o conforme descrito em [Configurar Linux e WSL2](#set-up-linux-and-wsl2), reinicie o Claude Code e execute `/sandbox` novamente.74Se o painel mostrar apenas uma aba Dependencies, o sandbox ainda não pode ser iniciado. Corrija o que a aba relata conforme descrito em [Configurar Linux e WSL2](#set-up-linux-and-wsl2), reinicie o Claude Code e execute `/sandbox` novamente.

75 75 

76**2. Escolha um modo**76**2. Escolha um modo**

77 77 


97 97 

98> [!WARNING]98> [!WARNING]

99>99>

100> Por padrão, se o sandbox não puder ser iniciado porque uma dependência está ausente ou a plataforma não é compatível, o Claude Code executa os comandos sem sandboxing. Para fazer o Claude Code encerrar na inicialização em vez disso, defina [`sandbox.failIfUnavailable`](https://code.claude.com/docs/pt/settings-reference#sandbox-failifunavailable) como `true`. Implantações gerenciadas que exigem sandboxing como barreira de segurança podem usar essa configuração.100> Por padrão, quando a plataforma não é compatível com o sandbox ou a verificação de dependências na inicialização falha, o Claude Code executa os comandos sem sandboxing. Para fazer o Claude Code encerrar na inicialização em vez disso, defina [`sandbox.failIfUnavailable`](https://code.claude.com/docs/pt/settings-reference#sandbox-failifunavailable) como `true`. Implantações gerenciadas que exigem sandboxing como barreira de segurança podem usar essa configuração.

101 101 

102### Confirmar que os comandos são executados dentro do sandbox102### Confirmar que os comandos são executados dentro do sandbox

103 103 


135 135 

136O ripgrep vem incluído no binário nativo do Claude Code. O filtro seccomp é opcional e adiciona o bloqueio de sockets de domínio Unix. Instale-o com `npm install -g @anthropic-ai/sandbox-runtime` se estiver ausente.136O ripgrep vem incluído no binário nativo do Claude Code. O filtro seccomp é opcional e adiciona o bloqueio de sockets de domínio Unix. Instale-o com `npm install -g @anthropic-ai/sandbox-runtime` se estiver ausente.

137 137 

138Quando uma dependência obrigatória está ausente, a aba Dependencies é a única exibida até que você a instale. Quando apenas o filtro seccomp opcional está ausente, a aba Dependencies aparece junto com as outras abas. A verificação de dependências é executada na inicialização, então reinicie o Claude Code após instalar pacotes para que `/sandbox` os detecte.138* **Dependencies é a única aba**: o sandbox não pode ser iniciado. Instale o que a aba lista como ausente ou, se ela relatar a restrição do AppArmor do Ubuntu, [adicione um perfil do AppArmor para o bubblewrap](#add-an-apparmor-profile-for-bubblewrap)

139* **Dependencies aparece junto com as outras abas**: a aba lista um item opcional ausente, como o filtro seccomp. O sandbox pode ser iniciado sem ele, então instale-o apenas se quiser o que ele adiciona

139 140 

140> [accordion] Ubuntu 24.04 e posteriores: permitir que o bubblewrap crie user namespaces141A verificação de dependências é executada na inicialização, então reinicie o Claude Code após instalar pacotes para que `/sandbox` os detecte.

141>

142> No Ubuntu 24.04 e posteriores, a política padrão do AppArmor impede que o bubblewrap crie os user namespaces de que precisa para o isolamento.

143>

144> Para verificar se o seu ambiente impõe essa restrição, inclusive dentro do WSL2, execute `sysctl kernel.apparmor_restrict_unprivileged_userns`. Se o comando retornar `0`, pule este passo. Se ele exibir um erro `No such file or directory`, a chave não existe e você pode pular este passo. Se retornar `1`, adicione um perfil do AppArmor que conceda essa capacidade ao `bwrap`:

145>

146> ```bash theme={null}

147> sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'

148> abi <abi/4.0>,

149> include <tunables/global>

150>

151> profile bwrap /usr/bin/bwrap flags=(unconfined) {

152> userns,

153> include if exists <local/bwrap>

154> }

155> EOF

156> ```

157>

158> O perfil se aplica apenas ao próprio `bwrap`, não aos comandos que ele executa dentro do sandbox. Recarregue o AppArmor para aplicá-lo:

159>

160> ```bash theme={null}

161> sudo systemctl reload apparmor

162> ```

163 142 

164> [accordion] Observações sobre o WSL2143> [accordion] Observações sobre o WSL2

165>144>


167>146>

168> No WSL2, o WSL repassa a inicialização de um binário do Windows, como `cmd.exe`, `powershell.exe` ou qualquer coisa em `/mnt/c/`, ao host Windows por meio de um socket Unix, então a possibilidade de um comando em sandbox iniciar um deles segue as [configurações de socket Unix](https://code.claude.com/docs/pt/settings-reference.md#sandbox-network-allowunixsockets) do sandbox: o filtro seccomp opcional precisa estar instalado para que o socket seja bloqueado. Para permitir essas inicializações, defina `allowAllUnixSockets`, que abre todos os sockets Unix para os comandos em sandbox.147> No WSL2, o WSL repassa a inicialização de um binário do Windows, como `cmd.exe`, `powershell.exe` ou qualquer coisa em `/mnt/c/`, ao host Windows por meio de um socket Unix, então a possibilidade de um comando em sandbox iniciar um deles segue as [configurações de socket Unix](https://code.claude.com/docs/pt/settings-reference.md#sandbox-network-allowunixsockets) do sandbox: o filtro seccomp opcional precisa estar instalado para que o socket seja bloqueado. Para permitir essas inicializações, defina `allowAllUnixSockets`, que abre todos os sockets Unix para os comandos em sandbox.

169 148 

149#### Adicionar um perfil do AppArmor para o bubblewrap

150 

151Adicione o perfil se o Claude Code executar `/usr/bin/bwrap` e uma destas situações ocorrer:

152 

153* O Claude Code [relata a restrição do AppArmor do Ubuntu sobre user namespaces](#apparmor-restriction-stops-bubblewrap)

154* Os comandos em sandbox falham com `bwrap: setting up uid map: Permission denied` ou `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` enquanto [essa restrição está ativada](#bwrap-uid-map-permission-denied)

155 

156O Claude Code executa o primeiro `bwrap` no `PATH`, a menos que as configurações gerenciadas indiquem um em [`sandbox.bwrapPath`](https://code.claude.com/docs/pt/settings-reference#sandbox-bwrappath). Para ver qual `bwrap` vem primeiro, execute `which bwrap` no shell a partir do qual você inicia o Claude Code. Se o Claude Code executar qualquer caminho diferente de `/usr/bin/bwrap`, [remova a restrição com `sysctl`](#apparmor-restriction-stops-bubblewrap) em vez disso.

157 

158Para adicionar o perfil para `/usr/bin/bwrap`, execute este comando:

159 

160```bash theme={null}

161sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'

162abi <abi/4.0>,

163include <tunables/global>

164 

165profile bwrap /usr/bin/bwrap flags=(unconfined) {

166 userns,

167 include if exists <local/bwrap>

168}

169EOF

170```

171 

172Recarregue o AppArmor para aplicá-lo:

173 

174```bash theme={null}

175sudo systemctl reload apparmor

176```

177 

178Em seguida, reinicie o Claude Code e [confirme que o sandbox funciona](#confirm-commands-run-inside-the-sandbox).

179 

170### Modos do sandbox180### Modos do sandbox

171 181 

172O Claude Code oferece dois modos de sandbox. Em ambos, o sandbox impõe as mesmas restrições de sistema de arquivos e de rede; a diferença está apenas em se os comandos em sandbox são aprovados automaticamente ou exigem permissão explícita.182O Claude Code oferece dois modos de sandbox. Em ambos, o sandbox impõe as mesmas restrições de sistema de arquivos e de rede; a diferença está apenas em se os comandos em sandbox são aprovados automaticamente ou exigem permissão explícita.


716 726 

717As duas chaves além de `enabled` controlam o que acontece quando o sandbox não consegue executar um comando:727As duas chaves além de `enabled` controlam o que acontece quando o sandbox não consegue executar um comando:

718 728 

719* **`failIfUnavailable`**: uma dependência faltante como bubblewrap no Linux impede o Claude Code de iniciar em vez de recorrer à execução sem sandbox729* **`failIfUnavailable`**: quando a plataforma não suporta o sandbox ou a verificação de dependências na inicialização falha, o Claude Code se recusa a iniciar em vez de recorrer à execução sem sandbox

720* **`allowUnsandboxedCommands: false`**: o Claude Code ignora o escape hatch `dangerouslyDisableSandbox`, portanto quando um comando falha sob o sandbox, Claude não consegue tentá-lo novamente sem sandbox730* **`allowUnsandboxedCommands: false`**: o Claude Code ignora o escape hatch `dangerouslyDisableSandbox`, portanto quando um comando falha sob o sandbox, Claude não consegue tentá-lo novamente sem sandbox

721 731 

722Considere estas adições junto com elas:732Considere estas adições junto com elas:


902 912 

903Em um container sem privilégios, [bubblewrap](#os-level-enforcement) não consegue montar um sistema de arquivos `/proc` fresco, então comandos em sandbox falham com um erro `bwrap` como `Can't mount proc on /newroot/proc: Operation not permitted`. Defina [`enableWeakerNestedSandbox`](https://code.claude.com/docs/pt/settings-reference#sandbox-enableweakernestedsandbox) como `true` para que o sandbox faça bind-mount do `/proc` existente do container em vez disso. Use esta configuração apenas quando o container externo já fornece o limite de isolamento que você precisa, pois a configuração expõe informações de processo a comandos em sandbox que uma montagem `/proc` fresca ocultaria.913Em um container sem privilégios, [bubblewrap](#os-level-enforcement) não consegue montar um sistema de arquivos `/proc` fresco, então comandos em sandbox falham com um erro `bwrap` como `Can't mount proc on /newroot/proc: Operation not permitted`. Defina [`enableWeakerNestedSandbox`](https://code.claude.com/docs/pt/settings-reference#sandbox-enableweakernestedsandbox) como `true` para que o sandbox faça bind-mount do `/proc` existente do container em vez disso. Use esta configuração apenas quando o container externo já fornece o limite de isolamento que você precisa, pois a configuração expõe informações de processo a comandos em sandbox que uma montagem `/proc` fresca ocultaria.

904 914 

915### A restrição do AppArmor do Ubuntu impede o bubblewrap

916 

917No Linux e WSL2, a mensagem `Ubuntu's AppArmor restriction on user namespaces stops bubblewrap here` significa que a restrição do AppArmor do Ubuntu impede que o sandbox inicie.

918 

919Para fazer o sandbox iniciar, remova a restrição de uma destas duas formas:

920 

921* [Adicione um perfil do AppArmor para o bubblewrap](#add-an-apparmor-profile-for-bubblewrap) se o Claude Code executar `/usr/bin/bwrap`

922* No seu shell, execute `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, o que remove a restrição para todos os programas na máquina e dura até você reiniciar

923 

924Em seguida, reinicie o Claude Code e [confirme que o sandbox funciona](#confirm-commands-run-inside-the-sandbox).

925 

926Até você remover a restrição, os comandos são executados sem o sandbox sob o fluxo de permissão regular, ou o Claude Code se recusa a iniciar se [`sandbox.failIfUnavailable`](https://code.claude.com/docs/pt/settings-reference#sandbox-failifunavailable) for `true`.

927 

928### Comandos em sandbox falham com `bwrap: setting up uid map: Permission denied`

929 

930No Linux e WSL2, este erro ou `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` pode significar que a restrição do AppArmor do Ubuntu sobre user namespaces está impedindo o bubblewrap. Para verificar, execute `sysctl kernel.apparmor_restrict_unprivileged_userns` no seu shell:

931 

932* `kernel.apparmor_restrict_unprivileged_userns = 1`: a restrição está ativada. [Adicione um perfil do AppArmor](#add-an-apparmor-profile-for-bubblewrap) se o Claude Code executar `/usr/bin/bwrap`, ou execute `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, o que a remove para todos os programas até você reiniciar. Em seguida, reinicie o Claude Code e [confirme que o sandbox funciona](#confirm-commands-run-inside-the-sandbox)

933* Qualquer outra saída: a restrição não é a causa. Para relatar a falha, execute [`/feedback`](https://code.claude.com/docs/pt/commands#all-commands) no prompt do Claude Code

934 

935Antes da v2.1.310, o Claude Code não verificava essa restrição na inicialização, então o `/sandbox` não a relatava.

936 

905### Arquivos somente leitura de 0 bytes aparecem em caminhos de configurações `.claude`, e "Sim, e não pergunte novamente" não salva937### Arquivos somente leitura de 0 bytes aparecem em caminhos de configurações `.claude`, e "Sim, e não pergunte novamente" não salva

906 938 

907No Linux e WSL2, o sandbox mantém uma negação de gravação em um arquivo que ainda não existe criando um espaço reservado somente leitura de 0 bytes lá enquanto um comando em sandbox é executado. O sandbox remove o espaço reservado depois.939No Linux e WSL2, o sandbox mantém uma negação de gravação em um arquivo que ainda não existe criando um espaço reservado somente leitura de 0 bytes lá enquanto um comando em sandbox é executado. O sandbox remove o espaço reservado depois.

Details

472 472 

473Para confirmar que o trap funciona, adicione uma linha diretamente abaixo da linha `trap` que chama um comando que não existe, como `no-such-command`. Execute o arquivo do hook a partir do seu shell e verifique se `echo $?` imprime `1`, depois remova a linha.473Para confirmar que o trap funciona, adicione uma linha diretamente abaixo da linha `trap` que chama um comando que não existe, como `no-such-command`. Execute o arquivo do hook a partir do seu shell e verifique se `echo $?` imprime `1`, depois remova a linha.

474 474 

475#### Descubra por que uma solicitação de spawn foi enviada

476 

477Seu hook recebe o motivo de cada solicitação de spawn em `CLAUDE_RUNNER_SPAWN_REASON`, para que você possa registrar em log por que o hook foi executado, junto com `CLAUDE_RUNNER_SESSION_UUID`. Requer Claude Code v2.1.318 ou posterior no orquestrador. Leia-o como `"${CLAUDE_RUNNER_SPAWN_REASON:-}"`, porque ele pode não estar definido, e inicie o runner qualquer que seja o valor. Se seu hook tomar caminhos diferentes com base nele, mantenha um caso padrão, porque a Anthropic pode adicionar valores.

478 

479Para descobrir o motivo de solicitações anteriores, pesquise no log de cada réplica do orquestrador por `session=` e pelo `CLAUDE_RUNNER_SESSION_UUID` da sessão, não pelo seu ID `session_...`. As linhas `ok session=` e `nack session=` mostram o valor de `CLAUDE_RUNNER_SPAWN_REASON` após `reason=`, ou `reason=-` se ele não estava definido:

480 

481* **`[runner:orchestrator] ok session=`**: o hook saiu com 0

482* **`[runner:orchestrator] nack session=`**: o orquestrador está relatando à Anthropic uma solicitação de spawn com falha

483 

484Cada valor informa apenas a última causa que a Anthropic registrou para a sessão, não o seu histórico:

485 

486| Valor | O que aconteceu | O que verificar |

487| :- | :- | :- |

488| `session_created` | Esta é a primeira solicitação de spawn para uma nova sessão | Nada. Não dependa dele para identificar a primeira solicitação de uma sessão, porque a primeira solicitação que seu hook vê pode carregar `runner_lost` depois que um runner de frota fixa ou em standby reteve a sessão. |

489| `no_runner_registered` | Nenhum runner se registrou para a solicitação anterior dentro de `--expected-spawn-seconds`, e a Anthropic não registrou nenhum relatório de falha para ela | `stop: no nack for session=` ou `nack failed session=` entre as linhas anteriores da sessão significa que nenhum relatório de falha foi registrado. Leia qualquer erro do hook antes disso e, se o orquestrador estava parando, consulte [Pare ou reinicie o orquestrador](#stop-or-restart-the-orchestrator). Após uma linha `ok session=`, verifique se seu runner foi iniciado e se registrou dentro de `--expected-spawn-seconds`. Se nenhuma réplica registrou a solicitação em log, verifique seus orquestradores quanto a reinicializações e linhas `poll failed`. |

490| `hook_failed` | Seu orquestrador relatou que a solicitação anterior falhou e pode ser tentada novamente, por exemplo porque seu hook saiu com 1 ou ainda estava em execução quando `--hook-timeout` terminou. O valor é o mesmo quando seu orquestrador devolve uma solicitação à Anthropic sem executar o hook, por exemplo enquanto o orquestrador está parando. | Encontre a última linha `[runner:orchestrator] nack session=` ou `stop: handing back session=` da sessão antes desta solicitação. O erro de spawn que o orquestrador enviou vem após o valor `reason=` e pode continuar nas linhas seguintes. Uma linha `handing back session=` significa que o orquestrador estava parando e não executou o hook, então não há nada a corrigir no hook. |

491| `runner_lost` | O runner que retinha a sessão parou de se comunicar com a Anthropic, cancelou o registro ou foi excluído | Descubra o que interrompeu o runner ou o desconectou da Anthropic, como uma remoção do nó, um encerramento por falta de memória, uma recuperação de instância spot ou seu próprio rollout ou redução de escala |

492| `runner_reported_failure` | O runner anterior relatou que a sessão falhou nele, por exemplo durante o checkout | Leia o log do runner anterior. Se muitas sessões recebem esse valor, verifique a imagem e a configuração do repositório. |

493| `resumed` | A sessão foi pausada e agora precisa de um runner novamente. Por exemplo, seu runner a liberou sob [`--release-idle-session-min`](#make-on-demand-runners-exit-when-idle) e, mais tarde, ela recebeu uma nova mensagem. | Nada |

494| `requeued` | A sessão foi colocada de volta na fila, por exemplo quando um Owner selecionou **Retry** ou uma sessão bloqueada recebeu uma nova mensagem | Se a mesma sessão continua recebendo esse valor, leia o erro nas suas linhas `nack session=`. Se o hook dela saiu com 0, leia o log do runner. |

495| `server_retry` | A Anthropic desistiu da solicitação anterior ou de iniciar a sessão no seu runner e está tentando novamente. Seu hook não falhou. | Nada, para uma única solicitação. Se o valor continuar aparecendo, em uma sessão ou em muitas, relate-o à [sua equipe de conta da Anthropic](https://code.claude.com/docs/pt/self-hosted-environments-deploy.md#report-an-issue). |

496| `prewarm` | Esta é uma solicitação de pré-aquecimento, ainda sem sessão | Nada |

497 

475### Pare ou reinicie o orquestrador498### Pare ou reinicie o orquestrador

476 499 

477Para parar ou reiniciar o orquestrador sem interromper hooks `spawn-runner` em execução, inicie-o com [`--shutdown-drain-sec`](https://code.claude.com/docs/pt/self-hosted-environments-reference#orchestrator-cli-flags). Ao receber `SIGTERM`, ele então concede aos hooks em execução até o número de segundos que você definir para terminarem. Para escolher o valor e configurar seu supervisor de processos de acordo, consulte [Dimensione `--shutdown-drain-sec` e o timeout de parada do orquestrador](#size-shutdown-drain-sec-and-the-supervisors-stop-timeout-for-the-orchestrator).500Para parar ou reiniciar o orquestrador sem interromper hooks `spawn-runner` em execução, inicie-o com [`--shutdown-drain-sec`](https://code.claude.com/docs/pt/self-hosted-environments-reference#orchestrator-cli-flags). Ao receber `SIGTERM`, ele então concede aos hooks em execução até o número de segundos que você definir para terminarem. Para escolher o valor e configurar seu supervisor de processos de acordo, consulte [Dimensione `--shutdown-drain-sec` e o timeout de parada do orquestrador](#size-shutdown-drain-sec-and-the-supervisors-stop-timeout-for-the-orchestrator).

Details

172 172 

173Um cliente conectado através de um [gateway de aplicativos Claude](#platform-availability) busca suas configurações do gateway e aguarda essa busca antes da sessão iniciar, portanto a busca nas listas abaixo não se aplica a ele. [Impor inicialização com falha fechada](#enforce-fail-closed-startup) cobre o que acontece quando essa busca falha.173Um cliente conectado através de um [gateway de aplicativos Claude](#platform-availability) busca suas configurações do gateway e aguarda essa busca antes da sessão iniciar, portanto a busca nas listas abaixo não se aplica a ele. [Impor inicialização com falha fechada](#enforce-fail-closed-startup) cobre o que acontece quando essa busca falha.

174 174 

175> [!NOTE]

176>

177> Em um login claude.ai de Team ou Enterprise armazenado na máquina, a Anthropic pode exigir as configurações da sua organização antes de uma sessão iniciar. Quando isso acontece, independentemente do que as listas abaixo dizem, um desenvolvedor [não pode iniciar uma sessão](https://code.claude.com/docs/pt/errors.md#couldnt-load-your-organizations-settings) em casos como estes:

178>

179> * O login dele expirou, até que ele execute `claude auth login`

180> * O Claude Code não tem as configurações nem uma cópia recente em cache. Verifique se a máquina consegue alcançar `api.anthropic.com`

181>

182> Uma mensagem de inicialização com `before a session can start` ou `Your Claude session has expired` significa que o requisito se aplica.

183 

175**Primeiro lançamento sem configurações em cache:**184**Primeiro lançamento sem configurações em cache:**

176 185 

177* Quando um desenvolvedor se conecta na inicialização, como em uma primeira execução ou após `/logout`, o Claude Code aguarda até cinco segundos pela busca antes de abrir a sessão. Quando a política chega a tempo, o Claude Code a aplica desde a primeira tela e mostra seus [`companyAnnouncements`](https://code.claude.com/docs/pt/settings-reference#companyannouncements) nela. Quando o payload precisa de [aprovação de segurança](#security-approval-dialogs), o Claude Code encerra a espera e aplica o payload uma vez que o desenvolvedor aprova186* Quando um desenvolvedor se conecta na inicialização, como em uma primeira execução ou após `/logout`, o Claude Code aguarda até cinco segundos pela busca antes de abrir a sessão. Quando a política chega a tempo, o Claude Code a aplica desde a primeira tela e mostra seus [`companyAnnouncements`](https://code.claude.com/docs/pt/settings-reference#companyannouncements) nela. Quando o payload precisa de [aprovação de segurança](#security-approval-dialogs), o Claude Code encerra a espera e aplica o payload uma vez que o desenvolvedor aprova

178* Em qualquer outra inicialização, e quando essa espera de cinco segundos se esgota, o Claude Code abre a sessão enquanto a busca continua, portanto uma breve janela passa antes das configurações carregarem e as restrições entrarem em vigor187* Em qualquer outra inicialização, e quando essa espera de cinco segundos se esgota, o Claude Code abre a sessão enquanto a busca continua, portanto uma breve janela passa antes das configurações carregarem e as restrições entrarem em vigor

179* Se a busca falhar, o Claude Code continua sem configurações gerenciadas pelo servidor e avisa em sessões interativas que nenhuma política remota se aplica; as configurações gerenciadas pelo endpoint ainda se aplicam. Se uma fonte gerenciada define [`forceRemoteSettingsRefresh`](#enforce-fail-closed-startup), o Claude Code sai em vez disso188* Se a busca falhar, o Claude Code continua sem configurações gerenciadas pelo servidor e avisa em sessões interativas e na [aba Code do Claude Desktop](https://code.claude.com/docs/pt/desktop.md) que nenhuma política remota se aplica; as configurações gerenciadas pelo endpoint ainda se aplicam. Se uma fonte gerenciada define [`forceRemoteSettingsRefresh`](#enforce-fail-closed-startup), o Claude Code sai em vez disso

180 189 

181**Lançamentos subsequentes com configurações em cache:**190**Lançamentos subsequentes com configurações em cache:**

182 191 


186* Um valor em cache de [`prependPlugins`](https://code.claude.com/docs/pt/settings-reference#prependplugins), [`appendPlugins`](https://code.claude.com/docs/pt/settings-reference#appendplugins) ou [`enabledPlugins`](https://code.claude.com/docs/pt/settings-reference#enabledplugins) não pode remover a guarda integrada, alterar sua posição ou desativá-la até que a busca da sessão confirme o payload195* Um valor em cache de [`prependPlugins`](https://code.claude.com/docs/pt/settings-reference#prependplugins), [`appendPlugins`](https://code.claude.com/docs/pt/settings-reference#appendplugins) ou [`enabledPlugins`](https://code.claude.com/docs/pt/settings-reference#enabledplugins) não pode remover a guarda integrada, alterar sua posição ou desativá-la até que a busca da sessão confirme o payload

187* Em uma máquina onde uma [fonte gerenciada pelo endpoint](https://code.claude.com/docs/pt/managed-settings.md#choose-a-delivery-mechanism) lista ou ativa plugins próprios, um plugin que apenas uma lista em cache ativa conta como [do usuário](https://code.claude.com/docs/pt/plugins/mods/admin.md#install-your-organizations-mods), e não da sua organização, até que a busca confirme o payload196* Em uma máquina onde uma [fonte gerenciada pelo endpoint](https://code.claude.com/docs/pt/managed-settings.md#choose-a-delivery-mechanism) lista ou ativa plugins próprios, um plugin que apenas uma lista em cache ativa conta como [do usuário](https://code.claude.com/docs/pt/plugins/mods/admin.md#install-your-organizations-mods), e não da sua organização, até que a busca confirme o payload

188* O Claude Code busca configurações atualizadas em segundo plano197* O Claude Code busca configurações atualizadas em segundo plano

189* As configurações em cache persistem através de falhas de rede. Se a busca de inicialização falhar, o Claude Code avisa em sessões interativas que a política em cache está em vigor198* As configurações em cache persistem através de falhas de rede. Se a busca de inicialização falhar, o Claude Code avisa em sessões interativas e na aba Code que a política em cache está em vigor

190* Até que uma busca seja bem-sucedida, os valores retidos na inicialização permanecem retidos199* Até que uma busca seja bem-sucedida, os valores retidos na inicialização permanecem retidos

191 200 

192O Claude Code retém várias categorias de variáveis no bloco `env` em cache até que o servidor confirme o payload para a sessão. Isso evita que um proxy em cache, autoridade de certificação, endpoint ou valor de credencial redirecione, intercepte ou reautentique a busca de configurações que confirma o payload. O endurecimento se aplica apenas ao cache de configurações buscado do servidor: [configurações gerenciadas pelo endpoint](https://code.claude.com/docs/pt/managed-settings.md#delivery-mechanisms) implantadas através de MDM ou `managed-settings.json` não são afetadas. As categorias retidas incluem:201O Claude Code retém várias categorias de variáveis no bloco `env` em cache até que o servidor confirme o payload para a sessão. Isso evita que um proxy em cache, autoridade de certificação, endpoint ou valor de credencial redirecione, intercepte ou reautentique a busca de configurações que confirma o payload. O endurecimento se aplica apenas ao cache de configurações buscado do servidor: [configurações gerenciadas pelo endpoint](https://code.claude.com/docs/pt/managed-settings.md#delivery-mechanisms) implantadas através de MDM ou `managed-settings.json` não são afetadas. As categorias retidas incluem:


221 * Nenhuma delas volta a um valor mais rigoroso.230 * Nenhuma delas volta a um valor mais rigoroso.

222 * O payload contém uma chave diferente daquelas duas chaves de retenção.231 * O payload contém uma chave diferente daquelas duas chaves de retenção.

223 232 

224 O aviso de inicialização, `/status` e `claude doctor` então relatam a [falha de carregamento](https://code.claude.com/docs/pt/errors.md#remote-managed-settings-failed-to-load) com a causa `no setting in the server response could be applied as written`, e essa entrada diz qual política a sessão é executada. Clientes que [impõem inicialização com falha fechada](#enforce-fail-closed-startup) saem na inicialização em vez disso.233 O aviso de inicialização, `/status` e `claude doctor` então relatam a [falha de carregamento](https://code.claude.com/docs/pt/errors.md#remote-managed-settings-failed-to-load) com a causa `no setting in the server response could be applied as written`, e essa entrada diz qual política a sessão é executada. Clientes que [impõem inicialização com falha fechada](#enforce-fail-closed-startup) saem na inicialização em vez disso. Se a inicialização parar com uma mensagem de que sua organização exige suas configurações `before a session can start`, veja [O Claude Code não conseguiu carregar as configurações da sua organização](https://code.claude.com/docs/pt/errors.md#couldnt-load-your-organizations-settings).

225* 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.234* 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.

226 235 

227Para 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.236Para 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.

228 237 

229### Impor inicialização com falha fechada238### Impor inicialização com falha fechada

230 239 

231Por padrão, se a busca de configurações remotas falhar na inicialização, a CLI continua com as configurações em cache da última busca bem-sucedida, exceto pelos [valores que o Claude Code retém](#fetch-and-caching-behavior) até que uma busca seja bem-sucedida. Em uma máquina que nunca as buscou, a CLI continua sem configurações gerenciadas pelo servidor e ainda aplica qualquer [configuração gerenciada pelo endpoint](https://code.claude.com/docs/pt/managed-settings.md#delivery-mechanisms) no dispositivo.240Por padrão, se a busca de configurações remotas falhar na inicialização, a CLI continua com as configurações em cache da última busca bem-sucedida. Os [valores que o Claude Code retém](#fetch-and-caching-behavior) permanecem retidos até que uma busca seja bem-sucedida. Em uma máquina que nunca as buscou, a CLI continua sem configurações gerenciadas pelo servidor e ainda aplica qualquer [configuração gerenciada pelo endpoint](https://code.claude.com/docs/pt/managed-settings.md#delivery-mechanisms) no dispositivo. Em vez disso, [a Anthropic pode exigir as configurações](#fetch-and-caching-behavior).

232 241 

233Para impedir que clientes iniciem em configurações gerenciadas pelo servidor em cache ou ausentes, defina `forceRemoteSettingsRefresh: true` em suas configurações gerenciadas.242Para impedir que clientes iniciem em configurações gerenciadas pelo servidor em cache ou ausentes, defina `forceRemoteSettingsRefresh: true` em suas configurações gerenciadas.

234 243 


370| Usuário deleta o arquivo de configurações em cache | [Comportamento de primeiro lançamento](#fetch-and-caching-behavior) ocorre |379| Usuário deleta o arquivo de configurações em cache | [Comportamento de primeiro lançamento](#fetch-and-caching-behavior) ocorre |

371| Usuário executa um binário Claude Code modificado | Um usuário que pode executar um cliente modificado pode contornar qualquer controle do lado do cliente |380| Usuário executa um binário Claude Code modificado | Um usuário que pode executar um cliente modificado pode contornar qualquer controle do lado do cliente |

372| Usuário executa uma versão anterior do Claude Code | Versões que antecedem as configurações gerenciadas pelo servidor não as buscam ou aplicam |381| Usuário executa uma versão anterior do Claude Code | Versões que antecedem as configurações gerenciadas pelo servidor não as buscam ou aplicam |

373| API está indisponível | As configurações em cache se aplicam se disponíveis, exceto pelos [valores que Claude Code retém](#fetch-and-caching-behavior) até que uma busca seja bem-sucedida. Sem um cache, Claude Code não aplica nenhuma configuração gerenciada pelo servidor até a próxima busca bem-sucedida e ainda aplica qualquer [configuração gerenciada pelo endpoint](https://code.claude.com/docs/pt/managed-settings.md#delivery-mechanisms) no dispositivo. Com `forceRemoteSettingsRefresh: true`, a CLI sai em vez de continuar, exceto para [subcomandos `claude auth`](#enforce-fail-closed-startup). Clientes conectados através de um [gateway de aplicativos Claude](#platform-availability) saem na inicialização sem essa configuração, com a mesma exceção `claude auth` |382| API está indisponível | As configurações em cache se aplicam se disponíveis. Sem um cache, Claude Code não aplica nenhuma configuração gerenciada pelo servidor até a próxima busca bem-sucedida. [Comportamento de busca e cache](#fetch-and-caching-behavior) lista as exceções, incluindo quando a Anthropic exige as configurações. Com `forceRemoteSettingsRefresh: true`, a CLI sai em vez de continuar, exceto para [subcomandos `claude auth`](#enforce-fail-closed-startup). Clientes conectados através de um [gateway de aplicativos Claude](#platform-availability) saem na inicialização sem essa configuração, com a mesma exceção `claude auth` |

374| Usuário se autentica com uma organização diferente | As configurações não são entregues para contas fora da organização gerenciada, incluindo uma sessão que se autentica com uma [chave de API do Console](#platform-availability) |383| Usuário se autentica com uma organização diferente | As configurações não são entregues para contas fora da organização gerenciada, incluindo uma sessão que se autentica com uma [chave de API do Console](#platform-availability) |

375| Usuário configura um [provedor de modelo de terceiros](#platform-availability) | As configurações gerenciadas pelo servidor são ignoradas. Isso inclui definir `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`, ou um `ANTHROPIC_BASE_URL` não padrão |384| Usuário configura um [provedor de modelo de terceiros](#platform-availability) | As configurações gerenciadas pelo servidor são ignoradas. Isso inclui definir `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_MANTLE`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_ANTHROPIC_AWS`, ou um `ANTHROPIC_BASE_URL` não padrão |

376| Tráfego de rede é interceptado ou redirecionado | Validação TLS desabilitada ou tráfego interceptado pode alterar as configurações que o cliente recebe |385| Tráfego de rede é interceptado ou redirecionado | Validação TLS desabilitada ou tráfego interceptado pode alterar as configurações que o cliente recebe |

settings.md +2 −2

Details

199* **Erro de Configurações**: um arquivo de usuário, projeto ou local tem JSON inválido ou um valor que o esquema rejeita. No início de uma sessão interativa, o Claude Code mostra um diálogo que permite você corrigir o arquivo com a ajuda do Claude, sair ou continuar sem as configurações quebradas.199* **Erro de Configurações**: um arquivo de usuário, projeto ou local tem JSON inválido ou um valor que o esquema rejeita. No início de uma sessão interativa, o Claude Code mostra um diálogo que permite você corrigir o arquivo com a ajuda do Claude, sair ou continuar sem as configurações quebradas.

200* **Aviso de Configurações**: apenas entradas individuais falham, como uma regra de permissão malformada ou um nome de evento de hook desconhecido. O Claude Code pula esses valores e mantém o resto do arquivo em vigor.200* **Aviso de Configurações**: apenas entradas individuais falham, como uma regra de permissão malformada ou um nome de evento de hook desconhecido. O Claude Code pula esses valores e mantém o resto do arquivo em vigor.

201* **Configurações gerenciadas**: o Claude Code continua impondo o resto do arquivo. [Entradas inválidas em configurações gerenciadas](https://code.claude.com/docs/pt/managed-settings.md#invalid-entries-in-managed-settings) diz o que ele descarta e quais chaves voltam para um valor mais rigoroso até você corrigi-las. Para um documento de configurações gerenciadas que não é JSON válido, veja [Documento de configurações gerenciadas não pôde ser analisado](https://code.claude.com/docs/pt/errors.md#managed-settings-document-could-not-be-parsed).201* **Configurações gerenciadas**: o Claude Code continua impondo o resto do arquivo. [Entradas inválidas em configurações gerenciadas](https://code.claude.com/docs/pt/managed-settings.md#invalid-entries-in-managed-settings) diz o que ele descarta e quais chaves voltam para um valor mais rigoroso até você corrigi-las. Para um documento de configurações gerenciadas que não é JSON válido, veja [Documento de configurações gerenciadas não pôde ser analisado](https://code.claude.com/docs/pt/errors.md#managed-settings-document-could-not-be-parsed).

202* **Erro de configuração**: `~/.claude.json` não pode ser analisado. O Claude Code copia o arquivo quebrado para `~/.claude/backups/.claude.json.corrupted.<timestamp>` e pergunta se você quer sair e corrigi-lo manualmente ou redefinir para a configuração padrão; uma execução `-p` imprime o erro e sai. Para recuperar seu estado anterior, copie de volta um dos cinco arquivos `.claude.json.backup.<timestamp>` mais recentes em `~/.claude/backups/`, que o Claude Code salva antes de escrever o arquivo.202* **Erro de configuração**: [`~/.claude.json`](https://code.claude.com/docs/pt/claude-directory#ce-claude-json) não pode ser analisado. Uma execução `claude -p` é encerrada, e seu arquivo permanece inalterado. Veja [Erro de configuração em \~/.claude.json](https://code.claude.com/docs/pt/errors.md#configuration-error-in-claude-json) para restaurar uma cópia anterior. O Claude Code copia o arquivo quebrado para `~/.claude/backups/.claude.json.corrupted.<timestamp>` e, em uma sessão interativa, pergunta se você quer sair e corrigi-lo ou redefinir para a configuração padrão. Quando o arquivo está em branco e não há backup para restaurar, o Claude Code inicia com as configurações padrão.

203 203 

204Depois que você continuar, execute `/status` para ver os arquivos afetados e `claude doctor` para os detalhes de cada erro.204Depois que você continuar, execute `/status` para ver os arquivos afetados e `claude doctor` para os detalhes de cada erro.

205 205 

206Uma execução `-p` não mostra diálogo. A menos que [um documento de configurações gerenciadas não possa ser analisado](https://code.claude.com/docs/pt/errors.md#managed-settings-document-could-not-be-parsed), o Claude Code pula o arquivo ou valores quebrados e continua com o resto, então após uma execução `-p` que ignora uma configuração, execute `claude doctor` para ver o que ele descartou.206Uma execução `-p` não mostra diálogo. A menos que [um documento de configurações gerenciadas não possa ser analisado](https://code.claude.com/docs/pt/errors.md#managed-settings-document-could-not-be-parsed), o Claude Code pula um arquivo de usuário, projeto ou local quebrado ou seus valores quebrados e continua com o resto. Após uma execução `-p` que ignora uma configuração, execute `claude doctor` no seu terminal para ver o que ele descartou.

207 207 

208## Precedência das configurações208## Precedência das configurações

209 209 

Details

40| [`autoCompactWindow`](#autocompactwindow) | Defina o quão cheio o contexto fica antes de Claude Code [compactar](https://code.claude.com/docs/pt/context-window.md) | Memória e contexto | Any file |40| [`autoCompactWindow`](#autocompactwindow) | Defina o quão cheio o contexto fica antes de Claude Code [compactar](https://code.claude.com/docs/pt/context-window.md) | Memória e contexto | Any file |

41| [`autoConnectIde`](#autoconnectide) | Conecte-se automaticamente a um [VS Code](https://code.claude.com/docs/pt/vs-code.md) ou [JetBrains](https://code.claude.com/docs/pt/jetbrains.md#from-external-terminals) IDE em execução a partir de um terminal externo | Configurações de config global | Global config |41| [`autoConnectIde`](#autoconnectide) | Conecte-se automaticamente a um [VS Code](https://code.claude.com/docs/pt/vs-code.md) ou [JetBrains](https://code.claude.com/docs/pt/jetbrains.md#from-external-terminals) IDE em execução a partir de um terminal externo | Configurações de config global | Global config |

42| [`autoContinueAtUsageLimit`](#autocontinueatusagelimit) | Aguarde na sessão aberta e [continue a tarefa automaticamente](https://code.claude.com/docs/pt/interactive-mode.md#wait-for-a-usage-limit-to-reset) após um limite de uso claude.ai ser redefinido | Interface e terminal | User or managed |42| [`autoContinueAtUsageLimit`](#autocontinueatusagelimit) | Aguarde na sessão aberta e [continue a tarefa automaticamente](https://code.claude.com/docs/pt/interactive-mode.md#wait-for-a-usage-limit-to-reset) após um limite de uso claude.ai ser redefinido | Interface e terminal | User or managed |

43| [`autoInstallIdeExtension`](#autoinstallideextension) | Desative a instalação automática da [extensão IDE](https://code.claude.com/docs/pt/vs-code.md#install-the-extension) a partir de um terminal VS Code | Configurações de config global | Global config |43| [`autoInstallIdeExtension`](#autoinstallideextension) | Permita que `/ide` instale a [extensão IDE](https://code.claude.com/docs/pt/vs-code.md#install-the-extension) a partir de um terminal externo | Configurações de config global | Global config |

44| [`autoMemoryDirectory`](#automemorydirectory) | Armazene a [memória automática](https://code.claude.com/docs/pt/memory.md#auto-memory) em um diretório de sua escolha | Memória e contexto | Any file |44| [`autoMemoryDirectory`](#automemorydirectory) | Armazene a [memória automática](https://code.claude.com/docs/pt/memory.md#auto-memory) em um diretório de sua escolha | Memória e contexto | Any file |

45| [`autoMemoryEnabled`](#automemoryenabled) | Desative ou ative a [memória automática](https://code.claude.com/docs/pt/memory.md#auto-memory) | Memória e contexto | Any file |45| [`autoMemoryEnabled`](#automemoryenabled) | Desative ou ative a [memória automática](https://code.claude.com/docs/pt/memory.md#auto-memory) | Memória e contexto | Any file |

46| [`autoMode`](#automode) | Adicione suas próprias regras de permissão e negação ao classificador de [modo automático](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) | Configurações de permissão | User or managed |46| [`autoMode`](#automode) | Adicione suas próprias regras de permissão e negação ao classificador de [modo automático](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode) | Configurações de permissão | User or managed |


139| [`outputStyle`](#outputstyle) | Altere o papel, tom e formato de saída de Claude com um [estilo de saída](https://code.claude.com/docs/pt/output-styles.md) | Modelo e respostas | Any file |139| [`outputStyle`](#outputstyle) | Altere o papel, tom e formato de saída de Claude com um [estilo de saída](https://code.claude.com/docs/pt/output-styles.md) | Modelo e respostas | Any file |

140| [`parentSettingsBehavior`](#parentsettingsbehavior) | Aplique ou descarte restrições que um [host SDK ou IDE](https://code.claude.com/docs/pt/managed-settings.md#let-an-embedding-host-add-policy) passa quando você implanta [configurações gerenciadas](https://code.claude.com/docs/pt/managed-settings.md) | Configurações empresariais e gerenciadas | Managed |140| [`parentSettingsBehavior`](#parentsettingsbehavior) | Aplique ou descarte restrições que um [host SDK ou IDE](https://code.claude.com/docs/pt/managed-settings.md#let-an-embedding-host-add-policy) passa quando você implanta [configurações gerenciadas](https://code.claude.com/docs/pt/managed-settings.md) | Configurações empresariais e gerenciadas | Managed |

141| [`permissionExplainerEnabled`](#permissionexplainerenabled) | Removido na v2.1.257, junto com a explicação do comando `Ctrl+E` nos prompts de permissão de shell | Configurações de config global | Global config |141| [`permissionExplainerEnabled`](#permissionexplainerenabled) | Removido na v2.1.257, junto com a explicação do comando `Ctrl+E` nos prompts de permissão de shell | Configurações de config global | Global config |

142| [`permissions`](#permissions) | Defina regras de permissão, pergunta e negação e o [modo de permissão](https://code.claude.com/docs/pt/permission-modes.md) inicial | Configurações de permissão | Any file |142| [`permissions`](#permissions) | Defina regras de permissão, pergunta e negação e o [modo de permissão](https://code.claude.com/docs/pt/permission-modes.md) padrão | Configurações de permissão | Any file |

143| [`permissions.additionalDirectories`](#permissions-additionaldirectories) | Dê a Claude acesso a arquivos em [diretórios fora do atual](https://code.claude.com/docs/pt/permissions.md#working-directories) | Configurações de permissão | Any file |143| [`permissions.additionalDirectories`](#permissions-additionaldirectories) | Dê a Claude acesso a arquivos em [diretórios fora do atual](https://code.claude.com/docs/pt/permissions.md#working-directories) | Configurações de permissão | Any file |

144| [`permissions.allow`](#permissions-allow) | Aprove [usos de ferramentas](https://code.claude.com/docs/pt/permissions.md#permission-rule-syntax) listados sem um prompt | Configurações de permissão | Any file |144| [`permissions.allow`](#permissions-allow) | Aprove [usos de ferramentas](https://code.claude.com/docs/pt/permissions.md#permission-rule-syntax) listados sem um prompt | Configurações de permissão | Any file |

145| [`permissions.ask`](#permissions-ask) | Sempre solicite antes de [usos de ferramentas](https://code.claude.com/docs/pt/permissions.md#permission-rule-syntax) listados | Configurações de permissão | Any file |145| [`permissions.ask`](#permissions-ask) | Sempre solicite antes de [usos de ferramentas](https://code.claude.com/docs/pt/permissions.md#permission-rule-syntax) listados | Configurações de permissão | Any file |

146| [`permissions.blockReadsOutsideWorkingDirectories`](#permissions-blockreadsoutsideworkingdirectories) | Faça as ferramentas de arquivo recusarem leituras fora dos [diretórios de trabalho](https://code.claude.com/docs/pt/permissions.md#working-directories) em cada modo de permissão | Configurações de permissão | Any file |146| [`permissions.blockReadsOutsideWorkingDirectories`](#permissions-blockreadsoutsideworkingdirectories) | Faça as ferramentas de arquivo recusarem leituras fora dos [diretórios de trabalho](https://code.claude.com/docs/pt/permissions.md#working-directories) em cada modo de permissão | Configurações de permissão | Any file |

147| [`permissions.blockWritesOutsideWorkingDirectories`](#permissions-blockwritesoutsideworkingdirectories) | Faça as ferramentas `Write`, `Edit` e `NotebookEdit` recusarem caminhos fora dos [diretórios de trabalho](https://code.claude.com/docs/pt/permissions.md#working-directories) em cada modo de permissão, exceto [alguns dos próprios arquivos de Claude Code](#what-the-write-block-refuses-and-what-stays-writable) | Configurações de permissão | Any file |147| [`permissions.blockWritesOutsideWorkingDirectories`](#permissions-blockwritesoutsideworkingdirectories) | Faça as ferramentas `Write`, `Edit` e `NotebookEdit` recusarem caminhos fora dos [diretórios de trabalho](https://code.claude.com/docs/pt/permissions.md#working-directories) em cada modo de permissão, exceto [alguns dos próprios arquivos de Claude Code](#what-the-write-block-refuses-and-what-stays-writable) | Configurações de permissão | Any file |

148| [`permissions.defaultMode`](#permissions-defaultmode) | Defina o [modo de permissão](https://code.claude.com/docs/pt/permission-modes.md#which-mode-a-session-starts-in) em que novas sessões começam | Configurações de permissão | Any file |148| [`permissions.defaultMode`](#permissions-defaultmode) | Defina o [modo de permissão](https://code.claude.com/docs/pt/permission-modes.md#which-mode-a-session-starts-in) padrão para novas sessões | Configurações de permissão | Any file |

149| [`permissions.deny`](#permissions-deny) | Bloqueie [usos de ferramentas](https://code.claude.com/docs/pt/permissions.md#permission-rule-syntax) listados, incluindo leituras de arquivos que contêm segredos | Configurações de permissão | Any file |149| [`permissions.deny`](#permissions-deny) | Bloqueie [usos de ferramentas](https://code.claude.com/docs/pt/permissions.md#permission-rule-syntax) listados, incluindo leituras de arquivos que contêm segredos | Configurações de permissão | Any file |

150| [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) | Impeça qualquer pessoa de entrar no [modo bypassPermissions](https://code.claude.com/docs/pt/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) | Configurações de permissão | Any file |150| [`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) | Impeça qualquer pessoa de entrar no [modo bypassPermissions](https://code.claude.com/docs/pt/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) | Configurações de permissão | Any file |

151| [`plansDirectory`](#plansdirectory) | Escolha onde o [modo de planejamento](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode) escreve arquivos de plano | Memória e contexto | Any file |151| [`plansDirectory`](#plansdirectory) | Escolha onde o [modo de planejamento](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode) escreve arquivos de plano | Memória e contexto | Any file |


804 804 

805## Configurações de permissão805## Configurações de permissão

806 806 

807Decida o que Claude pode fazer sem perguntar, em qual modo de permissão uma sessão começa e o que o classificador do modo automático permite. Para a sintaxe de regras e o modelo de permissão, consulte [Configurar permissões](https://code.claude.com/docs/pt/permissions.md).807Decida o que Claude pode fazer sem perguntar, o modo de permissão padrão para novas sessões e o que o classificador do modo automático permite. Para a sintaxe de regras e o modelo de permissão, consulte [Configurar permissões](https://code.claude.com/docs/pt/permissions.md).

808 808 

809### `allowManagedPermissionRulesOnly`809### `allowManagedPermissionRulesOnly`

810 810 


899 899 

900### `permissions`900### `permissions`

901 901 

902Controle quais ferramentas Claude pode usar sem perguntar, quais sempre solicitam e quais são bloqueadas, e defina o [modo de permissão](https://code.claude.com/docs/pt/permission-modes.md) em que uma sessão começa. Cada chave `permissions.*` abaixo se aninha sob este objeto.902Controle quais ferramentas Claude pode usar sem perguntar, quais solicitam confirmação e quais são bloqueadas. Também defina o [modo de permissão](https://code.claude.com/docs/pt/permission-modes.md) padrão para novas sessões. Cada chave `permissions.*` abaixo se aninha sob este objeto.

903 903 

904* **Escopo**: [`Any file`](#scopes)904* **Escopo**: [`Any file`](#scopes)

905* **Tipo**: objeto com `allow`, `ask`, `deny`, `additionalDirectories`, `blockReadsOutsideWorkingDirectories`, `blockWritesOutsideWorkingDirectories`, `defaultMode`, `disableBypassPermissionsMode` e `disableAutoMode`905* **Tipo**: objeto com `allow`, `ask`, `deny`, `additionalDirectories`, `blockReadsOutsideWorkingDirectories`, `blockWritesOutsideWorkingDirectories`, `defaultMode`, `disableBypassPermissionsMode` e `disableAutoMode`


1137 1137 

1138### `permissions.defaultMode`1138### `permissions.defaultMode`

1139 1139 

1140Defina o [modo de permissão](https://code.claude.com/docs/pt/permission-modes.md) em que novas sessões começam. Quando você deixa não definido, as sessões começam no [padrão integrado](https://code.claude.com/docs/pt/permission-modes.md#which-mode-a-session-starts-in) para sua superfície.1140Defina o [modo de permissão](https://code.claude.com/docs/pt/permission-modes.md) padrão para novas sessões. Quando você o deixa não definido, aplica-se o [padrão integrado](https://code.claude.com/docs/pt/permission-modes.md#which-mode-a-session-starts-in) para sua superfície.

1141 1141 

1142* **Escopo**: [`Any file`](#scopes). `auto` e `bypassPermissions` não entram em vigor a partir de configurações de projeto ou local, portanto defina-os em `~/.claude/settings.json` em vez disso. Antes da v2.1.257, `bypassPermissions` entrava em vigor a partir de qualquer arquivo. Para conversas que a extensão VS Code inicia, Claude Code lê apenas valores de usuário, gerenciados e `--settings`.1142* **Escopo**: [`Any file`](#scopes). `auto` e `bypassPermissions` não entram em vigor a partir de configurações de projeto ou local, portanto defina-os em `~/.claude/settings.json` em vez disso. Antes da v2.1.257, `bypassPermissions` entrava em vigor a partir de qualquer arquivo. Para conversas que a extensão VS Code inicia, Claude Code lê apenas valores de usuário, gerenciados e `--settings`.

1143* **Tipo**: string, uma de:1143* **Tipo**: string, uma de:


1267 1267 

1268### `sandbox.failIfUnavailable`1268### `sandbox.failIfUnavailable`

1269 1269 

1270Faça Claude Code sair com um erro na inicialização quando `sandbox.enabled` é `true` mas o sandbox não consegue iniciar, porque uma dependência está faltando ou a plataforma não é suportada. Sem essa chave, Claude Code executa comandos sem sandbox. Implantações gerenciadas que exigem sandboxing como uma barreira de segurança podem usar essa configuração.1270Faz o Claude Code encerrar com um erro na inicialização quando `sandbox.enabled` é `true`, mas o sandbox não consegue iniciar porque a plataforma não oferece suporte a ele ou a verificação de dependências falha. Sem esta chave, o Claude Code executa os comandos fora do sandbox. Implantações gerenciadas que exigem sandboxing como barreira de segurança podem usar esta configuração.

1271 1271 

1272Em uma plataforma que o sandbox não suporta, Claude Code não inicia com essa chave ativada. Consulte [Enforce sandboxing with managed settings](https://code.claude.com/docs/pt/sandboxing.md#enforce-sandboxing-with-managed-settings).1272Em uma plataforma que o sandbox não suporta, Claude Code não inicia com essa chave ativada. Consulte [Enforce sandboxing with managed settings](https://code.claude.com/docs/pt/sandboxing.md#enforce-sandboxing-with-managed-settings).

1273 1273 


5087 5087 

5088### `sshHostCommands`5088### `sshHostCommands`

5089 5089 

5090Adicione ao seletor de ambiente do [Desktop](https://code.claude.com/docs/pt/desktop.md#create-an-ssh-connection-from-a-command) conexões SSH cujo host vem de um comando. Quando você cria uma conexão ou substitui seu host, o Desktop executa o comando da entrada em seu computador e se conecta ao host que o comando imprime. Requer Claude Desktop v3.6556.0 ou posterior no macOS ou Linux, com login feito com uma conta Claude.5090Adicione ao seletor de ambiente do [Desktop](https://code.claude.com/docs/pt/desktop.md#create-an-ssh-connection-from-a-command) conexões SSH cujo host vem de um comando. Quando você cria uma conexão ou cria outra máquina para ela, o Desktop executa o comando da entrada em seu computador e se conecta ao host que o comando imprime.

5091 

5092Requer Claude Desktop v3.6556.0 ou posterior no macOS ou Linux, ou v4.16336.0 ou posterior no Windows, com login feito com uma conta Claude. No Windows, o Desktop também precisa [se conectar pelo cliente OpenSSH](https://code.claude.com/docs/pt/desktop.md#use-your-ssh-configuration).

5091 5093 

5092* **Escopo**: [`Usuário ou gerenciado`](#scopes). Apenas o aplicativo desktop lê essa chave. Ele lê entradas gerenciadas de [um arquivo de configurações gerenciadas ou política de MDM](https://code.claude.com/docs/pt/desktop.md#distribute-commands-to-your-team) no computador, e ignora a chave nas [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md).5094* **Escopo**: [`Usuário ou gerenciado`](#scopes). Apenas o aplicativo desktop lê essa chave. Ele lê entradas gerenciadas de [um arquivo de configurações gerenciadas ou política de MDM](https://code.claude.com/docs/pt/desktop.md#distribute-commands-to-your-team) no computador, e ignora a chave nas [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md).

5093* **Tipo**: array de objetos, cada um com `id`, `name` e `command` obrigatórios e `sshIdentityFile` e `startDirectory` opcionais. O Desktop inicia `command` sem um shell, então [escreva-o como um programa e argumentos simples](https://code.claude.com/docs/pt/desktop.md#write-the-command).5095* **Tipo**: array de objetos, cada um com `id`, `name` e `command` obrigatórios e `sshIdentityFile` e `startDirectory` opcionais. O Desktop não lê `command` como sintaxe de shell, então pipes e variáveis não funcionam: [escreva-o como um programa e seus argumentos](https://code.claude.com/docs/pt/desktop.md#write-the-command).

5094* **Padrão**: não definido5096* **Padrão**: não definido

5095 5097 

5096Este exemplo adiciona uma conexão chamada `Dev box`, onde `acme-dev create` representa sua própria ferramenta:5098Este exemplo adiciona uma conexão chamada `Dev box`, onde `acme-dev create` representa sua própria ferramenta:


5107}5109}

5108```5110```

5109 5111 

5112No Windows, um nome simples como `acme-dev` não funciona, então [inicie o comando com o caminho completo do programa](https://code.claude.com/docs/pt/desktop.md#write-the-command-on-windows).

5113 

5110Antes do Claude Code v2.1.307, a ferramenta Edit recusava uma alteração que adicionava essa chave a um arquivo de configurações válido, com o erro `Unrecognized field: sshHostCommands`. Nessas versões, adicione a chave em um editor de texto; o Claude Code carrega um arquivo que contém a chave. No Desktop, a versão que conta é a [versão do Claude Code da aba Code](https://code.claude.com/docs/pt/desktop.md#claude-code-version-in-the-code-tab), não a do seu terminal.5114Antes do Claude Code v2.1.307, a ferramenta Edit recusava uma alteração que adicionava essa chave a um arquivo de configurações válido, com o erro `Unrecognized field: sshHostCommands`. Nessas versões, adicione a chave em um editor de texto; o Claude Code carrega um arquivo que contém a chave. No Desktop, a versão que conta é a [versão do Claude Code da aba Code](https://code.claude.com/docs/pt/desktop.md#claude-code-version-in-the-code-tab), não a do seu terminal.

5111 5115 

5112## Autenticação e provedores5116## Autenticação e provedores


5583 5587 

5584Bloqueie a inicialização do CLI até que Claude Code tenha buscado recentemente [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md). Se a busca falhar, Claude Code sai em vez de continuar com configurações em cache ou nenhuma. Defina-o quando seu ambiente não puder aceitar nem mesmo uma breve janela em que uma sessão seja executada sem sua política gerenciada.5588Bloqueie a inicialização do CLI até que Claude Code tenha buscado recentemente [configurações gerenciadas pelo servidor](https://code.claude.com/docs/pt/server-managed-settings.md). Se a busca falhar, Claude Code sai em vez de continuar com configurações em cache ou nenhuma. Defina-o quando seu ambiente não puder aceitar nem mesmo uma breve janela em que uma sessão seja executada sem sua política gerenciada.

5585 5589 

5586Quando a chave não está definida, Claude Code não bloqueia a inicialização na busca, embora quando o desenvolvedor se conecta na inicialização ele aguarde até cinco segundos pela busca. Uma sessão de gateway na nuvem sempre aguarda e sai se o gateway não puder ser alcançado.5590Quando a chave não está definida, Claude Code não bloqueia a inicialização na busca, embora quando o desenvolvedor se conecta na inicialização ele aguarde até cinco segundos pela busca. [A Anthropic pode exigir as configurações](https://code.claude.com/docs/pt/server-managed-settings.md#fetch-and-caching-behavior), o que de fato bloqueia uma inicialização sem elas. Uma sessão de Cloud gateway aguarda e sai se o gateway não puder ser alcançado.

5587 5591 

5588* **Escopo**: [`Managed`](#scopes). Claude Code honra um `true` de qualquer fonte gerenciada controlada por administrador, mesmo uma que não seja a fonte de prioridade mais alta.5592* **Escopo**: [`Managed`](#scopes). Claude Code honra um `true` de qualquer fonte gerenciada controlada por administrador, mesmo uma que não seja a fonte de prioridade mais alta.

5589* **Tipo**: Booleano5593* **Tipo**: Booleano

5590 * `true`: Claude Code bloqueia a inicialização até ter buscado recentemente configurações gerenciadas pelo servidor e sai se a busca falhar5594 * `true`: Claude Code bloqueia a inicialização até ter buscado recentemente configurações gerenciadas pelo servidor e sai se a busca falhar

5591 * `false`: Claude Code não bloqueia a inicialização na busca, embora em uma inicialização de conexão ele aguarde até cinco segundos pela busca5595 * `false`: a menos que a Anthropic exija as configurações, Claude Code não bloqueia a inicialização na busca, embora em uma inicialização de conexão ele aguarde até cinco segundos pela busca

5592* **Padrão**: `false`5596* **Padrão**: `false`

5593 5597 

5594```json managed-settings.json theme={null}5598```json managed-settings.json theme={null}


5823 5827 

5824### `autoInstallIdeExtension`5828### `autoInstallIdeExtension`

5825 5829 

5826Instale a extensão Claude Code IDE automaticamente quando você executa Claude Code a partir de um terminal VS Code. Aparece em `/config` como **Auto-instalar extensão IDE** quando você executa Claude Code dentro de um terminal VS Code ou JetBrains.5830Permita que [`/ide`](https://code.claude.com/docs/pt/commands) instale a extensão Claude Code IDE em um VS Code, Cursor ou Devin Desktop em execução quando você executa o comando a partir de um terminal externo. Claude Code não instala a extensão quando você o inicia. Aparece em `/config` como **Auto-instalar extensão IDE** quando você executa Claude Code dentro de um terminal VS Code ou JetBrains.

5827 5831 

5828* **Escopo**: [`Global config`](#scopes)5832* **Escopo**: [`Global config`](#scopes)

5829* **Tipo**: Booleano5833* **Tipo**: Booleano

5830 * `true`: Claude Code instala a extensão IDE automaticamente quando você a executa a partir de um terminal VS Code5834 * `true`: `/ide` instala a extensão

5831 * `false`: Claude Code não instala a extensão automaticamente5835 * `false`: `/ide` não instala a extensão

5832* **Padrão**: `true`5836* **Padrão**: `true`

5833* **Substituições por sessão**: [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](https://code.claude.com/docs/pt/env-vars) definido como `1` pula a instalação para uma sessão mesmo quando essa chave é `true`5837* **Substituições por sessão**: [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](https://code.claude.com/docs/pt/env-vars) definido como `1` pula a instalação para uma sessão mesmo quando essa chave é `true`

5834 5838 

skills.md +1 −1

Details

404| `allowed-tools` | Não | Ferramentas que Claude pode usar sem pedir permissão durante o turno que invoca esta skill. A concessão é removida quando você envia sua próxima mensagem. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. Consulte [Pré-aprovar ferramentas para uma skill](#pre-approve-tools-for-a-skill). |404| `allowed-tools` | Não | Ferramentas que Claude pode usar sem pedir permissão durante o turno que invoca esta skill. A concessão é removida quando você envia sua próxima mensagem. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. Consulte [Pré-aprovar ferramentas para uma skill](#pre-approve-tools-for-a-skill). |

405| `disallowed-tools` | Não | Ferramentas removidas do conjunto disponível para Claude enquanto esta skill está ativa. Use para skills autônomas que nunca devem chamar certas ferramentas, como `AskUserQuestion` em um loop em segundo plano. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. A restrição é removida quando você envia sua próxima mensagem. Assim como as regras deny, o campo não pode remover [`EndConversation`](https://code.claude.com/docs/pt/tools-reference#endconversation-tool-behavior) enquanto qualquer outra ferramenta permanecer. |405| `disallowed-tools` | Não | Ferramentas removidas do conjunto disponível para Claude enquanto esta skill está ativa. Use para skills autônomas que nunca devem chamar certas ferramentas, como `AskUserQuestion` em um loop em segundo plano. Aceita uma string separada por espaços ou vírgulas, ou uma lista YAML. A restrição é removida quando você envia sua próxima mensagem. Assim como as regras deny, o campo não pode remover [`EndConversation`](https://code.claude.com/docs/pt/tools-reference#endconversation-tool-behavior) enquanto qualquer outra ferramenta permanecer. |

406| `model` | Não | Modelo a ser usado quando esta skill está ativa. A substituição se aplica ao restante do turno atual e não é salva nas configurações. O modelo da sessão é retomado quando você envia seu próximo prompt. Aceita os mesmos valores que [`/model`](https://code.claude.com/docs/pt/model-config), ou `inherit` para manter o modelo ativo. Um valor excluído pela allowlist [`availableModels`](https://code.claude.com/docs/pt/model-config#restrict-model-selection) da sua organização não é usado, e a sessão mantém seu modelo atual. No [modo auto](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode), e no [modo de planejamento enquanto o classificador revisa comandos](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode), um modelo que o modo auto não suporta também não é usado, e a sessão mantém seu modelo atual. Com `context: fork`, o valor define o [modelo do subagente bifurcado](#run-skills-in-a-subagent), e um valor excluído segue as [mesmas regras de uma substituição de modelo de subagente](https://code.claude.com/docs/pt/model-config.md#restrict-model-selection). |406| `model` | Não | Modelo a ser usado quando esta skill está ativa. A substituição se aplica ao restante do turno atual e não é salva nas configurações. O modelo da sessão é retomado quando você envia seu próximo prompt. Aceita os mesmos valores que [`/model`](https://code.claude.com/docs/pt/model-config), ou `inherit` para manter o modelo ativo. Um valor excluído pela allowlist [`availableModels`](https://code.claude.com/docs/pt/model-config#restrict-model-selection) da sua organização não é usado, e a sessão mantém seu modelo atual. No [modo auto](https://code.claude.com/docs/pt/permission-modes.md#eliminate-prompts-with-auto-mode), e no [modo de planejamento enquanto o classificador revisa comandos](https://code.claude.com/docs/pt/permission-modes.md#analyze-before-you-edit-with-plan-mode), um modelo que o modo auto não suporta também não é usado, e a sessão mantém seu modelo atual. Com `context: fork`, o valor define o [modelo do subagente bifurcado](#run-skills-in-a-subagent), e um valor excluído segue as [mesmas regras de uma substituição de modelo de subagente](https://code.claude.com/docs/pt/model-config.md#restrict-model-selection). |

407| `effort` | Não | [Nível de esforço](https://code.claude.com/docs/pt/model-config.md#adjust-effort-level) para o restante do turno atual. Sobrescreve o nível de esforço da sessão, mas não a variável de ambiente [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/pt/env-vars#variables). Com `context: fork`, o valor define, em vez disso, o nível de esforço do subagente bifurcado. Quando você o omite, o nível vem da [ordem de resolução de esforço](https://code.claude.com/docs/pt/model-config.md#adjust-effort-level). Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo. |407| `effort` | Não | [Nível de esforço](https://code.claude.com/docs/pt/model-config.md#adjust-effort-level) para o restante do turno atual. Sobrescreve o nível de esforço da sessão, mas não a variável de ambiente [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/pt/env-vars#variables). Com `context: fork`, o valor define, em vez disso, o nível de esforço do subagente bifurcado. Quando você o omite, o nível vem da [ordem de resolução de esforço](https://code.claude.com/docs/pt/model-config.md#adjust-effort-level). Para um subagente bifurcado em outro modelo, consulte [Nível de esforço de subagentes e colegas de equipe](https://code.claude.com/docs/pt/model-config.md#effort-level-of-subagents-and-teammates). Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo. |

408| `context` | Não | Defina como `fork` para executar em um contexto de subagente bifurcado. Consulte [Executar skills em um subagente](#run-skills-in-a-subagent). |408| `context` | Não | Defina como `fork` para executar em um contexto de subagente bifurcado. Consulte [Executar skills em um subagente](#run-skills-in-a-subagent). |

409| `agent` | Não | Qual tipo de subagente usar quando `context: fork` está definido. |409| `agent` | Não | Qual tipo de subagente usar quando `context: fork` está definido. |

410| `background` | Não | Aplica-se apenas com `context: fork`. Defina como `false` para aguardar o resultado do subagente bifurcado no turno que invocou a skill, em vez de [executá-lo em segundo plano](#run-skills-in-a-subagent). Padrão: `true`. |410| `background` | Não | Aplica-se apenas com `context: fork`. Defina como `false` para aguardar o resultado do subagente bifurcado no turno que invocou a skill, em vez de [executá-lo em segundo plano](#run-skills-in-a-subagent). Padrão: `true`. |

Details

1264 1264 

1265Assim que o Keychain for gravável novamente, Claude Code move as credenciais de volta na próxima vez que grava uma credencial. Para forçar agora, execute `/logout` e depois `/login`. Sair remove todas as credenciais armazenadas, incluindo o conteúdo do arquivo de texto simples, logins de servidor MCP salvos e valores sensíveis de plugin, então espere re-autorizar servidores MCP e re-inserir segredos de plugin depois. Fazer login novamente armazena seu login no Keychain.1265Assim que o Keychain for gravável novamente, Claude Code move as credenciais de volta na próxima vez que grava uma credencial. Para forçar agora, execute `/logout` e depois `/login`. Sair remove todas as credenciais armazenadas, incluindo o conteúdo do arquivo de texto simples, logins de servidor MCP salvos e valores sensíveis de plugin, então espere re-autorizar servidores MCP e re-inserir segredos de plugin depois. Fazer login novamente armazena seu login no Keychain.

1266 1266 

1267#### Falha de login em um diretório pessoal de rede

1268 

1269Quando uma requisição falha com `API Error: 401` e seu [diretório de configuração](https://code.claude.com/docs/pt/claude-directory.md) está em um sistema de arquivos de rede, verifique se esse sistema de arquivos ou sua cota nele está cheio. Sem espaço restante, Claude Code não consegue salvar um login novo ou renovado no [arquivo `.credentials.json`](https://code.claude.com/docs/pt/authentication#credential-management) de texto simples, e `claude auth login` ainda pode imprimir `Login successful.`

1270 

1271**1. Liberar espaço no sistema de arquivos**

1272 

1273Exclua arquivos de que você não precisa mais no sistema de arquivos que contém `~/.claude`, ou o diretório que você definiu em [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/pt/env-vars).

1274 

1275**2. Fazer login novamente**

1276 

1277Execute `/login` no prompt do Claude Code ou `claude auth login` em seu shell.

1278 

1279Antes da v2.1.318, quando Claude Code salvava o arquivo de login em um sistema de arquivos de rede cheio, ele podia substituir um login armazenado ainda válido por um arquivo vazio. Comandos posteriores então reportavam `Not logged in`.

1280 

1267### Bedrock, Agent Platform, or Foundry credentials not loading1281### Bedrock, Agent Platform, or Foundry credentials not loading

1268 1282 

1269Se você configurou Claude Code para usar um provedor de nuvem e vê `Could not load credentials from any providers` no Amazon Bedrock, `Could not load the default credentials` no Google Cloud's Agent Platform, ou `ChainedTokenCredential authentication failed` no Microsoft Foundry, seu CLI do provedor de nuvem provavelmente não está autenticado no shell atual.1283Se você configurou Claude Code para usar um provedor de nuvem e vê `Could not load credentials from any providers` no Amazon Bedrock, `Could not load the default credentials` no Google Cloud's Agent Platform, ou `ChainedTokenCredential authentication failed` no Microsoft Foundry, seu CLI do provedor de nuvem provavelmente não está autenticado no shell atual.

vs-code.md +7 −2

Details

818 818 

819### Executar a CLI no VS Code819### Executar a CLI no VS Code

820 820 

821Para usar a CLI sem sair do VS Code, pressione `` Ctrl+` `` no Windows/Linux ou `` Cmd+` `` no Mac para abrir o terminal integrado e, em seguida, execute `claude`. A CLI se integra automaticamente ao seu IDE para recursos como visualização de diff e compartilhamento de diagnósticos. Se você usa um terminal externo, execute `/ide` dentro do Claude Code para conectá-lo ao VS Code.821Para usar a CLI sem sair do VS Code, pressione `` Ctrl+` `` no Windows/Linux ou `` Cmd+` `` no Mac para abrir o terminal integrado e, em seguida, execute `claude`. Iniciar `claude` não instala a extensão. Sem ela, `/ide` no terminal integrado informa "No available IDEs detected" e `/status` mostra o IDE como "Not connected".

822 

823Para obter recursos como visualização de diff e compartilhamento de diagnósticos, conecte a CLI à extensão a partir do terminal integrado ou de um terminal externo:

824 

825* **Terminal integrado**: [instale a extensão](#install-the-extension) e, em seguida, inicie `claude`. A CLI se conecta automaticamente.

826* **Terminal externo**: execute `/ide` dentro do Claude Code para conectá-lo ao VS Code. Se o VS Code estiver em execução sem a extensão, `/ide` a instala, a menos que você tenha desativado [`autoInstallIdeExtension`](https://code.claude.com/docs/pt/settings-reference#autoinstallideextension).

822 827 

823Instalar a extensão não coloca `claude` no PATH do seu shell. A extensão inclui uma cópia privada da CLI para o seu painel de chat, mas digitar `claude` em um terminal requer a [instalação independente da CLI](https://code.claude.com/docs/pt/setup.md). Execute a instalação uma vez e os comandos desta página, incluindo `claude mcp add` e `claude --resume`, funcionarão em qualquer terminal. Se `claude` ainda não for encontrado após a instalação, [verifique seu PATH](https://code.claude.com/docs/pt/troubleshoot-install.md#verify-your-path).828Instalar a extensão não coloca `claude` no PATH do seu shell. A extensão inclui uma cópia privada da CLI para o seu painel de chat, mas digitar `claude` em um terminal requer a [instalação independente da CLI](https://code.claude.com/docs/pt/setup.md). Execute a instalação uma vez e os comandos desta página, incluindo `claude mcp add` e `claude --resume`, funcionarão em qualquer terminal. Se `claude` ainda não for encontrado após a instalação, [verifique seu PATH](https://code.claude.com/docs/pt/troubleshoot-install.md#verify-your-path).

824 829 


10862. Pesquise por "Claude Code"10912. Pesquise por "Claude Code"

10873. Clique em **Uninstall**10923. Clique em **Uninstall**

1088 1093 

1089Se você executar `claude` em um terminal integrado do VS Code, o Claude Code reinstala a extensão automaticamente. Para mantê-la desinstalada, desative **Auto-install IDE extension** em `/config` ou defina [`autoInstallIdeExtension`](https://code.claude.com/docs/pt/settings-reference#autoinstallideextension) como `false`. Você também pode definir a variável de ambiente [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](https://code.claude.com/docs/pt/env-vars) como `1`.1094A extensão permanece desinstalada quando você inicia `claude`. Se você executar `/ide` a partir de um terminal externo enquanto o VS Code estiver em execução, o Claude Code a reinstala. Para impedir isso, defina [`autoInstallIdeExtension`](https://code.claude.com/docs/pt/settings-reference#autoinstallideextension) como `false` em `~/.claude.json` ou desative **Auto-install IDE extension** em `/config` no terminal integrado. Você também pode definir a variável de ambiente [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](https://code.claude.com/docs/pt/env-vars) como `1`.

1090 1095 

1091Para também remover os dados da extensão e redefinir todas as configurações, exclua o diretório de armazenamento da extensão para sua plataforma.1096Para também remover os dados da extensão e redefinir todas as configurações, exclua o diretório de armazenamento da extensão para sua plataforma.

1092 1097