---
read_when:
    - Emparelhando ou reconectando o nó iOS
    - Executando o aplicativo iOS a partir do código-fonte
    - Depuração da descoberta do Gateway ou dos comandos do canvas
summary: 'App de nó iOS: conectar ao Gateway, pareamento, tela e solução de problemas'
title: Aplicativo iOS
x-i18n:
    generated_at: "2026-05-07T13:20:42Z"
    model: gpt-5.5
    provider: openai
    source_hash: 707f8b97156e800f89bc00265c1889c9cbade347fde35f037a302065956346f4
    source_path: platforms/ios.md
    workflow: 16
---

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:

```bash
openclaw gateway --port 18789
```

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

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

```bash
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:

```json5
{
  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.

4. Verifique a conexão:

```bash
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:

```json5
{
  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:

```bash
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:

```bash
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](/pt-BR/gateway/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:

```bash
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](/pt-BR/plugins/codex-computer-use)
para controle de desktop local e esta página para capacidades de nó iOS.

### Eval / instantâneo do Canvas

```bash
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\"; })()"}'
```

```bash
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](/pt-BR/gateway/configuration).
- 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

- [Pareamento](/pt-BR/channels/pairing)
- [Descoberta](/pt-BR/gateway/discovery)
- [Bonjour](/pt-BR/gateway/bonjour)