�� OpenClaw搭建教程(本地隔离环境)-夜雨聆风

�� OpenClaw搭建教程(本地隔离环境)

献给 Mac 新手小白，一次通关，告别报错。

本教程将使用 Docker 技术，在你的电脑上搭建一个纯净、安全、可无限扩展的 AI 大脑中控台（OpenClaw），并将它接入飞书，打造一个 24 小时待命、且具备看图能力的超级数字员工。

🗺️ 全局架构与通关路线图（动手前必读）

在正式开始之前，我们先来看看这套系统是怎么运作的，以及每一步到底是为了干什么。

核心运转逻辑图

各步骤的目的是什么？相互之间有什么联系？

步骤	目的	联系
步骤 0：打地基（安装 Docker）	为复杂的 AI 系统准备一个隔离的运行环境。	它是承载一切的底层容器。没有 Docker，后面的系统就无法在 Mac 上安全运行。
步骤 1：组装中枢大脑（部署 OpenClaw + DeepSeek）	安装核心程序，给它注入当前地表最强的逻辑思维（DeepSeek 模型）。	OpenClaw 是”大脑皮层”，负责协调所有数据；DeepSeek 是”逻辑中枢”。完成这一步时，系统已经可以在浏览器网页里陪你聊天了。
步骤 2：打造身体（打通飞书）	让 AI 走出浏览器，拥有一个随时随地可以被呼叫的实体（飞书聊天框）。	通过长连接技术，飞书变成了 OpenClaw 伸出来的一只手。你在飞书里打字，相当于直接把数据传回了步骤 1 的大脑。
步骤 3：装配眼睛（接入阿里视觉模型）	弥补 DeepSeek 不能看图的短板，让数字员工能解析截图和照片。	作为 OpenClaw 的外接插件，进一步扩展能力边界。

🛠️ 准备阶段：安装基石与排雷

在让 AI 跑起来之前，我们需要先在电脑里建一个”防爆房”，并且清空历史的杂物。

步骤 0：安装 Docker Desktop（必须条件）

Docker 就是我们要用的”防爆集装箱”，它能让复杂的 AI 程序在里面完美运行，又绝对不会弄脏或搞坏你的 Mac 系统。

去浏览器访问 Docker 官方网站下载 Docker Desktop for Mac。
注意芯片版本：

如果你的 Mac 是 M1/M2/M3/M4 芯片 → 下载 Apple Silicon 版本
如果是老款 Intel 芯片 → 下载 Intel 版本

下载后像安装普通软件一样，把它拖进”应用程序”文件夹并双击打开。
验证成功： 当你看到 Mac 屏幕右上角的状态栏出现了一个”小鲸鱼”🐳 的图标，并且显示 Engine running 时，说明你的集装箱基地已经搭好了！

步骤 0.5：大扫除（防端口冲突与历史脏数据）

💡 如果你之前从未安装过 OpenClaw，可以跳过这一步。

如果你之前试过安装其他版本的 OpenClaw，电脑的 18789 端口可能被占用，而且会残留旧数据。

✅ 正确操作：

确保退出所有旧版 OpenClaw 桌面端应用。
打开 Mac 终端（Terminal），执行”外科手术式”清理，彻底粉碎旧工作区（放心，这会为你创造一个 100% 纯净的无菌环境）：

rm -rf ~/.openclaw/workspace

🏗️ 第一阶段：部署 OpenClaw 核心系统与初始配置

打开 Mac 终端（Terminal），依次输入并回车：

1. 创建”发动机舱”并启动

# 创建并进入安装目录（程序的肉体）mkdir ~/openclaw && cd ~/openclaw# 下载官方配置文件（施工图纸）curl -O https://raw.githubusercontent.com/openclaw/openclaw/main/docker-compose.yml# 后台拉起并启动系统docker compose up -d

🧠 深度解析：刚刚这三行代码到底干了啥？

对于新手来说，这三步可能像变魔术。简单来说，它完成了两件核心大事：

拉取正确镜像（Pull Image）： 官方的 docker-compose.yml 就像一张施工图纸。当你按下回车执行 up -d 时，Docker 会照着图纸，自动去云端仓库把 OpenClaw 最稳定、正确的系统包（镜像）下载到你的集装箱里。
建立挂载映射（Bind Mount）： 这是最聪明的设计。Docker 会自动在你电脑里建一个带点的隐藏文件夹 ~/.openclaw，并建立一个”双向玻璃抽屉“，把这个文件夹和集装箱内部的系统打通。

这就意味着： 你在 Mac 上的这个文件夹里写配置（比如千问的 API Key），集装箱里的 AI 瞬间就能看见；AI 整理好的文件，也会顺着抽屉直接存到你的 Mac 硬盘上，绝不会因为关机而丢失！

2. 获取你的”大门钥匙”

系统启动后，会自动生成一个安全密钥（Token）。在终端运行以下命令提取它：

cat ~/.openclaw/.env | grep TOKEN

你会看到一串以 sk-gw- 开头的代码。请把它复制下来，这就是你的超级管理员密码。

3. 登录控制台大盘

打开浏览器，访问：http://127.0.0.1:18789
粘贴刚刚复制的 Token，点击登录，进入你的专属 AI 控制台。

4. 首次注入灵魂：配置 DeepSeek 模型

进入控制台后，AI 此时还是个”空壳”，我们需要给它配置大脑（DeepSeek）。

在控制台左侧导航栏找到并点击 Settings（设置）。
找到 Providers（模型供应商） 选项卡。
点击 Add Provider，在列表中选择 DeepSeek。
维护 API Key：

在弹出的输入框中，填入你去 DeepSeek 官网申请的 API Key（形如 sk-xxxxxx）。
确认可用模型包含 deepseek-chat（V3）和 deepseek-reasoner（R1）。
点击 Save（保存）。

✅ 完成这一步，你的 AI 就能真正在网页端和你进行文字对话了。所有的 Key 都会被安全地保存在 ~/.openclaw/openclaw.json 这个保险柜文件里。

📂 新手备忘录：你电脑里的两个 OpenClaw 文件夹

~/openclaw（没有点）：系统的发动机舱 / 施工大队，负责拿着图纸启动和关闭，里面的文件平时不用管，删了也不心疼。

~/.openclaw（带点的隐藏文件夹）：你的私人保险柜 / 灵魂伴侣。由于”挂载映射”技术，这里存放的 API 密钥、聊天记录和飞书配置都是实打实存在你物理硬盘上的。千万不能删！

💬 第二阶段：打通飞书通道

让 AI 走出浏览器，住进你的飞书聊天框。

前置条件：你需要在飞书开发者后台创建好一个应用

如果你还没有飞书应用，请先跟着下面的步骤创建一个（只需要做一次）：

访问飞书开发者后台，登录你的飞书账号。
点击 创建应用 → 企业自建应用。
填写应用名称（比如”我的 AI 助理”）和描述，点击确定。
创建完成后，你会进入应用详情页。记下 App ID 和 App Secret（后面用不到它，但了解在哪就行）。
左侧导航找到 机器人 → 开启机器人功能。
点击 添加事件 → 搜索并添加 接收消息（im.message.receive_v1）。
左侧点击 权限管理 → 搜索并开通权限：获取与发送单聊、群组消息。
⚠️ 极其关键的一步： 左侧点击 版本管理与发布 → 创建一个新版本 → 填写版本号（如 1.0.0）和说明 → 点击保存并发布。新加的权限只有发布了才会真正生效！

以上准备工作只需在飞书后台配置一次。

开启长连接（WebSocket）模式

⛔ 避坑点： 官方文档中提到了 Webhook 回调地址，但对于本地 Mac 部署来说，搞公网 IP 极其麻烦且容易失效。

✅ 正确操作：锁定长连接（WebSocket）模式

回到飞书开发者后台，进入你的应用：

左侧点击 事件订阅。
打开”启用长连接”的开关

（这就是内网穿透的魔法！不需要公网 IP）。
确认已添加的事件中包含 接收消息（im.message.receive_v1）。

核心配对：让机器人认主

这是将飞书与本地 OpenClaw 打通的最核心操作：

第一步：重启系统

回到 Mac 终端，执行重启命令，让系统准备好接收飞书的信号：

cd ~/openclawdocker compose restart

第二步：获取配对码

去飞书客户端里找到你的机器人，随便发一句话（比如”你好”）。

此时机器人不会回答你的问题，而是回复一段包含配对码的英文提示，例如：

Your pairing code is: RVNV2R55

请把这个配对码记下来。

第三步：终端执行配对命令

拿着上面的配对码，回到 Mac 终端，执行以下命令（把 RVNV2R55 替换为你自己的配对码）：

cd ~/openclawdocker compose run --rm openclaw-cli pairing approve feishu RVNV2R55

🎉 恭喜！当这行代码执行成功后，你的飞书机器人就已经成功接管了 DeepSeek 最强大脑！

现在你可以在飞书里对机器人发消息了，它会用 DeepSeek 的大脑来回答你的问题。

👁️ 第三阶段：给 AI 装上眼睛（接入阿里千问视觉模型）

DeepSeek 文字能力极强，但目前还不能看图。我们需要添加一个能看图的模型（阿里通义千问 qwen-vl-max），让飞书机器人拥有视觉解析能力。

⛔ 避坑点：终端改代码的”标点符号地狱”——新手极易在用命令行编辑器（如 nano）修改底层 JSON 配置文件时漏掉逗号或括号，一旦格式错误，将导致整个系统崩溃无法启动（报 1006 错误）。

✅ 正确操作：两种方法，任选其一

方法 A：网页填表法（推荐新手，最简单安全）

打开浏览器，回到 OpenClaw 控制台：http://127.0.0.1:18789
点击左侧底部的 Settings → Providers → Add Provider。
选择 Custom / OpenAI Compatible（兼容格式）。

仔细填写以下参数：

参数	填写内容
Name	随便起个名字，比如 `qwen-vl`
Base URL	`https://dashscope.aliyuncs.com/compatible-mode/v1`
API Key	填入你的阿里云 API 密钥（形如 `sk-xxxx`）
Models	输入 `qwen-vl-max`（这是千问的视觉大模型）

点击 Save 保存。

方法 B：VS Code 编辑配置（适合熟悉代码的用户）

由于前面我们做好了目录挂载，你可以直接在 Mac 上用带有语法纠错功能的 VS Code 修改集装箱里的配置。

在终端输入以下命令打开配置文件：

code ~/.openclaw/openclaw.json

VS Code 弹出后，openclaw.json 的最外层应该有一个 providers 对象。在它的下面添加阿里千问的配置。如果不小心漏了逗号，VS Code 会画红色波浪线提醒你，不用担心。

正确的格式如下（注意 providers 是和 models 平级的一个对象）：

"providers":{"custom-qwen":{"type":"openai","baseUrl":"https://dashscope.aliyuncs.com/compatible-mode/v1","apiKey":"sk-xxx（替换为你的真实 Key）","models":[{"id":"qwen-vl-max","name":"Qwen VL Max","input":["text","image"]}]}}


保存文件（Cmd + S）。

必须重启系统才能生效：

cd ~/openclaw && docker compose restart
🌟 验收成果
配置完成后，在 OpenClaw 网页控制台的聊天框中，找到顶部或下拉菜单里的模型切换选项，将模型切换为 qwen-vl-max。输入框旁边会出现一个”回形针 📎” 或图片上传按钮——恭喜，你的数字员工正式长出了双眼！
你可以在飞书或网页里给它发一张截图、一张照片，它会看懂并回答你图中的内容。

💡 进阶使用小贴士：算力调度
在控制台的模型切换下拉菜单中，你会看到几个选项。不同的场景选不同的模式：

Inherited（继承）

 — 跟随系统的全局默认设置，也就是你在 Settings 里设定的默认模型。日常用这个就好。

Default（普通负载）

 — 日常闲聊选这个，速度快、省钱（Token 消耗少）。

High load（满血推理）

 — 当你让 AI 分析万字长文、复杂财务图表或写代码时，果断开启它。此时系统会允许模型（如 DeepSeek-R1）在后台打草稿、反复推演逻辑，提供极致质量的最终答案。


❓ 常见问题（FAQ）
Q：启动后浏览器访问不了 http://127.0.0.1:18789？
A：先检查 Docker Desktop 是否在运行（右上角小鲸鱼是否显示 Engine running）。如果 Docker 没启动，系统就不会运行。启动 Docker 后再执行一遍 docker compose restart。
Q：终端执行 docker compose 报错说找不到命令？
A：说明 Docker Desktop 还没装好，或者安装后没有重启终端。先确认 Docker Desktop 已安装并正常运行，然后完全退出终端再重新打开。
Q：飞书发消息给机器人没反应？
A：检查以下三点：


飞书开发者后台的”长连接”开关是否已打开？

接收消息（im.message.receive_v1）

 事件是否已添加？


是否已经完成了版本发布？新增的权限和事件必须发布后才能生效。


如果以上三点都确认无误，回到终端重新运行 docker compose restart 试试。
Q：重启后之前的配置丢了？
A：正常情况下不会。检查你的 ~/.openclaw 文件夹是否还在。如果这个文件夹没了，说明挂载映射出了问题。在终端执行 ls -la ~/.openclaw 看看，如果不存在，可能是 docker-compose.yml 中的 volumes 配置不正确。
Q：报错 1006，系统起不来了？
A：这通常是因为你手动编辑 openclaw.json 时搞错了 JSON 格式（漏了逗号、多写了括号）。解决方法：用 VS Code 打开 ~/.openclaw/openclaw.json，看有没有红色波浪线标出的语法错误，修正后重启即可。
Q：DeepSeek API Key 去哪申请？
A：访问 DeepSeek 开放平台，注册账号后，在左侧 API Keys 页面创建一个新 Key。
Q：阿里千问 API Key 去哪申请？
A：访问 阿里云百炼平台，注册或登录阿里云账号，进入模型广场找到通义千问视觉模型，开通服务并生成 API Key。

📝 最后的话
恭喜你完成了全部设置！现在你拥有了一套：


✅ 本地运行的 AI 中枢（数据安全、永远在线）


✅ DeepSeek 最强逻辑大脑（文字推理天花板）


✅ 飞书即时沟通入口（24 小时待命，随时呼叫）


✅ 阿里千问视觉能力（能看懂截图和照片）


这套系统就像你在数字世界的”第二大脑”。后面可以在对话框中给他下达任务：让它自动整理飞书文档、定时做日报、整理本地文件，或者接入更多能力 🚀