O gateway do Chatcode
O que é o gateway do Chatcode, onde corre (Linux ou macOS), como comunica com o Chatcode, que confiança exige e porque é que o macOS pede permissões.
O gateway é o pequeno programa que põe o Chatcode a funcionar numa máquina sua. Executa os seus agentes de programação — Claude Code, Codex, Gemini, OpenCode — e liga-os ao browser em app.chatcode.dev e ao Telegram, sem expor na sua máquina nada que aceite ligações de entrada.
Esta página explica o que é, onde fica, como comunica com o Chatcode e, em termos simples, as contrapartidas em matéria de confiança — incluindo o motivo pelo qual o macOS mostra por vezes pedidos de permissão com um aspeto alarmante (em resumo: é o seu agente a fazer o que lhe pediu).
O que é o gateway
- Um único binário,
chatcode-gateway(compilado para cada plataforma: Linux/macOS × Intel/ARM), instalado como serviço em segundo plano. - Mantém uma única ligação de saída ao plano de controlo do Chatcode e executa as sessões dos seus agentes em espaços de trabalho
tmuxdentro de~/workspace. - Corresponde à caixa «O seu servidor + gateway» na arquitetura do Chatcode: browser ⇄ Chatcode ⇄ o seu gateway ⇄ sessão do agente.
- O binário de cada versão é transferido por HTTPS e a sua soma de verificação (SHA-256) é confirmada antes de ser instalado.
Onde corre: Linux ou macOS
O gateway segue dois modelos diferentes consoante o sistema operativo — e esta é, na prática, a maior diferença.
Linux — um utilizador dedicado vibe (isolado)
Usado pelos droplets da DigitalOcean do modo fácil e pelos seus próprios servidores Linux. O instalador corre como root e:
- Cria um utilizador dedicado
vibe— os agentes correm comovibe, e não com a conta com que inicia sessão na máquina — com o espaço de trabalho em/home/vibe/workspace. - Instala um serviço systemd (
chatcode-gateway.service) que corre comovibe. - Instala ferramentas de base, incluindo
tmux,git,ripgrepebubblewrap(para isolar as sessões dos agentes numa sandbox). - Pré-instala o Claude Code e o Codex e ativa um temporizador de manutenção diário que atualiza as CLIs dos agentes e o próprio gateway.
Como os agentes correm com um utilizador próprio, ficam isolados da sua conta pessoal e dos seus ficheiros nessa máquina.
macOS — o seu próprio utilizador
Usado quando liga o seu próprio Mac. O instalador corre com o seu utilizador normal (nunca com sudo) e:
- Instala o binário em
~/.local/bin/chatcode-gatewaye um agente launchd (dev.chatcode.gateway) que arranca quando inicia sessão e se mantém em execução (nos Macs de secretária, o computador é mantido acordado comcaffeinate). - Requer o Homebrew, além de
tmux,gitecurl.
Aqui, o agente corre com o seu utilizador, pelo que tem exatamente o mesmo acesso a ficheiros que a sua conta. É cómodo — e é o motivo pelo qual o macOS mostra os pedidos de permissão descritos mais abaixo.
Onde fica cada coisa
| Linux (gerido) | macOS (o seu utilizador) | |
|---|---|---|
| Binário | /usr/local/bin/chatcode-gateway |
~/.local/bin/chatcode-gateway |
| Serviço | systemd chatcode-gateway.service |
launchd dev.chatcode.gateway |
| Configuração/ambiente | /etc/chatcode/gateway.env (modo 600) |
~/.config/chatcode/gateway.env (modo 600) |
| Corre como | utilizador dedicado vibe |
o utilizador com que inicia sessão |
| Espaço de trabalho | /home/vibe/workspace |
~/workspace |
| Registos | journalctl -u chatcode-gateway |
~/Library/Logs/chatcode-gateway.log |
Instalação
Na aplicação, adicione um servidor e o Chatcode dá-lhe um comando pronto a executar, já preenchido com o ID do gateway, o token de autenticação e o URL do plano de controlo. O comando passa à sua shell o instalador oficial em https://chatcode.dev/install.sh (que redireciona para a versão mais recente):
# Linux — run as root (installs under a dedicated `vibe` user)
curl -fsSL https://chatcode.dev/install.sh | sudo bash -s -- \
--gateway-id gw_xxx --gateway-auth-token tok_xxx \
--cp-url wss://<control-plane>/gw/connect
# macOS — run as your normal user (do NOT use sudo)
curl -fsSL https://chatcode.dev/install.sh | bash -s -- \
--gateway-id gw_xxx --gateway-auth-token tok_xxx \
--cp-url wss://<control-plane>/gw/connect
O instalador obtém o binário do gateway em releases.chatcode.dev e confirma a respetiva soma de verificação SHA-256 antes de o instalar. Pode fixar uma versão (--version vX.Y.Z) em vez de acompanhar a latest, ou compilar o binário por conta própria e instalá-lo com --binary-source /path/to/chatcode-gateway.
Sudo sem palavra-passe (e como se mantém transparente)
Quando um agente que está a utilizar precisa de executar uma ação de administração — instalar um pacote, reiniciar um serviço —, não pode parar e pedir-lhe uma palavra-passe através do Telegram. Por isso, o gateway está preparado para tarefas de administração sem supervisão:
- Linux: o utilizador
vibetem sudoNOPASSWD, mas cada comando fica gravado (use_pty) num registo pertencente ao root e só de acréscimo (append-only), em/var/log/chatcode/sudo-vibe.log, que ovibepode ler mas não alterar, com rotação ao longo de 14 dias. Pode auditar exatamente o que foi executado. - macOS: o sudo sem palavra-passe é opcional e só é proposto se o aceitar durante a instalação. Se o recusar, o gateway continua a funcionar; apenas lhe será pedida a palavra-passe (ou as tarefas de administração não serão executadas), como em qualquer Mac normal.
Trata-se de uma contrapartida deliberada para que tudo «funcione enquanto está ausente», tornada auditável em vez de escondida.
Pedidos de permissão do macOS: não entre em pânico
Se executar o gateway no seu Mac, é provável que veja pedidos do macOS como este:
“chatcode-gateway” pretende aceder a ficheiros na pasta Documentos.
…ou pedidos relativos às pastas Secretária e Descargas, a volumes amovíveis, à Acessibilidade ou à Gravação do ecrã. Isto pode parecer alarmante — como se o gateway quisesse bisbilhotar. Não é o caso.
Eis o que realmente acontece: no macOS, o gateway corre com o seu utilizador e executa o agente a seu pedido. Quando esse agente lê um ficheiro numa pasta protegida, ou quando uma ferramenta que ele executa precisa de automatizar a interface ou de capturar o ecrã, o sistema de privacidade do macOS (TCC) intervém e pede consentimento — e atribui o pedido ao processo que lançou o trabalho, que é o chatcode-gateway. Assim, o nome que aparece na caixa de diálogo é o do gateway, mas a intenção é a do seu agente, a realizar a tarefa que lhe deu.
O que fazer:
- Permita o que espera. Se pediu ao agente que trabalhasse com ficheiros em
~/Documents, permitir o acesso a Documentos é exatamente o correto. - Recuse o que não espera. O controlo é sempre seu; recusar significa apenas que o agente não pode tocar nesse recurso.
- Pode gerir isto a qualquer momento em Definições do Sistema → Privacidade e segurança (System Settings → Privacy & Security), nas secções Ficheiros e pastas, Acessibilidade e Gravação do ecrã.
Em Linux não existe uma caixa de diálogo equivalente — o utilizador vibe tem simplesmente as suas próprias permissões Unix, isoladas da sua conta.
Como comunica
Browser / Telegram ⇄ Chatcode control plane ⇄ your gateway ⇄ agent session
(you) (TLS relay) (your machine) (Claude/Codex/…)
- O gateway liga para fora, ao plano de controlo, através de um WebSocket TLS (
wss://…). Nunca abre uma porta de entrada na sua máquina. - O browser e o Telegram ligam-se ao plano de controlo, que retransmite o tráfego para o seu gateway.
- A sua autenticação faz-se com um cookie de sessão; o gateway autentica-se com um token próprio de cada gateway. O plano de controlo não guarda as suas chaves SSH privadas.
Sem encriptação ponta a ponta, e porquê
Não existe encriptação ponta a ponta entre o seu browser e o gateway, e trata-se de uma opção de design deliberada, não de um descuido. Cada troço é encriptado com TLS, mas o plano de controlo termina essas ligações para poder processar o conteúdo da sessão que faz a experiência no Telegram funcionar — formatar a saída do agente para a conversa, gerar pré-visualizações de ficheiros, transcrever mensagens de voz e decidir quando o notificar. Esse processamento precisa de conteúdo legível, por isso o plano de controlo ocupa uma posição de intermediário de confiança e consegue ler o tráfego do terminal.
Preferimos dizê-lo claramente a sugerir uma garantia que não oferecemos. O seu código, as suas credenciais e as sessões dos agentes continuam a residir apenas na sua máquina. Se quiser ter também o intermediário sob o seu controlo, pode alojar o próprio plano de controlo na sua conta da Cloudflare.
O que o gateway mostra no Telegram
O Telegram é a camada de continuidade, e é o gateway que a serve. Quando abre uma pré-visualização de ficheiro a partir de uma conversa, o gateway lê esse ficheiro e devolve-o através do intermediário. Os limites são deliberadamente apertados:
- Só de leitura. As pré-visualizações nunca escrevem. Só o trabalho das sessões e os carregamentos escrevem, e estão confinados a
~/workspace. - Âmbito limitado. As pré-visualizações só abrem caminhos dentro de
~/workspacee caminhos não ocultos no diretório pessoal do utilizador do gateway. Diretórios ocultos como~/.ssh,~/.claudee~/.codexestão vedados, a menos que se encontrem dentro de~/workspace— e a verificação é feita sobre o caminho real, depois de resolvidas as ligações simbólicas, pelo que não pode ser contornada com um symlink. - Links de curta duração. A transferência de uma pré-visualização usa um URL com token de portador (bearer), sem cookies, que expira ao fim de cerca de cinco minutos.
Uma ressalva que vale a pena deixar clara: a raiz de leitura das pré-visualizações inclui ficheiros não ocultos em qualquer ponto do diretório pessoal do utilizador do gateway — por isso, mantenha os segredos fora desse diretório pessoal (em Linux, é /home/vibe), e não apenas fora dos ficheiros ocultos (dotfiles).
Resumo de confiança e privacidade
- A sua máquina, a sua subscrição. Os agentes correm em hardware seu, com a sua própria conta do Claude/ChatGPT. O Chatcode é o intermediário, não uma nuvem que copia o seu repositório para outro lado.
- Sem portas de entrada. Apenas um WebSocket de saída. O acesso SSH para uma sessão de depuração é à parte e só é ativado se o pedir (a chave é adicionada por si; por omissão, não há nenhuma).
- Fronteira do espaço de trabalho. O trabalho das sessões e os carregamentos estão limitados a
~/workspace; as pré-visualizações no Telegram são só de leitura e têm âmbito limitado (detalhes acima). - Administração auditável. Em Linux, o sudo sem palavra-passe fica registado num ficheiro só de acréscimo, pertencente ao root.
- Segredos em repouso. O ficheiro de ambiente que contém o token do gateway tem o modo
600.
Verifique o que é executado
Não tem de acreditar apenas na nossa palavra:
- Leia o instalador. É um simples script de shell, executado por si — inspecione-o antes de ele tocar na máquina.
- Confirme a soma de verificação. Cada versão inclui um ficheiro
.sha256; o instalador verifica-o, e pode voltar a verificá-lo por si. - Fixe uma versão com
--version vX.Y.Zem vez delatest. - Compile a partir do código-fonte e instale com
--binary-source. - Aloje o próprio plano de controlo na sua conta da Cloudflare, para ter a custódia total do intermediário.
Estamos a documentar o protocolo do gateway e a abrir mais partes do código-fonte ao longo do tempo, para que o intermediário e o comportamento na máquina possam ser verificados de forma independente — é com transparência que isto conquista confiança.
Atualizar e desinstalar
- Atualizar: uma tarefa de manutenção diária atualiza automaticamente o gateway e as CLIs dos agentes. Para atualizar já, volte a executar o instalador com uma
--versionmais recente. - Estado / registos:
systemctl status chatcode-gatewayejournalctl -u chatcode-gatewayem Linux;~/Library/Logs/chatcode-gateway.logno macOS. - Desinstalar: execute o script de limpeza. É destrutivo por omissão — leia-o primeiro.
# Linux — removes the service, config, sudoers + log policy, and the `vibe` user + home
curl -fsSL https://chatcode.dev/cleanup.sh | sudo bash -s -- --yes
# macOS — removes the launchd agents, binary, config, and Chatcode-managed hooks; keeps ~/workspace
curl -fsSL https://chatcode.dev/cleanup.sh | bash -s -- --yes
Opções úteis: --keep-user (Linux: mantém o utilizador vibe e o respetivo diretório pessoal), --keep-workspace, --remove-workspace (macOS: apaga também ~/workspace) e --kill-tmux. No macOS, ~/workspace é mantido, a menos que passe --remove-workspace.
Se tudo isto é novo para si, comece por Como usar o Claude Code no Telegram com o Chatcode para ter uma visão geral da configuração.
Perguntas frequentes
Preciso de ter o meu próprio servidor para executar o gateway?
Não. No modo fácil, o Chatcode liga-se à DigitalOcean e aprovisiona um droplet Linux que executa o gateway por si. A opção de usar o seu próprio servidor instala o mesmo gateway num servidor Linux ou num Mac que já tenha.
Porque é que o macOS diz que o chatcode-gateway quer aceder às minhas pastas Documentos / Descargas ou ao meu ecrã?
No macOS, o gateway corre com o seu próprio utilizador, pelo que o agente de programação que está a utilizar (Claude Code, Codex, etc.) tem o mesmo acesso a ficheiros que a sua conta. Quando esse agente lê uma pasta protegida ou usa uma capacidade protegida, o macOS mostra o pedido de privacidade habitual e atribui-o ao processo que lançou o agente: o gateway. É o seu agente a fazer o que lhe pediu, apresentado através do fluxo de consentimento normal do macOS. Permita o que espera; recuse o que não espera.
O gateway abre portas na minha máquina?
Não abre portas de entrada. O gateway estabelece uma ligação WebSocket TLS de saída ao plano de controlo do Chatcode, e o plano de controlo retransmite o tráfego do seu browser e do Telegram. (O SSH para uma sessão de depuração é à parte e só é ativado se o pedir.)
O Chatcode consegue ver o tráfego do meu terminal?
Em trânsito, sim. O tráfego é encriptado com TLS em cada troço, mas não há encriptação ponta a ponta entre o seu browser e o gateway, e isso é intencional. O plano de controlo processa o conteúdo das sessões para dar suporte à experiência no Telegram (formatação da saída do agente, pré-visualizações de ficheiros, transcrição de voz, notificações), pelo que ocupa uma posição de intermediário de confiança e consegue ler o conteúdo do terminal. O seu código, as suas chaves e as sessões dos agentes continuam a residir apenas na sua máquina; para controlar também o intermediário, aloje-o por conta própria.
Porque é que o gateway usa sudo sem palavra-passe em Linux?
Para que um agente que está a utilizar possa executar tarefas de administração (instalar um pacote, reiniciar um serviço) sem ficar parado num pedido de palavra-passe a que não consegue responder à distância. Em Linux, o gateway corre com um utilizador dedicado vibe, e cada comando sudo é escrito num registo só de acréscimo, pertencente ao root, que pode consultar.