docs: add safety docs and OpenClaw gap roadmap
This commit is contained in:
William Valentin
@@ -0,0 +1,343 @@
|
||||
# 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.
|
||||
|
||||
## 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)
|
||||
|
||||
- Signal
|
||||
- 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 (MISSING)
|
||||
|
||||
- QMD backend (experimental)
|
||||
|
||||
### 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)
|
||||
|
||||
- Presence tracking
|
||||
|
||||
### 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]
|
||||
2) Vercel AI Gateway provider [P1]
|
||||
3) Skill/plugin safety scanner [P1]
|
||||
4) Elevated mode (break-glass) [P2]
|
||||
5) Matrix channel adapter [P2]
|
||||
6) Deployment targets (Nix + PaaS) [P3]
|
||||
|
||||
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)
|
||||
|
||||
### 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
|
||||
- Signal/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
|
||||
Reference in New Issue
Block a user