OpenClaw Uninstall Guide

intent

safely uninstall OpenClaw without paid cleanup services. use this skill when a user asks to remove openclaw, wants complete system cleanup, or questions whether paid uninstall services are necessary. provides free, executable steps backed by official docs and verification scripts. works across macOS, Linux, WSL2, and supports both automated IM-triggered uninstall and manual CLI removal.

inputs

external connections / prerequisites:

• openclaw gateway service (running on host machine for method 1)
• npm or pnpm or bun (for CLI-based uninstall, method 3)
• bash shell (macOS, Linux, WSL2 only; native Windows not supported)
• optional: ntfy instance or email server (for async notifications after uninstall completes)

environment setup:

• OPENCLAW_STATE_DIR: optional env var; defaults to $HOME/.openclaw if unset
• host=gateway: required parameter when calling schedule-uninstall.sh via agent exec (not host=sandbox)
• for headless linux: user must have run loginctl enable-linger $USER once
• for WSL2: systemd-run optional (script falls back to nohup if absent)

external docs:

• openclaw official uninstall docs
• security and threat model

procedure

method 1: IM-initiated uninstall (recommended for non-technical users)

step 1: user initiates request

• input: user sends message "uninstall" or "how do i uninstall openclaw" via whatsapp, telegram, slack, or other IM
• output: agent receives intent signal

step 2: agent requests confirmation

• input: agent has uninstall intent from step 1
• output: agent replies "confirm complete uninstall of openclaw? this action is irreversible. reply 'confirm' to continue."

step 3: user confirms

• input: user replies "confirm" (or equivalent affirmative)
• output: agent proceeds to step 4

step 4: agent optionally requests notification preference

• input: agent awaiting user notification preference
• output: agent asks "notify when done? reply 'email user@example.com' or 'ntfy my-topic' or 'no'"
• note: this step may be skipped if notification is not relevant to user's context

step 5: agent executes uninstall script

• input: user notification preference (email, ntfy topic, or none), script path <workspace>/skills/openclaw-uninstall/scripts/schedule-uninstall.sh, host=gateway parameter set in exec call
• output: script writes one-shot job to host cron or systemd, agent replies "uninstall scheduled. session will disconnect in ~15 seconds. results written to /tmp/openclaw-uninstall.log"
• command examples:
  • no notification: ./scripts/schedule-uninstall.sh (with host=gateway)
  • email notify: ./scripts/schedule-uninstall.sh --notify-email "user@example.com" (with host=gateway)
  • ntfy notify: ./scripts/schedule-uninstall.sh --notify-ntfy "my-uninstall-topic" (with host=gateway)

step 6: agent gracefully disconnects

• input: uninstall job scheduled
• output: gateway stops; uninstall runs as background process (~15 seconds later)

step 7: user verifies results (optional)

• input: gateway has stopped or user regains access to host
• output: user runs cat /tmp/openclaw-uninstall.log to see uninstall transcript; if gateway on remote vps, user SSHes in first

method 2: verify residue (read-only check, agent or user can run)

step 1: agent or user runs verify script

• input: script path <workspace>/skills/openclaw-uninstall/scripts/verify-clean.sh
• output: script scans system for openclaw remnants (processes, config dirs, service files, app bundles) and reports findings without deleting anything
• use case: user asks "is it clean?" or "check for residue" after uninstall, or to audit before uninstall

method 3: manual uninstall (for users with CLI access or when method 1 unavailable)

step 1 (option a): one-shot command

• input: openclaw CLI available in PATH, user terminal access
• output: openclaw uninstall --all --yes --non-interactive executes full uninstall
• fallback: npx -y openclaw uninstall --all --yes --non-interactive if global install unavailable

step 1 (option b): step-by-step manual removal

• step 1a: stop gateway. input: user terminal. command: openclaw gateway stop. output: gateway service stops.
• step 1b: uninstall gateway service. input: gateway stopped. command: openclaw gateway uninstall. output: service removed from launchd or systemd.
• step 1c: delete state directory. input: service uninstalled. command: rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}". output: all openclaw config, cache, and state erased.
• step 1d: uninstall CLI package. input: state deleted. command: npm rm -g openclaw (or pnpm or bun equivalent). output: global openclaw binary removed.
• step 1e (macOS only): remove app bundle. input: CLI uninstalled. command: rm -rf /Applications/OpenClaw.app. output: macOS app removed.

step 2 (if CLI already removed): manual service cleanup

• for macOS: input: no CLI but launchd service still active. commands:
  • launchctl bootout gui/$UID/ai.openclaw.gateway
  • rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist
  • output: launchd service and plist removed.
• for linux: input: no CLI but systemd service still active. commands:
  • systemctl --user disable --now openclaw-gateway.service
  • rm -f ~/.config/systemd/user/openclaw-gateway.service
  • systemctl --user daemon-reload
  • output: systemd service disabled and removed.

decision points

if user initiates via IM and agent supports method 1:

• run IM-initiated uninstall (method 1) with host=gateway parameter. this is preferred because it's async and does not block the gateway.

else if user does not want to disconnect gateway or method 1 failed (sandbox error, permission denied, no host access):

• offer method 3 manual uninstall. user must have CLI or SSH access to the gateway host. run ./scripts/schedule-uninstall.sh or ./scripts/uninstall-oneshot.sh manually on the host.

if user asks to check for uninstall residue:

• run method 2 verify script (./scripts/verify-clean.sh). this is read-only and safe to run anytime.

if user has multiple openclaw profiles (e.g., ~/.openclaw-dev, ~/.openclaw-prod):

• each profile has its own state directory. remove each separately via method 3 step 1c (adjust path) or method 1 with profile flag if supported.

if openclaw installed from source (git repo) instead of npm:

• uninstall the gateway service first (method 3 step 1b), then delete the git repo directory. do not use npm rm -g since the CLI was never installed globally.

if gateway is on remote VPS and method 1 fails:

• SSH to gateway host and run ./scripts/schedule-uninstall.sh or ./scripts/uninstall-oneshot.sh directly on the host machine.

if gateway is running on headless linux:

• run loginctl enable-linger $USER once before method 1 to allow background jobs to persist after logout.

if gateway is running on WSL2 and systemd-run unavailable:

• script automatically falls back to nohup. proceed with method 1 or 3 as normal.

if native Windows (not WSL2):

• openclaw gateway not supported natively. method 1 and 3 do not apply. direct user to official docs or manual removal of any installed npm packages. WSL2 recommended for full uninstall.

output contract

method 1 (IM-initiated):

• log file location: /tmp/openclaw-uninstall.log
• log format: plain text transcript of uninstall steps executed, exit codes, and errors (if any)
• success indicator: log contains "uninstall complete" or equivalent, exit code 0
• notification delivery: if user requested email or ntfy, notification sent to specified address or topic within 5 minutes after uninstall completes
• gateway status: gateway service no longer running; openclaw gateway status returns error or "not running"

method 2 (verify residue):

• output format: plain text list of residual files, directories, processes, or services found
• success indicator: script exits with 0 if no residue found, exits with 1 if residue detected
• file location: output printed to stdout (can be redirected to file)
• destructiveness: none (read-only)

method 3 (manual uninstall):

• CLI output: openclaw uninstall command prints "uninstall complete" or similar message to stdout
• state directory: ~/.openclaw (or custom $OPENCLAW_STATE_DIR) no longer exists
• launchd/systemd: service no longer listed in launchctl list (macOS) or systemctl --user list-units (linux)
• npm: npm list -g openclaw returns "not installed" or equivalent
• app bundle (macOS): /Applications/OpenClaw.app no longer exists
• network: no openclaw processes listening on any ports (verify with lsof -i or ss)

all methods:

• no orphaned processes: ps aux | grep openclaw returns no results (except grep itself)
• no stale config: no openclaw config files in ~/.config, ~/Library/Application Support, or ~/.openclaw* directories

outcome signal

user knows it worked when:

1. method 1 (IM-initiated):

   • user receives "uninstall scheduled" confirmation message in IM
   • gateway disconnects and does not reconnect
   • user can SSH into host (if remote) and cat /tmp/openclaw-uninstall.log shows completion without errors
   • if email or ntfy notification enabled, user receives message within 5 minutes confirming uninstall done
   • running openclaw status on host returns "command not found" or "not installed"

2. method 2 (verify residue):

   • script outputs "no residue found" or prints empty list
   • script exits with code 0
   • user runs script again moments later and gets same clean result

3. method 3 (manual uninstall):

   • command completes without error (exit code 0)
   • ~/.openclaw directory no longer exists or is empty
   • npm list -g openclaw shows "not installed"
   • openclaw command in terminal returns "command not found"
   • launchctl list | grep openclaw (macOS) returns nothing
   • systemctl --user status openclaw-gateway.service (linux) returns "not loaded"
   • running verify-clean.sh afterward reports no residue

common verification steps any user can run:

• ps aux | grep openclaw returns no processes (only grep in output)
• lsof -i :9000 (or other openclaw ports) returns nothing
• ls ~/.openclaw returns "no such file or directory"
• npm list -g openclaw returns "not installed"

---

notes

• this skill is community-maintained with no commercial affiliation to openclaw. uninstall is completely free.
• method 1 requires host=gateway in exec call, otherwise the one-shot job is created inside a container and lost when gateway stops. always verify this parameter is set.
• multiple profiles: if user has ~/.openclaw-profile1, ~/.openclaw-profile2, etc., remove each directory separately.
• remote mode: always run uninstall on the gateway host, not on a client machine.
• source install: if openclaw was installed from a git repo (not npm), uninstall the service first, then rm -rf /path/to/repo.
• network timeouts: if method 1 hangs waiting for user confirmation, check IM connectivity and retry. if script times out after confirmation, check host system logs at /tmp/openclaw-uninstall.log.
• rate limits: ntfy or email backends may rate-limit notifications; if notification does not arrive within 10 minutes, check spam folder or ntfy topic directly.
• auth expiry: if user has custom oauth or api tokens in ~/.openclaw/config.json, those are deleted in step 1c (method 3) or automatically in method 1. no manual revocation needed (revoke in upstream service if desired).
• empty result set: if verify-clean.sh finds no residue but user still suspects remnants, manually search for openclaw mentions in shell config files (~/.bashrc, ~/.zshrc, ~/.profile).
• IM uninstall failure recovery: if method 1 errors (e.g., "sandbox" or "permission denied"), SSH to gateway host and run ./scripts/schedule-uninstall.sh or ./scripts/uninstall-oneshot.sh directly.

---

中文 (Chinese)

免费、透明、可验证。无需付费清理服务。 本 skill 由社区维护，与 OpenClaw 官方无商业关联。

三种卸载方式

方式一（推荐）：IM 触发自动卸载

1. 用户在 IM 中发送「卸载」或「怎样卸载 OpenClaw」
2. Agent 确认「确认卸载 OpenClaw？此操作不可逆。回复「确认」继续。」
3. 用户回复「确认」
4. Agent 可选询问通知偏好「完成时通知？回复 'email user@example.com' 或 'ntfy my-topic' 或 'no'」
5. Agent 执行 ./scripts/schedule-uninstall.sh (必须 host=gateway 参数)
6. Agent 回复「卸载已排期。网关将在约 15 秒后断开。结果写入 /tmp/openclaw-uninstall.log」
7. 用户可 cat /tmp/openclaw-uninstall.log 验证完成

方式二（检查残留）：仅读取，不删除

• 运行 ./scripts/verify-clean.sh 扫描残留文件、进程、服务
• 用于"卸载干净了吗？"或"检查残留"的问题

方式三（手动卸载）：有 CLI 或 SSH 访问权限的用户

• 一条命令：openclaw uninstall --all --yes --non-interactive
• 或步骤式：停止网关 > 卸载服务 > 删除状态 > 删除 CLI > 删除应用
• 详见 官方文档

前置条件 / 重点

• 方式一需 host=gateway：否则 one-shot 在容器内创建会在网关停止时丢失，卸载不执行
• 支持平台：macOS、Linux (含 WSL2)；原生 Windows 不支持，请用 WSL2 或方式三手动
• headless Linux：需先运行 loginctl enable-linger $USER 使后台任务持久化
• WSL2：如 systemd-run 不可用，脚本自动降级到 nohup
• 多个配置文件：每个 ~/.openclaw-<profile> 需单独删除
• 远程网关：卸载必须在网关主机运行，不在客户端运行

决策点

• 如果用户通过 IM 请求且 Agent 支持方式一：运行方式一 (推荐)
• 如果方式一失败 (沙箱错误、权限拒绝)：SSH 到网关主机手动运行卸载脚本
• 如果用户询问"卸载干净吗？"：运行方式二验证脚本 (只读安全)
• 如果多个配置文件：分别删除每个 ~/.openclaw-<profile>
• 如果从源码安装：先卸载服务，再删除 git 仓库目录

验证成功

• ~/.openclaw 目录不存在
• openclaw 命令返回"command not found"
• npm list -g openclaw 返回"not installed"
• ps aux | grep openclaw 无结果 (除 grep 本身)
• /tmp/openclaw-uninstall.log 显示"complete"或成功标记

---

original source: clawhub / community-maintained
reference: openclaw official docs