Pontos principais
Inicie o Claude Code como habitualmente e introduza `/plugin install telegram@claude-plugins-official` na sessão. Se o plugin não for encontrado, adicione primeiro o marketplace oficial com `/plugin marketplace add anthropics/claude-plugins-official`. Após a instalação, execute `/reload-plugins` para ativar os comandos do plugin na sessão atual.
Abra um terminal em qualquer pasta onde costuma trabalhar com o Claude e execute:
```bash
claude
```
Introduza o comando com barra na sessão:
```
/plugin install telegram@claude-plugins-official
```
Se o Claude responder «Plugin not found in any marketplace», o cliente não conhece o marketplace oficial. Adicione-o:
```
/plugin marketplace add anthropics/claude-plugins-official
```
Ou atualize-o, se já o tiver adicionado anteriormente:
```
/plugin marketplace update claude-plugins-official
```
Após a instalação bem-sucedida, volte a carregar os plugins para ativar os respetivos comandos:
```
/reload-plugins
```
Deverá agora ter comandos com barra, como `/telegram:configure` e `/telegram:access`. Para confirmar, introduza `/help`; a lista deverá incluir uma secção telegram.
## Passo 3. Associe o token ao plugin
Pontos principais
Saia da sessão (`exit` ou `Ctrl+D`) e volte a iniciá-la com a opção `--channels plugin:telegram@claude-plugins-official`. Esta opção ativa o plugin e indica ao Claude que deve consultar a API do Telegram para procurar mensagens novas. Sem ela, o bot existe, mas permanece em silêncio — o plugin está inativo e a consulta ainda não começou.
Este é o ponto mais importante e aquele que apanha toda a gente da primeira vez. **Instalar o plugin não é suficiente.** Para que o bot comece realmente a receber mensagens, tem de iniciar o Claude com uma opção explícita:
```bash
claude --channels plugin:telegram@claude-plugins-official
```
Sem esta opção, a sessão funciona como habitualmente, mas o plugin do Telegram fica inativo. Com ela, o Claude inicia o servidor MCP do plugin, começa a consultar a API do Telegram e responde às mensagens enviadas ao bot.
Depois de iniciar, deverá ver algo semelhante no terminal:
```
✻ Welcome to Claude Code 2.1.80
Channels: telegram@claude-plugins-official (active)
Polling for messages...
```
Se não houver nenhuma linha sobre channels, a opção não foi aplicada. Confirme que a versão do Claude Code é 2.1.80+ e que o plugin está instalado (`/plugin list` na sessão).
⚠️ **Dica útil.** Adicionei um alias a `~/.zshrc`:
```bash
alias claude-tg="claude --channels plugin:telegram@claude-plugins-official"
```
Depois, basta executar `claude-tg`. Pode indicar vários plugins separados por espaços: `--channels plugin:telegram@... plugin:discord@...`.
## Passo 5. Associe a conta e bloqueie todas as outras
Pontos principais
Abra o seu bot no Telegram e envie-lhe qualquer mensagem. O bot responderá com um código de associação de seis dígitos. Volte ao terminal e introduza `/telegram:access pair `. Depois, restrinja o acesso com uma lista de permissões: `/telegram:access policy allowlist`. Aprove só códigos de pessoas que pretende autorizar; a lista de remetentes controla quem chega à sessão.
**Um remetente aprovado pode pedir ao Claude que atue sobre os ficheiros e ferramentas disponíveis na sessão.** Associe só a conta pretendida e restrinja a política de remetentes antes de depender do bot.
Passos:
1. **Abra o seu bot no Telegram.** Encontre-o pelo nome de utilizador `@my_claude_bot` ou pela ligação na resposta do BotFather. Carregue em «Start».
2. **Envie qualquer mensagem ao bot.** Por exemplo, `hi`.
3. **O bot responderá com um código de associação.** Será semelhante a este:
```
Olá! Para associar esta conta, execute na sua sessão do Claude Code:
/telegram:access pair 847291
Este código é válido durante 5 minutos.
```
4. **Volte ao terminal.** Na sessão do Claude, introduza o comando da resposta:
```
/telegram:access pair 847291
```
O Claude responderá: «Conta associada.» Agora, a sua conta do Telegram pode enviar comandos.
5. **Ative a política de lista de permissões.** Esta bloqueia todas as contas, exceto as que já foram associadas:
```
/telegram:access policy allowlist
```
Depois disso, as mensagens de outras contas serão **ignoradas silenciosamente**. Não aparecerão no terminal e o bot não responderá — como se nunca tivessem existido.
⚠️ **É muito importante** ativar a lista de permissões logo após a associação. **Não deixe para mais tarde.** Não aprove pedidos de associação desconhecidos durante a configuração nem assuma que uma resposta bem-sucedida prova que a política de remetentes está correta.
Se precisar de adicionar outra pessoa (por exemplo, um colega de projeto):
```
/telegram:access pair
```
Essa pessoa deve começar por enviar uma mensagem ao bot, obter um código e passá-lo a si. Só a pode adicionar desta forma.
Pode encontrar mais guias na [documentação da Ailoot](https://ailoot.ai/docs/).
[Guias Ailoot](https://ailoot.ai/docs/)
## Como manter o Claude a funcionar 24/7 no seu próprio VPS
Pontos principais
Uma sessão local funciona enquanto o portátil está ligado; feche a tampa e o bot fica em silêncio. Para que o Claude responda a qualquer hora, transfira a sessão para o seu próprio VPS: instale o Claude Code e o Bun, autentique-se, instale e associe o plugin com o mesmo utilizador Unix dedicado e configure o systemd para o reiniciar automaticamente. Um servidor Coolify consegue fazê-lo sem problemas.
Se quer que o bot esteja «vivo a toda a hora», em vez de «ligue o portátil durante uma hora e mexa nele», a sessão tem de continuar em execução. Pode fazê-lo localmente com o tmux, mas um VPS é mais simples e fiável.
Uma configuração de exemplo utiliza um VPS Coolify que também aloja um site ([detalhes no guia para publicar através do Coolify](https://ailoot.ai/blog/pt-pt/coolify-claude-code-deploy/)). Pode usar o mesmo servidor — o Claude utiliza pouca memória. Se não tiver um VPS, obtenha o mais barato por 4–5 euros por mês, como um Hetzner CX11 / Yandex Cloud / Selectel.
### Passo 1: Instale o sistema no VPS
Crie primeiro a conta Unix dedicada e a pasta de trabalho como administrador. Reutilize uma conta existente só depois de verificar pasta pessoal e titularidade:
```bash
sudo useradd --create-home --shell /bin/bash claude
sudo install -d -o claude -g claude /home/claude/workspace
sudo -iu claude
```
Continue nesta shell de início de sessão `claude`, não na pasta de root. Instale Bun pelo instalador oficial e Claude Code pelo [percurso nativo](https://code.claude.com/docs/en/setup):
```bash
curl -fsSL https://bun.sh/install | bash
curl -fsSL https://claude.ai/install.sh | bash
```
Abra uma shell de início de sessão nova do mesmo utilizador para aplicar PATH e verifique conta e caminhos:
```bash
whoami
printf '%s\n' "$HOME"
command -v bun
command -v claude
bun --version
claude --version
cd /home/claude/workspace
claude
```
`whoami` tem de mostrar `claude` e `HOME` tem de ser `/home/claude`. Registe os caminhos absolutos de `command -v`; use o caminho real de Claude em `ExecStart` e inclua a pasta Bun no PATH do serviço. Pare se faltar um executável.
### Passo 2: Autenticar, instalar e associar como utilizador do serviço
Nesta mesma sessão interativa `claude`, conclua a autenticação e repita os passos 2–5 acima com este utilizador Unix: instale o plugin Telegram no **âmbito de utilizador**, configure o token, reinicie com `--channels`, associe a conta Telegram e defina `policy allowlist`. Teste mensagem e resposta antes de configurar o serviço. Não copie configuração ou credenciais Claude de root para esta pasta pessoal.
São suportadas autenticação de subscrição claude.ai e chave API Anthropic Console. Team/Enterprise exigem ativação pela organização; organizações Console geridas também têm de satisfazer as definições Channels. Console é faturado pela API, não coberto por subscrição claude.ai. Mantenha a conta e autenticação escolhidas ao passar da shell interativa para o serviço.
### Passo 3: Configure a sessão com o systemd
Saia da shell do utilizador do serviço e crie a unidade como administrador. A unidade abaixo assume que os caminhos verificados foram `/home/claude/.local/bin/claude` e `/home/claude/.bun/bin/bun`; substitua pelos resultados reais se diferirem. Forneça o mesmo ambiente de autenticação e token, limite a leitura da unidade ao administrador e nunca inclua segredos em commits. Crie o serviço para arranque e reinício após falha:
```bash
cat > /etc/systemd/system/claude-code.service <<'EOF'
[Unit]
Description=Claude Code with Telegram channel
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=claude
WorkingDirectory=/home/claude/workspace
Environment="HOME=/home/claude"
Environment="TELEGRAM_BOT_TOKEN=1234567890:AAH..."
Environment="PATH=/home/claude/.local/bin:/home/claude/.bun/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/home/claude/.local/bin/claude --channels plugin:telegram@claude-plugins-official --dangerously-skip-permissions
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable claude-code
systemctl start claude-code
```
Eis o que configurei:
- **`Type=simple`** — modo simples; o systemd considera o processo iniciado assim que arranca.
- **`User=claude`** — é executado com um utilizador separado, não como root. É mais seguro.
- **`WorkingDirectory=/home/claude/workspace`** — pasta preparada e pertencente ao utilizador do serviço. Coloque aí o repositório antes de iniciar; não deixe uma clonagem de root nem execute da pasta pessoal de root.
- **`Environment=TELEGRAM_BOT_TOKEN=...`** — o token é passado diretamente ao processo. Não é necessário um ficheiro `.env`.
- **`--dangerously-skip-permissions`** — é essencial para a operação sem supervisão. Sem esta opção, o Claude espera pelo seu «sim/não» no terminal antes de cada ação e a sessão fica bloqueada. A lista identifica remetentes; não torna seguros os comandos pedidos. Use este bypass só num ambiente isolado com ficheiros, credenciais e acesso de rede deliberadamente limitados.
- **`Restart=on-failure`** — se o processo falhar (o Claude bloqueia ou a rede cai), o systemd volta a iniciá-lo dentro de 10 segundos.
Consulte os registos com:
```bash
journalctl -u claude-code -f
```
Se algo correr mal, `journalctl -u claude-code -n 100` mostra as últimas 100 linhas.
### Passo 4: Confirme que o bot está ativo
Inicie o serviço só depois de a configuração interativa produzir uma resposta real no Telegram. Envie ao mesmo bot uma mensagem inofensiva da conta associada e confirme a resposta e os registos. Se funcionar interativamente mas não em systemd, compare primeiro utilizador Unix, HOME, pasta de trabalho, executável, PATH e ambiente de autenticação.
Para alterar associações depois, pare o serviço, execute `sudo -iu claude`, entre em `/home/claude/workspace` e inicie o mesmo canal interativamente. Associe e ative a lista aí, saia e reinicie o serviço. Não execute dois processos de consulta do mesmo bot ao mesmo tempo. `journalctl` lê registos; não fornece um prompt Claude interativo.
## 5 armadilhas num servidor de produção e como evitá-las
Pontos principais
Reuni estas armadilhas com base numa semana de instalações em produção: o systemd não encontra o Bun, o long polling falha após um longo período de inatividade, os limites do plano Max esgotam-se a meio do dia, `--dangerously-skip-permissions` pode causar uma fuga e a lista de permissões é esquecida após uma reinstalação. Cada problema pode ser resolvido com uma definição de uma linha, mas, se não souber que existem, irá deparar-se com eles dentro de alguns dias.
### 1. O Bun não está no PATH do systemd
O systemd inicia processos com um ambiente mínimo: não vê as variáveis de `~/.bashrc`. Se instalou Bun só na pasta pessoal de root e o serviço tem `User=claude`, não herda essa instalação nem o PATH da shell de root.
**Solução.** Instale o Bun para todo o sistema (`/usr/local/bin/bun`) ou indique o PATH explicitamente:
```ini
Environment="PATH=/home/claude/.bun/bin:/usr/local/bin:/usr/bin:/bin"
```
### 2. A sessão perde a ligação TCP à API do Telegram após um longo período de inatividade
Após 6–12 horas de inatividade, o bot pode «ficar em silêncio» — as mensagens são enviadas para o Telegram, mas o plugin não as recebe. É uma particularidade do long polling.
**Solução.** Adicione um reinício regular ao systemd (a cada 24 horas):
```ini
Restart=always
RuntimeMaxSec=86400
```
Ou configure uma tarefa cron: `0 5 * * * systemctl restart claude-code` (reinício às 5 da manhã).
### 3. Os limites do Claude Max esgotam-se a meio do dia
Se usar intensivamente o Claude através do Telegram, com o plano Max 5x (cerca de \$100 por mês) poderá atingir o limite em 4–6 horas. Os pedidos do Telegram não diferem dos pedidos num terminal normal; consomem o mesmo orçamento.
**Solução.** Defina um lembrete: «O bot não responde — verifica `/stats`». Se atingir o limite, espere que seja reposto ou atualize para o Max 20x (\$200 por mês). O [guia para poupar tokens](https://ailoot.ai/blog/pt-pt/claude-code-token-limits-saving/) e o [guia sobre os modelos Sonnet e Opus](https://ailoot.ai/blog/pt-pt/claude-code-model-effort-sonnet-opus/) poderão ajudar.
### 4. `--dangerously-skip-permissions` é perigoso mesmo com uma lista de permissões
Esta opção desativa todas as confirmações. Qualquer comando seu no Telegram é executado sem perguntas: apagar ficheiros, enviar pedidos externos, qualquer coisa. Uma vez pedi ao Claude para «remover as instruções `console.log` desnecessárias» e, no seu zelo de limpeza, o Claude apagou metade dos registos de depuração num script de produção. Restaurei-os através do git, mas o estrago estava feito.
**Solução.** Não ative `--dangerously-skip-permissions` se estiver a trabalhar num projeto crítico. Em vez disso, use o [Remote Control](https://code.claude.com/docs/en/remote-control) para executar sessões — as permissões chegam ao telemóvel e pode aprová-las manualmente. O Channels com `--dangerously-skip-permissions` destina-se a rascunhos, refatorização e testes.
### 5. A lista de permissões «deixa de funcionar» após uma reinstalação
A lista de permissões está guardada em `~/.claude/channels/telegram/`. Se mudar para um VPS novo, reinstalar o Claude ou mudar de utilizador, os dados antigos de associação não serão recuperados. A lista de remetentes anterior está ausente; não assuma que a nova instância mantém a política de acesso antiga.
**Solução.** Antes de mudar, faça uma cópia de segurança de `~/.claude/channels/telegram/`. Depois, volte a colocá-la no sítio. Ou associe novamente a conta logo após a reinstalação e **não deixe passar nem um minuto entre iniciar o bot e definir `policy allowlist`**.
## Channels ou Remote Control — qual deve escolher?
Pontos principais
Com o Channels, a sua sessão do Claude responde no chat e envia instruções a partir do telemóvel. Com o Remote Control, vê o ecrã do terminal no telemóvel e opera a sessão com botões. O Channels é mais prático para «perguntar e seguir com o dia»; o Remote Control destina-se aos passos críticos em que precisa de ver o que o Claude está a fazer e aprovar cada ação arriscada.
A Anthropic lançou as duas funcionalidades quase ao mesmo tempo: o Remote Control a 25 de fevereiro de 2026 e o Channels a 20 de março de 2026. **Não duplicam** uma à outra; resolvem problemas diferentes.
| Cenário | Channels | Remote Control |
|----|----|----|
| Perguntar «quais foram os commits de ontem?» quando está fora | ✅ Ideal | Exagerado — precisa do ecrã inteiro |
| Aprovar uma alteração num ficheiro | ⚠️ Aprovação sem ver através de `--dangerously-skip-permissions` | ✅ Vê o que o Claude pretende fazer |
| Manter o Claude a funcionar 24/7 | ✅ VPS + configuração do systemd | ⚠️ Requer um portátil ligado |
| Enviar apenas algumas instruções a partir do telemóvel | ⚠️ Exagerado — bot, token, plugin | ✅ Um código QR |
| Captar um webhook do CI / Sentry | ✅ Caso de utilização nativo | ❌ Não se destina a isto |
| Equipa com várias pessoas | ✅ Lista de permissões para várias contas | ⚠️ Apenas o proprietário da sessão |
| Manter os ficheiros fora da cloud da Anthropic | ✅ Apenas texto através do MCP | ✅ Também apenas texto |
Para mim, divido-os assim: uso o **Channels** para trabalho assíncrono quando estou longe do portátil, notificações do CI e integrações. Uso o **Remote Control** quando preciso de ver o que o Claude está a fazer ou aprovar um passo arriscado.
Pode usar ambos ao mesmo tempo. O bot do Telegram oferece-lhe um canal rápido para «perguntar e obter uma resposta»; o Remote Control dá-lhe um canal para «controlar assuntos críticos». Usam o mesmo limite do Claude.
## Perguntas frequentes
Pontos principais
Sete das perguntas mais frequentes sobre o Channels: ligar vários bots, o que acontece ao fechar o terminal, webhooks do CI, Telegram ou Discord, limitações do plano Team, o que o Claude consegue ver a partir do telemóvel e o plano gratuito. Pode encontrar mais materiais na documentação da Ailoot.
**Posso ligar vários bots ao mesmo tempo?**
Sim. A opção `--channels` aceita uma lista separada por espaços: `--channels plugin:telegram@claude-plugins-official plugin:discord@claude-plugins-official`. Uma sessão do Claude responde nas duas conversas.
**O que acontece se fechar o terminal?**
A sessão termina, o plugin para e o bot fica em silêncio. Num VPS, a sessão continua a funcionar no systemd. Num computador local, feche o portátil e o `claude` desligar-se-á com SIGHUP dentro de alguns segundos.
**Posso receber notificações do CI ou do Sentry?**
Sim. O Channels é um **canal bidirecional**. Pode escrever o seu próprio plugin para encaminhar webhooks para a sessão utilizando a [referência do Channels](https://code.claude.com/docs/en/channels-reference). O Claude verá os eventos em tempo real e responderá.
**O Telegram tem alguma limitação em relação ao Discord?**
As capacidades básicas são as mesmas. O Discord requer Message Content Intent nas definições do bot. O iMessage só funciona em macOS e lê diretamente a base de dados `~/Library/Messages/chat.db`. O Telegram é universal.
**Se tiver um plano Team, o que preciso de fazer?**
O administrador da organização tem de ativar `channelsEnabled: true` nas definições geridas ou através de [admin-settings/claude-code](https://claude.ai/admin-settings/claude-code). Sem isto, o plugin liga-se, mas as mensagens não são transmitidas — aparece um aviso de arranque no terminal.
**O que consegue ver o Claude a partir do meu telemóvel — a própria conversa do Telegram?**
Não. O Claude vê **apenas a mensagem que enviou ao bot**. O histórico das suas conversas no Telegram, a lista de chats e os contactos estão inacessíveis. O plugin MCP lê apenas as mensagens dirigidas ao bot através da Telegram Bot API.
**Posso executar o Claude através do Channels sem uma subscrição Pro/Max?**
Sim, também é suportada uma chave API Anthropic Console; a utilização é faturada à organização Console. O nível claude.ai gratuito não é o percurso de subscrição aqui descrito. Team/Enterprise e organizações Console geridas têm de satisfazer as definições de ativação Channels.
## O que se segue
Pontos principais
O bot está configurado, a lista de permissões está ativa e a sessão está num VPS. A seguir, integre o Channels na sua rotina diária: ligue webhooks do GitHub Actions e do Sentry, combine-o com o Routines para tarefas regulares e configure um monitor do estado do bot. Cada passo demora 15–30 minutos e fecha uma lacuna de observabilidade.
Quando o bot estiver a funcionar de forma fiável, há alguns passos seguintes para tirar o máximo partido do Channels:
1. **Ligue webhooks do CI.** Se utilizar o GitHub Actions / GitLab CI, pode configurar o plugin Channels para encaminhar os resultados das compilações diretamente para a sessão. O Claude verá «o teste falhou» logo após um push e sugerirá uma correção. Consulte a documentação [channels-reference](https://code.claude.com/docs/en/channels-reference).
2. **Combine-o com o Routines.** Pode executar [Routines](https://ailoot.ai/blog/pt-pt/claude-code-routines/) na mesma sessão para tarefas regulares. De manhã, o bot envia por iniciativa própria «bom dia, aqui está o resumo do projeto» e responde a partir do telemóvel: «crie um relatório de receitas».
3. **Configure um monitor do bot.** Quero saber se o bot ficar em silêncio. Um pequeno script cron no VPS envia um ping ao bot do Telegram de hora a hora. Se o bot não responder, envia um alerta para um canal separado. Sem isto, o bot pode deixar de funcionar às 4 da manhã e só descobrirá ao meio-dia.
4. **Considere os [hooks](https://ailoot.ai/blog/pt-pt/claude-code-hooks/).** Os hooks respondem a eventos do Claude (ferramenta iniciada, mensagem concluída). Em conjunto com o Channels, permitem notificações automáticas do Telegram, como «O Claude concluiu a tarefa N».
Não ligue o Channels a tudo. É uma forma prática de acompanhar uma tarefa enquanto está fora ou num café. Quando precisar de pensar a sério, abra o portátil e sente-se. O Channels liberta a sua mente do pensamento «ainda preciso de lhe perguntar isto, tenho de abrir o portátil» quando está fora ou em viagem.
### Fontes
- [Push events into a running session with channels - Claude Code Docs](https://code.claude.com/docs/en/channels)
- [anthropics/claude-plugins-official on GitHub](https://github.com/anthropics/claude-plugins-official) - código-fonte dos plugins Telegram, Discord, iMessage e fakechat
- [Continue local sessions from any device with Remote Control - Claude Code Docs](https://code.claude.com/docs/en/remote-control)
Para mais materiais sobre trabalhar com ferramentas, consulte a [documentação da Ailoot](https://ailoot.ai/docs/).
[Guias Ailoot](https://ailoot.ai/docs/)
[Aceder à Ailoot](https://ailoot.ai/)
## Perguntas frequentes
### Porque funciona o bot Telegram manualmente e falha como serviço?
Compare utilizador Unix, HOME, pasta de trabalho, executável Claude, PATH do Bun e autenticação do serviço com a execução interativa bem-sucedida. Instale, configure e associe com o mesmo utilizador do serviço; plugins e associações de root são outra configuração.
### Uma chave API Console pode substituir o início de sessão Pro ou Max em Channels?
Sim. É suportada autenticação por chave API Anthropic Console, com faturação API Console. Verifique as definições da organização quando necessário e configure token, associação e lista de remetentes na conta que executa a sessão.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.