OpenClaw 详细使用指南

OpenClaw 详细使用指南 — 从安装到精通的完整手册本文全面介绍了 2026 年主流 AI Agent 框架 OpenClaw 的安装配置与使用实践。文章从环境准备和首次引导入手，深入解析 Gateway-Agent-Channel三层架构、目录结构与核心配置文件；系统讲解了 Skills 技能系统、Memory 记忆管理、Cron 定时任务、MCP 扩展等核心功能；涵盖多 Agent 路由

Java小白笔记

973人浏览 · 2026-04-25 17:52:29

Java小白笔记 · 2026-04-25 17:52:29 发布

OpenClaw 详细使用指南

版本：2026.4.23 | 最后更新：2026-04-25

0. 安装步骤

0.1 环境要求

组件	最低版本	推荐版本	说明
Node.js	20.x	22+	运行时
npm	10.x	11+	包管理器
macOS	13+	14+	操作系统
磁盘空间	500MB	1GB+	含依赖

验证环境：

node -v   # 应 >= 20
npm -v    # 应 >= 10

0.2 安装 OpenClaw

OpenClaw 通过 npm/pnpm 安装：

# 使用 npm 全局安装
npm install -g openclaw

# 或使用 pnpm
pnpm add -g openclaw

# 验证安装
openclaw --version
# 输出: 🦞 OpenClaw 2026.4.23 (xxxxxxx)

0.3 首次引导

# 交互式引导（推荐首次使用）
openclaw onboard

# 或分步配置
openclaw configure

引导流程会引导你完成：

模型配置 — 输入 API Key、选择模型
Gateway 设置 — 端口、绑定地址、认证
Channel 接入 — 可选连接聊天平台
Skills 安装 — 可选安装技能包

0.4 手动配置模型

如果跳过引导，需手动配置 Provider：

# 方式一：交互式
openclaw configure

# 方式二：命令行设置
openclaw config set models.providers.openai.baseUrl "https://api.openai.com/v1"
openclaw config set models.providers.openai.apiKey "sk-..."
openclaw config set models.providers.openai.api "openai-completions"

# 方式三：直接编辑配置
openclaw config file  # 查看路径，然后编辑
vi ~/.openclaw/openclaw.json

0.5 启动 Gateway

# 首次启动（前台，确认正常）
openclaw gateway run --verbose

# 确认正常后，后台启动
openclaw gateway --force

# 验证健康
openclaw health
# 正常输出: Agents: main (default)

0.6 安装为系统服务（可选）

# 安装 launchd 服务（macOS 开机自启）
openclaw gateway install

# 查看服务状态
openclaw gateway status

0.7 安全加固（必须做）

# 修复文件权限
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw

# 设置 Gateway 认证 token
openclaw config set gateway.auth.token "$(openssl rand -hex 16)"

# 设置 Gateway 模式
openclaw config set gateway.mode local

# 安全审计
openclaw security audit
# 应显示: 0 critical

1. 架构概览

OpenClaw 是一个 AI Agent 框架，核心架构由三层组成：

┌─────────────────────────────────────────┐
│           Channel 层 (输入/输出)          │
│  WhatsApp / Telegram / Discord / Web UI  │
│  / iMessage / Slack / Feishu / QQ ...   │
└───────────────┬─────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────┐
│          Gateway 层 (WebSocket)          │
│  ws://127.0.0.1:18789                   │
│  路由 / 会话管理 / 认证 / 调度            │
└───────────────┬─────────────────────────┘
                │
                ▼
┌─────────────────────────────────────────┐
│           Agent 层 (推理执行)             │
│  LLM Provider (OpenAI / Qwen / MiniMax)  │
│  Skills + MCP Tools + Memory            │
│  文件系统 / Shell / 浏览器操作            │
└─────────────────────────────────────────┘

Gateway：持久运行的 WebSocket 服务，是所有交互的中枢
Agent：接收消息 → 调用工具/LLM → 回复，通过 Gateway 路由
Channel：接入外部聊天平台，将消息转发到 Gateway

2. 目录结构

~/.openclaw/
├── openclaw.json              # 主配置文件（权限 600）
├── openclaw.json.bak          # 自动备份（每次修改前）
├── openclaw.json.last-good    # 上一次正常的配置
├── exec-approvals.json        # 命令执行审批策略
│
├── agents/
│   └── main/                  # 默认 Agent
│       ├── agent/             # Agent 工作区
│       │   ├── models.json    # 模型定义（API key 在这里）
│       │   └── auth-profiles.json  # 认证配置
│       └── sessions/          # 会话历史
│
├── skills/                    # 技能目录
├── workspace/                 # Agent 文件工作区
│   ├── AGENTS.md             # Agent 指令文件（最重要）
│   ├── SOUL.md               # Agent 性格设定
│   ├── TOOLS.md              # 工具使用说明
│   ├── IDENTITY.md           # Agent 身份定义
│   ├── USER.md               # 用户偏好
│   ├── HEARTBEAT.md          # 心跳任务指令
│   └── BOOTSTRAP.md          # 启动引导（可选）
├── logs/                      # 日志
├── tasks/                     # 持久化后台任务
├── devices/                   # 设备配对信息
├── canvas/                    # Canvas 数据
├── identity/                  # 身份信息
└── flows/                     # 自动化流程

关键文件说明

AGENTS.md：Agent 每次对话都会加载，是最核心的指令文件

SOUL.md：定义 Agent 的性格和行为方式

USER.md：用户的个人信息和偏好

HEARTBEAT.md：定时心跳任务的执行指令

3. 配置文件详解

3.1 主配置 `~/.openclaw/openclaw.json`

这是最核心的文件。当前你的配置结构：

{
  "models": {
    "mode": "merge",
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimaxi.com/v1",
        "apiKey": "sk-...",
        "api": "openai-completions",
        "models": [{
          "id": "MiniMax-M2.7",
          "name": "MiniMax M2.7",
          "cost": { "input": 0.001, "output": 0.004 },
          "contextWindow": 200000
        }]
      },
      "qianwen": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-...",
        "api": "openai-completions",
        "models": [{
          "id": "qwen-coder-turbo",
          "name": "qwen-coder-turbo",
          "cost": { "input": 0.002, "output": 0.006 },
          "contextWindow": 32000
        }]
      }
    }
  },
  "agents": {
    "defaults": {
      "models": {
        "qwen/qwen3.5-plus": { "alias": "Qwen" },
        "minimax/MiniMax-M2.7": { "alias": "MiniMax" }
      },
      "model": { "primary": "minimax/MiniMax-M2.7" }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": { "token": "7b3a..." }
  },
  "plugins": {
    "entries": {
      "minimax": { "enabled": true },
      "qwen": { "enabled": true }
    }
  }
}

3.2 配置项详解

`models` — 模型与 Provider

字段	说明
`mode`	`"merge"` = 合并内置 + 自定义，`"override"` = 仅使用自定义
`providers.<name>`	自定义 provider 名称
`baseUrl`	API 兼容地址（OpenAI 兼容即可）
`apiKey`	API 密钥
`api`	`"openai-completions"` 表示 OpenAI 兼容 API
`models[].id`	模型 ID，格式 `provider/模型名`
`models[].cost`	价格（美元/百万 token），用于用量统计
`models[].contextWindow`	上下文窗口大小

新增 Provider 模板：

{
  "providers": {
    "openai": {
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "sk-...",
      "api": "openai-completions",
      "models": [{
        "id": "gpt-4o",
        "name": "GPT-4o",
        "cost": { "input": 2.5, "output": 10 },
        "contextWindow": 128000
      }]
    }
  }
}

`agents.defaults` — Agent 默认配置

字段	说明
`model.primary`	默认使用的模型
`model.fallback`	主模型失败时回退的模型
`models.<id>.alias`	模型别名，方便记忆和路由
`timeoutSeconds`	Agent 单次请求超时时间（默认 600 秒）
`maxSteps`	单次 Agent 最大工具调用轮数

`gateway` — 网关配置

字段	值	说明
`mode`	`"local"` / `"remote"`	本地或远程模式
`auth.token`	字符串	连接 Gateway 所需的 token
`port`	数字	端口号（默认 18789）
`bind`	`"loopback"` / `"lan"` / `"tailnet"`	绑定地址

`env` — 环境变量

{
  "env": {
    "shellEnv": { "enabled": true, "timeoutMs": 5000 },
    "vars": {
      "MY_CUSTOM_VAR": "value"
    }
  }
}

`channels` — 聊天通道

{
  "channels": {
    "telegram": {
      "accounts": {
        "default": { "token": "bot-token-here", "enabled": true }
      }
    }
  }
}

`logging` — 日志

{
  "logging": {
    "level": "info",
    "file": "~/.openclaw/logs/gateway.log"
  }
}

3.3 配置文件操作命令

# 查看配置文件路径
openclaw config file

# 查看某个字段值
openclaw config get gateway.port

# 设置字段
openclaw config set gateway.port 19001
openclaw config set agents.defaults.model.primary "qwen/qwen3.5-plus"

# 批量设置（JSON 文件）
openclaw config set --batch-file ./changes.json

# 验证配置合法性
openclaw config validate

# 查看完整 JSON Schema
openclaw config schema

4. 核心命令参考

4.1 Gateway 管理

# 启动（前台，适合调试）
openclaw gateway run
openclaw gateway run --verbose --cli-backend-logs

# 启动（后台，杀掉旧进程）
openclaw gateway --force

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

# 服务控制
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway status
openclaw gateway uninstall

# 健康检查
openclaw health
openclaw gateway probe
openclaw gateway diagnostics

# 查看 Gateway 日志
openclaw logs --follow

# 查看 Gateway 用量（详见第11节）
openclaw gateway usage-cost

4.2 Agent 交互

# 发送消息给 Agent
openclaw agent --session-id main --message "你好，帮我总结下今天的待办"

# 指定接收者（通过 Channel 回复）
openclaw agent --to "+8613800138000" --message "查询状态"

# 指定模型思考深度
openclaw agent --session-id main --message "分析这个方案" --thinking high

# 运行后自动发送回复到 Channel
openclaw agent --to "+8613800138000" --message "生成报告" --deliver

# 指定 Agent 实例
openclaw agent --agent ops --message "检查服务器状态"

# JSON 模式输出
openclaw agent --session-id main --message "列出文件" --json

# 设置超时
openclaw agent --session-id main --message "处理大文件" --timeout 1800

4.3 终端交互界面 TUI

# 打开终端 UI（推荐日常使用）
openclaw tui

# 打开后直接发送第一条消息
openclaw tui --message "今天有什么计划？"

# 本地模式（不经过 Gateway）
openclaw tui --local

# 加载更多历史
openclaw tui --history-limit 500

# 交付模式（自动将回复发送到 Channel）
openclaw tui --deliver

4.4 模型管理

# 查看所有已配置模型
openclaw models status
openclaw models list

# 设置默认模型
openclaw models set "qwen/qwen3.5-plus"

# 设置图像模型
openclaw models set-image "provider/model-id"

# 管理模型别名
openclaw models aliases list
openclaw models aliases add "fast" "qwen/qwen3.5-plus"

# 扫描可用模型（OpenRouter）
openclaw models scan

# 管理 fallback 列表
openclaw models fallbacks list
openclaw models fallbacks add "provider/fallback-model"

# 管理认证
openclaw models auth list
openclaw models auth add

4.5 状态与诊断

# 总览状态
openclaw status
openclaw status --all

# 健康检查（含深度探针）
openclaw doctor
openclaw doctor --fix

# 安全审计
openclaw security audit
openclaw security audit --deep

# 会话管理
openclaw sessions

4.6 配置向导

# 交互式配置向导
openclaw configure

# 非交互式单步设置
openclaw config set gateway.mode local

# 初始化配置和 Agent 工作区
openclaw setup

# 完整引导（首次使用）
openclaw onboard

5. Channel 接入指南

Channel 是 Agent 与外部聊天平台之间的桥梁。

5.1 支持的 Channel

Channel	类型	说明
WhatsApp	个人消息	扫码登录 Web 版
Telegram	Bot	需要 Bot Token
Discord	Bot	需要 Bot Token + 服务器 ID
Slack	Bot/App	需要 App Token
iMessage	BlueBubbles	需要 BlueBubbles 服务器
Signal	CLI	需要 signald
QQ	QQBot	QQ 官方机器人
Feishu	Webhook/Bot	飞书
Matrix	Homeserver	Matrix 协议
IRC	传统 IRC	IRC 网络
Line	Bot	Line 开发者
MS Teams	Bot	Microsoft Teams
Google Chat	Bot	Google 开发者
Nextcloud Talk	App	Nextcloud 部署
Zalo	Bot	越南主流 IM
Twitch	Bot	直播平台
Nostr	协议	去中心化社交

5.2 添加 Channel

# 交互式添加
openclaw channels login --channel whatsapp

# 非交互式添加
openclaw channels add --channel telegram --token "your-bot-token"
openclaw channels add --channel discord --bot-token "your-discord-token"

# 查看所有 Channel
openclaw channels list

# 查看状态
openclaw channels status
openclaw channels status --probe

# 查看 Channel 日志
openclaw channels logs

# 解析用户/群组 ID
openclaw channels resolve --channel telegram --query "@username"

# 移除 Channel
openclaw channels remove --channel telegram

# 查看能力集
openclaw channels capabilities

5.3 消息收发

# 发送消息
openclaw message send --target "+8613800138000" --message "Hello"
openclaw message send --channel telegram --target "@mychat" --message "Hi"

6. Skills 技能系统

Skills 是 Agent 的能力扩展，类似"插件"。

6.1 技能管理

# 列出所有技能
openclaw skills list

# 查看就绪状态
openclaw skills check

# 搜索 ClawHub 技能
openclaw skills search "browser"
openclaw skills search "excel"

# 安装技能
openclaw skills install "skill-name"

# 查看技能详情
openclaw skills info "skill-name"

# 更新技能
openclaw skills update

6.2 你的环境已有技能（部分）

技能	状态	用途
ckm:banner-design	就绪	设计 Banner
ckm:brand	就绪	品牌设计同步
ckm:design	就绪	UI 设计建议
ckm:design-system	就绪	设计系统管理
ckm:slides	就绪	制作幻灯片
ckm:ui-styling	就绪	UI 样式定制
docx	就绪	Word 文档处理
pdf	就绪	PDF 处理
pptx	就绪	PPT 处理
xlsx	就绪	Excel 处理
frontend-design	就绪	前端设计
web-access	就绪	网页抓取/搜索
ui-ux-pro-max	就绪	UI/UX 专业建议
skill-creator	就绪	创建自定义技能
planning-with-files-zh	就绪	文件规划系统
1password	需配置	密码管理
apple-notes	需配置	Apple 备忘录
apple-reminders	需配置	Apple 提醒
blogwatcher	需配置	RSS 监控

6.3 创建自定义技能

openclaw skills install skill-creator

技能目录结构：

~/.openclaw/skills/my-skill/
├── SKILL.md           # 技能描述（Agent 读取此文件）
├── scripts/           # 脚本
│   └── run.sh
└── references/        # 参考文档
    └── guide.md

7. Memory 记忆系统

OpenClaw 有内置的记忆系统，让 Agent 记住历史信息。

7.1 记忆操作

# 查看记忆状态
openclaw memory status
openclaw memory status --deep

# 搜索记忆
openclaw memory search "部署配置"
openclaw memory search "deployment" --max-results 20

# 强制全量重建索引
openclaw memory index --force

# 提升短期记忆为长期记忆
openclaw memory promote --limit 10 --min-score 0.75

# 自动提升并写入 MEMORY.md
openclaw memory promote --apply

# 查看提升决策解释
openclaw memory promote-explain "router vlan"

# REM 回溯填充
openclaw memory rem-backfill --path ./memory

# REM 预览
openclaw memory rem-harness --json

7.2 记忆工作原理

短期记忆：最近对话的自动提取摘要
长期记忆：MEMORY.md 中持久化的关键信息
向量搜索：通过 embedding 进行语义搜索
自动提升：高评分的短期记忆被推荐写入长期记忆

最佳实践：

重要决策/配置变更后，在对话中明确让 Agent “记住这个”
定期运行 openclaw memory promote --apply 巩固记忆
记忆索引损坏时运行 openclaw memory index --force

8. 定时任务 Cron

内置的调度器，让 Agent 定时执行任务。

8.1 Cron 操作

# 查看调度器状态
openclaw cron status

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

# 添加定时任务
openclaw cron add --cron "0 9 * * 1-5" --message "发送每日晨报"

# 查看某个任务
openclaw cron show <job-id>

# 手动触发
openclaw cron run <job-id>

# 查看执行历史
openclaw cron runs <job-id>

# 暂停/恢复
openclaw cron disable <job-id>
openclaw cron enable <job-id>

# 编辑任务
openclaw cron edit <job-id>

# 删除任务
openclaw cron rm <job-id>

8.2 Cron 表达式速查

* * * * *
│ │ │ │ │
│ │ │ │ └─ 星期 (0-7, 0/7=日)
│ │ │ └─── 月份 (1-12)
│ │ └───── 日期 (1-31)
│ └─────── 小时 (0-23)
└───────── 分钟 (0-59)

示例:
*/5 * * * *     → 每 5 分钟
0 * * * *       → 每小时整点
0 9 * * 1-5     → 工作日 9:00
0 0 1 * *       → 每月 1 日零点
30 14 * * *     → 每天 14:30

9. 执行策略与安全

9.1 执行策略层级

Agent 请求 → 你配置的策略 → 主机审批 → 最终生效

9.2 三个预设档位

# 查看当前策略
openclaw exec-policy show

# 一键切换
openclaw exec-policy preset yolo       # 完全放行
openclaw exec-policy preset cautious   # 危险操作需要确认
openclaw exec-policy preset deny-all   # 全部禁止，需逐条审批

# 精细设置
openclaw exec-policy set --security full --ask off

9.3 命令审批白名单

# 管理允许执行的命令
openclaw approvals allowlist add "ls"
openclaw approvals allowlist add "git status"
openclaw approvals allowlist remove "rm"

推荐配置（个人使用）：

openclaw exec-policy preset cautious

9.4 安全审计

# 基础审计
openclaw security audit

# 深度审计（扫描技能代码中的危险模式）
openclaw security audit --deep

10. 设备配对与权限审批

10.1 什么是设备配对

OpenClaw 使用 设备配对 + 权限作用域（scopes） 来控制不同客户端对 Gateway 的访问权限。每个客户端（CLI、TUI、Web Dashboard 等）都是一个 “设备”，需要配对后才能访问。

权限作用域包括：

operator.read — 只读权限（查看状态、日志等）
operator.write — 写权限（发送消息、修改配置等）
operator.admin — 管理权限（设备管理、服务控制等）
operator.approvals — 审批权限（批准命令执行）
operator.pairing — 配对权限（批准/拒绝新设备）
operator.secrets — 密钥访问（API Key 等敏感数据）
operator.talk.secrets — 对话中引用密钥

10.2 常见问题：scope upgrade pending approval

当你运行某些命令（如 usage-cost、devices approve）时，CLI 设备会申请更多权限。如果权限升级还没批准，会报错：

gateway connect failed: GatewayClientRequestError: scope upgrade pending approval

解决方案：

# 1. 查看待审批的请求
openclaw devices list

输出示例：

Pending (1)
┌──────────────┬────────┬────────────────────────────┬───────────────┬────────┐
│ Request      │ Device │ Requested                  │ Approved      │ Age    │
├──────────────┼────────┼────────────────────────────┼───────────────┼────────┤
│ a2435037-... │ 8eba.. │ roles: operator;           │ roles:        │ 3m ago │
│              │        │ scopes: operator.admin,    │ operator      │        │
│              │        │ operator.approvals, ...    │ scopes:       │        │
│              │        │                            │ operator.read │        │
└──────────────┴────────┴────────────────────────────┴───────────────┴────────┘

# 2. 批准请求
openclaw devices approve a2435037-6c94-4c1f-a26f-21a6b07beb63

# 3. 如果不需要，拒绝请求
openclaw devices reject a2435037-6c94-4c1f-a26f-21a6b07beb63

10.3 设备管理

# 列出所有设备（待审批 + 已配对）
openclaw devices list

# 批准新设备
openclaw devices approve <request-id>

# 移除已配对设备
openclaw devices remove <device-id>

# 清空所有配对
openclaw devices clear

# 撤销设备 token
openclaw devices revoke <device-id>

# 轮换设备 token
openclaw devices rotate <device-id>

10.4 安全建议

定期检查待审批请求：openclaw devices list
不要盲目批准：确认请求来源是你自己的操作
长期不用的设备及时清理：openclaw devices remove
不要将 Gateway 暴露到公网：除非配置了 trustedProxies + auth.token

11. 用量统计

11.1 查看用量

openclaw gateway usage-cost

正常输出示例：

Usage cost (30 days)
Total: $0.0000 · 0 tokens
Latest day: 2026-04-25 · $0.0000 · 0 tokens

11.2 用量统计原理

Gateway 通过模型 provider 返回的 usage 字段记录 token 消耗
结合配置中的 cost 字段计算费用
统计周期为最近 30 天

11.3 用量为 0 的常见原因

原因	说明
未做过 Agent 推理	Gateway 启动后还没发送过任何消息
Provider 不上报 usage	部分非标准 OpenAI 兼容 API 不返回 token 用量
cost 配置缺失	模型的 `cost` 字段未配置时无法计算金额
本地 fallback 模式	Agent 以 embedded 模式运行，不经过 Gateway

11.4 用量验证方法

# 1. 发起一次真实的 Agent 调用
openclaw agent --session-id main --message "你好" --thinking minimal --json

# 2. 检查返回的 meta 中是否有 lastCallUsage
#    有字段说明用量已上报

# 3. 查看 Gateway 日志
openclaw logs --follow

# 4. 再查一次用量
openclaw gateway usage-cost

注意：如果你使用的是非标准 OpenAI 兼容 API（如某些国内模型），provider 可能不上报 token 用量，此时 usage-cost 始终为 0 是正常现象。可以通过模型提供商的控制台查看实际用量。

12. 高效使用技巧

12.1 让 Agent 更懂你的 7 个方法

1. 写好 Agent 身份指令

在 ~/.openclaw/workspace/ 目录下编辑关键文件：

USER.md — 你的偏好：

# 用户信息

- 沟通风格：中文，简洁直接
- 职业：软件工程师
- 技术栈：Java, Spring Boot, MyBatis-Plus

AGENTS.md — Agent 行为指令：

# Agent 行为准则

- 结论先行，细节在后
- 代码优先使用项目规范
- 不问确认（分歧/不可逆才问）
- 每次宣称成功必须附证据

SOUL.md — Agent 性格：

技术搭档，中文交流。结论先行，简洁直接。

Agent 每次对话都会加载这些文件。

2. 利用多模型组合

当前你配置了 MiniMax 和 Qwen，可以这样分配：

# 日常对话 → MiniMax（成本低、速度快）
openclaw models set "minimax/MiniMax-M2.7"

# 复杂编码/深度分析 → 切换到 Qwen
openclaw models set "qwen/qwen3.5-plus"

# 单条消息指定模型
openclaw agent --session-id main --message "深度分析" --thinking high

3. 用 Session 保持上下文

# 不同话题用不同 session
openclaw tui --session "work"      # 工作相关
openclaw tui --session "personal"   # 个人事务
openclaw tui --session "coding"     # 编码专用

# CLI 中指定 session
openclaw agent --session-id work --message "今天的工作计划"

4. 善用 Profile 隔离

# 创建独立环境（配置 + 状态完全隔离）
openclaw --profile work agent --message "工作相关"
openclaw --profile dev agent --message "开发相关"
openclaw --dev agent --message "实验性测试"

# --dev 是内置快捷 profile，端口 19001

5. 安装 Shell 补全

# 生成补全脚本
openclaw completion

# bash
openclaw completion bash >> ~/.bash_completion

# zsh
openclaw completion zsh >> ~/.zshrc

# 之后 tab 自动补全命令

6. 把 Gateway 注册为系统服务

# 安装为 launchd 服务（开机自启）
openclaw gateway install

# 查看服务状态
openclaw gateway status

# 之后 Gateway 会自动运行，不再需要手动启动

7. 使用 Dashboard 可视化管理

浏览器访问：http://127.0.0.1:18789/

查看 Agent 对话历史
管理 Channel 状态
监控资源使用
查看模型用量

12.2 提问模板

场景	推荐提问方式
编码任务	“帮我实现 XXX，要求：1… 2… 3…”
代码审查	“审查这个改动：[文件/路径]，重点关注 XXX”
Bug 排查	“报错：[错误信息]，发生在 [场景]，已尝试 [操作]”
方案设计	“需要实现 XXX，约束条件：[时间/技术/依赖]”
知识问答	“[概念] 是什么？用 [场景] 举例说明”
文件操作	“查找包含 XXX 的文件，然后做 YYY”
数据分析	“分析 [数据源]，输出 XXX 格式，关注 YYY 指标”

12.3 Thinking Level 指南

级别	适用场景	Token 消耗
`off`	简单查询、状态查看	最低
`minimal`	日常对话、简单问答	低
`low`	普通任务	较低
`medium`	代码修改、方案设计	中等
`high`	复杂编码、架构设计	较高
`xhigh`	深度分析、多步骤推理	高
`adaptive`	让模型自行判断	动态
`max`	关键任务、需要极致质量	最高

12.4 让 Agent “记住” 你

在对话中使用这些表达：

“以后遇到 XXX 情况，优先用 YYY 方案”
“记住我的项目路径是 XXX”
“每次写代码都要用 XXX 规范”
“不要问确认，直接做”
“这个决策过程记录下来”

Agent 会通过 Memory 系统自动保存这些偏好。

13. 多 Agent 管理

13.1 创建与管理 Agent

# 列出所有 Agent
openclaw agents list

# 添加新 Agent
openclaw agents add ops        # 运维专用
openclaw agents add coding     # 编码专用
openclaw agents add research   # 研究专用

# 设置 Agent 身份
openclaw agents set-identity ops --name "运维助手" --emoji "🔧"

# 添加路由绑定（将特定 Channel 路由到 Agent）
openclaw agents bind ops --channel telegram --target "@ops-chat"

# 查看绑定
openclaw agents bindings

# 解绑
openclaw agents unbind ops --channel telegram

# 删除 Agent
openclaw agents delete ops

13.2 Agent 路由示例

Telegram Bot @ops-bot  ──→  ops Agent（MiniMax）
WhatsApp 特定号码      ──→  main Agent（Qwen）
TUI 终端              ──→  main Agent（默认）
定时任务（晨报）        ──→  main Agent

14. MCP 扩展

MCP（Model Context Protocol）允许 Agent 接入外部工具服务。

14.1 MCP 操作

# 列出已配置的 MCP Server
openclaw mcp list

# 查看完整 MCP 配置
openclaw mcp show

# 查看单个 Server
openclaw mcp show "mysql"

# 添加 MCP Server
openclaw mcp set "mysql" '{"command":"npx","args":["-y","@modelcontextprotocol/server-mysql","mysql://..."]}'

# 移除 MCP Server
openclaw mcp unset "mysql"

# 作为 MCP Server 暴露给外部
openclaw mcp serve

14.2 常见 MCP 集成

你的环境中可能已安装的 MCP：

MySQL（数据库查询）
Redis（缓存操作）
Feishu/Lark（飞书文档、消息、群聊）
浏览器自动化
文件系统操作

15. 故障排查

15.1 诊断命令矩阵

症状	命令
Gateway 连不上	`openclaw gateway probe`
Agent 不回复	`openclaw health` + `openclaw logs --follow`
Channel 断开	`openclaw channels status --probe`
配置有错误	`openclaw config validate`
全面体检	`openclaw doctor --fix`
安全审计	`openclaw security audit --deep`
模型不工作	`openclaw models status`
记忆搜索不到	`openclaw memory status`
查看诊断包	`openclaw gateway diagnostics`
权限审批卡住	`openclaw devices list`
用量不更新	`openclaw gateway usage-cost`

15.2 常见问题

Gateway 启动失败

# 1. 检查端口占用
lsof -i :18789

# 2. 强制杀掉旧进程再启动
openclaw gateway --force

# 3. 查看配置是否合法
openclaw config validate

# 4. 前台模式看详细日志
openclaw gateway run --verbose

Agent 不回复 / 超时

# 1. 检查 API Key 是否有效
openclaw models status

# 2. 检查 Gateway 是否正常
openclaw health

# 3. 增加超时
openclaw agent --session-id main --message "..." --timeout 1800

# 4. 切换模型试试
openclaw models set "qwen/qwen3.5-plus"

Channel 掉线

# 1. 重新登录
openclaw channels login --channel whatsapp

# 2. 查看 Channel 日志
openclaw channels logs

# 3. 重新添加
openclaw channels remove --channel telegram
openclaw channels add --channel telegram --token "..."

权限审批卡住（scope upgrade pending）

# 1. 查看待审批列表
openclaw devices list

# 2. 批准请求
openclaw devices approve <request-id>

# 3. 再次执行失败的命令
openclaw gateway usage-cost

记忆索引损坏

openclaw memory index --force
openclaw memory status

用量始终为 0

# 1. 确认 Agent 正常执行过推理
openclaw agent --session-id main --message "test" --thinking minimal --json

# 2. 检查模型 cost 配置
openclaw models status

# 3. 查看 Gateway 日志
openclaw logs --follow

# 4. 如果 provider 不上报 usage，属正常现象
#    通过模型控制台查看实际用量

15.3 重置与恢复

# 重置配置（保留 CLI）
openclaw reset

# 完全卸载（含数据）
openclaw uninstall

# 备份状态
openclaw backup create

# 验证备份
openclaw backup verify ./backup-archive.tar.gz

附录 A：TUI 快捷键

按键	功能
`Ctrl+C`	取消当前操作
`Ctrl+L`	清屏
`↑/↓`	历史消息
`Ctrl+O`	查看完整摘要
`/help`	内置帮助
`/clear`	清除当前会话历史
`/status`	查看当前状态
`/models`	切换模型

附录 B：环境变量

变量	说明
`OPENCLAW_STATE_DIR`	状态目录（默认 `~/.openclaw`）
`OPENCLAW_CONFIG_PATH`	配置文件路径
`OPENCLAW_GATEWAY_TOKEN`	Gateway 认证 Token
`OPENCLAW_CONTAINER`	容器名称
`CDP_PROXY_PORT`	Chrome CDP 代理端口

附录 C：命令速查表

日常操作	命令
打开对话	`openclaw tui`
发一条消息	`openclaw agent --session-id main --message "..."`
查看状态	`openclaw status`
检查健康	`openclaw health`
查看日志	`openclaw logs --follow`
切换模型	`openclaw models set "provider/model"`
查看技能	`openclaw skills list`
查看用量	`openclaw gateway usage-cost`
设备审批	`openclaw devices list` → `openclaw devices approve <id>`
打开 Dashboard	`openclaw dashboard`

附录 D：Workspace 文件说明

文件	作用	是否必需
`AGENTS.md`	Agent 行为指令	是
`SOUL.md`	Agent 性格设定	推荐
`TOOLS.md`	工具使用说明	推荐
`IDENTITY.md`	Agent 身份定义	推荐
`USER.md`	用户偏好信息	推荐
`HEARTBEAT.md`	心跳任务指令	可选
`BOOTSTRAP.md`	启动引导信息	可选

本指南基于 OpenClaw 2026.4.23 编写。更多文档请访问 https://docs.openclaw.ai

龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

Agent消息通道实战：如何用Cloud Pub/Sub实现可靠事件驱动与乱序处理

龙虾开发者社区

Agent 网关密钥轮换：为什么你的 API Key 总在半夜失效？

龙虾开发者社区

Agent 网关常驻进程的崩溃恢复：为什么你的守护进程总在深夜挂掉？

龙虾开发者社区

所有评论(0)

查看更多评论

Java小白笔记

@weixin_45285213

已为社区贡献3条内容

OpenClaw 详细使用指南

Java小白笔记

OpenClaw 详细使用指南

目录

0. 安装步骤

0.1 环境要求

0.2 安装 OpenClaw

0.3 首次引导

0.4 手动配置模型

0.5 启动 Gateway

0.6 安装为系统服务（可选）

0.7 安全加固（必须做）

1. 架构概览

2. 目录结构

3. 配置文件详解

3.1 主配置 ~/.openclaw/openclaw.json

3.2 配置项详解

models — 模型与 Provider

agents.defaults — Agent 默认配置

gateway — 网关配置

env — 环境变量

channels — 聊天通道

logging — 日志

3.3 配置文件操作命令

4. 核心命令参考

4.1 Gateway 管理

4.2 Agent 交互

4.3 终端交互界面 TUI

4.4 模型管理

4.5 状态与诊断

4.6 配置向导

5. Channel 接入指南

5.1 支持的 Channel

5.2 添加 Channel

5.3 消息收发

6. Skills 技能系统

6.1 技能管理

6.2 你的环境已有技能（部分）

6.3 创建自定义技能

7. Memory 记忆系统

7.1 记忆操作

7.2 记忆工作原理

8. 定时任务 Cron

8.1 Cron 操作

8.2 Cron 表达式速查

9. 执行策略与安全

9.1 执行策略层级

9.2 三个预设档位

9.3 命令审批白名单

9.4 安全审计

10. 设备配对与权限审批

10.1 什么是设备配对

10.2 常见问题：scope upgrade pending approval

10.3 设备管理

10.4 安全建议

11. 用量统计

11.1 查看用量

11.2 用量统计原理

11.3 用量为 0 的常见原因

11.4 用量验证方法

12. 高效使用技巧

12.1 让 Agent 更懂你的 7 个方法

1. 写好 Agent 身份指令

2. 利用多模型组合

3. 用 Session 保持上下文

4. 善用 Profile 隔离

5. 安装 Shell 补全

6. 把 Gateway 注册为系统服务

7. 使用 Dashboard 可视化管理

12.2 提问模板

12.3 Thinking Level 指南

12.4 让 Agent “记住” 你

13. 多 Agent 管理

13.1 创建与管理 Agent

13.2 Agent 路由示例

14. MCP 扩展

14.1 MCP 操作

14.2 常见 MCP 集成

15. 故障排查

15.1 诊断命令矩阵

3.1 主配置 `~/.openclaw/openclaw.json`

`models` — 模型与 Provider

`agents.defaults` — Agent 默认配置

`gateway` — 网关配置

`env` — 环境变量

`channels` — 聊天通道

`logging` — 日志