1. Install the local prerequisites
Get Homebrew, Node.js, npm, OpenClaw, Claude Code, and Codex onto the machine
Start by installing the local tooling that the rest of the setup
depends on. On macOS, the practical route is Homebrew first, then
Node.js, then the CLIs.
Relevant sites:
# install Homebrew if it is not already present
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# install Node.js and npm
brew install node
node --version
npm --version
# install CLIs
npm install -g openclaw
npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
# verify
openclaw --help
claude --help || claude doctor
codex --help
In this environment, user-level npm binaries ended up in a custom
path, for example:
/home/example/.npm-global/bin/openclaw
/home/example/.npm-global/bin/codex
2. Create the OpenClaw workspace
Pin the workspace to one directory
The workspace must live in one predictable place. Here, that place is
~/.openclaw/workspace.
mkdir -p ~/.openclaw/workspace
cd ~/.openclaw/workspace
pwd
# expected: /home/example/.openclaw/workspace
Then bind OpenClaw to that directory:
openclaw setup --workspace ~/.openclaw/workspace --wizard
If the target is a remote gateway-backed setup:
openclaw setup \\
--workspace ~/.openclaw/workspace \\
--mode remote \\
--wizard
3. Let OpenClaw seed the workspace files
Use the starter files that setup creates automatically
OpenClaw creates the starter workspace files on setup or first agent
run. That includes AGENTS.md, SOUL.md,
TOOLS.md, IDENTITY.md,
USER.md, and HEARTBEAT.md. If the workspace
is brand new, it also creates BOOTSTRAP.md. By default,
MEMORY.md is optional and is not auto-created.
openclaw setup
Then inspect what setup created:
cd ~/.openclaw/workspace
find . -maxdepth 2 -type f | sort
The directory shape should look like this:
~/.openclaw/workspace/
├── AGENTS.md
├── HEARTBEAT.md
├── IDENTITY.md
├── SOUL.md
├── TOOLS.md
├── USER.md
├── BOOTSTRAP.md # only on a brand-new workspace
└── memory/
4. Edit the generated files
Write the startup sequence into AGENTS.md
The assistant needs a fixed startup order. Put it directly into
AGENTS.md.
## Session Startup
Before doing anything else:
1. Read `SOUL.md`
2. Read `USER.md`
3. Read `memory/YYYY-MM-DD.md` (today + yesterday)
4. If in main session: also read `MEMORY.md`
5. Read `PURPOSE.md` if it exists
Don't ask permission. Just do it.
This is the part that stops every session from becoming an amnesia
simulator.
5. Write the identity and user context files
Define voice, user context, and local tool notes
Next, populate SOUL.md, USER.md, and
TOOLS.md.
# SOUL.md
Have a take.
Be genuinely helpful.
Brevity is mandatory.
Solve first.
Call out bad ideas early.
# USER.md
- Name: example-user
- Timezone: Europe/Berlin
- Values organization, tidiness, and consistency
- Practitioner in NLP/Python and ISO 27001
- Wants memory preserved across Claude Code and Codex
# TOOLS.md
- openclaw binary: /home/example/.npm-global/bin/openclaw
- codex binary: /home/example/.npm-global/bin/codex
- workspace root: /home/example/.openclaw/workspace
6. Add MEMORY.md and daily notes
Use MEMORY.md for durable facts and daily notes for session detail
Long-term memory should stay clean. Create MEMORY.md
when you want durable facts, and use
memory/YYYY-MM-DD.md for day-to-day activity.
cd ~/.openclaw/workspace
touch MEMORY.md
mkdir -p memory
touch memory/$(date -u +%F).md
Example MEMORY.md content:
- OpenClaw is the persistent memory layer across Claude Code and Codex
- Strong preference for organization and consistency
- Never log credentials, tokens, or .env content
Example daily note:
# 2026-04-11
- Project: `example-user`
- Agent: Codex
- Time: 2026-04-11 08:13 UTC
- Task: bootstrap workspace memory files
- Decisions: split durable memory from daily notes
- Rationale: keep long-term memory tidy
7. Put the workspace under git
Track structure changes from the beginning
Once the files exist, commit them.
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md USER.md TOOLS.md MEMORY.md HEARTBEAT.md memory
git commit -m "Bootstrap OpenClaw workspace files"
If the workspace is already in git, skip git init and
just commit the files.
8. Add the ingestion hooks
Capture commits and session endings
The memory layer is more useful when it captures more than just final
git state. The setup uses a global git post-commit hook
plus a Claude Code Stop hook.
# set a global hooks path
mkdir -p ~/.git-hooks
git config --global core.hooksPath ~/.git-hooks
# example file locations
~/.git-hooks/post-commit
~/bin/claude_stop_hook.sh
The exact script contents can evolve. The design principle does not:
send commit events and session-end events into the memory layer.
9. Keep the remote side private
Use Tailscale, loopback binding, SSH tunneling, and a tight firewall
The memory and orchestration layer should not be public. Keep the VPS
private behind Tailscale, keep the gateway loopback-bound, and only
expose what genuinely needs public reachability.
# conceptual model
# - service bound to localhost on the VPS
# - Tailscale provides private network connectivity
# - SSH tunnel bridges local work to the private service when needed
# - provider firewall allows only required public ports
Practical firewall shape:
# allow 80/tcp if serving public HTTP
# allow 443/tcp if serving public HTTPS
# keep SSH/admin services private or tightly restricted
# deny everything else by default
10. Verify the whole chain
Check files, commands, and end-to-end capture
Verify the files are in place and readable.
cd ~/.openclaw/workspace
find . -maxdepth 2 -type f | sort
sed -n '1,120p' AGENTS.md
sed -n '1,120p' SOUL.md
sed -n '1,120p' USER.md
sed -n '1,120p' MEMORY.md
Then use a canary phrase to verify the capture path:
lobster remembers everything
If the system can later recall that exact phrase, the ingestion path
is doing its job.