Tutoriais de VPS
Implantação do Codex CLI em VPS (2026): instalação, login e execução permanente do ambiente de desenvolvimento remoto
Instale o Codex CLI em uma VPS Ubuntu/Debian, configure o login com ChatGPT ou API Key e monte um ambiente de desenvolvimento remoto recuperável usando um usuário comum e tmux.
Implantação do Codex CLI em VPS (2026): instalação, login e execução permanente do ambiente de desenvolvimento remoto
Se você já alugou uma VPS Linux e quer usá-la como uma máquina de desenvolvimento remota sempre online, o Codex CLI é um ponto de entrada muito prático: após entrar por SSH, você pode ler código, alterar arquivos e rodar testes diretamente no diretório do projeto. Os verdadeiros problemas não estão em npm install, mas em como autenticar em um ambiente sem desktop, como limitar permissões e como continuar depois que o processo se desconecta.
Este artigo usa Ubuntu 22.04/24.04 e Debian 12 como exemplos, partindo de uma VPS limpa até uma configuração do Codex CLI que possa ser usada a longo prazo. Todos os comandos podem ser copiados e executados, mas substitua a API Key, o caminho do projeto e o nome de usuário Linux pelos seus próprios valores.
O Codex CLI em si não precisa de uma CPU de alto desempenho; o consumo principal vem do Node.js, da indexação de código, dos comandos de teste e dos serviços que você executa ao mesmo tempo. Para projetos pessoais, comece com as seguintes configurações:
| Uso | Configuração recomendada | Observações |
|---|---|---|
| Scripts pequenos, sites estáticos | 2 núcleos / 2GB / 40GB SSD | Adequado para editar e rodar testes ao mesmo tempo |
| Projetos full-stack Node, Python | 2-4 núcleos / 4GB / 60GB NVMe | Deixa margem para instalação de dependências e builds |
| Projetos multi-repositório ou Docker | 4 núcleos / 8GB / 80GB NVMe | Mais estável ao rodar bancos de dados, testes e builds simultaneamente |
É possível instalar com apenas 1GB de memória, mas npm install, a compilação de TypeScript ou os builds do Docker podem facilmente acionar OOM. É melhor separar os serviços de produção do diretório de trabalho do Codex e, no mínimo, criar um usuário comum; não deixe o agente de codificação operar sempre no diretório root.
Entre por SSH e atualize o sistema:
ssh root@YOUR_SERVER_IP
apt update && apt full-upgrade -y
apt install -y ca-certificates curl git build-essential unzip tmux
Crie um usuário de trabalho:
adduser coder
usermod -aG sudo coder
mkdir -p /srv/workspaces
chown -R coder:coder /srv/workspaces
su - coder
Se você ainda não configurou chaves SSH, conclua primeiro o login por chave antes de desativar o login por senha. Ao solucionar problemas de Permission denied, consulte a lista de verificação para solucionar VPS SSH Permission denied. Não exponha a porta 22 a todas as origens sem nenhuma restrição antes de concluir a implantação do Codex.
O Codex CLI oferece suporte oficial à instalação via npm. Em uma VPS de produção, não é recomendado usar o Node.js antigo incluído na distribuição; instale primeiro a versão LTS do NodeSource:
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
node --version
npm --version
Depois de confirmar que a versão do Node.js atende aos requisitos do projeto, instale o Codex:
sudo npm install --global @openai/codex
codex --version
Atualizar também é simples:
sudo npm update --global @openai/codex
Se o sistema proibir gravações globais do npm, você pode usar o nvm para instalar o Node.js e depois executar a instalação global como o usuário coder. Não altere todo o diretório /usr para 777 só por conveniência.
O Codex CLI oferece suporte a login com ChatGPT e login com API Key. Ao executar codex login em um computador com desktop, uma página de autorização é aberta no navegador; uma VPS puramente SSH normalmente não tem navegador, então uma API Key é mais adequada para automação ou máquinas remotas.
Execute o seguinte no diretório do projeto na VPS:
mkdir -p /srv/workspaces/demo && cd /srv/workspaces/demo
codex login
Se o terminal fornecer uma URL de autorização, abra-a no navegador do seu computador local, conclua o login e volte para a sessão SSH. Versões diferentes da CLI podem exibir instruções ligeiramente diferentes; basta seguir as orientações do terminal. Você pode verificar o status do login com:
codex login status
Não escreva a API Key diretamente no histórico do shell. Passe-a para a CLI via entrada padrão usando uma variável de ambiente protegida:
read -s OPENAI_API_KEY
printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
unset OPENAI_API_KEY
codex login status
Se precisar usá-la para systemd ou CI, coloque a Key em um arquivo de credenciais legível apenas por coder:
mkdir -p /home/coder/.config
install -m 600 /dev/null /home/coder/.config/codex.env
printf 'OPENAI_API_KEY=replace-me\n' > /home/coder/.config/codex.env
Não faça commit de .config/codex.env no Git, nem coloque a Key em ~/.bashrc para depois tirar capturas de tela ou colar em tickets. O login com API Key é cobrado pelo uso da API e é adequado para scripts e integração contínua; o login com ChatGPT usa as permissões e a cota do workspace do ChatGPT correspondente. Para o comportamento específico de autenticação, consulte a documentação do Codex CLI no OpenAI Docs e Authentication.
Alterne para o repositório de código:
cd /srv/workspaces/demo
git clone YOUR_REPOSITORY_URL .
git status
codex
Na primeira conversa, recomenda-se pedir primeiro ao Codex uma inspeção somente leitura do projeto e depois permitir alterações:
先阅读项目结构和 README，只告诉我启动命令，不要修改文件。
Depois de confirmar o diretório de trabalho, proponha uma alteração pequena e solicite a execução dos testes. Quanto menores as permissões do workspace, melhor: não coloque /etc, diretórios de backup de banco de dados ou diretórios de credenciais do provedor de nuvem no diretório de trabalho do Codex. Em projetos de produção, crie primeiro uma branch do Git ou confirme um checkpoint para poder reverter.
Se você executar codex diretamente, o processo normalmente também termina quando o SSH se desconecta. A forma mais simples é usar o tmux:
tmux new -s codex
cd /srv/workspaces/demo
codex
Pressione Ctrl+b e depois d para sair da sessão mantendo o processo em execução; após entrar novamente, restaure-a:
tmux attach -t codex
Ver as sessões existentes:
tmux ls
tmux é adequado para operação manual; não é recomendado transformar um agente de codificação interativo que exige confirmação de permissões em um serviço de inicialização não assistido. Só considere o systemd se estiver executando um script fixo codex exec, e configure para o serviço um usuário dedicado, diretório de trabalho, limites de recursos e credenciais somente leitura.
Normalmente é porque o diretório global do npm não está no PATH. Localize-o primeiro:
npm prefix --global
which node
which npm
Ao instalar globalmente com sudo, confirme que /usr/bin ou o diretório bin do npm está no PATH do usuário atual; se usar nvm, recarregue a configuração do shell correspondente.
Verifique o proprietário do repositório e as permissões do diretório:
whoami
ls -ld /srv/workspaces/demo
sudo chown -R coder:coder /srv/workspaces/demo
Não use chmod -R 777 para resolver problemas de permissão; isso exporia o código-fonte, .env e a configuração de SSH a outros usuários na mesma máquina.
Primeiro verifique a memória e os logs de OOM:
free -h
dmesg -T | grep -i -E 'oom|killed process'
Uma VPS de 2GB pode adicionar temporariamente 2GB de swap, mas o swap não substitui a memória real. Quando há muitas tarefas de build, atualizar para 4GB economiza mais tempo do que repetir tentativas.
Confirme que o mesmo usuário Linux é usado para fazer login e executar o Codex, e verifique o status:
whoami
codex login status
Não faça login com a Key como root e depois alterne para o usuário coder para executar; os diretórios de credenciais dos dois usuários são diferentes.
node --versionecodex --versionretornam normalmente;- O usuário
coderpode ler e gravar no projeto, mas não tem permissões desnecessárias em diretórios do sistema; - O login com ChatGPT ou com API Key foi escolhido e pode ser verificado via
codex login status; - As permissões do arquivo de API Key são
600e ele foi adicionado a.gitignore; - As sessões interativas são executadas no tmux e podem ser restauradas após a desconexão do SSH;
- Há uma branch ou commit do Git antes das alterações, e os comandos de teste e o caminho de reversão estão claros;
- Projetos Docker têm healthchecks, logs e limites de recursos configurados separadamente; você pode continuar consultando a lista de verificação de configuração de produção do VPS Docker Compose.
O ponto central de executar o Codex CLI em uma VPS não é quão luxuosa é a configuração da máquina, mas sim fazer bem a autenticação, as permissões de usuário e a persistência de sessões. Um projeto pequeno pode começar com 2 núcleos e 2GB; se precisar executar Docker, bancos de dados e tarefas de build ao mesmo tempo, escolha diretamente 4 núcleos e 8GB para gastar menos tempo solucionando OOM.