Skip to content

openclaw/hermit

BranchesTags

Repository files navigation

Hermit

Hermit is the OpenClaw Discord bot built on Carbon, Bun, and SQLite.

It handles:

  • Discord slash commands and message-context moderation actions
  • helper-thread onboarding and thread-length enforcement
  • keyword-based automod responses
  • announcement crossposting for selected channels
  • local event and helper-thread state persistence in SQLite
  • a read-only local dashboard for helper events and tracked threads

Repository: openclaw/hermit

Runtime Overview

Hermit runs as a gateway-first Discord bot:

  • Bun is the runtime and package manager
  • Carbon handles command registration, gateway events, and Discord API access
  • Drizzle manages the SQLite schema and migrations
  • SQLite stores helper event history and tracked helper thread state
  • A small Bun HTTP server exposes read-only operational visibility

Main entrypoint: src/index.ts

Features

  • /github looks up GitHub issues and pull requests
  • Solved (Mod) marks a thread as solved in Answer Overflow and closes it
  • /say ... posts common guidance and documentation links
  • /helper ... posts helper-thread moderation messages and closes threads
  • /role ... toggles specific server roles
  • helper-thread creation triggers a welcome message and thread tracking
  • a background monitor warns on long threads and auto-closes very long ones
  • automod rules can repost/redact matching messages and send guidance replies
  • selected announcement channels are auto-crossposted

Requirements

  • Bun
  • a Discord application and bot token
  • access to the target Discord server
  • SQLite filesystem access for DB_PATH

Installation

  1. Install dependencies:
bun install
  1. Create a .env file.

Recommended variables:

DISCORD_CLIENT_ID="your-client-id"
DISCORD_BOT_TOKEN="your-bot-token"
DISCORD_DEV_GUILDS="guild_id_1,guild_id_2"

ANSWER_OVERFLOW_API_KEY="your-answer-overflow-api-key"
ANSWER_OVERFLOW_API_BASE_URL="https://www.answeroverflow.com"

HELPER_THREAD_WELCOME_PARENT_ID="123456789012345678"
HELPER_THREAD_WELCOME_TEMPLATE="Welcome to helpers. Please include expected vs actual behavior, what you already tried, and relevant logs/code."
THREAD_LENGTH_CHECK_INTERVAL_HOURS="2"

DB_PATH="data/hermit.sqlite"
DRIZZLE_MIGRATIONS="drizzle"

HELPER_LOGS_HOST="127.0.0.1"
HELPER_LOGS_PORT="8787"
  1. Apply migrations:
bun run db:migrate
  1. Start Hermit:
bun run dev

Scripts

  • bun run dev starts Hermit in watch mode
  • bun run start starts Hermit normally
  • bun run typecheck runs TypeScript without emitting files
  • bun run db:migrate applies Drizzle migrations to SQLite
  • bun run db:generate generates Drizzle migration files from the schema

Environment Variables

Required

  • DISCORD_CLIENT_ID: Discord application client ID
  • DISCORD_BOT_TOKEN: Discord bot token

Optional

  • DISCORD_DEV_GUILDS: comma-separated guild IDs for dev command registration
  • ANSWER_OVERFLOW_API_KEY: required for Solved (Mod) to call Answer Overflow
  • ANSWER_OVERFLOW_API_BASE_URL: defaults to https://www.answeroverflow.com
  • HELPER_THREAD_WELCOME_PARENT_ID: parent forum or helper channel whose new threads should receive the welcome message
  • HELPER_THREAD_WELCOME_TEMPLATE: overrides the default helper welcome text
  • THREAD_LENGTH_CHECK_INTERVAL_HOURS: enables the helper thread monitor when set to a positive number
  • DB_PATH: SQLite database path, defaults to data/hermit.sqlite
  • DRIZZLE_MIGRATIONS: migration directory, defaults to drizzle
  • HELPER_LOGS_HOST: host for the read-only helper dashboard, defaults to 127.0.0.1
  • HELPER_LOGS_PORT: port for the read-only helper dashboard, defaults to 8787; set to 0 to disable it
  • SKIP_DB_MIGRATIONS: set to 1 to skip automatic migration-on-startup

Commands

/github

Looks up a GitHub issue or pull request and returns:

  • title and state
  • repo and author
  • labels
  • description summary
  • recent comments
  • pull request change stats when applicable

Options:

  • number required
  • user optional, defaults to openclaw
  • repo optional, defaults to hermit

Available in:

  • guilds
  • bot DMs

Source: src/commands/github.ts

Solved (Mod)

Message-context moderation action that:

  • posts the chosen solution message to Answer Overflow
  • adds a checkmark reaction to the solved message
  • archives and locks the thread
  • records a mark_solution helper event in SQLite

Permissions:

  • ManageMessages
  • ManageThreads

Requires:

  • ANSWER_OVERFLOW_API_KEY

Source: src/commands/solvedMod.ts

/say

Posts common canned guidance messages.

Subcommands:

  • guide
  • server-faq
  • help
  • user-help
  • model
  • stuck
  • ci
  • answeroverflow
  • pinging
  • docs
  • security
  • install
  • blog-rename

Available in:

  • guilds
  • bot DMs

Source: src/commands/say.ts

/helper

Helper-channel moderation utilities.

Subcommands:

  • warn-new-thread: posts the long-thread warning message
  • close: posts the close message, archives the thread, and locks it
  • close-thread: same behavior as close

These commands also emit helper events into SQLite.

Source: src/commands/helper.ts

/role

Toggles specific hard-coded server roles.

Current subcommands:

  • showcase-ban
  • clawtributor

Permissions:

  • command requires ManageRoles
  • runtime access also checks that the invoking member has the hard-coded communityStaff role

Source: src/commands/role.ts

Gateway Events And Background Behavior

Ready

On startup, Hermit logs the connected username and starts the helper thread monitor when configured.

Source: src/events/ready.ts

Thread Create Welcome

When a new thread is created under HELPER_THREAD_WELCOME_PARENT_ID, Hermit:

  • stores the thread in tracked_threads
  • records a thread_welcome_created event
  • posts the helper welcome message

Source: src/events/threadCreateWelcome.ts

Thread Length Monitor

When THREAD_LENGTH_CHECK_INTERVAL_HOURS is set, Hermit polls tracked helper threads with setInterval.

Behavior:

  • loads open tracked threads from SQLite
  • fetches the Discord thread live
  • updates message counts and close state
  • warns at more than 100 messages
  • warns again at more than 150 messages
  • posts a close notice and archives/locks at more than 200 messages

Configured messages live in:

Source: src/services/threadLengthMonitor.ts

AutoModeration Action Execution

Hermit listens to automod keyword actions and can:

  • repost the triggering content through a webhook
  • redact the matched trigger in the repost
  • send a follow-up warning/guidance message
  • optionally include a role mention in the guidance message

Automod rule configuration lives in:

Message template placeholders:

  • {user}
  • {keyword}
  • {content}

Source: src/events/autoModerationActionExecution.ts

Auto Publish Message Create

Hermit auto-crossposts messages from a fixed set of announcement channel IDs.

Source: src/events/autoPublishMessageCreate.ts

Database

Hermit uses SQLite via Bun and Drizzle.

Database bootstrap: src/db.ts

Schema definition: src/db/schema.ts

Tables

keyValue

Generic key/value storage with:

  • key
  • value
  • createdAt
  • updatedAt

helper_events

Operational event log for helper-related actions.

Fields:

  • id
  • event_type
  • thread_id
  • message_count
  • event_time
  • command
  • invoked_by_id
  • invoked_by_username
  • invoked_by_global_name
  • received_at
  • raw_payload

Typical event types:

  • mark_solution
  • helper_command
  • thread_welcome_created

tracked_threads

Persistent helper-thread state used by the monitor.

Fields:

  • id
  • thread_id
  • created_at
  • last_checked
  • solved
  • warning_level
  • closed
  • last_message_count
  • received_at
  • raw_payload

Migrations

Drizzle configuration: drizzle.config.ts

Migration runner: src/scripts/migrate.ts

Committed SQL migrations live under:

On startup, Hermit automatically applies migrations unless SKIP_DB_MIGRATIONS=1.

Read-Only Helper Logs HTTP Server

Hermit starts a small Bun HTTP server for local visibility into helper activity.

Default address:

  • http://127.0.0.1:8787

Routes:

  • GET /: dashboard UI for helper events
  • GET /api/events: JSON event listing
  • GET /api/threads: JSON tracked-thread listing

Supported GET /api/events query params:

  • eventType
  • command
  • threadId
  • invokedBy
  • from
  • to
  • limit up to 500

Supported GET /api/threads query params:

  • threadId
  • solved
  • closed
  • limit up to 500

Source: src/server/helperLogsServer.ts

Configuration Files

Development Notes

  • Hermit is Bun-first; package-lock.json is intentionally not used
  • command registration and gateway listeners are wired in src/index.ts
  • helper events and tracked-thread writes are internal; the HTTP server is read-only
  • the thread-length scheduler is interval-based, not cron-based

Verification

Useful local checks:

bun run typecheck
bun run db:migrate
bun run dev

License

MIT

About

No description, website, or topics provided.

Resources

Readme

Security policy

Security policy
Activity
Custom properties

Stars

32 stars

Watchers

5 watching

Forks

39 forks
Report repository

Sponsor this project

Contributors

Languages