New behavior

openclaw channels add now uses one channel-owned setup contract for guided and non-interactive setup. Core selects a channel first, then registers only that channel's setup options.

• openclaw channels add --help shows only the shared --channel, --account, and --name envelope.
• openclaw channels add telegram --help and openclaw channels add --channel telegram --help show Telegram fields only.
• Bundled and installed plugins publish lightweight setup metadata, so selected-channel help does not load plugin runtime code.
• The selected plugin owns parsing, validation, account resolution, config updates, and post-write behavior.
• Signal owns its number and transport selectors end to end; core has no Signal-specific setup property.

This supersedes #108345 with the repository-wide architecture fix rather than landing the Signal-only compromise.

CLI proof

The final row is intentionally selection-scoped. An external plugin's own option shape and default win collisions, while unrelated legacy options never leak into modern channels.

What a channel implements

A modern channel defines its runtime fields and config behavior once:

import { defineChannelSetupContract } from "openclaw/plugin-sdk/channel-setup";

export const setupContract = defineChannelSetupContract({
  fields: {
    endpoint: {
      kind: "string",
      cli: { flags: "--endpoint <url>", description: "Service endpoint" },
    },
    transport: {
      kind: "choice",
      choices: ["native", "container"],
      cli: { flags: "--transport <kind>", description: "Transport owner" },
    },
  },
  adapter: {
    applyAccountConfig: ({ cfg, input }) => ({
      ...cfg,
      channels: { ...cfg.channels, example: input },
    }),
  },
});

It publishes the matching serializable projection for lazy CLI discovery:

{
  "openclaw": {
    "channel": {
      "id": "example",
      "setup": {
        "fields": [
          {
            "key": "endpoint",
            "kind": "string",
            "cli": { "flags": "--endpoint <url>", "description": "Service endpoint" }
          },
          {
            "key": "transport",
            "kind": "choice",
            "choices": ["native", "container"],
            "cli": { "flags": "--transport <kind>", "description": "Transport owner" }
          }
        ]
      }
    }
  }
}

Supported field kinds are string, boolean, integer, string-list, and choice. Runtime/package parity tests keep bundled projections aligned. A channel may also provide setupWizard; wizard values still pass through the same contract.

Third-party compatibility

The released setup/ChannelSetupInput adapter and package-level cliAddOptions remain accepted for existing external plugins. When such a plugin is selected:

1. OpenClaw registers that plugin's cliAddOptions.
2. Core adds only missing switches from the released compatibility set.
3. Execution crosses one explicit legacy adapter boundary.

New plugins should use setupContract. If a plugin exposes both contracts, OpenClaw prefers the modern contract. This gives existing plugins a migration path without keeping global, cross-channel help forever.

Behavioral details

• Positional ids and --channel <id> use the same selected-channel resolver; exact ids win before aliases.
• CLI execution forwards only explicitly supplied modern values, so Commander defaults cannot overwrite existing channel config.
• Completion generation explicitly opts into all setup metadata; normal help and execution do not.
• Installed package metadata is normalized without activating plugin runtime code.
• Signal transport is account-owned and validated by Signal rather than hard-coded in core.

No screenshots are included because this is a CLI/plugin contract and config-flow change. The command/output matrix is the reviewer-checkable UI proof.

How to verify

pnpm openclaw channels add --help
pnpm openclaw channels add telegram --help
pnpm openclaw channels add --channel signal --help
pnpm test src/cli/channels-cli.test.ts src/commands/channels.add.test.ts
pnpm test src/channels/plugins/setup-contract.test.ts src/channels/plugins/contracts/plugin-shape.contract.test.ts extensions/signal/src/setup-core.test.ts extensions/signal/src/setup-transport.test.ts

Checks

• pnpm check:changed — passed
• pnpm build — passed
• pnpm tsgo:core and pnpm tsgo:extensions — passed
• pnpm check:test-types — passed
• pnpm plugin-sdk:api:check — passed
• pnpm docs:check-mdx — 749 files passed
• pnpm docs:check-links — 6,150 links checked, 0 broken
• 248 focused CLI, command, contract, and Signal tests passed

Rebase and takeover notes (maintainer)

This branch was rebased onto current main and reconciled with #112319 (ChannelSetupInput envelope + deprecated compatibility tier):

• In-repo plugins keep their refactor(channels): shrink ChannelSetupInput to a generic envelope with a deprecated compatibility tier #112319 plugin-local setup-input types; the typed setup contracts build on them. No field was resurrected onto the core ChannelSetupInput envelope.
• The external-plugin compatibility fallback now maps onto refactor(channels): shrink ChannelSetupInput to a generic envelope with a deprecated compatibility tier #112319's deprecated tier — that tier is the released compatibility set this PR's legacy adapter boundary consumes.
• The refactor(config): config-surface reduction tranche 3 — product consolidations (review request) #111527 config-surface reductions are preserved; the Signal schema change is scoped to replacing the flat transport fields with the account-owned transport object.
• CHANGELOG.md edits were dropped (changelog is release-generation-owned); release-note context lives in this body.

Flag ordering

channels add selection now matches execution precedence (--channel wins over positional, last --channel wins):

Channels whose setup stores no flag values (twitch, feishu, msteams, reef, zalouser) publish empty contracts: previously-silently-ignored channel flags now fail loudly as unknown options. This is the intended selection-scoped contract — those flags never stored anything on shipped CLI (adapters are enable-only/wizard-driven).

Update flow hardening

freshDoctorRequired in the current-process post-update path now also triggers when the core install itself changed (didCoreUpdateChangeInstall, shared with the fresh-process resume gate). Previously a downgrade or resume-fallback update with no plugin sync/npm changes skipped the fresh doctor, leaving retired config unmigrated for the restarted gateway's stricter schema.

Red main repair

Current main is red in extensions/signal/src/monitor/event-handler.inbound-context.test.ts: 4 tests still asserted the messages.statusReactions.emojis and messages.removeAckAfterReply config surfaces that #111527 retired (verified failing on clean origin/main on a Blacksmith Testbox). This PR aligns those tests with the retained-ack / curated-defaults behavior (3 rewritten, 1 deleted — its subject, reaction removal, is unreachable with removeAckAfterReply hardcoded false). Dead-branch cleanup in the event handler is deferred as a follow-up.