flynn/docs/plans/2026-02-16-openclaw-gap-next-steps-3phase.md

OpenClaw Gap Next Steps — 3-Phase Implementation Plan

Date: 2026-02-16
Parent analysis: docs/plans/2026-02-06-openclaw-feature-gap-analysis.md
Related roadmap: docs/plans/2026-02-15-openclaw-gap-roadmap.md

Goal

Close the highest-impact remaining OpenClaw parity gaps that still affect day-to-day Flynn operator value, while keeping scope incremental and testable.

Prioritization Rationale

1. Queue behavior parity improves real-world reliability under bursty chats.
2. Channel reach adds immediate user-facing utility with bounded engineering cost.
3. Protocol/app foundation unlocks companion-node and canvas-class features without committing to full mobile/mac app scope yet.

Phase 1 — Queue Policy Parity v2 (P1)

Scope

• Extend current lane queue controls to include:
  • followup mode semantics.
  • steer_backlog semantics.
  • lane debounce support.
  • overflow summarize behavior.
• Add runtime control surface for queue policy per session.

File-Level Tasks

• src/gateway/lane-queue.ts
  • Add additional queue modes (followup, steer_backlog).
  • Add debounce handling and summarize-on-overflow strategy.
  • Add typed enqueue options for policy and enqueue metadata.
• src/gateway/handlers/agent.ts
  • Resolve new queue mode values from config/session overrides.
  • Add response payloads for summarized drops/interruption notices.
• src/commands/builtin/index.ts
  • Add /queue command group for inspect/set/reset queue behavior in current session.
• src/session/manager.ts
  • Persist per-session queue overrides (queue.mode, queue.debounce_ms, etc.).
• src/config/schema.ts
  • Add new queue keys and validation (debounce_ms, summarize settings).
• src/gateway/handlers/config.ts
  • Expose queue config fields in runtime config patch API (if applicable).
• README.md
  • Document queue modes and /queue command usage.
• docs/api/PROTOCOL.md
  • Update queue and cancellation behavior sections.

Test Checklist

• src/gateway/lane-queue.test.ts
  • followup behavior under active+pending workloads.
  • steer_backlog replacement behavior across multiple pending entries.
  • debounce behavior timing and ordering.
  • summarize overflow behavior and payload integrity.
• src/gateway/handlers/agent.test.ts
  • queue policy resolution for new modes and debounce.
  • session override precedence over channel/global config.
• src/commands/builtin/*.test.ts
  • /queue parse and execution behavior.
• src/config/schema.test.ts
  • new queue schema defaults and validation errors.

Acceptance Criteria

• Bursty same-session request streams behave deterministically with selected mode.
• Operators can inspect/change queue behavior per session without restart.
• Queue policy behavior is visible in docs and auditable.

Phase 2 — Channel Reach Expansion (Mattermost First) (P2)

Scope

• Add first additional high-value missing channel using existing adapter architecture.
• Mattermost is first due to enterprise overlap with existing Slack/Teams patterns.
• Keep LINE/Feishu/Zalo as follow-on adapters after Mattermost stabilizes.

File-Level Tasks

• src/channels/mattermost/adapter.ts
  • Implement channel adapter with connect/disconnect/send/onMessage.
  • Support allowlists and mention gating consistent with other adapters.
• src/channels/mattermost/index.ts
  • Export adapter + types.
• src/channels/index.ts
  • Register adapter export.
• src/daemon/channels.ts
  • Wire config -> adapter construction and registry registration.
• src/config/schema.ts
  • Add mattermost config block (token/webhook/team/channel constraints).
• src/gateway/handlers/services.ts
  • Add services reporting entry for Mattermost.
• README.md
  • Add setup section and config example.
• docs/architecture/CONTRIBUTOR_MAP.md
  • Update channel map and ownership notes.

Test Checklist

• src/channels/mattermost/adapter.test.ts
  • inbound normalization and sender/session IDs.
  • outbound send path.
  • allowlist and mention gating.
  • reconnect behavior and error handling.
• src/config/schema.test.ts
  • mattermost schema defaults/validation.
• src/daemon/channels.test.ts
  • adapter wiring and enable/disable lifecycle.
• src/gateway/handlers/services.test.ts
  • channel presence/status reporting.

Acceptance Criteria

• Mattermost operates end-to-end with same safety model as existing channels.
• Docs and diagnostics are sufficient for first-time setup.
• No regressions in existing channel startup/wiring tests.

Phase 3 — Companion Node + Capability Negotiation Foundation (P3)

Scope

• Build protocol/runtime foundation for future companion apps and advanced surfaces.
• Do not build full macOS/iOS/Android nodes in this phase.
• Deliver capability discovery, version negotiation, and node role model.

File-Level Tasks

• src/gateway/protocol.ts
  • Add capability/version negotiation types (protocol.version, feature flags).
  • Add node.register, node.capabilities.get RPC schema.
• src/gateway/server.ts
  • Track node-role connections and scoped auth constraints.
• src/gateway/router.ts
  • Route and validate node-specific RPC calls.
• src/gateway/handlers/system.ts
  • Add capability introspection endpoint(s).
• src/config/schema.ts
  • Add optional node policy config (gateway.nodes.allowed_roles, feature gates).
• src/gateway/auth.ts
  • Add scoped auth checks for node-role methods.
• docs/api/PROTOCOL.md
  • Document negotiation handshake and node method contracts.
• README.md
  • Add node foundation section and constraints.

Test Checklist

• src/gateway/protocol.test.ts
  • validation for negotiation and node method payloads.
• src/gateway/server.test.ts
  • node registration lifecycle.
  • role-based method allow/deny behavior.
• src/gateway/handlers/system.test.ts
  • capability introspection output correctness.
• src/gateway/auth.test.ts
  • node-role scope enforcement.
• Integration tests:
  • backward compatibility for non-node clients with old flow.

Acceptance Criteria

• Gateway supports explicit capability/version negotiation.
• Node connections can be constrained by role and method scope.
• Existing WebChat/TUI clients remain fully compatible.

Cross-Phase Delivery Rules

• Keep each phase behind config flags where behavior risk is non-trivial.
• Land in small atomic commits with docs and tests in the same commit.
• Update docs/plans/state.json after each phase completion.
• Run at least:
  • pnpm test:run for touched suites.
  • pnpm typecheck.
  • pnpm build for protocol/runtime touching phases.

Suggested Execution Order

1. Phase 1 (Queue parity v2).
2. Phase 2 (Mattermost adapter).
3. Phase 3 (Node/capability foundation).