# OpenClaw CLI 最佳实践指南

> **文档用途**：记录常用命令，避免直接修改JSON导致格式错误
> **创建时间**：2026-03-18
> **作者**：小笔

—

## 🛡️ 核心原则：避免直接修改JSON

### ❌ 错误做法

直接编辑配置文件中的JSON，容易导致：
– 格式错误（缺少逗号、引号不匹配）
– 语法错误（括号不匹配）
– 配置失效
– 系统无法启动

### ✅ 正确做法

使用OpenClaw CLI命令进行配置管理：
– 命令自动验证格式
– 提供错误提示
– 安全的配置更新

—

## 📋 常用命令速查

### 1. 系统状态命令

“`bash
# 查看系统状态
openclaw status

# 查看网关状态
openclaw gateway status

# 启动网关
openclaw gateway start

# 停止网关
openclaw gateway stop

# 重启网关
openclaw gateway restart
“`

—

### 2. Agent管理命令

“`bash
# 列出所有Agent
openclaw agents list

# 查看Agent详情
openclaw agents show

# 创建新Agent
openclaw agents create –name –model

# 删除Agent
openclaw agents delete
“`

—

### 3. 定时任务（Cron）命令

“`bash
# 列出所有定时任务
openclaw cron list

# 创建定时任务
openclaw cron create \
–name \
–schedule “” \
–agent \
–prompt “”

# 删除定时任务
openclaw cron delete

# 查看定时任务详情
openclaw cron show
“`

**Cron表达式示例**：

| 表达式 | 含义 |
|——–|——|
| `0 9 * * *` | 每天上午9点 |
| `0 */6 * * *` | 每6小时 |
| `0 9 * * 1` | 每周一上午9点 |
| `0 0 1 * *` | 每月1号 |

—

### 4. 配置管理命令

“`bash
# 查看配置
openclaw config get

# 设置配置
openclaw config set

# 查看所有配置
openclaw config list

# 重置配置
openclaw config reset
“`

—

### 5. 会话管理命令

“`bash
# 列出会话
openclaw sessions list

# 查看会话历史
openclaw sessions history

# 发送消息到会话
openclaw sessions send “”

# 结束会话
openclaw sessions kill
“`

—

## 📝 配置修改安全流程

### 步骤1：备份当前配置

“`bash
# 复制配置文件（修改前备份）
cp ~/.openclaw/config.json ~/.openclaw/config.json.backup
“`

### 步骤2：使用命令修改

“`bash
# 优先使用CLI命令
openclaw config set
“`

### 步骤3：验证修改

“`bash
# 检查配置是否生效
openclaw config get

# 检查系统状态
openclaw status
“`

### 步骤4：如出错，恢复备份

“`bash
# 恢复备份
cp ~/.openclaw/config.json.backup ~/.openclaw/config.json

# 重启网关
openclaw gateway restart
“`

—

## ⚠️ 常见错误及解决

### 错误1：JSON格式错误

**症状**：
“`
Error: Unexpected token } in JSON at position xxx
“`

**原因**：
– 缺少逗号
– 引号不匹配
– 括号不匹配

**解决**：
1. 使用JSON验证工具检查
2. 恢复备份文件
3. 使用CLI命令重新配置

—

### 错误2：配置项不存在

**症状**：
“`
Error: Config key ‘xxx’ not found
“`

**解决**：
“`bash
# 查看可用配置项
openclaw config list

# 确认键名拼写正确
“`

—

### 错误3：权限不足

**症状**：
“`
Error: Permission denied
“`

**解决**：
“`bash
# 检查文件权限
ls -la ~/.openclaw/

# 修复权限
chmod 644 ~/.openclaw/config.json
“`

—

### 错误4：网关启动失败

**症状**：
“`
Error: Gateway failed to start
“`

**解决**：
“`bash
# 1. 检查配置语法
openclaw config validate

# 2. 查看详细日志
openclaw gateway logs

# 3. 恢复默认配置（如必要）
openclaw config reset –all
“`

—

## 💡 最佳实践

### 1. 优先使用CLI命令

| 操作 | 推荐方式 | 避免方式 |
|——|———-|———-|
| 修改配置 | `openclaw config set` | 直接编辑JSON |
| 添加Agent | `openclaw agents create` | 修改agents.json |
| 创建Cron | `openclaw cron create` | 修改cron.json |
| 修改模型 | `openclaw config set model` | 修改config.json |

### 2. 修改前备份

**养成习惯**：
“`bash
# 重要配置修改前
openclaw config export > config-backup-$(date +%Y%m%d).json
“`

### 3. 小步修改

**原则**：
– 一次只修改一个配置项
– 修改后立即验证
– 确认正常后再修改下一个

### 4. 使用验证工具

“`bash
# 验证配置语法
openclaw config validate

# 验证Agent配置
openclaw agents validate
“`

### 5. 记录修改历史

**在MEMORY.md中记录**：
“`markdown
## 配置变更记录

### 2026-03-18
– 修改：xxx
– 原因：xxx
– 命令：`openclaw config set xxx xxx`
“`

—

## 🔧 高级技巧

### 批量配置

如需批量修改，使用脚本：

“`bash
#!/bin/bash
# config-batch.sh

openclaw config set key1 value1
openclaw config set key2 value2
openclaw config set key3 value3

echo “配置完成”
openclaw config list
“`

### 配置模板

创建常用配置模板：

“`bash
# 开发环境配置
cp config-dev.json ~/.openclaw/config.json

# 生产环境配置
cp config-prod.json ~/.openclaw/config.json
“`

### 快速恢复

“`bash
# 创建恢复脚本
#!/bin/bash
# restore-defaults.sh

openclaw config reset –all
openclaw gateway restart
“`

—

## 📚 相关资源

– OpenClaw文档：`~/workspace/docs/`
– 配置文件位置：`~/.openclaw/`
– 日志文件位置：`~/.openclaw/logs/`

—

_小笔 ✍️ 经验总结_