Summary

• Problem: @openclaw/discord 2026.5.2 channel startup crashes deterministically when channels.discord.token is configured as a SecretRef object (e.g. { id: "DISCORD_BOT_TOKEN", provider: "default", source: "env" }), failing every gateway restart with [discord] channel startup failed: channels.discord.token: unresolved SecretRef "env:default:DISCORD_BOT_TOKEN". Resolve this command against an active gateway runtime snapshot before reading it.
• Why it matters: Discord channel never reaches READY on 2026.5.2 with this very common config shape. Telegram with the analogous SecretRef config works fine on the same boot, so the failure is silent-on-other-channels and obvious-on-discord — easy to mistake for a Discord/network problem. Effectively a hard regression vs. 2026.4.29 (bundled dist/extensions/discord) for SecretRef users. Filed as [Bug] @openclaw/discord 2026.5.2 channel startup crashes on SecretRef-backed token (env:default:DISCORD_BOT_TOKEN unresolved) #76371.
• What changed: normalizeDiscordToken now uses the gentle normalizeSecretInputString instead of the strict normalizeResolvedSecretInputString. Unresolved SecretRefs return undefined and let the existing fall-through chain (account-token → top-level token → process.env.DISCORD_BOT_TOKEN → source=none) handle the common case where the env-source SecretRef's intent matches the existing env fallback. Two existing throw-assertions updated; two new tests added covering the SecretRef-without-env path and the account-level SecretRef + base-token interaction.
• What did NOT change (scope boundary): resolveDiscordToken's fall-through ordering, the Bot prefix stripping, the inspectConfiguredToken "configured but unavailable" path, the hasAccountToken "explicit blank means no inheritance" semantics, any caller of normalizeDiscordToken outside resolveDiscordToken itself, any code outside extensions/discord/. No SDK contract change.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug] @openclaw/discord 2026.5.2 channel startup crashes on SecretRef-backed token (env:default:DISCORD_BOT_TOKEN unresolved) #76371
• Related BUG: Embedded channel reply runs crash on SecretRef-backed Telegram/Discord credentials #75433 (sister bug — embedded reply path SecretRef crash, same resolved-snapshot-vs-raw-config family)
• Related [Bug]: @openclaw/bluebubbles 2026.5.2 webhook auth crashes on SecretRef password — TypeError in monitor.ts #76369 (sister bug — @openclaw/bluebubbles 2026.5.2 webhook auth SecretRef crash, same 2026.5.2 externalization wave)
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: extensions/discord/src/token.ts:normalizeDiscordToken invoked normalizeResolvedSecretInputString (strict mode → calls assertSecretInputResolved → throws createUnresolvedSecretInputError on any unresolved SecretRef). The channel-startup path (startChannel(plugin.id) → discord plugin → resolveDiscordAccount → resolveDiscordToken → normalizeDiscordToken) reads raw OpenClawConfig before the gateway has materialized channel SecretRefs into a runtime snapshot, so the assertion fires deterministically and crashes the channel start.
• Missing detection / guardrail: No test exercised the channel-start path with a SecretRef-shaped channels.discord.token. The existing token.test.ts > "throws when token is an unresolved SecretRef object" documented the throw as intentional, which made it look like a contract — but in practice the throw is unreachable from the runtime-snapshot consumers (which do pre-resolve) and only ever fires from raw-config consumers like channel startup, where it is the bug rather than the guard.
• Contributing context: The 2026.5.2 plugin externalization wave moved Discord from dist/extensions/discord (bundled) to @openclaw/discord (npm). The bundled 2026.4.29 startup path apparently happened to feed resolveDiscordToken a config where SecretRefs had already been coerced upstream; the externalized startup path receives raw config. Telegram dodges the same family because its token resolver does not call the strict variant.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: extensions/discord/src/token.test.ts (and existing extensions/discord/src/client.test.ts updated to assert the new user-actionable error).
• Scenario the test should lock in: resolveDiscordToken({ channels: { discord: { token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" } } } }) with process.env.DISCORD_BOT_TOKEN="..." returns { token: "...", source: "env" } and does not throw. Without the env, returns { token: "", source: "none" }. With an account-level SecretRef + base token, returns { token: "", source: "none" } (preserves "explicit blank means no inheritance").
• Why this is the smallest reliable guardrail: The unit covers the exact contract the channel-startup path depends on, with no plugin-runtime / mock surface. A higher-level seam test would add weight without catching anything the unit doesn't.
• Existing test that already covers this (if any): None (the previous "throws when token is an unresolved SecretRef object" test asserted the opposite — the bug as a feature).
• If no new test is added, why not: N/A; new tests added.

User-visible / Behavior Changes

• Discord channel start no longer fails when channels.discord.token is a SecretRef object whose intent matches the env fallback (the very common { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" } shape).
• When neither config nor env produces a token, the user-facing error becomes "Discord bot token missing for account "default" (set discord.accounts.default.token or DISCORD_BOT_TOKEN for default)." (from createDiscordRestClient) instead of the internal "channels.discord.token: unresolved SecretRef …. Resolve this command against an active gateway runtime snapshot before reading it." — clearer guidance, same loud failure.
• No config-format changes. Existing string tokens, account-level tokens, env-only setups, and inspectConfiguredToken "configured but unavailable" status all behave as before.

Diagram (if applicable)

Before (2026.5.2):
  startChannel("discord")
    -> resolveDiscordAccount(rawCfg)
      -> resolveDiscordToken(rawCfg)
        -> normalizeDiscordToken(SecretRef, "channels.discord.token")
          -> normalizeResolvedSecretInputString(...)  [strict]
            -> assertSecretInputResolved(...)  THROWS
  channel startup failed.

After:
  startChannel("discord")
    -> resolveDiscordAccount(rawCfg)
      -> resolveDiscordToken(rawCfg)
        -> normalizeDiscordToken(SecretRef, _path)
          -> normalizeSecretInputString(SecretRef)  [gentle] -> undefined
        configToken = undefined
        -> normalizeDiscordToken(process.env.DISCORD_BOT_TOKEN, ...)  [string -> string]
        -> { token, source: "env" }
  channel started.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? Yes (in spirit only — no new disclosure path; previously a SecretRef-shaped token crashed the channel before any token was used; now it falls through to the same env fallback that already existed in the same function for the no-config case. No new sink for token bytes; Bot prefix stripping preserved; explicit-blank account semantics preserved.)
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• Risk + mitigation: A SecretRef whose source/provider/id was not env:default:DISCORD_BOT_TOKEN previously crashed; it will now silently fall through to the env fallback if DISCORD_BOT_TOKEN happens to be set. This is the same fall-through behavior that already exists for the "no config token" case, so it does not introduce a new path — but it does mean the intent expressed in a non-env SecretRef (e.g. source: "exec") becomes invisible at the channel-start site. Mitigation: callers that need strict resolution semantics (i.e. consumers of an actual runtime snapshot) should call normalizeResolvedSecretInputString directly; this PR only changes the channel-start consumer's behavior. The user-actionable "bot token missing" error still fires loudly when no token resolves.

Repro + Verification

Environment

• OS: macOS 26.2 (arm64)
• Runtime/container: Node 25.9.0, gateway managed via launchd (gui/502/ai.openclaw.gateway), local mode
• Model/provider: N/A (failure is at channel-start, before any model call)
• Integration/channel (if any): Discord (channel + DM); Telegram present and working with analogous SecretRef config on the same boot
• Relevant config (redacted):

  "channels": {
    "discord": {
      "enabled": true,
      "token": { "id": "DISCORD_BOT_TOKEN", "provider": "default", "source": "env" }
    }
  },
  "secrets": { "providers": { "default": { "source": "env" } } }

  ~/.openclaw/.env contains DISCORD_BOT_TOKEN=... (autoloaded via dotenv; verified in process.env of the gateway child process).

Steps

1. Install OpenClaw 2026.5.2 (the openclaw doctor step of openclaw update auto-installs @openclaw/discord@2026.5.2 from npm).
2. Configure channels.discord.token as the SecretRef object above; ensure DISCORD_BOT_TOKEN is in env (any of: ~/.openclaw/.env, the LaunchAgent env file, or the parent shell).
3. Restart the gateway (launchctl kickstart -k gui/502/ai.openclaw.gateway).
4. Tail /tmp/openclaw/openclaw-<date>.log for discord events around startup.

Expected

• Discord channel reaches discord channels resolved → discord client initialized as <bot-id> → gateway ready (no channel startup failed lines).

Actual (before this PR)

• Every restart logs:

  [discord] channel startup failed: channels.discord.token: unresolved SecretRef
  "env:default:DISCORD_BOT_TOKEN". Resolve this command against an active gateway
  runtime snapshot before reading it.
  

  Channel never starts; bot is offline. Telegram on the same boot is unaffected.

Evidence

• Failing test/log before + passing after — gateway log lines above (failing) plus 1315/1315 unit pass after the change (was 1313 baseline; +2 new tests; updated 2 existing throw-assertions to assert the new graceful behavior).
• Trace/log snippets — see "Actual" above; the throw originates at normalizeResolvedSecretInputString → assertSecretInputResolved (dist/types.secrets-CyuYZNvB.js).
• Screenshot/recording — N/A (server-side log behavior).
• Perf numbers — N/A.

Human Verification (required)

• Verified scenarios:
  • Reproduced the failure on a real 2026.5.2 install with the SecretRef config above (multiple gateway restarts, deterministic).
  • Applied the equivalent config workaround (removed channels.discord.token so the env fallback fires unconditionally) and confirmed Discord channel starts cleanly — same code path this PR makes available with the SecretRef present.
  • Ran pnpm install + pnpm test:extension discord on upstream/main → 1313/1313 pass (baseline).
  • Applied this change → pnpm test:extension discord → 1315/1315 pass.
  • Inspected all normalizeDiscordToken call sites (accounts.ts, setup-account-state.ts, setup-surface.ts, directory-live.ts, probe.ts, resolve-allowlist-common.ts, client.ts via resolveDiscordToken); none rely on the strict-throw behavior other than the one test that asserted it directly.
  • Inspected the inspectConfiguredToken codepath — the gentle pattern this PR adopts is already used there for the same reason ("configured but unavailable").
• Edge cases checked:
  • SecretRef + DISCORD_BOT_TOKEN set in env → returns source=env, channel starts.
  • SecretRef + no env → returns source=none, channel reports user-actionable "bot token missing" error (no internal SecretRef contract error).
  • Account-level SecretRef + base-level string token → returns source=none for that account (preserves existing "explicit blank means no inheritance" semantics).
  • String token (existing happy path) → unchanged.
  • Bot <token> prefix stripping → preserved (covered by the unchanged regex).
• What I did NOT verify:
  • I did not run pnpm build && pnpm check && pnpm test (the full repo lane) locally — left to CI. No src/**, src/plugin-sdk/**, or packages/** files were touched, so the import-boundary inventories listed in CONTRIBUTING.md should not be required.
  • I did not run codex review --base origin/main locally (no Codex subscription on this box). Will address Codex/bot review comments after CI runs them.
  • I did not test multi-account configurations beyond the unit-level case added.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR. (Will fill in after first review pass.)
• I left unresolved only the conversations that still need reviewer or maintainer judgment. (Will fill in after first review pass.)

Compatibility / Migration

• Backward compatible? Yes — string-token configs unchanged; SecretRef configs that previously crashed now succeed via the env fallback (or surface a user-actionable error if no env).
• Config/env changes? No — existing configs work; the docstring in extensions/discord/src/doctor.ts:256 ("verify DISCORD_BOT_TOKEN is present in the state-dir .env or configure channels.discord.token / channels.discord.accounts.default.token as a SecretRef") becomes accurate again instead of misleading.
• Migration needed? No.

Risks and Mitigations

• Risk: A non-env SecretRef (e.g. { source: "exec", … }) previously threw at channel start; with this PR it falls through to env. If the operator intended an exec-resolved token but only has DISCORD_BOT_TOKEN set in env, the operator's stated intent is silently overridden by the env fallback.
  • Mitigation: This is the same fall-through behavior that already applies to the "no config token" case in the same function — not a new path, just a new entry point. The documented architectural fix (resolve channel token SecretRefs in core before startChannel) would handle this more cleanly; see extensions/discord/src/token.ts comment added in this PR. A future PR can add a "configured but unresolved" warning log if this surprises operators in practice.
• Risk: The previous strict throw was a debug aid for accidental raw-config consumers. Replacing it loses that signal.
  • Mitigation: Strict resolution remains available via normalizeResolvedSecretInputString and assertSecretInputResolved for runtime-snapshot consumers. This PR only changes the one call site that was systematically misusing the strict variant.

AI/Vibe-coded disclosure

• AI-assisted (Claude Sonnet 4.6 via Claude Code CLI, "fully tested" — full discord extension test lane green locally: 1315/1315).
• Author understands the code change and the surrounding plugin's secret-input contract.
• Will run codex review --base origin/main and address findings before requesting review (no Codex subscription on this box; will rely on CI Codex review).
• Will resolve bot review conversations after addressing them.

Session origin

This PR was authored mid-incident while debugging an actual production gateway hitting #76371 on a fresh 2026.5.2 install. Condensed session log:

1. Discord stopped responding in DM → traced to repeated channel-startup failures in the gateway log.
2. Restarting the gateway (launchctl kickstart -k) cleared transient saturation but the channel-startup error reproduced deterministically across multiple restarts.
3. Initially suspected an env-availability issue (the message text mentions "active gateway runtime snapshot before reading it"). Ruled that out by adding DISCORD_BOT_TOKEN directly to the LaunchAgent env file (so it was in process.env from the very first instruction). Same crash. Conclusion: the bug is in the SecretRef strict-resolver code path, not env availability.
4. Located the throw site by grepping the installed @openclaw/discord source for the literal error message: extensions/discord/src/token.ts:normalizeDiscordToken → normalizeResolvedSecretInputString (strict).
5. Compared with the safe sibling inspectConfiguredToken in setup-account-state.ts — same plugin, same author intent, gentle handling of SecretRef objects via normalizeSecretInputString.
6. Searched for prior art on this bug family — found BUG: Embedded channel reply runs crash on SecretRef-backed Telegram/Discord credentials #75433 (embedded reply path) and [Bug]: @openclaw/bluebubbles 2026.5.2 webhook auth crashes on SecretRef password — TypeError in monitor.ts #76369 (@openclaw/bluebubbles webhook path), confirmed no existing report for the channel-startup case, filed [Bug] @openclaw/discord 2026.5.2 channel startup crashes on SecretRef-backed token (env:default:DISCORD_BOT_TOKEN unresolved) #76371.
7. Initially considered changing normalizeDiscordToken was wrong because the existing test ("throws when token is an unresolved SecretRef object") explicitly asserted the throw — but on closer reading, the throw was a debug aid, not a feature, and the gentle path already exists in the same plugin. Updated the assertion to lock in the new graceful behavior.
8. Validated the workaround (Option 1, "remove channels.discord.token from config so env fallback unconditionally fires") on the real instance — Discord channel starts cleanly. That validates the same code path this PR enables with the SecretRef config preserved.
9. Cloned the repo, installed dependencies, ran the full discord extension test lane to baseline (1313/1313 pass), made the fix, updated the two existing throw-asserting tests, added two new tests covering the SecretRef + env and SecretRef + no-env scenarios, and re-ran (1315/1315 pass).

The session prompt thread is available on request; happy to share if useful for the AI-PR-tracking maintainers do.