Solução de Problemas

O Contêiner Não Inicia

”Conflict. The container name is already in use”

Docker

docker rm -f devcontainer
docker compose up -d

Podman

podman rm -f devcontainer
podman-compose up -d

Ferramentas de IA Não Funcionam

”claude: command not found”

A imagem pode estar desatualizada. Baixe a versão mais recente e reinicie:

Docker

docker compose pull
docker compose up -d

Podman

podman-compose pull
podman-compose up -d

Claude mostra “Not logged in”

O entrypoint popula ~/.claude.json com flags de onboarding. Se estiver ausente:

echo '{"hasCompletedOnboarding": true}' > ~/.claude.json

Claude mostra “Invalid API key”

Verifique qual valor está realmente definido:

echo "$ANTHROPIC_API_KEY"

Causas comuns:

• Chave do proxy LiteLLM ausente ou inválida — se você está usando o modo proxy, certifique-se de que LITELLM_API_KEY no .env contém a credencial de proxy correta, depois reinicie o contêiner para que o entrypoint possa derivar ANTHROPIC_API_KEY.
• Token OAuth ou incompatibilidade de modo proxy — use exatamente um modo de autenticação. Se CLAUDE_CODE_OAUTH_TOKEN estiver definido, ele tem precedência sobre o modo proxy LiteLLM.

Requisições à API falham com 401

Verifique se sua chave de API está configurada corretamente:

echo "$ANTHROPIC_API_KEY"

Confirme que funciona fazendo uma chamada direta ao seu provedor.

Claude diz “model not found”

O modelo é determinado pelo seu provedor e chave de API. Consulte a documentação do seu provedor para ver os modelos disponíveis.

GitHub CLI

”gh: not authenticated”

O CLI gh requer uma variável de ambiente GH_TOKEN. Adicione-a ao seu arquivo .env:

GH_TOKEN=ghp_your-token-here

Crie um token em github.com/settings/tokens. Tokens refinados (recomendado) ou tokens clássicos com escopo repo funcionam. Reinicie o contêiner após atualizar o .env.

Clone HTTPS do git falha com 401

Quando GH_TOKEN está definido, o entrypoint executa gh auth setup-git para configurar o auxiliar de credenciais do git para HTTPS. Se operações HTTPS falharem:

1. Verifique se o token é válido: gh auth status
2. Verifique se o auxiliar de credenciais está configurado: git config --global credential.helper
3. Reinicie o contêiner para reexecutar o entrypoint

SSH vs HTTPS

Ambos os métodos de autenticação podem coexistir no contêiner:

• SSH (SSH_PRIVATE_KEY no .env) — usa URLs git@github.com:. Necessário se sua organização exige SSH.
• HTTPS (GH_TOKEN no .env) — usa URLs https://github.com/. Configuração mais simples, sem gerenciamento de chaves.

Se ambos estiverem configurados, o git usa o protocolo que corresponde à URL do remote. Para alternar um clone existente:

# SSH para HTTPS
git remote set-url origin https://github.com/owner/repo.git

# HTTPS para SSH
git remote set-url origin git@github.com:owner/repo.git

Problemas de Permissão

”Permission denied” em /workspace ou /home

sudo chown -R $(id -u):$(id -g) /workspace ~

npm install falha com EACCES

O entrypoint configura automaticamente um prefixo global do npm gravável pelo usuário em ~/.npm-global, então comandos npm install -g em tempo de execução devem funcionar sem sudo. Se você ainda encontrar erros EACCES, aplique a correção manualmente:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Problemas de Build

O build demora muito tempo

O primeiro build baixa a imagem base (~1 GB). Builds subsequentes usam cache. Se estiver lento toda vez:

Docker

docker builder prune

Podman

podman builder prune

“No space left on device”

Docker

docker system prune -a --volumes

Podman

podman system prune -a --volumes

Aviso: Isso remove todos os contêineres, imagens e volumes não utilizados — não apenas os deste projeto.

Rede

Não é possível acessar a internet de dentro do contêiner

ping -c 1 8.8.8.8
nslookup google.com
curl -I https://github.com

Docker

Se o DNS falhar, adicione ao /etc/docker/daemon.json no host:

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

Em seguida, reinicie o Docker.

Podman

Se o DNS falhar, configure o DNS dentro da máquina Podman:

podman machine ssh
sudo sh -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
exit

Ou adicione configurações de DNS ao ~/.config/containers/containers.conf no host:

[containers]
dns_servers = ["8.8.8.8", "8.8.4.4"]

Em seguida, reinicie o Podman: podman machine stop && podman machine start.

Exibição Remota (noVNC)

Tela preta no noVNC

O Xvfb pode não ter iniciado. Verifique dentro do contêiner:

ps aux | grep Xvfb

Se não estiver em execução, verifique se ENABLE_VNC não está definido como false e reinicie o contêiner.

Erro “Cannot open display” ou “No display”

A variável de ambiente DISPLAY pode não estar definida. Verifique:

echo "$DISPLAY"

Deve ser :99. Se estiver vazia, adicione DISPLAY=:99 ao seu .env ou devcontainer.json e reinicie.

Conexão recusada na porta 6080

O noVNC pode não estar em execução. Verifique dentro do contêiner:

ps aux | grep -E 'novnc|websockify'

Se não estiver em execução, verifique se ENABLE_VNC é true (o padrão) e confira os logs do contêiner:

Docker

docker compose logs dev | grep -i vnc

Podman

podman-compose logs dev | grep -i vnc

Porta 6080 já em uso

Altere a porta do host no docker-compose.yml:

ports:
  - "127.0.0.1:16080:6080"

Chrome DevTools MCP

Depuração remota do Chrome não responde

A instância compartilhada do Chrome deve estar em execução na porta 9222. Verifique dentro do contêiner:

# O Chrome está em execução?
curl http://localhost:9222/json/version

# Verificar logs do Chrome
cat ~/.local/share/chrome-browser/chrome.log

# Verificar o symlink
ls -la /opt/google/chrome/chrome

# Reiniciar o Chrome manualmente
. /usr/local/lib/chrome-browser.sh
start_chrome_browser

Se o symlink estiver ausente, baixe a imagem mais recente e reinicie o contêiner.

Erro de bloqueio de perfil do navegador

Com a arquitetura de navegador compartilhado, erros de bloqueio de perfil não devem ocorrer. Se você encontrar um, um processo do Chrome obsoleto pode estar mantendo o bloqueio:

# Encerrar quaisquer processos do Chrome obsoletos
pkill -f 'chrome.*remote-debugging-port' || true

# Remover o arquivo de bloqueio
rm -f ~/.cache/chrome-devtools-mcp/chrome-profile/SingletonLock

# Reiniciar o Chrome
. /usr/local/lib/chrome-browser.sh
start_chrome_browser

Ferramentas chrome-devtools-mcp duplicadas

O servidor chrome-devtools-mcp agora é registrado globalmente em ~/.claude/settings.json. Se você tem um .mcp.json por repositório que também o registra, verá ferramentas duplicadas. Remova a entrada chrome-devtools-mcp dos arquivos .mcp.json por repositório:

# Verificar configuração por repositório
cat .mcp.json

Remova a chave chrome-devtools-mcp de qualquer .mcp.json por repositório para usar o registro global.

Redefinir Tudo

Docker

docker compose down -v
docker rm -f devcontainer 2>/dev/null
docker compose pull
docker compose up -d

Podman

podman-compose down -v
podman rm -f devcontainer 2>/dev/null
podman-compose pull
podman-compose up -d

Isso destrói todos os dados nos volumes. Você precisará clonar repositórios novamente e reconfigurar as ferramentas.