> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Updating

# Updating

WednesdayAI is moving fast before 1.0. Treat updates like shipping
infrastructure: update, run checks, restart, then verify. The `openclaw`
command remains a compatibility alias for the `wednesdayai` binary.

## Recommended: re-run the website installer (upgrade in place)

The **preferred** update path is to re-run the installer from the website. It
detects existing installs, upgrades in place, and runs `wednesdayai doctor` when
needed.

```bash theme={"dark"}
curl -fsSL https://wednesdayai.dev/install.sh | bash
```

Notes:

* Add `--no-onboard` if you don’t want the onboarding wizard to run again.

* For **source installs**, use:

  ```bash theme={"dark"}
  curl -fsSL https://wednesdayai.dev/install.sh | bash -s -- --install-method git --no-onboard
  ```

  The installer will `git pull --rebase` **only** if the repo is clean.

* For **global installs**, the script installs the `wednesdayai` npm package from the stable `latest` dist-tag under the hood. `openclaw` remains a binary alias, not a separate package rail.

* Legacy note: `clawdbot` remains available as a compatibility shim.

## Before you update

* Know how you installed: **global** (npm/pnpm) vs **from source** (git clone).
* Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd).
* Snapshot your tailoring:
  * Config: `~/.openclaw/openclaw.json`
  * Credentials: `~/.openclaw/credentials/`
  * Workspace: `~/.openclaw/workspace`

## Update (global install)

Global install (pick one):

```bash theme={"dark"}
npm i -g wednesdayai@latest
```

```bash theme={"dark"}
pnpm add -g wednesdayai@latest
```

We do **not** recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs).

The supported core npm package is `wednesdayai`. The `openclaw` command remains available as a compatibility alias after install. Release channels map to npm dist-tags for stable package installs: `stable` uses `latest`, and `beta` uses `beta`. The `dev` channel switches to a source checkout so it can rebase and reinstall from `main`.

To switch update channels (git + npm installs):

```bash theme={"dark"}
wednesdayai update --channel beta
wednesdayai update --channel dev
wednesdayai update --channel stable
```

Use `--tag <dist-tag|version>` for a one-off install tag/version.

See [Release channels](https://docs.wednesdayai.dev/next/admin/install/development-channels.md) for channel semantics,
promotion checks, and support expectations. Chat users who only need to know
what an update should look like can start at
[How WednesdayAI updates reach you](https://docs.wednesdayai.dev/next/admin/install/trusted-npm-publishing-user.md).

Note: on npm installs, the gateway logs an update hint on startup (checks the current channel tag). Disable via `update.checkOnStart: false`.

### Core auto-updater (optional)

Auto-updater is **off by default** and is a core Gateway feature (not a plugin).

```json theme={"dark"}
{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}
```

Behavior:

* `stable`: when a new version is seen, WednesdayAI waits `stableDelayHours` and then applies a deterministic per-install jitter in `stableJitterHours` (spread rollout).
* `beta`: checks on `betaCheckIntervalHours` cadence (default: hourly) and applies when an update is available.
* `dev`: no automatic apply; use manual `wednesdayai update`.

Use `wednesdayai update --dry-run` to preview update actions before enabling automation.

Then:

```bash theme={"dark"}
wednesdayai doctor
wednesdayai gateway restart
wednesdayai health
```

Notes:

* If your Gateway runs as a service, `wednesdayai gateway restart` is preferred over killing PIDs.
* If you’re pinned to a specific version, see “Rollback / pinning” below.

## Update (`wednesdayai update`)

For **source installs** (git checkout), prefer:

```bash theme={"dark"}
wednesdayai update
```

It runs a safe-ish update flow:

* Requires a clean worktree.
* Switches to the selected channel (tag or branch).
* Fetches + rebases against the configured upstream (dev channel).
* Installs deps, builds, builds the Control UI, and runs `wednesdayai doctor`.
* Restarts the gateway by default (use `--no-restart` to skip).

If you installed via **npm/pnpm** (no git metadata), `wednesdayai update` will try to update via your package manager. If it can’t detect the install, use “Update (global install)” instead.

## Update (Control UI / RPC)

The Control UI has an **Update** button in **Settings** (RPC: `update.run`). It:

1. Runs the same source-update flow as `wednesdayai update` (git checkout only).
2. Writes a restart sentinel with a structured report (stdout/stderr tail).
3. Restarts the gateway and pings the last active session with the report.

If the rebase fails, the gateway aborts and restarts without applying the update.

## Update (from source)

From the repo checkout:

Preferred:

```bash theme={"dark"}
wednesdayai update
```

Manual (equivalent-ish):

```bash theme={"dark"}
git pull
pnpm install
pnpm build
pnpm control:build:packaged # builds the operator console (Control UI v2)
wednesdayai doctor
wednesdayai health
```

Notes:

* `pnpm build` matters when you run the packaged `wednesdayai` binary or use Node to run `dist/`.
* If you run from a repo checkout without a global install, use `pnpm openclaw ...` or `pnpm wednesdayai ...` for CLI commands.
* If you run directly from TypeScript (`pnpm openclaw ...` or `pnpm wednesdayai ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor.
* Switching between global and git installs is easy: install the other flavor, then run `wednesdayai doctor` so the gateway service entrypoint is rewritten to the current install.

## Always run: `wednesdayai doctor`

Doctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn.

Note: if you’re on a **source install** (git checkout), `wednesdayai doctor` will offer to run `wednesdayai update` first.

Typical things it does:

* Migrate deprecated config keys / legacy config file locations.
* Audit DM policies and warn on risky “open” settings.
* Check Gateway health and can offer to restart.
* Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current WednesdayAI services.
* On Linux, ensure systemd user lingering (so the Gateway survives logout).

Details: [Doctor](https://docs.wednesdayai.dev/next/admin/gateway/doctor.md)

## One-time session actor backfill

On the first gateway start after upgrading to this build, the session store backfills a stored
actor (channel, account, peer kind/id, canonical identity, DM scope) onto existing session rows
from identity columns the gateway already persisted at write time. There is no operator step and
no CLI command: the backfill runs at storage open (Postgres: inside the startup initialization
lease; SQLite: at worker init), pages large stores in batches of 500 rows, skips tombstoned rows,
never overwrites an existing actor, and records completion as the `actor-meta-v1` marker row in
`ctx_schema_backfills` — later starts skip it entirely.

Rows that cannot yield a complete actor (invalid DM scope, or a group row with no group peer)
stay actorless, as do internal buckets that have no external counterpart (cron, subagent, ACP
sessions). An actorless session gets no identity guessed from its session key: no group tool
policy, no per-DM history limit, no `session.sendPolicy` rule that requires `channel` or
`chatType` (prefix rules on the key still match). `wednesdayai sessions` classifies the row's
`kind` from the stored actor (then `chatType`); the Control UI labels the row from the actor,
falling back to the raw key when the actor has no channel. The next inbound message in that
conversation re-establishes identity from the live message and the row is written normally
again.

Source-install operators can verify the result against the live database:

```bash theme={"dark"}
OPENCLAW_DATABASE_URL=postgres://<user>:<password>@<host>/<db> node scripts/verify-context-schema-consumers.mjs
```

On success it prints `verify-context-schema-consumers: PASS`. It fails unless the
`actor-meta-v1` marker exists, no eligible row still lacks an actor, and the sessionKey
identity-parse guard prints `check-no-sessionkey-identity-parse: PASS`
(`pnpm lint:sessions:no-sessionkey-identity-parse` runs the same guard in `pnpm check`).

## Start / stop / restart the Gateway

CLI (works regardless of OS):

```bash theme={"dark"}
wednesdayai gateway status
wednesdayai gateway stop
wednesdayai gateway restart
wednesdayai gateway --port 18789
wednesdayai logs --follow
```

If you’re supervised:

* macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/ai.wednesdayai.gateway` (use `ai.wednesdayai.<profile>`; legacy `ai.openclaw.<profile>`, `com.openclaw.*` still work)
* Linux systemd user service: `systemctl --user restart wednesdayai-gateway[-<profile>].service`
* Windows (WSL2): `systemctl --user restart wednesdayai-gateway[-<profile>].service`
  * `launchctl`/`systemctl` only work if the service is installed; otherwise run `wednesdayai gateway install`.

Runbook + exact service labels: [Gateway runbook](https://docs.wednesdayai.dev/next/admin/gateway.md)

## Rollback / pinning (when something breaks)

### Pin (global install)

Install a known-good version (replace `<version>` with the last working one):

```bash theme={"dark"}
npm i -g wednesdayai@<version>
```

```bash theme={"dark"}
pnpm add -g wednesdayai@<version>
```

Tip: to see the current published version, run `npm view wednesdayai version`.

Then restart + re-run doctor:

```bash theme={"dark"}
wednesdayai doctor
wednesdayai gateway restart
```

### Pin (source) by date

Pick a commit from a date (example: “state of main as of 2026-01-01”):

```bash theme={"dark"}
git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
```

Then reinstall deps + restart:

```bash theme={"dark"}
pnpm install
pnpm build
wednesdayai gateway restart
```

If you want to go back to latest later:

```bash theme={"dark"}
git checkout main
git pull
```

## If you’re stuck

* Run `wednesdayai doctor` again and read the output carefully (it often tells you the fix).
* Check: [Troubleshooting](https://docs.wednesdayai.dev/next/admin/gateway/troubleshooting.md)
* Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.