docs: iOS managed app — provider quick-connect and model switching guides

[Copilot]

No documentation existed for how a managed iOS app (with Supabase auth + AKS-hosted OpenClaw containers) should implement provider authentication or model switching. Each provider has a different auth pattern; without a concrete guide, iOS app developers have to reverse-engineer the CLI flows. Model switching is a distinct concern from provider auth and warrants its own reference.

Summary

• Problem: No guidance for implementing provider auth, model switching, or surfacing model controls in the UI of a managed iOS app fronting per-user OpenClaw containers.
• Why it matters: Each provider has a materially different auth surface (API key vs OAuth vs device flow vs setup-token vs AWS credentials); model switching has its own config keys and allowlist behavior; and iOS developers need concrete UI placement guidance to wire these controls correctly. Consolidated, separated references prevent ad-hoc guesswork in the iOS codebase.
• What changed: New dean/ios-managed-app.md covering all provider auth patterns; new dean/ios-model-switching.md covering model picker UI, primary/fallback/allowlist/image model config, filtering by connected providers, and recommended UI surfaces (nav bar quick-switch badge + settings row). The docs/docs.json nav entry previously added under install/ios-managed-app has been removed.
• What did NOT change: No runtime code, no existing docs modified.

New: dean/ios-managed-app.md — guide organized by auth type:

Auth pattern	Providers
API key SecureField + file-api write	OpenAI, Anthropic, Mistral, Together AI, OpenRouter, Venice, HuggingFace, MiniMax, Moonshot, NVIDIA, GLM, Qianfan, Kilocode, Xiaomi, Z.AI, Deepgram, Vercel AI Gateway
ASWebAuthenticationSession OAuth	OpenAI Codex, GitHub Copilot
Device-code flow (code + URL in UI)	GitHub Copilot (fallback), Qwen
Setup-token paste	Anthropic Claude subscription
Two-field AWS credentials form	Amazon Bedrock
Endpoint URL only	Ollama, vLLM, sglang, LiteLLM, Cloudflare AI Gateway

Core pattern for every token/key provider — read → merge → write openclaw.json via the file-api bridge (authenticated with the user's Supabase JWT):

func saveProviderKey(envKey: String, value: String) async throws {
    var config = try await fileAPI.readOpenClawConfig()
    config.env[envKey] = value
    try await fileAPI.writeOpenClawConfig(config)
    try await fileAPI.reloadGateway()
}

Includes a full AddProviderView SwiftUI picker that wires all flows through navigationDestination, plus a security considerations section covering key masking, OAuth scope minimization, and AWS IAM hygiene.

New: dean/ios-model-switching.md — separate guide covering:

• Core read → patch primary → write → reload pattern
• Swift ModelEntry catalog with frontier/balanced/fast/local tiers
• Full ModelPickerView SwiftUI component with grouped sections and live selection feedback
• setFallbacks() helper for ordered fallback lists
• setAllowlist() to restrict in-session /model switching (cost control)
• setImageModel() for image-processing workflows
• Filtering the picker to only show models whose provider the user has already connected
• Model ref format notes (OpenRouter double-slash, alias normalization, case-insensitivity)
• Security notes: allowlist for cost control, JWT validation at file-API layer
• Recommended UI surfaces: tappable model badge in the chat NavigationBar (sheet presentation for quick in-session switching) + a "Model" settings row for persistent preference and advanced config (fallbacks, allowlist)

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related #

User-visible / Behavior Changes

None. Docs only.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: N/A (docs)
• Runtime/container: N/A
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. Open dean/ios-managed-app.md for provider quick-connect patterns
2. Open dean/ios-model-switching.md for model switching patterns and UI surface recommendations
3. Navigate to the section relevant to your integration and follow the pattern

Expected

• Clear per-provider iOS implementation pattern with working Swift code snippets
• Separate model switching guide with SwiftUI picker, fallback/allowlist helpers, filtering by connected providers, and recommended UI placement

Actual

• Two focused guides: provider auth (30+ providers, 6 auth patterns) and model switching (picker UI, fallbacks, allowlist, image model, UI surface recommendations, security notes)

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Docs-only change; no runtime evidence applicable.

Human Verification (required)

• Verified scenarios: All provider sections reviewed against existing docs/providers/*.md for accuracy (env key names, base URLs, model IDs). Model switching config keys verified against docs/concepts/models.md and docs/cli/models.md. UI surface recommendations verified against common iOS AI chat app patterns.
• Edge cases checked: Qianfan (two-key provider), Bedrock (IAM security note), Anthropic (two distinct flows — API key vs setup-token), GitHub Copilot (OAuth + device-flow fallback), OpenRouter double-slash model refs, allowlist empty-vs-set behavior.
• What you did not verify: Live OAuth round-trip from an actual iOS build against the described endpoints.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Delete dean/ios-managed-app.md and/or dean/ios-model-switching.md.
• Files/config to restore: None (no docs/docs.json nav entry was added).
• Known bad symptoms reviewers should watch for: None; docs-only change.

Risks and Mitigations

• Risk: Swift code snippets may drift from actual iOS SDK APIs as the iOS app evolves.
  • Mitigation: Snippets are intentionally conceptual/annotated (// adapt to your actual file-api client) rather than copy-paste production code.
• Risk: Model catalog in ios-model-switching.md may drift from available models as providers release new versions.
  • Mitigation: Catalog is illustrative; comments indicate entries should be updated alongside provider changes.
• Risk: UI surface recommendations may not match the actual app's navigation structure.
  • Mitigation: Recommendations are patterns (nav bar badge + settings row), not prescriptive component names; adapt placement to the existing app navigation hierarchy.

Original prompt

Can you write a markdown per provider on how you would implement a quick connect of thr provider (options from token for OpenAI to full e2e flows to quick auth if we build an app to using your app) assuming users are running OpenClaw through a managed iOS app. See details on the arch below

OpenClaw iOS App

OpenClaw is a premium iOS application that provides users with their own personal AI assistant powered by Claude, running in dedicated containers in the cloud.

What is OpenClaw?

OpenClaw gives each user their own private AI assistant with:

• Personal AI Container: Each user gets an exclusive OpenClaw instance running in Azure Kubernetes Service
• Secure & Private: Your conversations and data stay private in your dedicated container
• File Storage: Store and access files in your personal workspace
• Real-time Chat: WebSocket-based chat interface with typing indicators
• Mobile-First: Native iOS app built with SwiftUI

Architecture

┌─────────────────┐    ┌──────────────┐    ┌──────────────────────────┐
│                 │    │              │    │  Azure Cloud (AKS)       │
│   iOS App       │◄──►│  Supabase    │    │                          │
│  (SwiftUI)      │    │  (Auth + DB) │    │  ┌────────────────────┐  │
│                 │    │              │    │  │  OpenClaw Pods 1-N  │  │
│ • Authentication│    │ • Users      │    │  │  (ClusterIP only)   │  │
│ • Subscription  │    │ • Containers │    │  └─────────┬──────────┘  │
│ • Chat UI       │    │ • RLS        │    │            │ Azure Files │
│ • File Browser  │    │              │    │  ┌─────────┴──────────┐  │
│                 │    │              │    │  │  file-api pod       │  │
└────────┬────────┘    └──────────────┘    │  │  (Cloudflare Tunnel)│  │
         │                                 │  └────────────────────┘  │
         │  HTTPS + Supabase JWT           │                          │
         └──▶ files.spark.ooo ─────────────┘                          │
                                           └──────────────────────────┘

The file-api pod is a dedicated Node.js server exposed via Cloudflare Tunnel
(files.spark.ooo) that handles all file operations (browse, read, write, delete) for the
iOS app. It authenticates using the user's Supabase JWT and mounts the same Azure Files
share as the OpenClaw pods. See docs/ for full documentation.

Prerequisites

Development Tools

• Xcode 15.0+ with iOS 17+ SDK
• Azure CLI (brew install azure-cli)
• kubectl (brew install kubectl)
• Git (for version control)

Accounts Required

• Apple Developer Account (for App Store Connect, StoreKit testing)
• Azure Subscription (for cloud infrastructure)
• Supabase Account (for authentication and database)
• Anthropic Account (for Claude API access)

Local Setup

# Install dependencies
brew install azure-cli kubectl jq
npm install -g @supabase/cli

# Clone the repository
git clone https://github.com/deankroker/claw.git
cd claw

Setup Instructions

1. Deploy Azure Infrastructure

# Login to Azure
az login

# Create resource group
az group create --name openclaw-dev --location "East US 2"

# Deploy infrastructure
az deployment group create \
  --resource-group openclaw-dev \
  --template-file infra/main.bicep \
  --parameters @infra/parameters.json

# Get deployment outputs
az deployment group show \
  --resource-group openclaw-dev \
  --name main \
  --query properties.outputs

2. Set Up Supabase

# Initialize Supabase project
supabase init

# Link to your Supabase project
supabase link --project-ref YOUR_PROJECT_REF

# Run database migrations
supabase db push

# Seed database (development only)
psql -h YOUR_DB_HOST -d postgres -U postgres -f supabase/seed.sql

3. Configure the iOS App

Create Claw/Config.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>SupabaseURL</key>
    <string>https://your-project.supabase.co</string>
    <key>SupabaseAnonKey</key>
    <string>your-anon-key</string>
    <key>FileAPIURL</key>
    <string>https://files.spark.ooo</string>
</dict>
</plist>

FileAPIURL is the Cloudflare Tunnel endpoint for the file-api pod. See step 5b below.

4. Configure StoreKit

1. In App Store Connect, create your app
2. Add the subscription product: com.openclaw.monthly ($19.99/month)
3. Create a StoreKit configuration file in Xcode
4. Add the product to your configuration

5a. Provision Container Pool

# Set environment variables
export RESOURCE_GROUP="openclaw-dev"
export AKS_CLUSTER="openclaw-dev-aks"
export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_SERVICE_ROLE_KEY="your-service-role-key"

# Provision containers
./infra/scripts/provision-pool.sh --count 10

5b. Deploy File API

The file-api ...

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[deankroker]

Add to /dean folder instead of docs please @copilot

[Copilot]

Add to /dean folder instead of docs please @copilot

Done — moved to dean/ios-managed-app.md and removed the docs/docs.json nav entry (commit 8593911).

[deankroker]

Or you know what i think it'd be good to have model switching be separate @copilot

[Copilot]

Or you know what i think it'd be good to have model switching be separate @copilot

Added dean/ios-model-switching.md as a standalone guide covering the model picker UI, setting primary/fallback/allowlist/image models via the file-API bridge, filtering by connected providers, and model ref format notes (commit 89a9506).

[deankroker]

Cool @copilot so how would you recommend controls of changing this to surface in the ui?

[Copilot]

Cool @copilot so how would you recommend controls of changing this to surface in the ui?

Two surfaces work well together:

1. Chat navigation bar (quick switch)
Put a tappable model badge in the leading/center of the NavigationBar on the conversation screen. Tapping it presents ModelPickerView as a sheet. This mirrors how ChatGPT and Claude mobile surface model switching — users can change mid-session without leaving the conversation.

.toolbar {
    ToolbarItem(placement: .principal) {
        Button {
            showModelPicker = true
        } label: {
            HStack(spacing: 4) {
                Text(currentModelDisplayName)
                    .font(.headline)
                Image(systemName: "chevron.down")
                    .imageScale(.small)
            }
        }
        .sheet(isPresented: $showModelPicker) {
            ModelPickerView(fileAPI: fileAPI)
        }
    }
}

2. Settings screen (persistent preference)
A "Model" row under a "AI" or "Assistant" settings section that pushes into ModelPickerView. This is where users set their baseline preference and configure fallbacks/allowlist. It's the right home for the more advanced options (fallback list, allowlist, image model).

The two-surface approach means:

• Nav bar badge → casual in-session switching (shows current model at a glance)
• Settings row → deliberate preference + advanced config

Filter both surfaces using availableModels(connectedProviders:) from the guide so users only see models for providers they've already connected.