Qclaw 使用攻略

Qclaw 是基于 OpenClaw 框架打造的个人 AI 助手平台，提供强大的自动化能力和丰富的扩展技能。本文将从指令系统、目录结构、配置文件三个方面，帮助你快速上手 Qclaw。

一、指令介绍

Qclaw 提供了一套完整的命令行工具，通过 openclaw 命令可以完成各种操作。

1.1 基础指令

指令	说明	示例
`openclaw --help`	显示帮助信息	`openclaw --help`
`openclaw --version`	显示版本号	`openclaw -V`
`openclaw status`	显示频道健康和最近会话状态	`openclaw status`
`openclaw docs`	搜索在线文档	`openclaw docs sessions`

1.2 常用管理指令

Gateway 相关

openclaw gateway status    # 查看 Gateway 状态
openclaw gateway start     # 启动 Gateway 服务
openclaw gateway stop      # 停止 Gateway 服务
openclaw gateway restart   # 重启 Gateway 服务

会话管理

1 2	openclaw sessions list # 列出存储的会话 openclaw sessions history # 查看会话历史

技能管理

1 2	openclaw skills list # 列出可用技能 openclaw skills inspect # 检查技能状态

模型管理

1 2	openclaw models list # 列出配置的模型 openclaw models scan # 扫描可用模型

1.3 聊天指令（在对话中使用）

指令	说明
`/reset`	重置当前会话上下文
`/status`	显示当前会话状态（用量、时间、成本）
`/memory`	管理记忆文件
`/resume`	恢复之前的会话
`/reasoning`	切换推理模式开关
`/stop`	停止当前任务

1.4 其他实用指令

# 配置管理
openclaw config get <path>     # 获取配置项
openclaw config set <path> <value>  # 设置配置项
openclaw configure             # 交互式配置向导

# 定时任务
openclaw cron list             # 列出定时任务
openclaw cron add              # 添加定时任务
openclaw cron run <jobId>      # 立即执行任务

# 消息管理
openclaw message send          # 发送消息
openclaw channels list         # 列出已连接的频道

# 设备管理
openclaw devices list          # 列出配对的设备
openclaw nodes status          # 查看节点状态

# 系统维护
openclaw doctor                # 健康检查
openclaw logs                  # 查看日志
openclaw update check          # 检查更新
openclaw backup create         # 创建备份

1.5 全局选项

--dev                # 开发模式：隔离状态和配置
--profile <name>     # 使用命名的配置 profile
--log-level <level>  # 设置日志级别 (silent|fatal|error|warn|info|debug|trace)
--no-color           # 禁用彩色输出

二、目录结构介绍

Qclaw 的数据主要分布在两个目录：数据目录 和 安装目录。

2.1 数据目录 `~/.qclaw/`

在 Windows 系统中位于：C:\Users\<用户名>\.qclaw\

~/.qclaw/
├── agents/                    # Agent 工作区
│   ├── agent-aa725a3a/        # 各个 Agent 的配置目录
│   │   └── agent/
│   ├── workspace-agent-aa725a3a/  # 各个 Agent 的工作空间
│   └── main/                  # 主 Agent
│
├── backups/                   # 自动备份目录
├── browser/                   # 浏览器配置文件
├── canvas/                    # 画布相关数据
├── cron/                      # 定时任务数据
│   └── cron.db
├── devices/                   # 配对设备信息
├── identity/                  # 身份标识
├── logs/                      # 日志文件
│   └── server.log
├── memory/                    # 记忆文件（手动维护）
│   ├── lossless/              # LCM 无损压缩记忆数据库
│   │   └── lcm.db
│   └── YYYY-MM-DD.md          # 每日记忆笔记
├── plugins/                   # 插件数据
├── qmemory/                   # 短期记忆缓存
├── skills/                    # 用户自定义技能
│   ├── amap-jsapi-skill/
│   ├── amap-lbs-skill/
│   └── ...
├── workspace/                 # 默认工作空间
├── .auto-memory/              # 自动记忆索引
├── .gitattributes             # Git 属性
├── .gitignore                 # Git 忽略规则
├── openclaw.json              # OpenClaw 运行时配置
├── openclaw.json.bak          # 配置备份
└── qclaw.json                 # Qclaw 基础配置

主要文件说明

文件/目录	说明
`qclaw.json`	Qclaw 基础配置，包含 CLI 路径、状态目录、端口等
`openclaw.json`	OpenClaw 运行时配置，包含模型、Agent、频道、插件等
`server.log`	Gateway 服务日志
`memory/YYYY-MM-DD.md`	每日记忆笔记，记录当天的重要事件
`MEMORY.md`	长期记忆文件（ curated memory）
`cron/cron.db`	定时任务数据库
`agents/`	各个 Agent 的配置和工作空间

2.1.1 Workspace MD 文件详解

~/.qclaw/workspace/ 目录是 Qclaw Agent 的工作空间目录，包含多个 Markdown 配置文件，用于定义 Agent 的行为规范、记忆系统和工具配置。

~/.qclaw/workspace/
├── AGENTS.md       # Agent 工作空间主配置文件
├── SOUL.md         # Agent 人格灵魂定义
├── IDENTITY.md     # Agent 身份标识
├── USER.md         # 用户信息模板
├── MEMORY.md       # 长期记忆文件
├── HEARTBEAT.md    # 心跳任务配置
├── TOOLS.md        # 本地工具配置
├── BOOTSTRAP.md    # 首次启动引导脚本（使用后删除）
├── memory/         # 每日记忆目录
│   └── YYYY-MM-DD.md  # 当日记忆笔记
└── .openclaw/      # 内部状态文件
    └── workspace-state.json

文件说明表

文件名	是否必需	说明
`AGENTS.md`	✅ 必须	核心配置文件。定义 Agent 的工作规则、启动流程、文件系统规范、对话行为准则。Agent 每次会话都会读取此文件。
`SOUL.md`	✅ 必须	人格灵魂定义。描述 Agent 的性格特点、说话风格、价值观。塑造 Agent 的独特个性。
`IDENTITY.md`	✅ 必须	身份标识。定义 Agent 的名称、emoji、角色定位、人设描述。
`USER.md`	✅ 必须	用户信息模板。记录用户的基本信息、偏好、时区、项目背景等。帮助 Agent 更好地了解用户。
`MEMORY.md`	✅ 必须	长期记忆。Agent 精心维护的记忆文件，包含重要决策、历史上下文、持续性信息。只在主会话（直接对话）中读取。
`HEARTBEAT.md`	⭕ 可选	心跳任务配置。定义周期性自动执行的后台任务（如检查邮件、日历）。为空时不执行任何任务。
`TOOLS.md`	⭕ 可选	本地工具配置。记录本地环境的特定配置（如 SSH 主机、TTS 偏好、摄像头位置）。技能共享，但工具配置是你的专属。
`BOOTSTRAP.md`	⭕ 仅首次	首次启动引导。仅在首次运行时存在，用于 Agent 初始化身份和人格设定。初始化完成后会自动删除。
`memory/YYYY-MM-DD.md`	⭕ 自动	每日记忆笔记。按日期自动创建的每日记录，保存当天的对话摘要和事件。
`.openclaw/workspace-state.json`	⭕ 自动	内部状态文件。由 OpenClaw 自动生成和维护，记录工作空间状态。

示例内容

AGENTS.md 示例

# AGENTS.md - 工作空间配置

## 启动流程
1. 读取 SOUL.md 了解人格设定
2. 读取 USER.md 了解用户信息
3. 读取 MEMORY.md 调取长期记忆
4. 检查 HEARTBEAT.md 是否有待执行任务

## 内存维护规则
- 重要决策写入 MEMORY.md
- 每日工作记录写入 memory/YYYY-MM-DD.md
- 定期（每隔几天）将每日笔记中有价值的内容提炼到 MEMORY.md

## 行为准则
- 主动提供帮助，但不强行介入
- 遇到不确定的问题，诚实地表达不确定性
- 尊重用户隐私，不记录敏感信息

SOUL.md 示例

# SOUL.md - 人格灵魂

## 性格特点
- 专业但不刻板：严谨对待技术问题，轻松对待日常交流
- 主动但不越界：积极提供帮助，但尊重用户主导权
- 诚实但有温度：承认错误和不确定性，但保持友善语气

## 说话风格
- 技术问题：简洁准确，重点突出
- 日常交流：轻松自然，适度幽默
- 建议反馈：具体可行，有理有据

IDENTITY.md 示例

# IDENTITY.md - 身份标识

- Name: 小Q
- Emoji: 🤖
- Vibe: 智能、可靠、友善的 AI 助手

USER.md 示例

# USER.md - 用户信息

## 基本信息
- **姓名：** [用户名]
- **称呼：** [用户偏好的称呼]
- **时区：** Asia/Shanghai

## 背景
- 从事 [行业/职业]
- 使用 Qclaw 主要用于 [主要用途]

## 偏好
- 沟通风格：简洁 / 详细
- 回复语言：[中文/英文/...]

MEMORY.md 示例

# MEMORY.md - 长期记忆

## 关于用户
- 用户从事 [职业]，关注 [领域]
- 偏好 [沟通风格/技术栈/工具]

## 项目背景
- [项目名称]：正在进行中
  - 目标：[项目目标]
  - 进展：[当前进展]

## 重要决策
- [日期]：[做出的重要决定及其原因]

## 待办事项
- [ ] [未完成的任务]

HEARTBEAT.md 示例

# HEARTBEAT.md

## 周期性任务
- 每天上午 9:00 检查邮箱
- 每周一上午 10:00 发送周报提醒

## 任务说明
检查邮箱时如有重要邮件（如来自 [重要联系人]），立即通知。

TOOLS.md 示例

# TOOLS.md - 本地工具配置

## TTS 语音
- 优先使用语音播报长文本
- 重要通知使用标准男声

## 截图设置
- 分辨率：1920x1080
- 快捷键：Win+Shift+S

安全注意事项

⚠️ 重要提醒：MEMORY.md 和 USER.md 包含用户个人信息，不要将这些文件分享给他人或上传到公共平台。

✅ 可以分享：AGENTS.md（工作规范）、IDENTITY.md（身份定义）
❌ 不要分享：USER.md（用户隐私）、MEMORY.md（个人记忆）、TOOLS.md（本地配置）
🔒 安全做法：在分享前先检查文件内容，确保没有敏感信息

2.2 安装目录 `D:\app\QClaw\`

D:\app\QClaw/
├── resources/
│   └── openclaw/              # OpenClaw 核心资源
│       ├── config/            # 配置文件目录
│       │   ├── bin/           # 内置脚本
│       │   ├── extensions/    # 插件扩展
│       │   │   └── lossless-claw/    # LCM 无损压缩插件
│       │   └── skills/        # 内置技能库
│       │       ├── browser-cdp/
│       │       ├── content-factory/
│       │       ├── docx/
│       │       ├── email-skill/
│       │       ├── pdf/
│       │       ├── pptx/
│       │       ├── qclaw-cron-skill/
│       │       ├── qclaw-env/
│       │       ├── qclaw-rules/
│       │       ├── qclaw-text-file/
│       │       ├── tencent-docs/
│       │       ├── tencent-survey/
│       │       └── ...
│       ├── memory-fs/         # 内存文件系统
│       └── node_modules/      # Node.js 依赖
│
├── security/                  # 安全组件
│   └── lowpriv-launcher.exe   # 低权限启动器
│
└── ...

主要文件夹说明

目录	说明
`resources/openclaw/config/skills/`	内置技能库，包含所有官方技能
`resources/openclaw/config/extensions/`	插件扩展目录
`resources/openclaw/node_modules/`	OpenClaw 的 Node.js 依赖
`resources/openclaw/docs/`	本地文档（镜像：https://docs.openclaw.ai）
`resources/security/`	安全相关组件

三、配置说明

3.1 `~/.qclaw/qclaw.json`

这是 Qclaw 的基础配置文件，通常不需要手动修改。

{
  "authGatewayBaseUrl": "http://127.0.0.1:19000/proxy",
  "cli": {
    "nodeBinary": "D:\\app\\QClaw\\resources\\node\\node.exe",
    "openclawMjs": "D:\\app\\QClaw\\resources\\openclaw\\node_modules\\openclaw\\openclaw.mjs",
    "pid": 4432
  },
  "stateDir": "C:\\Users\\91383\\.qclaw",
  "configPath": "C:\\Users\\91383\\.qclaw\\openclaw.json",
  "port": 28789,
  "platform": "win32"
}

配置项说明

字段	说明	默认值/示例
`authGatewayBaseUrl`	认证网关基础 URL	`http://127.0.0.1:19000/proxy`
`cli.nodeBinary`	Node.js 可执行文件路径	安装目录自动配置
`cli.openclawMjs`	OpenClaw 入口文件路径	安装目录自动配置
`cli.pid`	CLI 进程 ID	运行时自动生成
`stateDir`	状态数据目录	`~/.qclaw`
`configPath`	主配置文件路径	`~/.qclaw/openclaw.json`
`port`	Gateway 服务端口	`28789`
`platform`	操作系统平台	`win32` / `darwin` / `linux`

3.2 `~/.qclaw/openclaw.json`

这是 OpenClaw 的核心配置文件，包含模型、Agent、频道、插件等所有运行时配置。

3.2.1 模型配置 (`models`)

{
  "models": {
    "mode": "merge",
    "providers": {
      "qclaw": {
        "baseUrl": "${QCLAW_LLM_BASE_URL}",
        "apiKey": "${QCLAW_LLM_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "modelroute", "name": "modelroute" }
        ]
      },
      "qwen": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxx",
        "api": "openai-completions",
        "models": [
          { "id": "qwen3.5-plus", "name": "qwen3.5-plus" }
        ]
      },
      "zhipu-plan": {
        "baseUrl": "https://open.bigmodel.cn/api/anthropic",
        "apiKey": "xxxxxxxx.XXXXXXXXXXXX",
        "api": "anthropic-messages",
        "models": [
          { "id": "GLM-5-Turbo", "name": "GLM-5-Turbo" }
        ]
      }
    }
  }
}

字段	说明
`mode`	配置模式：`merge`（合并）或 `override`（覆盖）
`providers`	模型提供商列表，可配置多个
`baseUrl`	API 基础 URL，支持环境变量 `${VAR_NAME}`
`apiKey`	API 密钥，支持环境变量
`api`	API 类型：`openai-completions` / `anthropic-messages`
`models`	该提供商下可用的模型列表

🔍 `mode` 字段详解：merge vs override

models.mode 字段控制配置文件的加载方式，理解这个区别对于多配置文件场景非常重要。

merge 模式（推荐）

行为： 将当前配置文件与默认配置合并，只覆盖明确指定的字段。

适用场景：

只想修改部分配置项
保留默认配置的其他设置
多配置文件叠加使用

示例：

假设默认配置中有 3 个模型提供商：

// 默认配置
{
  "models": {
    "providers": {
      "provider-a": { ... },
      "provider-b": { ... },
      "provider-c": { ... }
    }
  }
}

使用 merge 模式时，你的配置只需指定要修改的部分：

// 你的配置 (mode: "merge")
{
  "models": {
    "providers": {
      "qwen": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-xxxxx"
      }
    }
  }
}

最终生效配置： 默认配置 + 你的 qwen 配置（共 4 个提供商）

override 模式

行为： 用当前配置文件完全替换默认配置，未指定的字段将丢失。

适用场景：

需要完全控制所有配置项
不想继承任何默认配置
创建独立的配置 profile

示例：

使用 override 模式时：

// 你的配置 (mode: "override")
{
  "models": {
    "providers": {
      "qwen": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-xxxxx"
      }
    }
  }
}

最终生效配置： 只有 qwen 一个提供商（默认的 provider-a/b/c 全部丢失）

两种模式对比表

特性	merge 模式	override 模式
配置继承	✅ 继承默认配置	❌ 不继承，完全替换
配置复杂度	低（只需写差异）	高（需要写完整配置）
安全性	较高（不易遗漏配置）	较低（容易遗漏重要配置）
灵活性	中等	最高
推荐场景	日常使用	特殊需求/测试
推荐指数	⭐⭐⭐⭐⭐	⭐⭐⭐

实际案例

场景： 你想添加一个新的模型提供商，但保留现有的配置。

✅ 正确做法（merge 模式）：

{
  "models": {
    "mode": "merge",
    "providers": {
      "zhipu": {
        "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
        "apiKey": "your-api-key",
        "api": "openai-completions",
        "models": [{ "id": "glm-4", "name": "GLM-4" }]
      }
    }
  }
}

结果：现有配置 + 新添加的 zhipu 提供商

❌ 错误做法（override 模式）：

{
  "models": {
    "mode": "override",
    "providers": {
      "zhipu": { ... }
    }
  }
}

结果：只有 zhipu 提供商，其他所有配置丢失！

如何选择

99% 的情况使用 merge：安全、简单、不易出错
仅在以下情况使用 override：
- 创建完全独立的测试环境
- 需要清除所有默认配置
- 使用 --profile 创建隔离的配置 profile

检查当前模式

# 查看当前配置
openclaw config get models.mode

# 查看完整模型配置
openclaw config get models

切换模式

编辑 ~/.qclaw/openclaw.json，修改 models.mode 字段后重启 Gateway：

{
  "models": {
    "mode": "merge"  // 或 "override"
  }
}

1 2	# 重启使配置生效 openclaw gateway restart

3.2.2 Agent 配置 (`agents`)

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "qwen/qwen3.5-plus"
      },
      "workspace": "C:\\Users\\91383\\.qclaw\\workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "timeoutSeconds": 72000,
      "maxConcurrent": 3
    },
    "list": [
      {
        "id": "main",
        "name": "QClaw"
      },
      {
        "id": "agent-aa725a3a",
        "name": "无不言",
        "workspace": "D:\\app\\openclaw\\.qclaw\\workspace-agent-aa725a3a",
        "agentDir": "C:\\Users\\91383\\.qclaw\\agents\\agent-aa725a3a\\agent",
        "skills": [
          "content-factory",
          "docx",
          "pptx",
          "pdf",
          "xlsx",
          "online-search",
          "browser-cdp",
          "qclaw-rules",
          "qclaw-env",
          "qclaw-text-file",
          "qclaw-cron-skill"
        ]
      }
    ]
  }
}

字段	说明
`defaults.model.primary`	默认使用的主模型
`defaults.workspace`	默认工作空间路径
`defaults.compaction.mode`	上下文压缩模式
`defaults.timeoutSeconds`	会话超时时间（秒）
`defaults.maxConcurrent`	最大并发会话数
`list`	Agent 列表，可配置多个不同角色的 Agent
`skills`	该 Agent 启用的技能列表

3.2.3 频道配置 (`channels`)

{
  "channels": {
    "wechat-access": {
      "enabled": true,
      "token": "c590xxxxxxxxxxxxxx38963",
      "wsUrl": "${QCLAW_WECHAT_WS_URL}",
      "guid": "2811c3xxxxxxxxxxxxxxxxxxxxxx831",
      "userId": "1823150851"
    },
    "openclaw-weixin": {
      "enabled": true
    }
  }
}

字段	说明
`wechat-access.enabled`	是否启用微信通道
`token`	微信访问令牌
`wsUrl`	WebSocket 服务器地址
`guid`	用户全局标识
`userId`	用户 ID

3.2.4 Gateway 配置 (`gateway`)

{
  "gateway": {
    "port": 28789,
    "mode": "local",
    "bind": "loopback",
    "controlUi": {
      "allowedOrigins": [
        "null",
        "file://"
      ]
    },
    "auth": {
      "mode": "token",
      "token": "3c9xxxxxxxxxxxx3888cd"
    },
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    },
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

字段	说明
`port`	Gateway 服务端口
`mode`	运行模式：`local` / `remote`
`bind`	绑定地址：`loopback`（仅本地） / `all`（所有接口）
`controlUi.allowedOrigins`	允许访问控制 UI 的来源
`auth.mode`	认证模式：`token` / `none`
`auth.token`	访问令牌
`tailscale.mode`	Tailscale 组网模式
`http.endpoints.chatCompletions.enabled`	是否启用 Chat Completions API

3.2.5 插件配置 (`plugins`)

{
  "plugins": {
    "enabled": true,
    "allow": [
      "wechat-access",
      "qclaw-plugin",
      "openclaw-weixin",
      "skill-interceptor",
      "queue-guard",
      "lossless-claw"
    ],
    "load": {
      "paths": [
        "D:\\app\\QClaw\\resources\\openclaw\\config\\extensions"
      ]
    },
    "entries": {
      "lossless-claw": {
        "enabled": true,
        "config": {
          "dbPath": "~/.qclaw/memory/lossless/lcm.db",
          "contextThreshold": 0.6,
          "freshTailCount": 16,
          "incrementalMaxDepth": 5
        }
      },
      "skill-interceptor": {
        "enabled": true,
        "config": {
          "blockedSkills": [
            "tencent-docs",
            "tencent-survey",
            "notion",
            "imap-smtp-email"
          ],
          "logOnly": false
        }
      }
    }
  }
}

字段	说明
`enabled`	是否启用插件系统
`allow`	允许加载的插件列表
`load.paths`	插件加载路径
`entries`	各个插件的具体配置
`entries.lossless-claw.config.contextThreshold`	LCM 上下文压缩阈值（0-1）
`entries.skill-interceptor.config.blockedSkills`	被拦截禁止加载的技能

3.2.6 会话配置 (`session`)

{
  "session": {
    "dmScope": "per-channel-peer",
    "reset": {
      "mode": "idle",
      "idleMinutes": 525600
    },
    "maintenance": {
      "pruneAfter": "365d",
      "maxEntries": 1000000,
      "rotateBytes": "1gb",
      "resetArchiveRetention": false
    }
  }
}

字段	说明
`dmScope`	私聊会话作用域
`reset.mode`	重置模式：`idle`（空闲时） / `manual`（手动）
`reset.idleMinutes`	空闲多少分钟后重置（525600 = 1 年）
`maintenance.pruneAfter`	会话保留时间
`maintenance.maxEntries`	最大条目数
`maintenance.rotateBytes`	日志轮转大小

3.2.7 技能配置 (`skills`)

{
  "skills": {
    "load": {
      "extraDirs": [
        "C:\\Users\\91383\\.qclaw\\skills",
        "D:\\app\\QClaw\\resources\\openclaw\\config\\skills"
      ]
    },
    "entries": {
      "tencent-docs": {
        "enabled": true
      },
      "tencent-survey": {
        "enabled": true
      },
      "skill-creator": {
        "enabled": false
      }
    }
  }
}

字段	说明
`load.extraDirs`	技能加载目录列表
`entries`	各个技能的启用状态

四、环境变量与命令执行

4.1 环境变量问题

在 ~/.qclaw/openclaw.json 配置文件中，某些字段支持使用环境变量语法 ${VAR_NAME}，例如：

{
  "models": {
    "providers": {
      "qclaw": {
        "baseUrl": "${QCLAW_LLM_BASE_URL}",
        "apiKey": "${QCLAW_LLM_API_KEY}"
      }
    }
  },
  "channels": {
    "wechat-access": {
      "wsUrl": "${QCLAW_WECHAT_WS_URL}"
    }
  }
}

⚠️ 重要提示： 如果环境变量未配置，这些字段的值将保持为原始字符串（如 ${QCLAW_LLM_API_KEY}），导致 API 调用失败。

4.2 常见环境变量

变量名	说明	配置位置
`QCLAW_LLM_BASE_URL`	大模型 API 基础 URL	系统环境变量
`QCLAW_LLM_API_KEY`	大模型 API 密钥	系统环境变量
`QCLAW_WECHAT_WS_URL`	微信 WebSocket 服务器地址	系统环境变量

4.3 如何配置环境变量

Windows 系统

方法一：通过系统属性配置（永久生效）

右键”此电脑” → “属性” → “高级系统设置”
点击”环境变量”按钮
在”用户变量”或”系统变量”中点击”新建”
输入变量名和变量值，例如：
- 变量名：QCLAW_LLM_API_KEY
- 变量值：sk-xxxxxxxxxxxxxxxx
点击”确定”保存
重启终端使配置生效

方法二：通过 PowerShell 配置

# 当前会话临时生效
$env:QCLAW_LLM_API_KEY="sk-xxxxxxxxxxxxxxxx"

# 永久生效（用户级别）
[System.Environment]::SetEnvironmentVariable("QCLAW_LLM_API_KEY", "sk-xxxxxxxxxxxxxxxx", "User")

# 永久生效（系统级别，需要管理员权限）
[System.Environment]::SetEnvironmentVariable("QCLAW_LLM_API_KEY", "sk-xxxxxxxxxxxxxxxx", "Machine")

方法三：直接在配置文件中写死（不推荐用于生产环境）

{
  "models": {
    "providers": {
      "qwen": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-f58a11a554694f46a7a238062d679c3e"
      }
    }
  }
}

macOS / Linux 系统

# 添加到 ~/.bashrc 或 ~/.zshrc
export QCLAW_LLM_API_KEY="sk-xxxxxxxxxxxxxxxx"
export QCLAW_LLM_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"

# 使配置生效
source ~/.bashrc  # 或 source ~/.zshrc

4.4 验证环境变量是否生效

# Windows PowerShell
echo $env:QCLAW_LLM_API_KEY

# macOS / Linux
echo $QCLAW_LLM_API_KEY

如果输出为空或显示 ${QCLAW_LLM_API_KEY} 原文，说明环境变量未正确配置。

4.5 避免环境变量配置的方法

方法一：使用绝对路径运行命令

如果不想配置环境变量，可以直接使用完整路径运行 OpenClaw 命令：

# Windows
D:\app\QClaw\resources\node\node.exe D:\app\QClaw\resources\openclaw\node_modules\openclaw\openclaw.mjs gateway start

# macOS / Linux
/usr/local/bin/node /path/to/openclaw/node_modules/openclaw/openclaw.mjs gateway start

方法二：使用 Qclaw 内置的 CLI 封装

Qclaw 安装后会自动创建命令行入口，无需额外配置：

# 直接使用 openclaw 命令（推荐）
openclaw gateway start
openclaw status
openclaw agent --message "Hello"

方法三：在 qclaw.json 中配置固定路径

编辑 ~/.qclaw/qclaw.json，确保 cli 字段指向正确的路径：

{
  "cli": {
    "nodeBinary": "D:\\app\\QClaw\\resources\\node\\node.exe",
    "openclawMjs": "D:\\app\\QClaw\\resources\\openclaw\\node_modules\\openclaw\\openclaw.mjs"
  }
}

4.6 排查命令不生效的问题

如果运行 openclaw 命令提示”未找到命令”或”command not found”：

Windows 排查步骤：

# 1. 检查 openclaw 是否在 PATH 中
where openclaw

# 2. 如果没有输出，手动添加 PATH
# 找到 Qclaw 安装目录的 bin 文件夹，例如：
# D:\app\QClaw\resources\openclaw\config\bin

# 3. 临时添加到当前会话的 PATH
$env:Path += ";D:\app\QClaw\resources\openclaw\config\bin"

# 4. 永久添加（用户级别）
$currentUserPath = [System.Environment]::GetEnvironmentVariable("Path", "User")
[System.Environment]::SetEnvironmentVariable("Path", "$currentUserPath;D:\app\QClaw\resources\openclaw\config\bin", "User")

macOS / Linux 排查步骤：

# 1. 检查 openclaw 是否在 PATH 中
which openclaw

# 2. 如果没有输出，添加到 PATH
# 在 ~/.bashrc 或 ~/.zshrc 中添加
export PATH="$PATH:/path/to/openclaw/bin"

# 3. 使配置生效
source ~/.bashrc  # 或 source ~/.zshrc

五、快速开始

5.1 初始化配置

首次使用 Qclaw，运行交互式配置向导：

1	openclaw configure

按照提示完成：

模型提供商配置（API Key 等）
聊天频道连接（微信/Telegram/Discord 等）
Gateway 服务设置
Agent 工作空间初始化

5.2 启动 Gateway

1	openclaw gateway start

或使用开发模式（隔离配置）：

1	openclaw --dev gateway start

5.3 查看状态

1	openclaw status

5.4 打开控制 UI

1	openclaw dashboard

六、常见问题

Q1: 如何切换模型？

编辑 ~/.qclaw/openclaw.json，修改 agents.defaults.model.primary 字段，然后重启 Gateway。

Q2: 如何添加新技能？

将技能文件夹放入 ~/.qclaw/skills/ 目录，然后在配置文件中启用。

Q3: 如何备份数据？

1	openclaw backup create

备份文件会保存在 ~/.qclaw/backups/ 目录。

Q4: 如何查看日志？

1	openclaw logs

或直接查看 ~/.qclaw/logs/server.log 文件。

Q5: Gateway 端口冲突怎么办？

1	openclaw gateway --force

强制释放端口并重启。

Q6: merge 和 override 模式选哪个？

99% 的情况选择 merge 模式。

merge：安全、简单，只覆盖你明确指定的配置
override：危险，会完全替换默认配置，容易丢失重要设置

除非你有特殊需求（如创建完全隔离的测试环境），否则始终使用 merge。

Q7: 配置修改后不生效怎么办？

检查 JSON 语法是否正确（可用在线 JSON 验证器）
确认环境变量是否已配置并生效
重启 Gateway 使配置生效：
1
openclaw gateway restart
查看日志确认是否有配置错误：
1
openclaw logs

Q8: 如何验证当前生效的配置？

# 查看特定配置项
openclaw config get models.mode
openclaw config get gateway.port

# 查看完整配置
openclaw config get

Q9: 命令提示”未找到命令”怎么办？

Windows：

# 检查是否在 PATH 中
where openclaw

# 临时添加到 PATH
$env:Path += ";D:\app\QClaw\resources\openclaw\config\bin"

macOS / Linux：

# 检查是否在 PATH 中
which openclaw

# 添加到 ~/.bashrc 或 ~/.zshrc
export PATH="$PATH:/path/to/openclaw/bin"
source ~/.bashrc

七、参考资料

官方文档: https://docs.openclaw.ai
GitHub 源码: https://github.com/openclaw/openclaw
Discord 社区: https://discord.com/invite/clawd
技能市场: https://clawhub.com

💡 提示: 配置文件修改后，记得重启 Gateway 服务使配置生效：
1
openclaw gateway restart