1. 基础信息命令

💡 新手提示：第一次使用建议先执行 openclaw --version 确认安装成功。

2. 安装与初始化

完成 OpenClaw 首次安装、依赖配置及全流程初始化。

2.1 首次安装

# 全局安装 OpenClaw（需要 Node.js 18+）
npm install -g openclaw
# 或使用 pnpm
pnpm add -g openclaw

2.2 初始化配置

# 安装所需依赖
openclaw install
# 全流程引导配置（推荐新手使用）
openclaw onboard
# 强制重新初始化（配置异常时重置）
openclaw onboard --force

2.3 健康检查

# 执行完整健康检查
openclaw doctor
# 检查并自动修复问题
openclaw doctor --fix
# 快速检查
openclaw check

💡 新手提示：openclaw onboard 会引导你完成模型配置、渠道登录等所有必要设置。

3. 网关管理命令

管理 OpenClaw 核心网关服务，包括启停、调试、设置开机自启。

3.1 基础操作

3.2 调试模式

# 前台运行并显示详细日志（排查问题用）
openclaw gateway run --verbose
# 前台运行并指定端口
openclaw gateway run --port 18789

3.3 系统服务配置

# 安装为系统服务（开机自启）
openclaw gateway install
# 卸载系统服务
openclaw gateway uninstall

💡 新手提示：生产环境建议执行 openclaw gateway install 实现开机自启。

4. 配置管理命令

查看、设置、重置 OpenClaw 各项配置（网关、模型、渠道等）。

4.1 查看配置

# 查看所有配置列表
openclaw config list
# 查看全部配置详情
openclaw config get all
# 查看特定配置
openclaw config get gateway      # 网关配置
openclaw config get models       # 模型配置
openclaw config get channels     # 渠道配置
openclaw config get agents       # 智能体配置

4.2 设置配置

# 设置网关端口
openclaw config set gateway.port 18789
# 设置网关主机（允许外部访问）
openclaw config set gateway.host 0.0.0.0
# 设置主智能体模型
openclaw config set agents.main.model "claude-3-5-sonnet"
# 设置 OpenAI API 密钥
openclaw config set models.openai.api_key "sk-xxxx"
# 设置 OpenAI 基础地址
openclaw config set models.openai.base_url "https://api.openai.com/v1"

4.3 取消/重置配置

# 取消某个配置项
openclaw config unset gateway.port
# 重置所有配置为默认值
openclaw config reset

💡 新手提示：修改配置后通常需要重启网关 openclaw gateway restart 才能生效。

5. 模型管理命令

查看、添加、删除、设置默认模型，管理 OpenClaw 关联的所有模型。

5.1 查看模型

# 查看所有已关联模型
openclaw models list
# 查看模型运行状态
openclaw models status
# 扫描可关联的模型
openclaw models scan
# 探测模型可用性
openclaw models probe

5.2 设置模型

# 设置默认模型
openclaw models set default "gpt-4o"
# 添加 OpenAI 模型
openclaw models add openai --api_key sk-xxxx --base_url https://api.openai.com/v1
# 删除已关联的模型
openclaw models remove openai

💡 新手提示：国内用户建议使用阿里云百炼、DeepSeek 等国内模型提供商。

6. 渠道管理命令

管理各类渠道/机器人的登录、登出，查看渠道状态。

6.1 查看渠道

# 查看所有已配置渠道
openclaw channels list
# 查看渠道运行状态
openclaw channels status
# 探测渠道连接状态
openclaw channels probe

6.2 登录渠道

# 登录 Telegram
openclaw channels login telegram
# 登录 Discord
openclaw channels login discord
# 登录 WhatsApp
openclaw channels login whatsapp
# 登录飞书
openclaw channels login feishu
# 登录 QQ
openclaw channels login qqbot

6.3 登出渠道

# 登出单个渠道
openclaw channels logout telegram
# 登出所有渠道
openclaw channels logout all

💡 新手提示：首次登录需要按提示完成扫码或 Token 配置。

7. 智能体管理

创建、删除、切换智能体，与智能体进行交互。

7.1 查看智能体

# 查看所有智能体
openclaw agent list
# 查看智能体状态
openclaw agent status

7.2 创建/删除智能体

# 创建新智能体
openclaw agent create myagent
# 删除智能体
openclaw agent delete myagent

7.3 切换与交互

# 切换默认智能体
openclaw agent use main
# 与智能体简单聊天
openclaw agent chat "你好"
# 向智能体发送指令
openclaw agent --message "帮我写个启动脚本"

💡 新手提示：默认智能体是 main，一般不需要额外创建。

8. 插件与技能

管理 OpenClaw 插件和技能，扩展工具功能。

8.1 插件管理

# 查看所有已安装插件
openclaw plugins list
# 安装插件
openclaw plugins install [插件名]
# 卸载插件
openclaw plugins uninstall [插件名]
# 启用插件
openclaw plugins enable [插件名]
# 禁用插件
openclaw plugins disable [插件名]

8.2 技能管理

# 查看所有可用技能
openclaw skills list
# 启用指定技能
openclaw skills enable [技能名]
# 禁用指定技能
openclaw skills disable [技能名]
# 查看技能详情
openclaw skills info [技能名]

💡 新手提示：常用插件包括 mem9（记忆系统）、openclaw-qqbot（QQ 机器人）等。

9. 日志与调试

查看系统日志、筛选错误信息，排查运行异常。

9.1 查看日志

# 查看所有日志
openclaw logs
# 实时查看日志（持续输出）
openclaw logs -f
# 只看错误日志
openclaw logs --error
# 只看网关日志
openclaw logs --gateway
# 只看渠道日志
openclaw logs --channels

9.2 调试技巧

# 查看最近 50 行日志
openclaw logs --tail 50
# 查看特定时间段日志
openclaw logs --since "2026-03-27 10:00"

💡 新手提示：遇到问题先执行 openclaw logs --error 查看错误信息。

10. 浏览器自动化

控制浏览器进行自动化操作，包括启动、打开网页、截图等。

10.1 基础操作

# 启动浏览器服务
openclaw browser start
# 停止浏览器服务
openclaw browser stop
# 打开指定网页
openclaw browser open https://baidu.com

10.2 自动化操作

# 页面截图
openclaw browser screenshot
# 在输入框输入内容
openclaw browser type "搜索内容"
# 点击按钮
openclaw browser click "按钮文字"

💡 新手提示：浏览器自动化需要安装 Chrome 并允许程序控制。

11. 定时任务管理

管理定时任务和心跳唤醒。

11.1 查看任务

# 查看所有定时任务
openclaw cron list
# 查看任务状态
openclaw cron status

11.2 管理任务

# 添加新任务
openclaw cron add --schedule "0 9 * * 1" --command "check-calendar"
# 更新现有任务
openclaw cron update [任务 ID] --schedule "新时间"
# 删除任务
openclaw cron remove [任务 ID]
# 手动执行任务
openclaw cron run [任务 ID]
# 触发心跳
openclaw cron wake

💡 新手提示：cron 表达式格式：分钟 小时 日期 月份 星期

12. 工作区管理

管理 OpenClaw 工作区，查看路径、清理缓存等。

12.1 工作区操作

# 查看工作区列表
openclaw workspace list
# 查看当前工作区路径
openclaw workspace path
# 清理工作区缓存
openclaw workspace clean

12.2 工作区文件

💡 新手提示：工作区默认在 ~/.openclaw/workspace。

13. 密钥与权限

管理 OpenClaw 相关权限密钥。

13.1 密钥管理

# 查看所有已存储密钥
openclaw keys list
# 添加密钥
openclaw keys add mykey "密钥内容"
# 删除密钥
openclaw keys remove mykey

13.2 安全建议

  • API 密钥建议通过 openclaw keys add 存储，不要明文写在配置文件
  • 生产环境建议启用沙箱模式
  • 定期轮换敏感密钥

💡 新手提示：密钥存储在安全位置，不会出现在日志中。

14. 高频组合命令

整合日常最常用的完整操作流程，一键完成配置。

14.1 完整启动流程

# 1. 设置网关端口
openclaw config set gateway.port 18789
# 2. 设置模型 API 密钥
openclaw config set models.openai.api_key "sk-xxxx"
# 3. 探测模型可用性
openclaw models probe
# 4. 登录渠道（按需选择）
openclaw channels login telegram
# 5. 安装为系统服务
openclaw gateway install
# 6. 启动网关
openclaw gateway start
# 7. 查看状态
openclaw gateway status
# 8. 实时查看日志
openclaw logs -f

14.2 快速重启流程

# 重启网关并查看日志
openclaw gateway restart && openclaw logs -f

14.3 故障修复流程

# 健康检查并自动修复
openclaw doctor --fix
# 重启网关
openclaw gateway restart
# 查看错误日志
openclaw logs --error

💡 新手提示：建议将常用命令保存为脚本文件。

15. 故障排查速查

15.1 常见问题

15.2 排查步骤

# 1. 检查网关状态
openclaw gateway status
# 2. 查看错误日志
openclaw logs --error
# 3. 健康检查
openclaw doctor
# 4. 自动修复
openclaw doctor --fix
# 5. 重启网关
openclaw gateway restart

16. 会话管理命令

管理 OpenClaw 智能体会话，包括查看、历史、消息发送等。

16.1 查看会话

# 查看所有活跃会话
openclaw sessions list
# 查看最近 10 个会话
openclaw sessions list --limit 10
# 查看特定类型的会话
openclaw sessions list --kind direct    # 只看私信会话
openclaw sessions list --kind cron      # 只看定时任务会话

16.2 会话历史

# 查看会话历史消息
openclaw sessions history [sessionKey]
# 查看最近 50 条消息
openclaw sessions history [sessionKey] --limit 50
# 包含工具调用的历史
openclaw sessions history [sessionKey] --include-tools

16.3 会话操作

# 向会话发送消息
openclaw sessions send [sessionKey] "消息内容"
# 生成子智能体会话（执行特定任务）
openclaw sessions spawn --task "分析这个日志文件"
# 查看会话状态
openclaw session status [sessionKey]

16.4 会话清理

# 清理 30 天前的旧会话
openclaw sessions clean --older-than 30d
# 清理所有已结束的会话
openclaw sessions clean --finished
# 查看会话统计
openclaw sessions stats

💡新手提示：sessionKey 格式如 agent:main:qqbot:direct:7a026db...

17. 安全与审计命令

检查 OpenClaw 安全配置，执行安全审计。

17.1 安全检查

# 执行安全审计
openclaw security audit
# 深度安全检查（包含所有探针）
openclaw security audit --deep
# 快速安全检查
openclaw check

17.2 查看安全报告

# 查看安全报告摘要
openclaw security report
# 查看详细安全报告
openclaw security report --verbose
# 导出安全报告
openclaw security report --output report.json

17.3 常见安全警告

17.4 安全配置建议

# 启用沙箱模式（生产环境推荐）
openclaw config set agents.defaults.sandbox.enabled true
# 限制工具权限
openclaw config set tools.profile "coding"
# 禁止高风险命令
openclaw config set gateway.nodes.denyCommands '["camera.snap", "screen.record"]'

💡 新手提示：定期执行 openclaw security audit 检查安全状态。

18. 节点与设备管理

管理连接的 iOS/Android 设备节点。

18.1 查看节点

# 查看所有已连接节点
openclaw nodes list
# 查看节点详情
openclaw nodes info [nodeId]
# 查看节点状态
openclaw nodes status

18.2 设备配对

# 生成配对码（用于手机 App 连接）
openclaw pairing generate
# 查看配对请求
openclaw pairing requests
# 批准配对请求
openclaw pairing approve [请求 ID]
# 拒绝配对请求
openclaw pairing reject [请求 ID]

18.3 节点操作

# 断开节点连接
openclaw nodes disconnect [nodeId]
# 重启节点
openclaw nodes restart [nodeId]
# 查看节点日志
openclaw nodes logs [nodeId]

18.4 设备控制命令

# 手机拍照（需授权）
openclaw camera snap
# 屏幕录制
openclaw screen record
# 发送通知到设备
openclaw notify "消息内容" --node [nodeId]

💡 新手提示：节点配对需要在手机 App 扫描配对码或输入 setup code。

19. 媒体处理命令

处理图片、语音、视频等媒体文件。

19.1 图片处理

# 分析图片内容
openclaw image analyze [图片路径]
# 图片描述
openclaw image describe [图片路径]
# 提取图片中的文字（OCR）
openclaw image ocr [图片路径]

19.2 语音处理

# 语音转文字（需配置 STT）
openclaw tts transcribe [音频文件]
# 文本转语音
openclaw tts speak "文本内容"
# 使用特定语音合成
openclaw tts speak "文本" --voice "alloy"

19.3 视频处理

# 提取视频帧
openclaw video frames [视频路径] --output [输出目录]
# 截取视频片段
openclaw video clip [视频路径] --start 00:01:00 --end 00:02:00

19.4 媒体上传

# 上传媒体文件到渠道
openclaw media upload [文件路径] --channel telegram
# 发送图片消息
openclaw message send --channel telegram --media [图片路径] "配文"

💡 新手提示：TTS/STT 功能需要配置相应的 API（如 OpenAI、Azure 等）。

20. Hooks 与 Webhooks

管理事件钩子和 Webhook 回调。

20.1 查看 Hooks

# 查看所有已配置 Hooks
openclaw hooks list
# 查看 Hook 详情
openclaw hooks info [HookID]
# 查看 Hook 日志
openclaw hooks logs [HookID]

20.2 添加 Webhook

# 添加通用 Webhook
openclaw hooks add https://your-server.com/webhook
# 添加特定事件的 Webhook
openclaw hooks add [URL] --event message.received
openclaw hooks add [URL] --event agent.response
# 添加带认证的 Webhook
openclaw hooks add [URL] --header "Authorization: Bearer xxx"

20.3 管理 Hooks

# 启用 Hook
openclaw hooks enable [HookID]
# 禁用 Hook
openclaw hooks disable [HookID]
# 删除 Hook
openclaw hooks remove [HookID]
# 测试 Hook
openclaw hooks test [HookID]

20.4 可用事件类型

💡 新手提示：Webhooks 适合与外部系统集成（如自动化工具、监控系统）。

21. 高级配置命令

配置导入导出、验证等高级操作。

21.1 配置备份

# 导出当前配置
openclaw config export > backup.json
# 导出配置到文件
openclaw config export --output backup.json
# 导出特定配置项
openclaw config export gateway > gateway-config.json

21.2 配置恢复

# 从文件导入配置
openclaw config import backup.json
# 导入并重启网关
openclaw config import backup.json --restart
# 验证配置文件
openclaw config validate backup.json

21.3 配置验证

# 验证当前配置
openclaw validate
# 验证配置文件
openclaw validate config.json
# 检查配置冲突
openclaw validate --check-conflicts

21.4 配置比较

# 比较两个配置文件
openclaw config diff config1.json config2.json
# 查看配置变更历史
openclaw config history

💡 新手提示：升级 OpenClaw 前建议先 openclaw config export 备份配置。

22. 性能监控命令

监控系统资源使用和性能指标。

22.1 资源监控

# 查看资源使用情况
openclaw metrics
# 查看 CPU/内存使用
openclaw metrics system
# 查看网关性能
openclaw metrics gateway

22.2 Token 统计

# 查看 Token 使用统计
openclaw usage stats
# 查看今日 Token 消耗
openclaw usage today
# 查看本月 Token 消耗
openclaw usage month
# 按模型查看 Token 使用
openclaw usage by-model

22.3 会话统计

# 查看会话统计
openclaw sessions stats
# 查看活跃会话数
openclaw sessions count
# 查看会话 Token 消耗排行
openclaw sessions top --by tokens

22.4 性能优化建议

# 获取性能优化建议
openclaw metrics recommendations
# 查看慢查询日志
openclaw logs --slow
# 监控实时性能
openclaw metrics watch

💡 新手提示：Token 消耗过高时，可以调整模型或启用缓存。

23. 批量操作命令

执行批量管理任务。

23.1 批量清理

# 清理 30 天前的会话
openclaw sessions clean --older-than 30d
# 清理所有临时文件
openclaw workspace clean --all
# 清理缓存的媒体文件
openclaw media clean --cache

23.2 批量操作

# 批量禁用所有插件
openclaw plugins disable --all
# 批量启用指定插件
openclaw plugins enable --list plugin1,plugin2,plugin3
# 批量更新所有插件
openclaw plugins update --all

23.3 批量重置

# 重置智能体状态
openclaw agent reset main
# 重置所有渠道配置
openclaw channels reset --all
# 重置模型配置
openclaw models reset

23.4 批量导出

# 导出所有会话历史
openclaw sessions export --all --output ./sessions/
# 导出所有日志
openclaw logs export --output ./logs/
# 导出完整备份
openclaw backup --full --output ./backup/

💡 新手提示：批量操作前建议先备份重要数据。

24. ACP 协议命令（开发者）

Agent Control Protocol 相关命令，适合开发者使用。

24.1 ACP 基础

# 查看 ACP 状态
openclaw acp status
# 查看 ACP 连接
openclaw acp connections
# 查看 ACP 日志
openclaw acp logs

24.2 ACP 调试

# 启动 ACP 调试模式
openclaw acp debug
# 发送 ACP 测试消息
openclaw acp test --message "hello"
# 查看 ACP 协议版本
openclaw acp version

24.3 ACP 配置

# 设置 ACP 端点
openclaw acp config set endpoint [URL]
# 设置 ACP 认证
openclaw acp config set token [TOKEN]
# 查看 ACP 配置
openclaw acp config get

💡 新手提示：ACP 协议主要用于高级开发场景，普通用户无需配置。

附录 A：命令缩写对照

附录 B：配置文件位置

附录 C：环境变量

附录 D：高级玩法

D.1 自定义命令别名

在 shell 配置文件中添加：

# bash/zsh (~/.bashrc 或 ~/.zshrc)
alias oc='openclaw'
alias ocg='openclaw gateway'
alias ocs='openclaw status'
alias ocl='openclaw logs -f'
# PowerShell (profile.ps1)
Set-Alias oc openclaw
Set-Alias ocg "openclaw gateway"
Set-Alias ocs "openclaw status"

D.2 自动化脚本示例

每日健康检查脚本（daily-check.sh）：

#!/bin/bash
echo "=== OpenClaw 每日检查 ==="
openclaw gateway status
openclaw check
openclaw security audit
echo "=== 检查完成 ==="

自动备份脚本（backup.sh）：

#!/bin/bash
DATE=$(date +%Y%m%d)
openclaw config export --output ~/backups/openclaw-$DATE.json
openclaw sessions export --all --output ~/backups/sessions-$DATE/
echo "备份完成：openclaw-$DATE.json"

D.3 性能调优建议

D.4 生产环境检查清单

  • 启用沙箱模式
  • 配置日志轮转
  • 设置监控告警
  • 定期备份配置
  • 限制外部访问（防火墙）
  • 使用 HTTPS（反向代理）
  • 定期安全审计
  • 监控 Token 用量

附录 E：故障排查速查表

E.1 网关问题

E.2 渠道问题

E.3 模型问题

E.4 性能问题

好了，以上就是今天的分享，欢迎关注、点赞、转发一键三连。有任何问题和需求，请在评论区留言，回见！