Foundations
Why This Dashboard Matters
OpenClaw is easier to understand when each dashboard menu is treated as an architectural primitive.
The key mistake is to think:
“Connection, Sessions, Skills, Channels, Instances, Cron are just application settings.”
They are not. They correspond to different layers of an agent system — a full request travels from the person, through a channel and the Gateway, out to an agent instance and its runtime, and from there into the model, skills, memory, tools, nodes, MCP and APIs, while sessions hold continuity and cron/automation supplies the trigger.
One-line summary
The Core OpenClaw Architecture
OpenClaw describes itself as a multi-channel Gateway for AI agents. The Gateway is a long-lived process that owns messaging surfaces and provides the control plane to clients, nodes, agents, sessions, and automation.
2.1 Gateway
The Gateway is the central routing/control process. It is not the model, and it is not the agent itself.
Typical responsibilities:
- maintain connections;
- route inbound messages;
- maintain sessions;
- route work to configured agents;
- manage nodes;
- coordinate channel adapters;
- expose control-plane interfaces;
- run automation/scheduling infrastructure.
In a local installation the Gateway may listen on a local WebSocket endpoint such as:
ws://localhost:18789
The address is where clients reach it. The Gateway is the process/service listening there.
Connection Layer
Connection
The Connection page answers:
“What is connected to this Gateway, and what role does each connected component play?”
The most important distinction is between:
3.1 Operator
An Operator is a control-plane client.
Think:
“Who is allowed to operate/manage the agent system?”
An operator can potentially:
- send commands;
- inspect sessions;
- manage configurations;
- approve actions;
- control Gateway behavior.
Depending on the system, operator authority may be scoped granularly.
3.2 Node
A Node is an execution environment/device that offers capabilities to the agent system.
Think:
“What can this device lend to the agent?”
Examples:
A Node is not a Skill. A useful distinction:
Example
Suppose the model determines that it needs to inspect the current screen:
The model does not physically take the screenshot. The Node does.
3.3 Nodes Can Be Added or Removed
Nodes are not permanently fixed to the Gateway. One Gateway can theoretically have:
Each environment may expose different capabilities. For example:
| Environment | Typical capabilities |
|---|---|
| Phone | camera, microphone, location |
| Windows PC | screen, browser, filesystem, native applications |
| Linux Server | shell, services, containers, files, databases |
Permissions: Capability Is Not Authority
One of the most important architectural lessons in OpenClaw is:
A device may technically be able to do something while the agent is still restricted from doing it.
4.1 Capability Toggles
Examples:
| Capability | State |
|---|---|
| Browser Control | ON / OFF |
| Camera | ON / OFF |
| Canvas | ON / OFF |
| Screen Capture | ON / OFF |
| Location | ON / OFF |
| Text-to-Speech | ON / OFF |
| Speech-to-Text | ON / OFF |
| System Access | ON / OFF |
These toggles answer:
“Does this Node expose this category of capability?”
They do not necessarily authorize every action inside that category.
Exec Policy and Executable Allowlist
When local command execution is available, an additional policy layer becomes necessary.
5.1 Executable-Path Allowlist
An executable-path allowlist is a list of specific executables that have earned enough trust to run according to the configured policy without starting approval from zero each time.
Example:
C:\Windows\System32\hostname.exe C:\Tools\generate-report.exe C:\Tools\sync-data.exe
This is fundamentally different from a Node capability toggle.
Practical flow
If:
Default Action = Ask Executable Allowlist = Empty
then:
5.2 Narrow Executables vs General-Purpose Executors
Not all executable permissions carry equal risk.
Relatively narrow
- hostname.exe
- whoami.exe
- purpose-built report-generator.exe
Much more powerful
- cmd.exe
- powershell.exe
- python.exe
- bash
- wsl.exe
Why? Because an interpreter or shell can execute arbitrary additional logic. Therefore:
A single python.exe permission may represent more authority than ten narrow diagnostic utilities.
Node Allowlist vs Executable Allowlist
These should not be confused.
Node Allowlist
- Controls which commands/capability surfaces the Gateway may send toward connected nodes.
Executable Allowlist
- Controls which specific native executables may run on the node according to the execution policy.
Conceptually, a request passes through several independent gates before it becomes a real action:
Windows Privacy Is Another Gate
Operating-system permission remains below OpenClaw.
For example:
OpenClaw allows microphone
+
Node microphone capability ON
+
Windows blocks microphone access
=
No microphone access
A useful permission stack:
Local Deterministic Operations
Agent systems should not use an LLM for work that deterministic software can execute exactly.
A healthy split:
Examples of local deterministic work:
- calculations;
- file transformations;
- database queries;
- data validation;
- indicator computation;
- report generation;
- data normalization;
- deterministic business rules.
Interfaces — CLI, API, MCP
Executable, CLI, API, and MCP
These are related but different interface concepts.
9.1 Executable
A program that the operating system can run. Example:
C:\Tools\calc_margin.exe
9.2 CLI — Command Line Interface
A CLI is a way of controlling software through command-line commands. Examples:
git status openclaw models list python report.py --month 8
CLI is especially useful for:
- local operations;
- developers/operators;
- quick diagnostics;
- scripts;
- background deterministic actions.
CLI = operational command interface.
9.3 Python Script
A Python script is usually a short-lived process:
Example:
python calculate_margin.py input.json
Good for: batch operations; transformations; one-shot calculations; utilities.
9.4 Python Service
A Python service stays running and waits for requests. Example:
A service is useful when: functionality is called repeatedly; there are many related functions; persistent DB connections matter; concurrency matters; authentication is required; a stable API contract is useful.
9.5 API
An API defines how one application/service communicates with another. Modern APIs frequently use HTTP/HTTPS and JSON.
An API commonly defines: endpoint; method; authentication; request schema; response schema; errors; rate limits; versioning.
POST /calculate-margin
Authorization: Bearer <TOKEN>
Content-Type: application/json
{
"revenue": 1000000,
"cost": 700000
}
→ { "gross_margin": 0.30 }API = service/application contract.
Why JSON Is Everywhere
JSON is not a protocol. It is a structured data format.
Typical combination:
JSON is popular because it is: compact; human-readable; easily parsed; naturally maps to programming-language objects; schema-friendly; highly compatible with modern web and agent tooling.
{
"decision_id": "D001",
"status": "REVIEW",
"risk_flags": [],
"next_action": "HUMAN_APPROVAL"
}
The same structure can move across:
MCP — Agent Interoperability
MCP should be understood as an agent-facing interoperability protocol. It allows capabilities to be exposed as structured tools that compatible agent environments can discover and call.
…which are then reached by an agent runtime / MCP client, and finally the model:
An MCP server may simply adapt an existing system:
API vs MCP
A useful practical distinction:
MCP can sit over an existing API:
Sessions, Context & Memory
Sessions
The OpenClaw Sessions page represents continuity containers.
A Session is not: the model; the agent; memory itself.
A Session answers:
“Which interaction/work thread should remain continuous?”
A session may contain: conversation history; tool calls; observations; task metadata; current state; compaction information.
Session vs History vs Context vs State vs Memory
These are frequently confused.
Information can exist in storage or memory without being present in the current model context.
Compaction
Long sessions grow. Sending the entire raw transcript forever would eventually become: expensive; slow; larger than the model context window.
Therefore systems may compact older session material:
Memory
Memory answers:
“What information should survive beyond the immediate context or session?”
A good distinction:
Memory may include: stable user preferences; durable decisions; important learned facts; recurring operating information.
Memory vs RAG
Memory and RAG may use similar retrieval technology, but their semantics differ.
Memory
- Experiential/persistent information.
- “What did this agent/user/system learn or decide previously?”
RAG
- Retrieval of authoritative/canonical knowledge.
- “Which source-of-truth knowledge is relevant to this task?”
Examples suitable for RAG: official methodology; SOPs; policy manuals; validated research; contracts; technical documentation; canonical internal playbooks.
Architecture
Critical Rules Should Not Depend on RAG
If a rule is short, critical, and must never be missed, do not rely only on probabilistic retrieval.
Never execute a payment without human approval.
Better architecture:
Skills & Extensibility
Skills
The Skills page is a library of procedural knowledge. OpenClaw skills are instruction packs, typically centered on a SKILL.md file.
A Skill answers:
“How and when should the agent use its capabilities?”
It is not necessarily executable code.
browser tool
- can open/click/read pages
browser-automation skill
- how to perform browser workflows safely/reliably
Python/debugger capability
- tools exist
python-debugpy skill
- procedure for debugging Python
Skill vs Tool
This distinction should be locked firmly:
A Skill may contain: instructions; workflow steps; review criteria; constraints; example commands; references; supporting scripts.
Skill Does Not Automatically Create the Tool
A skill can exist while the required tool is unavailable.
Tools may come from:
Installing Skills and Capabilities
Not everything is installed the same way.
Practical mental model:
Community Skills and Supply-Chain Risk
A community skill should not be treated as harmless merely because it is “just Markdown.”
The instructions may cause an agent with powerful tools to: run commands; read files; access credentials; make network requests; modify data; invoke external tools.
Audit checklist:
- Who wrote it?
- What does SKILL.md instruct?
- What scripts are included?
- What dependencies are installed?
- What network endpoints are contacted?
- What files are read?
- What credentials are requested?
- Which tools/permissions are needed?
Trust hierarchy
Even official skills should be inspected when they touch consequential permissions.
Plugins
A Plugin is broader than a Skill.
Plugin = extension/package boundary.
A plugin can potentially package or register several capabilities such as:
Useful distinction:
Hooks
A Hook is an event-triggered extension point.
Mental model:
“When event X happens, run Y.”
Therefore, across the whole architecture:
Channels
Channels
A Channel is an ingress/egress communication surface.
It answers:
“Where do messages enter the agent system, and where are responses delivered?”
Examples shown by OpenClaw may include:
Architecture
Channel vs Tool/API/MCP
This distinction is extremely useful.
Example:
Telegram is the front door. MCP is the agent’s capability door.
Channel Authentication
Different channels require different authentication mechanisms.
| Channel | Authentication |
|---|---|
| device/QR linking | |
| Telegram | bot token |
| Discord | bot token |
| Slack | OAuth/application setup |
| Google Chat | webhook/application integration |
| Signal | device/phone linking |
Channels Increase Attack Surface
Connecting a public or semi-public channel creates an ingress trust boundary.
Potential risk:
Therefore channel access should be considered together with:
- sender restrictions;
- group restrictions;
- tool permissions;
- write permissions;
- approval policies;
- prompt-injection defenses.
Instances & Automation
Instances / Agents
The Instances concept can be understood as:
digital employees / isolated agent identities.
Each agent may have its own: workspace; sessions; skills; memory; model configuration; credentials; routing; permissions.
A useful analogy
Instance vs Node
Do not confuse:
One Windows Node could serve several agent instances. Example:
Why Multiple Instances?
Isolation becomes useful when responsibilities genuinely differ.
Research Agent
- read-heavy
- broad research tools
- no sensitive write capability
Execution Agent
- narrow action set
- stronger approval
- separate credentials
Personal Agent
- calendar/email
- personal memory
Do not create many agents merely because multi-agent architecture exists.
Cron / Automations
Cron/Automations answer:
When should work begin?
OpenClaw provides a built-in scheduler that can persist scheduled jobs, wake an agent, and optionally deliver the output.
Architecture
Example
Cron Is a Trigger, Not Intelligence
Cron does not reason. It says:
“Run this at this time.”
The agent/runtime determines what happens afterward.
Do Not Agentify Deterministic Scheduling Without Need
Example:
17:30 download data → compute fixed indicators → save database
If every step is predetermined, ordinary deterministic scheduling/code is usually better.
Agentic automation earns its place when:
Scheduled Autonomy Has More Authority
A one-shot command stops when the current interaction ends. A scheduled automation can continue operating later. Therefore, in terms of governance requirements:
Scheduled agent work deserves:
- explicit scope;
- least privilege;
- logging;
- failure handling;
- kill switch;
- clear delivery target;
- review of persistent permissions.
Synthesis & Security
The Full Dashboard Mental Map
Every primitive covered so far fits into one composite map — from the human, through the channel and Gateway, out to instance/session/automation, down through the runtime into model/skills/memory, and finally into tools that reach local devices, domain systems, and remote services.
Security Wraps the Entire Architecture
Security is not one box at the bottom. It surrounds every layer.
A Concrete End-to-End Example
Assume an agent receives:
“Analyze Company X and send me the result tomorrow morning.”
Possible architecture:
Then:
Case Study — SFI
SFI as an Architecture Study Case
A mature existing domain system is an excellent learning specimen because it already contains real business logic.
An agent-facing architecture could add:
Then:
Prefer
- analyze_ticker()
- build_analysis_pack()
- screen_universe()
Avoid exposing every primitive
- compute_ema20()
- read_row()
- compute_atr7()
- write_cell()
The MCP interface should become a stable domain contract.
SFI Skill vs SFI MCP
These are different layers.
For example:
- Inspect Structure.
- Inspect Participation.
- Inspect Location.
- Run contrarian checks.
- Separate evidence from interpretation.
- Produce judgement according to schema.
The same MCP server can support multiple skills:
One Domain System, Many Interfaces
A healthy design can expose one underlying engine through different surfaces:
This separates:
Cross-Model and Cross-Runtime Testing
Once the capability contract is stable, the same input can be tested across models and runtimes.
Then change only the runtime:
This helps separate:
Reference
The Most Important Distinctions
Keep this table mentally available.
| Concept | Core Question |
|---|---|
| Gateway | Where is traffic/control routed? |
| Runtime | What executes the agent loop? |
| Instance / Agent | Who is the logical worker? |
| Session | Which work/conversation remains continuous? |
| Context | What does the model see right now? |
| State | Where does the task currently stand? |
| Memory | What should persist for later? |
| RAG | Which canonical knowledge should be retrieved? |
| Skill | How should the agent work? |
| Tool | What callable action exists? |
| Node | Where can local/device action execute? |
| API | How do applications/services communicate? |
| MCP | How do agent systems consume capabilities interoperably? |
| Channel | Where do users/messages enter and leave? |
| Cron / Automation | When should work begin? |
| Hook | What should run when an event occurs? |
| Plugin | What extension package adds capability? |
| Permission | What authority is actually granted? |
Ten Rules Worth Keeping
Model ≠ Agent.
Agent ≠ Agent System.
Automation ≠ Intelligence.
If the next step is already known, prefer deterministic code.
Tools expand capability, not intelligence.
Capability availability ≠ action authority.
Memory ≠ context; stored information matters only when retrieved into context.
Skill = procedure; Tool = capability.
More autonomy requires more observability, permission discipline, and failure handling.
Multi-agent complexity should be earned by real isolation or specialization needs.
Practical Learning Sequence From Here
A clean empirical learning path:
Final Mental Model
When looking at any agent platform—not only OpenClaw—ask:
- Where is the Gateway?
- Where is the runtime?
- Who is the agent?
- What constitutes a session?
- How is context assembled?
- Where is state stored?
- What becomes memory?
- How is canonical knowledge retrieved?
- What tools exist?
- Where do those tools execute?
- What protocol exposes them?
- What skills guide their use?
- What permissions constrain them?
- What triggers autonomous work?
- How is failure observed and recovered?
Official OpenClaw References
These pages were used as the primary reference for current OpenClaw behavior and terminology:
- OpenClaw Docshttps://docs.openclaw.ai/
- Gateway Architecturehttps://docs.openclaw.ai/concepts/architecture
- Agent Runtimehttps://docs.openclaw.ai/concepts/agent
- Session Managementhttps://docs.openclaw.ai/concepts/session
- Contexthttps://docs.openclaw.ai/concepts/context
- Agent Workspacehttps://docs.openclaw.ai/concepts/agent-workspace
- Multi-Agent Routinghttps://docs.openclaw.ai/concepts/multi-agent
- Tools Overviewhttps://docs.openclaw.ai/tools
- Skillshttps://docs.openclaw.ai/tools/skills
- Creating Skillshttps://docs.openclaw.ai/tools/creating-skills
- Skills Configurationhttps://docs.openclaw.ai/tools/skills-config
- ClawHubhttps://docs.openclaw.ai/clawhub
- MCP CLIhttps://docs.openclaw.ai/cli/mcp
- Automation / Cron Jobshttps://docs.openclaw.ai/automation/cron-jobs
- Securityhttps://docs.openclaw.ai/gateway/security
- Memory Configurationhttps://docs.openclaw.ai/reference/memory-config