OpenClaw Operations

Design Philosophy

This skill serves two core scenarios and nothing else:

1. Rescue — The main OpenClaw Gateway is down or broken. You (the rescue agent) need to diagnose the root cause, fix it, and bring the gateway back online.
Health Check — The main OpenClaw Gateway is running. You need to verify its operational health, clean up resources, or perform maintenance tasks like upgrades.

What this skill is NOT for:

- Day-to-day business configuration (adding channels, configuring agents, setting up integrations)
Application-level issues (agent behavior, prompt tuning, skill management)
Initial deployment or first-time setup (use openclaw daemon install and openclaw configure)

Principle: Diagnose → Judge → Act → Verify. Never skip steps.

Platform Detection

Detect the platform first — commands differ between Linux (systemd) and macOS (launchd):

CODEBLOCK0

Port Detection

Do NOT assume port 18789. Detect the actual configured port first:

CODEBLOCK1

Use $PORT in all port-related commands throughout this guide.

Scenario A: Rescue (Gateway Down)

Follow these sections in order when the main gateway is not running.

A1. Assess the Situation

CODEBLOCK2

A2. Check Logs for Root Cause

Linux:
CODEBLOCK3

macOS:
CODEBLOCK4

Common crash patterns

Log pattern	Meaning	Fix
INLINECODE3	Port already in use	Find conflicting process: `ss -tlnp \\| grep $PORT` (Linux) or `lsof -iTCP:$PORT` (macOS), kill it or change port
INLINECODE6 / INLINECODE7

A3. Config Repair

Always backup first:
CODEBLOCK5

JSON syntax validation:
CODEBLOCK6

Common JSON issues: trailing comma, missing quotes, unescaped characters. The error message shows line/position.

Config schema validation:
CODEBLOCK7

Common config errors:

Symptom	Likely cause	Fix
"device identity mismatch"	Service env token ≠ config token	Sync tokens between env file and openclaw.json
Agent not routing

bindings misconfigured | Bindings go at top-level, not inside agents.list[].routing |

After fixing, validate:
CODEBLOCK8

A4. Check Resources

CODEBLOCK9

A5. Restart and Verify

Only restart after identifying and fixing the root cause.

Linux:
CODEBLOCK10

macOS:
CODEBLOCK11

If service won't start at all:
CODEBLOCK12

Final verification:

openclaw status
openclaw doctor --non-interactive

Scenario B: Health Check (Gateway Running)

Follow these sections for routine operational checks on a running gateway.

B1. Quick Health Check

CODEBLOCK14

B2. Update & Upgrade

CODEBLOCK15

Perform update:
CODEBLOCK16

Rollback:
CODEBLOCK17

B3. Session & Disk Cleanup

CODEBLOCK18

B4. Backup

CODEBLOCK19

B5. Tailscale Serve Check

If OpenClaw uses Tailscale Serve as reverse proxy:

CODEBLOCK20

Reconfigure if broken:

tailscale serve reset
tailscale serve https / http://localhost:$PORT
tailscale serve status

Reference

Troubleshooting Quick Index

Symptom	Path
Gateway won't start	A1 → A2 → A3 → A5
Gateway crashed

`openclaw doctor` Reference

Flag	Effect
(none)	Interactive health check
INLINECODE20

--fix repairs: orphan transcripts, stale session locks, legacy key migration.
--fix does NOT: modify openclaw.json, change service files (unless --force), delete workspace files.

Key Commands

Command	Purpose
INLINECODE27	Quick status: running, version, basic info
INLINECODE28

Safety Rules

1. Always check logs before changing anything — understand the problem first
Always backup before editing config — cp with timestamp suffix
Always validate JSON after editing — one bad comma kills the service
Never print secrets — check env file exists, don't cat it
Never delete workspace files — use trash if you must remove something
Always verify after restart — status + logs, don't assume it worked
Destructive operations require confirmation — ask the user before wiping data

File Layout

CODEBLOCK22

OpenClaw 运维操作

设计理念

本技能仅服务于两个核心场景，不涉及其他用途：

1. 救援 — 主 OpenClaw 网关宕机或损坏。你（救援代理）需要诊断根本原因、修复问题并使网关恢复在线。
健康检查 — 主 OpenClaw 网关正在运行。你需要验证其运行健康状况、清理资源或执行升级等维护任务。

本技能不适用于：

- 日常业务配置（添加通道、配置代理、设置集成）
应用层问题（代理行为、提示词调优、技能管理）
初始部署或首次设置（请使用 openclaw daemon install 和 openclaw configure）

原则： 诊断 → 判断 → 操作 → 验证。切勿跳过步骤。

平台检测

首先检测平台——Linux（systemd）和 macOS（launchd）的命令不同：

bash
OS=$(uname -s) # Linux 或 Darwin
echo 平台：$OS

端口检测

不要假设端口为 18789。首先检测实际配置的端口：

bash
PORT=$(openclaw config get gateway.port 2>/dev/null | grep -oE [0-9]+)
PORT=${PORT:-18789} # 仅在配置不可用时回退到默认值
echo 网关端口：$PORT

在本指南的所有端口相关命令中使用 $PORT。

场景 A：救援（网关宕机）

当主网关未运行时，按顺序执行以下部分。

A1. 评估情况

bash

服务是否在运行？

Linux：

systemctl --user status openclaw-gateway

macOS：

launchctl list | grep openclaw

进程是否存活？

pgrep -af openclaw

端口是否在监听？

Linux：

ss -tlnp | grep $PORT

macOS：

lsof -iTCP:$PORT -sTCP:LISTEN

A2. 检查日志查找根本原因

最后 50 行上下文

journalctl --user -u openclaw-gateway -n 50 --no-pager

macOS：
bash
LOG_DIR=$HOME/.openclaw/logs
grep -iE error|crash|fatal $LOG_DIR/gateway.log | tail -20
tail -50 $LOG_DIR/gateway.log

同时检查统一日志

log show --predicate process == node --last 1h | grep -iE error|crash|fatal

常见崩溃模式

日志模式	含义	修复方法
EADDRINUSE	端口已被占用	查找冲突进程：ss -tlnp \	grep $PORT（Linux）或 lsof -iTCP:$PORT（macOS），终止进程或更改端口
ENOMEM / JavaScript heap

A3. 配置修复

始终先备份：
bash
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%s)

JSON 语法验证：
bash
python3 -c import json; json.load(open($HOME/.openclaw/openclaw.json))

常见 JSON 问题：尾部逗号、缺少引号、未转义字符。错误信息会显示行号和位置。

配置模式验证：
bash
openclaw config get gateway # 检查网关配置部分
openclaw config get channels # 检查通道配置部分

常见配置错误：

症状	可能原因	修复方法
设备身份不匹配	服务环境令牌 ≠ 配置令牌	同步环境文件和 openclaw.json 中的令牌
代理未路由

bindings 配置错误 | 绑定应放在顶层，而非 agents.list[].routing 内部 |

修复后验证：
bash
python3 -c import json; json.load(open($HOME/.openclaw/openclaw.json)); print(JSON 正常)
openclaw status

A4. 检查资源

bash

磁盘空间

df -h ~

内存（Linux）

free -h

内存（macOS）

vm_stat | head -5

Node.js 是否可用？

node -v which openclaw openclaw --version

A5. 重启并验证

仅在识别并修复根本原因后重启。

Linux：
bash
systemctl --user restart openclaw-gateway
sleep 3
systemctl --user status openclaw-gateway
journalctl --user -u openclaw-gateway -n 20 --no-pager

macOS：
bash
launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway
sleep 3
launchctl list | grep openclaw
tail -20 ~/.openclaw/logs/gateway.log

如果服务完全无法启动：
bash

手动前台启动以获得更好的错误输出

openclaw gateway start

最终验证：
bash
openclaw status
openclaw doctor --non-interactive

场景 B：健康检查（网关运行中）

对运行中的网关执行常规运维检查，请遵循以下部分。

B1. 快速健康检查

bash

综合检查——从这里开始

openclaw doctor

如果发现问题，自动修复安全项

openclaw doctor --fix

B2. 更新与升级

bash

检查版本

CURRENT=$(openclaw --version)
LATEST=$(npm view openclaw version)
echo 当前版本：$CURRENT 最新版本：$LATEST

执行更新：
bash

1. 保存 doctor 基线

openclaw doctor --non-interactive 2>&1 | tee /tmp/doctor-before.txt

2. 备份配置

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.pre-upgrade.$(date +%s)

3. 更新

npm update -g openclaw openclaw --version

4. 重启

Linux：

systemctl --user restart openclaw-gateway

macOS：

launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway

5. 比较 doctor 输出

sleep 5 openclaw doctor --non-interactive 2>&1 | tee /tmp/doctor-after.txt diff /tmp/doctor-before.txt /tmp/doctor-after.txt

回滚：
bash
npm install -g openclaw@<上一个版本>
cp ~/.openclaw/openclaw.json.pre-upgrade.<时间戳> ~/.openclaw/openclaw.json

重启（使用上述平台对应的命令）

B3. 会话与磁盘清理

bash

检查每个代理的磁盘使用情况

for agent_dir in ~/.openclaw/agents/*/; do
agent=$(basename $agent_dir)
size=$(du -sh $agent_dir/sessions/ 2>/dev/null | cut -f1)
count=$(find $agent_dir/sessions/ -name *.jsonl 2>/dev/null | wc -l)
echo $agent：$size（$count 条记录）
done

自动修复孤儿文件

openclaw doctor --fix

手动清理：旧记录（超过 30 天）

find ~/.openclaw/agents//sessions/ -name .jsonl -mtime +30 -exec ls -lh {} \;

审查后，如果安全则删除：

find ~/.openclaw/agents//sessions/ -name .jsonl -mtime

OpenClaw运维

OpenClaw运维

OpenClaw Operations

Design Philosophy

Platform Detection

Port Detection

Scenario A: Rescue (Gateway Down)

A1. Assess the Situation

A2. Check Logs for Root Cause

Common crash patterns

A3. Config Repair

A4. Check Resources

A5. Restart and Verify

Scenario B: Health Check (Gateway Running)

B1. Quick Health Check

B2. Update & Upgrade

B3. Session & Disk Cleanup

B4. Backup

B5. Tailscale Serve Check

Reference

Troubleshooting Quick Index

openclaw doctor Reference

Key Commands

Safety Rules

File Layout

OpenClaw 运维操作

设计理念

平台检测

端口检测

场景 A：救援（网关宕机）

A1. 评估情况

服务是否在运行？

Linux：

macOS：

进程是否存活？

端口是否在监听？

Linux：

macOS：

A2. 检查日志查找根本原因

最后 50 行上下文

同时检查统一日志

常见崩溃模式

A3. 配置修复

A4. 检查资源

磁盘空间

内存（Linux）

内存（macOS）

Node.js 是否可用？

A5. 重启并验证

手动前台启动以获得更好的错误输出

场景 B：健康检查（网关运行中）

B1. 快速健康检查

综合检查——从这里开始

如果发现问题，自动修复安全项

B2. 更新与升级

检查版本

1. 保存 doctor 基线

2. 备份配置

3. 更新

4. 重启

Linux：

macOS：

5. 比较 doctor 输出

重启（使用上述平台对应的命令）

B3. 会话与磁盘清理

检查每个代理的磁盘使用情况

自动修复孤儿文件

手动清理：旧记录（超过 30 天）

审查后，如果安全则删除：

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement

`openclaw doctor` Reference