Docs

Troubleshooting

Comece pelo diagnóstico barato antes de reinstalar:

curl -sS http://127.0.0.1:4477/status | jq .
/Applications/Knobler.app/Contents/MacOS/Knobler --selfcheck

O endpoint /status só existe quando a API local está ligada em Ajustes → Notch. Os campos variam por integração; normalmente incluem notches, player, dictation, ask, micInUse e lanMessaging.

O app fecha sozinho ao abrir (versões até a 0.13.0)

Sintoma: o ícone aparece por um instante e o app morre, sempre, em Mac onde ele nunca rodou antes. Em quem já usava, não acontece.

Causa: o monitor de AirPods pedia permissão de Bluetooth sem a chave NSBluetoothAlwaysUsageDescription no Info.plist, e o macOS aborta o processo nesse caso — só no primeiro pedido, por isso máquinas antigas escapavam.

Correção: atualize para a 0.13.1 ou posterior.

brew update && brew upgrade knobler

Pra confirmar que era isso, o motivo fica no relatório de falha:

ls -t ~/Library/Logs/DiagnosticReports/Knobler* | head -1 | xargs grep -o '"namespace":"TCC"[^]]*]'

O Knobler não aparece na lista do Ajustes do Sistema

Sintoma: instalação nova, o usuário abre Ajustes do Sistema → Privacidade e Segurança → Acessibilidade (ou Microfone, Câmera…) e o Knobler simplesmente não está lá para ser marcado.

Comece pelo diagnóstico — ele roda sem UI e serve para pedir por mensagem a quem está com o problema:

/Applications/Knobler.app/Contents/MacOS/Knobler --permissoes

A linha instalação: é a que decide:

Leitura Causa Correção
ok A instalação está sadia; ver abaixo Adicionar à mão pelo +
translocado O Gatekeeper está rodando uma cópia temporária read-only; a entrada do TCC aponta pra um caminho fantasma Mover para /Applications, xattr -dr com.apple.quarantine, reabrir
emQuarentena Instalado pelo .zip sem remover a marca do Gatekeeper xattr -dr com.apple.quarantine /Applications/Knobler.app
foraDeApplications(...) Rodando do Downloads/DerivedData; a permissão gruda naquele caminho Mover para /Applications e abrir de lá

O app avisa sozinho: nesses três estados o painel Ajustes → Permissões abre a cada inicialização com a causa e o passo de correção no topo.

Com a instalação sadia, a razão é outra e é do próprio macOS: o Ajustes do Sistema só lista um app depois que ele pede a permissão. Como o Knobler roda como agente (LSUIElement), o usuário que fechou o painel da primeira abertura fica sem nada visível. Duas saídas, ambas no painel Ajustes → Permissões:

Se o Knobler aparece na lista marcado e mesmo assim nada funciona, a entrada é de uma assinatura antiga: veja Reconceder a Acessibilidade.

Concedi a permissão e o painel continua dizendo "Sem status até usar"

Vale pra Rede local, Arquivos e pastas e Gravação de áudio do sistema: o macOS não dá API pra consultar essas três, só pra usá-las. O painel mostra Concedida depois que o recurso roda uma vez — não antes, por mais que o interruptor já esteja ligado no Ajustes do Sistema.

Atalho: o botão Verificar, na própria linha, força esse primeiro uso na hora (liga o Bonjour, lê a Mesa). A Gravação de áudio do sistema não tem o botão — ela só se prova com um player tocando, que é quando o tap de áudio é criado.

O countdown do calendário não aparece

Desde a 0.19.0 o Knobler não pede a permissão de Calendário na abertura (o balão caía por cima da página de novidades). Quem pede é Ajustes → Permissões, botão Permitir na linha Calendários. Concedida, o countdown liga em segundos — sem reabrir o app.

O app está aberto, mas o notch não aparece

  1. Confirme se o processo está ativo:

    pgrep -fl Knobler
    
  2. Encerre e abra a cópia instalada:

    killall Knobler 2>/dev/null || true
    open -a /Applications/Knobler.app
    
  3. Em monitores externos, confirme que a ilha simulada está posicionada no monitor esperado e que o app não está em modo de tela cheia exclusivo.

API local indisponível

O servidor escuta apenas loopback. Para scripts, tools/knobler retorna erro quando a API está desligada; isso é intencional para que o caller possa decidir se deve usar || true.

Ask não aparece no notch

  1. Confirme a API:

    curl -sS http://127.0.0.1:4477/status | jq '.ask'
    
  2. Para Claude Code, instale o hook e inicie uma nova sessão:

    ./tools/claude-hook/install.sh
    
  3. O hook falha aberto: se o Knobler estiver desligado, cancelado ou sem resposta, a pergunta deve continuar no terminal.

  4. Perguntas pendentes expiram em 15 minutos. Ao desligar a API, o app limpa a apresentação e invalida callbacks antigos.

Para testar sem Claude Code, use a CLI:

./tools/knobler ask "Continuar?" "Sim" "Não"

Aprovação do Codex não aparece no notch

Rode o gate — ele diz em qual etapa parou:

node tools/codex-integration-check.mjs
Saída Significado
capability: … esta versão do Codex não expõe os três pedidos de aprovação
daemon indisponível (instalação não-standalone) app e IDE ficam com aprovação nativa; só a CLI pela ponte espelha
OK a ponte funciona — o pedido veio de uma sessão fora dela

A causa mais comum do último caso: a sessão foi aberta com codex direto. Só o que passa por tools/knobler codex bridge é espelhado. Uma linha em stderr começando com codex bridge: explica cada recusa (token ausente, API fora, sem resposta a tempo) — em todas elas a aprovação nativa continua valendo, e nenhuma decisão é inventada.

Ditado não inicia

Sintoma típico: segurar a ⌥ direita não faz absolutamente nada — sem pílula, sem erro, sem log. O silêncio total é a assinatura de um problema de permissão, não de um problema no ditado.

O primeiro sinal está na barra de menus: com o ditado ligado e sem Acessibilidade, o ícone do Knobler vira ◐⚠ e o menu ganha ⚠ Ditado precisa de Acessibilidade…, que abre o painel direto. A marca some sozinha assim que a permissão é concedida (a checagem roda a cada 3s).

Para o diagnóstico completo, comece pelo /status, que separa as duas metades do fluxo:

curl -sS http://127.0.0.1:4477/status | jq '{axTrusted, tapExists, tapEnabled, dictation, keyLog}'
Leitura Significado
axTrusted: false Sem Acessibilidade — é a causa em quase todos os casos
tapExists/tapEnabled: false O CGEventTap não existe; nenhuma tecla chega ao app
keyLog sem tap61=1/tap61=0 depois de apertar e soltar a ⌥ direita Confirma que o tap está morto, não que o ditado está
dictation.enabled: false O recurso está desligado em Ajustes → Ditado
dictation.modelReady: false O Parakeet ainda está baixando ou falhou

O keyLog guarda as últimas 12 teclas que o diagnóstico enxerga, com horário: a ⌥ direita vista pelo tap (tap61=) e pelo monitor global (mon61=), tecla de mídia ou brilho que chega como evento NX (nx=<código>, por exemplo apertando volume), outros eventos de sistema (sd<subtipo>) e F1–F20 que chegam como tecla comum (kb=<keyCode> F14). Tecla que digita texto nunca entra — o /status responde sem autenticação a qualquer processo local —, então teclar num campo de texto não prova nada. Para testar o tap, aperte e solte a ⌥ direita (ou uma tecla de volume) e leia o keyLog de novo.

Se dictation está enabled: true e modelReady: true mas axTrusted é false, o ditado está sadio e o problema é só a permissão: sem ela o CGEventTap (setupEventTap em VolumeHUD.swift) nem é criado, então o flagsChanged da ⌥ direita nunca chega ao rightOptionChanged.

Reconceder a Acessibilidade

A UI pode mostrar o Knobler marcado enquanto a concessão não vale nada: o TCC ancora a permissão na assinatura do binário e guarda entradas antigas. Nesse estado, desmarcar e marcar de novo não resolve — é preciso apagar as entradas:

tccutil reset Accessibility com.zoi.knobler
killall Knobler; open -a Knobler

Ao reabrir, o app dispara o prompt do sistema (Dictation.swift:277). Conceda por ele, ou adicione /Applications/Knobler.app à lista com o botão + (remova a entrada antiga com − antes, se ainda estiver lá).

Não é preciso reiniciar de novo depois de conceder: o checkTapHealth (VolumeHUD.swift) roda em timer, percebe a mudança e recria o tap sozinho. Confirme:

curl -sS http://127.0.0.1:4477/status | jq '{axTrusted, tapEnabled}'

Os dois precisam ler true.

Por que isso volta a acontecer

O TCC casa a concessão contra a assinatura de código do binário. Se a assinatura muda, a permissão anterior deixa de valer. Isso acontecia quando a identidade mudava entre uma instalação e outra — o xcodebuild assinava com a identidade de desenvolvimento do Xcode e o tools/release.sh com Knobler Local Signing. Hoje as duas vias usam Knobler Local Signing, mas uma troca ainda acontece ao instalar por cima de uma cópia antiga, assinada com a identidade anterior. Veja Instalação local do build.

Verifique com que identidade a cópia instalada está assinada:

codesign -dv --verbose=2 /Applications/Knobler.app 2>&1 | grep Authority

Também confira o Microfone em Ajustes do Sistema → Privacidade e Segurança → Microfone. A falta dele é um sintoma diferente: o ditado começa e falha com a pílula "Sem acesso ao microfone".

Formatação local da transcrição não funciona

A falha do formatter deve devolver o transcript bruto; ela não deve impedir o ditado.

Câmera ou espelho não aparece

Webhook não entrega notificações

Nunca recebi um aviso do desenvolvedor

Provavelmente não há nenhum publicado — o canal é raro por natureza. Antes de suspeitar de defeito:

Ver Avisos do desenvolvedor.

Memória ou CPU subindo com o tempo

O Knobler guarda um registro de desempenho próprio: uma amostra no lançamento e outra a cada 5 minutos, uma linha JSON por amostra, em ~/Library/Application Support/Knobler/desempenho.jsonl. O arquivo cobre os últimos 7 dias (2016 amostras); a gravação comum é só um append, e a poda reescreve o arquivo uma vez a cada ~17 h, quando ele passa 10% desse teto.

Campo O que é
data ISO 8601, com fuso
versao, pid versão do app e processo — um pid novo é um relançamento
uptime_s segundos desde que o processo nasceu (conta o Mac dormindo)
footprint_mb phys_footprint, o número do Monitor de Atividade
residente_mb memória residente
cpu_s CPU acumulada (usuário + sistema) desde o lançamento
cpu_pct CPU desde a amostra anterior, em % de um núcleo (como o top); o intervalo não conta o Mac dormindo
threads threads do processo
notches, displays notches vivos e monitores que o macOS reporta — divergir é sintoma
janelas janelas do app; subir sem motivo é janela que não foi liberada

Como ler: memória que sobe e estabiliza é cache; memória que sobe em rampa com o pid igual é vazamento. Se a rampa acompanha notches, displays ou janelas, o culpado está na troca de monitor.

# footprint e CPU ao longo do tempo
jq -r '[.data, .footprint_mb, .cpu_pct, .notches, .janelas] | @tsv' \
  ~/Library/Application\ Support/Knobler/desempenho.jsonl | tail -50

A última amostra também sai no GET /status, no campo desempenho (ver local-api.md), e cada uma vai pro log unificado (/usr/bin/log stream --info --predicate 'subsystem == "com.zoi.knobler" && category == "desempenho"'). Para um retrato por categoria (Malloc, Image IO, IOSurface) no instante, use footprint -p $(pgrep -x Knobler).

Logs úteis

O app registra no log unificado do macOS com o subsystem com.zoi.knobler. Use o caminho completo /usr/bin/log: no zsh, log sozinho é um comando embutido do shell e não lê nada disso.

# o que aconteceu na última hora
/usr/bin/log show --last 1h --predicate 'subsystem == "com.zoi.knobler"'

# ao vivo, enquanto reproduz o problema
/usr/bin/log stream --predicate 'subsystem == "com.zoi.knobler"'

# uma área só
/usr/bin/log show --last 1h \
  --predicate 'subsystem == "com.zoi.knobler" && category == "api"'
Categoria O que fica registrado
api API local: escutando em 127.0.0.1:4477 quando a porta liga de fato, porta 4477 falhou (… Address already in use); tentativa N, de novo em S s quando outro processo a ocupa, falha ao gerar ou gravar o token das solicitações de agente
teclado taps de teclado (HUD de som e ⌥ direita do ditado; Control direito do desenho): indisponível, de volta, desligado pelo sistema; Acessibilidade concedida ou ausente
midia now playing: adapter quebrado, cada queda do stream com o status de saída, desistência depois de 5 tentativas
audio tap de áudio do visualizador: o status do Core Audio de cada passo que falha (o AudioHardwareCreateProcessTap falha sem a permissão de Áudio do sistema)
ditado falha de transcrição; falha no download do modelo (--download-model)
shelf prateleira: item arrastado que não foi guardado, preview de conversão que falhou ou não salvou
airdrop AirDrop indisponível para os itens
bluetooth leitura da bateria dos AirPods
espelho câmera indisponível
novidades janela de novidades que abriria em branco
notificacoes cada notificação interceptada: o bundle id do app de origem quando ele está aberto; senão o nome sai como hash (<mask.hash: …>), porque pode ser o remetente; o título sai privado
app item de login que não ligou ou não desligou
instancia instância única: a mais nova que assume e encerra a anterior, a anterior que não saiu a tempo e foi forçada
desempenho falha ao gravar ou podar o desempenho.jsonl; cada amostra sai como info (só ao vivo, no log stream --info)
webhook, avisos, TextoDaTela, corte-do-knob relay de webhooks, avisos do desenvolvedor, Texto da tela e o detector do knob cortado

O painel de uso dos agentes (código vendorizado do Codenotch) registra noutro subsystem, com.vinz.codenotch.

Falha sai como error e evento que vale guardar como notice, os dois níveis que o macOS guarda e o log show mostra sem flag extra; info e debug só aparecem ao vivo, no log stream --info/--debug. Nome de arquivo, título de notificação e outro conteúdo do usuário saem como <private>, de propósito: o trecho pode ir num relatório de bug sem expor nada.

Até a 0.36.0 essas mensagens saíam por NSLog, que no macOS 27 chega ao log unificado com o texto inteiro trocado por <private> (a linha aparece como (Foundation) <private>): nessas versões dá pra ver que algo foi registrado, mas não o quê.

Para um relatório de bug, inclua versão do app, macOS, feature afetada, resultado de /status, comando reproduzível e se o problema ocorre em um ou em todos os monitores. Remova tokens, nomes, áudio, imagens e textos privados.