OpenClaw_安装配置问题解决

作者：Nerd Nirvana
OpenClaw 安装配置问题全解手册

版本适用：OpenClaw v0.x ~ v1.x｜更新时间：2026-03
本手册覆盖从安装到运行的全链路常见故障，按问题类型分章，每节给出原因分析 → 快速定位 → 修复步骤 → 验证方法四段式解法。

---

目录

command not found · PATH 修复 · 软链接Config invalid · 字段位置错误 · 正确格式参考端口占用 · 频繁重启 · RPC probe 失败 · systemd 路径问题AI 静默 · 自定义接口格式错误 · MiniMax 配置长连接保存失败 · 消息不到达 · did not mention bot · 插件冲突token missing · VPS 远程访问 Control UI任意插件 duplicate 冲突通用处理配对码使用 · 批量拒绝 · 关闭配对模式Docker 权限 · tailscale 报错MiniMax / Ollama / Gemini / OpenRouter 四种免费方案日志查看方法 + 关键日志信号含义速查表一键诊断 Shell 脚本

---

一、command not found · PATH 修复 · 软链接

1.1 问题现象

1. bash: openclaw: command not found

复制代码

或执行 openclaw start 后无任何输出，程序静默退出。
1.2 原因分析

原因	说明
二进制未加入 $PATH	安装脚本默认写入 ~/.local/bin，但该路径不在系统 PATH 中
安装至非标准目录	手动解压后未移动二进制到可执行目录
多用户环境路径差异	root 安装，普通用户执行时找不到
Shell 类型不同	zsh / fish 不读取 ~/.bashrc

1.3 快速定位

1. # 查看二进制实际位置which openclaw 2>/dev/null ||find / -name"openclaw"-type f 2>/dev/null
3. # 查看当前 PATHecho$PATH# 检查默认安装目录是否存在ls-la ~/.local/bin/openclaw
4. ls-la /usr/local/bin/openclaw

复制代码

1.4 修复步骤

方法 A：手动添加 PATH（临时）

1. exportPATH="$HOME/.local/bin:$PATH"
2. openclaw --version# 验证立即生效

复制代码

方法 B：永久写入 Shell 配置（推荐）

1. # Bash 用户echo'export PATH="$HOME/.local/bin:$PATH"'>> ~/.bashrc
2. source ~/.bashrc
4. # Zsh 用户echo'export PATH="$HOME/.local/bin:$PATH"'>> ~/.zshrc
5. source ~/.zshrc
7. # Fish 用户
8. fish_add_path ~/.local/bin

复制代码

方法 C：创建全局软链接（多用户/系统级）

1. # 先确认二进制真实路径REAL_PATH=$(find ~/.local/bin /opt -name"openclaw"-type f 2>/dev/null |head-1)echo"Found at: $REAL_PATH"# 创建软链接到全局 PATHsudoln-sf"$REAL_PATH" /usr/local/bin/openclaw
3. # 验证
4. openclaw --version

复制代码

方法 D：重新安装并指定目标目录

1. # 安装时明确指定安装路径curl-fsSL https://install.openclaw.dev |bash-s -- --prefix /usr/local

复制代码

1.5 软链接管理常用命令

1. # 查看软链接指向ls-la /usr/local/bin/openclaw
3. # 删除损坏的软链接sudorm /usr/local/bin/openclaw
5. # 重建软链接sudoln-sf /path/to/real/openclaw /usr/local/bin/openclaw
7. # 验证软链接有效性file /usr/local/bin/openclaw

复制代码

1.6 验证修复成功

1. openclaw --version# 期望输出: openclaw version x.x.x
3. openclaw status
4. # 期望输出: daemon 状态信息

复制代码

---

二、Config invalid · 字段位置错误 · 正确格式参考

2.1 问题现象

1. [ERROR] Config invalid: unexpected field 'ai_provider' at root level
2. [ERROR] failed to parse config: yaml: line 12: did not find expected key
3. [FATAL] Config validation failed, refusing to start

复制代码

2.2 原因分析

OpenClaw 使用严格分层的 YAML 结构，常见错误包括：

字段写在了错误的层级（缩进不足或过多）使用了旧版字段名（版本升级后字段被重命名）YAML 混用 Tab 和空格缩进字符串值未加引号导致解析歧义布尔值写成了字符串 "true" 而非 true

2.3 快速定位

1. # 使用内置校验命令
2. openclaw config validate
4. # 使用 yq 检查 YAML 语法
5. yq eval'.' ~/.config/openclaw/config.yaml
7. # 检查 Tab 字符（YAML 不允许 Tab 缩进）cat-A ~/.config/openclaw/config.yaml |grep-n'\^I'# 用 Python 验证 YAML 合法性
8. python3 -c"import yaml; yaml.safe_load(open('~/.config/openclaw/config.yaml').read()); print('YAML OK')"

复制代码

2.4 字段层级错误示例

错误写法（ai_provider 放错位置）

1. # 错误：ai_provider 应在 ai 块内，而非根级别server:port:8080ai_provider: minimax        # ← 错误！这是根级字段ai:model:"abab6.5s-chat"

复制代码

正确写法

1. server:port:8080ai:provider: minimax         # ← 正确：provider 在 ai 块内model:"abab6.5s-chat"api_key:"your-key-here"

复制代码

2.5 完整正确配置格式参考

1. # ============================================================# OpenClaw 完整配置文件参考# 路径: ~/.config/openclaw/config.yaml# ============================================================# ── 基础服务配置 ──────────────────────────────────────────server:host:"0.0.0.0"# 监听地址，VPS 填 0.0.0.0port:8080# HTTP 端口rpc_port:9090# gRPC 端口tls:enabled:falsecert_file:""key_file:""# ── 认证配置 ──────────────────────────────────────────────auth:token:"your-secret-token"# Control UI 访问令牌pairing:enabled:truecode:""# 留空则自动生成max_devices:5# ── AI 接入配置 ────────────────────────────────────────────ai:provider:"openai"# openai | minimax | ollama | gemini | openrouterapi_key:"sk-xxxx"base_url:""# 自定义接口时填写，留空使用默认model:"gpt-4o-mini"timeout:30# 秒max_tokens:2048temperature:0.7system_prompt:|
2.     You are a helpful assistant.# ── 消息处理配置 ───────────────────────────────────────────message:mention_required:true# 是否需要 @bot 才触发max_history:20# 上下文保留消息数session_timeout:3600# 会话超时（秒）retry_on_failure:3# 失败重试次数# ── 持久化配置 ─────────────────────────────────────────────storage:type:"sqlite"# sqlite | postgres | mysqlpath:"~/.local/share/openclaw/data.db"# 使用 PostgreSQL 时启用以下配置：# dsn: "postgres://user:pass@localhost:5432/openclaw"# ── 日志配置 ───────────────────────────────────────────────log:level:"info"# debug | info | warn | errorformat:"text"# text | jsonoutput:"stdout"# stdout | filefile:"/var/log/openclaw/openclaw.log"max_size_mb:100max_backups:3# ── 插件配置 ───────────────────────────────────────────────plugins:enabled:truedirectory:"~/.config/openclaw/plugins"list:-name:"weather"enabled:true-name:"search"enabled:false# ── 平台连接配置 ───────────────────────────────────────────platforms:-type:"wechat"enabled:trueoptions:data_path:"~/.local/share/openclaw/wechat"-type:"telegram"enabled:falseoptions:bot_token:""

复制代码

2.6 常见字段名变更对照表（版本升级后）

旧字段名（v0.x）	新字段名（v1.x）	所在块
ai_backend	ai.provider	root → ai
api_token	auth.token	root → auth
bot_mention	message.mention_required	root → message
db_path	storage.path	root → storage
log_level	log.level	root → log

2.7 验证修复成功

1. openclaw config validate &&echo"配置文件合法 ✓"
2. openclaw config dump    # 打印解析后的完整配置，便于人工核查

复制代码

---

三、端口占用 · 频繁重启 · RPC probe 失败 · systemd 路径问题

3.1 端口占用

现象

1. [ERROR] listen tcp 0.0.0.0:8080: bind: address already in use

复制代码

定位与修复

1. # 查找占用端口的进程sudo ss -tlnp|grep':8080'sudolsof-i :8080
3. # 方式一：终止占用进程sudokill-9$(lsof-t-i:8080)# 方式二：修改 OpenClaw 端口sed-i's/port: 8080/port: 8088/' ~/.config/openclaw/config.yaml
4. openclaw restart
6. # 方式三：检查是否有残留的旧进程ps aux |grep openclaw
7. pkill-f openclaw

复制代码

3.2 频繁重启（crash loop）

现象

1. systemd[1]: openclaw.service: Main process exited, code=killed, status=9/KILL
2. systemd[1]: openclaw.service: Failed with result 'signal'.
3. systemd[1]: openclaw.service: Scheduled restart job, restart counter is at 5.

复制代码

定位原因

1. # 查看最近崩溃日志
2. journalctl -u openclaw.service -n50 --no-pager
4. # 查看退出码
5. systemctl show openclaw.service |grep-E'ExecMainStatus|Result'# 查看内存使用（OOM 导致的 kill）
6. journalctl -k|grep-i"oom\|killed process"dmesg|grep-i"out of memory"

复制代码

常见崩溃原因及修复

原因	修复方法
配置文件错误	运行 openclaw config validate
内存不足（OOM）	增加 swap 或降低 max_history
依赖库缺失	ldd $(which openclaw) 检查依赖
权限不足	检查数据目录权限
数据库损坏	删除或修复 data.db

1. # 增加 Swap（临时解决 OOM）sudo fallocate -l 2G /swapfile
2. sudochmod600 /swapfile
3. sudomkswap /swapfile
4. sudoswapon /swapfile
6. # 修复数据库损坏
7. sqlite3 ~/.local/share/openclaw/data.db "PRAGMA integrity_check;"# 若损坏则备份后删除mv data.db data.db.bak && openclaw db init

复制代码

3.3 RPC probe 失败

现象

1. [ERROR] RPC health probe failed: connection refused on :9090
2. [WARN]  gRPC server not responding, retrying in 5s...

复制代码

修复步骤

1. # 1. 确认 RPC 端口配置一致grep rpc_port ~/.config/openclaw/config.yaml
3. # 2. 检查端口是否监听
4. ss -tlnp|grep9090# 3. 检查防火墙是否放行sudo ufw status
5. sudo iptables -L-n|grep9090# 4. 若使用 Docker，检查端口映射dockerps--format"table {{.Names}}\t{{.Ports}}"# 5. 临时禁用健康检查（排查期间）# 在 config.yaml 中添加：# server:#   health_probe: false# 6. 手动测试 gRPC 连通性
6. grpcurl -plaintext localhost:9090 list 2>/dev/null ||echo"gRPC 不可达"

复制代码

3.4 systemd 服务路径问题

现象

1. openclaw.service: Executable path is not absolute
2. openclaw.service: Failed at step EXEC spawning /home/user/.local/bin/openclaw

复制代码

查看当前 service 文件

1. cat /etc/systemd/system/openclaw.service
2. # 或用户级 servicecat ~/.config/systemd/user/openclaw.service

复制代码

正确的 systemd service 文件模板

1. # /etc/systemd/system/openclaw.service
2. [Unit]
3. Description=OpenClaw Bot Service
4. Documentation=https://docs.openclaw.dev
5. After=network-online.target
6. Wants=network-online.target
8. [Service]
9. Type=simple
10. User=openclaw
11. Group=openclaw
13. # !! ExecStart 必须使用绝对路径 !!
14. ExecStart=/usr/local/bin/openclaw start --config /etc/openclaw/config.yaml
16. # 工作目录
17. WorkingDirectory=/var/lib/openclaw
19. # 环境变量文件（可选）
20. EnvironmentFile=-/etc/openclaw/env
22. # 重启策略
23. Restart=on-failure
24. RestartSec=10
25. StartLimitInterval=60
26. StartLimitBurst=3
28. # 资源限制
29. LimitNOFILE=65535
31. # 日志
32. StandardOutput=journal
33. StandardError=journal
34. SyslogIdentifier=openclaw
36. [Install]
37. WantedBy=multi-user.target

复制代码

修复与重载

1. # 获取 openclaw 绝对路径which openclaw    # 得到如 /usr/local/bin/openclaw# 编辑 service 文件（填入上方模板）sudonano /etc/systemd/system/openclaw.service
3. # 重载 systemd 并启动sudo systemctl daemon-reload
4. sudo systemctl enable openclaw
5. sudo systemctl start openclaw
6. sudo systemctl status openclaw

复制代码

---

四、AI 静默 · 自定义接口格式错误 · MiniMax 配置

4.1 AI 静默（收到消息但 AI 不回复）

现象

机器人在线，能收到消息日志显示收到 message 事件，但无 AI 响应无任何报错输出

排查清单

1. # 1. 确认 AI 配置已填写
2. openclaw config dump |grep-A10"^ai:"# 2. 手动测试 API 连通性
3. openclaw test ai --message"hello"# 3. 查看 AI 调用日志
4. openclaw logs --filter"ai"--level debug
6. # 4. 检查 mention_required 设置# 若为 true，需要 @bot 才触发；改为 false 则所有消息都触发grep mention_required ~/.config/openclaw/config.yaml

复制代码

常见原因与修复

1. # 原因一：api_key 为空或占位符ai:api_key:"sk-xxxx"# ← 替换为真实 key# 原因二：model 名称拼写错误ai:model:"gpt-4o-mini"# ← 使用官方文档中的准确模型名# 原因三：base_url 末尾多了斜杠ai:base_url:"https://api.minimax.chat/v1"# ← 不要加末尾 /

复制代码

4.2 自定义接口格式错误

现象

1. [ERROR] AI API error: invalid response format, missing 'choices' field
2. [ERROR] failed to decode AI response: unexpected token at position 0

复制代码

问题原因

OpenClaw 默认使用 OpenAI 兼容格式。若自定义接口返回的 JSON 结构不同，需要配置响应映射。
OpenAI 标准响应格式（OpenClaw 期望的格式）

1. {"id":"chatcmpl-xxx","object":"chat.completion","choices":[{"index":0,"message":{"role":"assistant","content":"回复内容"},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":20,"total_tokens":30}}

复制代码

配置自定义响应映射

1. ai:provider:"custom"base_url:"https://your-api.example.com/v1"api_key:"your-key"response_mapping:content_path:"choices.0.message.content"# JSON 路径# 若接口返回格式如 {"result": {"text": "..."}} 则写：# content_path: "result.text"

复制代码

4.3 MiniMax 配置详解

MiniMax 是国内免费额度最多的方案之一，配置略有特殊性。
获取密钥

注册 MiniMax 开放平台进入「开发者中心」→「密钥管理」→ 创建 API Key记录 Group ID 和 API Key（两者均需要）

正确配置

1. ai:provider:"minimax"api_key:"eyJ..."# MiniMax API Key（JWT 格式）base_url:"https://api.minimax.chat/v1"model:"abab6.5s-chat"# 推荐：abab6.5s-chat（免费额度大）# MiniMax 特有参数extra_params:GroupId:"1234567890"# ← 必填！Group IDbot_setting:-bot_name:"助手"content:"你是一个有帮助的助手"# 可选模型列表：# abab5.5-chat    - 轻量版，速度快# abab6-chat      - 标准版# abab6.5s-chat   - 推荐，性价比最高# abab6.5g-chat   - 支持图片理解

复制代码

MiniMax 常见错误

1. Error 1004: api_key invalid
2. → 检查 api_key 是否完整复制（JWT token 较长）
4. Error 1039: GroupId is required
5. → extra_params.GroupId 未填写
7. Error 2013: model not found
8. → 模型名称拼写错误，参考上方列表

复制代码

---

五、长连接保存失败 · 消息不到达 · did not mention bot · 插件冲突

5.1 长连接保存失败

现象

1. [ERROR] Failed to persist connection state: database is locked
2. [WARN]  Long connection dropped, attempting reconnect...
3. [ERROR] session save failed: context deadline exceeded

复制代码

修复步骤

1. # 1. 检查数据库文件权限ls-la ~/.local/share/openclaw/data.db
3. # 2. 修复权限chmod644 ~/.local/share/openclaw/data.db
4. chown$(whoami) ~/.local/share/openclaw/data.db
6. # 3. 检查磁盘空间df-h ~/.local/share/openclaw/
8. # 4. 检查 SQLite WAL 模式（多进程写入问题）
9. sqlite3 ~/.local/share/openclaw/data.db "PRAGMA journal_mode;"# 推荐设为 WAL
10. sqlite3 ~/.local/share/openclaw/data.db "PRAGMA journal_mode=WAL;"# 5. 清理锁文件rm-f ~/.local/share/openclaw/data.db-shm
11. rm-f ~/.local/share/openclaw/data.db-wal

复制代码

配置层面调整

1. storage:type:"sqlite"path:"~/.local/share/openclaw/data.db"sqlite_options:journal_mode:"WAL"busy_timeout:5000# 毫秒，避免数据库锁cache_size:2000

复制代码

5.2 消息不到达

排查流程

1. 发送消息
2.     ↓
3. 平台接收？ → 检查平台连接（openclaw status platform）
4.     ↓
5. OpenClaw 收到？ → 检查 message 日志
6.     ↓
7. 过滤器通过？ → 检查 whitelist/blacklist 配置
8.     ↓
9. AI 处理？ → 检查 AI 配置
10.     ↓
11. 回复发出？ → 检查平台写权限

复制代码

1. # 开启 debug 日志查看消息流
2. openclaw logs --level debug --follow# 检查消息过滤配置
3. openclaw config dump |grep-A20"filters:"# 测试消息通路
4. openclaw test message --text"test"--platform wechat

复制代码

5.3 did not mention bot

现象

日志出现：

1. [INFO] message received but did not mention bot, ignoring

复制代码

原因与修复

1. # 原因：mention_required 为 true，消息中未包含 @机器人名称message:mention_required:false# 改为 false，所有消息都触发# 若保持 true，确认 bot_name 与平台设置一致bot_name:"小助手"# 必须与微信/平台中的昵称完全一致

复制代码

1. # 验证 bot_name 是否匹配
2. openclaw config dump |grep bot_name
4. # 临时在消息中手动加 @bot_name 测试# 如：@小助手 你好

复制代码

5.4 插件冲突

现象

1. [ERROR] plugin 'search' conflicts with plugin 'web-search': duplicate handler for route /search
2. [PANIC] plugin initialization failed: nil pointer dereference

复制代码

排查与修复

1. # 列出所有已加载插件
2. openclaw plugin list
4. # 逐一禁用插件排查
5. openclaw plugin disable search
6. openclaw restart
7. # 观察是否恢复正常，然后逐步重新启用# 查看插件详细信息
8. openclaw plugin info search
9. openclaw plugin info web-search

复制代码

1. # 配置文件中精确控制插件plugins:enabled:truelist:-name:"search"enabled:false# ← 禁用冲突插件之一-name:"web-search"enabled:true

复制代码

---

六、token missing · VPS 远程访问 Control UI

6.1 token missing

现象

访问 Control UI 时出现：

1. 401 Unauthorized: token missing or invalid

复制代码

或 API 调用返回：

1. {"error":"token missing","code":401}

复制代码

修复步骤

1. # 1. 查看当前 token 配置
2. openclaw config dump |grep-A5"auth:"# 2. 生成新的安全 token
3. openssl rand -hex32# 输出示例：a3f8e2b1c4d5...# 3. 更新配置文件cat>> ~/.config/openclaw/config.yaml <<'EOF'
4. auth:
5.   token: "a3f8e2b1c4d5..."   # 替换为上面生成的值
6. EOF# 4. 重启服务
7. openclaw restart

复制代码

使用 token 访问 API

1. # curl 示例curl-H"Authorization: Bearer YOUR_TOKEN" http://localhost:8080/api/status
3. # 或使用 X-Token 头（取决于版本）curl-H"X-Token: YOUR_TOKEN" http://localhost:8080/api/status

复制代码

6.2 VPS 远程访问 Control UI

方法一：直接暴露端口（不推荐，需配合 HTTPS）

1. # 确保防火墙放行sudo ufw allow 8080/tcp
2. sudo ufw reload
4. # 配置文件中改为监听所有接口# server:#   host: "0.0.0.0"

复制代码

方法二：SSH 端口转发（推荐，安全）

1. # 在本地执行，将远程 8080 映射到本地 18080ssh-L18080:localhost:8080 user@your-vps-ip -N# 然后本地浏览器访问# http://localhost:18080

复制代码

方法三：Nginx 反向代理 + HTTPS（生产推荐）

1. # /etc/nginx/sites-available/openclaw
2. server {
3.     listen 443 ssl;
4.     server_name openclaw.yourdomain.com;
6.     ssl_certificate     /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem;
7.     ssl_certificate_key /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem;
9.     # 认证保护（双重安全）
10.     auth_basic "OpenClaw Control";
11.     auth_basic_user_file /etc/nginx/.htpasswd;
13.     location / {
14.         proxy_pass http://127.0.0.1:8080;
15.         proxy_set_header Host $host;
16.         proxy_set_header X-Real-IP $remote_addr;
17.         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
18.         proxy_set_header X-Forwarded-Proto $scheme;
19.         
20.         # WebSocket 支持
21.         proxy_http_version 1.1;
22.         proxy_set_header Upgrade $http_upgrade;
23.         proxy_set_header Connection "upgrade";
24.     }
25. }
27. server {
28.     listen 80;
29.     server_name openclaw.yourdomain.com;
30.     return 301 https://$server_name$request_uri;
31. }

复制代码

1. # 申请 SSL 证书sudo certbot --nginx-d openclaw.yourdomain.com
3. # 创建 Basic Auth 用户sudo htpasswd -c /etc/nginx/.htpasswd admin
5. # 重载 Nginxsudo nginx -t&&sudo systemctl reload nginx

复制代码

方法四：Cloudflare Tunnel（零开放端口）

1. # 安装 cloudflaredcurl-L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
2. sudomv cloudflared /usr/local/bin/
3. sudochmod +x /usr/local/bin/cloudflared
5. # 登录并创建 tunnel
6. cloudflared tunnel login
7. cloudflared tunnel create openclaw
8. cloudflared tunnel route dns openclaw openclaw.yourdomain.com
10. # 配置文件 ~/.cloudflared/config.ymlcat> ~/.cloudflared/config.yml <<EOF
11. tunnel: <tunnel-id>
12. credentials-file: /home/user/.cloudflared/<tunnel-id>.json
14. ingress:
15.   - hostname: openclaw.yourdomain.com
16.     service: http://localhost:8080
17.   - service: http_status:404
18. EOF
20. cloudflared tunnel run openclaw

复制代码

---

七、任意插件 duplicate 冲突通用处理

7.1 冲突类型

冲突类型	错误信息	说明
路由重复	duplicate route handler	两个插件注册了同名路由
命令重复	duplicate command: /help	两个插件都注册了同名命令
事件重复	duplicate event listener	多个插件监听同一事件
名称重复	plugin name already registered	同名插件加载了两次

7.2 通用排查步骤

1. # Step 1: 列出所有插件
2. openclaw plugin list --verbose# Step 2: 查看冲突详情
3. openclaw plugin check
5. # Step 3: 查看插件注册的路由/命令
6. openclaw plugin routes
7. openclaw plugin commands
9. # Step 4: 定位冲突的两个插件
10. openclaw logs --level debug |grep"duplicate\|conflict\|already registered"

复制代码

7.3 通用修复流程

1. #!/bin/bash# 插件冲突通用修复脚本CONFLICT_PLUGIN="$1"# 要禁用的冲突插件名echo"=== 禁用冲突插件: $CONFLICT_PLUGIN ==="
2. openclaw plugin disable "$CONFLICT_PLUGIN"echo"=== 重启服务 ==="
3. openclaw restart
5. echo"=== 等待服务就绪 ==="sleep3echo"=== 验证状态 ==="
6. openclaw status
7. openclaw plugin list

复制代码

7.4 插件目录手动清理

1. # 查看插件目录ls-la ~/.config/openclaw/plugins/
3. # 备份并删除冲突插件PLUGIN_NAME="duplicate-plugin"cp-r ~/.config/openclaw/plugins/$PLUGIN_NAME ~/backup-$PLUGIN_NAMErm-rf ~/.config/openclaw/plugins/$PLUGIN_NAME# 清理插件缓存rm-rf ~/.cache/openclaw/plugins/
4. openclaw restart

复制代码

7.5 防止 duplicate 的最佳实践

1. plugins:enabled:true# 严格模式：检测到 duplicate 时启动失败（而非忽略）strict_mode:true# 明确列出要加载的插件（白名单模式）load_mode:"whitelist"# whitelist | alllist:-name:"weather"enabled:truepriority:10# 优先级，数字越小越先加载-name:"search"enabled:truepriority:20

复制代码

---

八、配对码使用 · 批量拒绝 · 关闭配对模式

8.1 配对码基本使用

配对码（Pairing Code）用于允许新设备/用户连接到 OpenClaw 实例。
生成配对码

1. # 生成一次性配对码
2. openclaw pairing generate
4. # 生成带过期时间的配对码
5. openclaw pairing generate --expires 24h
7. # 生成带使用次数限制的配对码
8. openclaw pairing generate --max-uses 1# 查看当前所有有效配对码
9. openclaw pairing list

复制代码

使用配对码

1. # 用户使用配对码连接
2. openclaw connect --code XXXX-YYYY-ZZZZ --server http://your-vps:8080
4. # 验证配对是否成功
5. openclaw pairing status

复制代码

8.2 批量拒绝连接请求

1. # 查看待审批的连接请求
2. openclaw pairing requests
4. # 拒绝单个请求
5. openclaw pairing reject <request-id># 批量拒绝所有待审批请求
6. openclaw pairing reject --all# 批量拒绝特定时间段前的请求
7. openclaw pairing reject --before"2024-01-01"# 撤销已批准的设备
8. openclaw pairing revoke <device-id># 批量撤销所有设备（危险！）
9. openclaw pairing revoke --all

复制代码

8.3 关闭配对模式

临时关闭

1. # 关闭配对模式（不允许新设备加入）
2. openclaw pairing disable
4. # 重新开启
5. openclaw pairing enable

复制代码

配置文件中永久关闭

1. auth:pairing:enabled:false# 完全关闭配对功能# 或者限制性开放：# enabled: true# require_approval: true    # 需要管理员手动批准# whitelist_only: true      # 仅白名单设备可连接

复制代码

8.4 查看已连接设备

1. # 列出所有已配对设备
2. openclaw devices list
4. # 查看设备详情
5. openclaw devices info <device-id># 移除指定设备
6. openclaw devices remove <device-id>

复制代码

---

九、Docker 权限 · tailscale 报错

9.1 Docker 权限问题

现象

1. docker: permission denied while trying to connect to the Docker daemon socket
2. Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

复制代码

修复步骤

1. # 方法一：将用户加入 docker 组（推荐）sudousermod-aGdocker$USER
2. newgrp docker# 立即生效，或重新登录# 验证docker run hello-world
4. # 方法二：修改 socket 权限（不推荐，每次重启失效）sudochmod666 /var/run/docker.sock

复制代码

Docker 内 OpenClaw 权限问题

1. # 查看容器日志docker logs openclaw --tail50# 以正确用户运行容器docker run -d\--name openclaw \--user$(id-u):$(id-g)\-v ~/.config/openclaw:/config \-v ~/.local/share/openclaw:/data \-p8080:8080 \
2.   openclaw/openclaw:latest

复制代码

推荐的 docker-compose.yml

1. version:'3.8'services:openclaw:image: openclaw/openclaw:latest
2.     container_name: openclaw
3.     restart: unless-stopped
4.    
5.     user:"1000:1000"# 指定用户 UID:GID，避免 root 权限问题ports:-"8080:8080"-"9090:9090"volumes:- ./config:/config:ro           # 配置目录（只读）- ./data:/data:rw               # 数据目录（读写）- ./logs:/var/log/openclaw:rw   # 日志目录environment:- OPENCLAW_CONFIG=/config/config.yaml
6.       - TZ=Asia/Shanghai
7.    
8.     healthcheck:test:["CMD","openclaw","health"]interval: 30s
9.       timeout: 10s
10.       retries:3start_period: 10s
11.    
12.     security_opt:- no-new-privileges:true# 防止提权cap_drop:- ALL                           # 删除所有 capabilitiescap_add:- NET_BIND_SERVICE              # 仅保留必要权限

复制代码

1. # 修复数据目录权限sudochown-R1000:1000 ./data ./logs
2. sudochmod-R755 ./data
4. # 启动docker-compose up -ddocker-compose logs -f

复制代码

9.2 tailscale 报错

现象

1. [ERROR] tailscale: failed to connect to control plane: dial tcp: lookup controlplane.tailscale.com: no such host
2. [WARN]  tailscale: network unreachable, falling back to direct connection
3. tailscale status: stopped

复制代码

修复步骤

1. # 检查 tailscale 状态
2. tailscale status
3. tailscale ping100.x.x.x   # ping 另一节点# 重启 tailscalesudo systemctl restart tailscaled
4. tailscale up
6. # 查看 tailscale 日志
7. journalctl -u tailscaled -n50# 如果在容器内使用 tailscale（需要特殊权限）docker run -d\--name openclaw \
8.   --cap-add NET_ADMIN \
9.   --cap-add SYS_MODULE \--device /dev/net/tun \-v /var/lib/tailscale:/var/lib/tailscale \
10.   openclaw/openclaw:latest

复制代码

tailscale 与 OpenClaw 集成配置

1. # 使用 tailscale IP 绑定，仅允许 tailnet 内访问server:host:"100.x.x.x"# 替换为本机的 tailscale IPport:8080# 查询本机 tailscale IP# tailscale ip -4

复制代码

1. # 通过 tailscale funnel 对外暴露（可选）
2. tailscale funnel 8080

复制代码

---

十、MiniMax / Ollama / Gemini / OpenRouter 四种免费方案

10.1 MiniMax（国内推荐）

1. ai:provider:"minimax"api_key:"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."base_url:"https://api.minimax.chat/v1"model:"abab6.5s-chat"extra_params:GroupId:"你的GroupID"

复制代码

免费额度：注册送 100 万 tokens，月度有赠送
申请地址：https://api.minimax.chat
适用场景：国内服务器，无需代理

---

10.2 Ollama（本地部署，完全免费）

安装 Ollama

1. # Linux / macOS 一键安装curl-fsSL https://ollama.com/install.sh |sh# 拉取模型（按需选择）
2. ollama pull qwen2.5:7b        # 通义千问，中文效果好
3. ollama pull llama3.2:3b       # Meta Llama，英文强
4. ollama pull deepseek-r1:7b    # DeepSeek，推理能力强
5. ollama pull gemma3:4b         # Google Gemma# 启动服务
6. ollama serve

复制代码

OpenClaw 配置

1. ai:provider:"openai"# Ollama 兼容 OpenAI 接口api_key:"ollama"# 随意填写，Ollama 不校验base_url:"http://localhost:11434/v1"model:"qwen2.5:7b"# 与 pull 的模型名一致

复制代码

1. # 验证 Ollama 服务curl http://localhost:11434/v1/chat/completions \-H"Content-Type: application/json"\-d'{"model":"qwen2.5:7b","messages":[{"role":"user","content":"hello"}]}'

复制代码

---

10.3 Gemini（Google，免费额度充足）

获取 API Key

访问 https://aistudio.google.com点击「Get API Key」→「Create API key」复制 API Key

OpenClaw 配置

1. ai:provider:"openai"# 使用 OpenAI 兼容端点api_key:"AIzaSy..."# Google AI Studio Keybase_url:"https://generativelanguage.googleapis.com/v1beta/openai/"model:"gemini-2.0-flash-exp"# 免费且速度快# 可用免费模型：# gemini-2.0-flash-exp   - 最新，功能全# gemini-1.5-flash-8b    - 超快，轻量# gemini-1.5-flash       - 均衡

复制代码

免费限制：15 RPM / 1,500,000 TPM / 1,500 RPD（免费版）
注意：国内服务器需要代理或使用香港 VPS

---

10.4 OpenRouter（聚合平台，多模型统一接口）

获取 API Key

注册 https://openrouter.ai进入 Dashboard → Keys → Create Key新账户有免费额度，部分模型永久免费

OpenClaw 配置

1. ai:provider:"openai"api_key:"sk-or-v1-..."base_url:"https://openrouter.ai/api/v1"model:"google/gemma-3-4b-it:free"# 免费模型加 :free 后缀# OpenRouter 永久免费模型列表（截至2025年）：# google/gemma-3-4b-it:free# google/gemma-3-12b-it:free# meta-llama/llama-3.2-3b-instruct:free# microsoft/phi-3-mini-128k-instruct:free# mistralai/mistral-7b-instruct:free

复制代码

1. # 验证 OpenRouter 连接curl https://openrouter.ai/api/v1/chat/completions \-H"Authorization: Bearer sk-or-v1-..."\-H"Content-Type: application/json"\-d'{"model":"google/gemma-3-4b-it:free","messages":[{"role":"user","content":"ping"}]}'

复制代码

10.5 四种方案对比

方案	费用	速度	中文效果	适用场景	需要代理
MiniMax	免费额度+付费	⚡⚡⚡	⭐⭐⭐⭐⭐	国内服务器	否
Ollama	完全免费	⚡⚡（取决于硬件）	⭐⭐⭐⭐	本地/高配VPS	否
Gemini	免费额度充足	⚡⚡⚡⚡	⭐⭐⭐⭐	海外服务器	是
OpenRouter	部分免费	⚡⚡⚡	⭐⭐⭐	多模型切换	是

---

十一、日志查看方法 + 关键日志信号含义速查表

11.1 日志查看方法

实时日志

1. # 方法一：openclaw 内置命令
2. openclaw logs --follow
3. openclaw logs --follow--level debug    # 显示 debug 级别
4. openclaw logs --follow--filter"ai"# 过滤关键字# 方法二：systemd journal
5. journalctl -u openclaw.service -f
6. journalctl -u openclaw.service -f--since"10 minutes ago"# 方法三：直接读文件tail-f /var/log/openclaw/openclaw.log
7. tail-f /var/log/openclaw/openclaw.log |grep-E"ERROR|WARN"

复制代码

历史日志查询

1. # 查看最近 100 行
2. openclaw logs --tail100# 查看特定时间段
3. journalctl -u openclaw.service --since"2024-01-01 08:00"--until"2024-01-01 12:00"# 查看特定日志级别
4. openclaw logs --level error --since 24h
6. # 导出日志到文件
7. openclaw logs --since 24h > openclaw-debug-$(date +%Y%m%d).log
9. # 搜索特定错误grep-n"ERROR\|FATAL" /var/log/openclaw/openclaw.log |tail-50

复制代码

日志级别设置

1. log:level:"debug"# 临时调至 debug 排查问题# 生产环境用 "info" 或 "warn"

复制代码

1. # 运行时动态修改日志级别（无需重启）
2. openclaw config set log.level debug
3. openclaw config set log.level info

复制代码

11.2 关键日志信号含义速查表

启动阶段

日志信号	含义	处理建议
Starting OpenClaw v...	服务正常启动	✅ 正常
Config loaded from ...	配置文件读取成功	✅ 正常
Config invalid:	配置文件格式错误	→ 见第二章
Database initialized	数据库初始化成功	✅ 正常
database is locked	SQLite 锁冲突	→ 见第五章 5.1
address already in use	端口被占用	→ 见第三章 3.1
plugin loaded: xxx	插件加载成功	✅ 正常
duplicate route handler	插件路由冲突	→ 见第七章

运行阶段 - 消息处理

日志信号	含义	处理建议
message received from ...	收到新消息	✅ 正常
did not mention bot, ignoring	未@机器人	→ 见第五章 5.3
message filtered by rule	被过滤规则拦截	→ 检查 filters 配置
AI request sent	AI 请求已发出	✅ 正常
AI response received	AI 响应已收到	✅ 正常
AI timeout after ...s	AI 接口超时	→ 增大 ai.timeout
message sent successfully	回复发送成功	✅ 正常
failed to send message	回复发送失败	→ 检查平台连接

运行阶段 - AI 接口

日志信号	含义	处理建议
API key invalid	API Key 错误	→ 重新获取 key
rate limit exceeded	频率超限	→ 等待或升级配额
model not found	模型名称错误	→ 检查模型名拼写
context length exceeded	上下文过长	→ 减少 max_history
connection refused	接口连接失败	→ 检查 base_url 和网络
invalid response format	响应格式不匹配	→ 见第四章 4.2

运行阶段 - 系统

日志信号	含义	处理建议
health check passed	健康检查通过	✅ 正常
health check failed	健康检查失败	→ 检查 RPC 端口
memory usage: xxxMB	内存使用量	> 500MB 需关注
goroutine leak detected	协程泄漏	→ 重启并上报 issue
panic:	程序 panic	→ 查看完整 stack trace
signal: killed	被系统 OOM kill	→ 增加内存/swap
graceful shutdown	优雅退出	✅ 正常停止

---

十二、一键诊断 Shell 脚本

将以下脚本保存为 openclaw-diagnose.sh，赋予执行权限后运行：

1. curl-fsSL https://your-domain/openclaw-diagnose.sh |bash# 或本地保存后执行：# bash openclaw-diagnose.sh

复制代码

1. #!/usr/bin/env bash# ============================================================# OpenClaw 一键诊断脚本 v1.0# 用法: bash openclaw-diagnose.sh [--fix] [--output report.txt]# ============================================================set-euo pipefail
3. # ── 颜色定义 ──────────────────────────────────────────────RED='\033[0;31m'GREEN='\033[0;32m'YELLOW='\033[1;33m'BLUE='\033[0;34m'CYAN='\033[0;36m'BOLD='\033[1m'NC='\033[0m'# ── 参数解析 ──────────────────────────────────────────────AUTO_FIX=false
4. OUTPUT_FILE=""while[[$#-gt0]];docase$1in
5.         --fix)AUTO_FIX=true;shift;;
6.         --output)OUTPUT_FILE="$2";shift2;;
7.         *)echo"未知参数: $1";exit1;;esacdone# ── 输出函数 ──────────────────────────────────────────────log(){echo-e"${BLUE}[INFO]${NC}$*";}ok(){echo-e"${GREEN}[  OK]${NC}$*";}warn(){echo-e"${YELLOW}[WARN]${NC}$*";}err(){echo-e"${RED}[FAIL]${NC}$*";}section(){echo-e"\n${BOLD}${CYAN}══════════════════════════════════════════${NC}";echo-e"${BOLD}${CYAN}$*${NC}";echo-e"${BOLD}${CYAN}══════════════════════════════════════════${NC}";}PASS=0FAIL=0WARN_COUNT=0check_pass(){ ok "$1";((PASS++));}check_fail(){ err "$1";((FAIL++));}check_warn(){ warn "$1";((WARN_COUNT++));}# ── 开始诊断 ──────────────────────────────────────────────echo-e"${BOLD}"echo"  ╔═══════════════════════════════════════╗"echo"  ║     OpenClaw 一键诊断工具 v1.0        ║"echo"  ║     $(date'+%Y-%m-%d %H:%M:%S')               ║"echo"  ╚═══════════════════════════════════════╝"echo-e"${NC}"# ============================================================
8. section "① 二进制与 PATH 检查"# ============================================================ifcommand-v openclaw &>/dev/null;thenOPENCLAW_PATH=$(which openclaw)OPENCLAW_VERSION=$(openclaw --version2>/dev/null ||echo"unknown")
9.     check_pass "openclaw 已找到: $OPENCLAW_PATH ($OPENCLAW_VERSION)"else
10.     check_fail "openclaw 未在 PATH 中找到"
11.     log "搜索可能的安装位置..."FOUND=$(find /usr/local/bin /usr/bin ~/.local/bin /opt -name"openclaw"-type f 2>/dev/null |head-3)if[[-n"$FOUND"]];then
12.         warn "找到二进制: $FOUND"
13.         warn "请将其目录加入 PATH 或创建软链接"if[["$AUTO_FIX"=="true"]];thenFIRST=$(echo"$FOUND"|head-1)sudoln-sf"$FIRST" /usr/local/bin/openclaw
14.             ok "[自动修复] 已创建软链接: /usr/local/bin/openclaw -> $FIRST"fielse
15.         err "未找到 openclaw 二进制，请重新安装"fifi# ============================================================
16. section "② 配置文件检查"# ============================================================CONFIG_PATHS=("$HOME/.config/openclaw/config.yaml""/etc/openclaw/config.yaml""./config.yaml")CONFIG_FOUND=""forpin"${CONFIG_PATHS[@]}";doif[[-f"$p"]];thenCONFIG_FOUND="$p"
17.         check_pass "配置文件存在: $p"breakfidoneif[[-z"$CONFIG_FOUND"]];then
18.     check_fail "未找到配置文件，搜索路径: ${CONFIG_PATHS
19. [*]}"else# 检查 YAML 语法ifcommand-v python3 &>/dev/null;thenif python3 -c"import yaml; yaml.safe_load(open('$CONFIG_FOUND'))"2>/dev/null;then
20.             check_pass "YAML 语法合法"else
21.             check_fail "YAML 语法错误，请检查缩进和格式"fifi# 检查必要字段forfieldin"server:""ai:""auth:";doifgrep-q"^$field""$CONFIG_FOUND";then
22.             check_pass "必要字段存在: $field"else
23.             check_fail "缺少必要字段: $field"fidone# 检查 Tab 字符ifgrep-Pq"\t""$CONFIG_FOUND"2>/dev/null;then
24.         check_fail "配置文件包含 Tab 字符（YAML 必须用空格缩进）"if[["$AUTO_FIX"=="true"]];thensed-i's/\t/  /g'"$CONFIG_FOUND"
25.             ok "[自动修复] 已将 Tab 替换为两个空格"fielse
26.         check_pass "缩进字符正常（无 Tab）"fi# 检查 api_key 是否为占位符ifgrep-qE'api_key:\s*"(sk-xxxx|your-key|YOUR_KEY|placeholder)"'"$CONFIG_FOUND";then
27.         check_fail "api_key 仍为占位符，请填写真实 API Key"fifi# ============================================================
28. section "③ 端口检查"# ============================================================check_port(){localport=$1localname=$2if ss -tlnp2>/dev/null |grep-q":$port "||\netstat-tlnp2>/dev/null |grep-q":$port ";then
29.         check_pass "端口 $port ($name) 正在监听"else
30.         check_warn "端口 $port ($name) 未监听（服务可能未启动）"fi}HTTP_PORT=$(grep-oP'port:\s*\K\d+'"$CONFIG_FOUND"2>/dev/null |head-1||echo"8080")RPC_PORT=$(grep-oP'rpc_port:\s*\K\d+'"$CONFIG_FOUND"2>/dev/null |head-1||echo"9090")
32. check_port "$HTTP_PORT""HTTP"
33. check_port "$RPC_PORT""gRPC"# 检查端口是否被其他进程占用forportin$HTTP_PORT$RPC_PORT;doPIDS=$(lsof-ti :$port 2>/dev/null ||true)if[[-n"$PIDS"]];thenPROC=$(ps-p $PIDS -ocomm=2>/dev/null ||echo"unknown")if[["$PROC"!="openclaw"]];then
34.             check_warn "端口 $port 被非 openclaw 进程占用: $PROC (PID: $PIDS)"fifidone# ============================================================
35. section "④ 服务状态检查"# ============================================================ifcommand-v systemctl &>/dev/null;thenif systemctl is-active --quiet openclaw 2>/dev/null;then
36.         check_pass "systemd 服务运行中"UPTIME=$(systemctl show openclaw --property=ActiveEnterTimestamp |cut-d=-f2)
37.         log "服务启动时间: $UPTIME"elif systemctl is-enabled --quiet openclaw 2>/dev/null;then
38.         check_warn "systemd 服务已注册但未运行"else
39.         check_warn "未检测到 openclaw systemd 服务"fifi# 检查进程if pgrep -x"openclaw"&>/dev/null;thenPID=$(pgrep -x"openclaw")MEM=$(ps-orss=-p $PID 2>/dev/null |awk'{printf "%.1fMB", $1/1024}')CPU=$(ps-o %cpu=-p $PID 2>/dev/null |tr-d' ')
40.     check_pass "openclaw 进程运行中 (PID: $PID, MEM: $MEM, CPU: ${CPU}%)"else
41.     check_warn "未检测到运行中的 openclaw 进程"fi# ============================================================
42. section "⑤ 网络连通性检查"# ============================================================check_url(){localname=$1localurl=$2ifcurl-sf --max-time 5"$url"&>/dev/null;then
43.         check_pass "网络可达: $name ($url)"else
44.         check_fail "网络不可达: $name ($url)"fi}
46. check_url "本地 HTTP""http://localhost:${HTTP_PORT:-8080}/health"||true# 检查 AI 接口网络if[[-f"$CONFIG_FOUND"]];thenBASE_URL=$(grep-oP'base_url:\s*"\K[^"]+'"$CONFIG_FOUND"|head-1)if[[-n"$BASE_URL"]];thenDOMAIN=$(echo"$BASE_URL"|grep-oP'(?<=://)([^/]+)')ifcurl-sf --max-time 5"https://$DOMAIN"&>/dev/null;then
47.             check_pass "AI 接口域名可达: $DOMAIN"else
48.             check_fail "AI 接口域名不可达: $DOMAIN（可能需要代理）"fififi# ============================================================
49. section "⑥ 磁盘与内存检查"# ============================================================# 磁盘空间DISK_USAGE=$(df-h ~/.local/share/openclaw 2>/dev/null |tail-1|awk'{print $5}'|tr-d'%'||echo"0")if[["$DISK_USAGE"-lt80]];then
50.     check_pass "磁盘使用率: ${DISK_USAGE}%"elif[["$DISK_USAGE"-lt95]];then
51.     check_warn "磁盘使用率较高: ${DISK_USAGE}%"else
52.     check_fail "磁盘使用率危险: ${DISK_USAGE}%，请立即清理"fi# 内存MEM_FREE=$(free-m|awk'/^Mem:/{print $7}')if[["$MEM_FREE"-gt256]];then
53.     check_pass "可用内存: ${MEM_FREE}MB"elif[["$MEM_FREE"-gt64]];then
54.     check_warn "可用内存较低: ${MEM_FREE}MB"else
55.     check_fail "可用内存严重不足: ${MEM_FREE}MB"fi# ============================================================
56. section "⑦ 最近错误日志"# ============================================================LOG_FILE="/var/log/openclaw/openclaw.log"if[[-f"$LOG_FILE"]];thenERROR_COUNT=$(grep-c"ERROR\|FATAL\|PANIC""$LOG_FILE"2>/dev/null ||echo"0")
57.     log "日志文件: $LOG_FILE"
58.     log "错误总数（全量）: $ERROR_COUNT"echo-e"\n${YELLOW}最近 5 条错误:${NC}"grep"ERROR\|FATAL\|PANIC""$LOG_FILE"2>/dev/null |tail-5|whileIFS=read-r line;doecho-e"  ${RED}▶${NC}$line"doneelifcommand-v journalctl &>/dev/null;then
59.     log "从 journald 读取最近错误..."
60.     journalctl -u openclaw.service -n10 --no-pager -p err 2>/dev/null |tail-10|whileIFS=read-r line;doecho-e"  ${RED}▶${NC}$line"doneelse
61.     check_warn "未找到日志文件"fi# ============================================================
62. section "⑧ Docker 环境检查（如适用）"# ============================================================ifcommand-vdocker&>/dev/null;thenifdocker info &>/dev/null;then
63.         check_pass "Docker 守护进程运行中"OPENCLAW_CONTAINER=$(dockerps--format"{{.Names}}"|grep-i openclaw |head-1)if[[-n"$OPENCLAW_CONTAINER"]];thenSTATUS=$(docker inspect --format='{{.State.Status}}'"$OPENCLAW_CONTAINER")
64.             check_pass "OpenClaw 容器运行中: $OPENCLAW_CONTAINER (Status: $STATUS)"else
65.             check_warn "未检测到运行中的 OpenClaw 容器"fielse
66.         check_warn "Docker 守护进程未运行或无权限访问"if[["$AUTO_FIX"=="true"]];thensudousermod-aGdocker$USER
67.             ok "[自动修复] 已将 $USER 加入 docker 组，请重新登录生效"fififi# ============================================================
68. section "诊断报告汇总"# ============================================================TOTAL=$((PASS + FAIL + WARN_COUNT))echo""echo-e"  ${GREEN}通过: $PASS${NC} / ${RED}失败: $FAIL${NC} / ${YELLOW}警告: $WARN_COUNT${NC} / 总计: $TOTAL"echo""if[[$FAIL-eq0&&$WARN_COUNT-eq0]];thenecho-e"  ${GREEN}${BOLD}✅ 所有检查通过！OpenClaw 运行状态良好。${NC}"elif[[$FAIL-eq0]];thenecho-e"  ${YELLOW}${BOLD}⚠️  存在 $WARN_COUNT 个警告，建议检查。${NC}"elseecho-e"  ${RED}${BOLD}❌ 发现 $FAIL 个问题需要修复。${NC}"echo-e"  ${CYAN}提示: 使用 --fix 参数可自动修复部分问题${NC}"echo-e"  ${CYAN}      bash openclaw-diagnose.sh --fix${NC}"fiecho""echo-e"  ${CYAN}详细文档: https://docs.openclaw.dev/troubleshooting${NC}"echo""# ── 可选：输出到文件 ───────────────────────────────────────if[[-n"$OUTPUT_FILE"]];then# 重新运行并保存（去除颜色码）bash"$0"2>&1|sed's/\x1b\[[0-9;]*m//g'>"$OUTPUT_FILE"echo"诊断报告已保存至: $OUTPUT_FILE"fi# 返回状态码[[$FAIL-eq0]]

复制代码

使用示例

1. # 保存脚本curl-fsSL https://raw.githubusercontent.com/your/repo/main/diagnose.sh -o openclaw-diagnose.sh
2. chmod +x openclaw-diagnose.sh
4. # 基础诊断
5. ./openclaw-diagnose.sh
7. # 自动修复模式
8. ./openclaw-diagnose.sh --fix# 输出报告到文件
9. ./openclaw-diagnose.sh --output report-$(date +%Y%m%d).txt
11. # 提交 issue 时附上报告
12. ./openclaw-diagnose.sh --output /tmp/openclaw-report.txt
13. cat /tmp/openclaw-report.txt

复制代码

---

附录：常用命令速查

1. # 服务管理
2. openclaw start              # 启动
3. openclaw stop               # 停止
4. openclaw restart            # 重启
5. openclaw status             # 查看状态# 配置管理
6. openclaw config validate    # 验证配置
7. openclaw config dump        # 查看解析后配置
8. openclaw config set key val # 动态设置配置项# 日志
9. openclaw logs -f# 实时日志
10. openclaw logs --level debug # Debug 日志# 插件
11. openclaw plugin list        # 列出插件
12. openclaw plugin enable xxx  # 启用插件
13. openclaw plugin disable xxx # 禁用插件# 设备/配对
14. openclaw devices list       # 已连接设备
15. openclaw pairing generate   # 生成配对码
16. openclaw pairing disable    # 关闭配对# AI 测试
17. openclaw test ai --message"hello"# 测试 AI 接口# 数据库
18. openclaw db migrate         # 执行迁移
19. openclaw db status          # 数据库状态

复制代码

---

原文地址：https://blog.csdn.net/qq_45789531/article/details/158620907