#necessary steps to update

1 messages · Page 1 of 1 (latest)

velvet iceBOT Feb 21, 2026, 3:56 PM

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

hushed lilyBOT Feb 21, 2026, 3:59 PM

Here’s the “safe update” runbook, including backups.

Docs (canonical):

Updating: https://docs.openclaw.ai/install/updating
Backup strategy: https://docs.openclaw.ai/help/faq#whats-the-recommended-backup-strategy

0) Preflight (takes 30s)

openclaw --version
openclaw gateway status
openclaw update status   # optional, shows channel + what it thinks your install is

1) Backup (recommended)

OpenClaw has two important areas to back up:

A) Agent workspace (recommended: private git repo)

This is your “assistant brain”: AGENTS.md, SOUL.md, memory/, skills in-workspace, etc.

Default: ~/.openclaw/workspace (unless you changed agents.defaults.workspace)

Quick “file backup” version:

openclaw gateway stop  # optional but best if you care about perfect consistency
tar -czf ~/openclaw-workspace-$(date +%F).tgz ~/.openclaw/workspace
openclaw gateway start

B) State dir (only if you want full restore)

This includes config + sessions + credentials/tokens (store securely).

Default state dir: ~/.openclaw

openclaw gateway stop

tar -czf ~/openclaw-state-$(date +%F).tgz ~/.openclaw/openclaw.json ~/.openclaw/agents ~/.openclaw/credentials
openclaw gateway start

Notes:

Do not commit ~/.openclaw to git (it contains secrets).
If you’re on a VPS, an additional VPS snapshot backup is also a nice safety net.

2) Update (pick the path that matches your install)

Recommended (works for most installs): rerun the installer

curl -fsSL https://openclaw.ai/install.sh | bash

If you don’t want onboarding again:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

If you installed globally via npm/pnpm

npm i -g openclaw@latest
# or: pnpm add -g openclaw@latest
openclaw doctor
openclaw gateway restart
openclaw health

If you’re on a source (git) checkout

openclaw update

openclaw health

3) Verify after updating

openclaw gateway status
openclaw health
openclaw logs --follow   # if anything looks off

4) If something breaks (rollback)

Global install:

npm i -g openclaw@<version>
openclaw doctor

openclaw gateway restart

If you tell me:

your OS (macOS/Linux/VPS host) and
whether you installed via installer, npm/pnpm global, git source, or docker,
I’ll give you the exact shortest path for your setup.

sly lake Feb 21, 2026, 4:03 PM

vps host. Not sure how I installed most likely npm

hushed lilyBOT Feb 21, 2026, 4:03 PM

On a VPS + “most likely npm”, I’d do it like this.

Docs (worth skimming):

Updating: https://docs.openclaw.ai/install/updating
Backup strategy: https://docs.openclaw.ai/help/faq#whats-the-recommended-backup-strategy

1) Confirm install method (so we don’t update the wrong thing)

Run and paste the output:

openclaw --version
which openclaw
openclaw update status
openclaw gateway status

openclaw update status usually makes it obvious whether you’re on a git checkout or an npm-style install.

2) Backup (recommended)

On the VPS, OpenClaw’s important stuff is usually in:

Workspace (the “brain”): ~/.openclaw/workspace
State dir (config/sessions/credentials): ~/.openclaw

Best practice is to stop the gateway briefly so the snapshot is consistent:

openclaw gateway stop

# workspace backup (safe to store; contains memory + AGENTS.md etc)
tar -czf ~/openclaw-workspace-$(date +%F).tgz ~/.openclaw/workspace

# state backup (contains secrets; store privately!)
tar -czf ~/openclaw-state-$(date +%F).tgz ~/.openclaw/openclaw.json ~/.openclaw/agents ~/.openclaw/credentials

openclaw gateway start

Notes:

Don’t put ~/.openclaw into git (it contains tokens/credentials).
If your VPS provider offers snapshots, taking one also isn’t a bad idea.

3) Update (npm/global install path)

npm i -g openclaw@latest
openclaw doctor
openclaw gateway restart
openclaw health

(If you use pnpm globally instead of npm: pnpm add -g openclaw@latest.)

4) If it goes sideways (rollback)

Pin to a known-good version:

npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart

If you paste the openclaw update status output, I can tell you definitively which update path you’re on.

sly lake Feb 21, 2026, 4:05 PM

Service: systemd (enabled)
File logs: /tmp/openclaw/openclaw-2026-02-21.log
Command: /usr/bin/node /home/ubuntu/.npm-global/lib/node_modules/openclaw/dist/index.js gateway --port 18789
Service file: ~/.config/systemd/user/openclaw-gateway.service
Service env: OPENCLAW_GATEWAY_PORT=18789

Gateway service OPENCLAW_GATEWAY_TOKEN does not match gateway.auth.token in │
│ openclaw.json (service token is stale)

hushed lilyBOT Feb 21, 2026, 4:13 PM

That’s a Doctor warning about your installed Gateway service env, not a fatal error.

It means the Gateway service is still launching with an old OPENCLAW_GATEWAY_TOKEN, but your config now has a different gateway.auth.token in ~/.openclaw/openclaw.json. This often happens after a token rotation or reinstall.

Fix (recommended)

Let Doctor rewrite the service so it matches your config:

openclaw doctor --repair
openclaw gateway restart

If you want it fully non-interactive:

openclaw doctor --repair --yes

openclaw gateway restart

Verify what token is “correct”

Config token (source of truth):

openclaw config get gateway.auth.token

Make sure your Control UI / clients are using that token.

If Doctor can’t repair the service for some reason

Force-reinstall the gateway service (rewrites the service file/env), then restart:

openclaw gateway install --force
openclaw gateway restart

Docs:

Doctor: https://docs.openclaw.ai/gateway/doctor
Updating: https://docs.openclaw.ai/install/updating

If you paste the output of openclaw gateway status + your VPS OS (Ubuntu/Debian/etc.), I can tell you whether you’re on a systemd user service vs something else and what “install --force” will touch.

sly lake Feb 21, 2026, 4:16 PM

is therte a way to test automatically all the models that I have configured ?

hushed lilyBOT Feb 21, 2026, 4:19 PM

Yes-ish — there’s an automatic probe built in, but it’s aimed at “are my configured provider auth profiles working?” more than “try every single model id I ever typed into config”.

1) Best built-in smoke test: live auth+model probe per configured provider/profile

Run this on the VPS:

openclaw models status --probe

Useful knobs (still does real requests → can cost money + trigger rate limits):

openclaw models status --probe --probe-concurrency 2 --probe-timeout 8000 --probe-max-tokens 8

If you only want to test one provider:

openclaw models status --probe --probe-provider <provider>

This will print a section like “Auth probes” with OK/fail and latency.

Docs: https://docs.openclaw.ai/cli/models (see models status --probe)

2) If you mean “test every specific model ref in my primary+fallback list”

There isn’t currently a single “test all configured model refs” command. If you paste (redacting keys) how you configured models (e.g. agents.defaults.model.primary + fallbacks, or per-agent models), I can give you a short bash loop that runs a tiny prompt against each one without permanently messing up your gateway config.

sly lake Feb 21, 2026, 4:23 PM

"auth": {
"profiles": {
"google:default": {
"provider": "google",
"mode": "api_key"
},
"openrouter:default": {
"provider": "openrouter",
"mode": "api_key"
},
"qwen-portal:default": {
"provider": "qwen-portal",
"mode": "oauth"
},
"huggingface:default": {
"provider": "huggingface",
"mode": "api_key"
},
"moonshot:default": {
"provider": "moonshot",
"mode": "api_key"
},
"github-copilot:github": {
"provider": "github-copilot",
"mode": "token"
}
}
},

"models": {
"mode": "merge",
"providers": {
"qwen-portal": {
"baseUrl": "https://portal.qwen.ai/v1",
"apiKey": "qwen-oauth",
"api": "openai-completions",
"models": [
{
"id": "coder-model",
"name": "Qwen Coder",
"reasoning": false,
"input": [
"text"
],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 128000,
"maxTokens": 8192
},
{
"id": "vision-model",
"name": "Qwen Vision",
"reasoning": false,
"input": [
"text",
"image"
],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 128000,
"maxTokens": 8192
}
]
},
"huggingface": {
"baseUrl": "https://router.huggingface.co/v1",
"api": "openai-completions",
"models": [
{
"id": "deepseek-ai/DeepSeek-R1:together",
"name": "DeepSeek R1 (together)",
"reasoning": true,
"input": [
"text"
],
"cost": {
"input": 3,
"output": 7,
"cacheRead": 3,
"cacheWrite": 3
},
"contextWindow": 131072,
"maxTokens": 8192
},

"huggingface": {
"baseUrl": "https://router.huggingface.co/v1",
"api": "openai-completions",
"models": [
{
"id": "deepseek-ai/DeepSeek-R1:together",
"name": "DeepSeek R1 (together)",
"reasoning": true,
"input": [
"text"
],
"cost": {
"input": 3,
"output": 7,
"cacheRead": 3,
"cacheWrite": 3
},
"contextWindow": 131072,
"maxTokens": 8192
},
{
"id": "deepseek-ai/DeepSeek-V3.1",
"name": "DeepSeek V3.1",
"reasoning": false,
"input": [
"text"
],
"cost": {
"input": 0.6,
"output": 1.25,
"cacheRead": 0.6,
"cacheWrite": 0.6
},
"contextWindow": 131072,
"maxTokens": 8192
},
{
"id": "meta-llama/Llama-3.3-70B-Instruct-Turbo",
"name": "Llama 3.3 70B Instruct Turbo",
"reasoning": false,
"input": [
"text"
],
"cost": {
"input": 0.88,
"output": 0.88,
"cacheRead": 0.88,
"cacheWrite": 0.88
},
"contextWindow": 131072,
"maxTokens": 8192
},

{
"id": "openai/gpt-oss-120b",
"name": "GPT-OSS 120B",
"reasoning": false,
"input": [
"text"
],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 131072,
"maxTokens": 8192
}
]
},
"moonshot": {
"baseUrl": "https://api.moonshot.ai/v1",
"api": "openai-completions",
"models": [
{
"id": "kimi-k2.5",
"name": "Kimi K2.5",
"reasoning": false,
"input": [
"text"
],
"cost": {
"input": 0,
"output": 0,
"cacheRead": 0,
"cacheWrite": 0
},
"contextWindow": 256000,
"maxTokens": 8192
}
]
}
}
},

"agents": {
"defaults": {
"model": {
"primary": "cerebras/gpt-oss-120b"
},
"models": {
"google/gemini-3-pro-preview": {},
"openrouter/auto": {
"alias": "OpenRouter"
},
"openrouter/nvidia/nemotron-3-nano-30b-a3b:free": {},
"qwen-portal/coder-model": {
"alias": "qwen"
},
"qwen-portal/vision-model": {},
"huggingface/deepseek-ai/DeepSeek-R1:together": {
"alias": "Hugging Face"
},
"moonshot/kimi-k2.5": {
"alias": "Kimi"
},
"nvidia/nvidia/llama-3.1-nemotron-70b-instruct": {},
"github-copilot/claude-opus-4.5": {},
"huggingface/moonshotai/Kimi-K2.5": {},
"github-copilot/gpt-5.2": {},
"github-copilot/gpt-4o": {},
"groq/llama-3.3-70b-versatile": {},
"google/gemini-2.5-flash": {},
"huggingface/zai-org/GLM-4.7": {},
"openrouter/qwen/qwen3-next-80b-a3b-instruct:free": {},
"openrouter/google/gemma-3-27b-it:free": {},
"cerebras/zai-glm-4.7": {},
"mistral/mistral-large-latest": {},
"cerebras/gpt-oss-120b": {}
},
"workspace": "/home/ubuntu/.openclaw/workspace",
"compaction": {
"mode": "safeguard"
}
}
},

I want to test which ones are working to setup agents

hushed lilyBOT Feb 21, 2026, 4:28 PM

With that auth.profiles list, you can automatically smoke-test that each auth profile actually works using the built-in probe:

openclaw models status --probe

That will run a tiny real request (so: can cost money + can hit rate limits). You can make it gentler:

openclaw models status --probe --probe-concurrency 1 --probe-timeout 8000 --probe-max-tokens 8

Probe just the profiles you listed

You can target specific profile ids (yours are things like google:default, openrouter:default, etc.):

openclaw models status --probe --probe-profile google:default,openrouter:default,qwen-portal:default,huggingface:default,moonshot:default,github-copilot:github

Important limitation (re: “all models”)

models status --probe is mainly an auth/profile probe. It typically probes one model per provider (not every model you might have in fallbacks).

If you paste the part of your config that defines your actual model list (usually agents.defaults.model.primary + fallbacks, and optionally image models), I can give you a short bash loop to test each configured model ref one-by-one without permanently changing anything.

sly lake Feb 21, 2026, 4:32 PM

@hushed lily

hushed lilyBOT Feb 21, 2026, 4:32 PM

Yes — you can get pretty close to “test everything configured”, but it’s a 2-layer thing:

A) Test that each auth profile works (quickest)

This probes one model per provider/profile (real requests, may cost $ / rate-limit):

openclaw models status --probe

Target just your profiles:

openclaw models status --probe --probe-profile google:default,openrouter:default,qwen-portal:default,huggingface:default,moonshot:default,github-copilot:github

B) Test every configured model id (smoke-test loop)

There isn’t a single built-in “probe every model” command yet, but you can do it safely via Gateway RPC:

openclaw models list --plain gives your configured model refs (provider/model)
For each one:
1. set a dedicated test session’s model override (sessions.patch)
2. run one agent turn in that session (agent)

Copy/paste (uses python3, no jq needed):

SESSION_KEY="agent:main:model-smoke"
PROMPT="Reply with exactly: OK"

openclaw models list --plain | while read -r MODEL; do
  [ -z "$MODEL" ] && continue
  echo "=== Testing $MODEL ==="

  openclaw gateway call sessions.reset --expect-final --json --params "$(python3 - <<PY

import json
print(json.dumps({"key": "$SESSION_KEY", "reason": "reset"}))
PY
)"

  openclaw gateway call sessions.patch --expect-final --json --params "$(python3 - <<PY
import json
print(json.dumps({"key": "$SESSION_KEY", "model": "$MODEL"}))
PY
)"

  IDEM="$(python3 - <<'PY'
import uuid
print(uuid.uuid4())
PY

)"

  openclaw gateway call agent --expect-final --json --timeout 120000 --params "$(python3 - <<PY
import json
print(json.dumps({
  "sessionKey": "$SESSION_KEY",
  "message": "$PROMPT",
  "deliver": False,
  "timeout": 60,
  "idempotencyKey": "$IDEM",
}))
PY
)"
done

Notes:

This does real calls to every model → can get expensive / trigger rate limits.
It won’t message any chat app (deliver:false), it just runs internally and prints results.
If some providers/models choke on tool schema, they may fail here — which is useful signal.

If you want, paste the output of openclaw models list --plain (no secrets) and I can show you how to filter the loop to just one provider first (e.g. only qwen-portal/*), so you can validate gradually.

Yep — for your huggingface block specifically, you can do this two ways:

1) Quick “does HuggingFace auth work at all?” (one model)

This is the built-in probe (it sends a tiny prompt: “Reply with OK. Do not use tools.”):

openclaw models status --probe --probe-provider huggingface

That typically probes one model for that provider (not every model in your list).

2) Smoke-test every HuggingFace model you configured

First confirm OpenClaw sees them:

openclaw models list --provider huggingface --plain

# prints lines like:
# huggingface/deepseek-ai/DeepSeek-R1:together
# huggingface/deepseek-ai/DeepSeek-V3.1
# ...

Then run a loop that (a) sets a model override on a dedicated test session and (b) runs one tiny agent turn:

SESSION_KEY="agent:main:model-smoke-hf"
PROMPT="Reply with exactly: OK. Do not use tools."

openclaw models list --provider huggingface --plain | while read -r MODEL; do
  [ -z "$MODEL" ] && continue
  echo "=== Testing $MODEL ==="


  openclaw gateway call sessions.reset --params "$(python3 - <<PY
import json
print(json.dumps({"key":"$SESSION_KEY","reason":"reset"}))
PY
)"

  openclaw gateway call sessions.patch --params "$(python3 - <<PY
import json
print(json.dumps({"key":"$SESSION_KEY","model":"$MODEL"}))
PY
)"

  IDEM="$(python3 - <<'PY'
import uuid; print(uuid.uuid4())

Yep — with that agents.defaults.models allowlist, you can enumerate exactly those model refs and smoke-test them automatically.

1) List the models you’ve configured (not the whole public catalog)

openclaw models list --plain

That should print the provider/model keys (e.g. huggingface/deepseek-ai/DeepSeek-R1:together, qwen-portal/coder-model, etc.).

If you want to narrow:

openclaw models list --provider huggingface --plain

2) Smoke-test each configured model (one tiny prompt, no chat messages sent)

AGENT_ID="main"                  # change if your default agent id isn’t "main"
SESSION_KEY="agent:${AGENT_ID}:model-smoke"
PROMPT="Reply with exactly: OK"

openclaw models list --plain | while read -r MODEL; do
  [ -z "$MODEL" ] && continue
  echo "=== Testing $MODEL ==="

  openclaw gateway call sessions.reset --params "{\"key\":\"$SESSION_KEY\",\"reason\":\"reset\"}"

  openclaw gateway call sessions.patch --params "{\"key\":\"$SESSION_KEY\",\"model\":\"$MODEL\"}"

  IDEM="$(python3 - <<'PY'
import uuid; print(uuid.uuid4())
PY

)"

  openclaw gateway call agent --expect-final --timeout 120000 --params "$(python3 - <<PY
import json
print(json.dumps({
  "sessionKey": "$SESSION_KEY",
  "message": "$PROMPT",
  "deliver": False,
  "timeout": 60,
  "idempotencyKey": "$IDEM",
  "channel": "webchat"
}))
PY
)"
done

Quick check: what is my agent id?

If you’re not sure whether it’s main, run:

openclaw agents list

Heads up

This does real API calls to every model → can cost money / rate-limit.
It’s a basic “can it answer a prompt” test (not a tool-calling test).

If you want, I can give you a second pass that tests “model can call a tool” (e.g. web_fetch) too — that’s usually where some providers/models fall over.

PY
)"

  openclaw gateway call agent --expect-final --timeout 120000 --params "$(python3 - <<PY
import json
print(json.dumps({
  "sessionKey": "$SESSION_KEY",
  "message": "$PROMPT",
  "deliver": False,
  "timeout": 60,
  "idempotencyKey": "$IDEM"
}))
PY
)"
done

Nice — with your config, everything you want to test is already in the allowlist under agents.defaults.models. That means openclaw models list can enumerate it, and then you can smoke-test each model automatically.

1) Get the exact list of configured models (from your allowlist + primary/fallbacks)

openclaw models list --plain
# or narrow it:
openclaw models list --provider huggingface --plain

That should output refs like:
huggingface/deepseek-ai/DeepSeek-R1:together, qwen-portal/coder-model, etc.

2) Smoke-test each model (runs a tiny prompt, no messages sent)

This uses one dedicated session key, and for each model:

sessions.reset (fresh transcript)
sessions.patch (set session model override)
agent (run one turn)

Notes / expectations

This tests basic completions only. It does not prove tool-calling works (especially for api: "openai-completions" providers).
It’s doing real requests → can cost money / hit rate limits.
If your default agent id isn’t main, tell me what openclaw agents list shows and I’ll adjust the SESSION_KEY.

SESSION_KEY="agent:main:model-smoke"
PROMPT="Reply with exactly: OK"

openclaw models list --plain | while read -r MODEL; do
  [ -z "$MODEL" ] && continue
  echo "=== Testing $MODEL ==="

  openclaw gateway call sessions.reset --params "$(python3 - <<PY
import json
print(json.dumps({"key":"$SESSION_KEY","reason":"reset"}))
PY
)"

  openclaw gateway call sessions.patch --params "$(python3 - <<PY
import json

print(json.dumps({"key":"$SESSION_KEY","model":"$MODEL"}))
PY
)"

  IDEM="$(python3 - <<'PY'
import uuid; print(uuid.uuid4())
PY
)"

  openclaw gateway call agent --expect-final --timeout 120000 --params "$(python3 - <<PY
import json
print(json.dumps({
  "sessionKey": "$SESSION_KEY",
  "message": "$PROMPT",
  "deliver": False,