flynn/docs/plans/2026-02-15-openclaw-gap-roadmap.md

OpenClaw Gap Roadmap (Flynn)

Date: 2026-02-15

Source: docs/plans/2026-02-06-openclaw-feature-gap-analysis.md

Goal: Turn the remaining MISSING items into an executable roadmap with clear milestones, acceptance criteria, and test strategy.

Status: Completed on 2026-02-16.

Definition of Done

A gap item is considered implemented when:

• It is behind config flags where appropriate.
• It has tests for core logic (unit/integration, plus minimal adapter/provider mocks where applicable).
• It has docs (README or relevant docs section).
• docs/plans/state.json is updated with status + summary + test status.

Remaining Gap Inventory (from gap analysis)

Channels / Frontends (MISSING)

• Matrix
• Google Chat
• Microsoft Teams
• iMessage/BlueBubbles
• Zalo
• LINE/Feishu/Mattermost

Model Providers (MISSING)

• MiniMax / Moonshot
• Vercel AI Gateway
• OAuth subscription auth (support both API key and OAuth/token)

Agent Runtime / UX (MISSING)

• Canvas / A2UI (agent-driven visual workspace)

Memory

• QMD backend (experimental) — completed on 2026-02-16

Security (MISSING)

• Skill/plugin code safety scanner (static analysis)
• Elevated mode (explicit host-exec escape hatch)

Skills Ecosystem (MISSING)

• ClawHub / community skill registry

Gateway / Infra / Deployment (MISSING)

• Nix deployment
• Fly.io / Railway / Render
• Announce delivery mode (isolated job delivery)
• Bonjour/mDNS discovery

Misc (MISSING)

Companion Apps / Devices (MISSING)

• macOS menu bar app
• iOS node
• Android node
• Voice Wake / Talk Mode
• Camera / screen capture
• Location access

Roadmap Overview (Milestones)

This roadmap optimizes for: (1) high leverage, (2) low coupling, (3) ability to ship incrementally.

1. Credential System v2 (API + OAuth/token) [P0] - completed
2. Vercel AI Gateway provider [P1] - completed
3. Skill/plugin safety scanner [P1] - completed
4. Elevated mode (break-glass) [P2] - completed
5. Matrix channel adapter [P2] - completed
6. Deployment targets (Nix + PaaS) [P3] - completed

Everything else is explicitly deferred until there is a strong user need.

---

Milestone 1 (P0): Credential System v2 — API + OAuth/token

This closes the gap item "OAuth subscription auth" as: providers should support both API-key credentials and OAuth/token-based credentials (where available), with consistent UX and deterministic resolution order.

Scope

• Add an explicit auth_mode selector per model tier config:
  • auto (default): try the most specific configured credential sources in priority order
  • api_key: require API key sources
  • oauth: require OAuth/token sources

Rationale: per-tier enables common setups like:

• fast uses an API key for deterministic reliability.
• default uses OAuth/token for personal subscription accounts.

Provider Behavior (initial)

• OpenAI:

  • Support OAuth (existing): device flow + stored token (flynn openai-auth, /login openai, use_oauth: true).
  • Add API key storage in the same auth store (so YAML can omit secrets).

• Anthropic:

  • Today supports: API key (config/env/auth store) and auth_token (config/env).
  • Add auth-token storage and allow selecting it via auth_mode: oauth.
  • Note: do not invent an OAuth device flow for Anthropic unless a real flow exists; "oauth" here means token-based auth.

Design

Credential sources (recommended priority):

• Config (api_key / auth_token) -> Env var(s) -> Auth store (~/.config/flynn/auth.json)

Auth store should be able to hold multiple types per provider, e.g.:

{
  "openai": { "api_key": "...", "oauth": { "refresh_token": "...", "created_at": "..." } },
  "anthropic": { "api_key": "...", "auth_token": "..." }
}

Implementation Tasks

Config/schema:

• Add auth_mode to the model config schema (per tier) in src/config/schema.ts.
• Update schema tests in src/config/schema.test.ts.

Auth store:

• Extend src/auth/openai.ts to support API-key storage in auth.json (store/load/clear).
• Extend src/auth/anthropic.ts to support auth-token storage in auth.json (store/load/clear).
• Update src/auth/index.ts exports.

CLI:

• Add CLI command(s) for managing stored API keys for OpenAI (name TBD, recommended: flynn openai-key).
• Extend Anthropic auth CLI to store either API key or auth token (flag or separate command).

TUI:

• Extend /login openai flow to let user choose OAuth device flow OR paste API key.
• Add /login anthropic "paste API key" and "paste auth token" (non-OAuth).

Model factory:

• Update createClientFromConfig() in src/daemon/models.ts to resolve creds according to auth_mode.
• Ensure error messages are explicit about which credential type is missing.

Doctor:

• Update src/cli/doctor.ts to report:
  • whether the provider has an API key source
  • whether OAuth/token sources exist
  • without revealing any secret material

Tests

• src/daemon/clientFactory.test.ts

  • auth_mode=auto resolves API key when present
  • auth_mode=oauth resolves token when present
  • auth_mode=api_key fails when only OAuth exists (and vice versa)

• src/auth/openai.test.ts (or new) and src/auth/anthropic.test.ts

  • store/load/clear for all supported credential types

• src/config/schema.test.ts

  • config parsing + defaults for auth_mode

Acceptance Criteria

• OpenAI can authenticate via either:

  • stored OAuth token, or
  • stored API key, without secrets in YAML.

• Anthropic can authenticate via either:

  • stored API key, or
  • stored auth token, without secrets in YAML.

• /model switching does not silently fall back to a weaker tier due to missing credentials; it returns an explicit error.

---

Milestone 2 (P1): Vercel AI Gateway Provider

Scope

• Add a new model provider for Vercel AI Gateway.
• If OpenAI-compatible, implement via OpenAIClient with a configurable baseURL.

Implementation Tasks

• Add provider id in src/config/schema.ts (MODEL_PROVIDERS).
• Add createClientFromConfig() case in src/daemon/models.ts.
• Update setup wizard provider list (optional): src/cli/setup/providers.ts.
• Update doctor key checks if needed: src/cli/doctor.ts.

Tests

• src/daemon/clientFactory.test.ts: constructs correct client and passes baseURL.

Acceptance

• Tool calls + streaming work through the gateway in at least one tier.

---

Milestone 3 (P1): Skill/Plugin Code Safety Scanner

Scope

Add a static scanner that runs during skill load (and optionally install) to prevent obvious unsafe skill packages.

Recommended baseline checks:

• Reject symlinks.
• Reject binary blobs / huge files.
• Validate manifest.json.permissions exists for skills that will be routed as intent targets.
• Optionally scan SKILL.md for disallowed patterns (e.g. embedding secrets, injection markers).

Best Insertion Point

• src/skills/loader.ts inside loadSkill() (covers daemon load, watcher reload, and CLI skill operations).

Optional second insertion:

• src/skills/installer.ts pre-copy scan to avoid persisting unsafe content into managed dir.

Tests

• src/skills/loader.test.ts with fixture dirs for:
  • symlink rejection
  • oversized/binary rejection
  • missing/invalid permissions (when used for routing)

Acceptance

• Unsafe skills do not load and do not get injected into the system prompt.
• Clean skills behave exactly as before.

---

Milestone 4 (P2): Elevated Mode (Break Glass)

Scope

Add a user-visible, auditable, time-bounded mechanism to permit host execution of high-risk tools.

Constraints:

• Must require explicit confirmation.
• Must expire automatically.
• Must emit audit events with reason + TTL.

Integration Points

• src/tools/executor.ts: enforcement gate + audit fields
• src/daemon/routing.ts: set ToolPolicyContext.executionEnvironment based on elevation state
• src/hooks/*: confirmation UX

Tests

• Unit tests for TTL expiry and denial without elevation.

---

Milestone 5 (P2): Matrix Channel Adapter

Scope

Add Matrix as a channel adapter following existing patterns.

Implementation Tasks

• Implement adapter: src/channels/matrix/adapter.ts (+ tests)
• Export and register:
  • src/channels/matrix/index.ts
  • src/channels/index.ts
  • src/daemon/channels.ts
• Config schema: src/config/schema.ts
• Dashboard services reporting: src/gateway/handlers/services.ts
• Config secret redaction: src/gateway/handlers/config.ts

Acceptance

• Inbound messages normalize to InboundMessage with stable senderId.
• Outbound send works.
• Allowlists + mention gating work.

---

Milestone 6 (P3): Deployment Targets (Nix + Fly/Railway/Render)

Status: completed (2026-02-16). See docs/plans/2026-02-16-deployment-targets.md.

Nix

• Provide a flake/package that builds dist/ and preserves dist/gateway/ui adjacency.
• Optional NixOS module with:
  • service user
  • config path
  • data dir

PaaS Targets

• Add first-class docs and templates.
• Ensure network binding is correct (server.localhost: false).
• Either:
  • add PORT env override support, or
  • document explicit config requirements.

---

Deferred Items (P4+)

These are substantial UX/ecosystem projects or highly platform-specific; defer until there is a clear need:

• Canvas/A2UI
• Companion apps (macOS/iOS/Android)
• Voice wake/talk mode + camera/screen capture/location
• Presence tracking
• Bonjour/mDNS discovery
• QMD backend
• ClawHub registry
• Teams/Google Chat (enterprise/ops heavy)
• iMessage/BlueBubbles (Apple ecosystem)

Suggested Next Execution Order

1. Credential System v2 (API + OAuth/token)
2. Vercel AI Gateway provider
3. Skill safety scanner
4. Elevated mode
5. Matrix adapter
6. Deployment targets