(The Brain) Setting Up OpenClaw

#ai #openclaw #agents #tutorial

The Catalyst: Intent First

I wanted an assistant that understood the job before it opened its mouth: stable model, bounded context, a workspace the agent is allowed to touch, and identity files that do not turn every session into a data breach waiting to happen.

OpenClaw is the “brain” in this stack. If you get the brain wrong, no amount of channel polish will save you. This article is Phase 1 of the Practical Guide series: how to stand OpenClaw up as a first-class brain, not a chat toy.

Overview

OpenClaw is your runtime: it routes models, agents, skills, tools, and a Git-backed workspace where persona and long-lived knowledge live. I run a single default agent (main) with one primary model, filesystem tools limited to the workspace, and memory search turned off on that agent so retrieval does not become an accidental exfil channel.

The companion pieces in this series cover voice (multilingual safety), senses (media and image gen), and connection (WhatsApp). I also attach a home-grown security skill (silas-shield) on the main agent for PII handling, session isolation, and injection defence; Phase 2 (The Voice) is the full introduction.

It started as a hackathon project and was never submitted as a formal entry but it ships in my real config, so you will see it in openclaw.json from the start. Here we focus on the brain: install, onboard, model providers, agent defaults, and the markdown contract (AGENTS.md, SOUL.md, user.md, identity.md, BOOTSTRAP.md).

In this section:

1. Install and First Run
2. The Model Layer (Providers & Primary Model)
3. Agent main and the Workspace
4. The Markdown Contract (Persona, Soul, Identity)
5. Subagents and Concurrency

Key files and concepts in this setup:

Piece	Role
`openclaw.json`	Single source of truth for models, agent list, workspace path, compaction, skills, tools.
`workspace/`	Your agent’s “long memory” on disk: identity, user prefs, tools notes, optional git history.
`agents.defaults`	Default model, workspace path, compaction (token budget), concurrency caps.
`agents.list[]`	Per-agent overrides: e.g. which skills are loaded, `memorySearch.enabled`.

Series path (read in order): 1) The Brain (this article, local model and workspace), 2) The Voice (Silas, multilingual and injection), 3) The Senses (media and image-gen policy), 4) The Connection (WhatsApp, gateway, allowlists, more wiring than the model config in part 1). Part 4 assumes parts 1 to 3 are in place so the bridge has something sane to connect.

1. Install and First Run

Prerequisites (my path, no Docker required): Node.js (≥ 18 is typical for the OpenClaw CLI), Git (if you keep workspace under version control), the OpenClaw CLI itself, and Python on the same machine if you will run silas-shield / shield.py locally. If you ever move the gateway into a container, your openclaw.json and workspace paths are still the same idea; I just do not use Docker for my gateway.

Install the OpenClaw CLI (Node ≥ 18 is typical for global npm tools).
Run the onboarding wizard at least once so openclaw.json and paths exist (lastRunCommand: onboard, local mode in my config).
Point agents.defaults.workspace at a dedicated folder (in my case the workspace lives under the OpenClaw home directory).

Note: The exact install command and version string evolve with OpenClaw releases. Prefer the official docs for the current global install; the shape of config below stays the important part.

Environment variables (placeholders only):

${CEREBRAS_API_KEY}: if you use Cerebras as an OpenAI-compatible API
${OPENCLAW_GATEWAY_TOKEN}: gateway authentication (covered in the Connection article)
${SILAS_SALT}: salt for the optional Silas Shield hasher
${OPENAI_API_KEY}: if you add image or other OpenAI API skills

2. The Model Layer (Providers and Primary Model)

Note: The 1M token budget applies to the text inference layer; image generation via tools.media utilizes a separate API and quota.

I use merge mode for models and register a custom provider with an OpenAI completions API:

Provider: custom id (e.g. custom-api-cerebras-ai), baseUrl, apiKey from environment, one or more models with id, contextWindow, maxTokens.
Default model: agents.defaults.model.primary points at custom-api-cerebras-ai/llama3.1-8b (or your chosen id).
Alias: optional short name (llama) for quick switching in the CLI.

(this is redacted so use your paths and model ids):

"models": {
  "mode": "merge",
  "providers": {
    "custom-api-cerebras-ai": {
      "baseUrl": "https://api.cerebras.ai/v1/",
      "apiKey": "${CEREBRAS_API_KEY}",
      "api": "openai-completions",
      "models": [{ "id": "llama3.1-8b", "name": "llama3.1-8b (Cerebras)" }]
    }
  }
},
"agents": {
  "defaults": {
    "model": { "primary": "custom-api-cerebras-ai/llama3.1-8b" },
    "models": { "custom-api-cerebras-ai/llama3.1-8b": { "alias": "llama" } }
  }
}

Compaction (why it matters): compaction.mode: safeguard with reserveTokens and keepRecentTokens prevents unbounded context growth. That is the difference between a bot that remembers and one that melts under long threads. The 1M token/day cap I mention in the series intro is the budget I watch for the LLM; the Silas pre-checks in part 2 run on the host and are not the same line item in my head.

3. Agent main and the Workspace

The default agent id is main. I attach the silas-shield skill at the agent level and disable memorySearch for that agent:

Setting	My choice	Rationale
`skills`	`["silas-shield"]`	Behavioural and exec-time security; see the Voice and WhatsApp articles.
`memorySearch.enabled`	`false`	Reduces risk of cross-session or over-broad retrieval; pair with explicit workspace files and session policy.
`workspace` (under defaults)	absolute path to `.../workspace`	Keeps file tools on a single tree you can back up and audit.

Session state: what lives on disk

Per-peer history for the agent is not only “whatever fits in the next prompt.” In my OpenClaw home, conversation session data lives on disk under something like agents/<agentId>/sessions/ (for me, main). That is how threads survive a gateway restart: state is reloaded from those files, not held only in RAM. Relationships with contacts in the series intro: that is this per-channel-peer history plus what you choose to put in workspace/ (e.g. memory/ or notes), not a separate vector product in my install unless you add one.

4. The Markdown Contract: Persona, Soul, and Identity

AGENTS.md (The Operator): Concise rules for interaction (e.g., "Ask before irreversible actions").
SOUL.md (The Ethics): Non-negotiable privacy and tone guidelines. This is where the agent learns to refuse PII leaks.
identity.md (The Role): The assistant’s persona and explicit security rules.
user.md (The Context): Light user preferences. Note: Keep this lean to avoid injecting unnecessary bloat into every session.
BOOTSTRAP.md (The Onboarding): Minimal instructions for first-run initialization.
One contract in every language: If you want replies in the user’s language, say that in AGENTS / SOUL / identity. The same markdown contract applies. Security rules in SOUL.md and Silas are not a second formatting system; they extend the same policy to every script. Phase 2 (The Voice) spells out Silas. Here you only need one coherent rule set so part 2 does not fight part 1.

Practical rule: If identity.md and user.md are in the workspace they may be part of the system context. Treat them as security documents, not diaries. The Shield article in this series goes deeper; here the takeaway is: scope identity to what the agent must know to be useful, not everything you know.

5. Subagents and Concurrency

maxConcurrent: 1 and tight subagent limits keep behaviour predictable for a personal deployment. If you later fan out to parallel subagents, raise limits deliberately so that each extra concurrent agent is another surface for races and runaway tool use.

Key takeaway for new users: Phase 1 is done when (1) one primary model and provider are stable, (2) the workspace is the only FS surface, (3) compaction is on, (4) persona files are short and security-aware, and (5) memory search is a conscious “on or off” decision, not an accident. Then you are ready to give the agent a Voice and a Connection in the next articles.