mirror of https://github.com/openclaw/openclaw.git synced 2026-05-18 18:54:48 +00:00

Files

Peter Steinberger f91de52f0d refactor: move runtime state to SQLite

* refactor: remove stale file-backed shims

* fix: harden sqlite state ci boundaries

* refactor: store matrix idb snapshots in sqlite

* fix: satisfy rebased CI guardrails

* refactor: store current conversation bindings in sqlite table

* refactor: store tui last sessions in sqlite table

* refactor: reset sqlite schema history

* refactor: drop unshipped sqlite table migration

* refactor: remove plugin index file rollback

* refactor: drop unshipped sqlite sidecar migrations

* refactor: remove runtime commitments kv migration

* refactor: preserve kysely sync result types

* refactor: drop unshipped sqlite schema migration table

* test: keep session usage coverage sqlite-backed

* refactor: keep sqlite migration doctor-only

* refactor: isolate device legacy imports

* refactor: isolate push voicewake legacy imports

* refactor: isolate remaining runtime legacy imports

* refactor: tighten sqlite migration guardrails

* test: cover sqlite persisted enum parsing

* refactor: isolate legacy update and tui imports

* refactor: tighten sqlite state ownership

* refactor: move legacy imports behind doctor

* refactor: remove legacy session row lookup

* refactor: canonicalize memory transcript locators

* refactor: drop transcript path scope fallbacks

* refactor: drop runtime legacy session delivery pruning

* refactor: store tts prefs only in sqlite

* refactor: remove cron store path runtime

* refactor: use cron sqlite store keys

* refactor: rename telegram message cache scope

* refactor: read memory dreaming status from sqlite

* refactor: rename cron status store key

* refactor: stop remembering transcript file paths

* test: use sqlite locators in agent fixtures

* refactor: remove file-shaped commitments and cron store surfaces

* refactor: keep compaction transcript handles out of session rows

* refactor: derive transcript handles from session identity

* refactor: derive runtime transcript handles

* refactor: remove gateway session locator reads

* refactor: remove transcript locator from session rows

* refactor: store raw stream diagnostics in sqlite

* refactor: remove file-shaped transcript rotation

* refactor: hide legacy trajectory paths from runtime

* refactor: remove runtime transcript file bridges

* refactor: repair database-first rebase fallout

* refactor: align tests with database-first state

* refactor: remove transcript file handoffs

* refactor: sync post-compaction memory by transcript scope

* refactor: run codex app-server sessions by id

* refactor: bind codex runtime state by session id

* refactor: pass memory transcripts by sqlite scope

* refactor: remove transcript locator cleanup leftovers

* test: remove stale transcript file fixtures

* refactor: remove transcript locator test helper

* test: make cron sqlite keys explicit

* test: remove cron runtime store paths

* test: remove stale session file fixtures

* test: use sqlite cron keys in diagnostics

* refactor: remove runtime delivery queue backfill

* test: drop fake export session file mocks

* refactor: rename acp session read failure flag

* refactor: rename acp row session key

* refactor: remove session store test seams

* refactor: move legacy session parser tests to doctor

* refactor: reindex managed memory in place

* refactor: drop stale session store wording

* refactor: rename session row helpers

* refactor: rename sqlite session entry modules

* refactor: remove transcript locator leftovers

* refactor: trim file-era audit wording

* refactor: clean managed media through sqlite

* fix: prefer explicit agent for exports

* fix: use prepared agent for session resets

* fix: canonicalize legacy codex binding import

* test: rename state cleanup helper

* docs: align backup docs with sqlite state

* refactor: drop legacy Pi usage auth fallback

* refactor: move legacy auth profile imports to doctor

* refactor: keep Pi model discovery auth in memory

* refactor: remove MSTeams legacy learning key fallback

* refactor: store model catalog config in sqlite

* refactor: use sqlite model catalog at runtime

* refactor: remove model json compatibility aliases

* refactor: store auth profiles in sqlite

* refactor: seed copied auth profiles in sqlite

* refactor: make auth profile runtime sqlite-addressed

* refactor: migrate hermes secrets into sqlite auth store

* refactor: move plugin install config migration to doctor

* refactor: rename plugin index audit checks

* test: drop auth file assumptions

* test: remove legacy transcript file assertions

* refactor: drop legacy cli session aliases

* refactor: store skill uploads in sqlite

* refactor: keep subagent attachments in sqlite vfs

* refactor: drop subagent attachment cleanup state

* refactor: move legacy session aliases to doctor

* refactor: require node 24 for sqlite state runtime

* refactor: move provider caches into sqlite state

* fix: harden virtual agent filesystem

* refactor: enforce database-first runtime state

* refactor: rename compaction transcript rotation setting

* test: clean sqlite refactor test types

* refactor: consolidate sqlite runtime state

* refactor: model session conversations in sqlite

* refactor: stop deriving cron delivery from session keys

* refactor: stop classifying sessions from key shape

* refactor: hydrate announce targets from typed delivery

* refactor: route heartbeat delivery from typed sqlite context

* refactor: tighten typed sqlite session routing

* refactor: remove session origin routing shadow

* refactor: drop session origin shadow fixtures

* perf: query sqlite vfs paths by prefix

* refactor: use typed conversation metadata for sessions

* refactor: prefer typed session routing metadata

* refactor: require typed session routing metadata

* refactor: resolve group tool policy from typed sessions

* refactor: delete dead session thread info bridge

* Show Codex subscription reset times in channel errors (#80456)

* feat(plugin-sdk): consolidate session workflow APIs

* fix(agents): allow read-only agent mount reads

* [codex] refresh plugin regression fixtures

* fix(agents): restore compaction gateway logs

* test: tighten gateway startup assertions

* Redact persisted secret-shaped payloads [AI] (#79006)

* test: tighten device pair notify assertions

* test: tighten hermes secret assertions

* test: assert matrix client error shapes

* test: assert config compat warnings

* fix(heartbeat): remap cron-run exec events to session keys (#80214)

* fix(codex): route btw through native side threads

* fix(auth): accept friendly OpenAI order for Codex profiles

* fix(codex): rotate auth profiles inside harness

* fix: keep browser status page probe within timeout

* test: assert agents add outputs

* test: pin cron read status

* fix(agents): avoid Pi resource discovery stalls

Co-authored-by: dataCenter430 <titan032000@gmail.com>

* fix: retire timed-out codex app-server clients

* test: tighten qa lab runtime assertions

* test: check security fix outputs

* test: verify extension runtime messages

* feat(wake): expose typed sessionKey on wake protocol + system event CLI

* fix(gateway): await session_end during shutdown drain and track channel + compaction lifecycle paths (#57790)

* test: guard talk consult call helper

* fix(codex): scale context engine projection (#80761)

* fix(codex): scale context engine projection

* fix: document Codex context projection scaling

* fix: document Codex context projection scaling

* fix: document Codex context projection scaling

* fix: document Codex context projection scaling

* chore: align Codex projection changelog

* chore: realign Codex projection changelog

* fix: isolate Codex projection patch

---------

Co-authored-by: Eva (agent) <eva+agent-78055@100yen.org>
Co-authored-by: Josh Lehman <josh@martian.engineering>

* refactor: move agent runtime state toward piless

* refactor: remove cron session reaper

* refactor: move session management to sqlite

* refactor: finish database-first state migration

* chore: refresh generated sqlite db types

* refactor: remove stale file-backed shims

* test: harden kysely type coverage

# Conflicts:
#	.agents/skills/kysely-database-access/SKILL.md
#	src/infra/kysely-sync.types.test.ts
#	src/proxy-capture/store.sqlite.test.ts
#	src/state/openclaw-agent-db.test.ts
#	src/state/openclaw-state-db.test.ts

* refactor: remove cron store path runtime

* refactor: keep compaction transcript handles out of session rows

* refactor: derive embedded transcripts from sqlite identity

* refactor: remove embedded transcript locator handoff

* refactor: remove runtime transcript file bridges

* refactor: remove transcript file handoffs

* refactor: remove MSTeams legacy learning key fallback

* refactor: store model catalog config in sqlite

* refactor: use sqlite model catalog at runtime

# Conflicts:
#	docs/cli/secrets.md
#	docs/gateway/authentication.md
#	docs/gateway/secrets.md

* fix: keep oauth sibling sync sqlite-local

# Conflicts:
#	src/commands/onboard-auth.test.ts

* refactor: remove task session store maintenance

# Conflicts:
#	src/commands/tasks.ts

* refactor: keep diagnostics in state sqlite

* refactor: enforce database-first runtime state

* refactor: consolidate sqlite runtime state

* Show Codex subscription reset times in channel errors (#80456)

* fix(codex): refresh subscription limit resets

* fix(codex): format reset times for channels

* Update CHANGELOG with latest changes and fixes

Updated CHANGELOG with recent fixes and improvements.

* fix(codex): keep command load failures on codex surface

* fix(codex): format account rate limits as rows

* fix(codex): summarize account limits as usage status

* fix(codex): simplify account limit status

* test: tighten subagent announce queue assertion

* test: tighten session delete lifecycle assertions

* test: tighten cron ops assertions

* fix: track cron execution milestones

* test: tighten hermes secret assertions

* test: assert matrix sync store payloads

* test: assert config compat warnings

* fix(codex): align btw side thread semantics

* fix(codex): honor codex fallback blocking

* fix(agents): avoid Pi resource discovery stalls

* test: tighten codex event assertions

* test: tighten cron assertions

* Fix Codex app-server OAuth harness auth

* refactor: move agent runtime state toward piless

* refactor: move device and push state to sqlite

* refactor: move runtime json state imports to doctor

* refactor: finish database-first state migration

* chore: refresh generated sqlite db types

* refactor: clarify cron sqlite store keys

* refactor: remove stale file-backed shims

* refactor: bind codex runtime state by session id

* test: expect sqlite trajectory branch export

* refactor: rename session row helpers

* fix: keep legacy device identity import in doctor

* refactor: enforce database-first runtime state

* refactor: consolidate sqlite runtime state

* build: align pi contract wrappers

* chore: repair database-first rebase

* refactor: remove session file test contracts

* test: update gateway session expectations

* refactor: stop routing from session compatibility shadows

* refactor: stop persisting session route shadows

* refactor: use typed delivery context in clients

* refactor: stop echoing session route shadows

* refactor: repair embedded runner rebase imports

# Conflicts:
#	src/agents/pi-embedded-runner/run/attempt.tool-call-argument-repair.ts

* refactor: align pi contract imports

* refactor: satisfy kysely sync helper guard

* refactor: remove file transcript bridge remnants

* refactor: remove session locator compatibility

* refactor: remove session file test contracts

* refactor: keep rebase database-first clean

* refactor: remove session file assumptions from e2e

* docs: clarify database-first goal state

* test: remove legacy store markers from sqlite runtime tests

* refactor: remove legacy store assumptions from runtime seams

* refactor: align sqlite runtime helper seams

* test: update memory recall sqlite audit mock

* refactor: align database-first runtime type seams

* test: clarify doctor cron legacy store names

* fix: preserve sqlite session route projections

* test: fix copilot token cache test syntax

* docs: update database-first proof status

* test: align database-first test fixtures

* docs: update database-first proof status

* refactor: clean extension database-first drift

* test: align agent session route proof

* test: clarify doctor legacy path fixtures

* chore: clean database-first changed checks

* chore: repair database-first rebase markers

* build: allow baileys git subdependency

* chore: repair exp-vfs rebase drift

* chore: finish exp-vfs rebase cleanup

* chore: satisfy rebase lint drift

* chore: fix qqbot rebase type seam

* chore: fix rebase drift leftovers

* fix: keep auth profile oauth secrets out of sqlite

* fix: repair rebase drift tests

* test: stabilize pairing request ordering

* test: use source manifests in plugin contract checks

* fix: restore gateway session metadata after rebase

* fix: repair database-first rebase drift

* fix: clean up database-first rebase fallout

* test: stabilize line quick reply receipt time

* fix: repair extension rebase drift

* test: keep transcript redaction tests sqlite-backed

* fix: carry injected transcript redaction through sqlite

* chore: clean database branch rebase residue

* fix: repair database branch CI drift

* fix: repair database branch CI guard drift

* fix: stabilize oauth tls preflight test

* test: align database branch fast guards

* test: repair build artifact boundary guards

* chore: clean changelog rebase markers

---------

Co-authored-by: pashpashpash <nik@vault77.ai>
Co-authored-by: Eva <eva@100yen.org>
Co-authored-by: stainlu <stainlu@newtype-ai.org>
Co-authored-by: Jason Zhou <jason.zhou.design@gmail.com>
Co-authored-by: Ruben Cuevas <hi@rubencu.com>
Co-authored-by: Pavan Kumar Gondhi <pavangondhi@gmail.com>
Co-authored-by: Shakker <shakkerdroid@gmail.com>
Co-authored-by: Kaspre <36520309+Kaspre@users.noreply.github.com>
Co-authored-by: dataCenter430 <titan032000@gmail.com>
Co-authored-by: Kaspre <kaspre@gmail.com>
Co-authored-by: pandadev66 <nova.full.stack@outlook.com>
Co-authored-by: Eva <admin@100yen.org>
Co-authored-by: Eva (agent) <eva+agent-78055@100yen.org>
Co-authored-by: Josh Lehman <josh@martian.engineering>
Co-authored-by: jeffjhunter <support@aipersonamethod.com>

2026-05-13 13:15:12 +01:00

clawdock-helpers.sh

[ClawDock] Iteration on the first submission; bug fixes, UX improvements, etc (#23912 )

2026-03-29 20:05:41 -04:00

README.md

refactor: move runtime state to SQLite

2026-05-13 13:15:12 +01:00

README.md

ClawDock

Stop typing docker-compose commands. Just type clawdock-start.

Inspired by Simon Willison's Running OpenClaw in Docker.

Quickstart
Available Commands
Configuration & Secrets
Common Workflows
Requirements
Development

Quickstart

Install:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

Canonical docs page: https://docs.openclaw.ai/install/clawdock

If you previously installed ClawDock from scripts/shell-helpers/clawdock-helpers.sh, rerun the install command above. The old raw GitHub path has been removed.

See what you get:

clawdock-help

On first command, ClawDock auto-detects your OpenClaw directory:

Checks common paths (~/openclaw, ~/workspace/openclaw, etc.)
If found, asks you to confirm
Saves to ~/.clawdock/config

First time setup:

clawdock-start

clawdock-fix-token

clawdock-dashboard

If you see "pairing required":

clawdock-devices

And approve the request for the specific device:

clawdock-approve <request-id>

Available Commands

Basic Operations

Command	Description
`clawdock-start`	Start the gateway
`clawdock-stop`	Stop the gateway
`clawdock-restart`	Restart the gateway
`clawdock-status`	Check container status
`clawdock-logs`	View live logs (follows output)

Container Access

Command	Description
`clawdock-shell`	Interactive shell inside the gateway container
`clawdock-cli <command>`	Run OpenClaw CLI commands
`clawdock-exec <command>`	Execute arbitrary commands in the container

Web UI & Devices

Command	Description
`clawdock-dashboard`	Open web UI in browser with authentication
`clawdock-devices`	List device pairing requests
`clawdock-approve <id>`	Approve a device pairing request

Setup & Configuration

Command	Description
`clawdock-fix-token`	Configure gateway authentication token (run once)

Maintenance

Command	Description
`clawdock-update`	Pull latest, rebuild image, and restart (one command)
`clawdock-rebuild`	Rebuild the Docker image only
`clawdock-clean`	Remove all containers and volumes (destructive!)

Utilities

Command	Description
`clawdock-health`	Run gateway health check
`clawdock-token`	Display the gateway authentication token
`clawdock-cd`	Jump to the OpenClaw project directory
`clawdock-config`	Open the OpenClaw config directory
`clawdock-show-config`	Print config files with redacted values
`clawdock-workspace`	Open the workspace directory
`clawdock-help`	Show all available commands with examples

Configuration & Secrets

The Docker setup uses three config files on the host. The container never stores secrets — everything is bind-mounted from local files.

Docker Files

File	Purpose
`Dockerfile`	Builds the `openclaw:local` image (Node 24, pnpm, non-root `node` user)
`docker-compose.yml`	Defines `openclaw-gateway` and `openclaw-cli` services, bind-mounts, ports
`scripts/docker/setup.sh`	First-time setup — builds image, creates `.env` from `.env.example`
`.env.example`	Template for `<project>/.env` with all supported vars and docs
`docker-compose.extra.yml`	Optional overrides — auto-loaded by ClawDock helpers if present

Config Files

File	Purpose	Examples
`<project>/.env`	Docker infra — image, ports, gateway token	`OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_IMAGE`, `OPENCLAW_GATEWAY_PORT`, `OPENCLAW_AUTH_PROFILE_SECRET_DIR`
`~/.openclaw/.env`	Secrets — API keys and bot tokens	`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `TELEGRAM_BOT_TOKEN`
`~/.openclaw/openclaw.json`	Behavior config — models, channels, policies	Model selection, WhatsApp allowlists, agent settings

Do NOT put API keys or bot tokens in openclaw.json. Use ~/.openclaw/.env for all secrets.

Initial Setup

./scripts/docker/setup.sh handles first-time Docker configuration:

Builds the openclaw:local image from Dockerfile
Creates <project>/.env from .env.example with a generated gateway token
Creates the auth-profile secret key directory
Sets up ~/.openclaw directories if they don't exist

./scripts/docker/setup.sh

After setup, add your API keys:

vim ~/.openclaw/.env

See .env.example for all supported keys.

The Dockerfile supports two optional build args:

OPENCLAW_DOCKER_APT_PACKAGES — extra apt packages to install (e.g. ffmpeg)
OPENCLAW_INSTALL_BROWSER=1 — pre-install Chromium for browser automation (adds ~300MB, but skips the 60-90s Playwright install on each container start)

How It Works in Docker

docker-compose.yml bind-mounts both config and workspace from the host:

volumes:
  - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
  - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
  - ${OPENCLAW_AUTH_PROFILE_SECRET_DIR}:/home/node/.config/openclaw

This means:

~/.openclaw/.env is available inside the container at /home/node/.openclaw/.env — OpenClaw loads it automatically as the global env fallback
~/.openclaw/openclaw.json is available at /home/node/.openclaw/openclaw.json — the gateway watches it and hot-reloads most changes
~/.openclaw-auth-profile-secrets is available at /home/node/.config/openclaw — OpenClaw stores the auth-profile encryption key there
Downloadable plugin packages and install records live under the mounted OpenClaw home
No need to add API keys to docker-compose.yml or configure anything inside the container
Keys survive clawdock-update, clawdock-rebuild, and clawdock-clean because they live on the host

The project .env feeds Docker Compose directly (gateway token, image name, ports). The ~/.openclaw/.env feeds the OpenClaw process inside the container.

Example `~/.openclaw/.env`

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=123456:ABCDEF...

Example `<project>/.env`

OPENCLAW_CONFIG_DIR=/Users/you/.openclaw
OPENCLAW_WORKSPACE_DIR=/Users/you/.openclaw/workspace
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_BRIDGE_PORT=18790
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_TOKEN=<generated-by-docker-setup>
OPENCLAW_AUTH_PROFILE_SECRET_DIR=/Users/you/.openclaw-auth-profile-secrets
OPENCLAW_IMAGE=openclaw:local

Env Precedence

OpenClaw loads env vars in this order (highest wins, never overrides existing):

Process environment — docker-compose.yml environment: block (gateway token, session keys)
.env in CWD — project root .env (Docker infra vars)
~/.openclaw/.env — global secrets (API keys, bot tokens)
openclaw.json env block — inline vars, applied only if still missing
Shell env import — optional login-shell scrape (OPENCLAW_LOAD_SHELL_ENV=1)

Common Workflows

Update OpenClaw

Important: openclaw update does not work inside Docker. The container runs as a non-root user with a source-built image, so npm i -g fails with EACCES. Use clawdock-update instead — it pulls, rebuilds, and restarts from the host.

clawdock-update

This runs git pull → docker compose build → docker compose down/up in one step.

If you only want to rebuild without pulling:

clawdock-rebuild && clawdock-stop && clawdock-start

Check Status and Logs

Restart the gateway:

clawdock-restart

Check container status:

clawdock-status

View live logs:

clawdock-logs

Set Up WhatsApp Bot

Shell into the container:

clawdock-shell

Inside the container, login to WhatsApp:

openclaw channels login --channel whatsapp --verbose

Scan the QR code with WhatsApp on your phone.

Verify connection:

openclaw status

Troubleshooting Device Pairing

Check for pending pairing requests:

clawdock-devices

Copy the Request ID from the "Pending" table, then approve:

clawdock-approve <request-id>

Then refresh your browser.

Fix Token Mismatch Issues

If you see "gateway token mismatch" errors:

clawdock-fix-token

This will:

Read the token from your .env file
Configure it in the OpenClaw config
Restart the gateway
Verify the configuration

Permission Denied

Ensure Docker is running and you have permission:

docker ps

Requirements

Docker and Docker Compose installed
Bash or Zsh shell
OpenClaw project (run scripts/docker/setup.sh)

Development

Test with fresh config (mimics first-time install):

unset CLAWDOCK_DIR && rm -f ~/.clawdock/config && source scripts/clawdock/clawdock-helpers.sh

Then run any command to trigger auto-detect:

clawdock-start

README.md

ClawDock

Quickstart

Available Commands

Basic Operations

Container Access

Web UI & Devices

Setup & Configuration

Maintenance

Utilities

Configuration & Secrets

Docker Files

Config Files

Initial Setup

How It Works in Docker

Example ~/.openclaw/.env

Example <project>/.env

Env Precedence

Common Workflows

Update OpenClaw

Check Status and Logs

Set Up WhatsApp Bot

Troubleshooting Device Pairing

Fix Token Mismatch Issues

Permission Denied

Requirements

Development

Example `~/.openclaw/.env`

Example `<project>/.env`