> ## Documentation Index > Fetch the complete documentation index at: https://docs.octasend.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Token Control > Acompanhe o consumo do Claude Code por conta e seja avisado quando o limite bloquear e quando ele liberar O **Token Control** acompanha o consumo de tokens do **Claude Code** nas máquinas da sua equipe e avisa pelos canais da OctaSend quando uma conta bate no limite e quando esse limite libera de novo. Assim ninguém precisa ficar olhando o relógio para saber quando pode voltar a trabalhar. Os dados vêm de um agente que você instala em cada máquina. Ele lê os contadores de uso que o próprio Claude Code grava no computador e envia para a OctaSend. > [!NOTE] > > Módulo opcional — fale com a OctaSend para ativar. Sem o módulo, o item **Token Control** não aparece no menu, e quem abrir um link direto para essas telas é levado ao Dashboard. ## Conceitos * **Máquina** — um computador com o agente instalado. Cada máquina tem o próprio token de acesso. * **Conta** — a conta do Claude Code que gerou o consumo. O limite pertence à conta, não à máquina: a mesma conta usada em dois computadores aparece como **um único cartão**, com o consumo das duas máquinas somado. Uma máquina usada com duas contas gera **dois cartões**. * **Limite de sessão** e **limite semanal** — os dois bloqueios do Claude Code que o módulo acompanha. Máquinas, contas, alertas, destinatários e configurações pertencem à sua conta OctaSend inteira, não a um usuário. Todos os usuários do painel veem e alteram as mesmas telas. As telas ficam em **Token Control**, no menu lateral: | Tela | Para que serve | | - | - | | **Visão geral** | Consumo de cada conta e horário do próximo reset | | **Máquinas** | Cadastrar, acompanhar e revogar as máquinas com o agente | | **Alertas** | Histórico dos avisos agendados e enviados | | **Configurações** | Silêncio, resumo diário e quem recebe os avisos | ## Como funciona **1. Você cadastra a máquina** Em **Token Control → Máquinas** você cria a máquina e roda o comando de instalação no computador. **2. O agente envia o consumo** A cada 30 segundos o agente confere os arquivos de sessão do Claude Code e, havendo atividade nova, envia os contadores para a OctaSend. **3. A conta aparece sozinha** Na primeira vez que o agente enxerga uso de uma conta, ela surge em **Visão geral**. Não é preciso cadastrar a conta. **4. O bloqueio vira dois avisos** Quando o Claude Code bloqueia por limite, o agente captura a mensagem de bloqueio. A OctaSend envia na hora o aviso **Limite atingido** e agenda o aviso **Limite resetou** para o horário em que o acesso volta. ### O que sai da sua máquina Somente contadores: tokens de entrada, saída e cache, o modelo, o nome da pasta do projeto, o identificador da sessão e da conta, e o texto da mensagem de limite atingido do próprio Claude Code. **Nenhum prompt, resposta ou trecho de código sai da máquina.** ## Instalar o agente Requisito: **Node.js 20 ou superior** na máquina. **1. Crie a máquina** Em **Token Control → Máquinas**, clique em **Adicionar máquina**, informe o **Nome da máquina** (ex.: *Notebook do trabalho*) e clique em **Criar máquina**. **2. Copie o comando** A tela mostra o comando de instalação com o token da máquina: ```bash theme={null} npx @octasend/token-control@latest connect --token=SEU_TOKEN ``` **3. Rode no terminal da máquina** Cole o comando no terminal do computador que você quer monitorar. O agente confirma o token com a OctaSend e começa a monitorar em seguida. > [!WARNING] > > O comando com o token aparece **uma única vez**. Copie antes de clicar em **Concluído**. Se perder o token, revogue a máquina e crie outra. ### Deixar o monitor ligado depois de reiniciar Rodando pelo `npx`, o agente funciona enquanto o terminal estiver aberto e **não instala a inicialização automática**: o `npx` guarda o pacote num cache temporário que o próprio npm limpa, e um atalho apontando para lá pararia de funcionar. Para o monitor voltar sozinho depois de reiniciar o computador, instale o pacote de forma permanente e conecte pelo comando instalado: ```bash theme={null} npm install -g @octasend/token-control@latest octasend-token-control connect --token=SEU_TOKEN ``` * **Windows:** rode o `connect` num terminal como administrador. * **macOS e Linux:** rode o `connect` com o seu usuário normal, **sem `sudo`**. O agente monitora a pasta pessoal de quem executa o comando e registra a inicialização automática para esse usuário. Nessa forma, o agente registra a inicialização automática do sistema: Agendador de Tarefas no Windows, `launchd` no macOS e `systemd` do usuário no Linux. No Windows ele cria também uma segunda tarefa, que confere a cada 5 minutos se o monitor caiu e o sobe de novo. Se o sistema recusar a inicialização automática (por exemplo, por falta de permissão), a máquina continua conectada e o monitor roda naquela sessão. O agente mostra o motivo e o comando para instalar manualmente. ### Comandos do agente Com a instalação permanente, rode os comandos como `octasend-token-control `. Se você conectou pelo `npx`, use `npx @octasend/token-control@latest `. | Comando | O que faz | | - | - | | `connect --token=` | Conecta a máquina, instala a inicialização automática (quando instalado de forma permanente) e inicia o monitor | | `start` | Inicia o monitor | | `status` | Mostra se a máquina tem configuração local e quais pastas do Claude Code são monitoradas. Não mostra se o monitor está rodando nem se a máquina foi revogada | | `logs` | Mostra o registro recente do agente | | `disconnect` | Remove a inicialização automática e a configuração local do agente. Não avisa a OctaSend: para a máquina deixar de contar como ativa, revogue-a em **Máquinas** | Opções do `connect`: | Opção | Efeito | | - | - | | `--token=` | Obrigatório. O token gerado em **Máquinas** | | `--claude-dir=` | Pasta do Claude Code a monitorar. Sem ela, o agente usa a pasta `.claude` da pasta pessoal do usuário. Pode ser repetida, para contas que ficam em pastas diferentes | | `--no-autostart` | Não instala a inicialização automática | ### Primeira conexão Na primeira conexão, o agente lê as sessões do Claude Code que já estão na máquina. A OctaSend aceita o consumo dos **últimos 14 dias**; o que for mais antigo é descartado. Bloqueios antigos encontrados nesse histórico entram na linha do tempo da conta, mas **não geram aviso**: só um bloqueio que ainda está valendo quando chega à OctaSend dispara **Limite atingido** e **Limite resetou**. Sem internet, o agente tenta de novo sozinho, em intervalos crescentes de até 10 minutos. Ele envia sempre o total de cada sessão, então um reenvio não duplica o consumo. ## Visão geral Cada conta detectada vira um cartão com: * **Sessão atual** — tokens consumidos nas últimas 5 horas. * **Limites semanais → Todos os modelos** — tokens consumidos nos últimos 7 dias. * **Reinicia…** — quando se sabe, o horário do próximo reset, no formato *Reinicia em 16 min*, *Reinicia em 2 h 10 min* ou, se faltar mais de um dia, *Reinicia sáb., 23:00*. O total de tokens soma entrada, saída, criação de cache e leitura de cache, de todas as máquinas que usam aquela conta. > [!NOTE] > > O painel mostra o **consumo absoluto** e o **horário do reset**, não uma porcentagem do limite. O teto de cada plano do Claude Code não pode ser medido com precisão, e um "% usado" calculado sobre um teto errado induziria a erro. Como ler os números: * O valor de **Sessão atual** é uma leitura aproximada da janela: soma as últimas 5 horas corridas, sem reproduzir o início exato do bloco de 5 horas do Claude Code. * O horário de reset da sessão aparece só enquanto o último bloqueio de sessão ainda não liberou. * O horário de reset semanal aparece depois que a conta for bloqueada pelo limite semanal pelo menos uma vez. A partir daí, o painel projeta o próximo reset somando semanas, porque ele volta no mesmo dia e hora toda semana. * Se nenhuma máquina ativa enviou dados nas últimas 2 horas, o cartão troca os números por *Sem leitura desde 26/09, 14:03 — o agente parou de reportar.* Assim um consumo zerado por falta de leitura não é confundido com falta de uso. Se nenhuma máquina ativa está reportando, por exemplo porque todas foram revogadas ou nenhuma foi conectada, o aviso é *Nenhuma máquina ativa está reportando consumo — instale ou reconecte o agente na aba Máquinas.* ### Nome da conta Uma conta nova aparece como **Conta** seguida dos 8 primeiros caracteres do identificador dela. Clique no lápis ao lado do nome para dar um nome fácil de reconhecer (ex.: *Conta da empresa*). Esse nome é usado nos avisos. ### Detalhe da conta Clique no nome da conta para ver: * **Projetos que mais consumiram (7 dias)** — os 5 projetos com mais tokens. O projeto é o nome da pasta onde o Claude Code foi usado. * **Linha do tempo de eventos de limite** — os 50 bloqueios mais recentes, com o tipo (**Limite de sessão**, **Limite semanal** ou **Limite (tipo não identificado)**), quando foi detectado, quando reseta e a mensagem original do Claude Code. O horário de reset de cada bloqueio vem, nesta ordem: 1. do horário exato que o Claude Code registra junto com o bloqueio; 2. do texto da mensagem de bloqueio, quando a versão do Claude Code não registra o horário exato; 3. de uma estimativa de 5 horas depois da detecção, quando nenhum dos dois está disponível. ## Máquinas A lista mostra **Nome**, **Versão** do agente, **Último sinal** (ou *nunca*, se a máquina ainda não foi conectada) e **Situação**: **Ativa** ou **Revogada**. Clique numa máquina para ver também a plataforma, o sistema operacional e as datas de cadastro e de revogação. ### Revogar uma máquina Clique em **Revogar** na linha da máquina e confirme: * o token dela para de funcionar **imediatamente** e não pode ser recuperado; * o agente daquela máquina recebe a ordem de parar no próximo envio; * o consumo que ela já enviou continua no painel. Para voltar a monitorar aquele computador, crie uma máquina nova e instale o agente de novo com o novo token. ### Tirar o agente de um computador Rode `disconnect` no computador e depois revogue a máquina em **Máquinas**. O `disconnect` só remove a inicialização automática e a configuração local, sem avisar a OctaSend. Sem a revogação: * a máquina continua **Ativa** no painel e, depois de 2 horas sem enviar dados, gera o aviso **Máquina sem reportar**; * um monitor que ainda esteja rodando, por exemplo aberto num terminal, continua enviando até ser encerrado. Com a máquina revogada, ele recebe a ordem de parar no próximo envio. ## Alertas A tela **Alertas** mostra os 100 avisos mais recentes, com os **Pendentes** no topo. Colunas: **Tipo**, **Agendado para**, **Situação** e **Erro**. ### Tipos de aviso | Tipo | Quando é gerado | | - | - | | **Limite atingido** | Assim que a OctaSend recebe um bloqueio que ainda está valendo. Diz que a conta atingiu o limite e quando o acesso volta, com data e hora legíveis (ex.: *O acesso volta em 24/09/2026 às 14:00.*) | | **Limite resetou** | Agendado para o horário do reset. Avisa que a conta pode voltar a trabalhar, mesmo que a máquina esteja parada ou desligada nesse horário | | **Resumo diário** | Uma vez por dia para cada conta, na hora escolhida em **Configurações**, se o resumo estiver ligado. Traz os tokens das últimas 24 horas e o projeto que mais consumiu | | **Máquina sem reportar** | Quando uma máquina ativa passa mais de 2 horas sem enviar dados | Regras de repetição: * Um **Limite atingido** por bloqueio detectado, e um **Limite resetou** por horário de reset da conta. Dois bloqueios com o mesmo horário de reset geram um único aviso de reset. * Um **Resumo diário** por conta por dia. * Um **Máquina sem reportar** por período de silêncio. Se a máquina voltar a enviar e depois sumir de novo, sai um aviso novo. Uma máquina cadastrada que nunca foi conectada não gera esse aviso. > [!WARNING] > > O agente só envia dados quando o Claude Code tem atividade nova. Uma máquina ligada, mas sem uso do Claude Code por mais de 2 horas, também conta como **sem reportar**. ### Quando o aviso de reset não sai O **Limite resetou** sai no horário do reset mesmo que ninguém esteja usando a máquina. Ele é marcado como **Ignorado**, em vez de enviado, só nestes casos, e a coluna **Erro** da tela **Alertas** explica cada um: * **Um bloqueio posterior adiou o reset.** A mesma conta foi bloqueada de novo com um horário de reset mais tarde. O aviso antigo é descartado e vale o aviso do novo horário. * **O horário era uma estimativa e nenhuma máquina ativa está reportando.** Quando o horário do reset é a estimativa de 5 horas depois da detecção, porque o Claude Code não informou o horário (veja *Detalhe da conta*, acima), e nenhuma máquina ativa enviou dados nas últimas 2 horas, a OctaSend não tem como confirmar que o bloqueio de fato liberou, e prefere não avisar a avisar errado. * **O envio atrasaria mais de 30 minutos** em relação ao horário do reset. Um "pode voltar a trabalhar" tão tarde não ajuda mais. ### Situação de cada aviso | Situação | Significado | | - | - | | **Pendente** | Agendado. Aguarda o horário, uma nova tentativa ou o fim do período de silêncio | | **Enviado** | Todos os destinatários ativos receberam a mensagem. O resultado de cada canal aparece em [Logs de mensagens](https://docs.octasend.com.br/plataforma/logs-de-mensagens.md) | | **Falhou** | O envio não se completou para pelo menos um destinatário, e o motivo aparece em **Erro** | | **Ignorado** | O aviso não foi enviado de propósito: não há destinatário ativo, um bloqueio posterior adiou o reset, o reset estimado não pôde ser confirmado, o aviso venceu há mais de 30 minutos ou o módulo foi desligado | A OctaSend confere os avisos a cada minuto. Uma falha temporária (instabilidade de servidor ou de rede) é tentada de novo, até 3 tentativas no total, com 1 minuto e depois 5 minutos de espera. Uma falha definitiva, como uma comunicação desativada, vai direto para **Falhou**. Cada tentativa nova, automática ou pelo **Reenviar**, vai só para os destinatários que ainda não receberam aquele aviso. Quem já recebeu não recebe de novo. ### Reenviar Avisos **Falhou** ou **Ignorado** têm o botão **Reenviar**. O aviso volta para **Pendente**, agendado para agora, e sai no ciclo seguinte, passando pelas mesmas regras de novo e alcançando só quem ainda não recebeu. É útil, por exemplo, depois de cadastrar um destinatário para um aviso que ficou sem ninguém para receber, ou de corrigir o canal de um destinatário que falhou. ## Configurações ### Avisos | Campo | O que faz | | - | - | | **Limiares de aviso (%)** | Aparece desativado. O aviso antecipado por porcentagem precisa do teto da conta, que não é possível medir com precisão. Você continua sendo avisado quando o bloqueio acontece e quando ele libera | | **Silêncio começa às** / **Silêncio termina às** | Período em que avisos não urgentes esperam. Preencha os dois horários. A faixa pode atravessar a meia-noite (ex.: 22:00 às 07:00) | | **Enviar resumo diário** | Liga o **Resumo diário** | | **Horário do resumo** | Hora cheia do envio, de 0 a 23 | Clique em **Salvar** para aplicar. Os horários valem no fuso de São Paulo (horário de Brasília). Como o silêncio afeta cada aviso: | Aviso | Durante o silêncio | | - | - | | **Limite atingido** e **Limite resetou** | Saem normalmente, mesmo de madrugada | | **Máquina sem reportar** | Espera o fim do silêncio | | **Resumo diário** | Só é gerado fora do silêncio. Se o silêncio cobrir a hora inteira do resumo, ele não sai naquele dia | ### Destinatários Os destinatários recebem os avisos de **todas** as contas e máquinas. Para adicionar, escolha o canal, informe o endereço e clique em **Adicionar**: | Canal | O que informar | | - | - | | **Email** | O endereço de e-mail | | **WhatsApp** | O número com o código do país (DDI) | | **Telegram** | O número de telefone de quem já iniciou o seu bot e compartilhou o número. Veja [Telegram](https://docs.octasend.com.br/guias/telegram.md) | Em cada destinatário: * a caixa de seleção liga ou pausa o envio para ele, sem removê-lo; * o botão de enviar teste manda a mensagem de **Limite resetou** com dados de exemplo (*Conta de teste* e um horário de reset no mesmo formato do aviso real) para aquele endereço, pelo canal dele; * o botão de lixeira remove o destinatário. Sem nenhum destinatário ativo, os avisos ficam como **Ignorado**. > [!NOTE] > > O canal precisa estar configurado na sua conta, em **Configurações → Canais**. Veja [E-mail](https://docs.octasend.com.br/guias/email.md), [WhatsApp](https://docs.octasend.com.br/guias/whatsapp.md) e [Telegram](https://docs.octasend.com.br/guias/telegram.md). ## Textos dos avisos Quando o módulo é ativado, a OctaSend cria cinco comunicações na sua conta, com template em português para **e-mail** e **WhatsApp**: | Comunicação | Aviso | | - | - | | Token Control - limite resetou | **Limite resetou** e o envio de teste | | Token Control - limite atingido | **Limite atingido** | | Token Control - resumo do dia | **Resumo diário** | | Token Control - máquina sem reportar | **Máquina sem reportar** | | Token Control - perto do limite | Aviso por porcentagem, hoje indisponível | Você pode editar os textos em [Comunicações](https://docs.octasend.com.br/plataforma/comunicacoes.md). Se o módulo for desativado e reativado, os textos que você já editou são mantidos. Os textos padrão são escritos com acentuação; um template que você já editou não é alterado quando a OctaSend atualiza os textos padrão. Os avisos, inclusive o envio de teste, não contam no **Limite diário de mensagens** da conta e nunca são barrados por ele. Veja [Configurações](https://docs.octasend.com.br/plataforma/configuracoes.md#geral). > [!WARNING] > > Não exclua nem desative essas comunicações: sem elas, os avisos do tipo correspondente ficam como **Falhou**. Para receber por **Telegram**, adicione o canal Telegram às comunicações que você quer receber por lá, porque elas são criadas só com e-mail e WhatsApp. Variáveis disponíveis nos templates: | Variável | Conteúdo | | - | - | | `{{conta}}` | Nome da conta, ou o identificador dela se ainda não tiver nome. Em **Máquina sem reportar**, que não se refere a uma conta, chega como *conta desconhecida* | | `{{reseta_em}}` | Data e hora do reset, no mesmo fuso dos horários de silêncio (horário de Brasília), no formato `24/09/2026 às 14:00`. Preenchida em **Limite atingido** e **Limite resetou** | | `{{tokens_usados}}` | Tokens das últimas 24 horas. Preenchida no **Resumo diário** | | `{{projeto_top}}` | Projeto que mais consumiu nas últimas 24 horas. Preenchida no **Resumo diário** | | `{{maquina}}` | Nome da máquina. Preenchida em **Máquina sem reportar** | | `{{plataforma}}` | Sempre `Claude Code` | Uma variável que não se aplica ao tipo de aviso chega vazia. ## Se o módulo for desligado Com o módulo desligado na sua conta, a OctaSend deixa de registrar o consumo e de avisar: * O consumo enviado pelas máquinas é recusado e nada é gravado: nem consumo, nem bloqueio, nem aviso. Ao receber a recusa, o monitor da máquina para. O último sinal da máquina continua registrado, para que religar o módulo não dispare **Máquina sem reportar** para quem não parou de verdade. * Nenhum aviso novo é gerado para a conta. Os avisos que já estavam agendados ficam como **Ignorado**, com o motivo *Módulo Token Control desligado*, em vez de saírem dias depois, quando o módulo voltar. * Quando o módulo volta a ser ligado, o consumo volta a entrar sozinho nas máquinas com o agente instalado de forma permanente, porque a inicialização automática sobe o monitor de novo (veja *Deixar o monitor ligado depois de reiniciar*, acima). Se você conectou pelo `npx`, rode `npx @octasend/token-control@latest start` de novo. ## Solução de problemas > [accordion] O comando diz que o token é inválido ou revogado > > O token foi digitado errado, a máquina foi revogada ou o token não existe. Crie uma máquina nova em **Máquinas** e use o comando gerado para ela. > [accordion] O comando diz que não foi possível confirmar a conexão com o servidor > > O agente não conseguiu falar com a OctaSend. Confira a conexão de internet da máquina e rode o comando de novo. > [accordion] O monitor não volta depois de reiniciar o computador > > Instalações pelo `npx` não criam inicialização automática. Instale com `npm install -g @octasend/token-control@latest` e rode `octasend-token-control connect --token=SEU_TOKEN`: no Windows, num terminal como administrador; no macOS e no Linux, com o seu usuário normal, sem `sudo`. Se a inicialização automática falhar, o agente mostra o motivo (por exemplo, *Acesso negado*) e o comando para instalar manualmente. > [accordion] A Visão geral mostra “Sem leitura desde…” > > Nenhuma máquina ativa enviou dados nas últimas 2 horas: o agente parou, a máquina está desligada ou o Claude Code não foi usado nesse período. Se o aviso for *Nenhuma máquina ativa está reportando consumo*, todas as máquinas foram revogadas ou nenhuma foi conectada: instale ou reconecte o agente em **Máquinas**. Na máquina, rode `octasend-token-control status` (ou `npx @octasend/token-control@latest status`, se conectou pelo `npx`) para ver se ela tem configuração e quais pastas monitora, e `logs` para ver o registro recente. O `status` não mostra se o monitor está rodando nem se a máquina foi revogada. > [accordion] O aviso de limite liberado não chegou > > Em **Alertas**, confira a situação do aviso **Limite resetou**. Se estiver **Ignorado**, a coluna **Erro** diz o motivo: um bloqueio posterior adiou o reset (vale o aviso do novo horário), o horário era estimado e nenhuma máquina ativa estava reportando, o aviso venceu há mais de 30 minutos ou não havia destinatário ativo. Se estiver **Enviado**, confira o resultado de cada canal em [Logs de mensagens](https://docs.octasend.com.br/plataforma/logs-de-mensagens.md). > [accordion] Uso contas do Claude Code em pastas diferentes > > Informe cada pasta no `connect` com `--claude-dir`, repetindo a opção quantas vezes precisar. Cada conta encontrada vira um cartão próprio em **Visão geral**. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.