Summary

• Problem: Mattermost slash commands (/oc_model, /oc_status, /oc_help, …) always return 503 Service Unavailable with {"response_type":"ephemeral","text":"Slash commands are not yet initialized. Please try again in a moment."}, even after the log confirms mattermost: slash commands activated for account default (8 commands).
• Why it matters: On macOS/Linux installs, every `/oc_*` slash command in Mattermost is broken, with no path to recovery short of patching the installed npm package. Slack, Discord, etc. are unaffected.
• What changed: extensions/mattermost/index.ts now imports registerSlashCommandRoute statically from ./slash-route-api.js instead of resolving it through the sync jiti loader loadBundledEntryExportSync. That makes the plugin-registration path and the monitor path share a single ESM instance of slash-state.ts, so the HTTP route closure and activateSlashCommands see the same accountStates map.
• What did NOT change (scope boundary): No changes to slash-state.ts, monitor-slash.ts, monitor.ts, the HTTP handler, slash command registration flow, or any other extension. Just the single import in extensions/mattermost/index.ts. Slack's extensions/slack/index.ts has a similar-looking dual-path import, but its route handler does not close over module state (the handler uses await import("./handler.runtime.js") inside), so Slack is not affected by the same bug and is explicitly out of scope here.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Integrations

Linked Issue/PR

• Closes #
• Related #
• This PR fixes a bug or regression

Root Cause

extensions/mattermost/index.ts::registerFull used loadBundledEntryExportSync(import.meta.url, { specifier: "./slash-route-api.js", exportName: "registerSlashCommandRoute" }) to load the route registrar. On macOS/Linux that helper resolves through jiti (see src/plugin-sdk/channel-entry-contract.ts: nodeRequire is only tried inside the Win32 branch, everywhere else falls through to getJiti(modulePath)(modulePath)).

slash-route-api.ts re-exports registerSlashCommandRoute from ./src/mattermost/slash-state.js. Loading it via jiti causes jiti to re-evaluate slash-state.ts inside its own module registry, producing a second live instance of the module. Meanwhile src/mattermost/monitor-slash.ts and src/mattermost/monitor.ts (and therefore the channel runtime loaded via await import("./channel.runtime-*.js")) import ./slash-state.js through native ESM, giving them instance A.

The result: two separate accountStates maps.

• activateSlashCommands / deactivateSlashCommands mutate the ESM copy → the log line "slash commands activated for account default (N commands)" fires on the ESM instance.
• registerSlashCommandRoute's routeHandler closure closes over the jiti copy's accountStates → accountStates.size stays 0 for the lifetime of the process → every callback returns 503 "Slash commands are not yet initialized. Please try again in a moment.".

This matches the guidance in src/plugin-sdk/CLAUDE.md:

Do not mix static and dynamic imports for the same runtime surface when shaping SDK seams.

The fix is the straightforward application of that rule: index.ts should import ./slash-route-api.js statically so slash-state.ts loads through native ESM exactly once, shared with the monitor / channel-runtime path.

Missing detection / guardrail

There is a good unit test for the token-routing logic in extensions/mattermost/src/mattermost/slash-state.test.ts, but it only exercises one import of slash-state, so it cannot detect the dual-instance bug. I am happy to add a regression test that specifically simulates loading slash-route-api.js through jiti alongside the native ESM import and asserts that activation flows through to the route handler — happy to do it in this PR if maintainers prefer. I did not include it in the initial patch because simulating the jiti boundary in Vitest is a bit more involved than the fix itself, and I wanted the minimal-risk diff to land first.

Contributing context

The same loadBundledEntryExportSync pattern is used in extensions/feishu/index.ts, extensions/nostr/index.ts, extensions/qqbot/index.ts, extensions/slack/index.ts, extensions/zalouser/index.ts. Slack is safe because its handler does await import("./handler.runtime.js") inside the request closure instead of closing over module state. I did not audit the others in depth; if similar closures-over-module-state exist there, they would have the same failure mode and warrant a follow-up. Flagging for visibility, not proposing to change them in this PR.

Regression Test Plan

• Coverage level that should have caught this:
  • Seam / integration test
• Target test or file: extensions/mattermost/src/mattermost/slash-state.dual-load.test.ts (new) — would load slash-route-api.ts through a jiti instance and slash-state.ts through native ESM in the same test, activate commands on the ESM side, then drive an HTTP request against the jiti-registered route and assert that it does not return 503.
• Scenario to lock in: "route handler registered via loadBundledEntryExportSync observes activations performed via the monitor's static import of slash-state.js."
• Why this is the smallest reliable guardrail: The bug is entirely a module-identity bug; pure-unit tests that import slash-state.ts once do not reproduce it. A boundary test that crosses the same jiti / ESM seam is the minimum.
• Existing test that already covers this: None — slash-state.test.ts is single-import only.
• If no new test is added, why not: I did not want to block the fix on writing the jiti-boundary harness; happy to add it as a follow-up or in this PR if a reviewer prefers.

User-visible / Behavior Changes

• Mattermost /oc_status, /oc_model, /oc_models, /oc_new, /oc_help, /oc_think, /oc_reasoning, /oc_verbose (and any user-defined slash commands registered through the same path) start working again instead of responding 503 Service Unavailable / "Slash commands are not yet initialized.".
• No config changes. No new permissions. The HTTP route path, callback URL behavior, 401/409/413 responses, and multi-account dispatch logic are all unchanged.

Diagram

Before (broken):

  registerFull(api)
    └─ loadBundledEntryExportSync(...) ──(jiti)──► slash-state.ts   (instance B)
                                                     └─ accountStates_B  ◄── routeHandler closure
                                                                                 (size always 0 → 503)

  channel.runtime.ts ──(native ESM import)──► slash-state.ts   (instance A)
                                                 └─ accountStates_A  ◄── activateSlashCommands writes here


After (fixed):

  registerFull(api)
    └─ import { registerSlashCommandRoute } from "./slash-route-api.js"
                                    │
                                    ▼
                              slash-state.ts   (single ESM instance)
                                    └─ accountStates  ◄── routeHandler AND activateSlashCommands

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No — slash-command dispatch semantics, token validation, and multi-account routing are unchanged. The fix only restores the previously-intended flow.
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS 15.3.x (Darwin 25.3.0, arm64)
• Runtime/container: Node 22.22.0, openclaw installed via npm i -g openclaw@2026.4.15, gateway started as the launchd ai.openclaw.gateway LaunchAgent.
• Integration/channel: Mattermost 11.5.1 (team edition) behind Caddy, multiple channels.mattermost.accounts.* entries (default / forge / kline / probe / quill / scout) but only the default account has team-admin permission to register commands, so accountStates.size === 1 — the most common production shape.

Steps

1. Gateway boots; logs show:

   [plugins] mattermost: registered slash command callback at /api/channels/mattermost/command
   [mattermost] slash commands activated for account default (8 commands)
   [mattermost] slash commands registered (8 commands across 1 teams, callback=http://<lan>:18789/api/channels/mattermost/command)
   

2. Trigger /oc_model from the Mattermost UI. Server also reproducible via:

   curl -sS -o /dev/null -w "HTTP %{http_code}\n" -X POST \
     http://127.0.0.1:18789/api/channels/mattermost/command \
     -d 'token=<real-token>&command=/oc_model'
   

Expected

• For a single-account setup, the size === 1 branch should dispatch straight to state.handler, which validates the token internally and returns the normal slash-command response (200 with the ephemeral reply, or a 401 only for a genuinely wrong token).

Actual (before the fix)

• HTTP 503 with body {"response_type":"ephemeral","text":"Slash commands are not yet initialized. Please try again in a moment."}, even though the activation log fired seconds earlier. The Mattermost UI surfaces this as 触发器 "oc_model" 返回了响应状态 503 Service Unavailable. / "Trigger "oc_model" returned response status 503 Service Unavailable."

Evidence

Failing-before / passing-after against a locally patched installed dist (equivalent rewrite of this TS change onto the bundled output, /opt/homebrew/lib/node_modules/openclaw/dist/extensions/mattermost/index.js):

Before (immediately after launchctl kickstart -k gui/$UID/ai.openclaw.gateway, well past activation):

$ curl -sS -o /dev/null -w "HTTP %{http_code}\n" -X POST \
    http://127.0.0.1:18789/api/channels/mattermost/command \
    -d 'token=foo&command=/oc_model'
HTTP 503
$ curl -sS -X POST http://127.0.0.1:18789/api/channels/mattermost/command \
    -d 'token=foo&command=/oc_model'
{"response_type":"ephemeral","text":"Slash commands are not yet initialized. Please try again in a moment."}

After applying the equivalent patch and restarting the gateway:

$ curl -sS -o /dev/null -w "HTTP %{http_code}\n" -X POST \
    http://127.0.0.1:18789/api/channels/mattermost/command \
    -d 'token=foo&command=/oc_model'
HTTP 400
$ curl -sS -X POST http://127.0.0.1:18789/api/channels/mattermost/command \
    -d 'token=foo&command=/oc_model'
{"response_type":"ephemeral","text":"Invalid slash command payload."}
$ curl -sS -o /dev/null -w "HTTP %{http_code}\n" -X POST \
    http://127.0.0.1:18789/api/channels/mattermost/command \
    --data-urlencode 'token=not-a-real-token' \
    --data-urlencode 'command=/oc_model' \
    --data-urlencode 'team_id=498ogwtouigf8xfbuks451e8aa' \
    --data-urlencode 'channel_id=c' --data-urlencode 'user_id=u' \
    --data-urlencode 'user_name=n' --data-urlencode 'text=' \
    --data-urlencode 'trigger_id=t'
HTTP 401

Interpretation: the 503 "not yet initialized" path is now unreachable — incoming requests flow into the real handler, which correctly rejects malformed payloads (400) and bad tokens (401). A real Mattermost-signed request with the registered token returns the normal slash-command response.

Relevant gateway log lines from the fixed run (unchanged shape, included for completeness):

[plugins] mattermost: registered slash command callback at /api/channels/mattermost/command
[mattermost] [default] starting channel
[mattermost] connected as @nova
[mattermost] command /oc_model already registered (id=fffuot5kpjgafkmx7rc5fk9xjc)
[mattermost] slash commands activated for account default (8 commands)
[mattermost] slash commands registered (8 commands across 1 teams, callback=http://<lan>:18789/api/channels/mattermost/command)

Human Verification

• Verified scenarios:
  • Single-account (accountStates.size === 1) dispatch path, which was the production failure.
  • End-to-end via the running ai.openclaw.gateway LaunchAgent and real Mattermost (/oc_model from the Mattermost UI).
  • 400 / 401 paths reached correctly with synthetic curl payloads.
• Edge cases checked:
  • Restart via launchctl kickstart -k between before/after so the Node process and jiti registry are both replaced.
  • Confirmed that the fix does not regress the registered-HTTP-route path set for known callbackPath / callbackUrl overrides (route registration log is unchanged).
• What I did NOT verify:
  • Multi-account (accountStates.size > 1) token-routing path — code path is untouched, but I did not have a second team-admin account to activate commands on. The unit tests in slash-state.test.ts cover that branch.
  • pnpm check / pnpm build / pnpm test — I did not run these locally before opening the PR (this is my first contribution to the repo and I wanted to avoid a large-deps install cycle before you tell me which gates you want covered). Please run CI; happy to iterate on any failures or add the jiti-boundary regression test if that is what you would like to see.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: slash-route-api.ts and transitively ./src/mattermost/slash-state.ts now load eagerly as part of the plugin entry, instead of only when registerFull fires through jiti. slash-state.ts is a small module (≈300 LOC, top-level state is just one Map), but this does add it to the mattermost plugin's cold-start import cost.
  • Mitigation: the module has no expensive side effects at import time (just a new Map() and function definitions), matches how monitor.ts already imports it on the hot monitor path, and aligns with the SDK guidance that says the eager/light contract belongs next to the plugin entry and only the heavy runtime should live behind a lazy *.runtime.ts boundary. I am happy to instead introduce a dedicated slash-route.runtime.ts and keep registerSlashCommandRoute lazy-but-single-instance if maintainers prefer that shape.
• Risk: Other bundled channels use the same loadBundledEntryExportSync pattern and may have similar dual-instance bugs depending on whether their route registrars close over module state.
  • Mitigation: Out of scope for this PR — Slack is demonstrably fine. Happy to open a follow-up audit if useful.