OpenClaw完全安装指南

目录

入门篇

• 01-认识OpenClaw
• 02-出发前准备
• 03-安装环境
• 04-安装OpenClaw

进阶篇

• 05-接入飞书
• 06-更多渠道
• 07-Skills深度指南
• 08-模型配置完全指南

实战篇

• 09-第二大脑
• 10-实战场景
• 11-高阶配置

安全篇

• 12-安全加固
• 13-进阶安全部署

架构篇

• 14-技术架构
• 15-部署方案
• 16-常见问题

生态篇

• 17-命令速查
• 18-生态全景

第一章：认识 OpenClaw

OpenClaw 是什么？

OpenClaw 是一个开源、自托管的 AI Agent 系统，它让 AI 从被动的聊天工具进化为主动执行任务的数字员工。

官方定义： 开源、自托管的 AI Agent 系统
- 开源：代码全部公开，不存在偷偷收集数据
- 自托管：跑在你自己的机器上，数据不经过第三方
- AI Agent：不只是聊天，而是能主动执行任务

一句话总结： OpenClaw 就是住在你电脑里的 AI 员工，7×24 小时待命，你不在时它也在干活。

发展简史

2025年11月 - 项目诞生

奥地利开发者 Peter Steinberger 在一个周末完成了小项目，最初叫 ClawdBot。

2026年1月中旬 - 爆发式增长

短短72小时，获得 6万颗 Stars——GitHub 历史上极其罕见的爆炸速度。

2026年1月 - 商标问题

Anthropic（Claude 母公司）发出商标警告 → 改名为 Moltbot → 几天后改为 OpenClaw。

2026年2月 - 安全事件

项目经历严重安全漏洞 CVE-2026-25253（WebSocket 远程代码执行漏洞）。

2026年2月14日 - 里程碑

Peter 本人宣布加入 OpenAI，项目移交独立开源基金会运营。

2026年3月3日 - 历史性时刻

Stars 超过 25万，超越 React，成为 GitHub 全球第一的开源项目。

为什么这么火？

• 大模型能力已经足够强
• 第一次让普通人能把 AI 变成真正能自主干活的助手
• 踩中了"AI从工具变成员工"这个时代节点

装完之后能干什么？

场景一：每日资讯助手

每天早上8点，AI 自动整理行业早报，推送到飞书。

场景二：日程管理

你说"下周三下午3点我要开复盘会"，它帮你在飞书日历建好日程、加提醒。

场景三：团队助手

给团队群里加个 AI 助手，有人 @ 它翻译，有人让它查数据。

场景四：邮件整理

帮你整理邮件，把重要的单独拎出来，有需要回复的打标记。

本章完

第二章：出发前的准备

设备选择

选项一：用旧电脑（推荐新手）

要求很低：能开机、能联网、macOS 12 以上或 Ubuntu 20.04 以上

选项二：Mac mini（进阶推荐）

功耗低（6-20W）、静音、体积小、不容易自动睡眠

选项三：云服务器

阿里云、腾讯云、火山引擎有一键部署镜像

⚠️ 最重要的原则：不要用主力电脑

三条红线：
1. 找一台专用设备给 OpenClaw 用
2. 不要让它碰你最重要的资料
3. 先备份重要文件再操作

申请 API Key

推荐平台

MiniMax 申请步骤

1. 打开 MiniMax API 开放平台
2. 选择 Coding Plan 套餐
3. 创建 API Key

🔐 API Key 是你的银行账号，绝对不要发到公开地方

备一个 AI 老师

下载豆包桌面版（doubao.com/download/desktop），免费。

开启"共享屏幕"功能，豆包会实时看着你的屏幕，帮你解决安装中的问题。

本章完

第三章：安装基础环境

认识终端：不用怕的黑窗口

终端就是你跟电脑"打字对话"的地方。你打什么命令，电脑就执行什么。

怎么打开终端（macOS）：

按住 Command（⌘ 符号的键），再按空格，在搜索框里打"终端"，回车。

💡 接下来所有的命令，你都不需要手动敲——复制 → 粘贴 → 回车。

第一步：检查 Node.js 是否已安装

node --version

• 如果显示 v22.x.x 或更高版本：恭喜，直接跳到安装 OpenClaw
• 如果显示 command not found，或版本低于 22：继续往下读

第二步：安装 Homebrew（Mac 的命令行应用商店）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

这里有个坑： 它会让你输入电脑的开机密码。输的时候屏幕上什么都不显示——没有星号，这是正常的。

安装过程会比较慢，5到15分钟。如果超过15分钟还没动静，把网络切到手机热点再试一次。

国内网络加速

如果上面那条命令卡在下载，可以试试这个国内镜像脚本：

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
/bin/bash -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

第三步：安装 Node.js

brew install node@22

⚠️ 指定 @22 是因为 OpenClaw 需要 Node.js 22 或更高版本

然后让系统认识新装的 Node：

echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

验证：

node --version

看到 v22.x.x 这样的版本号，说明装好了。

本章完

第四章：安装 OpenClaw

安装命令

npm install -g openclaw@latest

国内镜像：

npm install -g openclaw@latest --registry=https://registry.npmmirror.com

验证：

openclaw --version

初始化向导

openclaw onboard --install-daemon

向导步骤

1. 确认风险提示 - 读一下继续
2. 选择模型供应商 - 选 MiniMax
3. 输入 API Key - 粘贴即可
4. 选择默认模型 - 选 M2.5
5. 选择聊天渠道 - 先 Skip
6. 选择初始聊天方式 - 选"打开网页浏览器"

验证安装

打开浏览器访问 http://127.0.0.1:18789

发一句"你好"，如果它回复了——恭喜，你的 OpenClaw 正式活了！

防止电脑睡觉

macOS：系统设置 → 电池 → 防止自动进入睡眠 → 打开

本章完

第五章：接入飞书

为什么选飞书？

1. 原生内置支持：从 v2026.2 版本起，飞书插件已经内置
2. 长连接模式：不需要公网 IP
3. 功能最完整：支持发图、收文件、审批交互
4. 企业协作场景：可以直接拉进工作群

第一步：启用飞书插件

openclaw plugins enable feishu
openclaw plugins list

第二步：在飞书开放平台创建机器人

1. 打开 飞书开放平台
2. 登录你的飞书账号
3. 点击 "创建企业自建应用"

第三步：记下 App ID 和 App Secret

• App ID：以 cli_ 开头
• App Secret：一串乱码

第四步：开启机器人能力

添加应用能力 → 机器人 → 添加

第五步：配置权限

{
  "scopes": {
    "tenant": ["im:message", "im:message:send_as_bot", "aily:file:read"],
    "user": ["aily:file:read"]
  }
}

第六步：配置事件订阅

添加事件：
- im.message.receive_v1
- im.chat.member.bot.added_v1
- 等等

第七步：发布应用

每次修改完配置，都必须重新发布一次应用才能生效！

第八步：在 OpenClaw 里配置

openclaw channels add
# 选择 Feishu

openclaw gateway restart

第九步：配对验证

在飞书里向机器人发"你好"，会收到配对码。

在终端执行：

openclaw pairing approve feishu 123456

然后再回飞书发消息测试。

本章完

第六章：接入更多渠道

渠道选择建议

Telegram 接入（5分钟搞定）

1. 创建 Bot

在 Telegram 里搜索 @BotFather，发送 /newbot

按提示输入 Bot 的名字和用户名（必须以 bot 结尾）

获取 Bot Token（格式类似 110201543:AAHdqTcv...）

2. 配置到 OpenClaw

openclaw channels add

选择 Telegram，粘贴 Bot Token

openclaw gateway restart

3. 配对

在 Telegram 里搜索你的 Bot，发一条消息

Bot 会回复一串配对码，在终端执行：

openclaw pairing approve telegram 123456

⚠️ 国内使用需要代理

QQ 接入

1. 打开 QQ开放平台 注册开发者
2. 创建 Bot，获取 App ID 和 App Token
3. 配置：

openclaw channels add
# 选择 QQ

钉钉接入

openclaw plugins install @soimy/dingtalk
openclaw channels add
# 选择钉钉

企业微信接入

openclaw plugins install openclaw-wecom
openclaw channels add
# 选择 WeCom

Discord 接入

1. 打开 Discord Developer Portal
2. 创建 Application，添加 Bot
3. 开启 Message Content Intent
4. 获取 Token 和 Server ID

openclaw channels add
# 选择 Discord

微信个人号（不推荐）

微信个人号没有官方 API，所有方案都有封号风险。新手不要碰。

如果一定要用，用企业微信中转是最平衡的选择。

本章完

第七章：Skills 深度指南

Skills 是什么？

Skills（技能）就是给 AI 装的"专业证书"。装了天气技能，它就能查天气；装了 GitHub 技能，它就能帮你管代码。

安装技能的三种方式

方式一：命令行安装

openclaw skills install web-search
openclaw skills install file-manager calendar translator

方式二：自然语言安装

直接跟 OpenClaw 说："帮我安装一个能搜索网页的技能"

方式三：手动放置

cp -r my-skill/ ~/.openclaw/skills/
openclaw gateway restart

推荐技能清单

自建 Skill

最小的技能只需要一个文件夹里的一个 SKILL.md：

# 每日工作汇报助手

/# Description
帮助用户整理和生成每日工作汇报

/# Trigger
当用户提到「日报」「工作汇报」时激活

/# Instructions
1. 询问用户今天完成了哪些工作
2. 询问明天计划做什么
3. 按格式整理日报

/# Tools Required
file_read
memory_search

ClawHavoc 事件：一场真实的供应链攻击

2026年1月底到2月初，ClawHub 上发生了一次大规模恶意技能攻击。

攻击手法：
攻击者上传大量看似专业的技能（如"PDF转换工具"），用户安装后，技能会建议安装"helper agent"，实际上安装的是 Atomic macOS Stealer (AMOS)——盗取密码、API Key 的木马。

更可怕的是： 这些恶意技能会篡改 SOUL.md 和 MEMORY.md，给 AI "洗脑"，让它主动泄露信息。

最终影响：
- 超过 13.5 万台设备受影响
- 约 20% 的 Skills 被确认为恶意

防范措施

本章完

第八章：模型配置完全指南

全球模型一览

不同预算推荐

月预算 < 30元：
- 主力：GLM-4.5-Flash（免费）+ Qwen 3.5（按量）

月预算 30-100元：
- 主力：MiniMax M2.5（29元/月）
- 心跳任务：GLM-4.5-Flash（免费）

月预算不设限：
- 主力：Claude Sonnet 4.6
- 降级：DeepSeek-V3

完整的多模型配置

{
  "models": {
    "mode": "merge",
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}",
        "models": [{ "id": "claude-sonnet-4-6", "contextWindow": 200000 }]
      },
      "deepseek": {
        "apiKey": "${DEEPSEEK_API_KEY}",
        "models": [{ "id": "deepseek-v3", "contextWindow": 128000 }]
      },
      "zhipu": {
        "apiKey": "${ZHIPU_API_KEY}",
        "models": [{ "id": "glm-4.5-flash", "contextWindow": 128000 }]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallbacks": ["deepseek/deepseek-v3", "zhipu/glm-4.5-flash"]
      }
    }
  }
}

成本控制四个关键手段

① 设置硬限额

{ "budget": { "maxCostPerDay": 5.00 } }

② Fallback 降级

主力模型挂了自动切到便宜模型

③ 买 Coding Plan 套餐

④ 用 /status 盯着用量

为什么 OpenClaw 比普通聊天贵？

普通聊天： 你说一句话 → 1次 API 调用

OpenClaw Agent 任务：
1. 接收消息（1次）
2. 理解意图（1次）
3. 调用工具（1次）
4. 读取结果（1次）
5. 生成回复（1次）

一个简单的"帮我查新闻"，可能触发 5-10 次 API 调用。

本章完

第九章：打造你的第二大脑

截图 TODO: 记忆系统配置页面

从"用它干活"到"它真的了解你"

OpenClaw 真正的价值，不在于"你问它答"，而在于让它主动干活——定时执行、自动推送、在你没开飞书的时候帮你盯着事情。

但有一个问题：你可能已经发现了——每次开启新对话，它都好像把之前的事情忘了。

OpenClaw 的解决方案是一套文件系统记忆机制——用几个特定的 Markdown 文件，存储 AI 的"长期记忆"。

工作区的核心文件

截图 TODO: 工作区文件结构

快速初始化第二大脑

mkdir -p ~/.openclaw/workspace/memory
mkdir -p ~/.openclaw/workspace/blog

SOUL.md（AI的灵魂文件）

这是最重要的文件，决定了 AI 的"人格"。

cat > ~/.openclaw/workspace/SOUL.md << 'EOFMARKER'
# SOUL.md — AI助手的核心人格

## 角色定位
你不是聊天机器人。你是我的第二大脑、工作伙伴和思维催化剂。

## 核心原则
**直接有用，不要表演式的有用。**
不要说"好问题！"、"我很乐意帮助！"——直接给答案、给方案、给行动。

**有自己的判断。**
你可以反对我，可以说"这个方向有问题"，可以有偏好。

**先尝试解决，再来问我。**
读文件、查上下文、搜索信息——把能做的都做了。

**对外行动谨慎，对内行动大胆。**
外部操作（发邮件、发消息、公开发布）必须确认后再执行。

## 沟通风格
- 中文为主，技术术语保留英文原文
- 简洁优先
- 不确定的事情明确标注"我不确定"

## 边界
- 私密信息绝不外泄
- 任何不可逆操作必须先确认
EOFMARKER

截图 TODO: SOUL.md 文件示例

USER.md（关于你的信息）

cat > ~/.openclaw/workspace/USER.md << 'EOFMARKER'
# USER.md — 关于我

## 基本信息
- 姓名：[你的名字]
- 职业：[你的职业]
- 主要设备：MacBook / Mac mini

## 技术栈
[列出你常用的编程语言、工具、平台]

## 工作方式
- 喜欢高效直接的沟通
- 重视实操性，方案要能直接落地

## 沟通偏好
- 语言：中文为主，技术名词保留英文
EOFMARKER

AGENTS.md（任务执行规范）

cat > ~/.openclaw/workspace/AGENTS.md << 'EOFMARKER'
# AGENTS.md — 行为规范

## 任务执行原则
### 分级响应
- **简单问答**：直接回答，1-3句话
- **技术问题**：给方案 + 可执行命令/代码
- **复杂决策**：结论先行 → 分析推理 → 备选方案 → 行动建议
- **探索任务**：先给框架和假设，确认方向后深入

### 记忆管理
- 每次会话开始：读取 MEMORY.md 和最近3天的 daily notes
- 对话中出现重要信息：实时写入 memory/YYYY-MM-DD.md
- 每周：将本周 daily notes 中有价值的内容整理晋升到 MEMORY.md

### 安全规则
- 绝不自动执行发送消息、邮件的操作，必须先确认
- 执行 rm、删除、覆盖等破坏性命令前必须确认
EOFMARKER

MEMORY.md（长期记忆）

cat > ~/.openclaw/workspace/MEMORY.md << 'EOFMARKER'
# MEMORY.md — 长期记忆

> 此文件由 AI 维护，记录跨会话的持久知识。

## 进行中的项目
| 项目 | 状态 | 下一步 | 截止 |
|------|------|--------|------|
| OpenClaw 部署 | 已完成基础配置 | 配置 Skills | — |

## 重要决策记录
| 日期 | 决策 | 原因 | 结果 |
|------|------|------|------|

## 技术环境备忘
- OpenClance 版本：v2026.3.x
- 运行设备：Mac mini M4
- 主力模型：MiniMax-M2.5
- Gateway 端口：18789
EOFMARKER

使用习惯

习惯一：重要事情说"请记住"

在对话里，遇到你希望 AI 长期记住的信息，加"请记住这个"。

习惯二：定期让 AI 整理记忆

每周跟它说："把这周 daily notes 里的重要信息整理晋升到 MEMORY.md。"

习惯三：在 SOUL.md 里打补丁

每当你发现 AI 有什么做法让你觉得不对劲，立刻在 SOUL.md 里加一条规则。

本章完

第十章：实战场景配置

场景一：每日资讯助手

想做什么

每天早上8点，AI 自动整理一份行业早报，推送到飞书。

配置步骤

第一步：创建心跳配置文件

nano ~/.openclaw/workspace/HEARTBEAT.md

写入内容：

# HEARTBEAT.md — 定时任务

## 每日早晨 8:00（首次心跳）
- 搜索过去24小时内，以下领域的重要动态：
  - AI 大模型与 Agent 技术
  - 创业融资（A轮及以上）
- 整理成早报，格式如下：
  - 每条新闻：标题 + 2-3句摘要 + 来源链接
  - 总共5-8条，按重要性排序
- 最后加一句今日天气
- 通过飞书发给我

## 每周五下午 5:30
- 整理本周日报中出现频率最高的关键词
- 生成一份本周信息摘要（200字以内）

第二步：开启 web-search 技能

openclaw skills install web-search
openclaw gateway restart

第三步：告诉 OpenClaw 开始执行

在飞书里说："请开始执行 HEARTBEAT.md 里定义的每日任务，从今天起，每天早上8点给我发早报。"

截图 TODO: 心跳任务配置

场景二：英语私教助手

想做什么

一个能出题、能批改、能追踪错题的 AI 英语外教。

配置方法

在飞书里发送：

我希望你扮演我的英语私教。以后我发给你"英语练习"这四个字，你就出5道题给我。我答完，你逐题批改，告诉我对错和原因。做错的题，帮我记在 MEMORY.md 里。

更进一步： 在 HEARTBEAT.md 里加一条：

## 每周三晚 8:00
- 读取 MEMORY.md 里的英语错题记录
- 从最近的错题里挑3道，重新出题给我练习
- 通过飞书发给我

截图 TODO: 英语私教配置

场景三：团队群助手

想做什么

把 AI 加到工作群里，全组共用。

配置方法

第一步：在飞书群里添加机器人

第二步：设置群聊响应模式

/activation mention

第三步：定义群助手职责

你现在在一个工作群里，你是这个群的 AI 助手。你的主要职责是：
1. 有人 @ 你让你翻译，你就翻译
2. 有人发来文档链接让你摘要，你读完给一个300字以内的摘要
3. 有人问你技术问题，你就认真回答
4. 如果有人只是在群里聊天没有 @ 你，你不需要插话

截图 TODO: 团队群助手配置

本章完

第十一章：高阶配置

多模型配置：不同任务用不同的"大脑"

OpenClaw 一个很强的特性是可以给不同任务配置不同的模型：

• 日常聊天 → 用便宜的 DeepSeek
• 深度推理 → 切换到 Claude Sonnet
• 心跳任务 → 用免费的 GLM-4.5-Flash

打开 ~/.openclaw/openclaw.json：

{
  "models": {
    "mode": "merge",
    "providers": {
      "minimax": {
        "apiKey": "${MINIMAX_API_KEY}",
        "models": ["MiniMax-M2.5"]
      },
      "deepseek": {
        "apiKey": "${DEEPSEEK_API_KEY}",
        "models": ["deepseek-v3", "deepseek-r1"]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax/MiniMax-M2.5",
        "fallback": ["deepseek/deepseek-v3", "zhipu/glm-4.5-flash"]
      }
    }
  }
}

💡 "mode": "merge" 非常重要，保留内置配置再叠加自定义配置

Fallback 机制

主力模型挂了、达到速率限制、余额不足时，OpenClaw 会自动切换到备用模型。

聊天内指令速查

本章完

第十二章：安全加固

为什么这一章很重要？

2026年2月，OpenClaw 发生了严重的安全漏洞（CVE-2026-25253）。另外，API Key 被盗导致账单刷爆的事件也频繁发生。

1. 确保在最新版本

openclaw --version

如果低于 v2026.3.2，立刻更新：

npm install -g openclaw@latest
openclaw gateway restart

2. 配置 Gateway 认证

nano ~/.openclaw/openclaw.json

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "填入一串你自己设定的随机字符串"
    }
  }
}

💡 bind: "loopback" 让 Gateway 只在本机监听

openclaw gateway restart

3. 设置每日费用上限

{
  "budget": {
    "maxCostPerDay": 5.00,
    "maxTokensPerDay": 500000
  }
}

4. 运行安全审计

openclaw security audit

把 CRITICAL 和 WARNING 级别的问题全部修复。

5. API Key 的存储安全

不要把 API Key 直接明文写在配置文件里。

用环境变量：

echo "MINIMAX_API_KEY=你的Key" >> ~/.openclaw/.env
chmod 600 ~/.openclaw/.env

然后在 openclaw.json 里引用：

{
  "models": {
    "providers": {
      "minimax": {
        "apiKey": "${MINIMAX_API_KEY}"
      }
    }
  }
}

本章完

第十三章：进阶安全部署

Mac mini + Tailscale 终极方案

参考架构

主力 MacBook（主机）
 └── Tailscale 加密隧道（唯一授权通道）
      Mac mini（AI 节点）
           ├── OpenClaw Gateway
           └── Docker Sandbox
路由器
 ├── 主网络（MacBook、NAS、手机）
 └── Guest WiFi ← Mac mini（无法访问主网络）

三层防护同心圆：

第一阶段：Mac mini 系统配置

1. 创建专用用户

系统设置 → 用户与群组 → 添加用户

2. 设置自动登录

系统设置 → 用户与群组 → 登录选项 → 自动登录

3. 连接 Guest WiFi

系统设置 → Wi-Fi → 连接路由器的 Guest 网络

4. 开启远程访问

系统设置 → 通用 → 共享，勾选远程登录（SSH）

5. 禁止睡眠

sudo pmset -a sleep 0 disksleep 10 autopoweroff 0

第二阶段：软件安装

brew install node@22 docker tailscale
npm install -g openclaw@latest

第三阶段：安全配置

1. 生成 Gateway Token

echo "OPENCLAW_GATEWAY_TOKEN=$(openssl rand -base64 32)" > ~/.openclaw/.env
chmod 600 ~/.openclaw/.env

2. 核心配置

{
  "gateway": { "bind": "loopback", "auth": { "mode": "token" } },
  "budget": { "maxCostPerDay": 5.00 },
  "tools": { "fs": { "workspaceOnly": true } },
  "agents": { "defaults": { "sandbox": { "mode": "all", "docker": { "network": "none" } } } }
}

第四阶段：验证

openclaw health
lsof -i :18789  # 期望 127.0.0.1:18789
openclaw security audit --deep

本章完

第二部分：技术架构

第五章：整体架构

OpenClaw 采用分层解耦设计，核心层次如下：

分层结构

┌─────────────────────────────────────┐
│         渠道层 (Channels)           │  ← Telegram、飞书、Discord...
├─────────────────────────────────────┤
│         会话层 (Sessions)           │  ← 用户识别、上下文管理
├─────────────────────────────────────┤
│           Agent 层                   │  ← 推理、规划、工具调用
├─────────────────────────────────────┤
│          工具层 (Tools)              │  ← 文件、网络、浏览器...
├─────────────────────────────────────┤
│          存储层 (Storage)            │  ← SQLite、PostgreSQL...
└─────────────────────────────────────┘

核心组件

第六章：记忆系统

OpenClaw 拥有持久化、多层次、可检索的记忆系统。

记忆层次

┌─────────────────────────────────────┐
│         外部知识库                   │  ← 用户导入的文档
├─────────────────────────────────────┤
│         长期记忆                    │  ← 偏好、摘要、向量存储
├─────────────────────────────────────┤
│         短期记忆                    │  ← 当前会话上下文
└─────────────────────────────────────┘

配置示例

{
  "memory": {
    "enabled": true,
    "provider": "supabase",  // supabase | qdrant | chroma
    "vectorDimension": 1536
  }
}

功能特性

• 语义检索: 向量相似度搜索
• 选择性遗忘: 可删除特定记忆
• 隐私控制: 用户掌控
• 多存储后端: Supabase PGVector、Qdrant、Chroma

第七章：Agent 工作区

Agent 工作区是任务执行的隔离环境。

核心组件

┌─────────────────────────────────────┐
│           沙箱环境                   │  ← 任务隔离
├─────────────────────────────────────┤
│           工具箱                     │  ← 可用工具
├─────────────────────────────────────┤
│           状态管理                   │  ← 会话状态
└─────────────────────────────────────┘

多工作区支持

{
  "agents": {
    "main": {
      "model": "gpt-4o",
      "tools": ["exec", "browser", "files"],
      "channels": ["telegram"]
    },
    "coder": {
      "model": "gpt-5.4",
      "tools": ["exec", "github", "browser"],
      "channels": ["discord"]
    }
  }
}

工具分类

第八章：Session 与用户识别

Session 管理支持多用户场景。

Session 模式

认证方式

{
  "auth": {
    "telegram": {
      "mode": "pairing",
      "allowedUsers": ["xxx"]
    },
    "password": {
      "enabled": true,
      "hash": "bcrypt..."
    }
  }
}

支持的认证：
- 密码
- OAuth (Google、GitHub)
- Telegram 配对码
- API Key

第九章：设计哲学

核心原则

1. 本地优先 (Local First)
   - 数据存储在用户服务器
   - 不依赖第三方服务
   - 隐私自己掌控

2. 工具优先 (Tools First)
   - AI 不仅回答问题
   - 还能执行操作

3. 可组合 (Composable)
   - 模块化设计
   - 灵活组合

4. 渐进增强 (Progressive)
   - 入门简单
   - 高级定制空间大

本章最后更新：2026-03-10

第十五章：部署方案全景

选哪种部署方式？

零门槛试用

→ 扣子编程 (code.coze.cn)

花钱少，不想管服务器

• 国内：阿里云 / 腾讯云 / 火山引擎
• 海外：Railway / Zeabur

有技术基础，想本地跑

• Mac/Linux：npm 本地安装
• Windows：WSL2 + npm

追求极致安全

→ Mac mini + Tailscale 方案

方案一：扣子编程（最零门槛）

1. 打开 code.coze.cn
2. 点击"一键部署 OpenClaw"
3. 点确认，系统自动配置好

✅ 真正零门槛，2步完成
❌ 定制空间有限，数据在平台上

方案二：阿里云一键部署

1. 购买阿里云轻量应用服务器
2. 选择预装 OpenClaw 镜像（新用户约 9.9 元/月起）
3. 放通端口 18789 和 3000
4. 配置 API Key

方案三：Docker 部署

services:
  openclaw:
    image: openclaw/openclaw:latest
    ports:
      - "18789:18789"
      - "3000:3000"
    volumes:
      - ~/.openclaw:/root/.openclaw
      - ~/openclaw/workspace:/workspace
    restart: always

docker-compose up -d

方案四：Railway（海外首选）

1. 访问 railway.app
2. 搜索 OpenClaw 模板
3. 一键部署

每月 5 美元免费额度。

Windows 用户：WSL2

不要在 Windows 原生环境里装 OpenClaw，官方强烈推荐用 WSL2。

wsl --install

然后按 Linux 流程安装。

本章完

第十六章：常见问题

安装问题

Q：终端显示 command not found: openclaw

A：OpenClaw 没有正确加入系统路径。

echo 'export PATH="$(npm root -g)/.bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

Q：npm install 安装卡住不动

A：国内网络访问 npm 官方仓库经常超时。

npm install -g openclaw@latest --registry=https://registry.npmmirror.com

渠道问题

Q：飞书机器人发消息没有反应

按顺序排查：

1. 检查 OpenClaw 是否在运行：openclaw gateway status
2. 如果没在运行，手动启动：openclaw gateway
3. 如果在运行但没反应，重启：openclaw gateway restart
4. 检查电脑是否进入了睡眠
5. 确认飞书应用最新版本已发布

Q：飞书权限审批显示需要管理员审批

A：如果用的是公司企业版飞书，需要公司 IT 管理员审批。

解决方法：
1. 联系公司管理员说明情况
2. 或者申请一个个人版飞书账号

模型问题

Q：初始化向导里 API Key 填错了怎么办

A：

openclaw models configure

费用问题

Q：OpenClaw 使用费用怎么查？

• OpenClaw 内查：发送 /status 指令
• API 平台查：在你注册 API Key 的平台后台

本章完

第十七章：命令速查卡

安装相关

npm install -g openclaw@latest        # 安装/更新 OpenClaw
openclaw onboard --install-daemon     # 初始化向导
openclaw --version                   # 查看当前版本

运行控制

openclaw gateway                     # 启动 Gateway
openclaw gateway restart            # 重启 Gateway
openclaw gateway status             # 查看运行状态
openclaw health                     # 健康检查

渠道管理

openclaw plugins enable feishu      # 启用飞书插件
openclaw plugins list              # 查看插件状态
openclaw channels add              # 添加新渠道
openclaw pairing approve feishu [配对码]  # 完成配对

技能管理

openclaw skills install <技能名>   # 安装技能
openclaw skills list               # 查看已安装技能
openclaw skills update             # 更新技能

安全运维

openclaw security audit --deep     # 深度安全审计
openclaw doctor                   # 环境诊断

飞书内指令

本章完

第十八章：OpenClaw 生态全景

它不只是一个工具

2026年3月，OpenClaw 已经形成了一个完整的生态：

ClawHub（技能市场）

目前拥有 13,729 个技能，涵盖：
- 办公自动化
- 内容创作
- 开发工具
- 生活助手

⚠️ 但有安全风险（见 ClawHavoc 事件）

Moltbook（AI 的社交网络）

专为零丁 Agent 设计的社交平台，已有 32,000+ AI 角色在上面互动、发帖、讨论。

你的 OpenClaw 可以在这里有自己的"账号"，和其他人的 AI 进行自主对话。

openclaw-china（国内专属插件）

针对国内用户定制：

openclaw plugins install openclaw-china

优化了：
- DeepSeek、GLM 等国内模型接入
- 飞书、钉钉、QQ 深度集成

轻量替代品

• nanoclaw：只有 4000 行代码的极简版，适合树莓派
• zeroclaw：Rust 重写版，内存占用极低（开发中）

聚合平台

如果你觉得一个个配置 API Key 太麻烦：

• SiliconFlow
• OpenRouter
• One-API

用一个 Key 调用几十个模型：

{
  "providers": {
    "siliconflow": {
      "baseUrl": "https://api.siliconflow.cn/v1",
      "apiKey": "${SILICONFLOW_API_KEY}",
      "models": ["deepseek-v3", "qwen-max", "glm-4-flash"]
    }
  }
}

本章完