Instalar o Claude Code e o ChatGPT Codex num servidor Linux: passo a passo

Este guia leva-o de um servidor Debian ou Ubuntu acabado de instalar a um agente de IA operacional que analisa registos, verifica configurações e executa tarefas de manutenção. Configuramos o Claude Code (Anthropic) e o Codex CLI (OpenAI, a ferramenta de linha de comandos por trás do ChatGPT), ambos com um utilizador dedicado de direitos limitados. Todos os comandos foram testados num servidor root KVM da KernelHost com Debian 13 e Ubuntu 24.04. O que é um servidor gerido por IA em geral e que arquiteturas existem está explicado no artigo Servidor gerido por IA: ligar agentes em segurança.

Estado em setembro de 2026. As ferramentas evoluem depressa; em caso de dúvida, verifique as opções com claude --help ou codex --help.

Pré-requisitos

• Um servidor root com Debian 12 ou 13 ou Ubuntu 22.04 ou 24.04 e acesso root por SSH. Em AlmaLinux e Rocky Linux os passos são iguais, só que os comandos de pacotes se chamam dnf em vez de apt.
• Proteção básica feita: início de sessão SSH por chave, firewall, atualizações de segurança automáticas. A lista de verificação para novos servidores root cobre isso.
• Uma conta na Anthropic (Claude Pro, Max ou Team) ou uma chave API, uma conta ChatGPT (Plus, Pro ou Team) ou uma chave API da OpenAI. Basta uma delas se só quiser configurar uma ferramenta.
• HTTPS de saída para api.anthropic.com e api.openai.com. Nos servidores da KernelHost é assim de origem; uma firewall própria restritiva tem de o permitir.

Passo 1: criar um utilizador dedicado e limitar o sudo

O agente nunca corre como root. Recebe a sua própria conta e, através de uma lista branca sudo, exatamente os comandos de que precisa. Comece com poucos comandos de leitura e alargue a lista quando uma tarefa o exigir mesmo.

sudo adduser --disabled-password --gecos "Agente IA" aiagent
sudo tee /etc/sudoers.d/aiagent >/dev/null <<'EOF'
aiagent ALL=(root) NOPASSWD: /usr/bin/journalctl *, /usr/bin/systemctl status *, /usr/bin/systemctl restart nginx, /usr/bin/apt-get update, /usr/bin/apt-get upgrade -y, /usr/bin/tail *, /usr/bin/df *, /usr/bin/ss *
EOF
sudo chmod 440 /etc/sudoers.d/aiagent
sudo visudo -cf /etc/sudoers.d/aiagent

A última linha verifica a sintaxe. Um erro num ficheiro sudoers pode bloquear o sudo para toda a gente, por isso a verificação faz sempre parte. --disabled-password garante que ninguém pode iniciar sessão como aiagent com palavra-passe; mais tarde mudará para a conta com sudo -iu aiagent.

Se o agente tiver de alterar ficheiros em /etc, não lhe autorize o nano via sudo (isso permitiria editar qualquer ficheiro, incluindo /etc/sudoers), mas trabalhe com um grupo e direitos de escrita específicos, por exemplo setfacl -m u:aiagent:rw /etc/nginx/sites-available/o-meu-site.conf. Para começar, chega perfeitamente que o agente proponha as alterações e que seja você a aplicá-las.

Passo 2: instalar o Node.js 22

Ambas as ferramentas correm com Node.js. O Claude Code exige pelo menos a versão 18, o Codex CLI pelo menos a 22, por isso instalamos a 22 LTS. Os repositórios do Debian 12 fornecem uma versão demasiado antiga; o NodeSource fornece a atual:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version
npm --version

Quem não quiser executar scripts da internet com direitos de root usa o nvm na pasta pessoal do utilizador do agente; assim é possível completamente sem direitos de root. Detalhes e alternativas no guia do Node.js em Debian.

Passo 3: instalar o Claude Code e iniciar sessão

A partir daqui trabalhamos na conta do agente:

sudo -iu aiagent
curl -fsSL https://claude.ai/install.sh | bash
claude --version

O instalador nativo coloca o Claude Code em ~/.local/bin e mantém-se atualizado sozinho. Em alternativa funciona o npm com npm install -g @anthropic-ai/claude-code; se falhar com EACCES, a secção de resolução de problemas mais abaixo ajuda.

No primeiro arranque do claude, a ferramenta pede o início de sessão. Com uma conta Claude abre normalmente o navegador; num servidor sem navegador mostra um endereço e um código que confirma no portátil ou no smartphone. Para scripts e cron jobs, uma chave API é a melhor escolha:

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
chmod 600 ~/.bashrc
source ~/.bashrc
claude -p "Responde apenas com OK" 

A chave fica assim apenas na pasta pessoal do utilizador do agente, que outros utilizadores não podem ler. Crie-a na consola da Anthropic com um limite de gastos mensal; assim uma sessão que descarrile não pode sair cara.

Passo 4: configurar o Claude Code para o servidor

Ao arrancar, o Claude Code lê um ficheiro CLAUDE.md na pasta atual. Nele estão as regras válidas para cada sessão. Crie na pasta pessoal do agente uma pasta de trabalho com este ficheiro:

mkdir -p ~/server && cd ~/server
cat > CLAUDE.md <<'EOF'
# Regras para este servidor
- Este é um servidor de produção (Debian 13, nginx, PHP-FPM, MariaDB).
- Comandos de leitura (journalctl, systemctl status, tail, df, ss) são sempre permitidos.
- Antes de cada comando de escrita, explicar brevemente o que altera e aguardar aprovação.
- Nunca remover pacotes, nunca apagar ficheiros em /var/lib, nunca criar nem eliminar utilizadores.
- Nunca repetir palavras-passe, chaves ou dados de clientes nas saídas.
- No fim de cada tarefa, entregar um resumo em três frases.
EOF

A isto junta-se uma lista branca de ferramentas, para que o Claude Code execute comandos de leitura sem perguntar e peça aprovação para tudo o resto. O ficheiro ~/.claude/settings.json aplica-se ao utilizador:

mkdir -p ~/.claude
cat > ~/.claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Bash(sudo journalctl:*)",
      "Bash(sudo systemctl status:*)",
      "Bash(sudo tail:*)",
      "Bash(df:*)",
      "Bash(free:*)",
      "Bash(ss:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo rm:*)",
      "Bash(dd:*)",
      "Bash(mkfs:*)"
    ]
  }
}
EOF

Agora a primeira tarefa, de forma interativa:

cd ~/server && claude
> Resume os erros do journalctl das últimas 24 horas e indica as três causas mais frequentes.

E a mesma tarefa sem supervisão, por exemplo como cron job diário às 7 cujo resultado chega por e-mail:

0 7 * * * cd /home/aiagent/server && /home/aiagent/.local/bin/claude -p "Resume erros e avisos do journalctl das últimas 24 horas. Indica serviço, hora e causa provável." --allowedTools "Bash(sudo journalctl:*)" 2>&1 | mail -s "Relatório diário do servidor" admin@example.com

A opção -p inicia o Claude Code sem sessão interativa, --allowedTools limita as ferramentas exatamente ao que a execução precisa. Ações de escrita não pertencem a execuções sem supervisão.

Passo 5: instalar o Codex CLI (ChatGPT) e iniciar sessão

O Codex CLI é a ferramenta da OpenAI que traz os modelos por trás do ChatGPT para a linha de comandos. Instalação na mesma conta de utilizador:

npm install -g @openai/codex
codex --version

O início de sessão faz-se com a conta ChatGPT (Plus, Pro ou Team): iniciar o codex, escolher «Sign in with ChatGPT» e abrir o endereço apresentado num dispositivo com navegador. Para scripts, defina em vez disso uma chave API da plataforma OpenAI:

echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc
source ~/.bashrc

O Codex traz a sua própria sandbox e um modo de aprovação. Ambos se definem em ~/.codex/config.toml; para um servidor de produção faz sentido esta combinação:

mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
approval_policy = "on-request"
sandbox_mode = "workspace-write"
EOF

workspace-write só permite escrever na pasta de trabalho atual, on-request faz o agente pedir autorização para tudo o que vá além disso. O nível danger-full-access anula ambos e não pertence a um sistema de produção. O Codex lê regras como as do CLAUDE.md a partir de um ficheiro AGENTS.md na pasta de trabalho; pode usar o mesmo conteúdo:

cp ~/server/CLAUDE.md ~/server/AGENTS.md
cd ~/server && codex "Verifica se todos os serviços systemd ativados estão a correr e lista os que falharam com a última mensagem de erro."

Para execuções sem supervisão existe codex exec "tarefa", o equivalente ao claude -p.

Alternativa: o agente corre no seu computador e trabalha por SSH

Quem não quiser instalar nada no servidor inicia o Claude Code ou o Codex no portátil e deixa o agente enviar comandos por SSH. Para isso o servidor recebe uma chave SSH própria do utilizador do agente, e no CLAUDE.md consta a regra de antepor ssh aiagent@servidor a todos os comandos do servidor. Funciona bem para manutenção ocasional, mas tarefas longas e cron jobs correm melhor diretamente no servidor.

Passo 6: proteger e definir limites

• Snapshot ou cópia de segurança antes de cada sessão em que algo deva mudar. A estratégia de cópias de segurança para servidores mostra como automatizar isso.
• Manter o modo de aprovação ligado. --dangerously-skip-permissions no Claude Code e danger-full-access no Codex destinam-se a VM descartáveis.
• Segredos fora de alcance. O utilizador do agente não pode conseguir ler ficheiros .env, palavras-passe de bases de dados e dados de clientes. O que lê vai para o fornecedor.
• Limite de custo para cada chave API na consola do fornecedor.
• Rastreabilidade: instalar o etckeeper para que cada alteração em /etc vá para o Git, e guardar os resumos do agente.
• À entrada nada muda. Ambas as ferramentas só precisam de HTTPS de saída. Firewall, Fail2ban e a proteção DDoS do fornecedor de alojamento mantêm-se inalterados.

Erros típicos e soluções

Conclusão

Um agente de IA no servidor configura-se numa hora: utilizador, lista branca sudo, Node.js, ferramenta, regras. O verdadeiro trabalho está nos limites, e aqui são propositadamente apertados. Alargue-os passo a passo quando uma tarefa o exigir, nunca em bloco. Num servidor root da KernelHost ou num servidor dedicado não há nada a ativar para isso: acesso root, livre escolha da distribuição e ligações de saída são o padrão.