---
title: "O gateway do Chatcode"
seoTitle: "Gateway do Chatcode: instalação, confiança e funcionamento"
navTitle: "Gateway"
description: "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."
slug: gateway
lang: pt-PT
date: 2026-06-12
updated: 2026-06-12
author: "Chatcode"
section: "Gateway"
faq:
  - q: "Preciso de ter o meu próprio servidor para executar o gateway?"
    a: "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."
  - q: "Porque é que o macOS diz que o chatcode-gateway quer aceder às minhas pastas Documentos / Descargas ou ao meu ecrã?"
    a: "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."
  - q: "O gateway abre portas na minha máquina?"
    a: "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.)"
  - q: "O Chatcode consegue ver o tráfego do meu terminal?"
    a: "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."
  - q: "Porque é que o gateway usa sudo sem palavra-passe em Linux?"
    a: "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."
---

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](https://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 `tmux` dentro de `~/workspace`.
- Corresponde à caixa «O seu servidor + gateway» na [arquitetura do Chatcode](/articles/claude-code-telegram-with-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 como `vibe`, **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 como `vibe`.
- Instala ferramentas de base, incluindo `tmux`, `git`, `ripgrep` e **`bubblewrap`** (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-gateway` e 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 com `caffeinate`).
- Requer o Homebrew, além de `tmux`, `git` e `curl`.

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):

```bash
# 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 `vibe` tem sudo `NOPASSWD`, 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 o `vibe` pode 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 `~/workspace` e caminhos **não ocultos** no diretório pessoal do utilizador do gateway. Diretórios ocultos como `~/.ssh`, `~/.claude` e `~/.codex` estã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:

1. **Leia o instalador.** É um simples script de shell, executado por si — inspecione-o antes de ele tocar na máquina.
2. **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.
3. **Fixe uma versão** com `--version vX.Y.Z` em vez de `latest`.
4. **Compile a partir do código-fonte** e instale com `--binary-source`.
5. **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 `--version` mais recente.
- **Estado / registos:** `systemctl status chatcode-gateway` e `journalctl -u chatcode-gateway` em Linux; `~/Library/Logs/chatcode-gateway.log` no macOS.
- **Desinstalar:** execute o script de limpeza. É **destrutivo por omissão** — leia-o primeiro.

```bash
# 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](/articles/claude-code-telegram-with-chatcode)** para ter uma visão geral da configuração.
