OpenClaw 2026.8.2 upgrade guide: session visibility, Linux app, and rollback

OpenClaw v2026.8.2, released September 1, 2026, adds an x86-64 Linux desktop companion, background sessions, a docked Home view, safer update recovery, and supported Chrome-extension relay wake-up. It also changes an access default: an unsandboxed session may now work with other sessions owned by the same agent unless you narrow tools.sessions.visibility.[1][2]

Bottom line: back up v2026.8.1, verify both exact npm archives and the Linux assets before execution, and rehearse with isolated state. Shared-agent operators should decide whether the new same-agent default is acceptable rather than inheriting it silently.

If you are still migrating OpenProse or legacy Codex routes, complete the OpenClaw v2026.8.1 upgrade guide first. This guide starts from that exact version and does not rewrite its migration record.

What changed in v2026.8.2

The visible additions are useful: New Session can launch work in the background without replacing the current page, Home can dock beside the page, and the Control UI gains four themes. The Linux companion ships as a .deb and AppImage for x86-64, can connect to local or remote Gateways, and exposes Quick Chat from the tray or an X11 shortcut.[2][3]

The operational changes matter more during an upgrade:

• readable newer configuration is migrated before last-known-good recovery is considered;
• incomplete session migration is supposed to block startup and update success;
• failed updates may restart a stopped managed Gateway only after the selected installed package or rollback is verified usable;
• openclaw update cleanup --dry-run previews retained migration originals before removal.[2][5]

Cleanup is not housekeeping to run automatically. Removing eligible originals permanently gives up rollback to them even though current SQLite history remains. Keep a separately verified full backup until the upgraded service has passed its observation window.[2][5]

The session-visibility default is broader

The exact property is tools.sessions.visibility. In v2026.8.2, the documented unsandboxed default is same-agent visibility: one session can work with other sessions belonging to the same agent, including retained cron sessions. Cross-agent restrictions remain, and sandboxed sessions retain their separate restriction.[1][2]

Use an explicit setting when one agent serves people or workloads that should not browse one another’s sessions:

{
  "tools": {
    "sessions": {
      "visibility": "tree"
    }
  }
}

tree narrows access to the current session tree. self is narrower again and limits session tools to the current session. Neither value turns a shared process into hostile-tenant isolation; OpenClaw still runs with the filesystem, network, process, plugin, and tool permissions granted to it.

The reproducible upgrade packet imported the policy module from the checksum-verified openclaw@2026.8.2 package. Its assertions observed agent as the unsandboxed default, allowed a same-agent sibling, denied a cross-agent target, denied an unrelated sibling under tree, allowed a spawned child under tree, and denied both sibling and spawned-child targets under self. The tested sandbox default clamped effective visibility to tree.

That is a policy-module test with synthetic session rows, not a live multi-user account test. It avoids real sessions and credentials while exercising the shipped decision code.

Exact artifacts and Linux package inspection

The packet recorded provenance before running either CLI:

Artifact	Observed SHA-256
npm openclaw@2026.8.1	43c4b1f81afcd50244c85bcb5686fa6e39f0da6a5941735811b58064b7e0ca10
npm openclaw@2026.8.2	20e9c2f16742dfcebfb21504e51067d31e000a19577126ff4fab117e5e87dbe2
OpenClaw-2026.8.2-amd64.deb	6021ac38b398fc3b4c1364f72fb83a5d89e2d6c20ed6bbe6d3ceed0cddbeaa85
OpenClaw-2026.8.2-amd64.AppImage	4501dcfd1d5c30dc0eb8c25829be7f1f5fc4a177895ec7c0c404a20e2eec7f6a

The npm integrity values were also retained, and the locally calculated Linux hashes matched both GitHub’s release-asset digests and SHA256SUMS.linux-app.txt.[6][7][8]

dpkg-deb reported package open-claw, version 2026.8.2, architecture amd64, with the desktop binary, CLI installer, icons, and desktop entry. readelf plus unsquashfs identified the AppImage as an x86-64 ELF runtime with a zstd-compressed SquashFS payload containing the companion and bundled media/UI libraries. Neither package was installed system-wide.

The release metadata includes a Tauri update signature for the AppImage, and the release notes state that AppImage updates are signature-verified while .deb lifecycle remains with the package manager.[2][3] The packet did not independently validate that signature against a separately obtained public key. Matching hashes prove which bytes were inspected; they do not prove those bytes are safe.

Disposable configuration and Gateway evidence

The rehearsal generated a valid config with exact v2026.8.1, loopback Gateway binding, and an explicit tools.sessions.visibility: tree. It used fresh HOME, OPENCLAW_HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, and OPENCLAW_WORKSPACE_DIR paths under /tmp. No token, provider key, channel, remote device, browser profile, or real user state was supplied.

The baseline configuration SHA-256 was cf9eeb635d3171213311a42b0ab5a7e4321b4bf54756a6beec7a532cc1ee0db3. Exact v2026.8.2 validated the same file, retained the explicit visibility setting, and left the file byte-identical. A deliberately malformed config returned exit code 1 rather than a false success.

The exact v2026.8.2 Gateway then started on 127.0.0.1:18882 with channels disabled. /readyz returned ready: true with no failing checks, and shutdown completed cleanly. The CLI’s authenticated health RPC correctly did not pass because the fixture had no token, password, or paired device credential.

This proves loopback HTTP readiness for the fixture. It does not prove managed-service recovery after a failed package swap, an actual session-database migration, channel recovery, authenticated health, or production readiness. Those gates remain explicitly unmeasured.

Browser relay wake-up is not a permission shortcut

Supported macOS and Linux extension builds can wake a paired standalone direct-loopback relay without a running local Gateway. The documented path requires the updated native host, a build with relay wake-up support, an exact 127.0.0.1 pairing, and authenticated connection-bound proofs. Remote Gateway routes do not trigger local daemon wake-up.[2][4]

This release changes availability, not browser trust. The extension can automate eligible tabs through Chrome’s debugger interface. Use a separate browser profile for automation, review which tabs are allowed, and do not treat “Gateway not running” as “browser control unavailable.” The packet did not launch Chrome or test the relay because doing so would touch a real browser profile; relay behavior remains vendor-documented rather than independently observed.

Reversible v2026.8.1 to v2026.8.2 procedure

1. Record exact v2026.8.1 CLI output, install method, state/config paths, Gateway service owner, plugins, channels, session store, and current health evidence.
2. Create a verified full backup. Automatic config copies and migration originals are not full-state backups.[5]
3. Download exact v2026.8.1 and v2026.8.2 artifacts. Record registry integrity, release digest, and calculated SHA-256 before execution.
4. Clone the backup into fresh isolated paths. Disable channels, provider calls, remote devices, automatic updates, and browser integration.
5. Decide whether the same-agent default is acceptable. Set tools.sessions.visibility explicitly to tree or self if narrower access is required.
6. Validate config with exact v2026.8.1, hash it, then validate with exact v2026.8.2. Stop if newer valid settings disappear or a migration reports success while startup remains blocked.
7. Start only a loopback Gateway. Check /readyz, then authenticated health only if the disposable fixture has a disposable credential. Do not weaken a real Gateway to imitate this test.
8. Inspect config, session inventory, scheduled jobs, plugins, and logs. Keep every real secret out of transcripts and diffs.
9. Roll back by selecting exact v2026.8.1 and restoring the verified baseline into a fresh target. If older code cannot read a newer database, stop and restore the full pre-update snapshot instead of repeatedly running repair commands.[5]
10. Verify version, config checksum, session inventory, and Gateway health before reconnecting anything.

In the packet, exact v2026.8.1 validated the restored fixture and reproduced the baseline checksum. A post-rollback Gateway was not started, so the rollback claim is limited to package reselection plus byte-identical config restoration.

Security boundary

Project trust and sandboxing are different controls. Unsandboxed OpenClaw executes with the operating-system identity and tool/plugin capabilities granted to its process. Session visibility controls which sessions the session tools may address; it does not remove filesystem, network, process, credential-store, plugin, or browser authority.

For shared or sensitive deployments, use separate agents for separate trust domains, explicit tools.sessions.visibility, least-privilege process accounts, reviewed plugins, restricted browser profiles, loopback binding where possible, and tested backups. Stop the upgrade if isolation cannot be demonstrated without production state or real credentials.

Sources

[1] OpenClaw v2026.8.2 GitHub release — https://github.com/openclaw/openclaw/releases/tag/v2026.8.2 [2] OpenClaw v2026.8.2 release notes — https://docs.openclaw.ai/releases/2026.8.2 [3] OpenClaw Linux desktop guide — https://docs.openclaw.ai/platforms/linux [4] OpenClaw Chrome extension guide — https://docs.openclaw.ai/tools/chrome-extension [5] OpenClaw updating and rollback guide — https://docs.openclaw.ai/install/updating [6] OpenClaw v2026.8.2 release API — https://api.github.com/repos/openclaw/openclaw/releases/tags/v2026.8.2 [7] openclaw 2026.8.1 npm registry metadata — https://registry.npmjs.org/openclaw/2026.8.1 [8] openclaw 2026.8.2 npm registry metadata — https://registry.npmjs.org/openclaw/2026.8.2

Put this to work

Separate exact artifact identity, vendor-documented behavior, and behavior observed in a disposable fixture.

Try

Clone a verified v2026.8.1 backup into isolated paths, disable channels, and test exact v2026.8.2 before changing a managed service.

Prove it worked

Record checksums, config hashes, visibility assertions, loopback readiness, and an exact v2026.8.1 restore.

Where it can pay

A reversible upgrade with explicit access policy is more valuable than a feature-only release summary.

Keep in view

• The release adds Linux .deb and AppImage packages, background sessions, a docked Home agent, and browser-relay wake-up.
• Unsandboxed sessions can see other sessions of the same agent by default; tree and self are the documented narrower settings.
• Update recovery is safer, but cleanup can permanently remove rollback originals and still requires a verified full backup.

Learn the workflow: comparing OpenClaw with other agent platforms →