5-minute quick setup
Four steps and you're chatting with an AI coding CLI from Lark:
Before you start: take a quick look at the Prerequisites. The CLI you want to use (e.g. claude, codex) must already be installed, signed in, and working in a terminal; tmux is also needed by default. Most "installed but won't connect" problems come from something missing here.
Step 1 · Install
Open a new terminal afterwards and the botmux command is ready.
- Supports Linux / macOS (x64, arm64). On musl systems such as Alpine, the musl build is picked automatically. On Windows, install inside WSL2.
- Installs to
~/.botmux/bin/botmux; setBOTMUX_INSTALL_DIRto change it. The script verifies the download's SHA-256 and adds that directory to your shell's startup file (zsh / bash / fish). - botmux itself needs no Node. If your CLI is an npm package, installing that CLI still needs Node.
You can also install with npm: npm install -g botmux (this step needs Node ≥ 22). The npm package contains the same program and behaves exactly like the curl install.
On a Mac and want to start and stop the service with a click? You can also install the macOS Desktop App: it bundles its own runtime and shares the same ~/.botmux config with the command-line install.
Upgrading later:
⚠️
BOTMUX_VERSIONonly takes effect when placed before theshon the right side of the pipe. For releases older than v3.18.0, upgrade only with curl; see FAQ · How do I upgrade? for why.
Step 2 · Configure the bot
This is an interactive wizard: use the arrow keys to choose and Enter to confirm. Pressing Esc cancels setup without writing any config. On first run it asks you the following:
① Where the Lark app comes from
After one scan on this machine, the login is remembered. Next time you add a bot, just confirm the account; no new scan needed.
② Pick a CLI: choose the CLI this bot connects to, e.g. Claude Code or Codex. You can type to search. If the CLI isn't found on this machine, you'll be told to install it first.
③ Where new topics start
In repo-card mode, try not to use
~; there are too many folders to scan.
④ Admin (owner): when you create the app by scanning, the person who scanned becomes the admin automatically. When entering credentials manually, you fill it in yourself; a full work email is recommended, a phone number also works.
Once done, setup configures the Open Platform automatically: imports all permissions, sets the redirect URL, creates and publishes a version, then prints the result of each step.
🔧 When you need to finish Open Platform config yourself
- You passed
botmux setup --no-open-platform-auto(skip auto-config), or the auto-config failed.- setup then lists the remaining items (enable bot capability, long-connection event subscription, permissions, redirect URL, publish a version) with links; the full permission list is written to
~/.botmux/lark-scopes.json.- Choosing availability "Visible to me only" usually gets the version approved automatically.
Running botmux setup on a machine that's already configured shows a menu: Add new bot, Edit existing bot, Delete bot, Reconfigure. When done, run botmux restart as prompted.
Want to configure from a script or an AI agent instead of the interactive UI? Use the
botmux setup add/botmux setup listsubcommands;botmux setup helpshows all options.
➕ Need permissions beyond the built-in list? Pass
--extra-scopes-file <json>in scripted setup (Feishu tenants only; on Lark, add them manually in the developer console), e.g.botmux setup add --create-app --allowed-users <email> --extra-scopes-file ./scopes.json; for an existing bot runbotmux setup configure <process-name|AppID> --extra-scopes-file ./scopes.json. The file uses thelark-scopes.jsonshape ({"scopes":{"tenant":[],"user":[]}}).{"scopes":[{"scope":"x:y"}]}is also accepted, but every entry in that form is requested as a user scope; use{"scopes":{"tenant":["x:y"]}}for tenant scopes. Scopes missing from the tenant catalog (including scopes that only exist for the other identity type) are skipped and listed in the result instead of failing the run. The file path is saved on the bot so laterconfigureruns reuse it; if the saved file can't be read, setup warns and continues with the built-in list. Runbotmux setup configure <process-name|AppID> --extra-scopes-file -to clear it.
👋 Welcome message on first launch:
botmux setup add ... --welcome-message "Reply /init to get started"(or--welcome-message-file welcome.txtto read it from a file) makes the bot DM its owner once after it first comes online; for an existing bot usebotmux setup edit <process-name|AppID> --welcome-message ..., and-clears it. Delivery is recorded underwelcome-sent/in the daemon data dir so restarts never resend; a failed send does not block startup and is retried on the next start. See bots.json · Welcome message.
Step 3 · Start
- Start on boot uses user systemd on Linux and launchd on macOS.
- The first
botmux startasks which "feedback storage" to use. Just press Enter for the default SQLite. You can pick PostgreSQL here if you need it, and migrate later withbotmux feedback storage(new tasks pause during migration; the original SQLite is kept, but botmux won't switch back automatically if PostgreSQL fails). See Feedback storage and migration. - Check status:
botmux status; view logs:botmux logs.
Step 4 · Create a group and start chatting
- Create a topic group in Lark (regular groups work too).
- Group settings → Group bots → add the bot you just created.
- @ the bot with a message, e.g. "@bot how do I build this project?".
- If you chose the repo selection card in step 2, a card asks you to pick a project first; with a pinned directory, the CLI starts there right away.
The bot replies with a card that updates as it works and shows the full answer when finished:

Common questions:
- Do I always need to @ it? In groups, the bot replies only when @-mentioned by default. In a group with just you and one bot, follow-ups inside a topic that's already started don't need the @. To go mention-free, see Mention policy.
- Don't want a group? Just DM the bot.
- Want to create a group in one click? Send
/g <group name>in any chat, or open the "Groups" page inbotmux dashboardand click "New Chat"; see Create a Session Group in One Step.
Not receiving messages? Self-check first
Most "no response" cases are local config or network issues. Let your AI CLI troubleshoot: it reads the logs, checks the config, and gives you a verdict.
First save the diagnostic task in a variable:
Then run the line for the CLI you have (all non-interactive; they print the verdict and exit):
The trailing
--allowedTools/--yolojust let the agent run commands to read logs.botmux logscan pinpoint almost any problem.
Still stuck? Check by hand:
Run botmux restart after fixing. See FAQ / Troubleshooting for more.
Optional events: @ by editing, recall sync, disbanded groups
Missing any of these does not affect ordinary messages; only the related small feature. New bots subscribe to them automatically; for older bots, botmux tries to add them at startup using this machine's existing Open Platform login.
Things to note:
- The startup top-up only adds events to the existing long-connection config. It does not change the delivery mode, change permissions, or publish a version. A log line saying the update request succeeded doesn't mean it's live. For production apps, review pending changes in the Open Platform, publish a version, then verify by editing a message that hasn't triggered the bot to add an @.
- If the sender's chat access comes from team membership, an edited message also needs a contact lookup to get their
union_id. This requires contact read permission (the default permission list includescontact:user.id:readonly) and the sender must be within the app's visibility scope. If the lookup fails, access is judged only by the original author'sopen_id; the editor's identity is never borrowed.
