前言
OpenClaw 的命令行工具 openclaw 是管理 AI 网关的主要入口。除了配置文件之外，许多行为可以通过启动参数临时覆盖或调整。本文将完整列出 openclaw 的所有子命令和参数选项，帮助你在不同场景下灵活使用。
全局选项
以下选项适用于所有子命令：
openclaw [全局选项] <子命令> [子命令选项]
| 选项 | 缩写 | 说明 |
|---|---|---|
--config <path> |
-c |
指定配置文件路径，覆盖默认的 ~/.openclaw/openclaw.json |
--log-level <level> |
-l |
日志级别：debug、info、warn、error |
--quiet |
-q |
静默模式，仅输出错误信息 |
--verbose |
-v |
详细输出模式，等同于 --log-level debug |
--no-color |
禁用终端彩色输出 | |
--version |
-V |
显示版本号 |
--help |
-h |
显示帮助信息 |
示例
# 使用自定义配置文件启动
openclaw -c /etc/openclaw/production.json gateway
# 以调试模式运行
openclaw -v gateway
# 查看版本
openclaw --version
gateway 命令
gateway 是最核心的命令，用于启动 AI 网关服务。
openclaw gateway [选项]
| 选项 | 缩写 | 默认值 | 说明 |
|---|---|---|---|
--port <number> |
-p |
18789 |
网关监听端口 |
--host <address> |
-H |
127.0.0.1 |
监听地址 |
--daemon |
-d |
以守护进程模式运行（后台运行） | |
--pid-file <path> |
~/.openclaw/openclaw.pid |
PID 文件路径 | |
--workers <number> |
-w |
0（自动） |
工作线程数 |
--timeout <ms> |
-t |
120000 |
请求超时（毫秒） |
--no-dashboard |
不启动内置 Dashboard | ||
--channels <list> |
全部 | 仅启用指定频道，逗号分隔 | |
--dry-run |
验证配置并模拟启动，不实际运行 |
常见用法
# 默认启动
openclaw gateway
# 指定端口和地址
openclaw gateway --port 8080 --host 0.0.0.0
# 后台运行
openclaw gateway --daemon
# 仅启用 Telegram 和 Discord 频道
openclaw gateway --channels telegram,discord
# 验证配置是否正确（不实际启动）
openclaw gateway --dry-run
守护进程管理
以 --daemon 模式启动后，可以通过以下命令管理：
# 查看运行状态
openclaw status
# 优雅停止
openclaw stop
# 强制停止
openclaw stop --force
# 重启
openclaw restart
# 热重载配置（不中断连接）
openclaw reload
dashboard 命令
单独启动 Web Dashboard，不启动网关服务。
openclaw dashboard [选项]
| 选项 | 缩写 | 默认值 | 说明 |
|---|---|---|---|
--port <number> |
-p |
18789 |
Dashboard 端口 |
--gateway <url> |
-g |
http://localhost:18789 |
连接的网关地址 |
--open |
-o |
启动后自动打开浏览器 | |
--no-auth |
跳过密码认证（仅限开发环境） |
示例
# 启动并打开浏览器
openclaw dashboard --open
# 连接到远程网关
openclaw dashboard --gateway https://remote-server:18789
# 使用自定义端口
openclaw dashboard --port 3000
doctor 命令
诊断工具，检查配置、依赖和连接状态。
openclaw doctor [选项]
| 选项 | 说明 |
|---|---|
--config-only |
仅检查配置文件语法和必填项 |
--connectivity |
测试所有已配置频道和模型的网络连通性 |
--remote |
测试外部访问是否正常（需要配置 webhookBase） |
--fix |
自动修复可修复的问题（如创建缺失的目录） |
输出示例
$ openclaw doctor
OpenClaw 诊断报告
==================
配置文件
✓ 配置文件格式正确
✓ 所有必填项已设置
模型连接
✓ Claude API 连接正常 (延迟: 230ms)
✓ OpenAI API 连接正常 (延迟: 180ms)
✗ Ollama 连接失败: ECONNREFUSED localhost:11434
频道状态
✓ Telegram Bot 已认证
✓ Discord Bot 已登录
- WhatsApp 未配置
系统环境
✓ Node.js v20.11.0
✓ 磁盘空间充足 (可用: 50GB)
✓ 内存充足 (可用: 4.2GB)
问题: 1
1. Ollama 服务未运行，请启动 Ollama 或禁用该模型配置
session 命令
管理对话会话数据。
openclaw session <子命令> [选项]
| 子命令 | 说明 |
|---|---|
list |
列出所有会话 |
stats |
查看会话统计信息 |
clear |
清除会话数据 |
export |
导出会话 |
compact |
手动触发压缩 |
trim |
修剪历史到指定条数 |
常用操作
# 列出所有活跃会话
openclaw session list
# 按 Agent 过滤
openclaw session list --agent default
# 查看某个会话的详细统计
openclaw session stats --session telegram_123456
# 清除某个会话
openclaw session clear --session telegram_123456
# 清除某个 Agent 的全部会话
openclaw session clear --agent default --all
# 导出会话为 JSON
openclaw session export --session telegram_123456 --format json
# 手动压缩
openclaw session compact --session telegram_123456
# 保留最近 20 条消息
openclaw session trim --session telegram_123456 --keep 20
mobile 命令
管理移动设备配对。
openclaw mobile <子命令> [选项]
| 子命令 | 说明 |
|---|---|
pair |
生成配对码或二维码 |
list |
列出已配对设备 |
remove |
移除设备 |
示例
# 生成文本配对码
openclaw mobile pair --generate
# 生成二维码
openclaw mobile pair --qrcode
# 列出设备
openclaw mobile list
# 移除指定设备
openclaw mobile remove mob_a3f2c1d8
# 移除所有设备
openclaw mobile remove --all
config 命令
查看和管理配置。
openclaw config <子命令> [选项]
| 子命令 | 说明 |
|---|---|
--dump |
输出当前生效的完整配置 |
--get <key> |
获取指定配置项的值 |
--set <key> <value> |
设置配置项 |
--edit |
使用系统编辑器打开配置文件 |
--init |
生成默认配置文件 |
--validate |
验证配置文件 |
示例
# 查看完整配置
openclaw config --dump
# 获取某个配置值
openclaw config --get gateway.port
# 设置配置值
openclaw config --set gateway.port 8080
# 初始化默认配置
openclaw config --init
# 打开编辑器
openclaw config --edit
access 命令
管理访问控制和权限。
openclaw access <子命令> [选项]
| 子命令 | 说明 |
|---|---|
allow <id> |
将用户或群组加入白名单 |
deny <id> |
将用户或群组加入黑名单 |
remove <id> |
从白名单或黑名单中移除 |
list |
列出当前的白名单和黑名单 |
pair-code |
生成配对码 |
log |
查看访问日志 |
示例
# 添加用户到白名单
openclaw access allow tg:123456789
# 拉黑用户
openclaw access deny tg:999888777
# 查看白名单
openclaw access list
# 查看访问日志
openclaw access log --tail 50
media 命令
管理媒体文件缓存。
openclaw media <子命令>
| 子命令 | 说明 |
|---|---|
cleanup |
清理媒体缓存 |
stats |
查看缓存统计 |
环境变量
部分启动参数也可以通过环境变量设置，环境变量的优先级高于配置文件但低于命令行参数：
| 环境变量 | 对应参数 |
|---|---|
OPENCLAW_CONFIG |
--config |
OPENCLAW_PORT |
--port |
OPENCLAW_HOST |
--host |
OPENCLAW_LOG_LEVEL |
--log-level |
OPENCLAW_DASHBOARD_PASSWORD |
Dashboard 密码 |
OPENCLAW_CLAUDE_API_KEY |
Claude API 密钥 |
OPENCLAW_OPENAI_API_KEY |
OpenAI API 密钥 |
OPENCLAW_TELEGRAM_TOKEN |
Telegram Bot Token |
优先级顺序（从高到低）：命令行参数 > 环境变量 > 配置文件 > 默认值。
systemd 服务配置
在 Linux 服务器上，推荐使用 systemd 管理 OpenClaw：
# /etc/systemd/system/openclaw.service
[Unit]
Description=OpenClaw AI Gateway
After=network.target
[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/local/bin/openclaw gateway --port 18789 --host 0.0.0.0
ExecReload=/usr/local/bin/openclaw reload
Restart=always
RestartSec=5
Environment=OPENCLAW_CONFIG=/etc/openclaw/openclaw.json
[Install]
WantedBy=multi-user.target
sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw
总结
openclaw 命令行工具提供了从启动网关到管理会话、从诊断问题到配置权限的完整功能集。日常使用中，gateway、doctor 和 session 是最常用的三个命令。记住命令行参数的优先级高于配置文件——这意味着你可以在不修改配置文件的情况下，通过参数临时调整网关行为，非常适合调试和测试。