Agent Bot

Use local Codex, TraeX, and compatible ACP agents through Feishu.

Website | English | 简体中文

Agent Bot runs on your computer and connects a Feishu bot to your local coding agents. Send a message to start working; the bot updates a progress card while the agent runs and sends the final answer as Markdown.

• Use your existing local Codex or TraeX login from Feishu
• Create, continue, switch, fork, and stop tasks
• Reset the current conversation from any successfully completed progress card
• Collaborate with text, images, files, quoted messages, merged-forwarded chat records, group chats, and topics
• Queue follow-up Prompts or add instructions while a task is running
• Automatically retry temporary model-service failures
• Continue existing work after Agent Bot restarts
• Run through the local Console UI without Feishu

• Node.js 22 or later
• At least one supported App Server Agent: Codex or TraeX
• Codex 0.153.4 or later when using Codex (TraeX and ACP Agents have separate versions)
• A completed local login for the Agent you plan to use

Check the installed Agents and their login status:

codex --version
codex login status
traex --version
traex login status

You can continue once either Codex or TraeX is ready. agentbot init checks both and can help install or upgrade them.

# Install the stable version
npm install --global @keyou007/agent-bot
# Install the Alpha version to try the latest features
# npm install --global @keyou007/agent-bot@alpha
agentbot --version
agentbot --help

See the technical reference to install from source.

agentbot init

Initialization detects Codex and TraeX and reports their installed versions. Missing or outdated Agents are listed with the appropriate install or upgrade commands. Agent Bot saves its configuration to ~/.agent-bot/config.yaml.

Codex's minimum supported version is checked locally even when the npm registry is unavailable. An older Codex cannot be selected during fresh setup; existing Profiles using it must upgrade before initialization continues. The runtime also checks the actual App Server version at startup and reports an upgrade instruction instead of using legacy full-history fallbacks. Run codex update (or npm install -g @openai/codex@latest), then safely restart Agent Bot.

In an interactive terminal, initialization uses a guided flow for Agent selection, Lark bot creation, and permissions. After the ordinary one-click authorization is complete, the wizard asks how group messages should be handled. The final permission that requires manually publishing an app version appears only when receiving every group message is selected.

1. Create the bot. This creates a Feishu app with the standard basic messaging configuration and saves its App ID, App Secret, and authorizing user. This step cannot be skipped because Agent Bot cannot connect to Feishu without it. Permissions already provided during creation are not repeated below.

2. Add the remaining permission, event, and callback. This step adds only:

   Type	Permission, event, or callback	Purpose
   Permission	im:chat:delete	Let /dismiss dissolve a group created and owned by the bot. Without it, other Agent Bot features still work.
   Event	im.chat.updated_v1	Detect group renames and synchronize them to Agent task titles.
   Callback	card.action.trigger	Enable card button interactions.

3. Optionally add the all-group-message permission. This final step appears only after choosing to receive all group messages. The im:message.group_msg permission lets Agent Bot receive ordinary group messages that do not @ the bot, and Feishu requires it to be added manually in the Developer Console and published in an app version. Entering Y, reaching the timeout, or leaving the version unpublished does not fail initialization; group conversations simply remain mention-only. Mention-only mode never requests this permission.

After these steps, the ~/.agent-bot directory is initialized and Agent Bot starts immediately. Every successful agentbot init sends a private welcome card containing the Agent Bot logo. The first card introduces the main capabilities; after an upgrade it highlights the new version, while a same-version rerun confirms that the Profile was refreshed.

Agent Bot includes a keepalive mechanism that automatically reconnects after Agent Bot, Codex, or TraeX crashes.

Start the service:

# agentbot init starts the Server automatically, so manual startup is usually unnecessary.
agentbot server start

Check the service status:

agentbot server status

Stop the service:

agentbot server stop

Safely restart the service:

agentbot server restart

It waits for currently running Agent tasks to finish before restarting, allowing every task to complete normally. When an Agent invokes the CLI, the status card returns to its source task; from an ordinary terminal it goes to the configured user's private chat. Add --task <task> to override either destination. When triggered from a Feishu topic, both restart status and the post-restart startup card return to that topic.

The safe-restart card offers Cancel and ForceRestart. Clicking ForceRestart immediately starts the pending restart without waiting for tasks, final deliveries, or the quiet window, and may interrupt running tasks. If a prepared update is waiting, it applies that update and restarts immediately. Cancelled, superseded, or already-triggered plans cannot be forced again.

Each displayed running task also has a Stop action that interrupts only that task, including tasks in other conversations. The card refreshes automatically as tasks stop; the safe restart continues waiting for the remaining blockers.

To start Agent Bot automatically at user login:

agentbot server autostart enable
agentbot server autostart status
agentbot server autostart disable

Autostart is configured separately for each Profile. Disabling it does not stop the currently running Server.

The recommended way to update a global npm installation is:

agentbot update

Stable installations check the stable channel by default; Alpha installations stay on the Alpha channel. Use --stable, --alpha, or --version <version> to choose explicitly. When the service is running, Agent Bot sends a safe-restart card, waits for active tasks to finish, updates, and restores the service automatically. If no task is active, the update restarts the service immediately. Source checkouts and npm link installations are never modified by self-update.

On Windows, Agent Bot hides the internal npm and Node command windows used for update checks, installation, and validation; command output and errors remain captured.

While the Feishu service is running, automatic updates check only npm's stable latest once daily at a persisted random time between 10:00 and 17:00 in the server's local timezone. A newer version sends the configured owner one private card containing that version's release notes, a 60-second countdown, and Cancel this update. No cancellation means the package is downloaded and validated in the background, then installed and restarted only after active tasks, final-message deliveries, and the quiet inbound window are clear. Existing rollback protection applies. Each version is notified only once per Profile; cancelling skips that version even after restart. Interrupted countdowns restart at 60 seconds on the same card, without sending another reminder.

Set updates.enabled: false in the Profile configuration and safely restart to disable automatic checks. Without a configured private recipient, confirmed card delivery, or release notes, no automatic installation starts. Failed checks are retried on the next day's schedule; failed installations are not automatically retried for the same version. Automatic updates never install Alpha versions or downgrade, and the same npm-only installation protection applies. Manual agentbot update behavior is unchanged.

Send /update in Feishu to check the latest stable and Alpha releases together, read their release notes, and choose an Update button. Release introductions prefer Chinese for that exact version (including bundled translations for existing releases), falling back to the original notes when Chinese is unavailable. Only the configured bot owner can start installation; checking does not install anything. Older or already-installed versions have no update button. Preparation happens in the background, then installation waits for tasks and final replies to finish before a safe restart. The existing rollback protection applies. This manual command remains available when automatic checks are disabled; source checkouts and npm link installations can view releases but cannot update in place. If a choice expires or a download fails, send /update again.

To replace the global package manually, stop the running service first:

agentbot server stop
npm install --global @keyou007/agent-bot@latest
agentbot init # Update the Profile and start the Server

To uninstall, remove the startup registration and stop the service first:

agentbot server autostart disable
agentbot server stop
npm uninstall --global @keyou007/agent-bot

Uninstalling the npm package does not delete user data under ~/.agent-bot.

Multiple Profiles let you run several independent Agent Bot instances on the same device without interfering with one another.

Create a new Profile with:

# Select a new Profile directory and initialize a new bot
agentbot --profile ~/.agent-bot-rescue init
agentbot --profile ~/.agent-bot-rescue server start
agentbot --profile ~/.agent-bot-rescue server status
agentbot --profile ~/.agent-bot-rescue server autostart enable

Commands without --profile use the main Profile at ~/.agent-bot.

Each Profile stores its own config.yaml, .env, data/, and logs/ in the selected directory. Feishu credentials and local control endpoints are isolated as well.

To completely reconfigure the default Profile, stop its Server and run reset without --profile:

agentbot server stop # Stop the default Profile Server
agentbot init --reset # Reset the default Profile

Use --profile <directory> with both commands to reset another Profile.

Reset moves the current config.yaml, .env, data/, and logs/ into .reset-backups, then creates clean files and directories. Existing backups are retained permanently and are not overwritten or cleaned by later resets. The old remote Feishu app is not deleted.

Reset does not remove Codex or TraeX chat sessions. It only recreates the Feishu bot and clears Agent Bot's local data.

agentbot console

The Console UI does not require Feishu credentials. It does not share task state with a running Server unless --force is supplied.

agentbot task list
agentbot task current [--json]
agentbot task status [task]
agentbot task prompt [task] "<prompt>"
agentbot task new [task] [title] [--agent <standard-name>] [--dir <path> | --nodir]
agentbot task newgroup [task] [title] [--agent <standard-name>] [--dir <path> | --nodir]
agentbot task fork [task]
agentbot task forkgroup [task] [title]
agentbot task clone [task] [title] [--agent <standard-name>]
agentbot task clonegroup [task] [title] [--agent <standard-name>]
agentbot task queue [task] "<prompt>"
agentbot task model [task] [model]
agentbot task goal [task] [action-or-objective]
agentbot task turns [task]
agentbot task reset [task] <Turn ID>
agentbot task dir [task] [directory]
agentbot task file [task] <path>
agentbot task title [task] "<title>"
agentbot task stop [task]
agentbot task archive [task]
agentbot task dismiss [task] --yes

Inside an Agent started by Agent Bot, [task] defaults to the current task; use --task <task> to target another task explicitly. A regular terminal must supply a task. task current shows the automatically detected task details. A task reference can be a number from task list, a task ID, or an unambiguous task-ID prefix. Every Feishu task, fork, queue, Agent, Provider, model, thinking, permission, Goal, historical Turn, Reset, group mute, group dismissal, directory, file, shell, and restart operation has a CLI counterpart. Run agentbot --help for the complete list and options.

task newgroup creates a Feishu group and a new task. By default, it inherits the source task's Agent and execution settings. --agent <standard-name> selects another configured Agent; the source project shape is still inherited, while Provider, model, reasoning effort, and permission mode use the target Agent's saved defaults. --dir overrides the project directory and supports ~; --nodir forces a Projectless App Server task. Project and Projectless group names can be customized separately through feishu.groupNameFormat. task forkgroup forks from the source task's latest available completed turn without interrupting an active turn. Both commands require the Server to be running, invite the authorizing user saved in the Profile, leave the source conversation on its current task, and support --json.

task clone and task clonegroup (also available as /clone and /clonegroup, abbreviated /cg) transfer lightweight dialogue, even between different Agents. They export user Prompts and final answers in order through the latest completed Turn to a local text file, then automatically ask a fresh Agent to read it, acknowledge, and wait for the next request. No LLM summary, reasoning, tool calls/results, image payloads, or native session files are copied. Large files can be read in sections. App Server history uses summary pagination; ACP sources export only dialogue already saved by Agent Bot.

The target uses the conversation's default Agent unless --agent is supplied, even when that differs from the source Agent. Provider, model, and reasoning use the target Agent's saved defaults; permissions and project directory come from the source, with a fresh workspace for Projectless App Server tasks. clone switches the conversation only after task creation and import start succeed; clonegroup creates a new private group without switching the source conversation. Neither interrupts active source work or includes its unfinished Turn. In a topic without completed task history, the mapped source Turn is the cutoff. Both CLI commands support --json; group creation requires the Profile's authorized user. Files remain under context-transfers beside the configured SQLite file (normally ~/.agent-bot/data/context-transfers); retain them while cloned tasks need them. This transfers text context, not executable session state or local file changes.

Send a message beginning with / to run a command. Use /help in Feishu for the latest command list.

Slash commands accept unique prefixes: /mo, /mod, and /mode all open the /model settings card. Arguments follow the matched command's rules; ambiguous prefixes require more characters, and unknown commands are never sent to the Agent as Prompts.

Renaming a Feishu group updates its currently bound task title, even when you remove the generated prefixes or use a different format. Recognized configured names or matching Agent prefixes still supply just the task title; otherwise the complete new group name is used with normal title whitespace and length normalization. This does not switch the task's Agent, rename topic or historical tasks, or change the naming format for new groups. Empty names and groups without an open current task are ignored.

Private chats, group timelines, and topics keep separate current tasks. A new topic remains unbound while you use commands such as /help, /status, or /sessions; those commands do not create a hidden fork. Its first ordinary message forks from the mapped source turn, or starts a fresh task when no source turn can be identified. /new starts a fresh topic task, while /sessions can bind an existing task. Commands that require a current task explain how to bind one instead of operating on the parent conversation. Ordinary messages sent while a task is running add instructions to that turn; use /queue when the message should run afterward as a separate turn.

/release sends a card for releasing the shared App Server used by the current task's Agent so its tasks can be opened in Codex Desktop. The card lists blocking task names and keeps them updated. Agent Bot never releases automatically: click Release when idle, or Release Now to interrupt active work and clear queued Prompts. Cancel cancels the pending release. Releasing does not archive or delete task history, but it affects every task loaded by that shared App Server.

Topic replies check whether the root message is already in the task's history using lightweight Turn links, without loading the full history before sending the thinking card. Legacy parent links are repaired only when needed.

In a group, /mute and /mute on make the bot process only messages that mention it. Mention the bot and send /mute off to restore automatic responses. The setting applies to every topic in that group.

Only groups explicitly enabled with /mute or /mute on supplement ordinary @-mention Prompts with recent human text and images. Topic requests read only that topic; ordinary group requests exclude topic messages. Reads are limited to two reverse-chronological pages of 30 messages, selecting up to 20 messages before the triggering mention, 16,000 text characters (2,000 per message), and six additional images, newest first. Bot messages, deleted messages, and later messages are excluded; non-image attachments and forwarded bundles are not expanded automatically. The original question remains the card Prompt. Included context is marked as reference data, not authorization. Successful submissions persist a bounded deduplication ledger scoped to the task, remote branch, and conversation. Scanning stops at the first message already submitted to that Agent conversation (either a direct Prompt or previously injected context): that message and all older messages are excluded, and no earlier page is requested. Queued-but-not-submitted context is deduplicated without becoming a stop boundary. /mute off, private chats, unmentioned messages, and slash/Shell commands do not trigger this read. Existing topic-root and explicit-reply handling remains unchanged. Reading requires the bot to have the relevant Feishu history/group-message/resource permissions; denied reads or image-download failures are reported without submitting an incomplete Prompt. This feature does not enable permissions automatically.

/new and /newgroup use the conversation's default Agent unless --agent <name> selects another configured Agent for this task only; the source conversation's default is unchanged. For example, /new Fix tests --agent codex or /newgroup Review --agent traex --dir ~/dev/project. They inherit the current project; execution settings are inherited only when the selected Agent matches the current task's Agent, otherwise Provider, model, reasoning, and permission mode use the target Agent's saved defaults. Use --dir to choose another directory or --nodir to start without a project directory; --nodir requires the selected Agent to be App Server, and ~ represents your home directory.

/file accepts relative paths, absolute paths, and paths beginning with ~; relative paths resolve from the current task directory.

/fork and /forkgroup branch from completed work without interrupting a running turn. /sessions manages tasks across projects and Providers in pages of up to 10 tasks; switching Provider does not hide a task from the list or search. Use each project menu for New and NewGroup. Each task’s SwitchGroup action creates a new group bound to that same task, preserving its history, title, and execution settings without creating or forking an Agent task. The original conversation stays unchanged. An Agent Bot Turn already in progress keeps replying to its original conversation; new messages from the new group queue until it finishes. Tasks running in an external client cannot be switched until they finish. Expanding a task directly shows the first 50 characters of its latest user Prompt, its update time, and task-specific actions. Running tasks also show a direct Stop button, including the current task and tasks running in other conversations or external clients. It sends the normal Agent interrupt without switching tasks or killing processes. The list refresh preserves search and pagination and keeps Stop available until the Agent reports the task idle; Archive is available only when idle. Use Turns to view that task’s history without switching tasks, including tasks not yet bound to Agent Bot; non-current tasks are read-only until you switch to them. /turns restores conversation context without reverting local files.

/turn and /turns are equivalent. Without an argument they open the history card; /turn 3 uses its one-based, newest-first index (including a running Turn at the top), and /turn <Turn ID> selects a Turn in the current task's history. Viewing details does not Reset, resume, stop, or switch tasks. Saved IDs are read directly; missing history is located through summary pages, stopping at the requested index or the page containing the ID. Fork lookups stay within inherited history. Details show the saved Prompt, status, timing, activities, and results, with Preview when configured; summary-only external Turns cannot show tool activity that Agent Bot never recorded.

Fork creation records the source task and branch Turn without synchronizing the local history list. Agent-side conversation inheritance is unchanged. Opening /turns reuses local history first and requests only the Turn-summary pages needed for the selected card page, bounded by the branch Turn. Older history is loaded only when needed for later pages; agentbot task turns loads the first page if necessary and returns the available local records. Failed history reads remain retryable, and Agents without summary pagination do not trigger a full-history fallback.

Ordinary tasks also load history as summary pages on demand. Task lists read only the latest Turn summary; metadata lookups do not request Turns. Status and recovery read at most the latest Turn's complete result and reuse the reconciliation result when available. Local Turn cards read the graph's IDs and timestamps, then only the visible page's Prompt summaries, without loading historical tool outputs. Codex activity detection caches unchanged rollout files and incrementally scans appended content.

Turn history uses fixed-width graph lanes with separate sequence numbers, keeping nodes and branch connectors aligned without adding blank continuation rows.

Enter a message beginning with ! directly in the Feishu chat box to run a local command in the current task directory.

For example, ! ls lists files in the current directory, and ! git status shows the state of the current Git repository. Local commands run in independent background processes without a time limit, so they do not block other messages or commands in the current conversation. The same output card refreshes while a command runs, preserves the observed order of normal and diagnostic output, and includes a Cancel action. Agent Bot resumes monitoring commands that are still running after a Worker restart. Long output keeps its beginning and end while the middle is truncated.

Agent Bot keeps user-owned files outside the repository:

Set AGENT_BOT_HOME to use another user-data directory. See config.example.yaml for configuration examples.

Local non-image files and directories referenced in Agent replies become signed, read-only viewer links for source code, Markdown, logs, PDFs, common media files, or downward directory browsing. By default, links open only on the computer running Agent Bot. Setting fileViewer.host to 0.0.0.0 automatically selects a LAN address in wired, Wi-Fi, other physical, then VPN order. Use fileViewer.publicBaseUrl to override that address for a domain, HTTPS reverse proxy, or port mapping.

Relative file links in Feishu answers and thinking cards, such as outputs/report.md, resolve from the Turn’s saved project directory before conversion to signed viewer URLs. Windows and POSIX paths, encoded spaces, and line references are supported. Unavailable resolved files fall back to path text; web links, images, and code remain unchanged.

/status cards also include Preview beside Refresh and Stop/Switch. It opens the active Turn, or the latest Turn when idle, and updates its target when you refresh the card. For external tasks not yet recorded by Agent Bot, opening Preview loads the selected Turn from the Agent and caches its full execution details. Read failures can be retried by refreshing the page. The button is hidden if there is no Turn, no supported history reader, or the file viewer is unavailable. Viewing another task’s status does not switch or take over that task.

Progress cards include a Preview button that opens the saved Turn timeline in a compact, mobile-friendly browser view. Reasoning panels use the content title as their collapsed header and show the text directly on expansion. Tool blocks have a single collapse level and start collapsed with a meaningful one-line command summary, a compact duration (58s or 2:32), and completion status. Expanding a block shows the full command prefixed by $, followed directly by its results, images, and changed files. Identical output/error logs appear once. Running Turns update live by patching changed sections in place, preserving expanded or collapsed steps, scroll positions, and unchanged image elements instead of reloading them. Token and other metadata updates do not replace the timeline. Collapsed tool steps and the file-change summary initially contain only their headers; commands, logs, images, and file lists are fetched on expansion. Reopening reuses loaded content, and live updates refresh only expanded details whose content changed. Failed loads offer Retry. Finished Turns do not open a live SSE connection. The waiting-for-progress placeholder is hidden once a response or other visible progress is available, and is never shown for finished Turns. Click a file in the file changes or tool file list to preview its current contents in a new tab; deleted or unavailable files remain plain text. Turn previews use the same signed viewer address and access rules as local file links. Beside Final answer, download and copy icons export the original Markdown (including formatting, code blocks, and unchanged link targets), not the rendered HTML. Download saves a UTF-8 .md file; Copy uses the clipboard with a fallback for HTTP/LAN previews and shows success or failure feedback. Both work on completed pages and when the final answer arrives live.

Opening /turn <ID or index> or Preview for an imported summary loads that Turn's execution details from its original Agent session and caches the result. Only summary pages and the selected Turn's full record are requested, never the entire full history; source tasks are not resumed or interrupted. Read failures show their reason separately from the Turn's execution status; reopen the details or refresh Preview to retry. Existing detailed snapshots remain unchanged, and unavailable historical timing or token data is not estimated.

Turn Preview highlights fenced code blocks in common languages such as JavaScript/TypeScript, Python, Shell/PowerShell, JSON/YAML, SQL, HTML/CSS, Go, Rust, Java, and C/C++. Colors follow the system light/dark theme. Specify the language after the opening fence; unknown, unspecified, or oversized blocks stay as complete plain text. Inline code and tool logs keep their existing appearance.

Turn Preview retains complete recorded execution content without repeatedly saving the whole Turn to the database. Live previews update incrementally; collapsed tools load their full details when opened. Back up the entire Profile data directory to keep execution records as well as task metadata. Existing saved history remains readable.

Mermaid diagrams in Turn Preview and Markdown file previews have Preview / Source controls and default to Preview. Use a mermaid fenced code block with flowchart or graph syntax (flowchart fences are also accepted). Your mode selection survives live updates; invalid or incomplete diagrams fall back to source. Rendering runs locally in your browser, without sending diagram content to an external service. Diagrams scale down to the available width by default without enlarging small diagrams. On phones, the preview is capped at roughly half the screen height; scroll vertically for long flows. Use Actual size / Fit to inspect details or return to the fitted view. Live updates preserve this choice.

The compact Turn Preview header uses dot-separated values, keeps the duration label, and abbreviates token counts with K, M, and B units. It wraps to fit narrow screens. Prompt, Commentary, and result text use a regular weight and a slightly larger font than tool calls. Tool commands and outputs preserve line breaks and indentation; long lines scroll horizontally within the tool block without wrapping. Commands and results share one scroll area capped at 30 lines in height. The page reserves space for classic vertical scrollbars so expanding or collapsing tools does not shift the header or timeline horizontally. Thin, subtle scrollbars have no arrow buttons. On desktop they appear on hover or keyboard focus; on touch devices they are hidden while gesture scrolling remains available.

Tool blocks have a subtle outline. Horizontal separators appear after the Prompt, before the file-change summary, and before the answer, with no separator after the final answer. The file-change summary starts collapsed, shows the file count, and preserves your expanded state during live updates. Both file lists show project files as relative paths and files outside the project as absolute paths.

When an App Server reports only Read or Grep as the command, available action metadata supplies the file path or search query and scope in both the summary and expanded command. Complete commands remain unchanged, and missing targets are not guessed; previously saved previews are not backfilled.

Tool titles start with the same status icons as the thinking card: an hourglass while running, a check mark on success, or a cross on failure. Running blocks have an accent border. Header summaries omit shell line-continuation markers while preserving file paths and the full expanded command. Durations remain hidden at zero seconds. The expanded footer shows the execution status, start time, duration, and result character count outside the scroll area; running durations update live in both the header and footer.

Command approval cards use a short heading and show the reason first, with the command in a collapsed panel instead of repeating it as a long bold title. The summary omits recognized shell wrappers, but the expanded command retains them. Oversized commands and reasons show an explicit truncation notice; check the complete original command in Turn Preview before authorizing. The four approval actions and their permission scope are unchanged. Preview remains read-only and preserves command expansion and scroll position during live updates.

TraeX plan-mode confirmations appear on the existing progress card as Waiting for approval, with the plan text and Approve Plan (or Enter Plan Mode), Reject, and Cancel Request actions. They require an explicit decision even with automatic permissions; cancelling the request is not the same as stopping the task. Turn Preview shows the plan and pending confirmation but remains read-only: respond in Feishu. Waiting turns remain active and continue to block safe restart until they finish or are explicitly stopped. Notifications missed by an older running version cannot be recovered automatically by this adaptation.

Local images in Turn Preview Prompts, Commentary, and results load through signed file URLs, including live updates. Relative image paths resolve from the task's project directory.

Attached images from initial and appended user messages are saved with the Turn snapshot and displayed through signed file URLs, including SSE updates and reopening after a restart. Missing cached files show an unavailable placeholder. Older snapshots that never recorded attachment paths cannot restore those images automatically.

The Turn Preview header shows Processing during both normal processing and tool execution; tool details and other status labels are unchanged.

The header hides compaction statistics and shows Context in tokens immediately before Model calls (before the tool count when model calls are unavailable) using the Agent's latest reported context size for that Turn, not cumulative token consumption or the model's capacity. It updates in place, including decreases after compaction when reported; hover for the exact count. Historical Turns show their saved value. Missing or invalid values stay hidden, without estimating from other token counts or fetching history.

Turn Preview shows the Provider before the model recorded for each Turn, without a visible Provider prefix. Changing settings affects subsequent Turns, not the running Turn or earlier Turns. Older snapshots without a recorded Provider leave it hidden rather than using the task's current settings.

The header also shows Model calls for the Turn, counting effective token-usage updates: the first positive usage report counts once, and subsequent cumulative increases count once each. Total tokens including cache take precedence, with non-cached usage as a fallback. Duplicate, regressing, invalid, and context-only updates do not add calls. Counts update in place and persist across restarts; Feishu thinking cards are unchanged. Saved Preview events can reconstruct the count during normal replay, but incomplete old snapshots or Agents without usage reports leave it hidden; no additional Agent history or rollout scan is performed.

When reported by the Agent, Turn Preview shows this Turn's total tokens (input plus output, including cached input) alongside the existing non-cached count. The separate cache-hit token count is hidden; underlying token accounting is unchanged. Values update live, use compact units, and show exact counts on hover. Duplicate usage notifications are not counted twice. Missing breakdowns and older snapshots are not estimated or backfilled from task history; Feishu card token counts keep their existing calculation.

Markdown previews keep table cells at their content width. Wide tables scroll horizontally within the preview instead of squeezing columns on narrow screens, and live updates preserve each table's horizontal scroll position.

Local links in rendered Markdown open signed viewer pages for the referenced files or directories. Relative paths resolve from the Markdown file's directory; absolute paths, file:// URLs, and line references are supported, and local images load through the same read-only service. Web links and the original code view are unchanged. Sharing a Markdown viewer link also gives its readers access to the local paths referenced in that document, so only share trusted documents.

HTML files (.html and .htm) open in preview mode with a code toggle, line anchors, and live updates. Self-contained HTML can use inline styles, inline scripts, and embedded media inside an isolated frame. External resources, relative local assets, network requests, forms, and access to the outer viewer are not enabled. The rendered document is complete; only the code view is limited to the first 2 MiB.

CSV files (.csv, case-insensitive) open as read-only tables with row numbers, column letters, sticky labels, and horizontal/vertical scrolling. The first row remains data, not an inferred header. Standard comma-separated fields support quoted commas, escaped quotes, embedded newlines, empty cells, and UTF-8/UTF-16 BOM or GB18030 text decoding; numeric strings and formulas remain plain text. Preview reads at most the first 2 MiB and displays up to 500 records, 50 columns, and 4,000 characters per cell, with explicit truncation or malformed-quote notices. Incomplete records at the byte boundary are omitted. The code view displays up to 2,000 physical lines; raw/download links preserve the entire original file. Live updates retain the selected view and table scroll position.

Provider, model, reasoning effort, and permission choices apply to the current task and are also saved under that Agent's defaults. If an older configuration has no defaults section for that Agent, it is created automatically on the first change. Future tasks that have no same-Agent settings to inherit start with those saved defaults; each configured Agent keeps its own values.

For App Server tasks, permission changes apply both approval and sandbox policies on the next Turn: auto uses no sandbox and no approval prompts; confirm uses the workspace-write sandbox and on-request approval. Choose the mode in /permissions, or use agentbot task permissions auto|confirm. Switching requires no Agent restart, fork, or new task and does not change already-running tool processes or steering requests. Workspace writable roots, network access, and temporary-directory exclusions retain the Agent's configured values.

The execution settings card ends with a one-sentence Markdown blockquote for the selected tab's scope and timing. Agent selection changes only the default for new tasks in that conversation, without migrating the current task. Model, reasoning, and permission changes apply from the next turn. Agent and Provider options show their identifiers without duplicate display names, while retaining current/default indicators. /provider opens this card even when only one Provider is available, keeping the Model, Thinking, and Permission tabs accessible.

Provider changes require an idle task. Wait for an active turn to finish, or stop it before switching. For a custom Provider, Agent Bot uses its OpenAI-compatible /models endpoint when available and shows only that Provider's models. A switch keeps the previous model when the target supports it, otherwise selects the target's default model or its first returned model. Providers without a model-list endpoint remain usable: Agent Bot keeps the current or configured model as the single fallback candidate and lets Codex apply it. Agent Bot unloads only the selected idle thread, resumes it with the resolved Provider and model, and verifies both before saving settings or reporting success. A known fresh, empty thread may be replaced while keeping its task identity, title, and directory; forked or resumed tasks are not treated as empty merely because they have no new messages. If a switch fails, the previous settings are retained and remote recovery is attempted. If recovery also fails, further turns are blocked until a Provider switch succeeds.

For TraeX's built-in trae Provider, Agent Bot uses the complete native model/list catalog, including model names and reasoning options, without requiring a custom Provider base_url. Other custom Providers keep their own model discovery and fallback behavior.

If Provider model discovery fails, settings cards retain the fallback model but show the failure and warn that service availability is unconfirmed. A successful settings change verifies configuration, not a live inference request. App Server runtime errors and native retry notices show the message and any additionalDetails in the existing progress card and Preview, including upstream error codes and retry delays when supplied. Error text is displayed literally, duplicate details are omitted, and long reasons remain available in Preview and activity history. Missing details are not guessed, and previously saved snapshots are not backfilled. Retrying does not create another card or end the turn; the final turn notification still determines success, failure, or cancellation.

Some Responses-compatible Providers omit assistant message phases. Their text stays in the progress timeline instead of being concatenated into a premature final answer. On successful completion, only the last unphased message not followed by a tool start becomes the final answer; explicit commentary and final_answer phases take precedence. Cards and Preview share this classification. Previously saved snapshots are not automatically rewritten.

feishu.groupNameFormat defines separate name templates for new Project and Projectless groups, with variables for the operating system, Agent, project, task name, and date. See the technical reference for the complete format.

If Codex ignores the requested Provider or model when resuming an existing task, Agent Bot retries on a new Codex thread forked through the latest completed Turn. The local task, title, and directory remain unchanged; later failed or interrupted Turns remain only in the original thread. The replacement is adopted only after the settings are verified.

Agent processes inherit ordinary parent-process variables and their explicit agents.<name>.env settings. Before starting an Agent, Agent Bot removes inherited FEISHU_* credentials and internal AGENT_BOT_* state, then provides only namespaced, non-secret Profile and Lark identity context. FEISHU_APP_SECRET is never forwarded to an Agent process.

At startup, Agent Bot also reads each Codex Agent's CODEX_HOME/.env (default: ~/.codex/.env) for Provider model discovery and the Codex process. You do not need to duplicate those keys in Agent Bot's .env. Existing environment values and explicit Agent settings take precedence. Safely restart Agent Bot after editing the file.

By default, feishu.respondToOwnerOnly: true accepts only messages and card actions from the bot owner identified by feishu.userOpenId; other users are ignored before any processing reaction is added. Set it to false to allow collaborators. When enabled without an owner Open ID, all Feishu user input is ignored until the owner is configured.

Agent Bot responds to ordinary owner messages in groups containing the bot. Set feishu.respondToAllGroupMessages to false to additionally require the owner to @ the bot in groups; private chats are unchanged. Initialization requests the manually published all-group-message permission only when this option is enabled. After changing it from false to true, rerun agentbot init and complete the final permission step.

Thinking cards use the grouped layout by default: auxiliary Commentary and user steering remain visible, while each execution group shows only its latest native reasoning and expands to reveal complete tool commands and results. Common PowerShell, zsh, bash, and sh launcher prefixes are omitted from the displayed commands. A failed tool remains marked inside its own tool panel but does not turn the complete execution group red or give the group a failure icon. Execution groups start collapsed and keep stable component identities so a group manually opened in Feishu stays open across card updates. When Codex compacts its context, the card shows the live compaction state as a progress activity, including elapsed time, before/after context token counts, executed Turn count, and rollout disk usage when available. On long turns, pagination measures the fully rendered card content instead of using fixed message or tool counts. Set feishu.thinkingCardLayout to timeline to temporarily restore the original layout.

Whitespace-only Commentary does not use a pinned message slot. Adjacent omission markers generated by the card are shown once, without removing literal message text or changing saved history.

Turn Preview shows each saved reasoning item in a collapsed panel. A leading Markdown heading or standalone bold title appears directly in the header; expanding shows the remaining summary and content without extra Summary/Content labels or a repeated title. Items without an explicit title keep the Reasoning fallback and all original text. Collapsed panels load their full Markdown on expansion and retain expansion during live updates. Reasoning content and authoritative completed items are stored separately from card activities; this does not change thinking-card titles, grouping, or final replies. Existing saved summaries remain viewable, but previously unrecorded content is not backfilled from Agent history.

Quoted cards and cards inside merged forwards include their available original text and images in the Agent's context.

File-change summaries display paths as plain text, preserving Windows separators and literal underscores (including \__init__.py) instead of interpreting them as Markdown formatting.

After a crash, an unfinished Codex rollout alone no longer means the task is running: unloaded threads also require a live writer process. Agent Bot confirms session resume before creating a new running card. Writer conflicts stop automatic recovery with an occupancy card; other unconfirmed recovery failures are retried every five seconds for a one-minute window, then marked interrupted with a notification. No external process is closed automatically. Already-confirmed live turns remain monitored, including during temporary connection outages, and are not subject to this recovery timeout.

• The bot does not respond: run agentbot server status and check today's ~/.agent-bot/logs/agent-bot.YYYY-MM-DD.log
• The Worker restarted after a Node crash: check ~/.agent-bot/data/last-crash.json, that day's ~/.agent-bot/logs/worker.stderr.YYYY-MM-DD.log, and ~/.agent-bot/data/crash-reports/
• Feishu permissions are incomplete: rerun agentbot init and follow the displayed authorization steps
• An Agent cannot start: run codex login status or traex login status as the same operating-system user that runs Agent Bot, then rerun agentbot init to check its version
• You only need local testing: run agentbot init --skip-feishu, then run agentbot console
• A safe restart keeps waiting: inspect active tasks with agentbot task list --status running

• Technical Reference: configuration, permissions, routing, persistence, recovery, and runtime behavior
• Example Configuration
• Changelog
• Agent Development Guide