🚀 快速入门

安装 OpenClaw

# 推荐：使用官方安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 或手动安装
npm install -g openclaw@latest
# 或
pnpm add -g openclaw@latest

初始化配置

# 运行交互式向导（推荐）
openclaw onboard

# 快速启动模式
openclaw onboard --flow quickstart

# 手动配置模式
openclaw onboard --flow manual

启动 Gateway

# 前台运行
openclaw gateway --port 18789

# 安装为系统服务（推荐生产环境）
openclaw gateway install

# 启动服务
openclaw gateway start

🔧 核心运维命令

状态检查

# 查看 Gateway 服务状态
openclaw gateway status

# 深度检查（包含 RPC 探测）
openclaw gateway status --deep

# 查看整体状态（通道 + 会话）
openclaw status

# 深度探测所有通道
openclaw status --deep

# 查看使用情况
openclaw status --usage

# JSON 格式输出
openclaw gateway status --json

健康检查

# 基础健康检查
openclaw gateway health --url ws://127.0.0.1:18789

# 运行医生诊断
openclaw doctor

# 深度诊断
openclaw doctor --deep

# 自动修复问题
openclaw doctor --repair

日志查看

# 查看日志（默认限制条数）
openclaw logs

# 持续跟踪日志
openclaw logs --follow

# 查看最近 500 条
openclaw logs --limit 500

# JSON 格式输出
openclaw logs --json

# 本地时区时间戳
openclaw logs --local-time

# 组合使用
openclaw logs --follow --local-time

🖥️ Gateway 管理

服务生命周期

# 安装服务（launchd/systemd/schtasks）
openclaw gateway install

# 启动服务
openclaw gateway start

# 停止服务
openclaw gateway stop

# 重启服务
openclaw gateway restart

# 卸载服务
openclaw gateway uninstall

# 查看服务状态
openclaw gateway status

运行 Gateway

# 前台运行（默认端口 18789）
openclaw gateway

# 指定端口
openclaw gateway --port 18789

# 详细日志
openclaw gateway --verbose

# 强制启动（杀死现有监听器）
openclaw gateway --force

# 允许未配置模式启动
openclaw gateway --allow-unconfigured

# 开发模式（自动创建配置）
openclaw gateway --dev

# 绑定模式选择
openclaw gateway --bind loopback    # 仅本地
openclaw gateway --bind lan         # 局域网
openclaw gateway --bind tailnet     # Tailscale
openclaw gateway --bind auto        # 自动

Tailscale 集成

# 通过 Tailscale Serve 暴露（仅 tailnet 内访问）
openclaw gateway --tailscale serve

# 通过 Tailscale Funnel 暴露（公开访问）
openclaw gateway --tailscale funnel

# 退出时重置 Tailscale 配置
openclaw gateway --tailscale-reset-on-exit

发现 Gateway

# 发现局域网内的 Gateway（Bonjour/mDNS）
openclaw gateway discover

# 指定超时时间
openclaw gateway discover --timeout 4000

# JSON 格式输出
openclaw gateway discover --json

# 提取 WebSocket URL
openclaw gateway discover --json | jq '.beacons[].wsUrl'

远程访问

# SSH 隧道访问
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

# 通过 SSH 探测远程 Gateway
openclaw gateway probe --ssh user@gateway-host

# 指定 SSH 密钥
openclaw gateway probe --ssh user@host --ssh-identity ~/.ssh/id_ed25519

# 自动选择第一个发现的 Gateway 作为 SSH 目标
openclaw gateway probe --ssh-auto

Gateway 探测

# 探测所有可达的 Gateway
openclaw gateway probe

# JSON 格式输出
openclaw gateway probe --json

# 仅探测配置的远程 Gateway
openclaw gateway probe --url ws://gateway-host:18789

RPC 调用

# 低级 RPC 调用
openclaw gateway call status

# 带参数调用
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'

📱 通道管理

通道状态

# 列出所有通道
openclaw channels list

# 查看通道状态
openclaw channels status

# 探测通道能力
openclaw channels capabilities

# 查看特定通道能力
openclaw channels capabilities --channel discord --target channel:123

# 查看通道日志
openclaw channels logs --channel all

添加/移除通道

# 添加 Telegram 通道
openclaw channels add --channel telegram --token <bot-token>

# 添加 WhatsApp 通道（交互式登录）
openclaw channels login --channel whatsapp

# 移除通道
openclaw channels remove --channel telegram --delete

# 登出通道
openclaw channels logout --channel whatsapp

名称解析

# Slack 频道/用户解析
openclaw channels resolve --channel slack "#general" "@jane"

# Discord 频道/用户解析
openclaw channels resolve --channel discord "My Server/#support" "@someone"

# Matrix 房间解析
openclaw channels resolve --channel matrix "Project Room"

💬 会话管理

会话列表

# 列出所有会话
openclaw sessions

# 指定 Agent
openclaw sessions --agent work

# 所有 Agent
openclaw sessions --all-agents

# 仅活跃会话（最近 120 分钟）
openclaw sessions --active 120

# JSON 格式输出
openclaw sessions --json

会话清理

# 预览清理（干运行）
openclaw sessions cleanup --dry-run

# 指定 Agent 清理
openclaw sessions cleanup --agent work --dry-run

# 清理所有 Agent
openclaw sessions cleanup --all-agents --dry-run

# 执行清理
openclaw sessions cleanup --enforce

# 保护特定活跃会话
openclaw sessions cleanup --enforce --active-key "agent:main:telegram:dm:123"

# JSON 格式输出
openclaw sessions cleanup --json

📡 节点管理

节点列表

# 列出所有节点
openclaw nodes list

# 仅显示已连接节点
openclaw nodes list --connected

# 最近 24 小时内连接过的节点
openclaw nodes list --last-connected 24h

# 节点状态
openclaw nodes status

# 待批准请求
openclaw nodes pending

# 批准请求
openclaw nodes approve <requestId>

节点调用

# 调用节点命令
openclaw nodes invoke --node <id|name|ip> --command <command> --params <json>

# 执行 shell 命令
openclaw nodes run --node <id|name|ip> --raw "git status"

# 指定工作目录
openclaw nodes run --node <id|name|ip> --cwd /path/to/dir --raw "ls -la"

# 设置环境变量
openclaw nodes run --node <id|name|ip> --env KEY=value --raw "echo $KEY"

# 需要屏幕录制权限
openclaw nodes run --node <id|name|ip> --needs-screen-recording --raw "screencapture"

# 指定 Agent（用于审批策略）
openclaw nodes run --agent main --node <id|name|ip> --raw "command"

⚙️ 配置管理

读取配置

# 获取配置值
openclaw config get browser.executablePath

# 获取嵌套配置
openclaw config get agents.defaults.workspace

# 获取数组配置
openclaw config get agents.list
openclaw config get agents.list[0].id

修改配置

# 设置配置值
openclaw config set browser.executablePath "/usr/bin/google-chrome"

# 设置嵌套配置
openclaw config set agents.defaults.heartbeat.every "2h"

# 设置数组配置
openclaw config set channels.whatsapp.groups '["*"]' --strict-json

# 设置数值（需要 --strict-json）
openclaw config set gateway.port 19001 --strict-json

# 删除配置
openclaw config unset tools.web.search.apiKey

配置向导

# 打开交互式配置向导
openclaw config
# 或
openclaw configure

🔄 更新与维护

检查更新

# 查看更新状态
openclaw update status

# JSON 格式输出
openclaw update status --json

# 指定超时
openclaw update status --timeout 10

执行更新

# 更新到最新版本
openclaw update

# 更新到 Beta 通道
openclaw update --channel beta

# 更新到 Dev 通道
openclaw update --channel dev

# 更新到 Stable 通道
openclaw update --channel stable

# 预览更新（不执行）
openclaw update --dry-run

# 更新后不重启 Gateway
openclaw update --no-restart

# JSON 格式输出
openclaw update --json

# 快捷方式
openclaw --update

更新通道说明

通道说明
stable稳定版，适合生产环境
beta测试版，新功能先行
dev开发版，最新代码（需要 git 仓库）

回滚版本

# 安装指定版本（全局安装）
npm install -g openclaw@<version>
# 或
pnpm add -g openclaw@<version>

# 查看当前发布版本
npm view openclaw version

# 源码安装回滚到指定日期
git fetch origin
git checkout "$(git rev-list -n 1 --before="2026-01-01" origin/main)"
pnpm install
pnpm build

🐛 故障排查

诊断命令

# 运行医生诊断
openclaw doctor

# 深度诊断
openclaw doctor --deep

# 自动修复
openclaw doctor --repair

# 非交互式模式
openclaw doctor --non-interactive

常见问题

Gateway 无法启动

# 检查端口占用
openclaw gateway --force

# 查看详细日志
openclaw gateway --verbose

# 检查配置
openclaw doctor

认证失败

# 检查 token/password 配置
openclaw config get gateway.auth

# macOS: 检查 launchctl 环境变量
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

# 如有冲突，清除环境变量
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

通道连接问题

# 深度探测所有通道
openclaw status --deep

# 查看通道日志
openclaw channels logs --channel <channel-name>

# 重新登录通道
openclaw channels logout --channel <channel-name>
openclaw channels login --channel <channel-name>

会话问题

# 清理会话存储
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

# 重置会话
openclaw reset

日志位置

# Gateway 日志目录（默认）
~/.openclaw/logs/

# 实时查看日志
openclaw logs --follow

# 查看最近日志
openclaw logs --limit 1000

📋 常用命令速查表

命令说明
openclaw gateway status查看 Gateway 状态
openclaw gateway start/stop/restart服务控制
openclaw logs --follow实时日志
openclaw doctor健康诊断
openclaw status --deep深度状态检查
openclaw channels list通道列表
openclaw sessions会话列表
openclaw nodes list节点列表
openclaw update更新系统
openclaw config get/set配置管理

🔐 安全建议

  1. 生产环境务必配置认证

    openclaw config set gateway.auth.mode "token"
openclaw config set gateway.auth.token "your-secure-token"

  2. 限制 DM 访问

    openclaw config set channels.whatsapp.allowFrom '["+8613800138000"]'

  3. 启用沙箱模式

    openclaw config set agents.defaults.sandbox.mode "non-main"

  4. 定期运行诊断

    openclaw doctor --deep

📚 相关资源