Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Feature]: Improve QQBot error messages with actionable guidance and docs links [3 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#65868•Fetched 2026-04-14 05:39:47
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
Jah-yeeJah-yee
Participants
Jah-yeeJah-yee
Timeline (top)
cross-referenced ×3

QQBot extension error messages are overly technical — they dump raw JSON API responses and lack actionable user guidance, documentation links, or env var hints.

Error Message

QQBot extension error messages are overly technical — they dump raw JSON API responses and lack actionable user guidance, documentation links, or env var hints. When QQBot encounters configuration or API errors, the error messages are developer-oriented and unhelpful for end users: 3. Network errors (extensions/qqbot/src/api.ts ~line 245): Network error [${path}] — no troubleshooting hints (e.g., check network, check whitelist, check region). By contrast, other channels and providers in OpenClaw include docsUrl, signupUrl, and actionable hints in their error messages. Improve QQBot error messages to include:

  • Adding a dedicated QQBot troubleshooting page — useful but orthogonal to improving inline error messages.
  • Severity: Medium (poor DX and UX on error paths)
  • Consequence: Users must search source code or ask in Discord to understand error causes, instead of being guided by the error message itself Current error in extensions/qqbot/src/api.ts:139: throw new Error(Failed to get access_token: ${JSON.stringify(data)}); For comparison, MiniMax web search provider includes a structured error: The QQBOT_DEBUG env var (extensions/qqbot/src/utils/debug-log.ts) is also undocumented (neither in the manifest channelEnvVars nor in docs/channels/qqbot.md). If this env var is intended for end-user troubleshooting, documenting it alongside improved error messages would help. If it is internal-only, it can remain undocumented but the error messages should still guide users to the debug flag when relevant.

Root Cause

QQBot extension error messages are overly technical — they dump raw JSON API responses and lack actionable user guidance, documentation links, or env var hints.

Fix Action

Fixed

PR fix notes

PR #65879: fix(qqbot): add actionable setup guidance to common errors

Description (problem / solution / changelog)

Summary

  • fixes #65868
  • improve QQBot configuration and token-fetch error messages with actionable setup guidance

Why

Several common QQBot errors only reported technical text like missing appId or clientSecret, without clear env variable names or docs links. This made setup/debugging slower for users.

Changes

  • extensions/qqbot/src/gateway.ts
  • extensions/qqbot/src/outbound.ts
  • extensions/qqbot/src/proactive.ts
    • replace generic QQBot not configured messages with actionable guidance:
      • explicitly call out QQBOT_APP_ID and QQBOT_CLIENT_SECRET
      • include docs link https://docs.openclaw.ai/channels/qqbot
  • extensions/qqbot/src/api.ts
    • improve missing token error to include setup hint and docs link
    • improve API network error text with connectivity guidance and docs link

Validation

  • pnpm vitest run extensions/qqbot/src/proactive.test.ts extensions/qqbot/src/outbound-deliver.test.ts extensions/qqbot/src/setup.test.ts

Notes

  • keeps existing error paths and behavior; only improves user-facing guidance
  • local tests passed before PR creation

Made with Cursor

Changed files

  • extensions/qqbot/src/api.ts (modified, +8/-2)
  • extensions/qqbot/src/errors.ts (added, +8/-0)
  • extensions/qqbot/src/gateway.ts (modified, +2/-1)
  • extensions/qqbot/src/outbound.ts (modified, +11/-4)
  • extensions/qqbot/src/proactive.ts (modified, +3/-2)

PR #65928: fix(qqbot): add actionable setup guidance to common errors

Description (problem / solution / changelog)

Summary

  • fixes #65868
  • improve common QQBot setup/network errors with actionable guidance
  • centralize shared setup guidance text to avoid message drift

Changes

  • extensions/qqbot/src/errors.ts (new)
  • extensions/qqbot/src/api.ts
  • extensions/qqbot/src/gateway.ts
  • extensions/qqbot/src/outbound.ts
  • extensions/qqbot/src/proactive.ts
    • unify config-missing message text and docs URL
    • keep existing error paths; improve guidance only

Validation

  • pnpm vitest run extensions/qqbot/src/proactive.test.ts extensions/qqbot/src/outbound-deliver.test.ts extensions/qqbot/src/setup.test.ts

Notes

  • behavior unchanged except improved user-facing diagnostics
  • local tests passed

Made with Cursor

Changed files

  • extensions/qqbot/src/api.ts (modified, +8/-2)
  • extensions/qqbot/src/errors.ts (added, +8/-0)
  • extensions/qqbot/src/gateway.ts (modified, +2/-1)
  • extensions/qqbot/src/outbound.ts (modified, +11/-4)
  • extensions/qqbot/src/proactive.ts (modified, +3/-2)

PR #65943: fix(qqbot): add actionable setup guidance to common errors

Description (problem / solution / changelog)

Summary

  • fixes #65868
  • improve QQBot user-facing setup and network error guidance
  • centralize shared error guidance constants to prevent message drift

Why

Several high-frequency errors were too generic for operator troubleshooting and did not consistently point users to setup guidance.

Changes

  • extensions/qqbot/src/errors.ts (new)
    • shared setup docs URL and standardized config-missing message
  • extensions/qqbot/src/api.ts
    • make token/network errors actionable and docs-linked
  • extensions/qqbot/src/gateway.ts
  • extensions/qqbot/src/outbound.ts
  • extensions/qqbot/src/proactive.ts
    • reuse shared setup guidance for config-missing paths

Validation

  • pnpm vitest run extensions/qqbot/src/proactive.test.ts extensions/qqbot/src/outbound-deliver.test.ts extensions/qqbot/src/setup.test.ts

Notes

  • no protocol/transport behavior changes
  • local tests passed

Made with Cursor

Changed files

  • extensions/qqbot/src/api.ts (modified, +8/-2)
  • extensions/qqbot/src/errors.ts (added, +8/-0)
  • extensions/qqbot/src/gateway.ts (modified, +2/-1)
  • extensions/qqbot/src/outbound.ts (modified, +11/-4)
  • extensions/qqbot/src/proactive.ts (modified, +3/-2)

Code Example

QQBot not configured. Set QQBOT_APP_ID and QQBOT_CLIENT_SECRET, or run `openclaw configure`.
   See: https://docs.openclaw.ai/channels/qqbot

---

Failed to get QQBot access token. Check that your QQBOT_APP_ID and QQBOT_CLIENT_SECRET are correct.
   Get credentials at: https://q.qq.com/
   Docs: https://docs.openclaw.ai/channels/qqbot

---

QQBot API request failed [${path}]. Check your network connection and that your server IP is whitelisted.

---

throw new Error(`Failed to get access_token: ${JSON.stringify(data)}`);

---

`MiniMax search requires an API key with Token Plan access. Get one at: https://platform.minimax.io/user-center/basic-information/interface-key`
RAW_BUFFERClick to expand / collapse

Summary

QQBot extension error messages are overly technical — they dump raw JSON API responses and lack actionable user guidance, documentation links, or env var hints.

Problem to solve

When QQBot encounters configuration or API errors, the error messages are developer-oriented and unhelpful for end users:

  1. Failed to get access_token (extensions/qqbot/src/api.ts line 139): throws Failed to get access_token: ${JSON.stringify(data)} — dumps the raw API JSON response with no guidance on what to check.

  2. QQBot not configured (extensions/qqbot/src/gateway.ts ~line 128, outbound.ts ~line 268): says QQBot not configured (missing appId or clientSecret) but does not mention:

    • The actual env var names (QQBOT_APP_ID, QQBOT_CLIENT_SECRET)
    • A link to the setup docs (https://docs.openclaw.ai/channels/qqbot)
    • The QQ Open Platform where credentials are obtained

  3. Network errors (extensions/qqbot/src/api.ts ~line 245): Network error [${path}] — no troubleshooting hints (e.g., check network, check whitelist, check region).

By contrast, other channels and providers in OpenClaw include docsUrl, signupUrl, and actionable hints in their error messages.

Proposed solution

Improve QQBot error messages to include:

  1. Env var names in "not configured" errors:

    QQBot not configured. Set QQBOT_APP_ID and QQBOT_CLIENT_SECRET, or run `openclaw configure`.
See: https://docs.openclaw.ai/channels/qqbot

  2. Actionable guidance in auth failures:

    Failed to get QQBot access token. Check that your QQBOT_APP_ID and QQBOT_CLIENT_SECRET are correct.
Get credentials at: https://q.qq.com/
Docs: https://docs.openclaw.ai/channels/qqbot

  3. Troubleshooting hints in network errors:

    QQBot API request failed [${path}]. Check your network connection and that your server IP is whitelisted.

Alternatives considered

  • Keeping raw JSON in errors for debugging — this can coexist with a user-friendly message prefix.
  • Adding a dedicated QQBot troubleshooting page — useful but orthogonal to improving inline error messages.

Impact

  • Affected: All QQBot channel users, especially those setting up for the first time
  • Severity: Medium (poor DX and UX on error paths)
  • Frequency: Every misconfiguration or network issue
  • Consequence: Users must search source code or ask in Discord to understand error causes, instead of being guided by the error message itself

Evidence/examples

Current error in extensions/qqbot/src/api.ts:139:

throw new Error(`Failed to get access_token: ${JSON.stringify(data)}`);

For comparison, MiniMax web search provider includes a structured error:

`MiniMax search requires an API key with Token Plan access. Get one at: https://platform.minimax.io/user-center/basic-information/interface-key`

Additional information

The QQBOT_DEBUG env var (extensions/qqbot/src/utils/debug-log.ts) is also undocumented (neither in the manifest channelEnvVars nor in docs/channels/qqbot.md). If this env var is intended for end-user troubleshooting, documenting it alongside improved error messages would help. If it is internal-only, it can remain undocumented but the error messages should still guide users to the debug flag when relevant.

extent analysis

TL;DR

Improve QQBot error messages to include env var names, actionable guidance, and troubleshooting hints to enhance user experience.

Guidance

  • Update error messages in extensions/qqbot/src/api.ts and extensions/qqbot/src/gateway.ts to include user-friendly guidance, such as env var names and documentation links.
  • Consider adding a docsUrl and signupUrl to error messages, similar to other channels and providers in OpenClaw.
  • Review the use of the QQBOT_DEBUG env var and document it if intended for end-user troubleshooting.

Example

throw new Error(`Failed to get access_token. Check that your QQBOT_APP_ID and QQBOT_CLIENT_SECRET are correct.
Get credentials at: https://q.qq.com/
Docs: https://docs.openclaw.ai/channels/qqbot`);

Notes

The proposed solution focuses on improving error messages, but it may be beneficial to also consider adding a dedicated QQBot troubleshooting page for more complex issues.

Recommendation

Apply the proposed solution to improve error messages, as it provides a clear and actionable guidance to users, enhancing their experience and reducing the need for external support.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#network issue#search optimization#API routing#API middleware

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING