- App Store release uses canonical `ai.openclawfoundation.app*` bundle IDs through a temporary generated xcconfig in `apps/ios/build/AppStoreRelease.xcconfig`.

- App Store release uses manual `Apple Distribution` signing with profile names pinned in `apps/ios/Config/AppStoreSigning.json`.

- Fastlane owns one-time Developer Portal setup, encrypted `match` signing sync to the repo/branch pinned in `apps/ios/Config/AppStoreSigning.json`, and release handling.

- App Store release also switches the app to `OpenClawPushTransport=relay`, `OpenClawPushDistribution=official`, `OpenClawPushAPNsEnvironment=production`, `OpenClawPushRelayProfile=production`, `OpenClawPushProofPolicy=appleStrict`, and the App-Attest-capable entitlement file.

- App Store release also switches the app to `OpenClawPushMode=appStore`, which derives relay transport, official distribution, the canonical production relay, production APNs, production relay profile, `appleStrict` proof, and the App-Attest-capable entitlement file.

- `pnpm ios:release:upload` generates App Store screenshots and uploads release notes before archiving and uploading the IPA.

- The release archive is validated before upload by inspecting the exported IPA's signed entitlements, embedded App Store profile, and push mode. The upload fails if the IPA is not an App Store production relay build.

- `pnpm ios:release` remains a compatibility alias for `pnpm ios:release:upload`; prefer the explicit upload command in new release docs and automation.

- App Review submission is manual in App Store Connect. The release lane uploads a build and metadata, but does not submit for review.

- The release flow does not modify `apps/ios/.local-signing.xcconfig` or `apps/ios/LocalSigning.xcconfig`.

Relay behavior for App Store builds:

- Release builds default to `https://ios-push-relay.openclaw.ai`.

- Optional custom relay override: `OPENCLAW_PUSH_RELAY_BASE_URL=https://relay.example.com`

This must be a plain `https://host[:port][/path]` base URL without whitespace, query params, fragments, or xcconfig metacharacters.

- App Store release builds use the canonical hosted relay at `https://ios-push-relay.openclaw.ai`.

- App Store release builds reject custom relay URL overrides. Future self-hosted relay support should use a separate explicit release path, not the public App Store build lane.

Signing setup commands:

Use `pnpm ios:release:signing:setup` for the initial portal setup, then `MATCH_PASSWORD=... pnpm ios:release:signing:sync:push` to publish encrypted Fastlane match assets to the shared private repo.

4. Optional: set a custom official relay URL for the build. If unset, the release flow uses `https://ios-push-relay.openclaw.ai`.

```bash

export OPENCLAW_PUSH_RELAY_BASE_URL=https://relay.example.com

```

5. If you are starting a brand-new production release train, pin iOS to the current gateway version first:

4. If you are starting a brand-new production release train, pin iOS to the current gateway version first:

```bash

pnpm ios:version:pin -- --from-gateway

```

6. Upload the build:

5. Upload the build:

```bash

pnpm ios:release:upload

```

7. Expected behavior:

6. Expected behavior:

- Fastlane reads `apps/ios/version.json`

- verifies synced iOS versioning artifacts

- resolves the next App Store Connect build number for that short version

- generates deterministic App Store screenshots

- uploads release notes and screenshots to the editable App Store version

- generates `apps/ios/build/AppStoreRelease.xcconfig`

- archives `OpenClaw`

- validates the exported IPA's push mode, signed entitlements, and embedded App Store profile

- uploads the IPA to App Store Connect for TestFlight/App Review use

- leaves App Review submission for a maintainer to complete manually

8. Expected outputs after a successful run:

7. Expected outputs after a successful run:

- `apps/ios/build/app-store/OpenClaw-<version>.ipa`

- `apps/ios/build/app-store/OpenClaw-<version>.app.dSYM.zip`

- Fastlane log line like `Uploaded iOS App Store build: version=<version> short=<short> build=<build>`

9. If this is a fresh clone on a maintainer machine that already works elsewhere, it is OK to copy the non-secret `apps/ios/fastlane/.env` from another trusted local clone on the same Mac. The Keychain-backed private key remains machine-local and is not stored in the repo.

8. If this is a fresh clone on a maintainer machine that already works elsewhere, it is OK to copy the non-secret `apps/ios/fastlane/.env` from another trusted local clone on the same Mac. The Keychain-backed private key remains machine-local and is not stored in the repo.

## iOS Versioning Workflow

- `apps/ios/Sources/OpenClaw.entitlements` derives `aps-environment` from the active build configuration/signing override.

- App Attest relay builds use `apps/ios/Sources/OpenClawAppAttest.entitlements`; local/direct builds do not require App Attest provisioning.

- APNs token registration to gateway happens only after gateway connection (`push.apns.register`).

- Local/manual builds default to `OpenClawPushTransport=direct`, `OpenClawPushDistribution=local`, and a development `aps-environment` entitlement.

- Local/manual Debug builds default to `OpenClawPushMode=localSandbox`, direct APNs registration, and a development `aps-environment` entitlement. Local/manual Release builds default to `OpenClawPushMode=localProduction` and direct production APNs registration.

- Your selected team/profile must support Push Notifications for the app bundle ID you are signing.

- If push capability or provisioning is wrong, APNs registration fails at runtime (check Xcode logs for `APNs registration failed`).

- The gateway host also needs direct APNs auth configured separately with `OPENCLAW_APNS_TEAM_ID`, `OPENCLAW_APNS_KEY_ID`, and either `OPENCLAW_APNS_PRIVATE_KEY_P8` or `OPENCLAW_APNS_PRIVATE_KEY_PATH`.

- Recommended gateway-host storage for the APNs `.p8` file is `~/.openclaw/credentials/apns/AuthKey_<KEYID>.p8` with restrictive permissions, then point `OPENCLAW_APNS_PRIVATE_KEY_PATH` at that file.

- `apps/ios/fastlane/.env` only covers App Store Connect / Fastlane auth; it does not provide gateway APNs credentials for local direct-push testing.

- Debug builds default to `OpenClawPushAPNsEnvironment=sandbox`; Release builds default to `production`.

- Debug builds default to sandbox APNs through `OpenClawPushMode=localSandbox`; Release builds default to production APNs through `OpenClawPushMode=localProduction`.

## APNs Expectations For Official Builds

- The relay registration is bound to the gateway identity fetched from `gateway.identity.get`, so another gateway cannot reuse that stored registration.

- The app persists the relay handle metadata locally so reconnects can republish the gateway registration without re-registering on every connect.

- If the relay base URL changes in a later build, the app refreshes the relay registration instead of reusing the old relay origin.

- Production relay mode uses the `production` relay profile, production APNs, App Attest, and a StoreKit app transaction JWS during registration.

- App Store release mode uses the internal `production` relay profile, production APNs, App Attest, and a StoreKit app transaction JWS during registration.

- Gateway-side relay sending is configured through `gateway.push.apns.relay.baseUrl` in `openclaw.json`. `OPENCLAW_APNS_RELAY_BASE_URL` remains a temporary env override only.

## Official Build Relay Trust Model