OpenClaw 中文文档 — CLI 入门与向导自动化

本文覆盖 OpenClaw CLI 的日常使用和脚本化部署两个方面。前者针对交互式场景下的核心命令，后者针对 CI/CD 和批量部署场景下的非交互式自动化。

CLI 命令体系

OpenClaw CLI 按功能领域组织，核心命令可分为以下几类：

网关管理

命令	说明
openclaw gateway --port 18789	前台启动网关
openclaw gateway status	查看运行状态
openclaw gateway stop	停止网关
openclaw gateway restart	重启网关
openclaw gateway install	注册为系统服务
openclaw gateway uninstall	卸载系统服务

诊断与监控

命令	说明
openclaw status	本地状态（凭据、会话、排队事件）
openclaw status --all	完整诊断信息（可粘贴用于远程排错）
openclaw status --deep	附带 Gateway 健康探测
openclaw health --json	Gateway 健康快照（通过 WebSocket）
openclaw doctor	配置检查、迁移、安全审计
openclaw logs --follow	实时日志流

配置与初始化

命令	说明
openclaw onboard	运行引导向导
openclaw configure	增量配置修改
openclaw setup	初始化工作区
openclaw dashboard	打开 Web 控制面板
openclaw channels login	渠道登录（WhatsApp 扫码等）

日志默认存放在 /tmp/openclaw/，文件名格式 openclaw-YYYY-MM-DD.log。

个人助手配置

OpenClaw 的一个典型使用场景是将其配置为个人 AI 助手，通过专用 WhatsApp 号码提供 24/7 服务。

安全模型

值得注意的是，个人助手场景下的 Agent 拥有以下能力：

• 在主机上运行命令（取决于工具配置）
• 读写工作区文件
• 通过聊天渠道对外发送消息

因此需要遵循最小权限原则：

• 必须设置 channels.whatsapp.allowFrom 白名单
• 使用专用手机号（而非个人号），避免所有消息都被 Agent 处理
• 心跳功能初始时应禁用（heartbeat.every: "0m"），在信任配置后再启用

配置示例

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-6",
    workspace: "~/.openclaw/workspace",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    heartbeat: { every: "0m" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
    },
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
  },
}

工作区架构

Agent 从工作区目录（默认 ~/.openclaw/workspace）读取运行指令：

文件	用途	自动创建
AGENTS.md	Agent 运行指令	是
SOUL.md	Agent 人设	是
TOOLS.md	工具配置	是
IDENTITY.md	身份信息	是
USER.md	用户信息	是
HEARTBEAT.md	心跳任务	是
BOOTSTRAP.md	引导仪式（一次性）	是
MEMORY.md	记忆	否

从架构层面来看，工作区设计为纯 Markdown 文件，这使得版本控制和备份非常直接——推荐将工作区做成私有 Git 仓库。

心跳机制

心跳功能使 Agent 能够主动检查任务。默认间隔 30 分钟，每次心跳运行完整的 Agent 回合，消耗 token。

• HEARTBEAT.md 为空时，自动跳过以节省 API 调用
• Agent 回复 HEARTBEAT_OK 时，压制对外发送
• 可通过 directPolicy: "block" 禁止心跳向 DM 目标投递

会话管理

• /new 或 /reset 启动新会话
• /compact [instructions] 压缩上下文并报告预算
• 会话文件存储在 ~/.openclaw/agents/<agentId>/sessions/

向导自动化

非交互模式

CI/CD 场景下使用 --non-interactive 实现无人值守部署：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --secret-input-mode plaintext \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

值得注意的是，--json 并不意味着非交互模式——它只控制输出格式。脚本中必须显式传入 --non-interactive。

密钥管理策略

--secret-input-mode 支持两种模式：

• plaintext（默认）：API Key 以明文存储在配置中
• ref：存储环境变量引用，运行时解析

export ANTHROPIC_API_KEY="sk-xxx"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --secret-input-mode ref \
  --gateway-port 18789 \
  --gateway-bind loopback

ref 模式下，配置中存储的是 { source: "env", id: "ANTHROPIC_API_KEY" }。这个设计将密钥管理的职责推给了运行时环境，适合使用 Vault、Kubernetes Secrets 等外部密钥管理系统的场景。

各供应商自动化示例

Ollama（本地模型）：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice ollama \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk \
  --gateway-port 18789 \
  --gateway-bind loopback

自定义供应商（OpenAI/Anthropic 兼容接口）：

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "my-model" \
  --custom-api-key "$CUSTOM_API_KEY" \
  --custom-provider-id "my-custom" \
  --custom-compatibility anthropic \
  --gateway-port 18789 \
  --gateway-bind loopback

多 Agent 自动化配置

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

每个 Agent 拥有独立的工作区、会话和认证 profile。--bind 参数配置消息路由，将特定渠道的消息路由到对应 Agent。

小结

OpenClaw CLI 的设计在交互式使用和脚本化自动化之间取得了较好的平衡。--non-interactive + --secret-input-mode ref 的组合使得在 CI/CD 管线中安全部署成为可能，而交互式向导则降低了首次使用的门槛。

本文是入门篇的最后一篇。下一篇开始渠道篇，从渠道系统总览和配对机制讲起。

---

完整中文文档：OpenClaw 中文文档

GitHub 仓库：openclaw/openclaw