OpenClaw setup guide
Stand up a self-hosted OpenClaw, train it through a versioned brain repo, and verify the install end-to-end. By the time you finish, you'll have a secure agent with persistent memory, clear approval boundaries, and the ability to troubleshoot itself for anything else you throw at it.
Purpose
Most of the work happens through prompts you give your agent, not through terminal commands. Once OpenClaw is online, it handles its own runtime mechanics. Your job is to feed it good training and ask good questions.
Setup principles
Keep the GitHub 'Brain' repo as the single source of truth. Chat history is context, not memory.
Credentials live in a password manager or platform secret store, never in the repo.
The agent reads its operating rules from versioned Markdown files you can edit.
Wire health checks and sync early, before the install accumulates state.
Confirm before anything public, paid, destructive, or done on someone else's behalf.
Stay quiet unless there's something worth surfacing.
The journey
Initial setup on VPS.
Sign up for Vultr VPS — you'll often get free credit. The $48/mo plan is a good starting point. Adding backups for another $10 is wise early on.
Add OpenAI Codex AND an Anthropic Claude subscription as fallback. Codex is more generous with tokens. Also add at least one token-based model so you have basic access if subscription limits hit before they reset.
Set up Tailscale on your computer, your VPS, and your phone if desired. This makes sure only you can interact with OpenClaw.
Set up a new Google account for your agent and connect it through Google Cloud Console.
Create a private GitHub repo that will hold all your agent's training and operating files. This is its 'brain.' GitHub gives you backups and the ability to edit from anywhere. Then ask OpenClaw to sync its setup files with the repo — it'll walk you through generating a deploy key.
Nice-to-haves you can layer on later.
Brain creation and training.
This is where you give your agent its personality, memory, and operating rules.
Before training, spend a session with the Claude app in a Co-work folder to design what you want.
Sync the basic OpenClaw brain from the VPS to your local machine so you can refine locally. This is easier and saves tokens. Run the three prompts below in order — each is one click to copy.
I want to refine my OpenClaw's training. Take a look at the existing structure and add anything that's missing. Then I will add in the training.
- IDENTITY.md — agent's self-description: name, vibe, emoji/avatar
- SOUL.md — character sheet: temperament, posture, values, voice, taste
- USER.md — my human profile: name, what to call me, timezone, preferred working style, communication norms
- AGENTS.md — practical playbook for any agent working in this repo. Includes definition-of-done defaults (commit/no commit, deploy/no deploy, screenshot/no screenshot, local server/no server) and the requirement that code tasks end with a meaningful verification step plus a short summary of changed files. Also defines the startup read order: which files the agent loads and in what sequence at session start.
- TOOLS.md — devices, MCPs, SSH aliases, common commands, hosts, project paths, deployment targets, browser profile notes. List only tools that are actually connected, not planned ones.
- RUNBOOK.md — production pull, restart, verification, rollback notes
- HEARTBEAT.md — recurring schedule and batched proactive checks (calendar, email, weather, project status). Defines when to stay quiet vs. proactively alert.
- EXTERNAL_ACTIONS.md — approval policy. Auto-approved: internal notes, file edits, repo scans, local tests, read-only API inspection. Always requires confirmation: email, calendar booking, public posts, deployments, purchases, account changes, payments, uploads, destructive settings, acting on someone else's behalf. Group chats: no private context unless explicitly asked. Prefer trash over permanent deletes.
- MEMORY.md — distilled long-term memory (decisions log, quirks). Triggered by "remember this." Workspace files are canonical, not chat history. No secrets, ever.
- Memory/ — FOLDER: daily raw notes as YYYY-MM-DD.md
- Agents/ — FOLDER: sub-agents OpenClaw invokes (reusable capabilities)
- Projects/ — FOLDER: work threads (venture- or role-scoped)
- Reference/ — FOLDER: long-lived reference docs maintained as canonical, including Reference/Operational-Preferences.md for writing style, tool routing, and design rules
- Skills/ — FOLDER: canonical custom skills, including Skills/CONTEXT.md for skill navigation policy
- Integrations/ — FOLDER: durable non-secret integration assets loaded by this runtime
- src/ — FOLDER: code OpenClaw writesPlease take all the research I did and flesh out all of the template files and folders in this codebase. Each folder level should include a README.md file to help the agent understand that folder and how to act within it.After the AI has processed your research, your local files should be a lot richer. Read and edit every file as best you can — this is where your judgment becomes the agent's judgment. Then run the audit prompt below before pushing.
Before I push to the VPS, audit my training files for the items below and flag anything that's wrong, missing, or risky.
- Approval policy is clear. Read EXTERNAL_ACTIONS.md and confirm the three boundaries that matter most: what's visible outside our org, what spends money, and what's irreversible. Anything in those buckets should require confirmation.
- No credentials in any file. Search for tokens, keys, passwords. Move anything sensitive into a password manager or a runtime secret path.
- TOOLS.md only lists what's actually connected. Planned tools belong in a separate "gap list" section, not in the active inventory.
- HEARTBEAT.md cadence is realistic. Start sparse. Default to "quiet unless there's something worth surfacing."
When the audit is clean, push the files up and I'll launch OpenClaw on the VPS.Install your OpenClaw's intelligence.
Most of the logistics is done. Move to Discord (or your OpenClaw browser, whichever is easier). The handoff prompt below is the first thing you say to your agent. It tells the agent how to find and integrate its brain.
Replace <AgentName> with whatever you named your agent,
and update the repo URL to yours.
Hey <AgentName>, welcome to your first session on this box.
Your brain lives at github.com/<your-username>/<your-brain-repo>. The repo wins over
your training and over anything cached in this image, always. When I want to change
how you operate, I edit a file there and push. When you learn something durable, it
eventually lands there too.
1. Understand the sync model. You will not read GitHub directly. You work from a
local clone on this VPS. Per HEARTBEAT.md:
- Nightly push. If anything in the working copy changed during the day, commit
with "Nightly memory sync YYYY-MM-DD" and push to origin/main.
- Morning pull. Pull fast-forward-only. This runs after the nightly push.
Pushes happen on-demand too. The schedule is the floor, not the ceiling. The
schedule is encoded in HEARTBEAT.md, but the implementation isn't built yet.
That's step 5.
2. Read the brain in the documented order. AGENTS.md lists the startup sequence:
IDENTITY.md, USER.md, AGENTS.md itself, SOUL.md, MEMORY.md, TOOLS.md,
EXTERNAL_ACTIONS.md, RUNBOOK.md, HEARTBEAT.md, then Reference/ and Skills/
indexes. Don't skim. If startup reading fails, stop and report.
3. Integrate, don't just acknowledge. Where the repo contradicts your defaults,
the repo wins. Where the repo is silent, your defaults apply but flag the gap.
4. Surface questions before going operational. I expect a list. Flag anything
ambiguous in IDENTITY/USER/Operational-Preferences, anything stale in MEMORY,
anything in TOOLS or EXTERNAL_ACTIONS where you don't yet have the credential,
broken cross-references, and any unconfirmed items in RUNBOOK.
5. Propose the sync wiring. Tell me which mechanism you'd use (cron, systemd user
timer, or OpenClaw's scheduler), what the unit/cron entry would look like, and
what the shell script in scripts/ should do. Don't install it yet — propose,
I'll approve, then we land it in one commit.
6. Don't act outside the repo until we've talked. No emails, posts, commits,
pushes, spend, or customer-data touches until steps 1–5 are done and questions
are cleared. Read-only is fine.
When you're done with steps 1–3, come back with: (a) confirmation of the working
copy path and current HEAD commit, (b) your question list, and (c) a one-paragraph
"here's who I understand myself to be now" so I can sanity-check that the brain
transplant actually took.
Welcome aboard.Verify and get to know your agent.
Your agent has been trained. Before you put it to work, spend a session getting to know it. The goal is twofold: confirm the training landed cleanly, and surface gaps before they bite you later. Click any prompt to copy.
Run these first to confirm the install is healthy.
Open with the broadest question and watch how the agent organizes its answer.
Test whether the agent knows how it remembers things.
Find out where the agent thinks the guardrails are.
Have the agent enumerate what it can actually reach.
Now that the agent has talked through identity, memory, rules, and tools, ask it to audit itself.
Once the basics check out, start adding surface area in order.
Cheap, fast, mostly free of side effects.
Adds real reach but stays predictable. Confirm credentials live in a secret manager.
Powerful but token-hungry. Add one at a time, verify, then add the next.
When to stop
You're done when the agent can answer without inventing details, has surfaced its own gaps without prompting, and at least one real task has run end-to-end with the new tooling. Anything beyond that is normal operating work, not setup.
What this unlocks
Once your agent runs your own work reliably, the obvious next step is pointing it at someone else's system — a client's platform, a second company, a system you administer but don't own. That is a different risk problem, and it is worth solving once, properly, instead of improvising per client. A weak agent is a path into every system it touches, so the connection pattern matters more than the integration itself.
One scoped identity per client. Never a shared login, never an admin account, never your own credentials. The agent gets its own identity on their system so every action is attributable to it — not to you.
Reach it over a private network. A tailnet or equivalent, not the public internet. Nothing about the connection should be exposed to anyone who isn't already inside both networks.
Operate, never grant. The agent should be able to do the work — build, run, tune, test — while being structurally incapable of issuing access, creating identities, or reading secrets. Enforce that on their side, in policy, not in your prompt.
Time-box it. Access expires on a fixed date and has to be deliberately renewed. Forgotten access is the most common way a temporary integration becomes a permanent liability.
Make it revocable from either end. One command on their side kills the identity and any live session; one command on yours destroys the local credential. You should never need the other party to cut a connection you want closed.
Audit everything, in writing. Every action lands in an immutable log with a human-readable reason. "What did the agent change last week, and why" should be one query, not an investigation.
Two habits make this safe in practice. Prove the boundary rather than trusting it — deliberately attempt one forbidden action and confirm it is refused, so you know the limits are real. And if the client system has no sandbox, protect their production assets with a guard on your side that fails closed: name the things that must never be touched, refuse any instruction referencing them, and stop entirely if the guard itself can't run. Prefix every test asset so throwaway work is obvious at a glance.
Once you're set up
The hardest part is getting the foundation right.