OpenClaw CLI 命令参考手册：我的实战笔记

今天我想和你分享一下我使用 OpenClaw CLI 的经验。这份手册基于 2026.2.26 版本，是我在实际工作中整理出来的完整命令参考，希望能帮你快速上手。

---

目录

1. 基础命令
2. 模型管理命令
3. 认证管理命令
4. 配置管理命令
5. Gateway 命令
6. 实战案例
7. 常见问题

---

1. 基础命令

1.1 帮助命令

刚开始用 OpenClaw 时，我发现自己最常用的就是 --help 参数。它就像我的随身小助手，随时告诉我该用什么命令。

# 查看主帮助
openclaw --help

# 查看子命令帮助
openclaw models --help
openclaw auth --help

1.2 版本信息

有时候我需要确认自己用的是哪个版本，特别是在排查问题或者查看新功能的时候。

# 查看版本
openclaw --version

输出示例：

OpenClaw 2026.2.26 (bc50708) - Your AI assistant, now without the $3,499 headset.

---

2. 模型管理命令

2.1 openclaw models 子命令

模型管理是 OpenClaw 的核心功能。我整理了一下常用的子命令，你可以把它们看作是一套完整的模型工具箱。

命令	说明
aliases	管理模型别名
auth	管理模型认证配置
fallbacks	管理模型 fallback 列表
image-fallbacks	管理图像模型 fallback 列表
list	列出已配置的模型
scan	扫描 OpenRouter 免费模型
set	设置默认模型
set-image	设置图像模型
status	显示模型配置状态

2.2 查看模型列表

每次配置新环境，我第一个运行的就是这个命令。它能让我快速了解当前有哪些模型可用。

# 列出所有已配置的模型
openclaw models list

输出示例：

OpenClaw 2026.2.26 (bc50708)

Model                          Input       Ctx     Local  Auth  Tags
qwen-portal/coder-model        text        125k    no     no    default,configured,alias:qwen
moonshot/kimi-k2.5             text+image  250k    no     no    configured,alias:Kimi
qwen-portal/vision-model       text+image  125k    no     no    configured

字段说明：
- Model: 模型 ID
- Input: 支持的输入类型（text/text+image）
- Ctx: 上下文窗口大小
- Local: 是否本地模型
- Auth: 是否需要认证
- Tags: 标签（default/configured/alias）

2.3 查看模型状态

这个命令是我日常使用频率最高的。它就像一张仪表盘，让我一眼就能看清整个系统的配置状态。

# 查看当前模型配置状态
openclaw models status

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

# 纯文本输出
openclaw models status --plain

输出示例：

Config              : ~/.openclaw/openclaw.json
Agent dir           : ~/.openclaw/agents/main/agent
Default             : qwen-portal/coder-model
Fallbacks (0)       : -
Image model         : -
Image fallbacks (0) : -
Aliases (2)         : Kimi -> moonshot/kimi-k2.5, qwen -> qwen-portal/coder-model
Configured models (3): moonshot/kimi-k2.5, qwen-portal/coder-model, qwen-portal/vision-model

Auth overview
Auth store          : ~/.openclaw/agents/main/agent/auth-profiles.json
Shell env           : off
Providers w/ OAuth/tokens (1): qwen-portal (1)

2.4 设置默认模型

切换默认模型是我经常做的操作，特别是当我要针对不同任务使用不同模型的时候。

# 设置默认模型
openclaw models set <model-id>

# 示例：设置 Qwen Coder 模型
openclaw models set qwen-portal/coder-model

# 示例：使用别名
openclaw models set qwen

2.5 设置图像模型

处理图像任务时，这个命令就派上用场了。我发现单独设置图像模型能让工作流更清晰。

# 设置图像模型
openclaw models set-image <model-id>

# 示例：设置 Qwen Vision 模型
openclaw models set-image qwen-portal/vision-model

2.6 管理模型别名

给模型起别名是我最喜欢的功能之一。它让命令变得更简洁，也更容易记忆。

# 查看别名列表
openclaw models aliases list

# 添加别名
openclaw models aliases add <alias-name> <model-id>

# 示例：添加 qwen 别名
openclaw models aliases add qwen qwen-portal/coder-model

# 删除别名
openclaw models aliases remove <alias-name>

2.7 管理 Fallback 模型

配置 fallback 模型是个好习惯，特别是当主模型不可用时，它能保证服务不中断。

# 查看 fallback 列表
openclaw models fallbacks list

# 添加 fallback 模型
openclaw models fallbacks add <model-id>

# 移除 fallback 模型
openclaw models fallbacks remove <model-id>

# 清空 fallback 列表
openclaw models fallbacks clear

2.8 扫描 OpenRouter 免费模型

这个命令帮我发现了不少好用的免费模型，对于预算有限的项目来说特别有价值。

# 扫描 OpenRouter 免费模型（支持 tools + images）
openclaw models scan

---

3. 认证管理命令

3.1 添加认证

第一次配置认证时，我建议使用交互式方式，它会引导你完成整个过程。

# 交互式添加认证
openclaw auth add

# 指定 provider 添加认证
openclaw auth add --provider <provider-name>

3.2 OAuth 登录

对于支持 OAuth 的 provider，这个登录流程非常方便，省去了手动复制粘贴 token 的麻烦。

# OAuth 登录
openclaw models auth login --provider <provider-name>

# OAuth 登录并设为默认
openclaw models auth login --provider <provider-name> --set-default

适用场景： Qwen Portal 等支持 OAuth 的 provider

3.3 查看认证状态

我经常用这个命令来确认认证是否配置正确，特别是在切换环境之后。

# 通过 status 命令查看
openclaw models status

# 输出中的 Auth overview 部分显示：
# - kimi-coding: api_key=1
# - qwen-portal: oauth=1

---

4. 配置管理命令

4.1 配置文件位置

了解配置文件的位置很重要，特别是当需要手动修改或者备份的时候。

文件	路径
主配置	~/.openclaw/openclaw.json
Agent 配置	~/.openclaw/agents/main/agent/
认证配置	~/.openclaw/agents/main/agent/auth-profiles.json
模型配置	~/.openclaw/agents/main/agent/models.json

4.2 环境变量覆盖

在多环境部署时，环境变量覆盖功能让我能灵活地切换配置。

# 使用环境变量覆盖 Agent 目录
OPENCLAW_AGENT_DIR=/custom/path openclaw models status

# 使用 PI_CODING_AGENT_DIR 环境变量
PI_CODING_AGENT_DIR=/custom/path openclaw models status

4.3 检查配置

定期检查配置是个好习惯，能避免很多潜在的问题。

# 检查当前配置
openclaw models status

# 检查特定 Agent 配置
openclaw models status --agent <agent-id>

---

5. Gateway 命令

5.1 启动 Gateway

启动 Gateway 是使用 OpenClaw 的关键一步。我习惯先检查端口是否被占用。

# 启动 Gateway（默认端口）
openclaw gateway

# 指定端口启动
openclaw gateway --port 18789

输出示例：

OpenClaw 2026.2.26 (bc50708) - Because the right answer is usually a script.

[canvas] host mounted at http://127.0.0.1:18789/__openclaw__/canvas/
[health-monitor] started (interval: 300s, grace: 60s)
[gateway] agent model: qwen-portal/coder-model
[gateway] listening on ws://127.0.0.1:18789, ws://[::1]:18789 (PID 29488)
[log file] C:\Users\teach\AppData\Local\Temp\openclaw\openclaw-2026-03-14.log

5.2 Gateway 日志

理解日志类型能帮助我快速定位问题。下面是我总结的几个关键日志类型。

日志类型	说明
[gateway]	Gateway 主日志
[ws]	WebSocket 连接日志
[health-monitor]	健康监控日志
[hooks:loader]	Hook 加载日志
[canvas]	Canvas 挂载日志

5.3 查看日志文件

遇到问题时，查看日志文件是我的第一反应。不同系统的日志位置略有不同。

# Windows
notepad %LOCALAPPDATA%\Temp\openclaw\openclaw-YYYY-MM-DD.log

# macOS/Linux
cat ~/.openclaw/logs/openclaw-YYYY-MM-DD.log

---

6. 实战案例

6.1 首次配置流程

这是我给新同事的标准配置流程，经过多次实践，非常可靠。

# 步骤 1：添加认证
openclaw auth add

# 步骤 2：查看可用模型
openclaw models list

# 步骤 3：设置默认模型
openclaw models set qwen-portal/coder-model

# 步骤 4：验证配置
openclaw models status

6.2 切换模型

根据任务需求切换模型是我日常工作的一部分。这个流程已经成了我的肌肉记忆。

# 当前使用 Qwen 模型
openclaw models status
# Default: qwen-portal/coder-model

# 切换到 Kimi 模型
openclaw models set moonshot/kimi-k2.5

# 验证切换
openclaw models status
# Default: moonshot/kimi-k2.5

6.3 配置图像模型

当项目需要处理图像时，我会专门配置图像模型，确保获得最佳效果。

# 设置图像模型
openclaw models set-image qwen-portal/vision-model

# 验证配置
openclaw models status
# Image model: qwen-portal/vision-model

6.4 启动 Gateway 并验证

启动 Gateway 后，我总会检查几个关键输出，确保一切正常。

# 启动 Gateway
openclaw gateway --port 18789

# 验证输出
# 看到 [gateway] agent model: xxx 表示模型配置生效
# 看到 [gateway] listening on ws://... 表示服务已启动

6.5 使用别名快速切换

设置别名后，切换模型变得异常快捷。这是我提高工作效率的小技巧。

# 假设已创建别名：
# qwen -> qwen-portal/coder-model
# Kimi -> moonshot/kimi-k2.5

# 快速切换到 Qwen
openclaw models set qwen

# 快速切换到 Kimi
openclaw models set Kimi

---

7. 常见问题

Q1: 如何查看当前使用的模型？

这是我最常被问到的问题。其实很简单：

openclaw models status

查看输出中的 Default 字段。

Q2: 如何检查模型认证状态？

当模型调用失败时，我首先会检查认证状态：

openclaw models status --probe

Q3: 如何扫描新的免费模型？

想要尝试新模型时，我会定期扫描：

openclaw models scan

Q4: 如何重置认证？

遇到认证问题时，重置往往是最快的解决方法：

# 删除认证配置文件
rm ~/.openclaw/agents/main/agent/auth-profiles.json

# 重新添加认证
openclaw auth add

Q5: Gateway 启动失败怎么办？

根据我的经验，Gateway 启动失败通常有几个原因：

1. 检查端口是否被占用
2. 尝试更换端口：openclaw gateway --port 18790
3. 查看日志文件定位问题

Q6: 如何配置多个 Agent？

在多项目环境中，配置多个 Agent 能避免配置冲突：

# 使用 --agent 参数指定 Agent ID
openclaw models status --agent <agent-id>

# 或设置环境变量
export OPENCLAW_AGENT_DIR=/path/to/agent

Q7: 如何备份配置？

定期备份配置是个好习惯，特别是在重大变更之前：

# 备份整个 .openclaw 目录
cp -r ~/.openclaw ~/.openclaw.backup

# 或单独备份配置文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

---

附录：快捷键和技巧

这些是我在日常使用中积累的小技巧，能显著提升操作效率。

技巧	说明
Tab 补全	使用 Tab 键自动补全命令
--help	任何命令后加 --help 查看帮助
--json	需要程序化处理时使用 JSON 输出
--plain	需要纯文本输出（无颜色）时使用

---

相关文档

• OpenClaw 官方文档
• OpenClaw 安装指南
• OpenClaw 切换模型操作手册

---

文档版本：1.0
最后更新：2026-03-14