OpenClaw Setup Guide: from clean install to safe daily use

Who this guide is for

This guide is for people who want an OpenClaw setup that is actually usable day to day — not just technically "running". The goal is a system that can chat, code, check infra, use GitHub and Railway, and keep long-term memory without turning into a security mess.

The baseline architecture

A healthy OpenClaw stack usually has four layers:

1. Gateway + channel layer — Telegram, Discord, or another chat surface.
2. Model/provider layer — OpenAI, OpenRouter, or other model backends.
3. Workspace + memory layer — markdown files, handoff, daily notes, and a curated long-term memory file.
4. Ops layer — GitHub auth, Railway auth, cron tasks, health checks, and backups.

If one layer is shaky, the whole experience feels unreliable.

Step 1 — Start with a clean workspace

Your workspace should be treated like a real working directory, not a junk drawer.

• Keep a clear AGENTS.md, SOUL.md, USER.md, and TOOLS.md.
• Store durable context in memory/YYYY-MM-DD.md, memory/handoff.md, and MEMORY.md.
• Do not keep secrets in markdown files.
• Add .gitignore rules for runtime state, caches, .openclaw/, and local secrets.

A good test: if you had to hand the repo to another engineer for one hour, would they understand the project without seeing your private tokens?

Step 2 — Connect models safely

For day-to-day work, it helps to split models by job:

• Main chat / coding: use a stronger model.
• Cron / memory maintenance / background summaries: use a cheaper model.
• Speech or OCR: route to task-specific tools only when needed.

Do not paste API keys into chat history. Prefer one of these:

• openclaw models auth paste-token --provider ...
• env vars loaded by the daemon
• auth profiles managed by OpenClaw

If a key was ever pasted into chat, rotate it. Assume compromise.

Step 3 — Set channel boundaries early

Before the assistant becomes useful, decide where it is allowed to speak.

A solid policy looks like this:

• Main direct chat: full personal context allowed.
• Group chats: respond only when tagged, asked, or clearly useful.
• Operational bot accounts: send alerts only on changes, not on every heartbeat.

This matters more than people think. A technically good agent with bad notification hygiene becomes annoying fast.

Step 4 — Use memory with intent

Memory should not be a dump of everything that happened.

Use three layers:

• Daily notes for raw events and short-term context.
• Handoff for what the next session needs immediately.
• Long-term memory for durable facts, rules, preferences, and decisions.

Good examples of durable memory:

• which projects are active
• which projects are archived
• which bots are paper trading only
• what models are preferred for coding vs cron
• notification preferences

Bad examples:

• one-off tokens
• random outputs that can be regenerated
• speculative assumptions

Step 5 — Lock down external actions

OpenClaw becomes much safer when you define a default rule:

• reading, searching, and internal edits are cheap
• public posting, email sending, account changes, and production writes need confirmation

That includes GitHub and Railway. Reading status is usually safe. Pushing to production should be deliberate.

Step 6 — Add health checks before you need them

A stable setup usually has:

• openclaw status
• cron list checks
• cron task failure checks
• gateway status checks
• memory consistency checks
• lightweight handoff freshness checks

The right time to add health checks is before the first broken deploy or expired provider token.

Step 7 — GitHub and Railway access

For GitHub, prefer gh auth login over manually storing PATs.

For Railway:

• authenticate with the CLI once
• verify with railway whoami
• inspect services and logs before changing variables
• prefer local fixes + review before deploy

A useful principle is: read first, mutate second.

Common mistakes

Storing secrets in markdown

This is the fastest way to leak credentials into memory files, git history, or screenshots.

Letting cron spam the owner

Heartbeats and bot notifications should collapse duplicate states. If nothing changed, stay quiet.

Mixing test and production assumptions

Paper trading, staging services, and production should be labeled explicitly. Don’t rely on memory.

Skipping handoff discipline

If the system wakes up "smart" but forgets yesterday’s real work, it won’t feel dependable.

Troubleshooting checklist

If OpenClaw feels broken, check in this order:

1. openclaw status
2. gateway/channel status
3. model auth status
4. cron list + recent task runs
5. relevant repo auth (gh auth status, railway whoami)
6. workspace files changed recently
7. handoff freshness

That order catches most real failures quickly.

Recommended daily workflow

• Morning: check gateway, cron, and urgent notifications.
• During work: use the main chat for coding/help, keep pushes explicit.
• Evening: write durable decisions into memory and keep handoff short but factual.

Security note: if any secret ever lands in a chat message, markdown note, or git history by accident, treat it as compromised and rotate it.

Commands you will actually use

openclaw status
openclaw cron list --json
openclaw tasks list --runtime cron --json
gh auth status
railway whoami

FAQ

What should never go into memory files?

Tokens, passwords, recovery codes, and other credentials. Memory files are for durable context, not secrets.

When should the assistant stay quiet?

When nothing changed, when the user is asleep, or when the update would be repetitive operational noise.

What is the safest default for production actions?

Read first, propose second, mutate last.

Final advice

The best OpenClaw setups are boring in the right way: predictable, recoverable, and easy to audit. If a feature adds magic but makes the system harder to trust, it is usually not worth it.