From 3fabe324b3ec611ea7ebf0beb14a0807ed3084c6 Mon Sep 17 00:00:00 2001 From: Julian Engel Date: Fri, 6 Mar 2026 16:12:37 +0100 Subject: [PATCH 1/4] docs: add helper tools, workflows, welcome message, and improve Krill guide - Rewrite helpers/krill.md with usage tips, pre-posting checklist, and limitations - Add helpers/tools.md with Hermit /helper and /say commands reference - Add helpers/workflows.md for common helper scenarios (off-topic, long threads, unrelated help) - Add helpers/welcome-message.md showing the auto-posted thread welcome message --- helpers/krill.md | 49 ++++++++++++++++++++++++++++++++++++-- helpers/tools.md | 28 ++++++++++++++++++++++ helpers/welcome-message.md | 29 ++++++++++++++++++++++ helpers/workflows.md | 40 +++++++++++++++++++++++++++++++ 4 files changed, 144 insertions(+), 2 deletions(-) create mode 100644 helpers/tools.md create mode 100644 helpers/welcome-message.md create mode 100644 helpers/workflows.md diff --git a/helpers/krill.md b/helpers/krill.md index 90a79b1..f1eb749 100644 --- a/helpers/krill.md +++ b/helpers/krill.md @@ -1,3 +1,48 @@ -Krill is the OpenClaw instance that functions as our support bot in #help and #ideas. It is hosted on Peter's account on https://exe.dev, and only Shadow can access it. It is responsible for answering support questions in #help automatically, with the full context of the docs and the codebase. +# Krill -If you need assistance with it, or it goes offline, directly ping Shadow. \ No newline at end of file +Krill is the OpenClaw AI instance that functions as our support bot in **#help** and **#ideas**. It has full context of the OpenClaw docs and codebase, and answers support questions automatically. + +## Hosting + +- Hosted on [exe.dev](https://exe.dev) (Peter's account) +- Only **Shadow** has access + +**If Krill goes down directly ping Shadow.** + +## How Krill Works + +Krill cannot see a user's system. Krill has access to the latest docs + codebase and only information it has is what you include in your message. This means vague questions like "it doesn't work" are almost impossible for Krill to help with. + +## Before Posting to Krill + +Check the docs first — this is usually the fastest way to solve your issue: +[FAQ: I'm stuck, what's the fastest way to get unstuck?](https://docs.openclaw.ai/help/faq#im-stuck-whats-the-fastest-way-to-get-unstuck) + +The recommended approach is to use a **local AI agent** that can see your machine and setup, which is often far more effective than asking in chat. + +If you still need help, include: + +1. **What you're trying to do** (goal / expected behaviour) +2. **What happened instead** (exact error message) +3. **What you ran or clicked** (commands, config snippet, etc.) +4. **Your environment** (OS, install method, versions) +5. **Relevant logs** (smallest useful snippet) + +Posts like "it doesn't work" without details are almost impossible to debug. + +## Tips for Getting Good Answers + +- **Be specific.** Krill performs best with clear, detailed questions. +- **Paste error messages.** Krill can parse and diagnose errors quickly when given the exact text. +- **Include code snippets.** If your question involves config or code, paste the relevant section. +- **One question per message.** Splitting complex issues into focused questions yields better results. +- **Follow up with context.** If Krill's first answer doesn't solve your problem, reply with what you tried and what happened. +- **One Problem per thread.** If your initial question/issue is resolved, mark it as completed please and create a new thread for any new issues. + + +## Limitations + +- Krill **cannot** access your filesystem, terminal, or browser. +- Krill **cannot** run code or commands on your behalf. +- Krill's knowledge is based on the docs and codebase — it may not know about very recent changes that haven't been synced yet. +- For issues that require seeing your system state, a local AI agent is a better tool. diff --git a/helpers/tools.md b/helpers/tools.md new file mode 100644 index 0000000..822b6f7 --- /dev/null +++ b/helpers/tools.md @@ -0,0 +1,28 @@ +# Helper Tools + +This is a reference of the tools available to the Helper team. + +## Krill (Support Bot) + +OpenClaw AI instance in **#help** and **#ideas** that answers support questions automatically using the full docs and codebase context. + +See [krill.md](krill.md) for detailed usage and guidelines. + +## Hermit Commands + +Hermit is our custom bot ([source](https://github.com/openclaw/hermit)). It provides three command groups: + +### `/helper` — Thread moderation utilities + +Commands for managing help threads. These also fire a webhook for tracking. + +| Command | What it does | +|---|---| +| `/helper warn-new-thread` | Warns that the thread is too long and should be split. Asks Krill to summarize the conversation. Optionally mention a user. | +| `/helper close-thread` | Posts a close notice, then archives and locks the thread. Only works inside a thread. | + +Hermit also automatically posts a **welcome message** when a new thread is created in the help channel, reminding users to include details (goal, error, commands, environment, logs). + +## Answer Overflow + +Indexes **#help** threads for SEO so that common questions are discoverable via search engines. Managed at [answeroverflow.com](https://answeroverflow.com). \ No newline at end of file diff --git a/helpers/welcome-message.md b/helpers/welcome-message.md new file mode 100644 index 0000000..b16d4af --- /dev/null +++ b/helpers/welcome-message.md @@ -0,0 +1,29 @@ +# Help Thread Welcome Message + +When a new thread is created in the help channel, Hermit automatically posts the following welcome message: + +--- + +> Welcome to the help channel! +> +> Krill cannot see your system — it only knows what you tell it. The more details you include, the easier it is to help. +> +> If you haven't included it yet, please consider sending: +> +> What you're trying to do (goal / expected behaviour) +> +> What happened instead (exact error message) +> +> What you ran or clicked (commands, config snippet, etc.) +> +> Your environment (OS, install method, versions) +> +> Relevant logs (the smallest useful snippet) +> +> Posts like "it doesn't work" without details are very hard to debug. +> +> If new issues arise, please open a new thread/topic instead of continuing in this one. Keeping one issue per thread helps ensure answers stay accurate and makes it easier for others to find solutions later. + +--- + +This template is defined in [hermit/src/events/threadCreateWelcome.ts](https://github.com/openclaw/hermit/blob/main/src/events/threadCreateWelcome.ts) and can be overridden via the `HELPER_THREAD_WELCOME_TEMPLATE` environment variable. diff --git a/helpers/workflows.md b/helpers/workflows.md new file mode 100644 index 0000000..4f80bef --- /dev/null +++ b/helpers/workflows.md @@ -0,0 +1,40 @@ +# Helper Workflows + +Common workflows and situations that helpers encounter. + +## When a Thread Goes Off-Topic + +1. Politely redirect the conversation back to the original question. +2. If it continues, use `/helper warn-new-thread` to ask participants to move to a new thread. +3. If the thread is beyond recovery, use `/helper close-thread` to archive and lock it. +4. If the original question is still unanswered, re-surface it in a new thread after locking. + +## When a Thread Gets Too Long + +1. Use `/helper warn-new-thread` to warn users the thread is too long. This also asks Krill to summarize the conversation so far. +2. If the thread continues or spans multiple topics, use `/helper close-thread` to post a close notice and archive/lock it. +3. Ask the user to open a new thread with a clean summary including: + - The original goal + - What has been tried + - The current error or blocker +4. Link the old thread in the new one for context. + +## When Someone Asks for Unrelated Help + +If someone asks for help that is **not related to OpenClaw** (e.g., general programming questions, other tools/products): + +1. Be polite. +2. Let them know that **#help** is specifically for OpenClaw support. +3. Close/Lock the thread please. + +## Escalation + +- **Recurring issue/bug:** If the same issue keeps coming up, let your Team Lead and/or Admin know. +- **Krill is down:** Ping Shadow( Admin) directly. +- **Security issue:** Escalate to Shadow (Admin) immediately. + +## Thread Hygiene + +- When a question is resolved, use the discord context menu to mark the message as answer. +- One issue per thread — if a new issue arises, use `/helper warn-new-thread` to ask for a new thread. +- Keep threads focused so that Answer Overflow can index them cleanly for others to find later. From e8b17a8e24edb52f02716234532fe80f81ec6030 Mon Sep 17 00:00:00 2001 From: Julian Engel Date: Fri, 6 Mar 2026 16:19:29 +0100 Subject: [PATCH 2/4] docs: add /helper close and /github commands to tools reference --- helpers/tools.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/helpers/tools.md b/helpers/tools.md index 822b6f7..87b21ed 100644 --- a/helpers/tools.md +++ b/helpers/tools.md @@ -19,9 +19,16 @@ Commands for managing help threads. These also fire a webhook for tracking. | Command | What it does | |---|---| | `/helper warn-new-thread` | Warns that the thread is too long and should be split. Asks Krill to summarize the conversation. Optionally mention a user. | +| `/helper close` | Close and lock the current thread (shorthand). Only works inside a thread. | | `/helper close-thread` | Posts a close notice, then archives and locks the thread. Only works inside a thread. | -Hermit also automatically posts a **welcome message** when a new thread is created in the help channel, reminding users to include details (goal, error, commands, environment, logs). +Hermit also automatically posts a **welcome message** when a new thread is created in the help channel, reminding users to include details (goal, error, commands, environment, logs). See [welcome-message.md](welcome-message.md) for the full template. + +### `/github` — GitHub issue/PR lookup + +| Command | What it does | +|---|---| +| `/github number:` | Fetches and displays a GitHub issue or pull request. Defaults to `openclaw/hermit`. Optionally specify `user:` and `repo:` for other repositories. | ## Answer Overflow From cf8cd87ee1d795e3ca2c6f3220238ec4297e0ff2 Mon Sep 17 00:00:00 2001 From: Julian Engel Date: Fri, 6 Mar 2026 16:21:06 +0100 Subject: [PATCH 3/4] docs: remove /github command from tools reference --- helpers/tools.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/helpers/tools.md b/helpers/tools.md index 87b21ed..4a8952f 100644 --- a/helpers/tools.md +++ b/helpers/tools.md @@ -24,12 +24,6 @@ Commands for managing help threads. These also fire a webhook for tracking. Hermit also automatically posts a **welcome message** when a new thread is created in the help channel, reminding users to include details (goal, error, commands, environment, logs). See [welcome-message.md](welcome-message.md) for the full template. -### `/github` — GitHub issue/PR lookup - -| Command | What it does | -|---|---| -| `/github number:` | Fetches and displays a GitHub issue or pull request. Defaults to `openclaw/hermit`. Optionally specify `user:` and `repo:` for other repositories. | - ## Answer Overflow Indexes **#help** threads for SEO so that common questions are discoverable via search engines. Managed at [answeroverflow.com](https://answeroverflow.com). \ No newline at end of file From bbd339bfcc732d6284bcd7b08896faec0102e1c7 Mon Sep 17 00:00:00 2001 From: Julian Engel Date: Mon, 9 Mar 2026 16:19:03 +0100 Subject: [PATCH 4/4] docs: document Solved (Mod) helper workflow --- helpers/tools.md | 12 +++++++++++- helpers/workflows.md | 3 ++- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/helpers/tools.md b/helpers/tools.md index 4a8952f..7e292ae 100644 --- a/helpers/tools.md +++ b/helpers/tools.md @@ -24,6 +24,16 @@ Commands for managing help threads. These also fire a webhook for tracking. Hermit also automatically posts a **welcome message** when a new thread is created in the help channel, reminding users to include details (goal, error, commands, environment, logs). See [welcome-message.md](welcome-message.md) for the full template. +### `Solved (Mod)` - Moderator solution marker + +Use the Discord message context menu item `Solved (Mod)` when a moderator needs to mark a reply as the answer for a thread. + +Why use it: + +- it marks the solution in Answer Overflow +- it logs the moderation action in Hermit's worker event pipeline +- it keeps thread-resolution handling consistent with the rest of the helper tooling + ## Answer Overflow -Indexes **#help** threads for SEO so that common questions are discoverable via search engines. Managed at [answeroverflow.com](https://answeroverflow.com). \ No newline at end of file +Indexes **#help** threads for SEO so that common questions are discoverable via search engines. Managed at [answeroverflow.com](https://answeroverflow.com). diff --git a/helpers/workflows.md b/helpers/workflows.md index 4f80bef..a1ec32b 100644 --- a/helpers/workflows.md +++ b/helpers/workflows.md @@ -35,6 +35,7 @@ If someone asks for help that is **not related to OpenClaw** (e.g., general prog ## Thread Hygiene -- When a question is resolved, use the discord context menu to mark the message as answer. +- When a question is resolved and a moderator needs to mark the answer, use the `Solved (Mod)` message context menu item. +- Do not rely on ad-hoc reactions or manual notes for this. `Solved (Mod)` updates Answer Overflow and records the action in Hermit's worker event flow. - One issue per thread — if a new issue arises, use `/helper warn-new-thread` to ask for a new thread. - Keep threads focused so that Answer Overflow can index them cleanly for others to find later.