OpenClaw 常用命令速查手册

yuzhucu

222人浏览 · 2026-03-08 23:04:34

yuzhucu · 2026-03-08 23:04:34 发布

OpenClaw 常用命令速查手册

从安装配置到日常维护的完整命令参考

📑 目录

安装与初始化
配置管理
Gateway 管理
智能体管理
飞书配置
日志查看
运维监控
故障排查
快捷脚本

安装与初始化

安装 OpenClaw

1 、🚀 一键安装命令

macOS / Linux
在终端中直接运行以下命令：

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell)
请务必以管理员身份打开 PowerShell，然后运行

iwr -useb https://openclaw.ai/install.ps1 | iex

2、使用 npm 安装（推荐）

#  使用 npm 安装（推荐）
npm install -g openclaw

npm install -g openclaw@latest

# 验证安装
openclaw --version

# 查看帮助
openclaw --help

3、源码安装 (Git)

克隆仓库

git clone `https://github.com/openclaw/openclaw.git`

然后依次执行

pnpm install、pnpm build、pnpm link --global

4、 Docker 追求环境一致性，避免依赖冲突

参考官方文档编写 docker-compose.yml 文件，并使用 docker compose up --build 启动

升级更新

1. 一键安装脚本（推荐）

# 运行官方安装脚本进行升级
curl -fsSL https://openclaw.ai/install.sh | bash

说明：如果不想重新运行设置向导，可以在命令末尾加上 --no-onboard 参数

2. 全局安装用户（通过 npm / pnpm）

如果你当初是通过 npm i -g openclaw 安装的，可以使用以下命令直接更新

# 使用 npm
npm i -g openclaw@latest

# 或使用 pnpm
pnpm add -g openclaw@latest

3. 源码安装用户（通过 Git）

如果你是通过克隆 Git 仓库安装的，官方强烈建议使用 OpenClaw 自带的更新命令，它能自动处理拉取代码、安装依赖、构建项目等步骤

# 运行内置更新命令
openclaw update

进阶技巧：

切换渠道：如果你想尝鲜测试版或开发版，可以使用 --channel 参数，例如 openclaw update --channel beta。

跳过重启：更新后不想立即重启服务，可以加上 --no-restart 参数

升级后的必要检查
无论使用哪种方式升级，都强烈建议执行以下命令：

1、健康检查与自动修复：新版可能变更了配置项或环境变量，运行此命令可自动检测并修复常见问题。

openclaw doctor --fix

重启网关服务：让更新生效。

openclaw gateway restart

验证状态：确认服务已正常运行。

openclaw status

初始化配置

安装脚本执行完毕后，OpenClaw 并未完全就绪，你还需要完成以下两个关键步骤：

1. 运行初始化向导

这是配置 OpenClaw 的核心步骤。在终端中执行以下命令，它会引导你完成模型配置（如 OpenAI、Kimi API Key 的填写）、网关设置等

openclaw onboard --install-daemon

2. 验证安装

配置完成后，运行健康检查命令，如果看到 OK 或正常运行状态，说明你的"龙虾"已经准备就绪

openclaw doctor

# 交互式配置向导
openclaw configure

# 配置特定模块
openclaw configure --section model      # 配置模型
openclaw configure --section channel    # 配置通道
openclaw configure --section gateway    # 配置 Gateway
openclaw configure --section web        # 配置网络搜索

检查安装状态

# 查看完整状态
openclaw status

# 查看 Gateway 状态
openclaw gateway status

# 诊断问题
openclaw doctor

配置管理

配置文件位置

# 主配置文件
~/.openclaw/openclaw.json

# 多智能体配置
~/.openclaw/gateway-xxx.json

# Agent 配置
~/.openclaw/agents/<name>/agent/agent.json

# 工作区
~/.openclaw/workspace/

配置操作

# 查看配置值
openclaw config get agents.defaults.model.primary

# 设置配置值
openclaw config set agents.defaults.model.primary custom-coding-dashscope-aliyuncs-com/qwen3.5-plus

# 验证配置
openclaw config validate

# 导出配置
openclaw config export > backup.json

# 导入配置
openclaw config import backup.json

配置修复

# 自动修复配置问题
openclaw doctor --fix

# 重置配置（谨慎使用）
openclaw reset

Gateway 管理

启动 Gateway

# 使用默认配置启动
openclaw gateway run

# 指定端口
openclaw gateway run --port 18789

# 使用独立配置启动
OPENCLAW_CONFIG_PATH=~/.openclaw/gateway-finance.json \
  openclaw gateway run --port 18790

# 后台运行
nohup openclaw gateway run --port 18789 > /tmp/gateway.log 2>&1 &

# 前台运行（调试用）
openclaw gateway run --verbose

停止 Gateway

# 优雅停止
openclaw gateway stop

# 强制停止（找到 PID）
kill $(lsof -i :18789 | grep LISTEN | awk '{print $2}')

# 停止所有 Gateway
pkill -f "openclaw gateway"

重启 Gateway

# 使用服务管理（如已安装）
openclaw gateway restart

# 手动重启
openclaw gateway stop && openclaw gateway start

# 后台重启
kill $(lsof -i :18789 | grep LISTEN | awk '{print $2}') && \
  nohup openclaw gateway run --port 18789 > /tmp/gateway.log 2>&1 &

Gateway 服务管理

# 安装为系统服务（macOS launchd）
openclaw gateway install

# 卸载服务
openclaw gateway uninstall

# 查看服务状态
openclaw gateway status

# 启动服务
openclaw gateway start

# 停止服务
openclaw gateway stop

智能体管理

查看智能体

# 列出所有智能体
openclaw agents list

# 查看路由绑定
openclaw agents bindings

# 查看智能体详情
openclaw agents list --deep

创建智能体

# 添加新智能体
openclaw agents add <name> \
  --agent-dir ~/.openclaw/agents/<name> \
  --workspace ~/.openclaw/workspace \
  --model custom-coding-dashscope-aliyuncs-com/qwen3.5-plus \
  --non-interactive

# 添加并绑定通道
openclaw agents add finance-assistant \
  --bind feishu:cli_a9265f0443b85cb2 \
  --model custom-coding-dashscope-aliyuncs-com/qwen3.5-plus

绑定智能体

# 为智能体添加通道绑定
openclaw agents bind \
  --agent finance-assistant \
  --bind feishu:cli_a9265f0443b85cb2

# 移除绑定
openclaw agents unbind \
  --agent finance-assistant \
  --bind feishu

删除智能体

# 删除智能体（谨慎使用）
openclaw agents delete <name>

# 删除并清理工作区
openclaw agents delete <name> --cleanup

飞书配置

飞书应用管理

# 查看飞书通道状态
openclaw channels status

# 探测飞书连接
openclaw channels status --probe

# 查看飞书配置
openclaw config get channels.feishu

飞书机器人测试

# 发送测试消息（需要配置）
openclaw feishu send --chat-id <chat_id> --message "测试"

# 查看飞书应用信息
openclaw feishu app-info --app-id cli_xxxxx

飞书事件配置

在飞书开放平台配置（非命令行）：

访问 https://open.feishu.cn/
进入应用 → 事件与回调
添加事件：接收消息 v2.0 (im.message.receive_v1)
选择长连接模式
保存并发布

日志查看

Gateway 日志

# 实时查看日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 查看最近 100 行
tail -100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 查看错误
grep -i "error\|failed" /tmp/openclaw/openclaw-*.log

# 查看消息接收
grep "received message" /tmp/openclaw/openclaw-*.log

# 查看 WebSocket 连接
grep "WebSocket" /tmp/openclaw/openclaw-*.log

独立 Gateway 日志

# 金融助手
tail -f /tmp/gateway-finance.log

# 办公助手
tail -f /tmp/gateway-office.log

# 编程助手
tail -f /tmp/gateway-programming.log

# 所有日志
tail -f /tmp/gateway-*.log

日志过滤

# 按时间过滤
grep "2026-03-20T19:" /tmp/gateway-finance.log

# 按级别过滤
grep "\[error\]" /tmp/gateway-finance.log
grep "\[warn\]" /tmp/gateway-finance.log
grep "\[info\]" /tmp/gateway-finance.log

# 组合过滤
grep "received message" /tmp/gateway-finance.log | tail -20

运维监控

进程监控

# 查看 Gateway 进程
ps aux | grep "openclaw gateway" | grep -v grep

# 查看端口占用
lsof -i :18789,18790,18800,18801 | grep LISTEN

# 查看特定端口
lsof -i :18789 | grep LISTEN

# 查看 PID
pgrep -f "openclaw gateway"

状态检查脚本

#!/bin/bash
# check-status.sh

echo "=== OpenClaw 状态检查 ==="
echo ""

# 检查 Gateway 进程
echo "📊 Gateway 进程:"
ps aux | grep "openclaw gateway" | grep -v grep | awk '{print "  PID:", $2, "CPU:", $3"%", "MEM:", $4"%"}'
echo ""

# 检查端口
echo "🔌 端口状态:"
for port in 18789 18790 18800 18801; do
  pid=$(lsof -i :$port | grep LISTEN | awk '{print $2}')
  if [ -n "$pid" ]; then
    echo "  ✅ 端口 $port: 运行中 (PID: $pid)"
  else
    echo "  ❌ 端口 $port: 未运行"
  fi
done
echo ""

# 检查日志文件
echo "📁 日志文件:"
ls -lh /tmp/gateway-*.log 2>/dev/null | awk '{print "  " $9 ": " $5}'

性能监控

# 查看资源占用
top -pid $(pgrep -f "openclaw gateway")

# 查看内存占用
ps aux | grep "openclaw gateway" | awk '{sum+=$6} END {print "总内存:", sum/1024, "MB"}'

# 查看文件描述符
lsof -p $(pgrep -f "openclaw gateway") | wc -l

健康检查

# Gateway 健康检查
openclaw gateway health

# 探测 Gateway
openclaw gateway probe

# 完整诊断
openclaw doctor --deep

故障排查

常见问题诊断

# 问题 1: Gateway 无法启动
# 检查端口占用
lsof -i :18789

# 检查配置
openclaw doctor

# 查看详细错误
openclaw gateway run --verbose

# 问题 2: 飞书消息无响应
# 检查 WebSocket 连接
grep "WebSocket" /tmp/gateway.log

# 检查事件订阅
grep "received message" /tmp/gateway.log

# 检查应用配置
openclaw config get channels.feishu

# 问题 3: 配置无效
# 验证 JSON 格式
cat ~/.openclaw/openclaw.json | python3 -m json.tool

# 自动修复
openclaw doctor --fix

# 问题 4: 智能体无响应
# 检查智能体状态
openclaw agents list

# 检查路由绑定
openclaw agents bindings

# 重启智能体 Gateway
kill $(lsof -i :18790 | grep LISTEN | awk '{print $2}')

调试模式

# 启用详细日志
openclaw gateway run --verbose

# 启用 WebSocket 日志
openclaw gateway run --ws-log full

# 启用调试模式
openclaw gateway run --debug

# 查看实时日志
tail -f /tmp/gateway.log | grep -E "error|warn|info"

恢复操作

# 恢复备份配置
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

# 重置智能体
openclaw agents delete <name>
openclaw agents add <name> --non-interactive

# 清理缓存
rm -rf ~/.openclaw/cache/*

# 重新初始化
openclaw configure

快捷脚本

一键启动所有智能体

#!/bin/bash
# start-all.sh

echo "🚀 启动所有 OpenClaw 智能体..."

# 主应用
OPENCLAW_CONFIG_PATH=~/.openclaw/gateway-main.json \
  nohup openclaw gateway run --port 18789 > /tmp/gateway-main.log 2>&1 &
echo "✅ 主应用启动 (端口 18789)"

# 金融助手
OPENCLAW_CONFIG_PATH=~/.openclaw/gateway-finance.json \
  nohup openclaw gateway run --port 18790 > /tmp/gateway-finance.log 2>&1 &
echo "✅ 金融助手启动 (端口 18790)"

# 办公助手
OPENCLAW_CONFIG_PATH=~/.openclaw/gateway-office.json \
  nohup openclaw gateway run --port 18800 > /tmp/gateway-office.log 2>&1 &
echo "✅ 办公助手启动 (端口 18800)"

# 编程助手
OPENCLAW_CONFIG_PATH=~/.openclaw/gateway-programming.json \
  nohup openclaw gateway run --port 18801 > /tmp/gateway-programming.log 2>&1 &
echo "✅ 编程助手启动 (端口 18801)"

sleep 3
echo ""
echo "📊 状态检查:"
lsof -i :18789,18790,18800,18801 | grep LISTEN

一键停止所有智能体

#!/bin/bash
# stop-all.sh

echo "⏹️  停止所有 OpenClaw 智能体..."

for port in 18789 18790 18800 18801; do
  pid=$(lsof -i :$port | grep LISTEN | awk '{print $2}')
  if [ -n "$pid" ]; then
    kill $pid
    echo "⏹️  已停止端口 $port (PID: $pid)"
  fi
done

sleep 2
echo "✅ 所有智能体已停止"

一键重启

#!/bin/bash
# restart-all.sh

PORTS=(18789 18790 18800 18801)
NAMES=(main finance office programming)

echo "🔄 重启所有 OpenClaw 智能体..."

for i in "${!PORTS[@]}"; do
  PORT=${PORTS[$i]}
  NAME=${NAMES[$i]}
  
  # 停止
  PID=$(lsof -i :${PORT} | grep LISTEN | awk '{print $2}')
  if [ -n "$PID" ]; then
    kill $PID
    echo "⏹️  已停止 ${NAME} (PID: $PID)"
  fi
  
  sleep 1
  
  # 启动
  OPENCLAW_CONFIG_PATH=~/.openclaw/gateway-${NAME}.json \
    nohup openclaw gateway run --port ${PORT} > /tmp/gateway-${NAME}.log 2>&1 &
  echo "▶️  已启动 ${NAME} (端口：${PORT})"
done

sleep 3
echo ""
echo "✅ 重启完成"
lsof -i :18789,18790,18800,18801 | grep LISTEN

状态监控脚本

#!/bin/bash
# status.sh

echo "╔════════════════════════════════════════╗"
echo "║     OpenClaw 智能体状态监控            ║"
echo "╚════════════════════════════════════════╝"
echo ""

PORTS=(18789 18790 18800 18801)
NAMES=("主应用" "投资顾问" "办公助手" "编程助手")

for i in "${!PORTS[@]}"; do
  PORT=${PORTS[$i]}
  NAME=${NAMES[$i]}
  
  PID=$(lsof -i :${PORT} | grep LISTEN | awk '{print $2}')
  
  if [ -n "$PID" ]; then
    CPU=$(ps -p $PID -o %cpu= | xargs)
    MEM=$(ps -p $PID -o %mem= | xargs)
    echo "✅ ${NAME}"
    echo "   端口：${PORT} | PID: ${PID}"
    echo "   CPU: ${CPU}% | 内存：${MEM}%"
  else
    echo "❌ ${NAME} (端口 ${PORT}): 未运行"
  fi
  echo ""
done

# 日志文件状态
echo "📁 日志文件:"
for name in main finance office programming; do
  if [ -f "/tmp/gateway-${name}.log" ]; then
    size=$(ls -lh /tmp/gateway-${name}.log | awk '{print $5}')
    echo "   /tmp/gateway-${name}.log: ${size}"
  fi
done

自动修复脚本

#!/bin/bash
# auto-fix.sh

echo "🔧 OpenClaw 自动修复工具"
echo ""

# 1. 检查配置
echo "1️⃣  检查配置..."
openclaw doctor

# 2. 清理缓存
echo ""
echo "2️⃣  清理缓存..."
rm -rf ~/.openclaw/cache/*
echo "✅ 缓存已清理"

# 3. 检查进程
echo ""
echo "3️⃣  检查 Gateway 进程..."
for port in 18789 18790 18800 18801; do
  pid=$(lsof -i :$port | grep LISTEN | awk '{print $2}')
  if [ -n "$pid" ]; then
    echo "✅ 端口 $port: 运行中 (PID: $pid)"
  else
    echo "⚠️  端口 $port: 未运行"
  fi
done

# 4. 检查日志
echo ""
echo "4️⃣  最近错误日志:"
grep -h "error\|failed" /tmp/gateway-*.log 2>/dev/null | tail -5 || echo "无错误日志"

echo ""
echo "✅ 自动修复完成"

附录：端口分配表

智能体	端口	配置文件	日志文件
虾米 (主应用)	18789	`gateway-main.json`	`/tmp/gateway-main.log`
投资顾问	18790	`gateway-finance.json`	`/tmp/gateway-finance.log`
办公助手	18800	`gateway-office.json`	`/tmp/gateway-office.log`
编程助手	18801	`gateway-programming.json`	`/tmp/gateway-programming.log`

附录：文件路径速查

# 配置文件
~/.openclaw/openclaw.json                    # 主配置
~/.openclaw/gateway-xxx.json                 # 独立 Gateway 配置
~/.openclaw/agents/<name>/agent/agent.json   # Agent 配置

# 日志文件
/tmp/openclaw/openclaw-YYYY-MM-DD.log        # 主 Gateway 日志
/tmp/gateway-xxx.log                         # 独立 Gateway 日志

# 工作区
~/.openclaw/workspace/                       # 工作区根目录
~/.openclaw/workspace/memory/                # 记忆文件
~/.openclaw/workspace/skills/                # 技能目录

# 会话数据
~/.openclaw/agents/<name>/sessions/          # 会话存储

附录：常用快捷键

# Tab 补全
openclaw <TAB>           # 补全命令
openclaw gateway <TAB>   # 补全子命令

# 快速搜索历史命令
Ctrl+R                   # 搜索历史命令
history | grep openclaw  # 查看 OpenClaw 历史命令

# 后台任务控制
Ctrl+Z                   # 挂起当前任务
bg                       # 后台继续
fg                       # 前台继续
jobs                     # 查看后台任务

文档版本: v1.0
最后更新: 2026-03-20
维护者: 虾米团队

💡 使用提示

收藏本文档 - 将常用命令添加到书签
设置别名 - 在 ~/.zshrc 或 ~/.bashrc 中添加常用命令别名
使用脚本 - 将快捷脚本添加到 PATH 中方便调用
定期备份 - 定期备份配置文件和工作区数据

# 示例：添加到 ~/.zshrc
alias oc-status='openclaw status'
alias oc-doctor='openclaw doctor'
alias oc-restart='~/scripts/restart-all.sh'

AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

【AI】-7 从知识库到 AI Agent -进阶

AI Agent技术社区

AI Agent 面试题 353：A2A协议的服务发现和注册机制详解

A2A 协议是 AI Agent 技术体系中的重要组成部分。简单来说，它涉及到 Agent 如何在工具使用与函数调用层面实现智能化的行为和决策。在实际应用中，A2A 协议的核心目标是让 Agent 能够更加高效、准确地完成特定任务。这需要我们深入理解其底层原理和实现机制。从学术角度来看，A2A 协议的研究可以追溯到人工智能的早期阶段。早在 1950 年代，Alan Turing 就提出了

AI Agent技术社区

英伟达AI刷爆ARC-AGI-3！AVO Harness架构让Agent从30%飙升到100%

AI Agent技术社区

所有评论(0)

查看更多评论

yuzhucu

@yuzhucu

已为社区贡献1条内容

OpenClaw 常用命令速查手册

yuzhucu

OpenClaw 常用命令速查手册

📑 目录

安装与初始化

安装 OpenClaw

1 、🚀 一键安装命令

2、 使用 npm 安装（推荐）

3、 源码安装 (Git)

4、 Docker 追求环境一致性，避免依赖冲突

升级更新

1. 一键安装脚本（推荐）

2. 全局安装用户（通过 npm / pnpm）

3. 源码安装用户（通过 Git）

初始化配置

1. 运行初始化向导

2. 验证安装

检查安装状态

配置管理

配置文件位置

配置操作

配置修复

Gateway 管理

启动 Gateway

停止 Gateway

重启 Gateway

Gateway 服务管理

智能体管理

查看智能体

创建智能体

绑定智能体

删除智能体

飞书配置

飞书应用管理

飞书机器人测试

飞书事件配置

日志查看

Gateway 日志

独立 Gateway 日志

日志过滤

运维监控

进程监控

状态检查脚本

性能监控

健康检查

故障排查

常见问题诊断

调试模式

恢复操作

快捷脚本

一键启动所有智能体

一键停止所有智能体

一键重启

状态监控脚本

自动修复脚本

附录：端口分配表

附录：文件路径速查

附录：常用快捷键

💡 使用提示

所有评论(0)

温馨提示：您尚未绑定手机号

yuzhucu

2、使用 npm 安装（推荐）

3、源码安装 (Git)