Inside Clawdbot: How Its Agent, Tool Calls, and Browser Engine Operate

What is Clawdbot?

Clawdbot is a TypeScript CLI application that runs as a local process and exposes a gateway server to handle channel connections (Telegram, WhatsApp, Slack, etc.), call LLM APIs, execute local tools, and control the computer.

Runs on your machine as a process with a Gateway Server that handles all channel connections. Calls LLM APIs (Anthropic, OpenAI, local models, etc.). Executes tools locally. Controls the computer according to your instructions.

Core Architecture

1. Channel Adapter

The adapter receives your message, normalises it, extracts attachments, and routes it to the appropriate channel‑specific handler.

2. Gateway Server

The gateway server acts as a task/session coordinator, receiving messages and dispatching them to the correct session. It supports concurrent requests by using a lane‑based command queue: each session has its own lane, while low‑risk parallel tasks (e.g., cron jobs) run in a parallel lane. This design favours explicit serialisation over chaotic async/await usage, reducing race conditions and debugging complexity.

Default serial, explicit parallel

3. Agent Runner

The Agent Runner decides which model to use, selects an API key (marking a key as “cool‑down” if it fails), and falls back to a secondary model when the primary fails. It dynamically assembles a System Prompt that incorporates available tools, skills, memory, and session history from a .jsonl file, then passes the prompt to a Context Window Guard that ensures sufficient token space, compressing the session or gracefully erroring when the window is near capacity.

4. LLM API Call

LLM calls support streaming responses and abstract over multiple providers. When the model supports it, an Extended Thinking mode can be requested.

5. Agentic Loop

If the LLM returns a tool call, Clawdbot executes the tool locally, appends the result to the conversation, and repeats until the LLM produces a final text response or a maximum of about 20 iterations is reached.

6. Response Path

The final response is sent back through the originating channel. Each interaction is persisted in a .jsonl file where every line is a JSON object containing the user message, tool call, execution result, and model response—Clawdbot’s session‑based memory.

Memory System

Clawdbot stores memory in two ways:

A JSONL session transcript file (as described above).

Markdown memory files under MEMORY.md or the memory/ directory.

Search combines vector search (implemented with SQLite ) and keyword matching (via FTS5 , a SQLite extension). The embedding provider is configurable. A file‑watcher triggers Smart Syncing whenever a memory file changes, and agents write these markdown files using the standard “write file” tool—there is no dedicated “memory write API”.

The memory is simple and “explainable”: there is no memory merging or periodic compression, and old and new memories retain equal weight, meaning there is effectively no “forgetting curve”.

Computer Use (The Moat)

Clawdbot grants the agent high‑level computer access (user‑responsibility assumed). It uses an exec tool to run shell commands in three possible environments:

Sandbox : default Docker container.

Host : directly on the host machine.

Remote Device : on a remote machine.

Additional tools include:

File System Tool : read, write, edit files.

Browser Tool : built on Playwright, uses “semantic snapshots”.

Process Tool : manage long‑running background commands, terminate processes, etc.

Security (Or Is It?)

Clawdbot implements an allowlist stored in ~/.clawdbot/exec-approvals.json. Commands on the list are pre‑approved (e.g., jq, grep, cut, sort, uniq, head, tail, tr, wc). Potentially dangerous shell constructs—command substitution, redirection, chained ||, subshells—are blocked by default.

// ~/.clawdbot/exec-approvals.json
{
  "agents": {
    "main": {
      "allowlist": [
        {"pattern": "/usr/bin/npm", "lastUsedAt": 1706644800},
        {"pattern": "/opt/homebrew/bin/git", "lastUsedAt": 1706644900}
      ]
    }
  }
}

The core security philosophy mirrors Claude Code: grant the agent as much autonomy as the user permits while keeping a guardrail.

Browser: Semantic Snapshots

The browser tool does not rely on screenshots; instead it captures a semantic snapshot —a text‑based representation of the page’s Accessibility Tree/ARIA structure. Example snapshot:

- button "Sign In" [ref=1]
- textbox "Email" [ref=2]
- textbox "Password" [ref=3]
- link "Forgot password?" [ref=4]
- heading "Welcome back"
- list
  - listitem "Dashboard"
  - listitem "Settings"

Advantages of semantic snapshots:

Size : screenshots can be ~5 MB, snapshots are typically <5 KB.

Cost : token overhead is a fraction of image processing cost.

Accuracy : operating on text nodes yields higher success than pixel‑based coordinate targeting.

Speed : parsing plain text is far faster than computer‑vision image analysis.

Original source: https://x.com/Hesamation/status/2017038553058857413

References

https://x.com/Hesamation/status/2017038553058857413

https://deepwiki.com/openclaw/openclaw

https://www.mmntm.net/articles/building-clawdbot