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:
- Botão Permitir, na linha da Acessibilidade — reabre o diálogo do sistema enquanto o TCC ainda não tiver decisão gravada.
- Botão Revelar o Knobler no Finder — abre o Finder com o app selecionado; no painel do Ajustes do Sistema clique em + e arraste o app pra lista.
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
-
Confirme se o processo está ativo:
pgrep -fl Knobler -
Encerre e abra a cópia instalada:
killall Knobler 2>/dev/null || true open -a /Applications/Knobler.app -
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
-
Ligue Ajustes → Notch → API local.
-
Confira se outra aplicação ocupou a porta:
lsof -nP -iTCP:4477 -sTCP:LISTEN -
O log diz se a porta ligou (
escutando em 127.0.0.1:4477) ou falhou (porta 4477 falhou (… Address already in use); tentativa N, de novo em S s). O app tenta de novo sozinho — 1 s, 2 s, 4 s… até uma vez por minuto —, então basta liberar a porta: a API sobe na tentativa seguinte, sem reabrir o app./usr/bin/log show --last 1h \ --predicate 'subsystem == "com.zoi.knobler" && category == "api"' -
Teste o endpoint mínimo:
curl -i -X POST 127.0.0.1:4477/notify \ -H 'Content-Type: application/json' \ -d '{"title":"teste"}'
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
-
Confirme a API:
curl -sS http://127.0.0.1:4477/status | jq '.ask' -
Para Claude Code, instale o hook e inicie uma nova sessão:
./tools/claude-hook/install.sh -
O hook falha aberto: se o Knobler estiver desligado, cancelado ou sem resposta, a pergunta deve continuar no terminal.
-
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
- Confirme que Ollama ou LM Studio está rodando.
- Confirme endpoint e modelo em Ajustes → Ditado.
- Desative temporariamente “Formatar transcrição” para separar o problema do motor de transcrição.
A falha do formatter deve devolver o transcript bruto; ela não deve impedir o ditado.
Câmera ou espelho não aparece
- Dê acesso à Câmera.
- O espelho só tem seção própria depois de ligado: fixe Espelho em Ajustes › Notch pra chegar nele sem depender da API local.
- "Câmera indisponível" no lugar do preview = abrir o dispositivo falhou:
nenhuma webcam, o USB caiu, ou outro app está com a câmera. Confira
GET /status(mirrorFailed: true,cameraDevice) e o console (knobler mirror: câmera indisponível). Fechar e reabrir o espelho tenta de novo — a preferência é relida a cada abertura. - "Ligando a câmera…" parado por mais de alguns segundos, sem virar "Câmera indisponível", é a câmera acordando devagar (Continuity costuma demorar mais).
- Abra o espelho e escolha a câmera pelo menu quando houver mais de uma.
- Se um dispositivo USB sumiu, volte para “Automática”; a preferência usa
uniqueID, não índice.
Webhook não entrega notificações
- Ligue o recurso e confirme que o perfil não foi rotacionado ou apagado.
- Verifique se o processo do relay está disponível e se o token está no Keychain.
- Use o diagnóstico do app e os logs do processo; não cole tokens em issues.
Nunca recebi um aviso do desenvolvedor
Provavelmente não há nenhum publicado — o canal é raro por natureza. Antes de suspeitar de defeito:
- O app só consulta uma vez por dia (e ~45 s depois de abrir). Um aviso publicado agora pode levar até 24 h.
- Cada aviso aparece uma vez só. Se você já o viu, ele não volta — o
registro fica em
avisos.vistos. - Um aviso pode ser dirigido a uma faixa de versão: "atualize, a 0.19 tem um bug" não é enviado a quem já está na 0.20.
- Com Silenciar durante reuniões ativo e uma reunião acontecendo, o aviso foi direto pro Histórico — role a seção Histórico do card.
- Se o interruptor Ajustes › Geral › Avisos do desenvolvedor está desligado, só os críticos chegam.
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.