Skip to content

Operator & Group Admin Guide ​

This page is for operators, group owners, and community / support leads: you keep the bot working well in your groups, but you don't write TypeScript. Everything you need lives in the browser-based Console and one configuration file.

Is this page for you?

  • Yes if you want welcomes, check-ins, reminders, feed pushes or content moderation in your groups, want to see what the bot is doing, and want to check problems yourself first.
  • No if you want to write new commands, plugins or platform adapters — that's developer work; see the developer quick start.

What Zhin does for you ​

OutcomeHowCode needed?
One bot managing groups on QQ, WeChat, WeCom, Lark, Discord and moreA developer deploys once; you watch everything under Console → Accounts and conversationsNo
Welcome new members, only in selected groupsGroup welcome guideNo
Check-in points, message stats, group Q&A / keyword repliesInstall the group suite @zhin.js/plugin-group-suite from the Plugin storeNo
Scheduled and event remindersReminders without AINo
Push feed updates into a groupAdmin RSS subscriptionsNo
Block ads, abuse and other unwanted contentInstall @zhin.js/plugin-content-moderationNo
An AI assistant that chats and answers business questionsA developer enables AI; you observe and stop it from ConsoleDeveloper for setup
Announcements that only go out after a human approves; risky admin actions gatedSee Group ops, announcements and approvalsNo

Not sure yet? Open the online demo to see Console (the demo is read-only).

Connect Console ​

Console is a standalone web app; you don't deploy it:

  1. Ask whoever deployed the bot for two things: the API address (e.g. http://127.0.0.1:8068 or your domain) and a Console account (username and password).
  2. Open console.zhin.dev, enter the address and sign in.
  3. When the accounts (Endpoints) on the home page show online, you're connected.

Keep credentials private

Never paste a password or API token in a group, a screenshot or a link. Everyone gets their own account: an operator can send messages and change feature settings; a viewer can only read. Colleagues who only watch status need nothing more than a viewer account.

No running bot yet? A developer or ops person does this once: create a project with the quick start or go live with Deployment and Recovery. Day-to-day operations then happen in Console.

Daily operations: find the right page ​

I want to…Console page
Check health and which account is offlineHome
Connect a platform accountAccounts and conversations → Connect platform account
Message a group or DM, see recent messagesAccounts and conversations → account → Chat tab
Review what the bot saidChat history
Try replies without a real platformTry a conversation (Sandbox)
See why the AI replied or stayed silent, and which tools it usedBot status (incl. decision replay)
Make the bot go quiet nowHome → AI runtime controls (see Emergency stop)
Manage scheduled remindersOperations → Scheduled tasks
Install pluginsPlugin store
Turn a plugin on or off in one groupAccounts and conversations → adapter → account → conversation → Features tab
Let a group owner or colleague manage features in a groupThe Roles tab of that conversation (or account, adapter) page
Follow a guided setup (e.g. new-member welcome)Operations → Scheduled tasks → Administrator tasks → start by use case
Investigate errors, find out why there was no replyRecent diagnostics in the conversation's Chat tab, Runtime logs

Details for every page: Console path and Console reference.

Change settings without code ​

The bot's behavior comes from one file, zhin.config.yml. You don't need to edit it by hand:

  • Install features from the Plugin store; decide in the Features tab of the object pages whether each is on globally, on one platform, one account or one group (see Turn a plugin off in a conversation).
  • Change feature settings in each plugin's form — welcome text, check-in points, keyword limits. The form follows the fields the plugin declares and won't save malformed values.
  • Secrets such as platform credentials and model keys go in Operations → Environment variables, not in regular config.
  • Confirm it applied: a successful save is not the same as live. Follow the page's distinction between "restart required" and "plugin config pending verification", use "read apply evidence" when needed, and treat the runtime capabilities page as the source of truth.
Comfortable with a terminal?

In the bot's project folder, npx zhin setup adds platforms, AI and a database through a wizard; npx zhin doctor diagnoses ports, tokens and config. All fields: Configuration.

Group ops, announcements and approvals ​

Zhin's rule: every bot decision is traceable, risky actions need approval, and you can stop everything with one switch.

Welcomes and group operations ​

  • Welcome new members: the group suite's welcome is off by default and only sends once you set a welcome text; you can limit it to selected groups. See Welcome only selected groups.
  • Check-ins, stats, Q&A: after installing the group suite, members use commands such as checkin and stats; only group owners, admins or trusted users can change keywords and Q&A.
  • Content moderation scans inbound and outbound messages and blocks or masks them by severity.

Announcements: draft → approve → send ​

  • The AI may draft an announcement, but it can't submit, approve or send it.
  • It goes out only after someone with approval rights (Console permission ops:approve) approves; editing the text after approval blocks the send.
  • Pending drafts expire after 24 hours; failed sends are never retried silently — Console shows why, and a resend needs a fresh approval.

Approving risky actions ​

For risky actions such as kicking a member, messaging another group or changing config, the bot only creates an approval card for an authorized person to approve or deny. The same action in the same group has a cooldown, so repeated clicks produce one card. In groups you can choose approval scopes like "this time only / this conversation / always"; see AI approvals.

Emergency stop ​

The AI runtime controls on Home have four switches, per bot or per group, kept across restarts:

SwitchEffect
Emergency stop (emergency_stop)No model calls, no outbound messages (including scheduled ones)
Muted (muted)The bot doesn't speak
Read-only (read_only)No write actions
Mention only (mention_only)Replies only when @-mentioned or in DMs

The AI has no way to turn these switches off. Every block and change is recorded in decision replay, so you can see who changed what and when.

Current status

Announcements, conversation welcomes, conversation schedules and the control plane are provided by the bot (Host); some matching Console pages are still rolling out, and older Console versions may not show them. If you can't find one, update Console or ask a developer. Rule-based automatic muting ("dynamic group rules") is still planned (#1050); today all admin actions need human approval.

Check problems yourself first ​

  1. Home: is the bot connected and are accounts online? If an Instance unavailable banner is at the top, click View instance.
  2. The conversation's Chat tab: did the member's message reach the bot? Open that message's "Diagnostics", or Recent diagnostics in the conversation header.
  3. The conversation's Features tab: is the relevant plugin on in this group?
  4. Runtime capabilities: is the relevant feature loaded?
  5. Bot status, and the conversation's Records tab → Decision replay: how far did the AI get, and why didn't it reply?

More in Find where a message stopped and the Troubleshooting center.

When to call a developer ​

SituationWhy
First deployment, moving servers, major upgradesNeeds the command line and server access; see Deployment and Recovery and Compatibility and Migration
A new command or feature no existing plugin providesNeeds a plugin; see First plugin
A platform with no adapter yetNeeds an adapter; see Adapter authoring
Letting the AI call your business systemsNeeds AI tools; see Agent tools
Console can't connect, CORS errors, reverse proxy issuesNeeds server config; see Deployment and Recovery
Errors in the runtime logs you can't interpretSend the error and time to a developer; see the Troubleshooting center

When you reach out, include: which group, when, what you expected, what actually happened, and a screenshot of Bot status or the runtime logs (hide the token).

Further reading ​