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)

- 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
- 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.:

```json
{
  "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)
- Location access
- Presence tracking
- Bonjour/mDNS discovery
- QMD backend
- ClawHub registry

## 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