企业官网建设流程全解析

1. OpenClaw 里 clawhub install 装完却显示 missing 到底缺了什么

clawhub install装完技能，openclaw skills list里却挂着一个 ✗ missing，这个场景我第一次遇到时也以为是安装包没落盘。后来把openclaw skills check的输出翻出来看，才发现 missing 跟"文件丢了"完全是两码事。OpenClaw 的 skills 机制里，missing 表示技能在 SKILL.md frontmatter 里声明的运行前提没有满足，而不是安装目录里少了 handler.js 或者脚本。

先把结论摆出来：clawhub install只负责把技能包里的 SKILL.md 和元数据写进 workspace 的 skills 目录，它不会替你装 Python 包、不会替你申请 API token、也不会替你改 PATH。技能能不能从 missing 变成 ready，取决于 frontmatter 里requires声明的三类前提——env、bins、os——是否全部满足。任意一项不满足，状态就是 missing（新版本里可能显示成 △ needs setup，语义一样）。

这套机制适合谁？适合所有在 OpenClaw 里用 clawhub 装技能、然后被 missing 卡住的人。不管你是装 paddleocr-doc-parsing 这种文档解析技能，还是装 notion、1password 这类需要外部 CLI 的技能，排查路径都是同一套。核心检索词就三个：clawhub install、skills missing、openclaw skills check。把这三个串起来，你就能定位到底是"安装没落盘"还是"加载路径没命中"。

我实测下来，missing 的成因基本落在两个方向。第一个方向是依赖没满足：技能声明了bins: [paddleocr]，但你机器上根本没有 paddleocr 这个命令，或者装了但不在 PATH 上，网关的 hasBinary 检测返回 false。第二个方向是加载路径没命中：技能确实装到了~/.openclaw/workspace/skills/下，但网关读取的 skills 根目录配置指向了别处，或者目录结构不符合预期，导致加载器扫不到这个技能。这两个方向的排查手法不一样，下面分开讲。

还有一个特别隐蔽的坑：网关会把"某个二进制是否存在"的判定结果缓存在进程内存里。你在装好 CLI 之后如果不重启网关，skills list拿到的还是旧结果，看起来就像"改了没用"。这一点在排查时极容易误判，后面会专门给验证步骤。

2. TaoToken 通道下 OpenClaw 技能排查的前置准备

在动手排查之前，先把 TaoToken 这条通道的角色理清楚。OpenClaw 本身是个 Agent 运行框架，它调用模型能力时需要走一个兼容 OpenAI 协议的 API 端点。TaoToken 提供的就是这个端点，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。你需要在 OpenClaw 的模型配置里把 Base URL 指向这个地址，把 API Key 填成在控制台申请的密钥，Model ID 填你实际要用的模型名。

这里要强调一个排查顺序问题。很多人一看到 skills missing，第一反应是去查模型通道是不是断了。其实 skills 的状态判定跟模型通道没有直接关系——missing 是技能前提检查的结果，发生在模型调用之前。但为什么还要先讲 TaoToken 前置？因为当你把技能修到 ready 之后，真正跑一次解析、验证功能可用时，模型通道必须通。如果通道没配好，你会看到技能状态是 ready，但一执行就报连接错误，那时候排查方向就乱了。所以先把通道配好，把技能状态和模型调用这两件事分开验证。

TaoToken 通道的配置要点有三个。Base URL 用 https://taotoken.net/api ，注意不要多加路径后缀，OpenClaw 会自己拼接/chat/completions。API Key 在控制台的 API Keys 页面生成，生成后只显示一次，记得当场保存。Model ID 要跟你申请通道时选的模型一致，写错了会返回 model not found。这三件套配好之后，先用一个最简单的对话请求验证通道通不通，再去折腾 skills。

如果你还没申请 Key，可以去 https://taotoken.net/api-keys 生成。接入文档在 https://taotoken.net/doc ，里面有各语言 SDK 的调用示例，照着改 Base URL 就行。想先验证模型能不能正常对话，可以用 https://taotoken.net/chat 这个页面直接试。长期做编码和 Agent 任务的，可以看 https://taotoken.net/coding-plan ，把额度规划一下。

通道验证通过之后，再回到 skills 排查。这时候你手里有两个独立的验证工具：一个是openclaw skills check看技能前提，一个是模型对话看通道。两者互不干扰，出问题时能快速定位是哪一层。

3. 可复制的目录检查与 clawhub 重装配置

排查 missing 的第一步，是把技能到底装到哪了、目录结构长什么样看清楚。OpenClaw 默认的 skills 根目录在用户目录下的.openclaw/workspace/skills/。Windows 上是C:\Users\<you>\.openclaw\workspace\skills\，macOS 和 Linux 上是~/.openclaw/workspace/skills/。先用命令确认这个目录存在，并且里面有你刚装的技能文件夹。

# Windows PowerShell Get-ChildItem "$env:USERPROFILE\.openclaw\workspace\skills" -Directory # macOS / Linux ls -la ~/.openclaw/workspace/skills/

正常输出里应该能看到paddleocr-doc-parsing这样的技能目录。进去看一层，确认 SKILL.md 在不在：

# Windows Get-ChildItem "$env:USERPROFILE\.openclaw\workspace\skills\paddleocr-doc-parsing" # macOS / Linux ls -la ~/.openclaw/workspace/skills/paddleocr-doc-parsing/

如果 SKILL.md 在，说明安装已经落盘，missing 不是文件丢失导致的。如果目录根本不存在，那才是安装没落盘，需要重装。重装之前先确认 clawhub 的缓存状态，因为 clawhub 会缓存技能包，缓存损坏时重装也可能装出问题。

# 查看 clawhub 缓存目录 # Windows Get-ChildItem "$env:USERPROFILE\.clawhub\cache" # macOS / Linux ls -la ~/.clawhub/cache/

清缓存后重装：

clawhub cache clean clawhub install paddleocr-doc-parsing

重装完再跑一次openclaw skills check，看 missing 行有没有变化。如果还是 missing，那就进入前提排查阶段。这时候打开技能的 SKILL.md，看 frontmatter 里的 requires 声明：

--- name: paddleocr-doc-parsing metadata: openclaw: requires: env: - PADDLEOCR_ACCESS_TOKEN bins: - paddleocr primaryEnv: PADDLEOCR_ACCESS_TOKEN install: - kind: uv package: paddleocr bins: [paddleocr] ---

这段 frontmatter 告诉你两件事：需要PADDLEOCR_ACCESS_TOKEN这个环境变量，需要paddleocr这个命令在 PATH 上。缺哪个补哪个。补 bins 的方式是在专用 venv 里装 paddleocr，然后做 PATH 垫片；补 env 的方式是在 openclaw.json 的 skills.entries 里配。

openclaw.json 的配置片段如下，路径在C:\Users\<you>\.openclaw\openclaw.json：

{ "skills": { "entries": { "paddleocr-doc-parsing": { "enabled": true, "env": { "PADDLEOCR_ACCESS_TOKEN": "你的真实令牌" } } } } }

注意这里的判定规则：isEnvSatisfied = Boolean(process.env[变量名] || skills.entries.<技能>.env[变量名])。只要配置里非空，状态检查就通过。但真正调用 API 时要用有效令牌，占位符过得了状态检查、过不了认证。

PATH 垫片的做法是在 npm 全局 bin 目录放一个转发脚本。Windows 上新建C:\Users\<you>\AppData\Roaming\npm\paddleocr.cmd，内容：

@echo off rem paddleocr CLI shim - forwards to dedicated venv install "C:\Users\<you>\.openclaw\tools\paddleocr-venv\Scripts\paddleocr.exe" %*

保存时注意三点：后缀必须是.cmd不是.txt，行尾必须是 CRLF，编码用 ANSI。做完垫片后新开一个终端，用where paddleocr验证能找到。

4. 验证请求与成功结果确认

配置改完之后，最关键的一步是重启网关。因为网关把 hasBinary 的判定结果缓存在进程内存里，不重启永远显示旧状态。

openclaw gateway restart

重启完再跑检查命令：

openclaw skills check openclaw skills list

修复前你会看到类似这样的输出：

△ needs setup │ paddleocr-doc-parsing (bins: paddleocr; env: PADDLEOCR_ACCESS_TOKEN)

修复后应该变成：

✓ ready │ paddleocr-doc-parsing

如果skills check里 Missing requirements 列表已经空了，skills list显示 ✓ ready，说明前提全部满足。但 ready 只代表前提满足，不代表功能可用。接下来要实际跑一次解析，验证模型通道和技能执行都正常。

在 OpenClaw 聊天里发一条指令：

把 C:\Users\<you>\Documents\测试报告.pdf 解析成 Markdown

Agent 会按 SKILL.md 的指引执行paddleocr api --model_type doc_parsing --file_path ...，返回结构化 Markdown 或 JSON。如果这一步成功返回内容，说明整条链路通了：技能加载正常、CLI 可调用、token 有效、TaoToken 模型通道也正常。

如果这一步报 Authentication 错误，说明 token 是占位符或已过期，回 openclaw.json 填真实令牌再重启网关。如果报命令不存在，说明网关启动早于垫片创建，重启网关即可。如果报连接超时，检查 TaoToken 通道的 Base URL 和网络。

验证模型通道是否正常，可以单独发一条普通对话请求，不涉及技能。如果普通对话能返回，说明通道没问题，问题在技能侧；如果普通对话也失败，先修通道。这个分离验证的思路能帮你快速缩小排查范围。

5. 本篇常见错误排查对照

排查过程中会遇到几类典型报错，这里按真实错误信息对照给解法。

第一类是 401 认证失败。报错信息通常是401 Unauthorized或Authentication failed。原因有两个可能：TaoToken 的 API Key 填错或过期，或者技能的 PADDLEOCR_ACCESS_TOKEN 是占位符。区分方法：如果普通对话也 401，是 TaoToken Key 的问题，去 https://taotoken.net/api-keys 重新生成；如果普通对话正常、只有技能执行 401，是技能 token 的问题，回 openclaw.json 填真实令牌。

第二类是 local proxy failed。这个报错通常出现在网关尝试连接模型端点时，说明 Base URL 配置有问题。检查 openclaw.json 里模型配置的 baseURL 是不是https://taotoken.net/api，有没有多加/v1或/chat/completions后缀。OpenClaw 会自己拼接路径，多写后缀会导致 404 或 proxy failed。

第三类是 reading choices 相关报错，比如Cannot read properties of undefined (reading 'choices')。这说明模型返回的响应结构不符合预期，通常是 Model ID 写错了，或者通道返回了错误信息但被当成正常响应解析。检查 Model ID 是否跟申请通道时选的模型一致，用 https://taotoken.net/chat 单独测一下这个模型能不能正常返回。

第四类是 OAuth 相关报错。如果技能声明了 OAuth 类型的认证，而你没完成授权流程，会看到 OAuth token missing 之类的提示。这类技能需要在对应平台完成授权，把 token 填进 skills.entries 的 env 里。

第五类是技能一直显示 needs setup 且标注os: darwin。这是操作系统硬限制，Windows 上无解。比如 peekaboo、apple-notes、tmux 这类技能只支持 macOS 或 Linux，在 Windows 上永远 missing。这不是故障，直接换 Windows 可用的同类技能即可。

第六类是where paddleocr找不到垫片。检查垫片文件是不是保存成了paddleocr.cmd.txt，记事本另存为时"保存类型"要选"所有文件"。另外确认垫片放在 npm 全局 bin 目录下，这个目录本身在 PATH 上。

第七类是状态 ready 但执行报命令不存在。这说明网关启动时垫片还不在 PATH 上，网关缓存了旧的 hasBinary 结果。重启网关即可。

排查时记住一个原则：openclaw skills check的 missing 行就是你的待办清单，格式是技能名 (bins: xxx; env: XXX; os: xxx)，缺哪项补哪项，不用猜。补完必重启，重启后再 check，循环直到 ready。

6. 后续接入与长期使用建议

把技能修到 ready 并实测通过之后，这套流程就可以固化成习惯。每次用clawhub install装新技能，都走五步：install → check → 补前提 → gateway restart → 实测。其中 check 是核心，它直接告诉你缺什么。

对于需要长期跑编码和 Agent 任务的场景，建议把 TaoToken 的 Coding Plan 用起来，地址在 https://taotoken.net/coding-plan ，额度规划好之后不用频繁担心调用限制。接入文档在 https://taotoken.net/doc ，里面有完整的配置示例。控制台在 https://taotoken.net/console ，可以管理 Key 和查看用量。

技能更新也要注意。openclaw skills update可以批量更新已装技能，但更新后同样要gateway restart加重新skills check，因为新版技能可能新增了 requires 声明。更新完不重启，状态可能还是旧的。

最后提醒一个安全细节：openclaw.json 里存了 token，这个文件不要提交进 git。建议加入 .gitignore，或者用忽略规则保护。令牌集中放这个文件的好处是方便统一轮换，但前提是文件本身别泄露。