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 próprio de direitos limitados, e mostramos o Gemini CLI (Google) como terceira opção. Todos os comandos foram testados num servidor root KVM da KernelHost com Debian 13 e Ubuntu 24.04. O que é, em termos gerais, um servidor gerido por IA e que arquiteturas existem é explicado no artigo Servidor gerido por IA: ligar agentes em segurança.

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

Pré-requisitos

• Um servidor root com Debian 12 ou 13, ou então Ubuntu 22.04 ou 24.04, e acesso root por SSH. Em AlmaLinux e Rocky Linux os passos são os mesmos; apenas os comandos de pacotes usam dnf em vez de apt.
• Proteção básica concluída: início de sessão SSH por chave, firewall, atualizações de segurança automáticas. A checklist para novos servidores root cobre tudo isto.
• Uma conta na Anthropic (Claude Pro, Max ou Team) ou uma chave API, e uma conta ChatGPT (Plus, Pro ou Team) ou uma chave API da OpenAI. Se só quiser configurar uma ferramenta, basta uma delas.
• 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.

Que servidor basta para um agente de IA?

Um agente de IA não precisa de hardware especial nem de GPU no servidor, porque o modelo de linguagem corre no fornecedor. No servidor correm apenas a ferramenta de linha de comandos e o Node.js, que, em conjunto, ocupam normalmente algumas centenas de megabytes de memória durante uma sessão. Num servidor em que pouco mais esteja a correr, bastam 2 vCPU e 4 GB de RAM. Se o servidor alojar também sites, bases de dados ou servidores de jogos, reserve cerca de 1 GB de memória para o agente. Um servidor root KVM da KernelHost fica disponível em cerca de 30 segundos, é faturado no modelo PrePaid, sem período mínimo, e serve por isso também como sistema de teste para experimentar primeiro o agente.

Passo 1: criar um utilizador próprio e limitar o sudo

O agente nunca corre como root. Recebe uma conta própria 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 realmente.

sudo adduser --disabled-password --gecos "KI-Agent" 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 esta verificação faz sempre parte do processo. --disabled-password garante que ninguém consegue iniciar sessão como aiagent com palavra-passe; mais tarde, muda para essa conta com sudo -iu aiagent. O artigo Criar um utilizador sudo no Linux explica como funcionam os utilizadores sudo em geral.

Direitos de escrita específicos em vez de um editor via sudo

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

O mesmo vale para comandos com wildcards na lista branca. /usr/bin/tail * permite ao agente ler qualquer ficheiro a que o root tenha acesso, incluindo ficheiros com credenciais de acesso. Quem não quiser isso escreve por extenso os caminhos permitidos, por exemplo /usr/bin/tail -n 200 /var/log/nginx/error.log.

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

Alternativa sem direitos de root: nvm

Quem não quiser executar scripts da internet com direitos de root usa o nvm na pasta pessoal do utilizador do agente; desta forma, tudo funciona sem quaisquer direitos de root. O comando de instalação do nvm deve ser copiado do README do projeto; depois bastam três linhas:

nvm install 22
nvm alias default 22
node --version

Os detalhes e outras formas de instalação estão no guia do Node.js no 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-no atualizado automaticamente. Em alternativa, a instalação também funciona através do npm com npm install -g @anthropic-ai/claude-code; se falhar com EACCES, consulte a secção de resolução de problemas mais abaixo.

Iniciar sessão num servidor sem navegador

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. A partir daí, o início de sessão mantém-se válido para este utilizador neste servidor até terminar a sessão.

Chave API para scripts e cron jobs

Para scripts e cron jobs, uma chave API é a escolha mais adequada:

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 os outros utilizadores não podem ler. Crie-a na consola da Anthropic com um limite de gastos mensal; dessa forma, uma sessão que fuja ao controlo não pode sair cara. Nunca escreva a própria chave numa tarefa para o agente nem num ficheiro cujo conteúdo ele deva mostrar.

Passo 4: configurar o Claude Code para o servidor

O ficheiro de regras CLAUDE.md

Ao arrancar, o Claude Code lê um ficheiro CLAUDE.md na pasta atual. Nele estão as regras que se aplicam a todas as sessões. 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).
- Os comandos de leitura (journalctl, systemctl status, tail, df, ss) são permitidos a qualquer momento.
- 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, apresentar um resumo em três frases.
EOF

O ficheiro vai crescendo. Sempre que o agente fizer algo de forma diferente da que pretende, a correção entra como nova regra. Ao fim de algumas semanas, reflete com bastante precisão a forma de trabalhar no seu servidor.

A lista branca em settings.json

A isto junta-se uma lista branca de ferramentas, para que o Claude Code execute comandos de leitura sem perguntar e peça autorizaçã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

A lista de bloqueio é uma rede de segurança adicional, não um muro: um comando pode ser escrito de muitas maneiras. O verdadeiro limite é a lista branca sudo do passo 1, porque aquilo que o utilizador não pode fazer, o agente também não pode.

A primeira tarefa em modo interativo

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.

Sem supervisão, através de um cron job

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

0 7 * * * cd /home/aiagent/server && /home/aiagent/.local/bin/claude -p "Resume os erros e avisos do journalctl das últimas 24 horas. Indica o serviço, a hora e a 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, e --allowedTools limita as ferramentas exatamente ao que a execução precisa. Ações de escrita não têm lugar em execuções sem supervisão. Como se configuram cron jobs em geral é explicado no artigo Configurar um cronjob no Linux.

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

Instalação e início de sessão

O Codex CLI é a ferramenta da OpenAI que traz os modelos por trás do ChatGPT para a linha de comandos. A instalação faz-se 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

Sandbox e modo de aprovação em config.toml

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, esta combinação faz sentido:

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, e on-request faz com que o agente peça autorização para tudo o que vá além disso. O nível danger-full-access anula ambas as restrições e não tem lugar num sistema de produção.

Regras em AGENTS.md

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 "Aufgabe", o equivalente ao claude -p.

Passo 6: Gemini CLI como terceira opção

O Gemini CLI é a ferramenta de linha de comandos da Google e funciona segundo o mesmo princípio. Também corre com Node.js e é instalado na mesma conta de utilizador:

npm install -g @google/gemini-cli
gemini --version

No primeiro arranque do gemini, inicia sessão com uma conta Google; para scripts, define uma chave API na variável de ambiente GEMINI_API_KEY. O Gemini CLI lê as regras de um ficheiro GEMINI.md na pasta de trabalho, e também aqui pode reutilizar o conteúdo do CLAUDE.md. As execuções sem supervisão iniciam-se com gemini -p "Aufgabe". A escolha entre as três ferramentas é sobretudo uma questão da conta que já tem: a forma de trabalhar no servidor é igual nas três, e pode utilizar várias lado a lado.

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 fica a regra de antepor ssh aiagent@server a todos os comandos do servidor. Isto funciona bem para manutenção ocasional, mas tarefas mais longas e cron jobs correm melhor diretamente no servidor. O relato prático Ligar a IA ao servidor mostra em pormenor como fica a ligação SSH com chave própria, alias de host e aprovações, e que processo o agente segue depois para fazer deploy em sistemas de produção.

Passo 7: proteger e definir limites

• Snapshot ou cópia de segurança antes de cada sessão em que algo deva ser alterado. A estratégia de backup 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 máquinas virtuais descartáveis.
• Segredos fora de alcance. O utilizador do agente não deve conseguir ler ficheiros .env, palavras-passe de bases de dados nem dados de clientes. O que ele lê é enviado ao fornecedor.
• Limite de custos para cada chave API, definido na consola do fornecedor.
• Rastreabilidade: instalar o etckeeper, para que cada alteração em /etc fique registada no Git, e guardar os resumos do agente.
• No tráfego de entrada, nada muda. Ambas as ferramentas só precisam de HTTPS de saída. A firewall, o Fail2ban e a proteção DDoS do fornecedor de alojamento mantêm-se inalterados.

As primeiras tarefas: cinco pedidos úteis

As melhores tarefas para começar são as que implicam muita leitura e nenhum risco. Mostram rapidamente o rigor com que o agente trabalha e trazem utilidade imediata:

• Relatório de registos: «Resume os erros e avisos das últimas 24 horas, agrupados por serviço, com a causa provável.»
• Verificar serviços: «Lista todos os serviços systemd que falharam, com a última mensagem de erro, e explica o que haveria a fazer em cada caso. Não alteres nada.»
• Espaço em disco: «Mostra que pastas ocupam mais espaço e sugere o que pode ser limpo sem risco.» Mais contexto no artigo Disco cheio no Linux.
• Atualizações: «Que pacotes têm atualizações de segurança pendentes e que serviços têm de ser reiniciados a seguir?»
• Servidor web: «Verifica a configuração do nginx quanto a erros e definições obsoletas e explica cada ocorrência.»

Só quando estas análises estiverem corretas vale a pena dar ao agente tarefas de escrita, e primeiro num sistema de teste.

Erros típicos e soluções

Manter as ferramentas atualizadas

Depois de instalado com o instalador nativo, o Claude Code atualiza-se sozinho. As ferramentas instaladas através do npm atualizam-se com um único comando:

npm update -g @openai/codex @google/gemini-cli
codex --version
gemini --version

As novas versões alteram ocasionalmente opções ou predefinições. Depois de uma atualização, leia rapidamente as notas de versão antes de deixar que as execuções sem supervisão continuem, e verifique se o próximo relatório diário apresenta alguma anomalia.

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 de forma generalizada. Num servidor root da KernelHost ou num servidor dedicado não é preciso ativar nada para isso: acesso root, livre escolha da distribuição e ligações de saída estão incluídos de série.

O relato prático Ligar a IA ao servidor descreve como um agente faz depois deploy em sistemas de produção, com cópia de segurança, reversão e aprovações.

Em resumo

• O Claude Code, o Codex CLI e o Gemini CLI correm em qualquer servidor Linux com Node.js 22; não é necessária GPU.
• O agente recebe um utilizador próprio com lista branca sudo e nunca corre como root.
• As regras ficam em CLAUDE.md, AGENTS.md ou GEMINI.md, os comandos de leitura entram na lista branca e tudo o resto precisa de aprovação.
• Para cron jobs e scripts, uma chave API com limite de gastos é o caminho mais limpo, e as execuções sem supervisão limitam-se a comandos de leitura.
• Cópia de segurança antes de cada sessão, segredos fora de alcance, modo de aprovação ligado.
• Nos servidores da KernelHost, o acesso root, a livre escolha da distribuição e as ligações de saída estão disponíveis de origem.