企业官网建设流程全解析

如果你也和我一样，手里跑着一个本地部署的AI智能体，却总是因为“人不在电脑前”而用不上它，那这篇文章应该能帮你省下至少两天的折腾时间。核心主角是开源的ClawdBot（社区里现在更多直接叫 OpenClaw）——一个可以接微信、飞书、钉钉，通过大模型“干活”的 Agent 框架；另外两个配角是 Cloudflare Tunnel 和 Zero-Trust，一个负责把本地服务安全暴露到公网，一个负责给公网访问加门禁。这套组合搭完之后，我在手机上就能唤起自己部署的 OpenClaw，出门在外也能随时打开它的控制台，IM 里丢一条消息给它就能让它跑任务，体验上已经接近那些“云上托管”的商业 Agent 产品，但数据和模型资源全在自己手里。

这篇保姆教程不假设你有任何公网 IP、服务器或网络工程基础，只要求你有一台能跑 Node.js 的电脑、一个域名、以及愿意跟着操作指南一步一步来。我把自己从零搭到跑通的完整过程、踩过的坑、每个坑背后的原因都写了出来。

1. 为什么是这组搭配：三个组件各自解决什么问题

1.1 ClawdBot（OpenClaw）：能接 IM、能写 Skill 的开源 Agent 框架

OpenClaw 是一个开源智能体运行框架，核心思路是：把大模型的能力装进一个可以“动手执行任务”的框架里。它不是某个固定的聊天机器人，而是一个壳，模型可以换，能力可以通过 Skill 无限扩展。社区里有人拿它写小说，有人让它修复 ComfyUI 的环境问题，有人给它写 Skill 接各种第三方 API，还有人靠 Active Memory 给它做长期工作记忆。

我当时看上它，就三点：

• 私有部署。模型 API Key、对话记录、Skill 逻辑全部存在自己的机器上，不经过第三方平台。
• 渠道灵活。官方支持接入飞书、钉钉，社区也有大量微信相关的实践。
• 模型中立。DeepSeek、千问、通义、本地模型、NVIDIA NIM，甚至 OpenAI 兼容接口都可以接入，不像某些产品锁死在自家模型上。

实际上手之后我发现，OpenClaw 的日常使用可以很轻：配好模型，写好一个 Skill，然后在 IM 里发一句“帮我查一下某个 API 的文档并整理成摘要”，它就能自己拆解任务、调用工具、返回结果。这个体验要远好于单纯在网页对话框里聊大模型。

1.2 Cloudflare Tunnel：把本地服务安全搬到公网的“管道”

本地部署最大的麻烦是“别人访问不了你”。没有公网 IP 的情况下，传统套路是路由器端口映射，或者用第三方内网穿透工具。前者要求运营商给你公网 IP，后者通常限速、限流量，免费版还强制绑定域名，不稳定。

Cloudflare Tunnel 的思路完全不同：在本地跑一个cloudflared进程，由它主动向 Cloudflare 边缘节点建立一条出方向的加密隧道。外部用户访问你的自定义域名时，请求会先到 Cloudflare 边缘，再由边缘通过隧道转发到本地服务。

这样做有几个实打实的好处：

• 不需要公网 IP，也不需要路由器上做任何端口映射。
• 出口方向由你的程序发起，家里网络、公司网络、虚拟机里都能跑。
• 自带 HTTPS，不用自己申请证书。
• 免费额度对这个场景完全够用。

你可以把它理解成：你的电脑和 Cloudflare 之间常年保持着一条加密管道，别人访问你的域名时，Cloudflare 负责把请求“塞进管道”递到你家电脑的服务上。别人看到的是 Cloudflare 的 IP，看不到你本机的真实 IP。

1.3 Zero-Trust：给服务加一道身份门禁

隧道把服务暴露到公网之后，随之而来的是新的问题：任何人都可能通过域名访问你的 WebUI。OpenClaw 的控制台如果裸奔在公网上，不仅数据会被看光，还有可能被当成肉鸡，别人通过它调用你的模型 API，那是真金白银的消耗。

Cloudflare Zero-Trust（也叫 Cloudflare Access）做的事情，是在流量到达你的服务之前，先做一次身份验证。用户访问域名时，先看到 Cloudflare 的登录页，输入邮箱收到一次性验证码，验证通过之后，Cloudflare 才把请求转发到隧道本地。也就是说，即使你的服务本身完全没有账号体系，也能获得一层和 Cloudflare 安全体系同级的外层防护。

三个组件加在一起的完整链路是：用户访问域名 → Cloudflare 边缘检查 Zero-Trust 策略 → 通过后进入隧道 → 到达本地 OpenClaw。任何一环都挡在服务之前，风险面被压缩到最低。

2. 零基础环境准备：版本、运行方式，以及最容易卡住的地方

2.1 先确认 Node.js 版本：这个项目对运行时要求非常严格

OpenClaw 对 Node.js 版本的要求很细：>=22.22.3 <23、>=24.15.0 <25，或者>=25.9.0。这和我平时见到的那种“随便装个 LTS 就行”的开源项目完全不同。

我一开始用的 Node 20，启动时直接报错提示版本不匹配。后来切到 Node 22.22.3 之后才正常。检查版本用：

node -v

如果版本不对，强烈建议用 nvm 管理多版本。macOS/Linux 用 nvm，Windows 用 nvm-windows。安装好后切换到指定版本：

nvm install 24.15.0 nvm use 24.15.0

这里有个细节：Windows 用户在安装新版本 Node 之前，最好把旧版本先卸载干净，否则可能出现“装了新版，但node -v还是旧版”的诡异问题。我遇到过好多次，基本都是 PATH 环境变量顺序或者 npm 全局 bin 目录残留导致的。

2.2 本地源码运行还是 Docker：两条路线怎么选

OpenClaw 有两条主流部署路线：源码运行和 Docker 运行。

源码运行适合需要二次开发、调试 Skill、快速改代码的场景。大致流程是：

git clone <openclaw仓库地址> cd openclaw npm install npm start

Docker 运行适合不想污染宿主机环境、或者希望快速迁移的场景。社区里有大量关于“Mac mini Docker 本地部署”和“VM 虚拟机安装”的讨论。用 Docker 的好处是版本一致性，可以在不同机器上得到完全相同的运行环境。

我个人的建议是：如果你只是拿它当工具用，直接 Docker；如果你想给 OpenClaw 写自定义 Skill、做二次开发，源码运行更方便，因为改完代码能立刻在终端看到输出，调试体验好很多。如果是在 VM 里用 Docker 部署，注意嵌套虚拟化的性能损耗，内存至少给到 4GB 以上，否则模型加载和构建过程会非常卡。

2.3 Windows 上两个高频报错及处理

Windows 用户最容易遇到的两个问题，热词里都出现了。

第一个是oneclaw node runtime not found。这个报错看起来像是“找不到 Node”，实际上 OpenClaw 启动时会对运行时版本做校验，校验失败就会报这个。常见处理是彻底卸载旧 Node，安装符合版本矩阵的版本，然后重启终端。另外检查一下 npm 全局路径：

npm config get prefix

如果前缀指向的是一个不存在的目录，后面的npm install -g都有问题。

第二个是failed to remove ~\.openclaw: error: ebusy: resource busy or locked, unlink。

这个错误几乎只出现在 Windows 上。原因是有进程占用了~/.openclaw目录下的文件。最常见的占用者是：还在运行的 OpenClaw 进程、Node.js 进程、代码编辑器（VSCode 看着不占，实际上会有文件监听）、以及安全软件的全盘扫描。解决步骤：

1. 任务管理器里结束所有node.exe进程。
2. 关闭正在编辑 .openclaw 目录下文件的编辑器。
3. 如果还不行，临时退一下安全软件，或者把~/.openclaw目录加入实时扫描排除清单。
4. 确认没有进程占用后，再手动删除或重新初始化。

这个坑的根源在于 Windows 对文件锁的处理方式和 Linux/macOS 不一样。很多在 Linux 上能正常删除的文件，在 Windows 上就是删不掉。遇到 EUSY，不要硬删，先找“谁锁了文件”。

2.4 数据目录与配置目录

OpenClaw 默认会在用户目录下创建~/.openclaw目录，用来存放配置、日志、Skill、Active Memory 等数据。如果你之前装过旧版本，新版本启动时可能会因为配置结构变化而报错。此时建议先备份旧目录，再让其初始化一份全新配置：

mv ~/.openclaw ~/.openclaw_backup

备份之后重新启动 OpenClaw，它会自动生成一份默认配置。确认没问题后，再把自己需要的模型配置手动迁移回去。这个操作能规避掉非常多“灵异问题”，因为大部分升级场景下的报错，都和旧配置里的字段不兼容有关。

3. 让 OpenClaw 正常“开口说话”：模型配置与多模型切换

3.1 模型供应商与 API Key 配置

环境准备好之后，第一步就是配置模型。OpenClaw 支持多种模型供应商，包括 DeepSeek、千问（通义）、OpenAI 兼容接口、本地模型、NVIDIA NIM 等。

配置文件的格式因版本而异，但核心字段基本一致：

model: provider: deepseek apiKey: sk-xxxx model: deepseek-chat

社区里很多人用千问的免费 token 跑通基础对话，也有人在本地跑模型做完全离线场景，还有人通过 NVIDIA NIM 接入专业领域的推理能力。如果你刚开始，我建议先挑一个你已经有的 API Key 的供应商，配好之后不要急着切换，先把对话跑通。

这里需要特别提醒：模型供应商的 API 地址是否可达，是你自己网络环境和供应商决定的，和 OpenClaw 框架本身无关。如果发现配了 API Key 之后请求超时，先用其他工具或命令行单独测试该模型的 API 连通性，确认没问题后再排查 OpenClaw 侧的配置，不然很容易在错误的方向上浪费时间。

3.2 “unknown model”与“agent failed before reply”的根因

热词里有一条很典型的报错：unknown model: deepsee。这个基本就是模型名写错了。DeepSeek 官方 API 里的模型名通常是deepseek-chat或deepseek-reasoner，不会是deepseek或deepsee这样简写。多一个字母、少一个字母，模型服务端都会直接拒绝。

还有一条高频报错：agent failed before producing a reply。遇到这个，先不要怀疑框架坏了，先确认：

• API Key 是否正确、是否有余额。
• 模型名称是否在该供应商的模型列表里。
• 网络是否能正常访问模型 API 服务。
• 如果是新加的供应商，确认该供应商的接口格式和 OpenClaw 要求的是否一致。

我的排查经验是：先绕开 OpenClaw，直接用 curl 或脚本调用一次模型 API，确认可以返回内容之后再说。如果单独调用都不通，问题出在模型侧；如果单独调用通、进了 OpenClaw 不行，再去看配置文件的 model 字段和 provider 名称是否匹配。

还有一个容易被忽略的点：“zero token”或新初始化的环境里，如果还没生成会话上下文，第一次对话可能因为初始化的原因失败。多试一次，或者清掉~/.openclaw下的缓存目录再试，往往就好了。

3.3 多模型切换与默认模型

OpenClaw 支持多模型配置，也就是说，你可以在一个实例里同时配好 DeepSeek、千问、本地模型，然后按需切换。切换可以在 WebUI 里操作，也可以通过在对话中发送特定指令，或者在配置文件里指定默认模型。

我的建议是：把最常用、最稳定的模型设为默认，其他模型作为备用。比如我默认用 DeepSeek 做日常任务，因为便宜、速度快；写长文或需要更强推理时切到更强模型；本地模型只在调试 Skill 或者网络不可用时用。

配置多个模型时，要保证每个模型的provider、apiKey、model三件套都齐全。少一个，切换时会直接报模型初始化失败。这种问题不好排查，因为报错信息不一定指向具体是哪个模型配置没写完。

3.4 Control UI（WebUI）无法启动的排查

OpenClaw 的 Control UI 是管理界面，能在浏览器里查看会话、切换模型、管理 Skill、查看 Active Memory。热词里出现openclaw control ui did not start，启动成功后却没有打开浏览器页面，或者页面完全打不开。我遇到的常见原因有三个：

1. 终端窗口没有打印出 UI 地址。此时看启动日志里有没有http://localhost:端口之类的输出，如果有手动复制到浏览器。
2. 端口被占用。OpenClaw 的 UI 端口如果已被其他服务占用，UI 进程会启动失败。换个端口，或者把占用端口的进程关掉。
3. 首次启动时需要下载前端依赖资源，如果网络不好，前端文件加载不完整，浏览器里只显示空白页。遇到这种情况，清掉浏览器缓存，硬刷新一次，还不行就重启 OpenClaw。

注意区分 API 端口和 UI 端口。API 端口是给 IM 渠道和外部调用用的，UI 端口是管理界面用的，两者不能搞混。Cloudflare Tunnel 转发时也必须转发到正确的端口，转发错了会看到 521 或 523 错误。

4. 让公网能访问到本地：Cloudflare Tunnel 完整配置

4.1 前置条件：域名、DNS、cloudflared

配置 Cloudflare Tunnel 之前，你需要三样东西：

• 一个 Cloudflare 账号。
• 一个域名，且域名的 DNS 托管在 Cloudflare。
• 本地安装cloudflared命令行工具。

安装cloudflared很直接。macOS 用 Homebrew：

brew install cloudflared

Linux 可以下载官方二进制：

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared chmod +x cloudflared sudo mv cloudflared /usr/local/bin/

Windows 就下载cloudflared-windows-amd64.exe，改名成cloudflared.exe，放到一个固定目录里，并把该目录加入 PATH。

安装完成后验证：

cloudflared --version

4.2 创建隧道并把域名指向本地服务

第一步，登录 Cloudflare 并授权域名：

cloudflared tunnel login

这条命令会弹出浏览器，选择你的域名，授权之后会在~/.cloudflared/下生成一张证书文件。

第二步，创建隧道：

cloudflared tunnel create openclaw

创建完成后，会在~/.cloudflared/下生成一个 JSON 凭据文件。这个文件相当于隧道的身份证，别删。

第三步，把域名路由到隧道：

cloudflared tunnel route dns openclaw claw.example.com

这条命令会在你的 DNS 里自动创建一个claw.example.com的 CNAME 记录，指向openclaw.cfargotunnel.com，也就是告诉 Cloudflare：这个域名的流量要进 openclaw 这条隧道。

4.3 用 config.yml 管理入口

隧道默认不知道要把流量转发到本机的哪个端口，所以需要创建一个配置文件~/.cloudflared/config.yml：

tunnel: openclaw credentials-file: /Users/yourname/.cloudflared/<隧道ID>.json ingress: - hostname: claw.example.com service: http://localhost:3000 - service: http_status:404

注意两个细节：

• tunnel字段填隧道名称，不是域名。
• credentials-file的路径要绝对路径，Windows 上注意路径分隔符。
• ingress列表最后一定要有一条兜底规则，返回http_status:404。如果没有兜底，配置校验会报错。

如果你的 OpenClaw UI 端口不是 3000，把它改成实际端口。想同时暴露 API 端口，可以再加一条 hostname 指向另一个域名或子路径：

ingress: - hostname: api.claw.example.com service: http://localhost:3001 - hostname: claw.example.com service: http://localhost:3000 - service: http_status:404

配置文件改好之后，检查一下：

cloudflared tunnel ingress validate

4.4 隧道跑起来之后，怎么验证和排障

启动隧道：

cloudflared tunnel run openclaw

如果一切正常，你会看到类似Registered tunnel connection的日志。这时在浏览器里访问https://claw.example.com，应该能打开本地 OpenClaw 的界面。

如果打不开，先看本地访问是否正常：

curl http://localhost:3000

如果本地正常但公网不行，大概率是隧道配置问题。浏览器报 521 表示 Cloudflare 无法连接到你本地服务，常见原因是 config.yml 里的 service 端口写错，或者 OpenClaw 的启动地址绑定了127.0.0.1，外部无法通过隧道的虚拟网络访问。后者需要在启动参数里把监听地址改成0.0.0.0。

我在这上面栽过一次：OpenClaw 启动时默认绑定 localhost，Tunnel 这边一切正常，但公网始终访问不了。后来发现 cloudflared 发出的请求到不了服务，一看日志，服务只监听了回环地址。改成0.0.0.0后立刻好了。

如果你希望隧道一直在后台跑，可以把它安装成系统服务：

cloudflared service install

安装后会注册为开机自启的服务，管理起来省心很多。

5. 给服务加锁：Zero-Trust 访问策略配置

5.1 创建 Access 应用与访问策略

隧道通了之后，如果你直接去访问claw.example.com，会发现没有任何登录过程，服务裸奔在公网。这时候就需要 Zero-Trust 上场。

登录 Cloudflare 控制台，进入 Zero Trust 板块。首次使用会要求创建一个团队名字，免费版即可。然后按下面步骤操作：

1. 在左侧菜单找到Access > Applications。
2. 点击Add an application，选择Self-hosted。
3. Application 名字随便填，比如 “OpenClaw Console”。
4. Session duration 默认 24 小时，可以按需缩短。
5. 下一步设置 Policy：

Policy name: Only Me Action: Allow Include: Emails -> 你的邮箱

保存之后，再访问claw.example.com，会出现 Cloudflare 的登录页。输入邮箱，会收到一次性验证码，验证通过后才会放行到本地 OpenClaw。

这一步做完，你的 WebUI 就有了身份门禁，即使服务本身没有账号体系，也不是谁都能访问的了。

5.2 IM 回调地址被拦截怎么办：Service Token

这里有个大坑：OpenClaw 接入飞书、钉钉后，消息平台服务器会主动调用你的回调地址（比如https://claw.example.com/webhook/feishu）。这些服务器是“机器”，没有邮箱，无法完成交互式验证码登录，请求会被 Zero-Trust 直接挡住。

结果就是你往 IM 里发消息，OpenClaw 完全没反应，因为回调根本进不来。

解决方案是使用 Zero-Trust 的 Service Token。在 Access 应用里，给回调路径单独配置一条 Policy，不要求邮箱登录，而是要求请求头里带上 Service Token：

1. 在 Zero Trust 控制台找到Access > Service Auth。
2. 创建一个 Service Token，系统会生成 Client ID 和 Client Secret。
3. 在 OpenClaw 的 IM 渠道配置里，把回调请求头设置为：

CF-Access-Client-Id: <你的Client ID> CF-Access-Client-Secret: <你的Client Secret>

4. 在 Access 应用里新增一条 Policy，Include 选择Service Token，勾选刚创建的那个 Token，Action 设为 Allow。

这样配置之后，携带了正确 Service Token 的请求就能绕过邮箱验证，直接进入隧道；普通浏览器用户仍然需要邮箱验证。两者互不干扰。

还有一种更省事但不太推荐的做法：对回调路径设置 Policy 时 Action 选Bypass。Bypass 意味着该路径下的所有请求都不需要验证，任何人都能调用你的回调接口。如果不做其他防御，别人可以伪造请求给你的 IM Bot 下发垃圾消息。所以我建议至少用 Service Token，不要直接 Bypass。

5.3 更安全的细节：域名、地区、IP 限制

把 Cloudflare Tunnel 和 Zero-Trust 都搭好之后，还有几个可以做的小加固：

• 邮箱域限制：如果你的需求是团队协作，Policy 里的 Include 可以直接填Emails domain: @yourcompany.com，这样只有该邮箱域下的人能访问。
• IP 限制：如果你有固定的办公 IP，可以在 Policy 里加一条 IP 范围限制，再加一个“先匹配 IP、后匹配邮箱”的嵌套结构。
• 国家地区限制：Cloudflare 支持按国家维度控制访问，但实际效果取决于你的用户分布。如果只有你自己用，可以直接限制为当前所在国家。
• 审计日志：Zero Trust 的 Access 日志里会记录每次登录和拦截操作。哪天你发现访问量异常，先来这里看。

这些配置都不是必须的，但能显著减少风险面。我的原则是：WebUI 这类管理入口，宁严勿松；IM 回调这类机器访问入口，宁用 Service Token，不裸奔。

6. 接入微信、飞书、钉钉的通用思路与合规提醒

6.1 渠道接入的本质：回调 URL 和消息路由

OpenClaw 接 IM 渠道，本质上是做三件事：

1. 在 IM 开放平台创建应用，获得凭证。
2. 把 IM 平台的事件回调地址指向你的公网域名（比如https://claw.example.com/webhook/feishu）。
3. OpenClaw 收到回调后，解析消息内容，交给模型处理，再通过 IM 开放平台的 API 把结果发回会话。

所以在做 IM 接入之前，Tunnel 加 Zero-Trust 这套公网链路必须先跑通。没有公网回调地址，IM 平台根本找不到你的服务。这也是我把 IM 接入放在教程后面的原因——前置条件必须先就位。

6.2 飞书、钉钉的配置步骤

飞书和钉钉的逻辑比较接近，以飞书为例：

1. 在飞书开放平台创建企业自建应用，开启机器人能力。
2. 在事件订阅里配置请求地址，也就是你的公网回调 URL。
3. 配置校验方式。飞书第一次请求你的地址时，会发一个 challenge 验证请求，OpenClaw 正常情况下能自动响应，前提是你的 Zero-Trust 策略没有把这次验证请求挡掉。所以第一次配置时，最好先把对应路径临时放行，调试通过后再收紧策略。
4. 在 OpenClaw 的渠道配置里填上飞书应用的 App ID、App Secret，保存后重启。

钉钉的流程类似，只是回调校验方式和事件订阅格式有差异，按官方文档操作即可。

如果你在配置后向机器人发了消息却完全没有响应，先去 Zero Trust 的 Access 日志里看回调请求是不是被拦截了。我之前排查过一次，日志里密密麻麻全是 Blocked，就是 Service Token 没配上。这里也再次印证了 5.2 节说的：回调路径必须单独处理身份验证。

6.3 关于个人微信自动化，我的建议

“OpenClaw 接入微信”是社区里非常热门的搜索词，但我要先泼一盆冷水：直接用个人微信账号做自动化的方案，在安全性上有很大隐患，轻则账号被限制功能，重则封号。这不只是 OpenClaw 的问题，是所有个人微信自动化工具的通病。正常做法是使用官方支持的接口，比如公众号、企业微信，或者用飞书、钉钉这类本身就对机器人开放程度较高的平台。

如果你只是自己用，我建议优先接飞书或钉钉，开发体验顺畅得多。配合公网回调和数据隐私保护策略，整个链路完全可控。

7. 部署过程踩坑记录与完整排查链路

7.1 本地服务正常但公网打不开：先看状态码

如果本地curl localhost:3000正常，但公网域名打不开，先看浏览器报错的状态码。Cloudflare 的错误页面一般会区分 521、522、523：

其中 521 最常见。我遇到过“OpenClaw 看起来在跑，但绑定的是 127.0.0.1，隧道访问不到”的情况，改监听地址为 0.0.0.0 后解决。522 多见于 Windows 防火墙弹窗时点了“取消”，导致 cloudflared 没有权限访问本机端口。523 则更多出现在笔记本睡眠唤醒之后，本机 IP 变化了，重启一下 cloudflared 就好。

排查顺序可以固定为：先看本地，再看隧道，最后看策略。

7.2 IM 回调没反应：先看 Access 日志

IM 回调没有响应时，不要急着改 OpenClaw 代码。我的排查链路是：

1. IM 开放平台的调试工具里手动触发一次回调，看平台侧是否报错。
2. 看 OpenClaw 的终端日志有没有收到请求。
3. 看 Zero Trust 的 Access 日志，有没有被 Block 的请求。
4. 用模拟请求手动调一次回调地址：

curl -X POST https://claw.example.com/webhook/feishu \ -H "Content-Type: application/json" \ -H "CF-Access-Client-Id: <Client ID>" \ -H "CF-Access-Client-Secret: <Client Secret>" \ -d '{"test":"ok"}'

如果模拟请求返回正常，而 IM 平台的消息依然进不来，问题基本出在 IM 平台侧的加密配置或事件订阅字段。如果模拟请求被拦，就在 Access 策略里检查 Service Token 的匹配情况。

7.3 VM / Docker 环境下的资源问题

在 VM 里用 Docker 跑 OpenClaw，有一个常见的隐蔽坑：磁盘空间不足。VM 的虚拟磁盘默认不会自动扩容，docker build拉镜像、构建层叠文件系统时，空间很容易被占满，然后出现莫名其妙的安装失败。先看一下磁盘占用：

docker system df df -h

清理构建缓存可以用：

docker builder prune

Mac mini 用 Docker 部署，一般注意 Apple Silicon 的 arm64 架构镜像即可，如果某些依赖没有 arm64 版本，可能需要加--platform=linux/amd64，但性能会有损耗。优先看镜像仓库有没有提供 arm64 版本。

7.4 文档读取失败与上下文限制

“OpenClaw 读取不了文档”是另一个高频问题。大部分时候不是“读不了”，而是模型上下文不够长，或者文档格式特殊（扫描版 PDF、图片型文件），模型本身不支持解析。这种情况下模型收到的内容是空的，表现就是“读取不了”。

排查思路：先确认这个文档格式是否被当前模型支持。文本类直接复制内容到对话里测试；PDF/Word 先转成文本再说。如果文档本身很大，先切片或摘要，再喂给模型。Skill 里接 API 时也要注意返回值大小，超出上下文就会被截断。

除了解析问题，也要确认文档是在本地哪个路径。OpenClaw 运行在容器里时，宿主机路径需要挂载进容器才能访问，否则它压根看不到你的文件。这也是“本地能读、容器里读不了”的常见原因。

最后说点实际的体会。这套组合真正跑通之后，我再也没觉得“本地部署的智能体只能在电脑前玩”。出门在外，手机微信/飞书里叫它干活，和管理界面随时打开看日志，数据始终在自己手里。回过头看，搭建过程中最耗时间的不是任何一步的“操作”，而是每一步的“默认值”——Node 版本、绑定地址、回调验证方式、Service Token，每一个都在用默认方式把我带进沟里。希望这篇教程能帮你把这些默认值一次性全部避开。