oomi-ai

Managed Oomi channel, bridge, voice, and persona app API tooling for OpenClaw.

oomi-ai connects an OpenClaw machine to Oomi. Persona UI creation and rendering happen inside Oomi-managed systems. The OpenClaw machine uses API actions only.

The current model is:

• OpenClaw talks to Oomi through managed channel and bridge APIs.
• Oomi clients render persona apps from approved templates, components, data bindings, actions, and permissions.
• The agent may inspect and update persona app state through approved Oomi API actions.
• The user adds persona apps from the Oomi client so platform permissions and data hydration happen in the right place.

What This Package Ships

1. OpenClaw channel extension

• File: openclaw.extension.js
• Purpose: managed text transport through the Oomi backend channel API.

2. Local bridge and CLI

• Files: bin/oomi-ai.js, bin/sessionBridgeState.js
• Purpose: pair a device, manage the OpenClaw bridge worker, and support managed gateway traffic for device-backed chat and voice.

3. Persona app API tools

• Files: persona-app/*, lib/personaApiClient.js, bin/oomi-ai.js
• Purpose: inspect account-linked component-composed persona apps and apply approved backend actions.

4. Permissioned context tools

• Files: lib/personaApiClient.js, bin/oomi-ai.js
• Purpose: read user-approved Oomi backend context, such as HealthKit summaries synced by the mobile app.

5. Agent/operator instructions

• Files: agent_instructions.md, skills/oomi/*
• Purpose: tell OpenClaw agents how to connect, repair, and use Oomi without local UI code generation.

Boundary

Persona UI is an Oomi-managed client capability, not an OpenClaw-machine responsibility.

This package exposes connection, bridge, voice, and persona app state APIs. It does not include a local persona app workspace, local persona runtime manager, queued UI job runner, or app framework bundle.

Install And Upgrade

Global install:

pnpm add -g oomi-ai@latest

Fallback:

npm install -g oomi-ai@latest

Install or update the OpenClaw plugin:

openclaw plugins install oomi-ai@latest

After upgrading, refresh the running bridge so stale gateway connections do not keep using the previous package:

oomi openclaw refresh --skip-version-check
oomi openclaw bridge ps

If the bridge still looks stale, restart it explicitly:

oomi openclaw bridge restart --detach
oomi openclaw bridge ps

On macOS supervised installs:

oomi openclaw bridge service restart
oomi openclaw bridge service status

Healthy update expectation:

• exactly one bridge worker is active
• the worker reports the newly installed package version
• bridge status reaches connected

Standard Connect Flow

Pair the machine:

oomi openclaw pair --app-url https://www.oomi.ai --no-start

Print the OpenClaw config:

oomi openclaw plugin --show-secrets --backend-url https://api.oomi.ai

Apply the printed channels.oomi.accounts.default config and restart OpenClaw.

Start or repair the bridge:

oomi openclaw bridge ensure --detach

Configuration

OpenClaw channel config lives under:

{
  "channels": {
    "oomi": {
      "defaultAccountId": "default",
      "accounts": {
        "default": {
          "backendUrl": "https://api.oomi.ai",
          "deviceToken": "...",
          "defaultSessionKey": "agent:main:webchat:channel:oomi",
          "requestTimeoutMs": 15000
        }
      }
    }
  }
}

Required fields:

• backendUrl
• deviceToken

Optional fields:

• defaultSessionKey
• requestTimeoutMs

Persona App API Tools

Component-composed persona apps are the default Oomi mini-app path. Use these commands when the user asks about or updates an existing Oomi persona app such as Fitness Today:

oomi persona-apps list --json
oomi persona-apps show fitness-today --json
oomi persona-apps apply-action fitness-today --action fitness.complete_workout --payload-json '{"goalId":"easy-run","minutes":20}' --json

Rules for agents:

• Answer from returned appState.bindings, not from memory.
• Apply updates only through approved persona-apps apply-action actions.
• If the persona app does not exist, tell the user to add it from the Oomi client first.
• Do not create local persona UI projects.

For the Fitness v0 slice:

oomi persona-apps apply-action fitness-today --action fitness.complete_goal --payload-json '{"goalId":"easy-run"}' --json
oomi persona-apps apply-action fitness-today --action fitness.complete_workout --payload-json '{"goalId":"easy-run","minutes":20}' --json

Context Tools

Use context tools when the user asks a data-backed question that should come from Oomi-approved mobile permissions, not model memory. For health and fitness questions, read the latest backend HealthKit context first:

oomi context health --json

Rules for agents:

• Answer from healthContext.summary and healthContext.derived.
• Respect healthContext.agentGuidance.canAnswerFromContext.
• If healthContext.agentGuidance.recommendedCommand is present, run it before answering current/latest health questions.
• If context is stale or needs_sync, run oomi context health sync --wait --json; answer only after fresh context is uploaded, or tell the user the phone sync is still pending if it times out.
• If context is missing, permission_denied, disabled_by_user, or unavailable, tell the user what repair action is needed instead of guessing.
• Never present stale HealthKit values as current values.
• Do not ask the phone for HealthKit directly; the Oomi mobile app syncs HealthKit to the backend.

Voice Contract

Managed voice uses the same Oomi plugin and bridge layer as managed chat.

For assistant replies, visible chat text stays user-facing. Optional hidden TTS metadata may live at metadata.spoken:

{
  "metadata": {
    "spoken": {
      "text": "Speech-optimized text for TTS only.",
      "language": "English",
      "instructions": "Speak with warm, upbeat conversational energy and natural pacing."
    }
  }
}

Rules:

• visible content is the source of truth for chat rendering
• metadata.spoken.text is backend TTS input only
• visible chat text should not contain raw speaking tags
• the package preserves valid metadata.spoken
• if omitted, the package may synthesize a bounded fallback from visible assistant text

Health Checks

Use these when chat or voice is failing:

oomi openclaw bridge ps
oomi openclaw bridge service status
oomi openclaw status
tail -f ~/.openclaw/logs/oomi-bridge-live.log
tail -f ~/.openclaw/logs/gateway.log
tail -f ~/.openclaw/logs/gateway.err.log

Bridge status meanings:

• starting: bridge booting or waiting for managed subscription
• connected: ready for managed chat and voice traffic
• reconnecting: transport dropped and retry is scheduled
• degraded: bridge caught a runtime fault but is still alive
• error: startup or auth failure blocked useful operation
• stopped: not running or intentionally stopped

Troubleshooting

Duplicate plugin id warning:

• Cause: multiple discoverable oomi-ai installs.
• Action: remove stale extension copies and reinstall once.

invalid handshake: first request must be connect:

• Cause: a gateway request was sent before connect had been accepted.
• Action: update oomi-ai, restart the bridge, and confirm only one bridge worker is running.

STT works but the assistant does not reply:

• Cause: the voice turn likely reached Oomi, but the managed gateway or OpenClaw run failed later.
• Action: inspect gateway.log, gateway.err.log, and the session JSONL for auth, network, or bridge restart errors.

Bridge keeps using an old package after update:

• Action: run oomi openclaw refresh --skip-version-check.
• If still stale: run oomi openclaw bridge restart --detach.
• On macOS service installs: run oomi openclaw bridge service restart.
• Confirm with oomi openclaw bridge ps.

Developer Verification

From packages/oomi-ai:

npm run check
npm test
npm pack --dry-run
npm publish --dry-run --no-git-checks --access public

Expected package contents are restricted by the files allowlist in package.json.