Um site devolve um erro 502. Em vez de copiar registos para um chatbot, pede a um agente de IA no servidor que inspecione os ficheiros relevantes e explique o problema. Esta é uma utilização prática do Codex CLI num VPS Linux.
Este guia abrange a instalação, o início de sessão a partir de uma sessão SSH e uma primeira tarefa com permissões restritas. Depois, explicamos o teste real por trás do nosso vídeo: o Codex identificou uma incompatibilidade de portas num site de demonstração deliberadamente avariado.
O que corre onde: o agente Codex e as suas ferramentas de linha de comandos correm no seu VPS. Com a configuração da OpenAI aqui descrita, o modelo de IA corre na cloud da OpenAI. Precisa da sua própria conta ChatGPT elegível ou de acesso à API da OpenAI faturado separadamente. Um VPS da SharpHeberg não inclui esse acesso.
Antes de começar
- Um VPS Linux a que possa aceder por SSH, com acesso HTTPS de saída. Os comandos de pacotes abaixo destinam-se a Debian e Ubuntu.
- Um utilizador Linux normal com sudo disponível para instalar pacotes do sistema. Execute o Codex com esse utilizador, e não como root.
- Uma conta OpenAI com acesso ao Codex. Verifique a disponibilidade e os limites atuais do seu plano; a faturação da API é independente de uma subscrição do ChatGPT.
- Um projeto de teste ou um ambiente de staging. Mantenha credenciais de produção e ficheiros de clientes não relacionados fora da conta e da área de trabalho acessíveis ao agente.
Não precisa de alojar os pesos do modelo nem de provisionar uma GPU para este fluxo de trabalho baseado na cloud. Os recursos que os seus projetos, ferramentas de build e serviços consomem continuam a ser importantes na escolha de um VPS.
Âmbito da validação: a nossa demonstração de diagnóstico correu num VPS Debian 12 descartável com o Codex CLI 0.164.0. Essa experiência isolada utilizou uma conta de diagnóstico privilegiada; não é a configuração de conta que recomendamos para produção. Verificámos também o instalador autónomo oficial num diretório de instalação Linux x86-64 isolado e confirmámos a versão do CLI e as opções de login/sandbox. Não testámos todas as versões do Ubuntu nem todas as configurações de VPS.
1. Ligue-se ao seu VPS
A partir do seu próprio computador, ligue-se com a sua conta SSH não-root existente. Substitua o utilizador e o endereço de exemplo:
ssh youruser@YOUR_VPS_IP
Se o seu servidor só tiver uma conta root, crie e verifique primeiro uma conta separada seguindo as instruções de administração do seu sistema operativo. Não deve dar a um agente de IA uma shell root só para começar.
No Debian ou no Ubuntu, instale as ferramentas de download e de projeto utilizadas neste guia:
sudo apt update
sudo apt install ca-certificates curl git less
Estes comandos instalam pacotes do sistema; não atualizam todo o servidor nem alteram a sua firewall.
2. Instale o Codex CLI
A OpenAI documenta um instalador autónomo para macOS e Linux, bem como alternativas com npm e Homebrew. A via autónoma não exige que instale primeiro o Node.js e o npm. Consulte o guia oficial de instalação do Codex CLI.
Descarregue o instalador para o seu próprio diretório, para o poder inspecionar antes de o executar:
mkdir -p "$HOME/codex-setup"
curl -fsSL https://chatgpt.com/codex/install.sh -o "$HOME/codex-setup/install.sh"
less "$HOME/codex-setup/install.sh"
Prima q para sair do less. Depois de rever o script, execute-o com o seu utilizador normal:
sh "$HOME/codex-setup/install.sh"
export PATH="$HOME/.local/bin:$PATH"
codex --version
codex --help
O instalador oficial usa por predefinição ~/.local/bin e gere o seu pacote autónomo no diretório de utilizador do Codex. Pode atualizar o ficheiro de arranque da sua shell. Volte a abrir o terminal quando lhe for pedido; o export acima também disponibiliza o local de instalação predefinido na sessão atual.
Se o URL de download curto falhar: o código do instalador também está disponível no repositório oficial do OpenAI Codex. Descarregue esse código, inspecione-o e depois siga os mesmos passos de instalação:
curl -fsSL https://raw.githubusercontent.com/openai/codex/main/scripts/install/install.sh -o "$HOME/codex-setup/install.sh"
less "$HOME/codex-setup/install.sh"
sh "$HOME/codex-setup/install.sh"
Não o substitua por um script de um mirror desconhecido. Se o próprio download do binário falhar, a OpenAI documenta CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false para selecionar as GitHub Releases:
CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh "$HOME/codex-setup/install.sh"
Se já gere uma instalação suportada de Node.js/npm, a alternativa npm documentada é npm install -g @openai/codex. Escolha um único método de instalação em vez de misturar vários e depois não saber qual o codex que está no seu PATH.
3. Inicie sessão a partir de um servidor sem interface gráfica
O seu VPS normalmente não tem um navegador de desktop. A OpenAI recomenda a autenticação por código de dispositivo para esta situação:
codex login --device-auth
Siga a ligação apresentada no terminal, no seu próprio computador ou telemóvel, inicie sessão e introduza o código de utilização única. Pode ser necessário ativar primeiro o início de sessão por código de dispositivo nas definições de segurança do seu ChatGPT, ou pedir ao administrador do seu espaço de trabalho que o permita. Nunca envie esse código a outra pessoa.
Depois, verifique o método de autenticação:
codex login status
Se o início de sessão por código de dispositivo não estiver disponível, a OpenAI documenta também um túnel SSH para o fluxo normal de início de sessão no navegador. Inicie esta ligação a partir do seu computador:
ssh -L 1455:localhost:1455 youruser@YOUR_VPS_IP
Dentro dessa sessão SSH, execute codex login e abra a respetiva ligação de início de sessão no seu navegador local. Isto reencaminha o callback de localhost sem expor publicamente uma porta de autenticação. Consulte as instruções de início de sessão sem interface gráfica da OpenAI se o seu ambiente utilizar uma configuração de callback diferente.
Utilizar uma chave de API em alternativa
Se preferir o acesso à API com faturação por utilização, disponibilize a sua própria chave de API da OpenAI de forma segura como variável de ambiente e passe-a pela entrada padrão:
printenv OPENAI_API_KEY | codex login --with-api-key
Não cole uma chave de API literal num comando guardado no histórico da shell. A utilização da API é faturada através da sua conta OpenAI Platform e não é deduzida da fatura do seu alojamento VPS. Trate as credenciais guardadas pelo Codex como palavras-passe e mantenha-as fora de repositórios, capturas de ecrã e tickets de suporte. O guia oficial de autenticação explica ambos os métodos.
4. Comece com uma tarefa só de leitura
Entre num projeto de teste cujos ficheiros compreenda. Se não tiver nenhum, um diretório vazio é suficiente para abrir o CLI e inspecionar a interface:
mkdir -p "$HOME/codex-first-session"
cd "$HOME/codex-first-session"
codex --sandbox read-only --ask-for-approval on-request
Num repositório de teste real, um bom primeiro prompt é:
Explica como este projeto arranca. Lê os ficheiros de configuração e o README relevantes, identifica o ponto de entrada e lista tudo o que não consegues verificar. Não alteres ficheiros nem instales pacotes.
O read-only restringe os comandos gerados pelo modelo através do sandbox configurado. O on-request permite que o modelo peça aprovação adicional; não significa que todos os comandos exijam automaticamente uma confirmação. Leia qualquer pedido de escalada de privilégios antes de decidir se o permite.
Um prompt que diga “não alteres nada” não é, por si só, uma fronteira de segurança. Utilize uma conta e um ambiente de teste dedicados, limite os dados acessíveis e verifique as permissões apresentadas pela versão que instalou. O acesso só de leitura pode, mesmo assim, expor ao serviço do modelo o conteúdo de ficheiros legíveis.
Consulte codex --help e a referência de comandos do CLI antes de copiar flags de um tutorial mais antigo. Evite contornar o sandbox ou as aprovações para resolver um erro de instalação.
5. Passe de uma explicação a uma tarefa útil no servidor
Um passo seguinte sensato é dar ao Codex um âmbito de diagnóstico pequeno e explícito. Prepare cópias higienizadas dos registos e da configuração relevantes num diretório de teste e depois peça:
Este site de demonstração devolve HTTP 502. Inspeciona apenas a configuração do nginx, o ponto de entrada da aplicação e o registo de erros fornecidos. Explica a causa e propõe a correção mais pequena possível. Não edites ficheiros, não instales pacotes nem reinicies serviços.
Reveja a alteração proposta antes de a aplicar você próprio. Num serviço real, faça uma cópia de segurança da configuração, valide-a com a verificação do próprio serviço e prepare uma reversão. Uma explicação de IA não é prova de que uma alteração seja segura para produção.
O que aconteceu na nossa demonstração
Configurámos deliberadamente mal um site de demonstração num VPS descartável. O Nginx reencaminhava os pedidos para a porta 3000, enquanto a aplicação escutava na 3001. O site devolvia HTTP 502.
O Codex inspecionou a configuração, a aplicação e o registo de erros selecionados em modo só de leitura. Identificou a incompatibilidade e propôs uma correção de uma linha em aproximadamente 22 segundos, sem editar os ficheiros fornecidos. O nosso operador de produção aplicou essa proposta, verificou a configuração do nginx, recarregou o serviço e confirmou uma resposta HTTP 200.
Foi um único teste controlado, com uma falha conhecida e introduzida deliberadamente. Não é um benchmark, uma garantia de tempo de reparação nem uma demonstração de recuperação autónoma em produção.
Se algo não funcionar
codex: command not found: volte a abrir o terminal, verifiquecommand -v codexe confirme que o diretório do instalador está no seu PATH.- O URL do instalador ou o download está bloqueado: utilize o código do repositório oficial e a seleção de GitHub Releases documentada acima. Não desative a verificação TLS.
- O início de sessão não consegue abrir um navegador: utilize o início de sessão por código de dispositivo ou o túnel SSH documentado. Não publique portas de autenticação localhost.
- Atingiu um limite de utilização: verifique a conta e o método de autenticação apresentados por
codex login status. Instalar o CLI ou comprar um VPS não elimina os limites de utilização da OpenAI. - Erros de sandbox ou de auxiliares: mantenha a instalação oficial completa e verifique o suporte da sua distribuição para os mecanismos de isolamento necessários. Um contentor ou um VPS restrito pode ter limitações adicionais. Não resolva isto executando o Codex como root nem desativando as suas salvaguardas.
Veja a demonstração e experimente depois no seu próprio VPS
O nosso vídeo acompanha o exemplo de diagnóstico, desde o site avariado até à resposta verificada. Demonstra o que o agente instalado o pode ajudar a investigar; os comandos de instalação estão neste guia.
Demonstração controlada num VPS de teste descartável: o Codex propõe a correção; o nosso operador aplica-a e verifica-a. Veja a demonstração no YouTube.
Comece com um projeto de teste, mantenha as permissões do agente restritas e verifique cada resultado. Se precisar de um servidor para esse espaço de trabalho, explore os planos VPS Linux da SharpHeberg. A sua conta OpenAI e a respetiva utilização continuam separadas do serviço de alojamento.