#bots.json Configuration

Configure bots via ~/.botmux/bots.json. Run botmux setup to create it interactively, or edit it by hand. The file is an array; each element is a bot (in production, one bot maps to one dedicated daemon process).

Most fields are optional — just larkAppId / larkAppSecret is enough to run; add the rest as needed. Applies to: manually tuning CLI / model / working dir / permissions / sandbox, etc.; for everyday config the dashboard's Bot Config page is preferred (it edits the same bots.json). Run botmux restart to apply changes.

[
  {
    "larkAppId": "cli_xxx_bot1",
    "larkAppSecret": "secret_1",
    "name": "claude-main",
    "cliId": "claude-code",
    "model": "sonnet",
    "lang": "zh",
    "workingDir": "~/projects",
    "allowedUsers": ["alice@company.com"],
    "allowedChatGroups": ["oc_xxx_team"],
    "p2pOpen": true,
    "oncallChats": [{ "chatId": "oc_xxx_oncall", "workingDir": "~/projects/foo" }]
  },
  {
    "larkAppId": "cli_xxx_bot2",
    "larkAppSecret": "secret_2",
    "cliId": "codex",
    "model": "gpt-5-codex",
    "workingDir": "~/work",
    "autoStartOnNewTopic": true
  }
]

There are many fields, listed below grouped by purpose. The vast majority are optional — just larkAppId / larkAppSecret is enough to get running, and you add the rest as needed.

#Required

#CLI and model

#Codex-compatible distributions

An independently released CLI that preserves Codex's arguments, interaction, rollout / resume, and authentication semantics does not need a new cliId. Keep cliId: "codex" as the protocol adapter and describe the concrete runtime separately:

{
  "cliId": "codex",
  "cliPathOverride": "vendor-codex",
  "cliRuntime": {
    "id": "vendor-codex",
    "displayName": "Vendor Codex",
    "executable": "vendor-codex",
    "update": { "provider": "npm", "packageName": "@vendor/codex" }
  }
}

• id is a stable identity using letters, numbers, ., _, or -, up to 64 characters. Changing it is treated as switching distributions.
• executable is one executable name or path, not a shell command; do not append arguments. The Dashboard performs a read-only --version probe before saving, and its output must contain a recognizable X.Y.Z version.
• displayName controls cards, status, and Dashboard labels only; it defaults to id.
• update.provider is one of auto, self, npm, or none. auto trusts only a unique npm package proven to own that exact binary. If no source can be established, the runtime is shown as unmanaged and is never compared with official Codex. Only self uses the CLI's structured doctor data, and its current version must match --version; npm requires the distribution's own packageName; none disables update checks for that runtime.
• cliRuntime currently applies only to cliId: "codex" and cannot be combined with wrapperCli. BotMux writers generate a cliPathOverride downgrade shadow that exactly matches executable: new versions use cliRuntime as canonical, while old versions still launch the same binary from the shadow. Manual configs must include the same exact shadow as shown above; a missing or mismatched value fails validation so an accepted config is always safe to roll back. Wrappers and gateways keep using the legacy entry-point mechanism below.
• Existing cliPathOverride configs remain launch-compatible and receive the same safe auto update behavior. The Dashboard shows them in a read-only compatibility state: model-only saves preserve the old entry point, choosing Official Codex explicitly clears it, and choosing Custom Compatible migrates it to cliRuntime. Because a raw path does not assert the full compatibility contract, Codex RPC enhancements remain disabled.

A session freezes its runtime snapshot when created. Model-only changes affect new sessions; switching CLI, runtime, or wrapper immediately closes active sessions that still use the old launch identity so they cannot lazy-resume into the wrong distribution. Existing sessions are never silently switched to another runtime.

#Run a bot on GLM / a third-party provider (per-bot env)

Run one bot on a GLM Coding Plan (or any Anthropic-compatible provider) while another keeps using official Claude — give the former an env:

{
  "cliId": "claude-code",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "your GLM Coding Plan key"
  }
}

• For GLM in China, use https://open.bigmodel.cn/api/anthropic for ANTHROPIC_BASE_URL.
• For an OpenAI-protocol CLI like Codex, set OPENAI_BASE_URL / OPENAI_API_KEY (the provider's OpenAI-compatible endpoint) instead of ANTHROPIC_*.
• Isolation: env is injected per-session into the CLI process, consistently across backends (tmux / zellij inject it per-pane, never into the shared server env), so one bot's provider config can't leak into another's.
• Security: values live in bots.json and the process environment in plaintext — not a secret vault; chat surfaces like /config get mask the values (the owner-authenticated dashboard editor shows real values).
• Takes effect from the next session.

#Clean Codex App input (experimental)

codexAppCleanInput keeps user messages shown in Codex App clean while preserving the context Botmux needs when invoking the model. It defaults to false / off; when disabled, Botmux keeps the original combined-prompt behavior unchanged.

An owner or allowedUsers member can hot-update it with /botconfig; no daemon restart is required:

/botconfig set codexAppCleanInput on
/botconfig set codexAppCleanInput off

You can also add it to the corresponding bot entry directly (manual bots.json edits still require the restart described at the end of this page):

{
  "cliId": "codex-app",
  "codexAppCleanInput": true
}

• The flag applies only to Botmux-managed sessions whose actual CLI is codex-app; other CLIs and externally bridged /adopt sessions are unaffected. A session-frozen CLI takes precedence over a later bot-default CLI change.
• When enabled, user-authored turns use the original text as the Codex App text UserMessage; Botmux-authored synthetic turns such as external triggers and document prewarm use a short readable label. Message-level sender, mentions, attachment paths, quotes, role, whiteboard, Skills, and synthetic-turn instructions primarily move to hidden additionalContext. Readable absolute-path images are also sent as localImage; missing, relative, or unreadable images skip the native image item with a diagnostic while their attachment path remains in context.
• A detectable Codex CLI >= 0.135 enables clean text plus additionalContext; >= 0.136 also attaches a separate clientUserMessageId. Older or unknown versions use the legacy combined prompt directly.
• The runner retries the legacy prompt once only when app-server explicitly rejects additionalContext / clientUserMessageId before turn/started, then disables clean mode for that runner lifetime. Network, timeout, model, and generic turn errors are never auto-retried, avoiding duplicate work.
• A /botconfig change is sampled at the next dispatch to the Codex worker. For ordinary live messages this is normally the next message; a first turn waiting on repo selection is sampled when the repo is committed. Already queued or running turns are not rewritten, and existing history is never backfilled.
• additionalContext is omitted from the ordinary Codex App user-message bubble, but it may still be retained in raw rollout or diagnostic records. When enabled, Botmux also keeps the legacy prompt and structured sidecar for compatibility fallback and retry_last_task. This feature improves App presentation and ordinary history reading; it is not a privacy-erasure or security-redaction mechanism.

#Working directory

#Permissions and authorization

#File sandbox

ZMX cannot enforce the file sandbox or effective read isolation, so configurations that enable those boundaries fail closed; see ZMX backend boundaries.

#Cards and terminal

#Proactive start

#Group message listener

Have a bot actively watch a group: matching group messages start a session automatically, no @ required. The classic use is alert operations — your monitoring/alerting system usually already has its own Lark bot posting alerts into a group, so just add this bot to that group and enable the listener; every alert triggers an investigation session, with no need to set up a separate Webhook integration point.

Configure it per-group in the Dashboard "Roles → Message Listener" tab (with Preview of the last 24h of matches and a dry run to validate); or write messageListeners directly in bots.json (keyed by chat_id, valued by the config below):

{
  "messageListeners": {
    "oc_xxxxxxxxxxxxxxxx": {
      "enabled": true,
      "name": "Alert listener",
      "prompt": "Every alert in this group is a production event. Identify the affected service and give an initial investigation direction; if it's a false alarm, explain why.",
      "senderPolicy": { "mode": "all_except_excluded", "includeSenderTypes": ["bot"] }
    }
  }
}

Conventions and limits (V1):

• Top-level group messages only: ordinary replies inside an existing topic are not handled; a message that explicitly @s this bot still goes through normal @ routing (no double trigger).
• One session per matched message, replied to in a new topic beneath it.
• Delivery: the realtime event path covers messages Lark pushes; messages from other bots, and non-@ messages, are backfilled by a history poll roughly every 30s (so up to ~30s of latency). That's why listening to a third-party alert bot works most reliably in blacklist mode (all_except_excluded + include "bot") — whitelist matches by open_id, but the history API reports third-party bots by app_id, which may not resolve to an open_id and therefore won't match.

#Summary command

Example:

{
  "summaryRange": {
    "limit": 50,
    "sinceHours": 24
  },
  "summaryMemory": true,
  "summaryMemoryPath": "docs/summary.md"
}

• Only the explicit @bot /summary command triggers a summary. Messages that do not mention the bot still follow the existing group/topic routing rules and are not woken up by keywords.
• The dashboard "/summary Range" controls this summaryRange field; the "Enable memory" toggle and "Memory file path" input save summaryMemory and summaryMemoryPath respectively.
• If an earlier @same bot /summary exists before the current trigger, the summary window includes only messages after that earlier command and up to the current trigger; otherwise botmux falls back to limit / sinceHours.
• limit and sinceHours are safety caps for the default (no explicit boundary) summary window. If both are 0, that dimension is not limited. An explicit boundary intentionally takes precedence over these caps: when summaryMemory is on and /summary carries boundary text, botmux honors the user's explicit "start from this message" intent and includes everything from the matched boundary onward — in a regular group limit still bounds the scan, but a boundary older than sinceHours, and any arbitrarily old boundary in a topic group, is accepted and may exceed the default configured range. If you do not want a bot to read in very old content, the reliable approach is to omit the boundary text; in a regular group you can also lower limit to bound the scan (but sinceHours, and any boundary in a topic group, are not constrained by the configured range).
• Only when summaryMemory is enabled, text following the /summary command is treated as a hard boundary: it locates the most recent message before the trigger that contains that text and summarizes only from there up to the current trigger; if the boundary is not found in the scanned history, botmux does not fall back to a wider range but hands the agent a "boundary not found" error together with an empty history (the memory write instruction still runs). When summaryMemory is off, text after /summary is only a focus hint for the summary and the history window still follows summaryRange.
• The memory file is written by the agent within its working directory. If the bot has sandbox enabled and summaryMemoryPath points outside the working directory (an absolute path, or a relative path that escapes via ../), add the file's existing parent directory to sandboxPaths.readWrite; the worker filters out paths that do not yet exist at spawn time, and a new memory file usually does not exist yet, so adding only the file path itself is dropped (unless the file is pre-created). Otherwise the write may be denied by the sandbox.

#Legacy content trigger config

#Voice

#Meeting listener roles and group placement

vcMeetingAgent.meetingConsumer.consumerProfiles defines reusable meeting-listener roles. responseMode controls whether automatic model output is authorized; listenerDelivery.placement independently controls where authorized output appears:

The Dashboard meeting-role editor includes a local built-in template library: Important information sync, Meeting minutes and action items, Meeting facilitator, Solution review and risk challenge, and Interview and requirement insights. “Use template” copies the selected template into a normal, fully editable profile; later template changes never overwrite user configuration. The catalog has stable template IDs, versions, and source metadata so a community source can use the same model later. This release makes no network request and uploads no usage data, so popularity rankings are intentionally unavailable.

• silent: automatic model output stays hidden.
• listener_thread: automatic output may be sent to the listener group and requires listener.output.request.
• placement auto (also the default when omitted): preserve legacy session routing.
• placement chat: send every update as a top-level group message.
• placement topic: use the first useful update as a stable topic root and thread later updates under it. Removing and re-enabling the profile starts a new topic.

Automatic listener_thread output uses an internal skip | publish control protocol. The agent decides whether the current meeting state warrants publication; botmux sends only the publish message body and never renders the control JSON in Lark. There is no semantic-fingerprint deduplication or debounce/interval setting: novelty, observation time, and publication timing remain the agent's responsibility under the profile prompt and full meeting context. Malformed envelopes fail closed. Explicit human IM replies keep their existing quote/thread routing and do not use this protocol.

Example generic “important meeting information sync” profile:

{
  "id": "important-sync",
  "agentAppId": "cli_your_agent_app_id",
  "label": "Important meeting information sync",
  "role": "important-information-sync",
  "instructions": "Continuously listen to the meeting. Publish only new information that materially matters to collaborators: confirmed decisions, status changes, explicit blockers or risks, and items people need to know or act on. When discussion has not formed a clear change, do not publish yet; decide whether to keep observing and when to publish from meeting semantics. Ignore discussion process, repetition, small talk, and unconfirmed speculation. Keep each update concise and include owner, deadline, scope, or impact when known. A correction to a previously stated time, owner, scope, status, or conclusion must be published as new information even when most surrounding details remain unchanged. Re-evaluate transcript revisions without repeating unchanged items.",
  "filter": { "activityTypes": ["transcript_received", "chat_received"] },
  "responseMode": "listener_thread",
  "listenerDelivery": { "placement": "topic" },
  "capabilities": ["listener.output.request", "meeting.read"]
}

Set agentAppId to the bot that executes the role. Add the profile id to defaultConsumerIds with defaultMode: "agents" to enable it by default, or select it manually from the in-meeting consumer card.

#Runtime state (auto-maintained, do not edit)

The following fields are written by botmux itself and persisted into bots.json alongside authorizations / switches. They are listed only for reference — do not edit them by hand:

Configuration precedence: the BOTS_CONFIG environment variable → ~/.botmux/bots.json. Run botmux restart after editing to take effect.