English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Platforms overview

Aplicativo iOS

Disponibilidade: prévia interna. O aplicativo iOS ainda não é distribuído publicamente.

O que ele faz

  • Conecta-se a um Gateway por WebSocket (LAN ou tailnet).
  • Expõe capacidades do nó: Canvas, instantâneo da tela, captura da câmera, localização, modo Talk, ativação por voz.
  • Recebe comandos node.invoke e relata eventos de status do nó.

Requisitos

  • Gateway em execução em outro dispositivo (macOS, Linux ou Windows via WSL2).
  • Caminho de rede:
    • Mesma LAN via Bonjour, ou
    • Tailnet via DNS-SD unicast (domínio de exemplo: openclaw.internal.), ou
    • Host/porta manual (fallback).

Início rápido (parear + conectar)

  1. Inicie o Gateway:
openclaw gateway --port 18789

  1. No aplicativo iOS, abra Settings e escolha um gateway descoberto (ou habilite Manual Host e insira host/porta).

  2. Aprove a solicitação de pareamento no host do gateway:

openclaw devices list
openclaw devices approve <requestId>

Se o aplicativo tentar parear novamente com detalhes de autenticação alterados (função/escopos/chave pública), a solicitação pendente anterior será substituída e um novo requestId será criado. Execute openclaw devices list novamente antes da aprovação.

Opcional: se o nó iOS sempre se conecta a partir de uma sub-rede estritamente controlada, você pode optar pela aprovação automática de nós no primeiro uso com CIDRs explícitos ou IPs exatos:

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

Isso vem desabilitado por padrão. Aplica-se apenas a pareamentos novos de role: node sem escopos solicitados. Pareamento de operador/navegador e qualquer alteração de função, escopo, metadados ou chave pública ainda exigem aprovação manual.

  1. Verifique a conexão:
openclaw nodes status
openclaw gateway call node.list --params "{}"

Push apoiado por relay para builds oficiais

Builds iOS distribuídos oficialmente usam o relay de push externo em vez de publicar o token APNs bruto no gateway.

Requisito no lado do Gateway:

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
        },
      },
    },
  },
}

Como o fluxo funciona:

  • O aplicativo iOS se registra no relay usando App Attest e um JWS de transação de aplicativo do StoreKit.
  • O relay retorna um identificador opaco de relay mais uma concessão de envio com escopo de registro.
  • O aplicativo iOS busca a identidade do gateway pareado e a inclui no registro do relay, de modo que o registro apoiado por relay seja delegado a esse gateway específico.
  • O aplicativo encaminha esse registro apoiado por relay ao gateway pareado com push.apns.register.
  • O gateway usa esse identificador de relay armazenado para push.test, ativações em segundo plano e nudges de ativação.
  • A URL base do relay do gateway deve corresponder à URL de relay embutida no build iOS oficial/TestFlight.
  • Se o aplicativo se conectar depois a outro gateway ou a um build com uma URL base de relay diferente, ele atualiza o registro do relay em vez de reutilizar o vínculo antigo.

O que o gateway não precisa para esse caminho:

  • Nenhum token de relay em toda a implantação.
  • Nenhuma chave APNs direta para envios oficiais/TestFlight apoiados por relay.

Fluxo esperado do operador:

  1. Instale o build iOS oficial/TestFlight.
  2. Defina gateway.push.apns.relay.baseUrl no gateway.
  3. Pareie o aplicativo com o gateway e deixe-o terminar de conectar.
  4. O aplicativo publica push.apns.register automaticamente depois de ter um token APNs, a sessão do operador estar conectada e o registro do relay ser bem-sucedido.
  5. Depois disso, push.test, ativações de reconexão e nudges de ativação podem usar o registro armazenado apoiado por relay.

Beacons de atividade em segundo plano

Quando o iOS desperta o aplicativo para um push silencioso, atualização em segundo plano ou evento de localização significativa, o aplicativo tenta uma reconexão curta do nó e então chama node.event com event: "node.presence.alive". O gateway registra isso como lastSeenAtMs/lastSeenReason nos metadados do nó/dispositivo pareado somente depois que a identidade autenticada do dispositivo de nó é conhecida.

O aplicativo trata uma ativação em segundo plano como registrada com sucesso somente quando a resposta do gateway inclui handled: true. Gateways mais antigos podem confirmar node.event com { "ok": true }; essa resposta é compatível, mas não conta como uma atualização durável de último visto.

Nota de compatibilidade:

  • OPENCLAW_APNS_RELAY_BASE_URL ainda funciona como uma substituição temporária de env para o gateway.

Fluxo de autenticação e confiança

O relay existe para impor duas restrições que APNs direto no gateway não consegue fornecer para builds iOS oficiais:

  • Somente builds iOS genuínos do OpenClaw distribuídos pela Apple podem usar o relay hospedado.
  • Um gateway pode enviar pushes apoiados por relay apenas para dispositivos iOS que parearam com esse gateway específico.

Etapa por etapa:

  1. iOS app -> gateway

    • O aplicativo primeiro pareia com o gateway por meio do fluxo normal de autenticação do Gateway.
    • Isso dá ao aplicativo uma sessão de nó autenticada mais uma sessão de operador autenticada.
    • A sessão do operador é usada para chamar gateway.identity.get.

  2. iOS app -> relay

    • O aplicativo chama os endpoints de registro do relay via HTTPS.
    • O registro inclui prova do App Attest mais um JWS de transação de aplicativo do StoreKit.
    • O relay valida o ID do pacote, a prova do App Attest e a prova de distribuição da Apple, e exige o caminho de distribuição oficial/produção.
    • Isso é o que bloqueia builds locais de Xcode/dev de usar o relay hospedado. Um build local pode ser assinado, mas não satisfaz a prova de distribuição oficial da Apple esperada pelo relay.

  3. gateway identity delegation

    • Antes do registro do relay, o aplicativo busca a identidade do gateway pareado em gateway.identity.get.
    • O aplicativo inclui essa identidade do gateway no payload de registro do relay.
    • O relay retorna um identificador de relay e uma concessão de envio com escopo de registro delegados a essa identidade de gateway.

  4. gateway -> relay

    • O gateway armazena o identificador de relay e a concessão de envio de push.apns.register.
    • Em push.test, ativações de reconexão e nudges de ativação, o gateway assina a solicitação de envio com sua própria identidade de dispositivo.
    • O relay verifica tanto a concessão de envio armazenada quanto a assinatura do gateway em relação à identidade de gateway delegada no registro.
    • Outro gateway não pode reutilizar esse registro armazenado, mesmo que de alguma forma obtenha o identificador.

  5. relay -> APNs

    • O relay possui as credenciais APNs de produção e o token APNs bruto do build oficial.
    • O gateway nunca armazena o token APNs bruto para builds oficiais apoiados por relay.
    • O relay envia o push final para APNs em nome do gateway pareado.

Por que este design foi criado:

  • Para manter credenciais APNs de produção fora dos gateways de usuários.
  • Para evitar armazenar tokens APNs brutos de builds oficiais no gateway.
  • Para permitir o uso do relay hospedado somente para builds OpenClaw oficiais/TestFlight.
  • Para impedir que um gateway envie pushes de ativação a dispositivos iOS pertencentes a outro gateway.

Builds locais/manuais permanecem em APNs direto. Se você estiver testando esses builds sem o relay, o gateway ainda precisa de credenciais APNs diretas:

export OPENCLAW_APNS_TEAM_ID="TEAMID"
export OPENCLAW_APNS_KEY_ID="KEYID"
export OPENCLAW_APNS_PRIVATE_KEY_P8="$(cat /path/to/AuthKey_KEYID.p8)"

Estas são variáveis de env de runtime do host do gateway, não configurações do Fastlane. apps/ios/fastlane/.env armazena apenas autenticação do App Store Connect / TestFlight, como ASC_KEY_ID e ASC_ISSUER_ID; ele não configura entrega APNs direta para builds iOS locais.

Armazenamento recomendado no host do gateway:

mkdir -p ~/.openclaw/credentials/apns
chmod 700 ~/.openclaw/credentials/apns
mv /path/to/AuthKey_KEYID.p8 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
chmod 600 ~/.openclaw/credentials/apns/AuthKey_KEYID.p8
export OPENCLAW_APNS_PRIVATE_KEY_PATH="$HOME/.openclaw/credentials/apns/AuthKey_KEYID.p8"

Não faça commit do arquivo .p8 nem o coloque dentro do checkout do repositório.

Caminhos de descoberta

Bonjour (LAN)

O aplicativo iOS navega por _openclaw-gw._tcp em local. e, quando configurado, pelo mesmo domínio de descoberta DNS-SD de área ampla. Gateways na mesma LAN aparecem automaticamente a partir de local.; a descoberta entre redes pode usar o domínio de área ampla configurado sem alterar o tipo de beacon.

Tailnet (entre redes)

Se mDNS estiver bloqueado, use uma zona DNS-SD unicast (escolha um domínio; exemplo: openclaw.internal.) e DNS dividido do Tailscale. Consulte Bonjour para o exemplo de CoreDNS.

Host/porta manual

Em Settings, habilite Manual Host e insira o host + porta do gateway (padrão 18789).

Canvas + A2UI

O nó iOS renderiza um canvas WKWebView. Use node.invoke para controlá-lo:

openclaw nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18789/__openclaw__/canvas/"}'

Notas:

  • O host de canvas do Gateway serve /__openclaw__/canvas/ e /__openclaw__/a2ui/.
  • Ele é servido pelo servidor HTTP do Gateway (mesma porta que gateway.port, padrão 18789).
  • O nó iOS navega automaticamente para A2UI ao conectar quando uma URL de host de canvas é anunciada.
  • Retorne ao scaffold integrado com canvas.navigate e {"url":""}.

Relação com Computer Use

O aplicativo iOS é uma superfície de nó móvel, não um backend Codex Computer Use. Codex Computer Use e cua-driver mcp controlam um desktop macOS local por meio de ferramentas MCP; o aplicativo iOS expõe capacidades do iPhone por meio de comandos de nó do OpenClaw como canvas.*, camera.*, screen.*, location.* e talk.*.

Agentes ainda podem operar o aplicativo iOS por meio do OpenClaw invocando comandos de nó, mas essas chamadas passam pelo protocolo de nó do gateway e seguem os limites de primeiro/segundo plano do iOS. Use Codex Computer Use para controle de desktop local e esta página para capacidades de nó iOS.

Eval / instantâneo do Canvas

openclaw nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__openclaw; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'

openclaw nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'

Ativação por voz + modo Talk

  • Ativação por voz e modo Talk estão disponíveis em Settings.
  • Nós iOS compatíveis com Talk anunciam a capacidade talk e podem declarar talk.ptt.start, talk.ptt.stop, talk.ptt.cancel e talk.ptt.once; o Gateway permite esses comandos push-to-talk por padrão para nós confiáveis compatíveis com Talk.
  • O iOS pode suspender áudio em segundo plano; trate os recursos de voz como melhor esforço quando o aplicativo não estiver ativo.

Erros comuns

  • NODE_BACKGROUND_UNAVAILABLE: traga o aplicativo iOS para primeiro plano (comandos de canvas/câmera/tela exigem isso).
  • A2UI_HOST_NOT_CONFIGURED: o Gateway não anunciou a URL da superfície do Plugin Canvas; verifique plugins.entries.canvas.config.host em configuração do Gateway.
  • Prompt de pareamento nunca aparece: execute openclaw devices list e aprove manualmente.
  • Reconexão falha após reinstalação: o token de pareamento do Keychain foi limpo; pareie o nó novamente.

Documentos relacionados