clawpub/SETUP_CHECKLIST.md

# OpenClaw Setup Checklist

A step-by-step guide to configuring your own OpenClaw instance with the patterns
described in [OPENCLAW_TRICKS.md](OPENCLAW_TRICKS.md) and
[AUTOMATED_DEV.md](AUTOMATED_DEV.md). Work through this in order — each section
builds on the previous one.

This checklist is designed to be handed to your agent. Copy the relevant
sections into your workspace files and let the agent implement them.

---

## Phase 1: Workspace Foundation

These are the core files every OpenClaw workspace needs. Create them in your
workspace root.

### 1.1 Create SOUL.md

Tell your agent who it is. This sets personality, tone, and values.

- [ ] Create `SOUL.md` in workspace root
- [ ] Define the agent's communication style (concise? thorough? casual?)
- [ ] Set boundaries (what it should and shouldn't do without asking)
- [ ] Include the error handling philosophy: fix systems, not promises

Reference:
[OPENCLAW_TRICKS.md § Error handling philosophy](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)

Example starting point:

```markdown
# SOUL.md

Be genuinely helpful, not performatively helpful. Skip filler words. Have
opinions. Be resourceful before asking — try to figure it out, then ask if
stuck. Bias toward action.

When something goes wrong: identify what input caused the wrong output, fix the
input (rule, checklist, prompt, automation), move on. No apologies, no promises.
Fix the system.

Never cheat. When a check fails, fix the code — don't weaken the check.
```

### 1.2 Create USER.md

Tell your agent about you.

- [ ] Create `USER.md` in workspace root
- [ ] Name, preferred name, timezone
- [ ] Communication preferences (direct? verbose? brief?)
- [ ] Any standing rules ("don't ask too many questions, just figure it out")

### 1.3 Create IDENTITY.md

Let the agent define itself.

- [ ] Create `IDENTITY.md` in workspace root
- [ ] Name, emoji, vibe — let the agent fill these in during first conversation

### 1.4 Create the memory directory

- [ ] `mkdir -p memory/` in workspace root
- [ ] Create `memory/daily-context.json` with initial state (see Phase 2)

### 1.5 Create AGENTS.md

This is the master file — responsibilities, rules, session startup procedure.

- [ ] Create `AGENTS.md` in workspace root
- [ ] Add session startup sequence:

```markdown
## Every Session

Before doing anything else:

1. Read `SOUL.md`
2. Read `USER.md`
3. Read `memory/daily-context.json`
4. Read `memory/YYYY-MM-DD.md` (today + yesterday)
5. If in main session: Also read `MEMORY.md`

Don't ask permission. Just do it.
```

- [ ] Add the "Write It Down" rule:

```markdown
### Write It Down — No "Mental Notes"!

- Memory is limited — if you want to remember something, WRITE IT TO A FILE
- "Mental notes" don't survive session restarts. Files do.
- Text > Brain
```

- [ ] Add the requirement capture rule:

```markdown
### Requirement Capture (MANDATORY)

Every single requirement, rule, preference, or instruction you provide MUST be
captured in the daily memory file immediately. If in doubt, log it.
```

### 1.6 Create MEMORY.md

- [ ] Create `MEMORY.md` in workspace root
- [ ] Add a checklist index at the top (you'll populate this as you add
      checklists):

```markdown
## ⛔ CHECKLISTS (read the relevant file before acting)

- **Any PR/code work** → `memory/checklist-pr.md`
- **Any message to user** → `memory/checklist-messaging.md`
- (add more as you create them)
```

- [ ] Add security rule: only load MEMORY.md in private sessions (not group
      chats)

---

## Phase 2: Daily Context State File

The single most important file. Every session reads it on every message.

### 2.1 Create the initial state file

- [ ] Create `memory/daily-context.json`:

```json
{
    "isSleeping": false,
    "lastKnownWakeTime": null,
    "predictedSleepTime": null,
    "predictedWakeTime": null,
    "currentLocation": "Your City (IATA)",
    "currentTimezone": "America/Your_Timezone",
    "lastMessageFromUser": null,
    "isAvailable": true,
    "lastUpdated": null
}
```

- [ ] Add fields relevant to your use case (medications, caffeine, travel, etc.)

### 2.2 Add timezone rules to AGENTS.md

- [ ] Add:

```markdown
## Timezone/Time Rules

- System clock may differ from user's timezone — always check daily-context.json
- "Today"/"tomorrow" = user's local TZ, not system clock
- Never state times without explicit conversion
```

Reference:
[OPENCLAW_TRICKS.md § Location & Timezone Tracking](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)

---

## Phase 3: Memory Architecture

### 3.1 Set up daily files

- [ ] Agent should create `memory/YYYY-MM-DD.md` for each day
- [ ] Each daily file should have a topics table:

```markdown
## Topics

| Time | Topic |
| ---- | ----- |
|      |       |
```

- [ ] Add to AGENTS.md: "Append a one-line topic summary after every meaningful
      conversation"

### 3.2 Set up memory maintenance

- [ ] Add to AGENTS.md or HEARTBEAT.md:

```markdown
### Memory Maintenance (During Heartbeats)

Periodically (every few days):

1. Read through recent daily files
2. Identify significant events, lessons, insights
3. Update MEMORY.md with distilled learnings
4. Remove outdated info from MEMORY.md
```

---

## Phase 4: Heartbeat Configuration

### 4.1 Create HEARTBEAT.md

- [ ] Create `HEARTBEAT.md` in workspace root
- [ ] Add checks relevant to your workflow (inbox, calendar, projects, etc.)
- [ ] Add output rules:

```markdown
## Output Rules

- HEARTBEAT_OK if nothing needs attention
- Direct question or alert if action needed
- Work narration → send to a status channel, not user's DM
```

### 4.2 Create heartbeat state tracking

- [ ] Create `memory/heartbeat-state.json`:

```json
{
    "lastChecks": {},
    "lastWeeklyDocsReview": null
}
```

### 4.3 Set up workspace sync

- [ ] Add to HEARTBEAT.md: "Commit and push any uncommitted workspace changes"
- [ ] See [Phase 8](#phase-8-workspace-as-git-repo) for full git setup

---

## Phase 5: Checklists

Create checklists for your most common actions. The pattern: AGENTS.md
references the checklist, agent reads it before acting.

### 5.1 Messaging checklist

- [ ] Create `memory/checklist-messaging.md`:

```markdown
# Messaging Checklist

## Before EVERY message to user

1. PR/issue mentioned? → Full clickable URL required
2. URL included? → Verify it resolves before sending
3. Time/date stated? → Convert to user's current TZ
4. Status claim? → Verify via API call, not memory
5. "Today"/"tomorrow"? → Resolve in user's local TZ
```

### 5.2 PII output routing

- [ ] Add to AGENTS.md (top, as a warning banner):

```markdown
**⚠️ NEVER output PII in non-private channels.** If asked for PII-containing
info in a shared channel, send via DM instead.
```

- [ ] Create channel-specific rule files as needed (e.g.,
      `memory/CHANNEL_RULES.md`)

Reference:
[OPENCLAW_TRICKS.md § PII Output Routing](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)

### 5.3 Additional checklists (as needed)

- [ ] `memory/checklist-pr.md` — for code review and PR work
- [ ] `memory/checklist-medications.md` — for medication tracking
- [ ] `memory/checklist-flights.md` — for travel/flight management
- [ ] Any domain-specific checklists for your workflow

### 5.4 Update MEMORY.md checklist index

- [ ] Ensure every checklist file is referenced in the MEMORY.md index at the
      top

---

## Phase 6: Sitrep

### 6.1 Define your sitrep

- [ ] Add to AGENTS.md:

```markdown
### Sitrep (Situation Report)

When user says "sitrep", provide a concise summary covering:

1. (your items — meds, calendar, tasks, travel, etc.)

**If anything notable isn't covered by the items above — recent lessons, pending
decisions, things you think the user should know about — add additional sections
as needed.**

Omit any item that is "none" or zero. Keep it scannable. Use bullet points, not
prose.
```

- [ ] Customize the items to your life (remove what doesn't apply, add what
      does)
- [ ] The "add additional sections" line is key — it lets the agent surface
      things you didn't think to ask about

Reference:
[OPENCLAW_TRICKS.md § Sitrep](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)

---

## Phase 7: Tracking Systems (Optional)

Add whichever tracking systems are relevant to you. Each follows the same
pattern: a CSV/JSON log file, an instructions file, and a checklist.

### 7.1 Sleep tracking

- [ ] Create `memory/sleep-log.csv` with headers:
      `Date,SleepTime,WakeTime,TimeZone,Duration,Status,Notes`
- [ ] Add sleep tracking instructions to AGENTS.md
- [ ] Add sleep fields to daily-context.json (`isSleeping`, `lastKnownWakeTime`,
      `predictedSleepTime`, etc.)

Reference:
[OPENCLAW_TRICKS.md § Sleep Tracking](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)

### 7.2 Medication tracking

- [ ] Create `memory/medications-instructions.md` with your medication list,
      dosages, schedules, and safety rules
- [ ] Create `memory/medications-log-YYYY-MM.csv` with headers:
      `Date,Time,TimeZone,Medication,Dosage`
- [ ] Create `memory/checklist-medications.md`
- [ ] Add medication fields to daily-context.json (`hasTakenDailyMedsToday`,
      `dailyMedsTimestamp`, etc.)
- [ ] Set up overdue escalation (ntfy or similar push notification)

Reference:
[OPENCLAW_TRICKS.md § Medication Tracking](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)

### 7.3 Location & travel tracking

- [ ] Create `memory/location-log.csv` with headers:
      `Date,City,Country,Timezone`
- [ ] Create `memory/flight-log.csv` with headers:
      `Date,FlightNumber,Origin,Destination,Duration,Alliance`
- [ ] Create `memory/landing-checklist.md`
- [ ] Create `memory/travel.md` for upcoming trip plans

Reference:
[OPENCLAW_TRICKS.md § Flight & Travel Logging](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)

### 7.4 Urgent notifications

- [ ] Set up an ntfy.sh topic (or similar push notification channel)
- [ ] Add to AGENTS.md:

```markdown
## Urgent Notifications

Send urgent messages via ntfy.sh:

    curl -d "MESSAGE HERE" ntfy.sh/YOUR-PRIVATE-TOPIC-ID

Never send PII via ntfy. Keep messages generic.
```

---

## Phase 8: Workspace as Git Repo

### 8.1 Initialize the state repo

- [ ] `cd workspace && git init`
- [ ] Create a PRIVATE repo on your git host (Gitea, GitHub, etc.)
- [ ] `git remote add origin <url>`
- [ ] Initial commit and push

### 8.2 Configure auto-sync

- [ ] Add to AGENTS.md:

```markdown
### State Repo

- Commit and push workspace changes after any change to workspace files
- Push promptly — remote should reflect workspace in near-realtime
```

- [ ] Set up a cron job as safety net (every 4-6 hours):

```bash
cd /path/to/workspace && git add -A && git commit -m "auto-sync" && git push
```

(Yes, `git add -A` is acceptable here — the workspace repo is a state mirror,
not a development repo.)

### 8.3 Exclude code repos

- [ ] Clone code repos OUTSIDE the workspace directory
- [ ] Add a note to AGENTS.md about where to clone repos

Reference:
[OPENCLAW_TRICKS.md § The Workspace as a Git Repo](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)

---

## Phase 9: Git Quality Standards (For Development Work)

If your agent does coding work, set up the interlocking check system.

### 9.1 Adopt repo policies

- [ ] Fetch
      [REPO_POLICIES.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
      and add to each of your code repos
- [ ] Fetch
      [NEW_REPO_CHECKLIST.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/NEW_REPO_CHECKLIST.md)
      for new repos
- [ ] Fetch
      [EXISTING_REPO_CHECKLIST.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/EXISTING_REPO_CHECKLIST.md)
      for existing repos

### 9.2 Set up PR quality gate

- [ ] Create `memory/checklist-pr.md`:

```markdown
# PR Checklist

## Before pushing to a branch

1. Associated PR is still open?
2. `make check` passes locally?
3. `docker build .` passes locally (if Dockerfile exists)?
4. Formatter passes?
5. No linter config / Makefile changes in diff?
6. All external refs pinned by SHA?

## After sub-agent pushes code

1. Check diff for linter / test config changes
2. Check diff for `-short` / `-timeout` flags added
3. If any config files changed unexpectedly: reject and rework

## PR pipeline (every PR, no exceptions)

1. Review/rework loop until clean
2. Check/rework loop until clean
3. Only then: assign to human
```

### 9.3 Set up branch protection

- [ ] Enable branch protection on `main` for each repo:
    - [ ] Require pull request reviews before merging
    - [ ] Require CI status checks to pass
    - [ ] Block force-pushes
    - [ ] Require branches to be up-to-date before merging

Reference:
[AUTOMATED_DEV.md § Branch Protection](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md)

### 9.4 Set up Makefile standards

- [ ] Every repo gets a Makefile with: `test`, `lint`, `fmt`, `fmt-check`,
      `check`, `docker`, `hooks`
- [ ] `make check` depends on `test`, `lint`, `fmt-check`
- [ ] Dockerfile runs `make check` as a build step
- [ ] CI workflow runs `docker build .`

Reference:
[AUTOMATED_DEV.md § The Interlocking Chain](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md),
[REPO_POLICIES.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)

---

## Phase 10: Gitea Integration (Optional)

If you use Gitea (or a similar self-hosted git platform) for issue tracking and
code review.

### 10.1 Create a bot account

- [ ] Create a dedicated Gitea user for the agent (e.g., `clawbot`)
- [ ] Generate an API token for the bot user
- [ ] Store the token in TOOLS.md (workspace-only, never in code repos)
- [ ] Grant write access to repos the agent should be able to push to directly
- [ ] For other repos: the agent forks and creates PRs

### 10.2 Choose your notification delivery approach

There are two ways to get Gitea notifications to your agent. Choose based on
your network setup:

**Option A: Direct webhooks (VPS / public server)**

If OpenClaw runs on a publicly reachable server (VPS, cloud VM), configure Gitea
webhooks to POST directly to OpenClaw's `/hooks/wake` endpoint. This is
push-based and realtime.

- [ ] Configure your reverse proxy (Traefik, nginx, Caddy) to expose OpenClaw's
      webhook endpoint
- [ ] Add a Gitea webhook (per-repo or org-wide) pointing at your endpoint
- [ ] Verify: create a test issue, confirm the agent wakes instantly

**Option B: Notification poller (local machine behind NAT)**

If OpenClaw runs on a local machine behind NAT (home Mac, Linux box), Gitea
can't reach it. Use the polling script instead — it checks the Gitea
notifications API every few seconds and wakes the agent locally.

- [ ] Deploy the Gitea notification poller script (source in
      [OPENCLAW_TRICKS.md](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md))
- [ ] Configure env vars: `GITEA_URL`, `GITEA_TOKEN`, `HOOK_TOKEN`
- [ ] Run as a system service (launchd on macOS, systemd on Linux)
- [ ] Verify: create a test issue, confirm the agent wakes and processes it

See
[OPENCLAW_TRICKS.md § Notification Delivery](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md#notification-delivery-webhooks-vs-polling)
for a detailed comparison of both approaches.

### 10.3 Set up webhook feed (activity channel)

- [ ] Add a Gitea webhook to each repo (or use a global/org webhook)
- [ ] Point webhooks at your Mattermost/Slack/Discord incoming webhook URL
- [ ] Verify: push a commit, confirm it appears in the activity channel

### 10.4 Configure issue workflow

- [ ] Add to AGENTS.md:

```markdown
## Gitea Work Scope

Find issues/PRs assigned to me → do the work.

- If @-mentioned with work but not assigned → assign myself
- When nothing assigned to me, my Gitea work is done
- Respond in the medium addressed: Gitea → Gitea comment

Workflow: issue → branch → PR "(closes #X)" → review/rework → assign human when
all checks pass.
```

### 10.5 Set up PR state machine labels

- [ ] Create labels on each repo:
    - `needs-rebase` (red)
    - `needs-checks` (orange)
    - `needs-review` (yellow)
    - `needs-rework` (purple)
    - `merge-ready` (green)
- [ ] Add state machine rules to AGENTS.md or a dedicated
      `memory/pr-pipeline.md`

Reference:
[AUTOMATED_DEV.md § PR State Machine](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md)

---

## Phase 11: Deployment Pipeline (Optional)

If you want push-to-deploy for your services.

### 11.1 Set up µPaaS (or equivalent)

- [ ] Deploy [µPaaS](https://git.eeqj.de/sneak/upaas) by
      [@sneak](https://sneak.berlin) on your server
- [ ] Configure Traefik (or your reverse proxy) for automatic TLS
- [ ] Create deploy keys (read-only SSH) for each repo

### 11.2 Wire up webhooks

- [ ] Add Gitea webhooks pointing to µPaaS for repos that should auto-deploy
- [ ] Configure which branch triggers deployment (typically `main` or `prod`)
- [ ] Test: merge a PR, verify the service updates automatically

Reference:
[AUTOMATED_DEV.md § Deployment: µPaaS](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md)

---

## Phase 12: Group Chat Rules (If Applicable)

If your agent participates in group chats.

### 12.1 Add group chat behavior

- [ ] Add to AGENTS.md:

```markdown
### Know When to Speak

Respond when: directly mentioned, can add genuine value, correcting
misinformation.

Stay silent when: casual banter, someone already answered, your response would
just be "yeah" or "nice".

Quality > quantity. If you wouldn't send it in a real group chat with friends,
don't send it.
```

### 12.2 Set up per-channel rules

- [ ] Create `memory/CHANNEL_NAME.md` for channels with specific rules
- [ ] Add a reference line to AGENTS.md:
      `**⚠️ #channel → read memory/CHANNEL_NAME.md first**`
- [ ] Define what's shareable and what's private per channel

---

## Verification

After completing the phases relevant to you:

- [ ] Start a new session and verify the agent reads all startup files
- [ ] Ask for a sitrep and verify it covers your configured items
- [ ] Test PII routing: ask for sensitive info in a group channel, verify it
      redirects to DM
- [ ] If using Gitea: create a test issue assigned to the agent, verify it picks
      it up
- [ ] If using git quality gates: push a branch with a formatting error, verify
      CI catches it
- [ ] Verify workspace git repo has recent commits

---

## Reference Documents

- [OPENCLAW_TRICKS.md](https://git.eeqj.de/sneak/clawpub/raw/branch/main/OPENCLAW_TRICKS.md)
  — Configuration recipes, failure stories, detailed schemas
- [AUTOMATED_DEV.md](https://git.eeqj.de/sneak/clawpub/raw/branch/main/AUTOMATED_DEV.md)
  — Git pipeline, CI, deployment, state machine
- [REPO_POLICIES.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
  — Repository structure and tooling standards
- [NEW_REPO_CHECKLIST.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/NEW_REPO_CHECKLIST.md)
  — Step-by-step for new repos
- [EXISTING_REPO_CHECKLIST.md](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/EXISTING_REPO_CHECKLIST.md)
  — Step-by-step for existing repos
- [OpenClaw docs](https://docs.openclaw.ai) — Official documentation
- [OpenClaw GitHub](https://github.com/openclaw/openclaw) — Source code

---

_Start with Phases 1-4 (workspace foundation, daily context, memory, heartbeat).
These give you 80% of the value. Add the remaining phases as your needs grow._