1. 手动装完 Markdown Converter 之后为什么还要配 TaoToken在 win11 本地部署 openclaw 的过程中手动安装技能只是第一步。很多人把markdown-converter文件夹丢进~/.openclaw/workspace/skills/之后重启网关然后在对话里让助手把 PDF 转成 Markdown结果助手回一句「我在本地没找到任何名为 Markdown Converter 的已安装技能」。这个报错我在第 9 集里也遇到过当时以为是路径写错了后来才发现真正的问题出在技能加载和模型通道这两件事上。Markdown Converter 这个技能本身不复杂它本质上是调用uvx markitdown把 PDF、Word、PPT、Excel、HTML、CSV、JSON、XML、图片、音频、ZIP、EPub 等格式转成 Markdown方便后续交给大模型处理或做文本分析。但技能装好之后openclaw 需要两样东西才能正常工作一是技能目录结构正确、SKILL.md能被扫描到二是一个稳定的模型 API 通道让助手在对话里能真正调用工具、返回结果。本篇聚焦的就是第二件事——手动安装 Markdown Converter 技能后的配置与验证环节。我会给出 TaoToken 统一 Key/API 通道的config.toml骨架与settings.json配置片段演示技能加载、转换测试与报错排查的可复制步骤。TaoToken 在这里扮演的角色是统一模型接入层官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你只需要一个 Key就能让 openclaw 里的助手稳定调用模型不用在多个供应商之间来回切换配置。适合谁看已经在 win11 上跑通 openclaw 基础对话、手动放好了markdown-converter技能文件夹、但卡在「技能不生效」或「转换请求发不出去」这一步的本地部署用户。如果你还没装 openclaw建议先看前几集把环境搭起来再回来跟这一篇。2. TaoToken 前置准备Key、通道与目录约定在动手改配置之前先把三件事确认清楚后面排错会省很多时间。第一件事是拿到 TaoToken 的 API Key。打开 https://taotoken.net/api-keys 登录后创建一个新 Key复制保存。这个 Key 是后面config.toml和settings.json里都要用到的核心凭证。注意不要把它提交到 Git 仓库也不要贴在公开聊天里。第二件事是确认 API 基地址。TaoToken 的统一通道地址是 https://taotoken.net/api 所有模型请求都走这个入口。openclaw 的配置里通常需要填base_url或api_base不同版本字段名略有差异下面我会给出两种常见写法。第三件事是确认 openclaw 的配置目录结构。在 win11 的 WSL 环境下典型路径是这样的~/.openclaw/ ├── config.toml # 主配置模型通道、网关参数 ├── settings.json # 技能与工具开关 ├── tools.json # exec 等工具权限可选 └── workspace/ └── skills/ └── markdown-converter/ ├── SKILL.md └── scripts/你可以先用一条命令确认技能文件夹到底在不在ls -la ~/.openclaw/workspace/skills/markdown-converter/如果这里能看到SKILL.md说明文件层面没问题接下来就是配置通道和加载。如果看不到先回到第 9 集把文件夹放对位置再继续往下。提示TaoToken 的 Key 只在服务端校验本地配置里不要写任何额外的中转地址直接填官方 API 入口即可。3. 可复制配置config.toml 骨架与 settings.json 片段这一节是全文的核心配置写对了后面验证基本一次过。3.1 config.toml 模型通道骨架打开~/.openclaw/config.toml加入或修改模型通道部分。下面是一个可直接套用的骨架把your_taotoken_key换成你在第 2 节拿到的 Key[gateway] host 127.0.0.1 port 18789 [model] provider openai-compatible base_url https://taotoken.net/api api_key your_taotoken_key model claude-sonnet-4-20250514 timeout_secs 120 [skills] enabled true skills_dir ~/.openclaw/workspace/skills auto_reload true几个字段说明一下。provider填openai-compatible是因为 TaoToken 的 API 兼容 OpenAI 风格的请求格式openclaw 大多数版本都支持这个 provider。base_url就是 https://taotoken.net/api 注意结尾不要多加/v1具体以你 openclaw 版本的拼接逻辑为准如果请求 404可以试着在末尾补/v1再测。model字段填你实际要用的模型名这里只是示例你可以换成自己账号下可用的任意模型。timeout_secs建议给到 120因为 PDF 转换加模型处理有时会比较慢。3.2 settings.json 技能开关片段settings.json负责技能和工具的细粒度开关。加入下面这段确保markdown-converter被显式启用{ skills: { markdown-converter: { enabled: true, autoLoad: true, description: Convert PDF/Word/PPT/Excel to Markdown via markitdown } }, tools: { exec: { enabled: true, allowlist: [uvx, markitdown, bash, -lc], denylist: [rm, dd], ask: on-miss, timeoutSecs: 120 } } }这里有两个关键点。第一markdown-converter的enabled和autoLoad都要为true否则技能扫描到了也不会加载。第二exec工具的allowlist里必须包含uvx和markitdown因为 Markdown Converter 底层就是靠uvx markitdown干活的。如果你只允许bash -lc而不放uvx助手在对话里调用转换时会直接被权限拦截。注意ask设为on-miss表示未命中白名单的命令需要人工确认这是比较安全的折中。如果你在纯测试环境想省事可以临时改成off但生产环境不要这么干。3.3 重启网关让配置生效改完两个文件后重启 openclaw 网关openclaw gateway restart如果重启命令没反应可以看一下进程状态openclaw gateway status正常情况下会显示 running。如果显示 stopped先看日志tail -n 50 ~/.openclaw/logs/gateway.log日志里如果出现config parse error多半是 TOML 或 JSON 语法写错了回去检查逗号和引号。4. 验证请求从技能加载到 PDF 转 Markdown 成功配置写完接下来用三步验证技能是否加载、通道是否通、转换是否成功。4.1 确认技能被扫描到重启后在 openclaw 对话里发一句列出当前已加载的技能如果返回列表里出现markdown-converter说明技能加载成功。如果还是提示找不到回到第 5 节看排查。4.2 确认模型通道连通再发一句简单的对话请求比如你好请回复当前使用的模型名称如果助手能正常回复说明 TaoToken 通道已经通了。如果报401或invalid api key检查config.toml里的 Key 是否复制完整、有没有多余空格。如果报404检查base_url结尾是否需要补/v1。4.3 实际转换一个 PDF把测试 PDF 放到工作区比如~/.openclaw/workspace/file/下然后在对话里说帮我把 file 目录下的 PDF 转换为 Markdown助手会先列出目录里的 PDF 文件名确认后执行转换。你也可以直接在终端手动跑一遍确认工具链本身没问题cd ~/.openclaw/workspace/file uvx markitdown 测试文档.pdf -o 测试文档.md ls -lh成功的话目录里会多出一个.md文件大小通常比原 PDF 小很多。我实测一个 14MB 的 PDF 转出来大约 27KB 的 Markdown转换耗时在几秒到十几秒之间取决于 PDF 页数和是否含图片。如果终端手动跑成功、但对话里让助手跑失败那问题基本在exec权限或技能加载上不是工具本身的问题。5. 本篇常见错排查这一节把我在 win11 本地部署时踩过的坑集中列一下对照着查能省不少时间。5.1 报错「找不到名为 Markdown Converter 的已安装技能」最常见的原因是文件夹层级多了一层。正确结构是skills/markdown-converter/SKILL.md而不是skills/markdown-converter/markdown-converter/SKILL.md。用find确认一下find ~/.openclaw/workspace/skills -name SKILL.md如果输出路径里出现了两次markdown-converter把内层文件夹的内容上移一层即可。5.2 报错「Command uvx not found」这是环境缺uv工具链。在 Ubuntu/WSL 下可以这样装sudo snap install astral-uv --classic注意--classic参数不能省否则 snap 会因为沙箱限制拒绝安装。装完后uvx --version能输出版本号就说明好了。5.3 报错「Exec denied」或转换请求被拦截说明settings.json里exec的allowlist没放行uvx。把uvx和markitdown加进去重启网关再试。如果还是被拦检查denylist里有没有误伤比如把bash整个禁掉了。5.4 报错「Rate limit exceeded」这个报错通常出现在用clawhub install自动安装技能时是技能仓库的限流不是 TaoToken 的问题。手动安装方式不受这个限制这也是本篇推荐手动装的原因之一。如果你在对话里频繁触发模型请求被限流那要看 TaoToken 账号的额度去 https://taotoken.net/console 查看用量。5.5 转换成功但 Markdown 内容为空多半是 PDF 本身是扫描件没有文字层。markitdown对纯图片 PDF 需要 OCR 支持默认不一定开启。可以先用pdftotext验证一下 PDF 有没有文字层pdftotext 测试文档.pdf - | head -20如果输出为空说明是扫描件需要额外配 OCR 流程这不在本篇范围内。5.6 配置改了但没生效openclaw 有些版本不会热加载config.toml必须重启网关。养成改完就openclaw gateway restart的习惯。如果重启后还是旧配置检查是不是有多个配置文件比如~/.openclaw/config.toml和项目目录下的config.toml同时存在实际加载的是另一个。6. 接入文档与后续验证入口配置和验证都跑通之后建议把接入文档存一份后面换模型或加技能时对照着改。TaoToken 的接入文档在 https://taotoken.net/doc 里面有不同语言和框架的调用示例openclaw 的openai-compatible配置可以直接参考其中的 OpenAI 部分。如果你只是想快速验证某个模型在当前通道下能不能正常对话可以用模型对话页面直接测 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这个页面不依赖 openclaw能帮你快速区分是通道问题还是本地配置问题。长期在 openclaw 里跑编码任务或 Agent 工作流的可以看一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它更适合高频调用场景额度管理也更清晰。最后提醒一句settings.json里的exec白名单尽量细粒度只放你确实需要的命令。Markdown Converter 只需要uvx和markitdown不要图省事写成通配符。我试过把ask设成off图方便结果一次误触发了不该跑的命令后来还是老老实实改回on-miss。技能装好、通道配好、权限收好这套本地部署才算真正稳。
