PandaPaw: Host Remoto para Claude Code, Codex e PandaCode

O PandaPaw transforma uma máquina Windows, macOS ou Linux que você controla em um host de agente PandaNpc. O mecanismo de codificação, os arquivos do projeto, o shell e as ferramentas permanecem nesse host; os clientes PandaNpc fornecem uma interface sincronizada a partir de um telefone, navegador ou outro desktop.

Use o PandaPaw quando a máquina que executa o trabalho for diferente do dispositivo que você está segurando, quando você quiser que um host sobreviva a desconexões do cliente ou quando vários mecanismos de codificação compartilharem a mesma configuração baseada em conta e a configuração da Central de Agentes.

O que o PandaPaw gerencia

• Conexões remotas de agente para Claude Code, OpenAI Codex e PandaCode.
• Serviços em segundo plano e inicialização automática para que o host possa voltar após uma reinicialização normal.
• Autorização de máquina baseada em conta, sem copiar manualmente um Bridge ID, token ou chave de assinatura de longa duração.
• Assistência de instalação de mecanismo quando um mecanismo de codificação compatível estiver ausente.
• Projeções da Central de Agentes que renderizam as orientações, habilidades, memória e definições de agente de cada mecanismo em seu layout nativo.
• Rede privada de dispositivos para máquinas integradas pelo fluxo de Dispositivos Conectados.
• Registro de atualização e desinstalação para que as ferramentas que existiam antes do PandaPaw sejam preservadas.

O PandaPaw não fornece uma assinatura de modelo por conta própria. O Claude Code, o Codex e o PandaCode continuam usando as credenciais do provedor e os limites configurados para seus mecanismos.

Como funciona a execução remota

Ambos os lados iniciam conexões de saída; portanto, uma configuração doméstica ou de escritório normal não exige regra de firewall de entrada, endereço IP público, encaminhamento de porta no roteador ou servidor SSH exposto publicamente. O relay transporta mensagens, status e aprovações; a execução de ferramentas acontece no host.

Se o host entrar em suspensão, for desligado ou perder o caminho de rede de saída, a conexão salva permanece na sua conta, mas não poderá executar trabalho até que o host volte.

Plataformas de host compatíveis

O cliente de visualização PandaNpc tem uma matriz de plataformas mais ampla. Consulte Instalar o PandaNpc e o PandaPaw ao escolher os pacotes de cliente e host.

Instalação recomendada

1. Faça login no PandaNpc.
2. Abra Dispositivos Conectados.
3. Escolha Adicionar um dispositivo. Uma chave de uso único é emitida e a caixa de diálogo mostra um comando para o sistema operacional detectado.
4. Copie esse comando para o host e execute-o nele.
5. Deixe a caixa de diálogo aberta se quiser que ela detecte a nova máquina automaticamente.

A chave preparada é de uso único. Copie o comando inteiro, mantenha-o privado e gere uma nova chave se ela expirar ou já tiver sido resgatada.

Instalador simples para macOS/Linux

Use este formato quando quiser autorização pelo navegador em vez de uma chave preparada:

curl -fsSL https://cos.pandanpc.com/pandapaw/install.sh | sh

Instalador simples para Windows PowerShell

iwr -useb https://cos.pandanpc.com/pandapaw/install.ps1 | iex

O instalador simples executa pandapaw login. Aprove a máquina na página do navegador que ele abrir. Se a autorização for interrompida, o binário e os serviços ainda poderão ser instalados; execute pandapaw login mais tarde para concluir a conexão da conta.

Verificar o host

Primeiro verifique o próprio host:

pandapaw status

Em seguida, abra o Agente PandaNpc e confirme se a máquina tem um indicador verde de online. Inicie uma sessão em um diretório de teste descartável ou somente leitura e pergunte:

Prompt de teste: Imprima o diretório de trabalho atual e liste os arquivos de nível superior. Não modifique nada.

Uma resposta bem-sucedida prova mais do que uma luz de status verde: ela verifica o pareamento da conta, a conectividade do relay, o mecanismo selecionado, a autenticação do provedor e o mapeamento do diretório de trabalho.

Para um projeto da Central de Agentes, execute:

pandapaw agent status --root /absolute/path/to/project

Isso mostra se o projeto está vinculado e se a configuração gerenciada está disponível localmente. Um remote Git estável ajuda o PandaPaw a identificar o mesmo projeto em várias máquinas.

Autorização de conta e identidade de conexão

O pandapaw login usa uma sessão de autorização de dispositivo pelo navegador. Depois que você a aprova, o host recebe credenciais com escopo de dispositivo e uma chave de verificação da Central de Agentes por TLS, grava sua configuração de máquina em ~/.pandapaw/, registra as conexões de mecanismo compatíveis e vincula projetos Git reconhecíveis.

Execute pandapaw login --force somente ao trocar de conta intencionalmente ou substituir uma credencial de host expirada. Reautorizar uma máquina saudável sem motivo pode criar identidades duplicadas ou substituídas confusas.

O pandapaw qr ainda cria um link de conexão manual de curta duração para compatibilidade e casos especiais. Ele não é o fluxo principal para um novo host; os Dispositivos Conectados são mais fáceis de auditar e não exigem que os usuários entendam IDs de Bridge.

Sincronização da Central de Agentes

A Central de Agentes é orientada a eventos em estado estável:

1. Alterações locais em arquivos gerenciados são detectadas e publicadas no projeto vinculado.
2. Versões assinadas chegam por meio de um fluxo de eventos.
3. Manifestos e blobs de conteúdo inalterados são reutilizados em vez de baixados novamente.
4. Uma verificação periódica de recuperação captura eventos perdidos durante uma desconexão temporária.

O Claude Code, o Codex e o PandaCode recebem projeções separadas porque esperam diretórios e formatos de instrução diferentes. O PandaCode prepara a versão verificada mais recente antes de montar um novo prompt de sessão, para que a configuração obtida na inicialização possa afetar essa mesma sessão.

Se a Central de Agentes estiver temporariamente indisponível, o mecanismo continua com a última versão local verificada. Uma falha de rede não deve substituir silenciosamente a configuração assinada por conteúdo não verificado.

Comandos úteis

pandapaw login
pandapaw status
pandapaw agent status --root /absolute/path/to/project
pandapaw update --restart
pandapaw uninstall

Consulte o histórico de versões do PandaPaw quando um comando ou UI diferir de uma captura de tela ou tutorial mais antigo.

Limites de segurança

• Um operador remoto pode usar quaisquer ferramentas e o diretório de trabalho que a sessão de agente selecionada permitir. O acesso remoto não é automaticamente somente leitura.
• Mantenha comandos de dispositivo de uso único, links de conexão manual, chaves do provedor e tokens de conta fora de logs e capturas de tela.
• Não abra portas de entrada no roteador apenas para tornar o PandaPaw acessível.
• Remova de Dispositivos Conectados os hosts que você não possui mais.
• Revise as aprovações de ferramentas e verifique o diretório de trabalho antes de permitir edições ou comandos de shell.
• Ao compartilhar uma conexão ao vivo, o destinatário consome a cota do mecanismo do proprietário do host e pode agir no host. Leia Compartilhamento de conexão primeiro.

Solução de problemas

`pandapaw` não é encontrado após a instalação

Abra um novo terminal para que ele recarregue o PATH do usuário. Os locais normais são ~/.local/bin no macOS/Linux e %LOCALAPPDATA%\Programs\pandapaw no Windows. Confirme que o arquivo existe antes de executar o instalador novamente.

A instalação foi bem-sucedida, mas nenhuma máquina aparece

Execute pandapaw status. Se a máquina não tiver autorização de conta, execute pandapaw login. Se uma chave de uso único preparada foi usada, crie uma nova chave em vez de tentar novamente um comando já consumido.

A máquina aparece, mas permanece offline

Confirme que o host está ativo e tem acesso à internet. Verifique o status do PandaPaw localmente. Um proxy ou firewall corporativo deve permitir o caminho de saída HTTPS/WebSocket; uma porta de entrada não resolve uma conexão de saída bloqueada.

O host está online, mas o Claude Code ou o Codex não responde

Parear o host não autentica todos os provedores de modelo. Abra o mecanismo localmente ou siga o prompt de login mostrado na sessão remota. Confirme também que o modelo selecionado existe para essa conta e que o limite de uso não foi esgotado.

A sessão abre no projeto errado

Encerre o teste, selecione o diretório de trabalho absoluto pretendido e peça ao agente para imprimi-lo antes de aprovar ferramentas. O PandaPaw não adivinha qual repositório você quis dizer e não adiciona uma sandbox de sistema de arquivos além do modelo de permissão do próprio mecanismo.

Alterações da Central de Agentes não aparecem

Execute pandapaw agent status --root /path/to/project a partir da raiz Git correta. Confirme se o projeto está vinculado, se o host está conectado e se o arquivo local faz parte de uma projeção gerenciada. Mantenha a última versão verificada no lugar durante a investigação, em vez de excluir diretórios gerenciados.

Atualização e desinstalação

O pandapaw update --restart baixa o binário atual, verifica sua soma de verificação SHA-256, substitui a cópia instalada e reinicia os serviços gerenciados para que a versão se torne ativa. O pareamento de conta existente é preservado.

O pandapaw uninstall usa o manifesto de instalação para remover itens criados pelo PandaPaw. Instalações compatíveis de Claude Code, Codex, PandaCode ou Node que já estavam presentes são intencionalmente preservadas. Após desinstalar, remova o host de Dispositivos Conectados se ele não precisar mais ser confiável.