OpenClaw_安装配置问题解决 - AI创想

bash: openclaw: command not found

复制代码

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

复制代码

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

复制代码

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

复制代码

# 先确认二进制真实路径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
# 验证
openclaw --version

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

# ============================================================# 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:|
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:""

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

# /etc/systemd/system/openclaw.service
[Unit]
Description=OpenClaw Bot Service
Documentation=https://docs.openclaw.dev
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=openclaw
Group=openclaw
# !! ExecStart 必须使用绝对路径 !!
ExecStart=/usr/local/bin/openclaw start --config /etc/openclaw/config.yaml
# 工作目录
WorkingDirectory=/var/lib/openclaw
# 环境变量文件（可选）
EnvironmentFile=-/etc/openclaw/env
# 重启策略
Restart=on-failure
RestartSec=10
StartLimitInterval=60
StartLimitBurst=3
# 资源限制
LimitNOFILE=65535
# 日志
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw
[Install]
WantedBy=multi-user.target

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

{"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}}

复制代码

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"

复制代码

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 - 支持图片理解

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

发送消息
↓
平台接收？ → 检查平台连接（openclaw status platform）
↓
OpenClaw 收到？ → 检查 message 日志
↓
过滤器通过？ → 检查 whitelist/blacklist 配置
↓
AI 处理？ → 检查 AI 配置
↓
回复发出？ → 检查平台写权限

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

401 Unauthorized: token missing or invalid

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

# /etc/nginx/sites-available/openclaw
server {
listen 443 ssl;
server_name openclaw.yourdomain.com;
ssl_certificate /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem;
# 认证保护（双重安全）
auth_basic "OpenClaw Control";
auth_basic_user_file /etc/nginx/.htpasswd;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket 支持
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
server {
listen 80;
server_name openclaw.yourdomain.com;
return 301 https://$server_name$request_uri;
}

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

# 查看插件目录ls-la ~/.config/openclaw/plugins/
# 备份并删除冲突插件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/
openclaw restart

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

# 查看容器日志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 \
openclaw/openclaw:latest

复制代码

version:'3.8'services:openclaw:image: openclaw/openclaw:latest
container_name: openclaw
restart: unless-stopped
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
- TZ=Asia/Shanghai
healthcheck:test:["CMD","openclaw","health"]interval: 30s
timeout: 10s
retries:3start_period: 10s
security_opt:- no-new-privileges:true# 防止提权cap_drop:- ALL # 删除所有 capabilitiescap_add:- NET_BIND_SERVICE # 仅保留必要权限

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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 - 均衡

复制代码

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

复制代码

# 验证 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"}]}'

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

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

复制代码

#!/usr/bin/env bash# ============================================================# OpenClaw 一键诊断脚本 v1.0# 用法: bash openclaw-diagnose.sh [--fix] [--output report.txt]# ============================================================set-euo pipefail
# ── 颜色定义 ──────────────────────────────────────────────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
OUTPUT_FILE=""while[[$#-gt0]];docase$1in
--fix)AUTO_FIX=true;shift;;
--output)OUTPUT_FILE="$2";shift2;;
*)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}"# ============================================================
section "① 二进制与 PATH 检查"# ============================================================ifcommand-v openclaw &>/dev/null;thenOPENCLAW_PATH=$(which openclaw)OPENCLAW_VERSION=$(openclaw --version2>/dev/null ||echo"unknown")
check_pass "openclaw 已找到: $OPENCLAW_PATH ($OPENCLAW_VERSION)"else
check_fail "openclaw 未在 PATH 中找到"
log "搜索可能的安装位置..."FOUND=$(find /usr/local/bin /usr/bin ~/.local/bin /opt -name"openclaw"-type f 2>/dev/null |head-3)if[[-n"$FOUND"]];then
warn "找到二进制: $FOUND"
warn "请将其目录加入 PATH 或创建软链接"if[["$AUTO_FIX"=="true"]];thenFIRST=$(echo"$FOUND"|head-1)sudoln-sf"$FIRST" /usr/local/bin/openclaw
ok "[自动修复] 已创建软链接: /usr/local/bin/openclaw -> $FIRST"fielse
err "未找到 openclaw 二进制，请重新安装"fifi# ============================================================
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"
check_pass "配置文件存在: $p"breakfidoneif[[-z"$CONFIG_FOUND"]];then
check_fail "未找到配置文件，搜索路径: ${CONFIG_PATHS
[*]}"else# 检查 YAML 语法ifcommand-v python3 &>/dev/null;thenif python3 -c"import yaml; yaml.safe_load(open('$CONFIG_FOUND'))"2>/dev/null;then
check_pass "YAML 语法合法"else
check_fail "YAML 语法错误，请检查缩进和格式"fifi# 检查必要字段forfieldin"server:""ai:""auth:";doifgrep-q"^$field""$CONFIG_FOUND";then
check_pass "必要字段存在: $field"else
check_fail "缺少必要字段: $field"fidone# 检查 Tab 字符ifgrep-Pq"\t""$CONFIG_FOUND"2>/dev/null;then
check_fail "配置文件包含 Tab 字符（YAML 必须用空格缩进）"if[["$AUTO_FIX"=="true"]];thensed-i's/\t/ /g'"$CONFIG_FOUND"
ok "[自动修复] 已将 Tab 替换为两个空格"fielse
check_pass "缩进字符正常（无 Tab）"fi# 检查 api_key 是否为占位符ifgrep-qE'api_key:\s*"(sk-xxxx|your-key|YOUR_KEY|placeholder)"'"$CONFIG_FOUND";then
check_fail "api_key 仍为占位符，请填写真实 API Key"fifi# ============================================================
section "③ 端口检查"# ============================================================check_port(){localport=$1localname=$2if ss -tlnp2>/dev/null |grep-q":$port "||\netstat-tlnp2>/dev/null |grep-q":$port ";then
check_pass "端口 $port ($name) 正在监听"else
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")
check_port "$HTTP_PORT""HTTP"
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
check_warn "端口 $port 被非 openclaw 进程占用: $PROC (PID: $PIDS)"fifidone# ============================================================
section "④ 服务状态检查"# ============================================================ifcommand-v systemctl &>/dev/null;thenif systemctl is-active --quiet openclaw 2>/dev/null;then
check_pass "systemd 服务运行中"UPTIME=$(systemctl show openclaw --property=ActiveEnterTimestamp |cut-d=-f2)
log "服务启动时间: $UPTIME"elif systemctl is-enabled --quiet openclaw 2>/dev/null;then
check_warn "systemd 服务已注册但未运行"else
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' ')
check_pass "openclaw 进程运行中 (PID: $PID, MEM: $MEM, CPU: ${CPU}%)"else
check_warn "未检测到运行中的 openclaw 进程"fi# ============================================================
section "⑤ 网络连通性检查"# ============================================================check_url(){localname=$1localurl=$2ifcurl-sf --max-time 5"$url"&>/dev/null;then
check_pass "网络可达: $name ($url)"else
check_fail "网络不可达: $name ($url)"fi}
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
check_pass "AI 接口域名可达: $DOMAIN"else
check_fail "AI 接口域名不可达: $DOMAIN（可能需要代理）"fififi# ============================================================
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
check_pass "磁盘使用率: ${DISK_USAGE}%"elif[["$DISK_USAGE"-lt95]];then
check_warn "磁盘使用率较高: ${DISK_USAGE}%"else
check_fail "磁盘使用率危险: ${DISK_USAGE}%，请立即清理"fi# 内存MEM_FREE=$(free-m|awk'/^Mem:/{print $7}')if[["$MEM_FREE"-gt256]];then
check_pass "可用内存: ${MEM_FREE}MB"elif[["$MEM_FREE"-gt64]];then
check_warn "可用内存较低: ${MEM_FREE}MB"else
check_fail "可用内存严重不足: ${MEM_FREE}MB"fi# ============================================================
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")
log "日志文件: $LOG_FILE"
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
log "从 journald 读取最近错误..."
journalctl -u openclaw.service -n10 --no-pager -p err 2>/dev/null |tail-10|whileIFS=read-r line;doecho-e" ${RED}▶${NC}$line"doneelse
check_warn "未找到日志文件"fi# ============================================================
section "⑧ Docker 环境检查（如适用）"# ============================================================ifcommand-vdocker&>/dev/null;thenifdocker info &>/dev/null;then
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")
check_pass "OpenClaw 容器运行中: $OPENCLAW_CONTAINER (Status: $STATUS)"else
check_warn "未检测到运行中的 OpenClaw 容器"fielse
check_warn "Docker 守护进程未运行或无权限访问"if[["$AUTO_FIX"=="true"]];thensudousermod-aGdocker$USER
ok "[自动修复] 已将 $USER 加入 docker 组，请重新登录生效"fififi# ============================================================
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]]

复制代码

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

复制代码

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

复制代码

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

旧字段名（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

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

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

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

日志信号	含义	处理建议
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	回复发送失败	→ 检查平台连接

日志信号	含义	处理建议
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	优雅退出	✅ 正常停止