1. 从一堆乱码 Markdown 到能检索的知识库我踩过的坑如果你和我一样电脑里躺着几百个.md文件——项目笔记、踩坑记录、临时摘抄、面试八股——那你一定懂那种写的时候爽找的时候疯的感觉。文件名从新建文本文档.md到final_v3_真的最终版.md同一个 Spring Boot 配置问题散落在五个文件里想找的时候只能靠grep硬搜搜出来还得一个个点开看哪个是最新的。纯 Java 实战用 OpenClaw 打造个人知识库核心要解决的就是这件事让程序自动扫描 Markdown 文档、提取标签、按内容归类最后形成一个能自然语言检索的本地知识库。它适合所有不想引入 Python/Node.js 依赖、只想用 Java 把这件事做干净的开发者。整套流程跑在本地文档不出机器分类和标签由模型判断你只管往inbox文件夹里丢文件。我试过用脚本按文件名分类结果发现文件名根本不可靠也试过手动维护一个索引表坚持了三天就放弃了。真正让我把这件事跑通的关键是把文档处理拆成四个独立步骤解析清洗、分类、打标签、建立关联每一步都能单独调试。下面这套方案就是按这个思路搭的全程 Java 代码OpenClaw 负责语义理解部分。在动手之前先把整体链路说清楚避免你写到一半不知道自己在干嘛inbox/*.md │ ▼ [DocumentProcessor] 解析 清洗 生成 Frontmatter │ ▼ [CategoryClassifier] 判断属于哪个分类目录 │ ▼ [TagGenerator] 提取关键词 / 技术栈 / 概念标签 │ ▼ [KnowledgeConnector] 语义相似度匹配建立文档间链接 │ ▼ knowledge-base/分类/时间戳_原名.md这条链路里OpenClaw 承担的是理解内容的部分——分类、标签、语义相似度这些用正则和关键词表做不准交给模型判断更稳。Java 承担的是工程部分——文件扫描、目录管理、并发处理、缓存去重。两者分工明确代码才好维护。2. TaoToken 前置把模型调用这件事先跑通在写业务代码之前得先解决一个现实问题OpenClaw 的语义能力从哪来。你可以本地部署模型但大多数人的笔记本跑 7B 以上的模型会很吃力分类和标签提取的质量也不稳定。更实际的做法是走 API把模型调用这部分交给稳定的服务。这里我用 TaoToken 来做模型接入层。它的作用是提供一个统一的 API 入口你不需要在代码里硬编码某一家模型的地址和密钥换模型只改配置。对个人知识库这种场景来说好处是分类用便宜快的模型、标签提取用理解力强的模型可以按需切换。先拿到 API Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 Key复制出来。这个 Key 只显示一次建议直接存到环境变量里别写死在代码里# Linux / macOS export TAOTOKEN_API_KEYsk-你的key # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的key然后确认一下你的调用地址。TaoToken 的 API 基础地址是https://taotoken.net/api兼容 OpenAI 的接口格式所以任何支持自定义 Base URL 的 SDK 都能直接用。你可以先用 curl 验证一下 Key 是否有效curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY返回一个模型列表的 JSON就说明 Key 和地址都没问题。如果返回 401检查 Key 有没有复制完整、有没有多余空格。接下来是模型选择。个人知识库的分类和标签提取不需要最强的推理模型选一个响应快、上下文够用的就行。你可以在 https://taotoken.net/models 看当前可用的模型列表记下你要用的 Model ID后面写进配置文件。这里有个容易踩的坑很多人以为 OpenClaw 是一个独立的模型其实它更像一个文档处理框架模型能力是外挂的。所以配置的时候要分两层——OpenClaw 的 gateway 地址是一层模型 API 的地址和 Key 是另一层。下面配置文件里我会把这两层分开写清楚。如果你后面打算长期跑这套知识库甚至想接 Agent 做自动整理可以了解一下 Coding Plan它适合这种持续调用、需要稳定额度的场景https://taotoken.net/coding-plan 。不过对于先跑通流程来说按量调用就够了。3. 可复制配置knowledge-config.json 与 Java 调用骨架这一节是全文的核心配置和代码都可以直接复制。先把项目结构定下来避免后面路径对不上knowledge-manager/ ├── pom.xml ├── config/ │ └── knowledge-config.json ├── inbox/ # 待处理的 Markdown └── knowledge-base/ # 整理后的知识库 ├── 技术笔记/ ├── 项目文档/ ├── 学习心得/ ├── 面试准备/ └── 工具教程/3.1 knowledge-config.json这个文件把 OpenClaw gateway 和模型 API 分开配置。注意apiKey不要写死用环境变量占位代码里读取{ openclaw: { gatewayUrl: http://localhost:18789, timeoutMs: 30000 }, model: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: 你的模型ID, maxTokens: 2048, temperature: 0.2 }, knowledgeBase: { inboxDir: ./inbox, kbDir: ./knowledge-base, categories: [技术笔记, 项目文档, 学习心得, 面试准备, 工具教程], classificationThreshold: 0.7, maxTags: 5, similarityThreshold: 0.6, maxRelatedDocs: 3 } }temperature设成 0.2 是因为分类和标签提取需要稳定输出太高的随机性会导致同一个文档两次跑出不同分类。classificationThreshold是分类置信度阈值低于这个值会归到未分类避免硬塞进错误的目录。3.2 pom.xml 依赖dependencies !-- OpenClaw Java SDK -- dependency groupIdai.openclaw/groupId artifactIdopenclaw-java-sdk/artifactId version2026.3.8/version /dependency !-- Markdown 解析 -- dependency groupIdcom.vladsch.flexmark/groupId artifactIdflexmark-all/artifactId version0.64.8/version /dependency !-- JSON 处理 -- dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.17.0/version /dependency /dependencies3.3 配置加载类package com.knowledge; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import java.io.File; public class KnowledgeConfig { public String gatewayUrl; public String modelBaseUrl; public String modelApiKey; public String modelId; public String inboxDir; public String kbDir; public double classificationThreshold; public int maxTags; public double similarityThreshold; public int maxRelatedDocs; public static KnowledgeConfig load(String path) throws Exception { ObjectMapper mapper new ObjectMapper(); JsonNode root mapper.readTree(new File(path)); KnowledgeConfig cfg new KnowledgeConfig(); cfg.gatewayUrl root.path(openclaw).path(gatewayUrl).asText(); cfg.modelBaseUrl root.path(model).path(baseUrl).asText(); cfg.modelId root.path(model).path(modelId).asText(); // 从环境变量读取 Key避免写死在配置文件 String key root.path(model).path(apiKey).asText(); if (key.startsWith(${) key.endsWith(})) { String envName key.substring(2, key.length() - 1); key System.getenv(envName); } cfg.modelApiKey key; JsonNode kb root.path(knowledgeBase); cfg.inboxDir kb.path(inboxDir).asText(); cfg.kbDir kb.path(kbDir).asText(); cfg.classificationThreshold kb.path(classificationThreshold).asDouble(0.7); cfg.maxTags kb.path(maxTags).asInt(5); cfg.similarityThreshold kb.path(similarityThreshold).asDouble(0.6); cfg.maxRelatedDocs kb.path(maxRelatedDocs).asInt(3); return cfg; } }3.4 核心处理类骨架package com.knowledge; import ai.openclaw.sdk.OpenClawClient; import ai.openclaw.sdk.config.OpenClawConfig; import java.io.File; import java.nio.file.Files; import java.util.List; public class KnowledgeManager { private final KnowledgeConfig cfg; private OpenClawClient client; private DocumentProcessor processor; private CategoryClassifier classifier; private TagGenerator tagGenerator; private KnowledgeConnector connector; public KnowledgeManager(KnowledgeConfig cfg) { this.cfg cfg; } public void init() throws Exception { // 初始化 OpenClaw 客户端指向 gateway OpenClawConfig oc new OpenClawConfig(); oc.setGatewayUrl(cfg.gatewayUrl); oc.setModelBaseUrl(cfg.modelBaseUrl); oc.setModelApiKey(cfg.modelApiKey); oc.setModelId(cfg.modelId); this.client new OpenClawClient(oc); client.connect(); this.processor new DocumentProcessor(client); this.classifier new CategoryClassifier(client, cfg.classificationThreshold); this.tagGenerator new TagGenerator(client, cfg.maxTags); this.connector new KnowledgeConnector(client, cfg.kbDir, cfg.similarityThreshold, cfg.maxRelatedDocs); createCategoryDirs(); } private void createCategoryDirs() { for (String cat : new String[]{技术笔记, 项目文档, 学习心得, 面试准备, 工具教程}) { new File(cfg.kbDir / cat).mkdirs(); } } public void processAll() throws Exception { File[] files new File(cfg.inboxDir).listFiles(f - f.getName().endsWith(.md)); if (files null || files.length 0) { System.out.println(inbox 里没有待处理的 Markdown); return; } for (File f : files) { processOne(f); } } public void processOne(File file) throws Exception { String raw processor.parseAndClean(file); String category classifier.classify(raw); ListString tags tagGenerator.generateTags(raw); ListString related connector.findRelated(raw); String doc processor.buildStandardDoc(file.getName(), raw, category, tags, related); processor.save(doc, category, file.getName()); file.delete(); System.out.println(已处理: file.getName() - category); } }3.5 分类与标签调用package com.knowledge; import ai.openclaw.sdk.OpenClawClient; import ai.openclaw.sdk.request.ClassificationRequest; import ai.openclaw.sdk.response.ClassificationResponse; public class CategoryClassifier { private final OpenClawClient client; private final double threshold; private final String[] categories {技术笔记, 项目文档, 学习心得, 面试准备, 工具教程}; public CategoryClassifier(OpenClawClient client, double threshold) { this.client client; this.threshold threshold; } public String classify(String content) throws Exception { ClassificationRequest req new ClassificationRequest(); req.setContent(content); req.setCategories(categories); req.setThreshold(threshold); ClassificationResponse resp client.execute(req); String top resp.getTopCategory(); return top null ? 未分类 : top; } }package com.knowledge; import ai.openclaw.sdk.OpenClawClient; import ai.openclaw.sdk.request.TagExtractionRequest; import ai.openclaw.sdk.response.TagExtractionResponse; import java.util.List; public class TagGenerator { private final OpenClawClient client; private final int maxTags; public TagGenerator(OpenClawClient client, int maxTags) { this.client client; this.maxTags maxTags; } public ListString generateTags(String content) throws Exception { TagExtractionRequest req new TagExtractionRequest(); req.setContent(content); req.setMaxTags(maxTags); req.setIncludeTechStack(true); req.setIncludeConcepts(true); TagExtractionResponse resp client.execute(req); return resp.getTags(); } }3.6 生成标准文档package com.knowledge; import ai.openclaw.sdk.OpenClawClient; import ai.openclaw.sdk.request.DocumentProcessRequest; import java.io.File; import java.nio.file.Files; import java.util.List; public class DocumentProcessor { private final OpenClawClient client; public DocumentProcessor(OpenClawClient client) { this.client client; } public String parseAndClean(File file) throws Exception { String content new String(Files.readAllBytes(file.toPath()), UTF-8); DocumentProcessRequest req new DocumentProcessRequest(); req.setContent(content); req.setAction(clean); req.setFormat(markdown); return client.execute(req).getProcessedContent(); } public String buildStandardDoc(String title, String content, String category, ListString tags, ListString related) throws Exception { DocumentProcessRequest req new DocumentProcessRequest(); req.setContent(content); req.setAction(summarize); req.setMaxLength(200); String summary client.execute(req).getProcessedContent(); StringBuilder sb new StringBuilder(); sb.append(---\n); sb.append(title: ).append(title.replace(.md, )).append(\n); sb.append(category: ).append(category).append(\n); sb.append(tags: ).append(String.join(, , tags)).append(\n); sb.append(summary: ).append(summary).append(\n); sb.append(created: ).append(java.time.LocalDate.now()).append(\n); sb.append(---\n\n); sb.append(content); if (!related.isEmpty()) { sb.append(\n\n## 相关文档\n); for (String doc : related) { sb.append(- [).append(doc.replace(.md, )).append(]().append(doc).append()\n); } } return sb.toString(); } public void save(String content, String category, String originalName) throws Exception { String fileName System.currentTimeMillis() _ originalName; File target new File(./knowledge-base/ category / fileName); Files.write(target.toPath(), content.getBytes(UTF-8)); } }配置和代码到这里就齐了。注意modelId和apiKey这两项前者从 https://taotoken.net/models 拿后者从 https://taotoken.net/api-keys 拿别搞混。4. 验证请求跑一次整理看目录前后对比代码写完不验证等于没写。这一节我们实际跑一次用真实的 Markdown 文件看效果。4.1 准备测试文档在inbox/里放三个不同类型的文件spring-boot-config.md# Spring Boot 多环境配置 在 application.yml 里用 spring.profiles.active 切换环境。 踩坑profile 文件命名必须是 application-{profile}.yml。interview-jvm.md# JVM 面试题整理 1. 内存模型堆、栈、方法区 2. GC 算法标记清除、复制、标记整理 3. 类加载双亲委派idea-tips.md# IDEA 常用快捷键 CtrlShiftA 查找动作 AltEnter 快速修复 CtrlAltL 格式化代码4.2 启动 gateway 并运行# 启动 OpenClaw gateway openclaw gateway start # 编译打包 mvn clean package # 运行 java -jar target/knowledge-manager.jar4.3 整理前的目录inbox/ ├── spring-boot-config.md ├── interview-jvm.md └── idea-tips.md4.4 整理后的目录knowledge-base/ ├── 技术笔记/ │ └── 1712345678901_spring-boot-config.md ├── 面试准备/ │ └── 1712345678902_interview-jvm.md └── 工具教程/ └── 1712345678903_idea-tips.md打开技术笔记/1712345678901_spring-boot-config.md头部会多出 Frontmatter--- title: spring-boot-config category: 技术笔记 tags: Spring Boot, 配置管理, application.yml, profile summary: 介绍 Spring Boot 多环境配置方式及 profile 文件命名注意事项。 created: 2026-05-20 ---标签是模型从内容里提取的profile、application.yml这些词你自己没写进标题但被识别出来了。这就是语义提取比关键词匹配强的地方。4.5 验证语义关联再放一个和 Spring Boot 相关的文档进inbox/比如spring-transaction.md重新跑一次。处理完后打开它底部会出现## 相关文档 - [spring-boot-config](../技术笔记/1712345678901_spring-boot-config.md)说明KnowledgeConnector的语义相似度匹配生效了。阈值0.6是个经验值太低会把不相关的文档也链上太高又匹配不到你可以根据自己文档的实际情况微调。4.6 用模型对话验证检索整理完之后如果你想直接问我关于 JVM 记了什么可以把知识库目录喂给模型做检索。打开 https://taotoken.net/chat 把相关文档内容贴进去提问验证一下整理后的文档是否结构清晰、信息完整。这一步不是必须的但能帮你确认 Frontmatter 和摘要生成得对不对。5. 本篇常见错排查401、local proxy failed、reading choices跑这套流程报错基本集中在几个地方。我把实际遇到过的整理出来对照着查。5.1 401 Unauthorized最常见。原因通常是三种Key 没读到、Key 复制错了、Base URL 写错了。先确认环境变量有没有生效echo $TAOTOKEN_API_KEY如果输出为空说明export没在当前终端生效重新执行一次。如果输出正常但还是 401检查knowledge-config.json里的baseUrl是不是https://taotoken.net/api注意结尾不要多加/v1SDK 内部会拼。还有一种情况是 Key 前面带了Bearer前缀。配置文件里只填 Key 本身不要带前缀SDK 会自己加。5.2 local proxy failed这个报错通常出现在 OpenClaw gateway 启动阶段提示连不上本地代理。原因是 gateway 默认监听18789端口如果这个端口被占用或者 gateway 根本没起来就会报这个。先确认 gateway 状态openclaw gateway status如果没起来重新启动openclaw gateway start如果提示端口占用换个端口同时改配置文件里的gatewayUrlopenclaw gateway start --port 18790对应knowledge-config.json改成http://localhost:18790。注意 gateway 地址和模型 API 地址是两个东西别改错。5.3 reading choices 报错这个报错说明模型返回的 JSON 结构里没有choices字段通常是模型 ID 写错了或者调用的接口不是 chat completions 格式。检查modelId是否和 https://taotoken.net/models 上列出的完全一致大小写敏感。另外确认baseUrl指向的是兼容 OpenAI 格式的接口TaoToken 的/api是兼容的但如果你手动拼了别的路径就可能出问题。5.4 OAuth 相关报错如果你用的是 Claude Code 这类工具可能会遇到 OAuth 认证失败。这类工具走的是 OAuth 流程和 API Key 是两套机制。如果你只是想跑本文的 Java 知识库用 API Key 就够了不需要配 OAuth。如果你确实在用 Claude Code 并且想接入参考 https://taotoken.net/doc 里的接入说明按文档配置 Base URL、Key、Model ID 三件套。三件套缺一不可只填 Key 不填 Base URL 是最常见的错误。5.5 分类结果不稳定同一个文档跑两次分到不同目录通常是temperature太高。把它降到0.1或0.2。另外classificationThreshold如果设得太低比如 0.3模型会在几个分类之间摇摆建议保持在 0.6 以上。5.6 标签提取出无关词maxTags设太大比如 10会逼模型凑数提取出一些边缘词。个人知识库 5 个标签足够多了反而干扰检索。如果发现标签质量差可以在TagExtractionRequest里加一个setLanguage(zh)限定中文减少英文停用词混入。6. 把知识库接进日常从手动整理到自动归档跑通上面这套流程之后你手里就有了一个能自动分类、打标签、建关联的本地知识库。但真正让它产生价值的是把它接进你的日常写作习惯。最省事的做法是设一个定时任务每天固定时间扫一次inbox。Linux/macOS 用 cron# 每天 22:00 自动整理 0 22 * * * cd /path/to/knowledge-manager java -jar target/knowledge-manager.jar logs/run.log 21Windows 用任务计划程序触发条件设成每天操作填java -jar的完整路径。如果你写文档的频率很高可以再往前一步把inbox目录设成你的编辑器默认保存目录写完直接存进去剩下的交给程序。这样你只需要专注写整理这件事完全不用管。关于模型调用这块如果你后面文档量上来了每天要处理几十上百个文件按量调用可能会比较费心。Coding Plan 适合这种持续、稳定的调用场景可以去 https://taotoken.net/coding-plan 看看额度方案。接入文档在 https://taotoken.net/doc 里面有完整的参数说明和示例。最后说一个我自己的经验知识库的价值不在于整理得多漂亮而在于你愿不愿意往里丢东西。如果整理流程太重你写文档的时候就会犹豫这个值不值得存。所以这套方案我刻意把入口做得很轻——只管往inbox丢分类、标签、关联全部自动完成。你唯一要做的就是保持写的习惯。 
长河君 · 2026/10/4 9:22:18 · 阅读 1.2k 纯Java实战：用OpenClaw打造个人知识库，自动整理Markdown文档，告别文件混乱
1. 从一堆乱码 Markdown 到能检索的知识库我踩过的坑如果你和我一样电脑里躺着几百个.md文件——项目笔记、踩坑记录、临时摘抄、面试八股——那你一定懂那种写的时候爽找的时候疯的感觉。文件名从新建文本文档.md到final_v3_真的最终版.md同一个 Spring Boot 配置问题散落在五个文件里想找的时候只能靠grep硬搜搜出来还得一个个点开看哪个是最新的。纯 Java 实战用 OpenClaw 打造个人知识库核心要解决的就是这件事让程序自动扫描 Markdown 文档、提取标签、按内容归类最后形成一个能自然语言检索的本地知识库。它适合所有不想引入 Python/Node.js 依赖、只想用 Java 把这件事做干净的开发者。整套流程跑在本地文档不出机器分类和标签由模型判断你只管往inbox文件夹里丢文件。我试过用脚本按文件名分类结果发现文件名根本不可靠也试过手动维护一个索引表坚持了三天就放弃了。真正让我把这件事跑通的关键是把文档处理拆成四个独立步骤解析清洗、分类、打标签、建立关联每一步都能单独调试。下面这套方案就是按这个思路搭的全程 Java 代码OpenClaw 负责语义理解部分。在动手之前先把整体链路说清楚避免你写到一半不知道自己在干嘛inbox/*.md │ ▼ [DocumentProcessor] 解析 清洗 生成 Frontmatter │ ▼ [CategoryClassifier] 判断属于哪个分类目录 │ ▼ [TagGenerator] 提取关键词 / 技术栈 / 概念标签 │ ▼ [KnowledgeConnector] 语义相似度匹配建立文档间链接 │ ▼ knowledge-base/分类/时间戳_原名.md这条链路里OpenClaw 承担的是理解内容的部分——分类、标签、语义相似度这些用正则和关键词表做不准交给模型判断更稳。Java 承担的是工程部分——文件扫描、目录管理、并发处理、缓存去重。两者分工明确代码才好维护。2. TaoToken 前置把模型调用这件事先跑通在写业务代码之前得先解决一个现实问题OpenClaw 的语义能力从哪来。你可以本地部署模型但大多数人的笔记本跑 7B 以上的模型会很吃力分类和标签提取的质量也不稳定。更实际的做法是走 API把模型调用这部分交给稳定的服务。这里我用 TaoToken 来做模型接入层。它的作用是提供一个统一的 API 入口你不需要在代码里硬编码某一家模型的地址和密钥换模型只改配置。对个人知识库这种场景来说好处是分类用便宜快的模型、标签提取用理解力强的模型可以按需切换。先拿到 API Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 Key复制出来。这个 Key 只显示一次建议直接存到环境变量里别写死在代码里# Linux / macOS export TAOTOKEN_API_KEYsk-你的key # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的key然后确认一下你的调用地址。TaoToken 的 API 基础地址是https://taotoken.net/api兼容 OpenAI 的接口格式所以任何支持自定义 Base URL 的 SDK 都能直接用。你可以先用 curl 验证一下 Key 是否有效curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY返回一个模型列表的 JSON就说明 Key 和地址都没问题。如果返回 401检查 Key 有没有复制完整、有没有多余空格。接下来是模型选择。个人知识库的分类和标签提取不需要最强的推理模型选一个响应快、上下文够用的就行。你可以在 https://taotoken.net/models 看当前可用的模型列表记下你要用的 Model ID后面写进配置文件。这里有个容易踩的坑很多人以为 OpenClaw 是一个独立的模型其实它更像一个文档处理框架模型能力是外挂的。所以配置的时候要分两层——OpenClaw 的 gateway 地址是一层模型 API 的地址和 Key 是另一层。下面配置文件里我会把这两层分开写清楚。如果你后面打算长期跑这套知识库甚至想接 Agent 做自动整理可以了解一下 Coding Plan它适合这种持续调用、需要稳定额度的场景https://taotoken.net/coding-plan 。不过对于先跑通流程来说按量调用就够了。3. 可复制配置knowledge-config.json 与 Java 调用骨架这一节是全文的核心配置和代码都可以直接复制。先把项目结构定下来避免后面路径对不上knowledge-manager/ ├── pom.xml ├── config/ │ └── knowledge-config.json ├── inbox/ # 待处理的 Markdown └── knowledge-base/ # 整理后的知识库 ├── 技术笔记/ ├── 项目文档/ ├── 学习心得/ ├── 面试准备/ └── 工具教程/3.1 knowledge-config.json这个文件把 OpenClaw gateway 和模型 API 分开配置。注意apiKey不要写死用环境变量占位代码里读取{ openclaw: { gatewayUrl: http://localhost:18789, timeoutMs: 30000 }, model: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, modelId: 你的模型ID, maxTokens: 2048, temperature: 0.2 }, knowledgeBase: { inboxDir: ./inbox, kbDir: ./knowledge-base, categories: [技术笔记, 项目文档, 学习心得, 面试准备, 工具教程], classificationThreshold: 0.7, maxTags: 5, similarityThreshold: 0.6, maxRelatedDocs: 3 } }temperature设成 0.2 是因为分类和标签提取需要稳定输出太高的随机性会导致同一个文档两次跑出不同分类。classificationThreshold是分类置信度阈值低于这个值会归到未分类避免硬塞进错误的目录。3.2 pom.xml 依赖dependencies !-- OpenClaw Java SDK -- dependency groupIdai.openclaw/groupId artifactIdopenclaw-java-sdk/artifactId version2026.3.8/version /dependency !-- Markdown 解析 -- dependency groupIdcom.vladsch.flexmark/groupId artifactIdflexmark-all/artifactId version0.64.8/version /dependency !-- JSON 处理 -- dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.17.0/version /dependency /dependencies3.3 配置加载类package com.knowledge; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import java.io.File; public class KnowledgeConfig { public String gatewayUrl; public String modelBaseUrl; public String modelApiKey; public String modelId; public String inboxDir; public String kbDir; public double classificationThreshold; public int maxTags; public double similarityThreshold; public int maxRelatedDocs; public static KnowledgeConfig load(String path) throws Exception { ObjectMapper mapper new ObjectMapper(); JsonNode root mapper.readTree(new File(path)); KnowledgeConfig cfg new KnowledgeConfig(); cfg.gatewayUrl root.path(openclaw).path(gatewayUrl).asText(); cfg.modelBaseUrl root.path(model).path(baseUrl).asText(); cfg.modelId root.path(model).path(modelId).asText(); // 从环境变量读取 Key避免写死在配置文件 String key root.path(model).path(apiKey).asText(); if (key.startsWith(${) key.endsWith(})) { String envName key.substring(2, key.length() - 1); key System.getenv(envName); } cfg.modelApiKey key; JsonNode kb root.path(knowledgeBase); cfg.inboxDir kb.path(inboxDir).asText(); cfg.kbDir kb.path(kbDir).asText(); cfg.classificationThreshold kb.path(classificationThreshold).asDouble(0.7); cfg.maxTags kb.path(maxTags).asInt(5); cfg.similarityThreshold kb.path(similarityThreshold).asDouble(0.6); cfg.maxRelatedDocs kb.path(maxRelatedDocs).asInt(3); return cfg; } }3.4 核心处理类骨架package com.knowledge; import ai.openclaw.sdk.OpenClawClient; import ai.openclaw.sdk.config.OpenClawConfig; import java.io.File; import java.nio.file.Files; import java.util.List; public class KnowledgeManager { private final KnowledgeConfig cfg; private OpenClawClient client; private DocumentProcessor processor; private CategoryClassifier classifier; private TagGenerator tagGenerator; private KnowledgeConnector connector; public KnowledgeManager(KnowledgeConfig cfg) { this.cfg cfg; } public void init() throws Exception { // 初始化 OpenClaw 客户端指向 gateway OpenClawConfig oc new OpenClawConfig(); oc.setGatewayUrl(cfg.gatewayUrl); oc.setModelBaseUrl(cfg.modelBaseUrl); oc.setModelApiKey(cfg.modelApiKey); oc.setModelId(cfg.modelId); this.client new OpenClawClient(oc); client.connect(); this.processor new DocumentProcessor(client); this.classifier new CategoryClassifier(client, cfg.classificationThreshold); this.tagGenerator new TagGenerator(client, cfg.maxTags); this.connector new KnowledgeConnector(client, cfg.kbDir, cfg.similarityThreshold, cfg.maxRelatedDocs); createCategoryDirs(); } private void createCategoryDirs() { for (String cat : new String[]{技术笔记, 项目文档, 学习心得, 面试准备, 工具教程}) { new File(cfg.kbDir / cat).mkdirs(); } } public void processAll() throws Exception { File[] files new File(cfg.inboxDir).listFiles(f - f.getName().endsWith(.md)); if (files null || files.length 0) { System.out.println(inbox 里没有待处理的 Markdown); return; } for (File f : files) { processOne(f); } } public void processOne(File file) throws Exception { String raw processor.parseAndClean(file); String category classifier.classify(raw); ListString tags tagGenerator.generateTags(raw); ListString related connector.findRelated(raw); String doc processor.buildStandardDoc(file.getName(), raw, category, tags, related); processor.save(doc, category, file.getName()); file.delete(); System.out.println(已处理: file.getName() - category); } }3.5 分类与标签调用package com.knowledge; import ai.openclaw.sdk.OpenClawClient; import ai.openclaw.sdk.request.ClassificationRequest; import ai.openclaw.sdk.response.ClassificationResponse; public class CategoryClassifier { private final OpenClawClient client; private final double threshold; private final String[] categories {技术笔记, 项目文档, 学习心得, 面试准备, 工具教程}; public CategoryClassifier(OpenClawClient client, double threshold) { this.client client; this.threshold threshold; } public String classify(String content) throws Exception { ClassificationRequest req new ClassificationRequest(); req.setContent(content); req.setCategories(categories); req.setThreshold(threshold); ClassificationResponse resp client.execute(req); String top resp.getTopCategory(); return top null ? 未分类 : top; } }package com.knowledge; import ai.openclaw.sdk.OpenClawClient; import ai.openclaw.sdk.request.TagExtractionRequest; import ai.openclaw.sdk.response.TagExtractionResponse; import java.util.List; public class TagGenerator { private final OpenClawClient client; private final int maxTags; public TagGenerator(OpenClawClient client, int maxTags) { this.client client; this.maxTags maxTags; } public ListString generateTags(String content) throws Exception { TagExtractionRequest req new TagExtractionRequest(); req.setContent(content); req.setMaxTags(maxTags); req.setIncludeTechStack(true); req.setIncludeConcepts(true); TagExtractionResponse resp client.execute(req); return resp.getTags(); } }3.6 生成标准文档package com.knowledge; import ai.openclaw.sdk.OpenClawClient; import ai.openclaw.sdk.request.DocumentProcessRequest; import java.io.File; import java.nio.file.Files; import java.util.List; public class DocumentProcessor { private final OpenClawClient client; public DocumentProcessor(OpenClawClient client) { this.client client; } public String parseAndClean(File file) throws Exception { String content new String(Files.readAllBytes(file.toPath()), UTF-8); DocumentProcessRequest req new DocumentProcessRequest(); req.setContent(content); req.setAction(clean); req.setFormat(markdown); return client.execute(req).getProcessedContent(); } public String buildStandardDoc(String title, String content, String category, ListString tags, ListString related) throws Exception { DocumentProcessRequest req new DocumentProcessRequest(); req.setContent(content); req.setAction(summarize); req.setMaxLength(200); String summary client.execute(req).getProcessedContent(); StringBuilder sb new StringBuilder(); sb.append(---\n); sb.append(title: ).append(title.replace(.md, )).append(\n); sb.append(category: ).append(category).append(\n); sb.append(tags: ).append(String.join(, , tags)).append(\n); sb.append(summary: ).append(summary).append(\n); sb.append(created: ).append(java.time.LocalDate.now()).append(\n); sb.append(---\n\n); sb.append(content); if (!related.isEmpty()) { sb.append(\n\n## 相关文档\n); for (String doc : related) { sb.append(- [).append(doc.replace(.md, )).append(]().append(doc).append()\n); } } return sb.toString(); } public void save(String content, String category, String originalName) throws Exception { String fileName System.currentTimeMillis() _ originalName; File target new File(./knowledge-base/ category / fileName); Files.write(target.toPath(), content.getBytes(UTF-8)); } }配置和代码到这里就齐了。注意modelId和apiKey这两项前者从 https://taotoken.net/models 拿后者从 https://taotoken.net/api-keys 拿别搞混。4. 验证请求跑一次整理看目录前后对比代码写完不验证等于没写。这一节我们实际跑一次用真实的 Markdown 文件看效果。4.1 准备测试文档在inbox/里放三个不同类型的文件spring-boot-config.md# Spring Boot 多环境配置 在 application.yml 里用 spring.profiles.active 切换环境。 踩坑profile 文件命名必须是 application-{profile}.yml。interview-jvm.md# JVM 面试题整理 1. 内存模型堆、栈、方法区 2. GC 算法标记清除、复制、标记整理 3. 类加载双亲委派idea-tips.md# IDEA 常用快捷键 CtrlShiftA 查找动作 AltEnter 快速修复 CtrlAltL 格式化代码4.2 启动 gateway 并运行# 启动 OpenClaw gateway openclaw gateway start # 编译打包 mvn clean package # 运行 java -jar target/knowledge-manager.jar4.3 整理前的目录inbox/ ├── spring-boot-config.md ├── interview-jvm.md └── idea-tips.md4.4 整理后的目录knowledge-base/ ├── 技术笔记/ │ └── 1712345678901_spring-boot-config.md ├── 面试准备/ │ └── 1712345678902_interview-jvm.md └── 工具教程/ └── 1712345678903_idea-tips.md打开技术笔记/1712345678901_spring-boot-config.md头部会多出 Frontmatter--- title: spring-boot-config category: 技术笔记 tags: Spring Boot, 配置管理, application.yml, profile summary: 介绍 Spring Boot 多环境配置方式及 profile 文件命名注意事项。 created: 2026-05-20 ---标签是模型从内容里提取的profile、application.yml这些词你自己没写进标题但被识别出来了。这就是语义提取比关键词匹配强的地方。4.5 验证语义关联再放一个和 Spring Boot 相关的文档进inbox/比如spring-transaction.md重新跑一次。处理完后打开它底部会出现## 相关文档 - [spring-boot-config](../技术笔记/1712345678901_spring-boot-config.md)说明KnowledgeConnector的语义相似度匹配生效了。阈值0.6是个经验值太低会把不相关的文档也链上太高又匹配不到你可以根据自己文档的实际情况微调。4.6 用模型对话验证检索整理完之后如果你想直接问我关于 JVM 记了什么可以把知识库目录喂给模型做检索。打开 https://taotoken.net/chat 把相关文档内容贴进去提问验证一下整理后的文档是否结构清晰、信息完整。这一步不是必须的但能帮你确认 Frontmatter 和摘要生成得对不对。5. 本篇常见错排查401、local proxy failed、reading choices跑这套流程报错基本集中在几个地方。我把实际遇到过的整理出来对照着查。5.1 401 Unauthorized最常见。原因通常是三种Key 没读到、Key 复制错了、Base URL 写错了。先确认环境变量有没有生效echo $TAOTOKEN_API_KEY如果输出为空说明export没在当前终端生效重新执行一次。如果输出正常但还是 401检查knowledge-config.json里的baseUrl是不是https://taotoken.net/api注意结尾不要多加/v1SDK 内部会拼。还有一种情况是 Key 前面带了Bearer前缀。配置文件里只填 Key 本身不要带前缀SDK 会自己加。5.2 local proxy failed这个报错通常出现在 OpenClaw gateway 启动阶段提示连不上本地代理。原因是 gateway 默认监听18789端口如果这个端口被占用或者 gateway 根本没起来就会报这个。先确认 gateway 状态openclaw gateway status如果没起来重新启动openclaw gateway start如果提示端口占用换个端口同时改配置文件里的gatewayUrlopenclaw gateway start --port 18790对应knowledge-config.json改成http://localhost:18790。注意 gateway 地址和模型 API 地址是两个东西别改错。5.3 reading choices 报错这个报错说明模型返回的 JSON 结构里没有choices字段通常是模型 ID 写错了或者调用的接口不是 chat completions 格式。检查modelId是否和 https://taotoken.net/models 上列出的完全一致大小写敏感。另外确认baseUrl指向的是兼容 OpenAI 格式的接口TaoToken 的/api是兼容的但如果你手动拼了别的路径就可能出问题。5.4 OAuth 相关报错如果你用的是 Claude Code 这类工具可能会遇到 OAuth 认证失败。这类工具走的是 OAuth 流程和 API Key 是两套机制。如果你只是想跑本文的 Java 知识库用 API Key 就够了不需要配 OAuth。如果你确实在用 Claude Code 并且想接入参考 https://taotoken.net/doc 里的接入说明按文档配置 Base URL、Key、Model ID 三件套。三件套缺一不可只填 Key 不填 Base URL 是最常见的错误。5.5 分类结果不稳定同一个文档跑两次分到不同目录通常是temperature太高。把它降到0.1或0.2。另外classificationThreshold如果设得太低比如 0.3模型会在几个分类之间摇摆建议保持在 0.6 以上。5.6 标签提取出无关词maxTags设太大比如 10会逼模型凑数提取出一些边缘词。个人知识库 5 个标签足够多了反而干扰检索。如果发现标签质量差可以在TagExtractionRequest里加一个setLanguage(zh)限定中文减少英文停用词混入。6. 把知识库接进日常从手动整理到自动归档跑通上面这套流程之后你手里就有了一个能自动分类、打标签、建关联的本地知识库。但真正让它产生价值的是把它接进你的日常写作习惯。最省事的做法是设一个定时任务每天固定时间扫一次inbox。Linux/macOS 用 cron# 每天 22:00 自动整理 0 22 * * * cd /path/to/knowledge-manager java -jar target/knowledge-manager.jar logs/run.log 21Windows 用任务计划程序触发条件设成每天操作填java -jar的完整路径。如果你写文档的频率很高可以再往前一步把inbox目录设成你的编辑器默认保存目录写完直接存进去剩下的交给程序。这样你只需要专注写整理这件事完全不用管。关于模型调用这块如果你后面文档量上来了每天要处理几十上百个文件按量调用可能会比较费心。Coding Plan 适合这种持续、稳定的调用场景可以去 https://taotoken.net/coding-plan 看看额度方案。接入文档在 https://taotoken.net/doc 里面有完整的参数说明和示例。最后说一个我自己的经验知识库的价值不在于整理得多漂亮而在于你愿不愿意往里丢东西。如果整理流程太重你写文档的时候就会犹豫这个值不值得存。所以这套方案我刻意把入口做得很轻——只管往inbox丢分类、标签、关联全部自动完成。你唯一要做的就是保持写的习惯。