OpenClaw 完全指南：Docker 部署 · 记忆系统 · 多 Agent

基于 dhso/openclaw-docker 封装，适合快速部署个人 AI 助理。

什么是 OpenClaw？

OpenClaw 是一个开源的自托管个人 AI 助理网关，让你可以通过钉钉、飞书、QQ、Telegram、WhatsApp 等任意消息渠道与 AI 交互。你在自己的服务器上运行一个 Gateway 进程，它成为消息渠道和 AI 模型之间的桥梁。

核心特点：

• 自托管，数据完全自主，不经过第三方
• 支持多渠道同时接入（钉钉/飞书/QQ/Telegram/WhatsApp/Discord）
• 支持多 Agent 并行运行，每个 Agent 有独立人格和记忆
• 内置分层记忆系统，AI 助理拥有真正的长期记忆
• 通过 Skills 扩展能力，支持代码执行、浏览器自动化、图片生成等

目录

1. 准备工作：VPS 选购与模型配置
2. 安全须知
3. Docker 部署
4. 渠道接入
5. 分层记忆系统
6. QMD 语义记忆搜索
7. 多 Agent 模式
8. 完整工作流示意
9. 推荐技能

一、准备工作：VPS 选购与模型配置

为什么推荐在 VPS 上用 Docker 部署？

OpenClaw 是一个自托管的个人 AI 助理网关，它能执行 shell 命令、读写文件、发送消息，权限相当大。选择合适的部署方式直接影响安全性和稳定性。

推荐 VPS + Docker 的理由：

不推荐本地部署的原因： 本地机器关机即断线，IP 变动影响外部访问，且 Agent 有权限访问本地文件系统风险更高。

推荐 VPS 方案

RackNerd 黑色星期五促销（续费同价）

多个机房可选，续费同价，适合长期运行 OpenClaw。个人使用推荐 2.5G 或 4G 套餐。

推荐 AI 模型套餐

OpenClaw 需要配置 AI 模型 API，推荐阿里云百炼系列：

阿里云 Coding Plan 接入 OpenClaw

Coding Plan 提供专属 API Key，通过 OpenAI 兼容接口接入 OpenClaw，支持 Qwen、Kimi、GLM、MiniMax 等多个主流模型，全部免费使用。

第一步：获取 Coding Plan 专属 API Key

前往 阿里云百炼控制台 获取 Coding Plan 专属 API Key（注意：不是普通百炼 API Key）。

第二步：修改 OpenClaw 配置

在 ~/.openclaw/openclaw.json 中添加以下配置（将 YOUR_API_KEY 替换为实际 Key）：

{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "YOUR_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "qwen3.5-plus（通用对话）",
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "qwen3-coder-plus",
            "name": "qwen3-coder-plus（代码专用）",
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "kimi-k2.5",
            "name": "kimi-k2.5（长上下文）",
            "input": ["text", "image"],
            "contextWindow": 262144,
            "maxTokens": 32768
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen3.5-plus"
      }
    }
  }
}

更多模型（glm-5、MiniMax-M2.5 等）见官方完整配置。

⚠️ 不要直接全量替换配置文件，否则会覆盖已有的钉钉/飞书等渠道配置。请找到对应字段局部合并。

第三步：重启生效

openclaw gateway restart

切换模型

# 临时切换（当前会话有效）
/model qwen3-coder-plus

# 永久切换（修改配置文件中的 primary 字段）

支持的模型列表

📖 完整接入文档：阿里云帮助中心 - OpenClaw 接入 Coding Plan

二、安全须知

OpenClaw 的安全模型

⚠️ OpenClaw 是个人助理安全模型，不是多租户隔离系统。一个 Gateway 对应一个信任边界（一个用户/一台 VPS）。

核心原则：访问控制 > 模型智能

大多数安全问题不是复杂攻击，而是"有人发消息，Bot 照做了"。OpenClaw 的防御思路：

1. 身份优先 — 谁能跟 Bot 说话（DM pairing / allowlist）
2. 范围其次 — Bot 能在哪里行动（工具权限、沙箱、群组限制）
3. 模型最后 — 假设模型可以被操控，设计上限制操控的影响范围

关键安全配置

1. 必须设置访问 Token

openclaw config set gateway.auth.token your-long-random-token

不设置 Token，Gateway 拒绝所有 WebSocket 连接（fail-closed）。

2. DM 访问策略

{
  channels: {
    dingtalk: {
      dmPolicy: "allowlist",   // 只允许白名单用户
      allowFrom: ["manager9327"]
    }
  }
}

• pairing（默认）：陌生人需要配对码审批
• allowlist：只允许白名单，陌生人直接拒绝
• open：任何人都能发消息（⚠️ 危险，慎用）

3. Docker 防火墙（重要！）

Docker 发布的端口会绕过 UFW 的 INPUT 规则，需要在 DOCKER-USER 链中配置：

# /etc/ufw/after.rules 末尾追加
*filter
:DOCKER-USER - [0:0]
-A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN
-A DOCKER-USER -s 127.0.0.0/8 -j RETURN
-A DOCKER-USER -s 10.0.0.0/8 -j RETURN
-A DOCKER-USER -s 192.168.0.0/16 -j RETURN
-A DOCKER-USER -m conntrack --ctstate NEW -j DROP
-A DOCKER-USER -j RETURN
COMMIT

然后 ufw reload 生效。

💡 新手提示： 如果你的 VPS 只在局域网或内网使用，或者已经通过云服务商的安全组限制了端口访问，可以跳过此步骤。UFW + Docker 的防火墙配置主要针对公网暴露的场景。

4. 工具权限最小化

对于群聊 Agent 或多人共用的 Agent，限制危险工具：

{
  tools: {
    deny: ["gateway", "cron", "sessions_spawn", "sessions_send"]
  }
}

5. 沙箱隔离（可选）

开启 Docker 沙箱，让工具执行在隔离容器内运行：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",   // 非主会话启用沙箱
        scope: "session"
      }
    }
  }
}

6. 定期安全审计

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix  # 自动修复部分问题

Prompt Injection 防护

AI 助理的特殊风险：攻击者可以通过消息内容操控模型执行恶意操作。

降低风险的措施：

• 保持 DM 白名单，不要对陌生人开放
• 群聊中使用 requireMention: true，避免 Bot 响应所有消息
• 对 web_fetch、browser 等读取外部内容的工具保持警惕
• 使用最新、最强的模型：新一代模型对 prompt injection 的抵抗力显著更强

文件权限

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

三、Docker 部署

前置要求

• Docker 已安装
• 开放端口 18789（Web 控制台）

1. 初始化配置（首次运行）

docker run --rm -it \
  -e TZ=Asia/Shanghai \
  -v openclaw_data:/root/.openclaw \
  dhso/openclaw:latest \
  openclaw onboard

2. 配置网关

# 本地网关模式
docker run --rm -e TZ=Asia/Shanghai \
  -v openclaw_data:/root/.openclaw \
  dhso/openclaw:latest \
  openclaw config set gateway.mode local

# 绑定局域网
docker run --rm -e TZ=Asia/Shanghai \
  -v openclaw_data:/root/.openclaw \
  dhso/openclaw:latest \
  openclaw config set gateway.bind lan

# 配置可信代理
docker run --rm -e TZ=Asia/Shanghai \
  -v openclaw_data:/root/.openclaw \
  dhso/openclaw:latest \
  openclaw config set gateway.trustedProxies '["127.0.0.1", "::1", "10.0.0.0/8"]'

# 设置访问 Token
docker run --rm -e TZ=Asia/Shanghai \
  -v openclaw_data:/root/.openclaw \
  dhso/openclaw:latest \
  openclaw config set gateway.auth.token your_token

# ⚠️ 2026.2.17+ 版本必须配置此项，否则启动失败
docker run --rm -e TZ=Asia/Shanghai \
  -v openclaw_data:/root/.openclaw \
  -v openclaw_cache:/root/.cache \
  dhso/openclaw:latest \
  openclaw config set gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback true

# 健康检查修复
docker run --rm -e TZ=Asia/Shanghai \
  -v openclaw_data:/root/.openclaw \
  dhso/openclaw:latest \
  openclaw doctor --fix

3. 启动服务

docker run -d \
  --name claw \
  -e TZ=Asia/Shanghai \
  -v openclaw_data:/root/.openclaw \
  -v openclaw_cache:/root/.cache \
  --restart=unless-stopped \
  -p 18789:18789 \
  dhso/openclaw:latest \
  openclaw gateway run

访问 http://ip:18789 打开 Web 控制台。

4. 使用 docker-compose（推荐）

比一堆 docker run 命令更易维护，推荐生产环境使用：

# docker-compose.yml
services:
  claw:
    image: dhso/openclaw:latest
    container_name: claw
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - openclaw_data:/root/.openclaw
      - openclaw_cache:/root/.cache
    ports:
      - "18789:18789"
    command: openclaw gateway run

volumes:
  openclaw_data:
  openclaw_cache:

# 启动
docker compose up -d

# 查看日志
docker compose logs -f claw

# 重启
docker compose restart claw

# 停止
docker compose down

数据持久化说明

⚠️ 需要持久化的文件必须放在 /root/.openclaw 下，容器重启后其他目录会丢失。

四、渠道接入

OpenClaw 支持多种即时通讯渠道，通过渠道插件将 AI 助理接入你常用的平台。以下是目前支持的主要渠道及接入文档。

支持的渠道

钉钉接入

通过钉钉应用与机器人，实现用户与机器人对话，驱动 OpenClaw 完成相关任务。

接入步骤概览：

1. 创建钉钉应用，获取 Client ID 和 Client Secret
2. 创建钉钉机器人（Stream 模式）
3. 创建卡片模板（AI 卡片，支持流式返回）
4. 申请权限：Card.Streaming.Write、Card.Instance.Write、qyapi_robot_sendmsg
5. 发布应用，添加机器人到群聊或单聊使用

📖 详细接入文档：钉钉接入指南
官方文档：OpenClaw 钉钉通道

飞书接入

通过飞书应用与机器人，实现用户通过飞书与机器人对话，驱动 OpenClaw 完成相关任务。

接入步骤概览：

1. 在飞书开放平台创建企业自建应用，获取 App ID 和 App Secret
2. 配置应用权限（批量导入 JSON 权限配置）
3. 启用机器人能力，配置事件订阅（长连接模式，添加 im.message.receive_v1 事件）
4. 发布应用
5. 在飞书中找到机器人，发送消息获取配对码，运行 openclaw pairing approve feishu <配对码> 完成授权

📖 详细接入文档：飞书接入指南
官方文档：OpenClaw 飞书通道

QQ 接入

通过 QQ 机器人实现用户通过 QQ 与机器人对话，驱动 OpenClaw 完成相关任务。

接入步骤概览：

1. 登录 QQ 开放平台，注册账号并绑定 QQ（不能直接用 QQ 账号登录）
2. 创建机器人，获取 AppID 和 AppSecret
3. 将 AppID 和 AppSecret 填入 OpenClaw 配置
4. 将 VPS 公网 IP 加入白名单（curl ifconfig.me 获取）
5. 配置沙箱环境，添加测试成员，扫码绑定手机 QQ

📖 详细接入文档：QQ 接入指南

通用配置说明

所有渠道接入后，在 openclaw.json 中配置 binding 将渠道路由到对应 Agent：

{
  bindings: [
    { agentId: "main", match: { channel: "dingtalk", accountId: "default" } },
    { agentId: "main", match: { channel: "feishu", accountId: "default" } }
  ]
}

多渠道、多账号的路由规则详见第六章：多 Agent 模式。

五、分层记忆系统

OpenClaw 的记忆系统基于文件系统实现，让 AI 助理拥有跨会话的长期记忆。

记忆金字塔

         核心记忆 MEMORY.md          ← 关键人物、偏好、重要决策（主会话专用）
              ↑
         年度记忆 YYYY.md            ← 年度里程碑、高度提炼
              ↑
         月度记忆 YYYY-MM.md         ← 月度重要事件、决策汇总
              ↑
         每日记忆 YYYY-MM-DD.md      ← 当日事件摘要（原始记录，不修改）
              ↑
    临时记忆 YYYY-MM-DD-HHMM.md     ← 完整会话记录（30天后自动删除）

文件结构

workspace/
├── MEMORY.md                        # 核心记忆（永久，主会话专用）
└── memory/
    ├── 2026.md                      # 年度记忆
    ├── 2026-03.md                   # 月度记忆
    ├── 2026-03-11.md                # 每日记忆
    └── 2026-03-11-1041.md           # 临时会话记录（30天后删除）

各层说明

自动维护 Cron 任务

每日凌晨 2:00        → 汇总临时记忆到每日记忆，清理 30 天前的临时文件
每周一凌晨 3:00      → 提取上周每日记忆重要内容到月度记忆
每月 1 号凌晨 4:00   → 提取上月月度记忆重要内容到年度记忆
每年 1 月 1 日凌晨 5:00 → 优化年度记忆，高度提炼

# 查看当前 cron 任务
openclaw cron list

# 添加每日记忆维护任务（示例）
openclaw cron add \
  --name "每日记忆维护" \
  --schedule "cron 0 2 * * * @ Asia/Shanghai" \
  --task "汇总昨天的临时记忆到每日记忆文件，清理30天前的临时记忆，更新QMD索引" \
  --target isolated

手动触发记忆维护

如果 cron 任务从未运行过（状态为 idle），或者需要立即整理记忆，可以直接告诉 Agent：

"帮我维护一次记忆，把最近的临时记忆汇总到每日记忆，并更新月度记忆"

Agent 会读取所有临时记忆文件，提炼重要内容写入对应的每日/月度记忆文件，并更新 MEMORY.md。

MEMORY.md 安全策略

MEMORY.md 包含个人敏感信息，仅在主会话（私聊/DM）中加载，群聊和共享会话不会加载此文件，防止隐私泄露。

六、QMD 语义记忆搜索

QMD（Quantum Memory Database）是 OpenClaw 内置的 Markdown 语义搜索引擎。

安装

npm install -g @tobilu/qmd

初始化索引

cd ~/.openclaw/workspace
qmd collection add . --name memory-files --mask "{MEMORY.md,memory/**/*.md}"
qmd status

三种搜索模式

1. qmd search — BM25 全文检索（推荐，无 GPU 环境）

速度快，无需 GPU，适合大多数 VPS 环境。

qmd search "老板 钉钉" -c memory-files
qmd search "数据库决策" -c memory-files --full
qmd search "待办事项" -c memory-files --files -n 5

原理：BM25 算法对关键词进行词频统计和逆文档频率加权，中文建议用关键词组合而非长句。

2. qmd query — 混合语义搜索（需 GPU 或高性能 CPU）

向量搜索 + 关键词搜索 + 重排序，理解自然语言语义，搜索质量最高。

qmd query "上次讨论的技术选型结论是什么" -c memory-files
qmd query "最近的重要决策" -c memory-files --min-score 0.7

工作原理：Query Expansion → Vector Search → BM25 → Reranking（Qwen3-Reranker-0.6B）

⚠️ 无 GPU 的低配 VPS 建议只用 qmd search

3. qmd vsearch — 纯向量相似度搜索

qmd vsearch "项目里程碑" -c memory-files -n 5

精确读取

qmd get memory/2026-02.md
qmd get MEMORY.md:5 -l 10
qmd multi-get "memory/2026-*.md" -l 50

典型流程

用户问："老板的钉钉 ID 是多少？"
  ↓ qmd search "老板 钉钉 ID" -c memory-files -n 3
  ↓ 找到 MEMORY.md 第 5-8 行
  ↓ qmd get MEMORY.md:5 -l 4
  ↓ 返回答案

索引维护

qmd update      # 新增文件后更新索引
qmd embed -f    # 重新生成向量嵌入
qmd cleanup     # 清理缓存
qmd status      # 查看状态

七、多 Agent 模式

一个 Gateway 进程里运行多个完全隔离的 Agent，每个 Agent 有独立的 Workspace、Session Store、Skills 和 Auth。

核心概念

路由优先级（从高到低）

1. peer 精确匹配（指定 DM/群组 ID）
2. parentPeer 匹配（线程继承）
3. guildId + roles（Discord 角色路由）
4. accountId 匹配（指定渠道账号）
5. 渠道级匹配（accountId: "*"）
6. 默认 Agent（default: true 或第一个）

配置示例

{
  agents: {
    list: [
      { id: "main", default: true, workspace: "~/.openclaw/workspace" },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        agentDir: "~/.openclaw/agents/work/agent"
      }
    ]
  },
  bindings: [
    { agentId: "main", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } }
  ]
}

我这边的实际配置（3 个 Agent）

通过钉钉不同机器人账号路由到不同 Agent：

{
  bindings: [
    { agentId: "main",        match: { channel: "dingtalk", accountId: "xiaohaishi" } },
    { agentId: "xiaopangxie", match: { channel: "dingtalk", accountId: "xiaopangxie" } },
    { agentId: "xiaolongxia", match: { channel: "dingtalk", accountId: "xiaolongxia" } }
  ]
}

每个 Agent 完全独立：独立人格文件（SOUL.md/IDENTITY.md）、独立记忆、独立技能、独立 cron 任务。

添加新 Agent

openclaw agents add <agentId>
openclaw agents list --bindings

per-Agent 工具限制（适合多人共用）

{
  agents: {
    list: [{
      id: "family",
      sandbox: { mode: "all", scope: "agent" },
      tools: {
        allow: ["read", "exec", "sessions_list"],
        deny: ["write", "edit", "browser"]
      }
    }]
  }
}

Agent 间通信（默认关闭）

{
  tools: {
    agentToAgent: {
      enabled: true,
      allow: ["main", "xiaolongxia", "xiaopangxie"]
    }
  }
}

开启后 Agent 可通过 sessions_send 工具互相协作。

八、完整工作流示意

用户发消息（钉钉/WhatsApp/Telegram）
    ↓
Gateway 根据 binding 路由到对应 Agent
    ↓
Agent 启动，读取 SOUL.md / USER.md / 今日记忆 / MEMORY.md
    ↓
处理请求，必要时调用 qmd search 检索历史记忆
    ↓
完成任务，将重要信息写入 memory/YYYY-MM-DD.md
    ↓
凌晨 2:00 cron 自动汇总 → 每日记忆
    ↓
每周一 3:00 cron 自动汇总 → 月度记忆
    ↓
每月 1 号 4:00 cron 自动汇总 → 年度记忆

九、推荐技能

OpenClaw 的技能（Skills）是模块化的能力扩展包，放在 workspace/skills/ 或 ~/.openclaw/skills/ 下，Agent 启动时自动加载。这里重点介绍两个让 Agent 持续进化的核心技能。

self-improvement — 持续自我改进

技能名： self-improvement

作用： 让 Agent 记录错误、纠正和学习，实现跨会话的持续改进。

触发场景

文件结构

workspace/
└── .learnings/
    ├── LEARNINGS.md       # 纠正、知识盲区、最佳实践
    ├── ERRORS.md          # 命令失败、异常
    └── FEATURE_REQUESTS.md # 用户请求的新功能

记录格式示例

## [LRN-20260311-001] correction

**Logged**: 2026-03-11T10:00:00Z
**Priority**: medium
**Status**: pending
**Area**: config

### Summary
交付物应放在 agent_temp 目录下，不是 docs/

### Details
用户纠正：任务产物必须放在 agent_temp/<任务名-日期>/ 下

### Suggested Action
在 AGENTS.md 中强化此规则，每次任务前检查

晋升机制

当某条学习记录具有普遍意义时，可以"晋升"到长期记忆：

晋升后将条目状态改为 promoted，注明目标文件。

快速查看待处理记录

grep -h "Status**: pending" .learnings/*.md | wc -l
grep -B5 "Priority**: high" .learnings/*.md | grep "^## \["

skill-creator — 技能创建向导

技能名： skill-creator

作用： 引导 Agent 创建新技能，将重复性工作封装成可复用的技能包。

什么是技能？

技能是"领域专家的入职指南"——把特定领域的工作流、工具集成、领域知识打包，让 Agent 从通用助理变成专业助理。

技能结构

skill-name/
├── SKILL.md          # 必须，包含 frontmatter + 使用说明
├── scripts/          # 可执行脚本（Python/Bash）
├── references/       # 参考文档（按需加载）
└── assets/           # 输出资源（模板、图片等）

SKILL.md frontmatter 示例：

---
name: my-skill
description: "做什么、什么时候用。Use when: (1) 场景一, (2) 场景二"
---

⚠️ description 是技能触发的核心，必须清晰描述"什么时候用"。

创建流程

1. 明确需求 → 收集具体使用场景
2. 规划内容 → 确定需要哪些 scripts/references/assets
3. 初始化   → python3 scripts/init_skill.py <skill-name> --path ./skills/
4. 编写内容 → 实现脚本、写 SKILL.md
5. 打包     → python3 scripts/package_skill.py ./skills/<skill-name>
6. 迭代     → 实际使用后持续优化

设计原则

• 简洁优先：上下文窗口是公共资源，只写 Agent 不知道的内容
• 渐进式披露：SKILL.md 控制在 500 行内，详细内容放 references/
• 代码优于描述：能用脚本解决的，不要让 Agent 反复推理

安装技能

# 从 ClawHub 安装
clawhub install <skill-name>

# 本地打包安装
python3 scripts/package_skill.py ./skills/my-skill
cp my-skill.skill ~/.openclaw/skills/

其他实用技能推荐

📖 更多技能：ClawHub 技能市场

相关资源