# Recuperação do Claude Code: Safe Mode, /cd e modelos alternativos > Diagnosticar problemas no Claude Code com o safe mode, o comando /cd, modelos alternativos e recuperação das definições. A ordem das verificações e as limitações originais. Source: https://ailoot.ai/blog/pt-pt/claude-code-safe-mode-recovery/ Canonical: https://ailoot.ai/blog/pt-pt/claude-code-safe-mode-recovery/ Language: pt-PT Publisher: Ailoot (https://ailoot.ai/) Translation: guide-140 Revision: sha256-2cb9ce92f071e5731d0e7c9f7bc0d45120d0b47394e36838753170913d8f94be Materiais práticos sobre trabalhar com agentes: [documentação Ailoot](https://ailoot.ai/docs/). ## O que mudou no Claude Code em junho de 2026?
Principais conclusões A 8 de junho de 2026, no Claude Code v2.1.169, a Anthropic acrescentou a opção `--safe-mode` e o comando `/cd`. Dois dias antes, a v2.1.166 tinha introduzido modelos alternativos, até 3 numa cadeia. Estas três funcionalidades resolvem o problema mais comum dos vibe coders: «está tudo em baixo, não sei de quem é a culpa e não quero perder uma hora a reinstalar».
Anteriormente, quando o Claude Code começava a comportar-se de forma estranha — um indicador de carregamento interminável, uma falha ao arrancar, o agente a ignorar as regras em `CLAUDE.md`, um hook que não era executado sem dar sinal — só havia uma saída: comentar manualmente secções de `.claude/settings.json`, desativar servidores MCP um a um ou, no pior dos casos, apagar `~/.claude` e reinstalar. Num caso descrito, apagou-se `~/.claude` e perdeu-se a configuração do servidor MCP, que tinha demorado hora e meia a montar. Mais tarde, percebeu-se que a culpa era de uma linha em `CLAUDE.md` e que poderia ter sido encontrada em 10 segundos — mas isso só ficou claro depois de uma recuperação completa. Em junho de 2026, a Anthropic lançou três mecanismos que mudam este cenário. Em resumo, o que chegou e quando: | Versão | Data | O que chegou | |----|----|----| | **2.1.166** | 6 de junho de 2026 | Definição `fallbackModel` + opção `--fallback-model` para sessões interativas | | **2.1.169** | 8 de junho de 2026 | Opção `--safe-mode` e variável de ambiente `CLAUDE_CODE_SAFE_MODE`, comando `/cd` | | **2.1.176** | 12 de junho de 2026 | Correção: `/cd` e a mudança de worktree deixaram de mostrar o ramo antigo do git | A seguir, cada mecanismo é explicado passo a passo, juntamente com a ordem pela qual os deve aplicar quando uma sessão do Claude Code descarrila. ## O que costuma avariar o Claude Code?
Principais conclusões Com base na experiência descrita, o Claude Code costuma avariar para os vibe coders devido a quatro coisas: um `CLAUDE.md` demasiado extenso com regras contraditórias, um hook com o código de saída errado, um servidor MCP que falha silenciosamente e definições sobrepostas em três níveis de `settings.json`. Há um culpado, o diagnóstico demora minutos e o pânico leva as pessoas a recorrer imediatamente a `rm -rf`.
No exemplo descrito, o `CLAUDE.md` foi inicialmente criado com 80 linhas — e funcionou durante um mês. No segundo mês, tornou-se evidente que, uma vez por semana, o Claude violava todas as regras definidas: tocava em `.env`, executava `git push --force`, remexia em `node_modules`. Não o fazia de forma maliciosa — simplesmente esquecia-se. Uma vez, o `.gitignore` foi apagado e a razão não ficou imediatamente clara. Este cenário é abordado com mais detalhe no [guia sobre `CLAUDE.md`](https://ailoot.ai/blog/pt-pt/claude-md-template/). Quando o `CLAUDE.md` chega às 400+ linhas, começa a causar problemas silenciosamente: ocupa uma parte significativa da janela de contexto no arranque da sessão e dilui as instruções importantes entre as secundárias. O Claude continua formalmente a ler o ficheiro, por isso, visto de fora, parece que «as regras estão lá, mas não funcionam» — um sinal típico de um contrato demasiado extenso. Os hooks são a segunda fonte comum de problemas. Os `Claude Code hooks` têm uma particularidade que a Anthropic não salienta. Ou seja, `sys.exit(1)` num hook Python (ou qualquer «falhou com um erro» convencional em Unix) não interrompe o Claude. Só o código `2` é bloqueante. No caso descrito, o hook era considerado uma «proibição absoluta», mas na prática registava uma reclamação e permitia a ação. Os servidores MCP são a terceira camada e também podem avariar à sua maneira. O sintoma é muitas vezes igual: os comandos MCP estão disponíveis, mas devolvem `failed` sem um traceback. Para saber mais sobre a configuração do MCP e como adicionar servidores com `claude mcp add`, consulte o [guia separado](https://ailoot.ai/blog/pt-pt/mcp-servers-claude-code/). A quarta fonte é a hierarquia de três níveis de `settings.json`. Tem `~/.claude/settings.json` (nível de utilizador), `.claude/settings.json` na raiz do projeto (projeto), `.claude/settings.local.json` (local) e, opcionalmente, definições geridas por um administrador da empresa. Estas são combinadas de acordo com regras de prioridade. Quando alguém adiciona um servidor MCP ao nível do projeto e já tem uma entrada semelhante, mas com uma configuração de arranque diferente, ao nível do utilizador, o resultado é um conflito silencioso que parece significar «o Claude Code está avariado». ## Como funciona o `--safe-mode` e o que desativa?
Principais conclusões `claude --safe-mode` inicia o Claude Code com as personalizações totalmente desativadas: `CLAUDE.md`, plugins, skills, hooks, servidores MCP, comandos de utilizador, agentes, estilos de saída, workflows e atalhos de teclado. A autorização, a seleção do modelo, as ferramentas integradas e as permissões continuam ativas. É uma ferramenta de diagnóstico: se o problema desaparecer no safe mode, a culpa é de uma das camadas que adicionou.
A formulação original da Anthropic no changelog da v2.1.169 diz:

Adicionada a opção --safe-mode (e CLAUDE_CODE_SAFE_MODE) para iniciar o Claude Code com as personalizações desativadas (CLAUDE.md, plugins, skills, hooks, servidores MCP) para fins de diagnóstico.

— Anthropic Claude Code Changelog, https://code.claude.com/docs/en/changelog
A Anthropic esclarece na documentação de configuração do modelo:

Para verificar se a culpa é das personalizações, inicie uma sessão com claude --safe-mode, que desativa CLAUDE.md, skills, servidores MCP e hooks. O estado do Git e os nomes dos diretórios não são considerados personalizações e continuam disponíveis.

— Anthropic Docs - Model configuration, https://code.claude.com/docs/en/model-config
Esta é uma **ferramenta de diagnóstico**, não um «ambiente limpo». O safe mode ajuda a responder a uma pergunta: o problema está no comportamento normal do Claude Code ou nas personalizações adicionadas? Isto faz parte da engenharia de contexto — gerir aquilo que o Claude vê e não vê em cada momento. Se tudo funcionar no safe mode, é evidente que as camadas devem ser verificadas através de uma pesquisa binária. Se não funcionar, o problema está na própria instalação, na autorização, na rede ou na infraestrutura; nesse caso, faz sentido consultar `claude doctor` e os registos. O que o safe mode desativa (lista oficial da Anthropic — 5 camadas principais): - `CLAUDE.md` em todos os níveis (utilizador / projeto) - Plugins - Skills - Hooks - Servidores MCP O que continua a funcionar: - Autorização (a sua sessão OAuth ou chave de API) - Seleção do modelo (`--model sonnet`, `--model opus`) - Ferramentas integradas (Read, Write, Bash, Grep, entre outras) - Permissões - Estado do Git - Nomes dos diretórios Um pormenor importante: o safe mode não desativa as definições geridas nem as políticas de um administrador da empresa. Se trabalha numa equipa em que o Bedrock GovCloud ou uma configuração MDM define `availableModels`, essas restrições mantêm-se — o safe mode desativa apenas as suas personalizações, não as políticas da empresa. ## Como isolar uma camada e encontrar o culpado em 60 segundos?
Principais conclusões Passo 1: execute `claude --safe-mode` na mesma pasta em que os problemas estavam a ocorrer. Se funcionar, o problema está nas suas personalizações; em seguida, ative-as uma a uma: `CLAUDE.md` -> hooks -> MCP -> skills. Se nem no safe mode funcionar, o problema está na autenticação, na versão, na rede ou no sistema operativo. Nesse caso, execute `claude doctor` para fazer um diagnóstico automático, sem tocar em `rm -rf`.
Um procedimento de diagnóstico para quando o Claude Code «deixou de ouvir». A versão mínima para todos os comandos abaixo é **Claude Code v2.1.169**. Se tiver uma versão anterior, atualize primeiro (`npm update -g @anthropic-ai/claude-code` ou através do instalador nativo da Anthropic). 1. Abra a mesma pasta em que os problemas estavam a ocorrer. 2. Execute `claude --safe-mode`. 3. Se iniciar sem problemas, verifique o pedido original. Funcionou? Então a culpa é de uma das camadas. Avance para o passo 4. 4. Se continuar avariado no safe mode, não toque nas configurações. Execute primeiro `claude doctor`; verifique a autenticação, a versão e a existência de instalações em conflito. Quando o safe mode iniciar sem problemas, ative as camadas uma de cada vez, começando pelo culpado mais provável. A ordem baseia-se na experiência descrita: 1. **`CLAUDE.md`.** Execute `claude` sem safe mode, mas mude temporariamente o nome do ficheiro: `mv CLAUDE.md CLAUDE.md.bak`. Se funcionar, a causa é esse ficheiro. Depois, pode fazer uma pesquisa binária: mantenha metade das linhas e verifique. 2. **Hooks.** Abra `.claude/settings.json` e defina temporariamente `[]` na secção `hooks`. Reinicie o `claude`. Funciona? Então a culpa é de um dos hooks. Ative-os um a um. 3. **Servidores MCP.** De forma semelhante, em `~/.claude.json` ou `.claude/settings.json`, defina temporariamente a secção `mcpServers` como um objeto vazio, reinicie e verifique. 4. **Skills.** Mova `.claude/skills/` para uma pasta temporária. Inicie e verifique. O que significa «mudança temporária de nome»: os ficheiros não são apagados durante o diagnóstico. `mv` ou `git stash` permitem restaurar tudo com um comando, caso se conclua que essa camada não era a culpada. ## Como mudar a pasta de trabalho com `/cd` sem perder o contexto?
Principais conclusões O comando `/cd ` no Claude Code 2.1.169+ muda a pasta de trabalho na sessão ativa sem perder a cache do prompt. É útil quando a configuração do projeto atual está avariada: pode mudar para uma pasta limpa, verificar se o Claude funciona e voltar. Antes, era preciso fechar a sessão e iniciar outra.
Do changelog da v2.1.169, a 8 de junho:

Adicionado o comando /cd para mudar a sessão para uma nova pasta de trabalho sem repor a cache do prompt a meio da sessão.

— Anthropic Claude Code Changelog, https://code.claude.com/docs/en/changelog
Porque é útil para resolver problemas. Imagine que está na pasta do projeto `~/work/myapp` e o Claude Code se comporta de forma estranha. Antes, a única forma de verificar «se funciona de todo» era fechar a sessão, mudar para outra pasta e iniciar de novo. Perdia o contexto, o histórico e a cache do prompt já aquecida. Agora: ```bash # In the same session: /cd ~/sandbox/test ``` O Claude muda para a nova pasta e lê o `CLAUDE.md` que lá exista como uma mensagem, não como substituição do prompt de sistema — ou seja, a cache é preservada. Se tudo funcionar em `~/sandbox/test`, é evidente que o problema estava na configuração de `~/work/myapp`. A 12 de junho, a v2.1.176 corrigiu uma regressão desagradável: `/cd` mostrava o ramo antigo do git até ser feito um reinício completo. Se tiver uma versão anterior, atualize ou simplesmente ignore `git status` durante as primeiras mensagens após a mudança — será atualizado. ## Como configurar modelos alternativos para um erro 529?
Principais conclusões Na v2.1.166, a Anthropic acrescentou `fallbackModel` — uma cadeia de até 3 modelos experimentados em sequência quando o modelo principal está sobrecarregado ou indisponível. A cadeia só é ativada por sobrecarga e erros de servidor não repetíveis. Erros de autorização, faturação, limite de pedidos e transporte não ativam a cadeia alternativa — seguem a lógica normal de repetição.
No cenário descrito, uma tarefa longa é executada no Opus num projeto uma vez por semana; ao fim de 10 minutos, a API devolve 529 Overloaded e a sessão falha. Antes, era preciso esperar ou mudar manualmente para Sonnet com `--model sonnet`, perdendo todo o contexto já aquecido. Num `business/` de grandes dimensões, com uma configuração de segundo cérebro, isto demora cerca de vinte minutos de trabalho. Agora existe um mecanismo adequado. A citação exata da documentação oficial:

Quando o modelo principal está sobrecarregado, indisponível ou devolve outro erro de servidor não repetível, o Claude Code pode mudar para um modelo alternativo em vez de falhar o pedido. Erros de autorização, faturação, limite de pedidos, tamanho do pedido e transporte nunca ativam a mudança — seguem o percurso normal de repetição e tratamento de erros.

— Anthropic Docs - Model configuration, https://code.claude.com/docs/en/model-config
E, separadamente, como funciona a cadeia:

Configure um ou mais modelos alternativos e o Claude Code experimenta-os pela ordem definida, apresentando uma notificação quando muda. A mudança aplica-se apenas ao turno atual — a mensagem seguinte volta a tentar o modelo principal. As cadeias estão limitadas a três modelos após a remoção de duplicados; as entradas adicionais são ignoradas.

— Anthropic Docs - Model configuration, https://code.claude.com/docs/en/model-config
Há duas formas de configurar esta opção. Através da CLI: ```bash claude --fallback-model sonnet,haiku ``` Através de `~/.claude/settings.json`: ```json { "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"] } ``` Uma observação à parte sobre os limites de pedidos. A Anthropic não encaminha deliberadamente um erro 429 para a cadeia, para impedir que se contorne o limite de pedidos mudando para o modelo seguinte. O modelo alternativo só funciona quando o modelo principal está sobrecarregado, indisponível ou devolve um erro de servidor não repetível (por exemplo, 529 Overloaded). Os limites de pedidos seguem a lógica normal de repetição e espera progressiva. Mais uma observação — a 12 de junho, a v2.1.174 corrigiu uma regressão: a compactação não respeitava `--fallback-model`. Se tiver uma sessão longa e houver compactação durante uma sobrecarga, antes desta correção o modelo alternativo não era chamado. Se trabalhar com sessões longas (`/compact`, `/loop` durante a noite), atualize pelo menos para a v2.1.174. ## O que corrigir quando a culpa é do `CLAUDE.md`, de um hook, do MCP ou de uma skill?
Principais conclusões Quando o safe mode identifica a camada culpada, a correção varia consoante a camada. Para `CLAUDE.md`, utilize uma pesquisa binária ou volte a um modelo pronto a usar com menos de 200 linhas. Para um hook, verifique o código de saída (2 bloqueia, 1 não bloqueia) e a lógica. Para o MCP, remova um servidor e verifique. Para uma skill, procure contradições entre `SKILL.md` e `CLAUDE.md`.
Estratégias específicas para cada camada. ### Se a culpa for do `CLAUDE.md` Abra o ficheiro e verifique o tamanho. Com base na experiência descrita, **mantenha o `CLAUDE.md` ativo com, no máximo, 200 linhas**; transfira o resto para routers e documentos de apoio junto ao projeto (a estrutura completa do segundo cérebro está no [guia sobre o segundo cérebro](https://ailoot.ai/blog/pt-pt/claude-code-second-brain/)). Se tiver 400+ linhas, é quase de certeza o culpado. Passos: 1. Faça uma cópia de segurança: `cp CLAUDE.md CLAUDE.md.full`. 2. Volte a um modelo curto que funcione. Encontra um modelo pronto a usar no [guia «Como configurar o CLAUDE.md»](https://ailoot.ai/blog/pt-pt/claude-md-template/). 3. Reinicie o Claude Code. Verifique. 4. Se funcionar, reponha as regras em pequenos blocos de 10–20 linhas, verificando após cada bloco. 5. Encontre o bloco que afeta o comportamento. Reescreva-o como um hook com o código de saída correto (os códigos de saída dos hooks são abordados na subsecção seguinte deste H2). ### Se a culpa for de um hook A questão principal é saber se o código de saída está correto. Os hooks do Claude Code usam: - **Exit 0** — tudo bem; a ação prossegue. - **Exit 1** — um erro, mas **não bloqueante**. O Claude continua como se nada tivesse acontecido. - **Exit 2** — um erro **bloqueante**. Só este código interrompe efetivamente a ação. Se escreveu `sys.exit(1)` ou `exit 1` num hook shell a pensar que estava a bloquear, esse código funciona como uma mensagem de aviso no Claude Code e não interrompe a ação. Mude-o para `2`. Para mais informações sobre hooks e como os configurar sem esta armadilha, consulte o [guia separado](https://ailoot.ai/blog/pt-pt/claude-code-hooks/). O segundo caso comum é um hook devolver JSON inválido em stdout. O Claude Code analisa a resposta do hook como JSON e, se incluir conteúdo adicional (um registo, um indicador de progresso, um emoji), considera-se que o hook falhou e a ação prossegue. Regra: **stdout só contém JSON; tudo o resto vai para stderr**. O terceiro caso é um hook que lê algo de `~/.claude/` que o safe mode ocultou. É um cenário normal; a solução não é corrigir o hook com um patch, mas verificar `os.environ.get('CLAUDE_CODE_SAFE_MODE')` no início e sair com o código 0. ### Se a culpa for de um servidor MCP Sintomas: os comandos MCP estão disponíveis, mas devolvem `failed` sem um traceback claro. Passos: 1. Execute `claude mcp list` — que servidores estão definidos? 2. Desative os servidores um a um em `~/.claude.json`: mude o nome da chave `claude-server-A` para `_claude-server-A` (isto desativa-a sem a apagar). 3. Reinicie o `claude`. Verifique que chamadas funcionam. 4. Quando encontrar o servidor culpado, verifique o respetivo registo: `claude mcp logs `. 5. Se for um servidor de terceiros (`@modelcontextprotocol/server-postgres` e outros semelhantes), verifique se tem uma versão recente. O ecossistema MCP continua em turbulência; os servidores avariam regularmente com as atualizações do Claude Code. Se encontrar «falhas ao arrancar, e apenas com dois MCP», compare o comportamento no safe mode sem MCP. ### Se a culpa for de uma skill Uma skill é composta por `SKILL.md` e código em `.claude/skills//`. Sintomas: o Claude ignora a skill, aplica-a na altura errada ou aplica-a mas produz resultados sem sentido. Passos: 1. Abra `SKILL.md`. Verifique a descrição — **deve ter 1–2 frases e indicar especificamente quando utilizar a skill**. Se disser «um assistente universal para tudo», o Claude não percebe quando a deve invocar. 2. Procure contradições com `CLAUDE.md`. Se `CLAUDE.md` disser «escreve sempre testes», mas a descrição da skill disser «utiliza para prototipagem rápida sem testes», há um conflito. 3. Se a skill utilizar comandos externos (npm, python, git), verifique se estão disponíveis no PATH do sistema. Uma skill tem o seu próprio ambiente mínimo. ## Se Safe Mode não ajudar: diagnosticar e preservar o estado antes de reparar
Principais conclusões Se Safe Mode também falhar, ainda pode haver causas de instalação, autorização, rede ou infraestrutura. Execute `claude doctor` e examine a evidência. Um relatório inconclusivo não justifica eliminar definições ou sessões: preserve e verifique primeiro o estado completo e repare só a instalação diagnosticada.
Remover dados do utilizador não é um atalho de diagnóstico. Use as verificações abaixo para identificar a falha; se forem inconclusivas, preserve a evidência e investigue. Qualquer reparação começa por cópia verificada e mantém a conta e a identidade no armazenamento de credenciais existentes. Ordem: 1. **`claude doctor`** — diagnóstico automático. A Anthropic escreve na sua documentação:

Se `claude --version` funcionar, mas houver algo mais a correr mal, execute `claude doctor` para gerar um relatório de diagnóstico automático.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install
2. **Verifique se há instalações em conflito.** Muitas pessoas têm instalada ao mesmo tempo uma versão global npm e o instalador nativo:

Várias instalações do Claude Code podem causar divergências de versões ou um comportamento inesperado.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install
3. **Verifique se `ANTHROPIC_API_KEY` está a intercetar a sua sessão OAuth.** Esta é uma causa comum de «nada funciona, a chave expirou»:

Quando `ANTHROPIC_API_KEY` está definida e confirma a sua utilização, o Claude Code utiliza essa chave em vez das credenciais OAuth da sua subscrição.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install
Solução: execute `unset ANTHROPIC_API_KEY` na sessão shell atual ou remova-a de `~/.zshrc` / `~/.bashrc`. 4. **Repare só a instalação identificada pelo diagnóstico; preserve antes todo o estado.** Uma falha Safe Mode ou doctor inconclusivo não prova que deva remover dados. Pare todas as sessões Claude e outros escritores antes de uma cópia consistente. Mantenha utilizador Unix, HOME, armazenamento de credenciais do sistema e conta Anthropic; não rode chaves nem crie outra identidade. O exemplo de cópia seguinte é para **Linux com GNU tar**. Em macOS ou Windows, use uma ferramenta que preserve ACLs, atributos alargados, ligações e metadados da plataforma e verifique o restauro; não assuma suporte de opções exclusivas GNU. O arquivo contém credenciais e transcrições: mantenha-o privado e fora de repositórios. ```bash # Executar como o mesmo utilizador dono do estado Claude, após parar escritores. set -eu umask 077 backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX") set -- if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then set -- "$@" .claude fi if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then set -- "$@" .claude.json fi [ "$#" -gt 0 ] || exit 1 tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@" tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME" sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256" (cd "$backup_dir" && sha256sum -c claude-state.sha256) mkdir "$backup_dir/restore-check" tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check" tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check" printf 'Verified recovery directory: %s\n' "$backup_dir" ``` Todos os comandos têm de passar. O arquivo cobre a árvore `.claude` inteira existente, incluindo sessões ignoradas/não controladas e estado de plugins, e `.claude.json`, não só definições Git. Se algum caminho for ligação simbólica ou houver dados noutro local configurado, pare e inclua o destino resolvido na mesma cópia verificada; arquivar só a ligação não copia o destino. O arquivo não inclui macOS Keychain nem outro armazenamento externo de credenciais: mantenha essas identidades no lugar. Se o diagnóstico identificar especificamente a **instalação local antiga** como cópia em conflito, mova só essa instalação para a pasta privada de recuperação, sem eliminar configuração e sessões: ```bash # Usar backup_dir verificado no bloco anterior. if [ -d "$HOME/.claude/local" ]; then mv "$HOME/.claude/local" "$backup_dir/legacy-local" fi ``` Remova a instalação npm só se o diagnóstico a identificar como conflito e pretender manter a nativa. Use depois o [instalador nativo documentado](https://code.claude.com/docs/en/setup), sem eliminar `.claude` ou `.claude.json`: ```bash curl -fsSL https://claude.ai/install.sh | bash claude --version claude doctor ``` Em Windows, o comando nativo continua a ser: ```powershell irm https://claude.ai/install.ps1 | iex ``` **Restaure separadamente.** Pare novamente os escritores. Verifique a soma do arquivo e extraia para uma pasta de recuperação vazia como acima; compare com sucesso antes de usar os ficheiros. Para repor a instalação antiga movida, confirme primeiro que `$HOME/.claude/local` não existe e mova `$backup_dir/legacy-local` de volta para esse caminho exato. Restaure um ficheiro de definições diagnosticado a partir da extração verificada só depois de preservar a substituição atual; não sobreponha a árvore inteira cegamente. Sessões, MCP e identidade original ficam preservados. Um retrato Git não cobre transcrições ignoradas/não controladas, credenciais ou metadados do sistema de ficheiros. ## O que NÃO deve fazer quando o Claude Code está avariado?
Principais conclusões Seis anti-padrões encontrados nos casos de suporte descritos: mudar as chaves antes do diagnóstico, fazer uma reposição completa como primeiro passo, entrar em pânico com um erro de UI num hook, aumentar o código de saída de um hook antes de corrigir a lógica, editar `CLAUDE.md` sem a salvaguarda do safe mode e acreditar que «o Claude corrige o seu próprio MCP». Cada um custa horas e nenhum é necessário.
### Não mude as chaves antes do diagnóstico «A autorização não funciona» deve-se, em 90% dos casos, a `ANTHROPIC_API_KEY` a intercetar a subscrição, a um erro de UI do hook ou a uma falha do MCP. Mudar as chaves não corrigirá nada disto e causará mais uma hora de inatividade: terá de revogar a chave antiga, emitir uma nova, voltar a assinar o CI com ela e atualizar as variáveis em produção. Execute primeiro `claude --safe-mode`. Funciona? Então o problema está nas personalizações; não é necessário mexer nas chaves. ### Não faça uma reposição completa antes de experimentar o safe mode Eliminar `.claude` pode destruir sessões, configuração MCP e outro estado não controlado. Diagnostique primeiro, verifique uma cópia privada e use uma mudança de local reversível só na camada de instalação ou configuração efetivamente implicada. ### Não entre em pânico com um erro de UI num hook Antes de corrigir alguma coisa, verifique se o hook foi realmente executado (através de um registo em `stderr` ou de uma impressão explícita), em vez de confiar no indicador visual. ### Não aumente o código de saída de um hook antes de corrigir a lógica Quando o seu hook de bloqueio não bloqueia, é tentador definir `exit 2` e dar o problema por resolvido. É uma correção funcional, mas esconde outro problema: se o bloqueio não funcionou durante um mês, então passou tudo aquilo que o hook devia proibir. Primeiro, percorra o registo do git e descubra exatamente o que passou. Depois, acrescente o bloqueio. Um bloqueio agora ativo não desfaz o que aconteceu antes. ### Não edite o `CLAUDE.md` de produção sem uma salvaguarda do safe mode No caso descrito: edita o `CLAUDE.md`, o Claude começa a comportar-se de forma estranha, executa `git diff` e vê que alguém também acrescentou um servidor MCP e um hook ao repositório nessa noite. Culpa a sua edição, reverte-a e o Claude continua a comportar-se de forma estranha. Regra: antes de executar `git revert`, execute `claude --safe-mode`. Se o problema persistir no safe mode, a sua edição não teve nada que ver com ele; não é preciso revertê-la. ### Não acredite que «o Claude corrige o seu próprio MCP» Um cenário típico: pede ao Claude para «adicionar uma determinada ferramenta ao servidor MCP», o Claude reescreve a configuração funcional, tudo deixa de funcionar e, depois, o Claude passa vários turnos a depurar os estragos que causou — gastando entretanto a quota da sessão. Quando o MCP está avariado, **obtenha a configuração manualmente**; não deixe essa tarefa para o agente. Parte do arsenal de ferramentas do agente também funciona através do MCP e um MCP avariado significa um diagnóstico avariado. ## O que fazer depois de o corrigir?
Principais conclusões Depois de restaurar o Claude Code, acrescente medidas preventivas para que não volte a avariar. No mínimo: `disableBypassPermissionsMode: "disable"` nas definições do utilizador, hooks que bloqueiem `.env` e `git push --force` e uma sandbox para execuções autónomas longas. O guia de prevenção é o seu complemento.
Depois de analisar o incidente, não volte imediatamente ao trabalho. Primeiro, acrescente medidas preventivas para evitar que o incidente se repita. Pode perder horas num segundo cérebro (a pasta `business/` com a estrutura do projeto) e no `CLAUDE.md`, e é difícil restaurá-los manualmente — esse é um bom motivo. Conjunto mínimo: 1. **`~/.claude/settings.json`** com `permissions.disableBypassPermissionsMode: "disable"` — uma proibição arquitetónica do modo de contorno, para que `--dangerously-skip-permissions` não funcione se for iniciado por engano. 2. **Hooks para `Read(./env*)`, `Bash(git push --force)`, `Write(./node_modules/**)`** — ações que têm de ser travadas ao nível da lei, não do desejo. 3. **Configuração da sandbox para execuções autónomas longas** (`/loop`, `/schedule`). 4. **`/compact` com as suas próprias regras** sobre o que descartar do contexto, para que o Claude não se esgote. O esquema completo de proteção em quatro camadas está no [guia «Como configurar o Claude Code para não danificar o seu projeto durante a noite»](https://ailoot.ai/blog/pt-pt/claude-code-safe-overnight-setup/). Um guia aborda a prevenção antes de iniciar `/loop`; o outro trata da recuperação depois de `/loop` já ter causado danos. São um par lógico.
### Fontes - [Anthropic Claude Code Changelog](https://code.claude.com/docs/en/changelog) - changelog oficial que descreve a v2.1.166 (`fallbackModel`), a v2.1.169 (safe mode, /cd), a v2.1.174 (correção da compactação) e a v2.1.176 (correção do ramo git em /cd). - [Anthropic Docs - Model configuration](https://code.claude.com/docs/en/model-config) - secções «Fallback model chains», «Check what triggered fallback», «Setting your model». - [Anthropic Docs - Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install) - instalações em conflito, `claude doctor`, interceção de `ANTHROPIC_API_KEY`.
Materiais práticos: [documentação Ailoot](https://ailoot.ai/docs/). Mais materiais e ferramentas: [Ailoot](https://ailoot.ai/). ## Perguntas frequentes ### Uma falha em Safe Mode significa que devo eliminar ~/.claude? Não. Continuam por investigar instalação, autorização, rede e infraestrutura. Um doctor inconclusivo não prova que deva remover definições ou sessões; repare só a camada diagnosticada. ### O que preservo antes de reparar a instalação? Pare os escritores e copie o estado Claude completo, incluindo sessões, plugins/MCP, ficheiros ignorados e metadados. Verifique soma e extração antes de avançar, mantenha a conta e armazenamento de credenciais existentes e restaure só a camada diagnosticada sem sobrepor cegamente o estado atual. ## Ailoot · A empresa e a sua carteira de projetos A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI. A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões. A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.