Como controlar o Claude Code a partir do telemóvel através do Telegram em 2026

Pode encontrar mais materiais sobre a configuração de ferramentas na documentação da Ailoot.

O que é o Claude Code Channels e por que precisa dele#

A 20 de março de 2026, a Anthropic lançou o Claude Code Channels, um plugin oficial para ligar uma sessão do Claude a aplicações de mensagens. São suportados o Telegram, o Discord e o iMessage. A funcionalidade está em pré-visualização de investigação: a documentação está em code.claude.com/docs/en/channels e o código-fonte do plugin está no repositório público anthropics/claude-plugins-official.

Em poucas palavras, é uma «ponte de chat» entre o seu telemóvel e a sua sessão do Claude Code. Envio uma mensagem ao bot: «Continua a reescrever a tabela de preços; atualiza as datas da próxima turma em business/products/practicum/README.md», e o bot encaminha-a para a sessão no meu VPS. O Claude recupera o contexto, edita o ficheiro, confirma as alterações e responde no Telegram: «Feito, verifica o commit.» O portátil fica fechado em casa.

⚠️ A principal limitação da pré-visualização de investigação: o Channels é uma ponte MCP. A sessão tem de estar a funcionar no seu computador ou VPS. Quando a sessão é encerrada, ninguém recebe as mensagens. Por isso, a operação 24/7 tem de ser configurada à parte (consulte a secção sobre VPS abaixo).

Em que difere o Channels de outras formas de trabalhar remotamente

Na sua documentação oficial, a Anthropic apresenta uma tabela comparativa direta. Eis uma adaptação:

A principal diferença entre Channels e Remote Control: o Remote Control é «o telemóvel como janela para o terminal» — vê literalmente o cursor e carrega em botões. O Channels é um chatbot cujo cérebro é a sua sessão local do Claude. Com o Remote Control, olho para o terminal. Com o Channels, envio uma mensagem a alguém que lê os meus ficheiros.

Se precisa de controlo total do ecrã, use o Remote Control. Se quer «enviar uma pergunta, continuar o seu dia e receber uma resposta», use o Channels. Uso ambos: o Remote Control quando preciso de aprovar alterações críticas e o Channels quando confio na tarefa e quero ficar com a minha noite livre.

O que precisa antes de começar#

Antes de passar aos comandos, confirme esta lista:

1. Conta Anthropic. Precisa de Pro, Max, Team ou Enterprise. O Channels não está disponível no plano gratuito. Uma chave API Anthropic Console também funciona; se a organização Console distribuir definições geridas, verifique que Channels está ativo aí.
2. Claude Code v2.1.80 ou posterior. Verifique com claude --version. Se for mais antiga, atualize com claude update ou npm install -g @anthropic-ai/claude-code@latest.
3. Bun. Os plugins Channels são scripts Bun, não scripts Node. Verifique com bun --version. Se não estiver instalado, execute curl -fsSL https://bun.sh/install | bash e, em seguida, source ~/.bashrc.
4. Conta Telegram. Pode ser qualquer conta; o essencial é ter iniciado sessão no telemóvel.
5. Se tiver um plano Team/Enterprise, peça ao administrador para ativar channelsEnabled nas definições geridas ou através de admin-settings/claude-code. Por predefinição, as organizações têm esta opção desativada.

Se nunca ouviu falar do Bun, não se preocupe. Bun é um ambiente de execução alternativo para JavaScript, como o Node. A Anthropic escolheu-o para os plugins Channels porque arranca mais depressa e é mais fácil de empacotar num único binário. Instale-o uma vez e esqueça-o.

⚠️ O Channels ainda não funciona com Bedrock / Google Vertex / Azure Foundry empresariais. Só funciona com autenticação através de claude.ai ou Anthropic Console.

Passo 1. Crie um bot do Telegram através do BotFather#

O BotFather trata de tudo — só precisa de carregar em cinco botões. Eis os passos:

1. Abra o @BotFather no Telegram (pode usar o telemóvel; também pode fazer o resto da configuração no telemóvel).
2. Carregue em «Start» se for a primeira vez que o utiliza.
3. Envie o comando /newbot.
4. O BotFather perguntará: «Muito bem, um novo bot. Que nome lhe vamos dar?» Introduza o nome apresentado, por exemplo, O meu assistente - Claude Code.
5. Em seguida, pedirá um nome de utilizador. Tem de ser único em todo o Telegram e terminar em bot. Por exemplo, my_claude_bot ou my_dev_bot.
6. O BotFather responderá com uma mensagem semelhante a esta:

Feito! Parabéns pelo seu novo bot. Pode encontrá-lo em
'<OFFICIAL_URL>'.

Use este token para aceder à HTTP API:
1234567890:AAHzlAU...

Mantenha o seu token seguro e guarde-o num local seguro; qualquer pessoa pode usá-lo para controlar o seu bot.

Copie o token. Vai precisar dele dentro de dois minutos.

⚠️ Segurança do token. O token dá controlo total sobre o bot. Se for divulgado, qualquer pessoa poderá escrever como se fosse o seu bot e (potencialmente) intercetar as mensagens que envia ao Claude. Não o publique em repositórios, não o cole no código nem o envie em conversas. Guardo os tokens em ~/.claude/channels/telegram/.env; o plugin irá colocá-lo aí no próximo passo.

Passo 2. Instale o plugin do Telegram no Claude Code#

Abra um terminal em qualquer pasta onde costuma trabalhar com o Claude e execute:

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#

Na sessão do Claude:

/telegram:configure 1234567890:AAHzlAU...

O comando irá guardar o token em ~/.claude/channels/telegram/.env. Só o seu utilizador tem acesso ao ficheiro (chmod 600), pelo que não precisa de se preocupar com isso.

Em alternativa, defina o token através de uma variável de ambiente. Isto é útil se estiver a implementar o Claude com systemd ou Docker e não quiser usar comandos interativos:

export TELEGRAM_BOT_TOKEN="1234567890:AAHzlAU..."
claude --channels plugin:telegram@claude-plugins-official

⚠️ Em produção, uso sempre variáveis de ambiente em vez de um ficheiro .env na minha pasta pessoal, ~/. Assim, é mais fácil gerir segredos através do systemd (Environment=TELEGRAM_BOT_TOKEN=...) e evita incluir acidentalmente ~/.claude/ no repositório.

Passo 4. Reinicie o Claude com a opção --channels#

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:

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:

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#

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 <code from their account>

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.

Como manter o Claude a funcionar 24/7 no seu próprio VPS#

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

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:

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:

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:

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:

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#

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:

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

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 e o guia sobre os modelos Sonnet e 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 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?#

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.

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#

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. 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. 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#

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.
2. Combine-o com o Routines. Pode executar 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. 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.

Para mais materiais sobre trabalhar com ferramentas, consulte a documentação da Ailoot.