Integração do App macOS

Visão Geral

Este guia descreve a experiência de integração do primeiro uso do aplicativo macOS do Clawdbot, cobrindo a configuração desde o lançamento inicial até o bootstrap do agente.

Fluxo de Configuração

A integração segue 8 etapas:

Etapa 1: Boas-vindas

Tela de boas-vindas inicial com aviso de segurança sobre as capacidades do Clawdbot.

Etapa 2: Seleção do Gateway

Escolha seu modo de Gateway:

Etapa 3: Autenticação

Para configurações locais, autentique-se com seu provedor de IA:

• Anthropic OAuth - Para assinantes Claude Pro/Max
• Anthropic API Key - Acesso direto à API
• OpenAI - Modelos GPT
• Outros Provedores - Várias opções

O fluxo OAuth abre seu navegador para autenticação PKCE. Cole o valor código/estado quando solicitado.

Credenciais armazenadas em: ~/.clawdbot/credentials/oauth.json

Etapa 4: Assistente de Configuração

Configuração guiada pelo Gateway para:

• Configurações de porta e rede
• Integrações de canais
• Instalação de habilidades

Etapa 5: Permissões

O macOS requer concessões explícitas de permissão:

Conceda permissões conforme solicitado. Alguns recursos requerem permissões específicas para funcionar.

Etapa 6: Instalação do CLI

Instalação opcional do comando global clawdbot:

# Instalado em /usr/local/bin/clawdbot
clawdbot --version

Etapa 7: Chat de Integração

Uma sessão dedicada para introdução do agente:

• O agente cria o espaço de trabalho (~/.clawdbot/workspace)
• Inicializa arquivos iniciais: AGENTS.md, BOOTSTRAP.md, IDENTITY.md, USER.md
• Realiza Q&A para personalizar sua experiência
• Aprende suas preferências e casos de uso

Etapa 8: Pronto

Configuração completa. Agora você pode:

• Conversar com seu assistente
• Configurar canais adicionais
• Instalar habilidades
• Personalizar seu espaço de trabalho

Modos do Gateway

Modo Local

• O Gateway executa no seu Mac
• Fluxos OAuth funcionam diretamente
• Credenciais armazenadas localmente
• Melhor para uso pessoal

Modo Remoto

Ao usar um Gateway remoto:

• Todas as credenciais residem no host do Gateway
• Arquivos do espaço de trabalho estão na máquina remota
• O Mac local atua apenas como cliente
• Útil para implantações compartilhadas ou em servidor

Bootstrap do Agente

Na primeira execução, o agente:

1. Cria o diretório do espaço de trabalho
2. Inicializa arquivos de instrução
3. Realiza Q&A de personalização
4. Configura preferências iniciais

Arquivos de Bootstrap

Solução de Problemas

Problemas de Permissão

Se recursos não funcionarem:

1. Abra Preferências do Sistema → Privacidade e Segurança
2. Verifique cada categoria de permissão
3. Certifique-se de que o Clawdbot está habilitado
4. Reinicie o app se necessário

Falhas de OAuth

Se a autenticação falhar:

1. Verifique sua conexão com a internet
2. Confirme o status da sua assinatura
3. Tente inserir a chave de API manualmente
4. Verifique ~/.clawdbot/credentials/ para problemas

O Gateway Não Inicia

1. Verifique se a porta 18789 está disponível
2. Revise os logs em /tmp/clawdbot/
3. Tente clawdbot health pelo terminal

Próximos Passos

• Guia de Configuração - Configuração detalhada
• Construindo um Assistente - Crie seu assistente
• Canais - Conectar plataformas de mensagens