尧图网页设计 
1. CodeBot 是什么OpenCode 之上的 AI 助手兼容 Hermes 与 ObsidianCodeBot 是一个跑在本地、以 OpenCode 为执行内核的 AI 助手它把「模型对话」「技能调用」「知识库读写」「定时任务」这几件事收拢到一个聊天界面里。你可以把它理解成一层薄适配层底层真正干活的是 OpenCode CLI 和 Hermes CLICodeBot 负责把模型网关、记忆库、技能目录、Obsidian 路径这些共享配置写进去再启动子进程把终端输出持续追加到当前聊天气泡。它适合谁适合已经在用 OpenCode 做编码、同时希望把 Hermes Agent 和 Obsidian 知识库串进同一条工作流的人尤其是需要「提问—检索—回写」闭环的知识工作者。我关注它主要因为 4.3.0 这次更新覆盖了 v3.6.0 到 v4.3.0 的累积变更包含 11 个大章节其中 Hermes Agent 深度集成和 Obsidian 知识库集成是两条主线。Hermes 接入从 Gateway 收敛为 CLI oneshot聊天里选中 Hermes 后由 CodeBot 调用hermes -z执行入口切换为 Hermes 官方--cli chat -q单次查询路径。这意味着你不再需要导入 Hermes 内部 Agent 类也不用维护自定义 runnerCodeBot 只做三件事写共享配置、起子进程、把 stdout 追加到气泡。Obsidian 这边设置页的 Obsidian 标签支持配置默认 Vault 路径与多个知识库路径聊天页通过#可多选知识库。CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill 去完成检索、模板调用、读取、写入、移动与 wiki-link 安全操作不会把知识库先转成向量库。这一点对知识工作者很关键你的双链、标签、模板都还在AI 只是多了一双手。模型管理上聊天页模型刷新会优先调用opencode models与 OpenCode CLI 的最新模型列表保持一致。如果 CodeBot 进程 PATH 与终端不同可以在config.json的opencode.cli_path填写 opencode 可执行文件或所在目录也可以设置环境变量CODEBOT_OPENCODE_PATH。Windows 桌面端还会额外自动探测%APPDATA%\npm、Scoop shim、WinGet Links、Chocolatey bin 等常见 CLI 安装位置。这些细节决定了你第一次跑通时会不会卡在「找不到 opencode」上。对话级状态独立也值得单独说每个普通对话会独立保存当前模式、模型、Hermes/Obsidian 目标和已选知识库。在 B 对话切换模型或处理目标不会覆盖 A 对话原来的选择。新建对话仍会沿用最近主动选择的全局默认模型创建后再形成自己的独立状态。这个设计对同时开多个知识库、多个模型对比的场景非常友好。定时任务会持久化executor字段。聊天中选择 Hermes 后沉淀的任务、成长候选接受后的任务和手动编辑为 Hermes 的任务到点执行时会调用 Hermes CLI选择 OpenCode 或未指定时走 OpenCode。聊天中创建定时任务时会把当时选择的主模型保存为任务的execution_model任务执行前会检查该模型是否仍在当前可用模型列表中如果模型过时或供应商不再提供会自动回退到「记忆 → 自动整理 → 整理使用模型」。流式链路采用prompt_async/global/event可实时看到工具调用与文本增量。前端按事件实时追加渲染步骤/工具事件逐条显示正文增量分块刷新不等待最终完成。从「技能/设置」等页面返回聊天页后会自动恢复当前对话的「处理中/排队中」状态并在任务结束后自动刷新最新消息。后台事件回放与数据库最终消息会做去重收敛避免同一回复先流式出现后又重复插入一次。记忆系统这次也补了不少聊天中手动「记住」时会优先识别偏好和习惯再识别联系方式和地址最后才判断个人信息避免使用偏好被误归为个人信息或联系人。AI 自动提取记忆时系统提示词包含严格的分类边界定义和示例。打开活跃记忆列表时会将生日类事实记忆自动补齐到长期记忆避免「有事实但列表为空」。删除带memory_key/fact_key的长期记忆时会同步归档对应事实。CodeBot 还提供 OpenAI 兼容接口GET /v1/models和POST /v1/chat/completions。使用前请先请求/v1/models从返回结果里的id选择当前真实可用的模型。如果直接调用 HTTP 接口而不是 OpenAI SDKmodel字段可以省略此时后端会优先使用记忆自动整理模型memory.organize_model若未设置则回退到聊天页默认模型。连接状态方面聊天页顶部会显示 OpenCode / Bridge / MCP 代理状态并支持手动刷新连接与模型列表。桌面端启动后端时会自动尝试拉起 OpenCode 服务并统一优先使用127.0.0.1:11200。npm start开发模式也会跟正式版一样优先连到 11200避免误起另一套 dev server。如需覆盖默认值可设置环境变量CODEBOT_OPENCODE_PREFERRED_PORT与CODEBOT_OPENCODE_FALLBACK_PORT。分享与归档点击左侧对话更多菜单里的「分享」后系统会生成/share/{share_id}只读页面并复制基于局域网地址的链接。分享页面只展示对话内容不提供继续发送消息、删除或修改能力。点击「归档」后对话仍保存在data/conversations.db中conversations.is_archived会被设置为 1。归档后的对话不会显示在聊天页左侧普通对话列表中可在「日志」页的「已归档对话」标签中查看、搜索和恢复。自动沉淀技能仅在复杂任务场景触发过滤寒暄类和系统提示词污染内容避免生成无意义技能。聊天页点击「生成技能」后后端会先调用find-skills搜索并评估现有 skill当最佳结果与需求差异小于 40%即相似度至少 60%时CodeBot 会基于该 skill 改造并保存否则会继续调用skill-creator创建新 skill。最终产物统一迁移或写入skills/auto_*在技能页中归类为「自动生成」。2. 前置准备TaoToken 模型网关与 CodeBot 环境在跑通 CodeBot 之前你需要先解决模型来源问题。CodeBot 本身不绑定某一家模型它通过 OpenAI 兼容网关去调用模型。我实测下来用 TaoToken 作为模型网关比较省事因为它提供 OpenAI 兼容接口CodeBot 的opencode.json里直接填 Base URL 和 Key 就能用。TaoToken 官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接写这个。你需要准备的东西一个 TaoToken 账号并在控制台创建一个 API Key。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite本地已安装 Node.js建议 18和 npm。本地已安装 OpenCode CLI。如果没装可以用 npm 全局安装具体命令参考 OpenCode 官方文档。本地已安装 Hermes CLI。Hermes 的安装方式参考其官方说明CodeBot 只负责调用hermes命令。Obsidian 已安装并且你有一个或多个 Vault 路径。关于 API Key 的获取你可以直接访问 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建。创建后复制 Key后面配置里会用到。CodeBot 的安装方式如果你是从源码跑通常是git clone codebot-repo cd codebot npm install npm start如果你用的是桌面端安装包直接安装后启动即可。桌面端启动后端时会自动尝试拉起 OpenCode 服务并统一优先使用127.0.0.1:11200。如果系统里已经有 OpenCode 桌面端或opencode serve在运行CodeBot 会直接复用现有健康服务并跳过额外安装检查。这里有个坑我踩过CodeBot 进程的 PATH 和你的终端 PATH 可能不一致。如果你在终端里能跑opencode但 CodeBot 里模型刷新失败大概率是 PATH 问题。解决办法是在config.json的opencode.cli_path填写 opencode 可执行文件或所在目录或者设置环境变量CODEBOT_OPENCODE_PATH。Windows 桌面端还会额外自动探测%APPDATA%\npm、Scoop shim、WinGet Links、Chocolatey bin 等常见 CLI 安装位置但如果你用的是自定义安装路径还是手动指定更稳。另一个前置是 Hermes CLI 的可用性。CodeBot 4.3.0 之后Hermes 接入从 Gateway 收敛为 CLI oneshot聊天中选择 Hermes 后由 CodeBot 调用hermes -z。执行入口已从顶层hermes -z/--oneshot切换为 Hermes 官方--cli chat -q单次查询路径。所以你需要确保hermes命令在 PATH 里可执行并且版本支持--cli chat -q。Obsidian 这边你需要在 CodeBot 设置页的 Obsidian 标签里配置默认 Vault 路径与多个知识库路径。CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill。所以你也需要确保obsidian-cli可用或者至少 Obsidian 的 Vault 路径可读写。关于模型网关的配置CodeBot 自己拉起 OpenCode Server 时会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json并通过OPENCODE_CONFIG_HOMEdata/opencode-config启动 OpenCode。这意味着你可以在全局opencode.json里配置 TaoToken 的 providerCodeBot 会自动合并。如果你还没有配置过 OpenCode 的 provider可以参考 TaoToken 的接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有 OpenAI 兼容接口的详细说明。最后如果你打算长期用 CodeBot 做编码或 Agent 任务可以考虑 TaoToken 的 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要稳定模型调用的场景。3. 可复制配置opencode.json、config.json 与 Hermes/Obsidian 参数这一节给出可以直接复制的配置片段。路径和原文一致你按自己的实际路径替换即可。3.1 OpenCode provider 配置opencode.jsonCodeBot 自己拉起 OpenCode Server 时会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json并通过OPENCODE_CONFIG_HOMEdata/opencode-config启动 OpenCode。所以推荐你在全局~/.config/opencode/opencode.json里配置 TaoToken provider。{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey }, models: { claude-sonnet-4-20250514: { name: Claude Sonnet 4 }, gpt-4.1: { name: GPT-4.1 } } } }, model: taotoken/claude-sonnet-4-20250514 }注意baseURL写https://taotoken.net/api不要加 UTM 参数。apiKey填你在 TaoToken 控制台创建的 Key。models里的模型 ID 需要是 TaoToken 实际支持的模型你可以先请求GET /v1/models确认。如果你不想改全局配置也可以直接在 CodeBot 的data/opencode-config/opencode.json里写同样的内容。但注意 CodeBot 启动时会合并全局配置所以全局配置优先级更高。3.2 CodeBot config.json 配置CodeBot 的config.json里可以配置 OpenCode CLI 路径、Obsidian Vault 路径、Hermes 相关参数等。以下是一个示例{ opencode: { cli_path: /usr/local/bin/opencode, preferred_port: 11200, fallback_port: 11201 }, obsidian: { default_vault: /Users/yourname/Documents/ObsidianVault, vaults: [ /Users/yourname/Documents/ObsidianVault, /Users/yourname/Documents/KnowledgeBase ] }, hermes: { cli_path: /usr/local/bin/hermes, skill_dirs: [ /Users/yourname/.hermes/skills, /Users/yourname/Documents/ObsidianVault/.skills ] }, memory: { organize_model: taotoken/claude-sonnet-4-20250514 } }opencode.cli_path填 opencode 可执行文件或所在目录。如果你在终端里能跑opencode但 CodeBot 里模型刷新失败大概率是 PATH 问题这里手动指定即可。Windows 桌面端还会额外自动探测%APPDATA%\npm、Scoop shim、WinGet Links、Chocolatey bin 等常见 CLI 安装位置但自定义路径还是手动指定更稳。obsidian.default_vault和obsidian.vaults填你的 Obsidian Vault 路径。CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill 去完成检索、模板调用、读取、写入、移动与 wiki-link 安全操作不会把知识库先转成向量库。hermes.cli_path填 hermes 可执行文件路径。hermes.skill_dirs填 Hermes Skill 目录。CodeBot 会把 Hermes Agent 自身默认可发现的 skill 目录、用户手动配置的 Hermes Skill 目录、CodeBot 内置/自动生成 skills 目录、以及 OpenCode CLI skill roots 一起并入 Hermes 的有效skills.external_dirs。memory.organize_model填记忆自动整理使用的模型。如果定时任务的execution_model过时或供应商不再提供会自动回退到这个模型。3.3 Hermes 接入参数Hermes 已从 Gateway 收敛为 CLI oneshot聊天中选择 Hermes 后由 CodeBot 调用hermes -z。CodeBot 只作为薄适配层写入共享配置模型网关、记忆库、定时任务库、技能目录和 Obsidian 路径启动 Hermes CLI 子进程把终端输出持续追加到当前聊天气泡。重构后的 Hermes 接入不再导入 Hermes 内部 Agent 类也不再依赖自定义 runner。聊天执行入口已从顶层hermes -z/--oneshot切换为 Hermes 官方--cli chat -q单次查询路径。当 CLI 明确要求确认、继续、密码、密钥或输入时会在聊天页显示交互面板并把用户回答写回 Hermes stdin。Hermes 不要求用户单独配置模型聊天主模型跟随当前聊天模型后台辅助模型跟随「记忆 → 自动整理 → 整理使用模型」。如果你需要手动测试 Hermes CLI 是否可用可以运行hermes --cli chat -q 你好如果这条命令能正常返回说明 Hermes CLI 配置正确。3.4 Obsidian 接入参数设置页中的 Obsidian 标签支持配置默认 Vault 路径与多个知识库路径。聊天页通过#可多选知识库。CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill 去完成检索、模板调用、读取、写入、移动与 wiki-link 安全操作不会把知识库先转成向量库。聊天输入框中的会搜索全部技能来源包括 CodeBot 内置/自动生成、OpenCode、Hermes Agent 与 OpenClaw支持描述、单词和多词搜索。聊天输入框中的/会搜索 OpenCode CLI 命令并支持按描述、单词和多词进行匹配。如果你需要手动测试 obsidian-cli 是否可用可以运行obsidian-cli --version如果这条命令能正常返回说明 obsidian-cli 配置正确。4. 验证请求从提问到结果回写 Obsidian配置完成后你需要做一次完整的验证从提问开始经过模型调用和知识库检索最后把结果回写到 Obsidian。这一节给出可跟做的步骤。4.1 启动 CodeBot 并检查连接状态启动 CodeBot 后聊天页顶部会显示 OpenCode / Bridge / MCP 代理状态并支持手动刷新连接与模型列表。你先点击刷新确认三个状态都是绿色或正常。如果 OpenCode 状态异常检查opencode.cli_path是否正确或者环境变量CODEBOT_OPENCODE_PATH是否设置。桌面端启动后端时会自动尝试拉起 OpenCode 服务并统一优先使用127.0.0.1:11200。npm start开发模式也会跟正式版一样优先连到 11200避免误起另一套 dev server。如需覆盖默认值可设置环境变量CODEBOT_OPENCODE_PREFERRED_PORT与CODEBOT_OPENCODE_FALLBACK_PORT。如果 Bridge 或 MCP 状态异常检查对应服务是否启动。4.2 刷新模型列表聊天页模型刷新会优先调用opencode models与 OpenCode CLI 的最新模型列表保持一致。点击刷新后你应该能看到taotoken/claude-sonnet-4-20250514等模型。如果模型列表为空先确认~/.config/opencode/opencode.json里的 provider 配置是否正确然后确认 TaoToken API Key 是否有效。你可以直接请求GET https://taotoken.net/api/v1/models验证 Keycurl -H Authorization: Bearer sk-你的TaoTokenKey https://taotoken.net/api/v1/models如果返回模型列表说明 Key 有效。如果返回 401说明 Key 无效或过期。4.3 选择 Hermes 模式并提问在聊天页选择 Hermes 模式然后选择一个 Obsidian 知识库通过#多选。接着输入一个问题例如请检索我的 Obsidian 知识库中关于「流式响应」的笔记总结要点并写一篇新的笔记到「AI 助手」文件夹。发送后CodeBot 会调用hermes -z启动 Hermes CLI 子进程。如果 CLI 长时间暂时没有正文输出CodeBot 会在聊天窗口中持续映射 Hermes 运行状态包括session.status启动状态、session.trace运行轨迹以及非阻塞的session.idle后台心跳。明显像「加载 skill / 调用 tool / 扫描资源 / 运行步骤」的 Hermes 行优先归类成可见的「工具调用」事件其余普通说明继续归类为「运行轨迹」。针对「启动后长时间 0 输出但同消息重试可成功」的间歇性卡死CodeBot 会在 Hermes 启动后连续 90 秒仍无任何 stdout 时自动重试 1 次。4.4 观察流式响应与工具调用流式链路采用prompt_async/global/event可实时看到工具调用与文本增量。前端按事件实时追加渲染步骤/工具事件逐条显示正文增量分块刷新不等待最终完成。为避免浏览器渲染被单次大量事件阻塞前端会在流式消费中定期让出事件循环并将文本增量按帧合并刷新。你应该能看到 Hermes 调用obsidian-cli检索笔记、读取内容、然后写入新笔记的过程。如果 Hermes 输出里有 ANSI 控制序列、Rich 边框、Resume this session/session_id/Session等终端辅助行CodeBot 会过滤掉。4.5 验证结果回写任务完成后打开 Obsidian检查「AI 助手」文件夹下是否生成了新笔记。如果生成了说明从提问到结果回写的闭环跑通了。如果没生成检查以下几点Hermes 是否有写入权限。CodeBot 会写入共享配置模型网关、记忆库、定时任务库、技能目录和 Obsidian 路径但实际写入操作由 Hermes 调用obsidian-cli完成。Obsidian Vault 路径是否正确。设置页中的 Obsidian 标签支持配置默认 Vault 路径与多个知识库路径。obsidian-cli是否可用。CodeBot 会优先引导调用obsidian-cli与相关 Obsidian skill。4.6 验证对话级状态独立在 A 对话选择 Hermes 模式和知识库 A在 B 对话选择 OpenCode 模式和知识库 B。然后在 B 对话切换模型回到 A 对话确认 A 对话的模型和知识库选择没有被覆盖。每个普通对话会独立保存当前模式、模型、Hermes/Obsidian 目标和已选知识库。在 B 对话切换模型或处理目标不会覆盖 A 对话原来的选择。新建对话仍会沿用最近主动选择的全局默认模型创建后再形成自己的独立状态。4.7 验证定时任务执行器绑定在聊天中选择 Hermes 后创建一个定时任务例如「每天 10 点提醒我整理 Obsidian 收件箱」。然后到定时任务页查看确认executor字段是hermes。定时任务会持久化executor字段。聊天中选择 Hermes 后沉淀的任务、成长候选接受后的任务和手动编辑为 Hermes 的任务到点执行时会调用 Hermes CLI选择 OpenCode 或未指定时走 OpenCode。聊天中创建定时任务时会把当时选择的主模型保存为任务的execution_model任务执行前会检查该模型是否仍在当前可用模型列表中如果模型过时或供应商不再提供会自动回退到「记忆 → 自动整理 → 整理使用模型」。在「定时任务」编辑窗口中可以为任务重新选择可用模型。4.8 验证 OpenAI 兼容接口CodeBot 提供 OpenAI 兼容接口GET /v1/models和POST /v1/chat/completions。你可以直接请求验证curl http://127.0.0.1:11200/v1/models使用前请先请求/v1/models从返回结果里的id选择当前真实可用的模型。如果直接调用 HTTP 接口而不是 OpenAI SDKmodel字段可以省略此时后端会优先使用记忆自动整理模型memory.organize_model若未设置则回退到聊天页默认模型。curl -X POST http://127.0.0.1:11200/v1/chat/completions \ -H Content-Type: application/json \ -d { messages: [{role: user, content: 你好}] }如果返回正常说明 OpenAI 兼容接口可用。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给出排查路径。你遇到问题时先看报错关键词再按对应步骤检查。5.1 401 Unauthorized报错示例Error: 401 Unauthorized原因TaoToken API Key 无效或过期或者opencode.json里的apiKey字段没有正确填写。排查步骤先确认~/.config/opencode/opencode.json里的apiKey字段是否填了正确的 Key。然后直接用 curl 验证curl -H Authorization: Bearer sk-你的TaoTokenKey https://taotoken.net/api/v1/models如果返回 401说明 Key 无效。到 TaoToken 控制台重新创建 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite如果 curl 返回正常但 CodeBot 里仍然 401检查 CodeBot 是否合并了全局配置。CodeBot 自己拉起 OpenCode Server 时会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json并通过OPENCODE_CONFIG_HOMEdata/opencode-config启动 OpenCode。如果data/opencode-config/opencode.json里有旧的 provider 配置可能会覆盖全局配置。你可以直接编辑data/opencode-config/opencode.json确保apiKey正确。5.2 local proxy failed报错示例local proxy failed: connect ECONNREFUSED 127.0.0.1:11200原因CodeBot 无法连接到 OpenCode Server或者 OpenCode Server 没有启动。排查步骤先确认 OpenCode Server 是否在运行。桌面端启动后端时会自动尝试拉起 OpenCode 服务并统一优先使用127.0.0.1:11200。如果系统里已经有 OpenCode 桌面端或opencode serve在运行CodeBot 会直接复用现有健康服务并跳过额外安装检查。你可以手动检查端口curl http://127.0.0.1:11200/health如果返回连接拒绝说明 OpenCode Server 没启动。你可以手动启动opencode serve --port 11200如果端口被占用可以设置环境变量CODEBOT_OPENCODE_PREFERRED_PORT与CODEBOT_OPENCODE_FALLBACK_PORT覆盖默认值。另外检查opencode.cli_path是否正确。如果 CodeBot 进程 PATH 与终端不同可以在config.json的opencode.cli_path填写 opencode 可执行文件或所在目录也可以设置环境变量CODEBOT_OPENCODE_PATH。5.3 reading choices报错示例Error: reading choices: unexpected end of JSON input原因模型返回的流式响应格式异常或者网络中断导致 JSON 不完整。排查步骤先确认模型网关是否稳定。你可以直接请求 TaoToken 的 OpenAI 兼容接口验证curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 你好}], stream: true }如果返回正常说明网关没问题。如果返回异常检查模型 ID 是否正确。使用前请先请求/v1/models从返回结果里的id选择当前真实可用的模型。如果网关正常但 CodeBot 里仍然报reading choices检查流式链路。流式链路采用prompt_async/global/event可实时看到工具调用与文本增量。如果前端渲染被单次大量事件阻塞可能会出现 JSON 解析异常。你可以尝试减少单次请求的复杂度或者重启 CodeBot。5.4 OAuth 相关报错报错示例Error: OAuth token expired原因如果你使用的是需要 OAuth 的模型供应商token 过期会导致报错。但如果你用的是 TaoToken 的 API Key不应该出现 OAuth 报错。排查步骤先确认opencode.json里配置的是apiKey而不是 OAuth。TaoToken 使用 API Key 认证不需要 OAuth。如果你之前配置过其他供应商的 OAuth检查~/.config/opencode/opencode.json里是否有残留的 OAuth 配置。CodeBot 自己拉起 OpenCode Server 时会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json。如果全局配置里有 OAuth provider可能会干扰。你可以直接编辑data/opencode-config/opencode.json移除不需要的 provider。5.5 Hermes 启动后长时间 0 输出报错示例Hermes 启动后 90 秒无 stdout原因Hermes CLI 启动后卡住可能是 skill 加载或资源扫描阻塞。排查步骤CodeBot 会在 Hermes 启动后连续 90 秒仍无任何 stdout 时自动重试 1 次。如果重试后仍然卡住检查 Hermes 的 skill 目录。Hermes 的 skill 共享模型统一收敛为「目录共享」CodeBot 会把 Hermes Agent 自身默认可发现的 skill 目录、用户手动配置的 Hermes Skill 目录、CodeBot 内置/自动生成 skills 目录、以及 OpenCode CLI skill roots 一起并入 Hermes 的有效skills.external_dirs。对于「显式点名且来源于 OpenCode 共享目录」的 skillCodeBot 会先检测 Hermes 兼容分流运行时证据表明某些 OpenCode-shared skill 会在 Hermes 子进程中长期静默卡住因此这类请求会透明切换到 OpenCode 原生执行链。你可以手动运行 Hermes CLI 测试hermes --cli chat -q 你好如果这条命令也卡住说明 Hermes 本身有问题检查 Hermes 安装和 skill 目录。5.6 Obsidian 写入失败报错示例Error: obsidian-cli write failed原因obsidian-cli不可用或者 Vault 路径没有写入权限。排查步骤先确认obsidian-cli可用obsidian-cli --version然后确认 Vault 路径可写。设置页中的 Obsidian 标签支持配置默认 Vault 路径与多个知识库路径。CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill 去完成检索、模板调用、读取、写入、移动与 wiki-link 安全操作不会把知识库先转成向量库。如果obsidian-cli不可用检查是否安装并加入 PATH。5.7 模型列表为空报错示例模型刷新后列表为空原因opencode models调用失败或者 provider 配置错误。排查步骤聊天页模型刷新会优先调用opencode models与 OpenCode CLI 的最新模型列表保持一致。你可以手动运行opencode models如果返回为空检查~/.config/opencode/opencode.json里的 provider 配置。确认baseURL是https://taotoken.net/apiapiKey正确。如果opencode models正常但 CodeBot 里为空检查opencode.cli_path是否正确。如果 CodeBot 进程 PATH 与终端不同可以在config.json的opencode.cli_path填写 opencode 可执行文件或所在目录也可以设置环境变量CODEBOT_OPENCODE_PATH。Windows 桌面端还会额外自动探测%APPDATA%\npm、Scoop shim、WinGet Links、Chocolatey bin 等常见 CLI 安装位置。5.8 定时任务不执行报错示例定时任务到点未执行原因executor字段配置错误或者execution_model过时。排查步骤定时任务会持久化executor字段。聊天中选择 Hermes 后沉淀的任务、成长候选接受后的任务和手动编辑为 Hermes 的任务到点执行时会调用 Hermes CLI选择 OpenCode 或未指定时走 OpenCode。聊天中创建定时任务时会把当时选择的主模型保存为任务的execution_model任务执行前会检查该模型是否仍在当前可用模型列表中如果模型过时或供应商不再提供会自动回退到「记忆 → 自动整理 → 整理使用模型」。在「定时任务」编辑窗口中可以为任务重新选择可用模型。如果任务不执行检查executor字段和execution_model字段。你可以在定时任务页编辑任务重新选择模型。5.9 分享链接无法访问报错示例分享链接打开后 404原因分享页面生成失败或者局域网地址不可达。排查步骤点击左侧对话更多菜单里的「分享」后系统会生成/share/{share_id}只读页面并复制基于局域网地址的链接。分享页面只展示对话内容不提供继续发送消息、删除或修改能力。如果链接无法访问检查 CodeBot 服务是否在运行以及局域网地址是否正确。你可以手动访问http://127.0.0.1:11200/share/{share_id}测试。5.10 归档对话找不到报错示例归档后对话消失原因归档后的对话不会显示在聊天页左侧普通对话列表中。排查步骤点击「归档」后对话仍保存在data/conversations.db中conversations.is_archived会被设置为 1。归档后的对话不会显示在聊天页左侧普通对话列表中可在「日志」页的「已归档对话」标签中查看、搜索和恢复。如果你需要恢复归档对话到「日志」页的「已归档对话」标签中操作。6. 把 CodeBot 接进你的知识工作流模型对话、Coding Plan 与接入文档CodeBot 跑通之后你可以把它接进日常的知识工作流。这里给出几个方向以及对应的 TaoToken 资源。如果你主要是做知识库问答和笔记整理用 Hermes Obsidian 模式就够了。聊天页通过#可多选知识库CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill 去完成检索、模板调用、读取、写入、移动与 wiki-link 安全操作不会把知识库先转成向量库。你可以直接问「检索我的 Obsidian 知识库中关于 X 的笔记总结要点」然后让 Hermes 把结果写回指定文件夹。如果你主要是做编码和 Agent 任务用 OpenCode 模式。聊天页模型刷新会优先调用opencode models与 OpenCode CLI 的最新模型列表保持一致。你可以用 CodeBot 做代码生成、重构、排错也可以创建定时任务做自动化。如果你需要长期稳定的模型调用可以考虑 TaoToken 的 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要长期编码或 Agent 任务的场景。如果你需要验证模型是否可用可以直接用 TaoToken 的模型对话功能https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。在配置 CodeBot 之前先用模型对话确认模型可用可以省去很多排查时间。如果你需要创建 API Key到控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后复制 Key填到opencode.json的apiKey字段。如果你需要查看接入文档到https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有 OpenAI 兼容接口的详细说明包括GET /v1/models和POST /v1/chat/completions的用法。如果你用的是 Claude Code 或 Anthropic 风格的接入可以参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。CodeBot 的 OpenAI 兼容接口也支持类似用法。最后如果你需要直接调用 API地址是 https://taotoken.net/api 。注意这个地址不带 UTM 参数配置时直接写这个。CodeBot 的 4.3.0 版本把 Hermes 和 Obsidian 两条线都补得比较完整了。Hermes 接入从 Gateway 收敛为 CLI oneshot执行入口切换为 Hermes 官方--cli chat -q单次查询路径。Obsidian 支持多知识库聊天页通过#可多选知识库。模型管理上聊天页模型刷新会优先调用opencode models。对话级状态独立每个普通对话会独立保存当前模式、模型、Hermes/Obsidian 目标和已选知识库。定时任务会持久化executor字段支持 Hermes 和 OpenCode 两种执行器。我实测下来最容易卡住的地方是 PATH 和 provider 配置。如果你在终端里能跑opencode但 CodeBot 里模型刷新失败大概率是 PATH 问题。解决办法是在config.json的opencode.cli_path填写 opencode 可执行文件或所在目录或者设置环境变量CODEBOT_OPENCODE_PATH。Windows 桌面端还会额外自动探测%APPDATA%\npm、Scoop shim、WinGet Links、Chocolatey bin 等常见 CLI 安装位置。另一个容易忽略的是data/opencode-config/opencode.json和全局~/.config/opencode/opencode.json的合并关系。CodeBot 自己拉起 OpenCode Server 时会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json并通过OPENCODE_CONFIG_HOMEdata/opencode-config启动 OpenCode。如果data/opencode-config/opencode.json里有旧的 provider 配置可能会覆盖全局配置。你可以直接编辑data/opencode-config/opencode.json确保apiKey正确。流式链路采用prompt_async/global/event可实时看到工具调用与文本增量。前端按事件实时追加渲染步骤/工具事件逐条显示正文增量分块刷新不等待最终完成。从「技能/设置」等页面返回聊天页后会自动恢复当前对话的「处理中/排队中」状态并在任务结束后自动刷新最新消息。后台事件回放与数据库最终消息会做去重收敛避免同一回复先流式出现后又重复插入一次。记忆系统这次也补了不少聊天中手动「记住」时会优先识别偏好和习惯再识别联系方式和地址最后才判断个人信息避免使用偏好被误归为个人信息或联系人。AI 自动提取记忆时系统提示词包含严格的分类边界定义和示例。打开活跃记忆列表时会将生日类事实记忆自动补齐到长期记忆避免「有事实但列表为空」。删除带memory_key/fact_key的长期记忆时会同步归档对应事实。如果你需要查看记忆存储状态CodeBot 提供/api/memory/storage-status可直接查看当前数据库路径与表计数。活跃记忆页支持「一键自检」会检测数据库路径、关键表计数和接口读链路状态。定时任务页顶部的「开启通知」控制任务候选提醒。开启后聊天或自动整理把定时任务加入「成长候选」时会发送应用内/桌面操作提醒便于及时打开「成长候选」确认、编辑或接受。判断依据同时满足「触发词提醒/通知/闹钟等 时间或日期线索每天/周几/几点/10月20日等」时优先判为定时任务。聊天中的定时任务创建意图由 AI 结构化分类器判断只有判断为「创建/添加/设置 CodeBot 定时任务、提醒或闹钟」时CodeBot 才会写入内置定时任务系统或成长候选。普通排错、日志分析和文件处理会继续交给 OpenCode/Hermes CLI不会被误创建为任务。CodeBot 也不会让 CLI 立即创建 PowerShell 后台作业、Windows schtasks、cron/systemd/launchd 等系统级定时器。自动沉淀技能仅在复杂任务场景触发过滤寒暄类和系统提示词污染内容避免生成无意义技能。聊天页点击「生成技能」后后端会先调用find-skills搜索并评估现有 skill当最佳结果与需求差异小于 40%即相似度至少 60%时CodeBot 会基于该 skill 改造并保存否则会继续调用skill-creator创建新 skill。最终产物统一迁移或写入skills/auto_*在技能页中归类为「自动生成」。技能与 MCP 上下文仅用于内部推理不向用户直接展示「技能参考」等标签。回答入库与展示前会自动清洗system_policy/conversation_context等内部提示片段避免污染最终回复与对话标题。聊天时间显示会将 SQLite 的 UTC 时间戳按本地时区换算并正确显示「刚刚/分钟前/小时前」。聊天相对时间会自动刷新避免时间长期停留在「刚刚」。用户手动上滑查看历史消息时流式更新不再强制自动滚动到底部仅在接近底部或主动发送消息时自动跟随。消息操作按钮复制/撤销统一固定在回复气泡右下角。应用与对话回复头像使用logo.ico。如果你需要配置 Windows 任务计划程序实现opencode serve开机自启详细步骤已写入文档。桌面端会强制开启 OpenCode 自动拉起如果系统里已经有 OpenCode 桌面端或opencode serve在运行CodeBot 会直接复用现有健康服务并跳过额外安装检查。CodeBot 的 OpenAI 兼容接口GET /v1/models和POST /v1/chat/completions可以直接用 OpenAI SDK 调用。使用前请先请求/v1/models从返回结果里的id选择当前真实可用的模型。如果直接调用 HTTP 接口而不是 OpenAI SDKmodel字段可以省略此时后端会优先使用记忆自动整理模型memory.organize_model若未设置则回退到聊天页默认模型。如果你在配置过程中遇到问题先检查 TaoToken API Key 是否有效再检查opencode.cli_path和hermes.cli_path是否正确最后检查 Obsidian Vault 路径是否可写。大部分问题都出在这三个地方。 CodeBot：基于OpenCode的AI助手，兼容Hermes和Obsidian
1. CodeBot 是什么OpenCode 之上的 AI 助手兼容 Hermes 与 ObsidianCodeBot 是一个跑在本地、以 OpenCode 为执行内核的 AI 助手它把「模型对话」「技能调用」「知识库读写」「定时任务」这几件事收拢到一个聊天界面里。你可以把它理解成一层薄适配层底层真正干活的是 OpenCode CLI 和 Hermes CLICodeBot 负责把模型网关、记忆库、技能目录、Obsidian 路径这些共享配置写进去再启动子进程把终端输出持续追加到当前聊天气泡。它适合谁适合已经在用 OpenCode 做编码、同时希望把 Hermes Agent 和 Obsidian 知识库串进同一条工作流的人尤其是需要「提问—检索—回写」闭环的知识工作者。我关注它主要因为 4.3.0 这次更新覆盖了 v3.6.0 到 v4.3.0 的累积变更包含 11 个大章节其中 Hermes Agent 深度集成和 Obsidian 知识库集成是两条主线。Hermes 接入从 Gateway 收敛为 CLI oneshot聊天里选中 Hermes 后由 CodeBot 调用hermes -z执行入口切换为 Hermes 官方--cli chat -q单次查询路径。这意味着你不再需要导入 Hermes 内部 Agent 类也不用维护自定义 runnerCodeBot 只做三件事写共享配置、起子进程、把 stdout 追加到气泡。Obsidian 这边设置页的 Obsidian 标签支持配置默认 Vault 路径与多个知识库路径聊天页通过#可多选知识库。CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill 去完成检索、模板调用、读取、写入、移动与 wiki-link 安全操作不会把知识库先转成向量库。这一点对知识工作者很关键你的双链、标签、模板都还在AI 只是多了一双手。模型管理上聊天页模型刷新会优先调用opencode models与 OpenCode CLI 的最新模型列表保持一致。如果 CodeBot 进程 PATH 与终端不同可以在config.json的opencode.cli_path填写 opencode 可执行文件或所在目录也可以设置环境变量CODEBOT_OPENCODE_PATH。Windows 桌面端还会额外自动探测%APPDATA%\npm、Scoop shim、WinGet Links、Chocolatey bin 等常见 CLI 安装位置。这些细节决定了你第一次跑通时会不会卡在「找不到 opencode」上。对话级状态独立也值得单独说每个普通对话会独立保存当前模式、模型、Hermes/Obsidian 目标和已选知识库。在 B 对话切换模型或处理目标不会覆盖 A 对话原来的选择。新建对话仍会沿用最近主动选择的全局默认模型创建后再形成自己的独立状态。这个设计对同时开多个知识库、多个模型对比的场景非常友好。定时任务会持久化executor字段。聊天中选择 Hermes 后沉淀的任务、成长候选接受后的任务和手动编辑为 Hermes 的任务到点执行时会调用 Hermes CLI选择 OpenCode 或未指定时走 OpenCode。聊天中创建定时任务时会把当时选择的主模型保存为任务的execution_model任务执行前会检查该模型是否仍在当前可用模型列表中如果模型过时或供应商不再提供会自动回退到「记忆 → 自动整理 → 整理使用模型」。流式链路采用prompt_async/global/event可实时看到工具调用与文本增量。前端按事件实时追加渲染步骤/工具事件逐条显示正文增量分块刷新不等待最终完成。从「技能/设置」等页面返回聊天页后会自动恢复当前对话的「处理中/排队中」状态并在任务结束后自动刷新最新消息。后台事件回放与数据库最终消息会做去重收敛避免同一回复先流式出现后又重复插入一次。记忆系统这次也补了不少聊天中手动「记住」时会优先识别偏好和习惯再识别联系方式和地址最后才判断个人信息避免使用偏好被误归为个人信息或联系人。AI 自动提取记忆时系统提示词包含严格的分类边界定义和示例。打开活跃记忆列表时会将生日类事实记忆自动补齐到长期记忆避免「有事实但列表为空」。删除带memory_key/fact_key的长期记忆时会同步归档对应事实。CodeBot 还提供 OpenAI 兼容接口GET /v1/models和POST /v1/chat/completions。使用前请先请求/v1/models从返回结果里的id选择当前真实可用的模型。如果直接调用 HTTP 接口而不是 OpenAI SDKmodel字段可以省略此时后端会优先使用记忆自动整理模型memory.organize_model若未设置则回退到聊天页默认模型。连接状态方面聊天页顶部会显示 OpenCode / Bridge / MCP 代理状态并支持手动刷新连接与模型列表。桌面端启动后端时会自动尝试拉起 OpenCode 服务并统一优先使用127.0.0.1:11200。npm start开发模式也会跟正式版一样优先连到 11200避免误起另一套 dev server。如需覆盖默认值可设置环境变量CODEBOT_OPENCODE_PREFERRED_PORT与CODEBOT_OPENCODE_FALLBACK_PORT。分享与归档点击左侧对话更多菜单里的「分享」后系统会生成/share/{share_id}只读页面并复制基于局域网地址的链接。分享页面只展示对话内容不提供继续发送消息、删除或修改能力。点击「归档」后对话仍保存在data/conversations.db中conversations.is_archived会被设置为 1。归档后的对话不会显示在聊天页左侧普通对话列表中可在「日志」页的「已归档对话」标签中查看、搜索和恢复。自动沉淀技能仅在复杂任务场景触发过滤寒暄类和系统提示词污染内容避免生成无意义技能。聊天页点击「生成技能」后后端会先调用find-skills搜索并评估现有 skill当最佳结果与需求差异小于 40%即相似度至少 60%时CodeBot 会基于该 skill 改造并保存否则会继续调用skill-creator创建新 skill。最终产物统一迁移或写入skills/auto_*在技能页中归类为「自动生成」。2. 前置准备TaoToken 模型网关与 CodeBot 环境在跑通 CodeBot 之前你需要先解决模型来源问题。CodeBot 本身不绑定某一家模型它通过 OpenAI 兼容网关去调用模型。我实测下来用 TaoToken 作为模型网关比较省事因为它提供 OpenAI 兼容接口CodeBot 的opencode.json里直接填 Base URL 和 Key 就能用。TaoToken 官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接写这个。你需要准备的东西一个 TaoToken 账号并在控制台创建一个 API Key。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite本地已安装 Node.js建议 18和 npm。本地已安装 OpenCode CLI。如果没装可以用 npm 全局安装具体命令参考 OpenCode 官方文档。本地已安装 Hermes CLI。Hermes 的安装方式参考其官方说明CodeBot 只负责调用hermes命令。Obsidian 已安装并且你有一个或多个 Vault 路径。关于 API Key 的获取你可以直接访问 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建。创建后复制 Key后面配置里会用到。CodeBot 的安装方式如果你是从源码跑通常是git clone codebot-repo cd codebot npm install npm start如果你用的是桌面端安装包直接安装后启动即可。桌面端启动后端时会自动尝试拉起 OpenCode 服务并统一优先使用127.0.0.1:11200。如果系统里已经有 OpenCode 桌面端或opencode serve在运行CodeBot 会直接复用现有健康服务并跳过额外安装检查。这里有个坑我踩过CodeBot 进程的 PATH 和你的终端 PATH 可能不一致。如果你在终端里能跑opencode但 CodeBot 里模型刷新失败大概率是 PATH 问题。解决办法是在config.json的opencode.cli_path填写 opencode 可执行文件或所在目录或者设置环境变量CODEBOT_OPENCODE_PATH。Windows 桌面端还会额外自动探测%APPDATA%\npm、Scoop shim、WinGet Links、Chocolatey bin 等常见 CLI 安装位置但如果你用的是自定义安装路径还是手动指定更稳。另一个前置是 Hermes CLI 的可用性。CodeBot 4.3.0 之后Hermes 接入从 Gateway 收敛为 CLI oneshot聊天中选择 Hermes 后由 CodeBot 调用hermes -z。执行入口已从顶层hermes -z/--oneshot切换为 Hermes 官方--cli chat -q单次查询路径。所以你需要确保hermes命令在 PATH 里可执行并且版本支持--cli chat -q。Obsidian 这边你需要在 CodeBot 设置页的 Obsidian 标签里配置默认 Vault 路径与多个知识库路径。CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill。所以你也需要确保obsidian-cli可用或者至少 Obsidian 的 Vault 路径可读写。关于模型网关的配置CodeBot 自己拉起 OpenCode Server 时会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json并通过OPENCODE_CONFIG_HOMEdata/opencode-config启动 OpenCode。这意味着你可以在全局opencode.json里配置 TaoToken 的 providerCodeBot 会自动合并。如果你还没有配置过 OpenCode 的 provider可以参考 TaoToken 的接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有 OpenAI 兼容接口的详细说明。最后如果你打算长期用 CodeBot 做编码或 Agent 任务可以考虑 TaoToken 的 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要稳定模型调用的场景。3. 可复制配置opencode.json、config.json 与 Hermes/Obsidian 参数这一节给出可以直接复制的配置片段。路径和原文一致你按自己的实际路径替换即可。3.1 OpenCode provider 配置opencode.jsonCodeBot 自己拉起 OpenCode Server 时会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json并通过OPENCODE_CONFIG_HOMEdata/opencode-config启动 OpenCode。所以推荐你在全局~/.config/opencode/opencode.json里配置 TaoToken provider。{ $schema: https://opencode.ai/config.json, provider: { taotoken: { npm: ai-sdk/openai-compatible, name: TaoToken, options: { baseURL: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey }, models: { claude-sonnet-4-20250514: { name: Claude Sonnet 4 }, gpt-4.1: { name: GPT-4.1 } } } }, model: taotoken/claude-sonnet-4-20250514 }注意baseURL写https://taotoken.net/api不要加 UTM 参数。apiKey填你在 TaoToken 控制台创建的 Key。models里的模型 ID 需要是 TaoToken 实际支持的模型你可以先请求GET /v1/models确认。如果你不想改全局配置也可以直接在 CodeBot 的data/opencode-config/opencode.json里写同样的内容。但注意 CodeBot 启动时会合并全局配置所以全局配置优先级更高。3.2 CodeBot config.json 配置CodeBot 的config.json里可以配置 OpenCode CLI 路径、Obsidian Vault 路径、Hermes 相关参数等。以下是一个示例{ opencode: { cli_path: /usr/local/bin/opencode, preferred_port: 11200, fallback_port: 11201 }, obsidian: { default_vault: /Users/yourname/Documents/ObsidianVault, vaults: [ /Users/yourname/Documents/ObsidianVault, /Users/yourname/Documents/KnowledgeBase ] }, hermes: { cli_path: /usr/local/bin/hermes, skill_dirs: [ /Users/yourname/.hermes/skills, /Users/yourname/Documents/ObsidianVault/.skills ] }, memory: { organize_model: taotoken/claude-sonnet-4-20250514 } }opencode.cli_path填 opencode 可执行文件或所在目录。如果你在终端里能跑opencode但 CodeBot 里模型刷新失败大概率是 PATH 问题这里手动指定即可。Windows 桌面端还会额外自动探测%APPDATA%\npm、Scoop shim、WinGet Links、Chocolatey bin 等常见 CLI 安装位置但自定义路径还是手动指定更稳。obsidian.default_vault和obsidian.vaults填你的 Obsidian Vault 路径。CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill 去完成检索、模板调用、读取、写入、移动与 wiki-link 安全操作不会把知识库先转成向量库。hermes.cli_path填 hermes 可执行文件路径。hermes.skill_dirs填 Hermes Skill 目录。CodeBot 会把 Hermes Agent 自身默认可发现的 skill 目录、用户手动配置的 Hermes Skill 目录、CodeBot 内置/自动生成 skills 目录、以及 OpenCode CLI skill roots 一起并入 Hermes 的有效skills.external_dirs。memory.organize_model填记忆自动整理使用的模型。如果定时任务的execution_model过时或供应商不再提供会自动回退到这个模型。3.3 Hermes 接入参数Hermes 已从 Gateway 收敛为 CLI oneshot聊天中选择 Hermes 后由 CodeBot 调用hermes -z。CodeBot 只作为薄适配层写入共享配置模型网关、记忆库、定时任务库、技能目录和 Obsidian 路径启动 Hermes CLI 子进程把终端输出持续追加到当前聊天气泡。重构后的 Hermes 接入不再导入 Hermes 内部 Agent 类也不再依赖自定义 runner。聊天执行入口已从顶层hermes -z/--oneshot切换为 Hermes 官方--cli chat -q单次查询路径。当 CLI 明确要求确认、继续、密码、密钥或输入时会在聊天页显示交互面板并把用户回答写回 Hermes stdin。Hermes 不要求用户单独配置模型聊天主模型跟随当前聊天模型后台辅助模型跟随「记忆 → 自动整理 → 整理使用模型」。如果你需要手动测试 Hermes CLI 是否可用可以运行hermes --cli chat -q 你好如果这条命令能正常返回说明 Hermes CLI 配置正确。3.4 Obsidian 接入参数设置页中的 Obsidian 标签支持配置默认 Vault 路径与多个知识库路径。聊天页通过#可多选知识库。CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill 去完成检索、模板调用、读取、写入、移动与 wiki-link 安全操作不会把知识库先转成向量库。聊天输入框中的会搜索全部技能来源包括 CodeBot 内置/自动生成、OpenCode、Hermes Agent 与 OpenClaw支持描述、单词和多词搜索。聊天输入框中的/会搜索 OpenCode CLI 命令并支持按描述、单词和多词进行匹配。如果你需要手动测试 obsidian-cli 是否可用可以运行obsidian-cli --version如果这条命令能正常返回说明 obsidian-cli 配置正确。4. 验证请求从提问到结果回写 Obsidian配置完成后你需要做一次完整的验证从提问开始经过模型调用和知识库检索最后把结果回写到 Obsidian。这一节给出可跟做的步骤。4.1 启动 CodeBot 并检查连接状态启动 CodeBot 后聊天页顶部会显示 OpenCode / Bridge / MCP 代理状态并支持手动刷新连接与模型列表。你先点击刷新确认三个状态都是绿色或正常。如果 OpenCode 状态异常检查opencode.cli_path是否正确或者环境变量CODEBOT_OPENCODE_PATH是否设置。桌面端启动后端时会自动尝试拉起 OpenCode 服务并统一优先使用127.0.0.1:11200。npm start开发模式也会跟正式版一样优先连到 11200避免误起另一套 dev server。如需覆盖默认值可设置环境变量CODEBOT_OPENCODE_PREFERRED_PORT与CODEBOT_OPENCODE_FALLBACK_PORT。如果 Bridge 或 MCP 状态异常检查对应服务是否启动。4.2 刷新模型列表聊天页模型刷新会优先调用opencode models与 OpenCode CLI 的最新模型列表保持一致。点击刷新后你应该能看到taotoken/claude-sonnet-4-20250514等模型。如果模型列表为空先确认~/.config/opencode/opencode.json里的 provider 配置是否正确然后确认 TaoToken API Key 是否有效。你可以直接请求GET https://taotoken.net/api/v1/models验证 Keycurl -H Authorization: Bearer sk-你的TaoTokenKey https://taotoken.net/api/v1/models如果返回模型列表说明 Key 有效。如果返回 401说明 Key 无效或过期。4.3 选择 Hermes 模式并提问在聊天页选择 Hermes 模式然后选择一个 Obsidian 知识库通过#多选。接着输入一个问题例如请检索我的 Obsidian 知识库中关于「流式响应」的笔记总结要点并写一篇新的笔记到「AI 助手」文件夹。发送后CodeBot 会调用hermes -z启动 Hermes CLI 子进程。如果 CLI 长时间暂时没有正文输出CodeBot 会在聊天窗口中持续映射 Hermes 运行状态包括session.status启动状态、session.trace运行轨迹以及非阻塞的session.idle后台心跳。明显像「加载 skill / 调用 tool / 扫描资源 / 运行步骤」的 Hermes 行优先归类成可见的「工具调用」事件其余普通说明继续归类为「运行轨迹」。针对「启动后长时间 0 输出但同消息重试可成功」的间歇性卡死CodeBot 会在 Hermes 启动后连续 90 秒仍无任何 stdout 时自动重试 1 次。4.4 观察流式响应与工具调用流式链路采用prompt_async/global/event可实时看到工具调用与文本增量。前端按事件实时追加渲染步骤/工具事件逐条显示正文增量分块刷新不等待最终完成。为避免浏览器渲染被单次大量事件阻塞前端会在流式消费中定期让出事件循环并将文本增量按帧合并刷新。你应该能看到 Hermes 调用obsidian-cli检索笔记、读取内容、然后写入新笔记的过程。如果 Hermes 输出里有 ANSI 控制序列、Rich 边框、Resume this session/session_id/Session等终端辅助行CodeBot 会过滤掉。4.5 验证结果回写任务完成后打开 Obsidian检查「AI 助手」文件夹下是否生成了新笔记。如果生成了说明从提问到结果回写的闭环跑通了。如果没生成检查以下几点Hermes 是否有写入权限。CodeBot 会写入共享配置模型网关、记忆库、定时任务库、技能目录和 Obsidian 路径但实际写入操作由 Hermes 调用obsidian-cli完成。Obsidian Vault 路径是否正确。设置页中的 Obsidian 标签支持配置默认 Vault 路径与多个知识库路径。obsidian-cli是否可用。CodeBot 会优先引导调用obsidian-cli与相关 Obsidian skill。4.6 验证对话级状态独立在 A 对话选择 Hermes 模式和知识库 A在 B 对话选择 OpenCode 模式和知识库 B。然后在 B 对话切换模型回到 A 对话确认 A 对话的模型和知识库选择没有被覆盖。每个普通对话会独立保存当前模式、模型、Hermes/Obsidian 目标和已选知识库。在 B 对话切换模型或处理目标不会覆盖 A 对话原来的选择。新建对话仍会沿用最近主动选择的全局默认模型创建后再形成自己的独立状态。4.7 验证定时任务执行器绑定在聊天中选择 Hermes 后创建一个定时任务例如「每天 10 点提醒我整理 Obsidian 收件箱」。然后到定时任务页查看确认executor字段是hermes。定时任务会持久化executor字段。聊天中选择 Hermes 后沉淀的任务、成长候选接受后的任务和手动编辑为 Hermes 的任务到点执行时会调用 Hermes CLI选择 OpenCode 或未指定时走 OpenCode。聊天中创建定时任务时会把当时选择的主模型保存为任务的execution_model任务执行前会检查该模型是否仍在当前可用模型列表中如果模型过时或供应商不再提供会自动回退到「记忆 → 自动整理 → 整理使用模型」。在「定时任务」编辑窗口中可以为任务重新选择可用模型。4.8 验证 OpenAI 兼容接口CodeBot 提供 OpenAI 兼容接口GET /v1/models和POST /v1/chat/completions。你可以直接请求验证curl http://127.0.0.1:11200/v1/models使用前请先请求/v1/models从返回结果里的id选择当前真实可用的模型。如果直接调用 HTTP 接口而不是 OpenAI SDKmodel字段可以省略此时后端会优先使用记忆自动整理模型memory.organize_model若未设置则回退到聊天页默认模型。curl -X POST http://127.0.0.1:11200/v1/chat/completions \ -H Content-Type: application/json \ -d { messages: [{role: user, content: 你好}] }如果返回正常说明 OpenAI 兼容接口可用。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给出排查路径。你遇到问题时先看报错关键词再按对应步骤检查。5.1 401 Unauthorized报错示例Error: 401 Unauthorized原因TaoToken API Key 无效或过期或者opencode.json里的apiKey字段没有正确填写。排查步骤先确认~/.config/opencode/opencode.json里的apiKey字段是否填了正确的 Key。然后直接用 curl 验证curl -H Authorization: Bearer sk-你的TaoTokenKey https://taotoken.net/api/v1/models如果返回 401说明 Key 无效。到 TaoToken 控制台重新创建 Keyhttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite如果 curl 返回正常但 CodeBot 里仍然 401检查 CodeBot 是否合并了全局配置。CodeBot 自己拉起 OpenCode Server 时会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json并通过OPENCODE_CONFIG_HOMEdata/opencode-config启动 OpenCode。如果data/opencode-config/opencode.json里有旧的 provider 配置可能会覆盖全局配置。你可以直接编辑data/opencode-config/opencode.json确保apiKey正确。5.2 local proxy failed报错示例local proxy failed: connect ECONNREFUSED 127.0.0.1:11200原因CodeBot 无法连接到 OpenCode Server或者 OpenCode Server 没有启动。排查步骤先确认 OpenCode Server 是否在运行。桌面端启动后端时会自动尝试拉起 OpenCode 服务并统一优先使用127.0.0.1:11200。如果系统里已经有 OpenCode 桌面端或opencode serve在运行CodeBot 会直接复用现有健康服务并跳过额外安装检查。你可以手动检查端口curl http://127.0.0.1:11200/health如果返回连接拒绝说明 OpenCode Server 没启动。你可以手动启动opencode serve --port 11200如果端口被占用可以设置环境变量CODEBOT_OPENCODE_PREFERRED_PORT与CODEBOT_OPENCODE_FALLBACK_PORT覆盖默认值。另外检查opencode.cli_path是否正确。如果 CodeBot 进程 PATH 与终端不同可以在config.json的opencode.cli_path填写 opencode 可执行文件或所在目录也可以设置环境变量CODEBOT_OPENCODE_PATH。5.3 reading choices报错示例Error: reading choices: unexpected end of JSON input原因模型返回的流式响应格式异常或者网络中断导致 JSON 不完整。排查步骤先确认模型网关是否稳定。你可以直接请求 TaoToken 的 OpenAI 兼容接口验证curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 你好}], stream: true }如果返回正常说明网关没问题。如果返回异常检查模型 ID 是否正确。使用前请先请求/v1/models从返回结果里的id选择当前真实可用的模型。如果网关正常但 CodeBot 里仍然报reading choices检查流式链路。流式链路采用prompt_async/global/event可实时看到工具调用与文本增量。如果前端渲染被单次大量事件阻塞可能会出现 JSON 解析异常。你可以尝试减少单次请求的复杂度或者重启 CodeBot。5.4 OAuth 相关报错报错示例Error: OAuth token expired原因如果你使用的是需要 OAuth 的模型供应商token 过期会导致报错。但如果你用的是 TaoToken 的 API Key不应该出现 OAuth 报错。排查步骤先确认opencode.json里配置的是apiKey而不是 OAuth。TaoToken 使用 API Key 认证不需要 OAuth。如果你之前配置过其他供应商的 OAuth检查~/.config/opencode/opencode.json里是否有残留的 OAuth 配置。CodeBot 自己拉起 OpenCode Server 时会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json。如果全局配置里有 OAuth provider可能会干扰。你可以直接编辑data/opencode-config/opencode.json移除不需要的 provider。5.5 Hermes 启动后长时间 0 输出报错示例Hermes 启动后 90 秒无 stdout原因Hermes CLI 启动后卡住可能是 skill 加载或资源扫描阻塞。排查步骤CodeBot 会在 Hermes 启动后连续 90 秒仍无任何 stdout 时自动重试 1 次。如果重试后仍然卡住检查 Hermes 的 skill 目录。Hermes 的 skill 共享模型统一收敛为「目录共享」CodeBot 会把 Hermes Agent 自身默认可发现的 skill 目录、用户手动配置的 Hermes Skill 目录、CodeBot 内置/自动生成 skills 目录、以及 OpenCode CLI skill roots 一起并入 Hermes 的有效skills.external_dirs。对于「显式点名且来源于 OpenCode 共享目录」的 skillCodeBot 会先检测 Hermes 兼容分流运行时证据表明某些 OpenCode-shared skill 会在 Hermes 子进程中长期静默卡住因此这类请求会透明切换到 OpenCode 原生执行链。你可以手动运行 Hermes CLI 测试hermes --cli chat -q 你好如果这条命令也卡住说明 Hermes 本身有问题检查 Hermes 安装和 skill 目录。5.6 Obsidian 写入失败报错示例Error: obsidian-cli write failed原因obsidian-cli不可用或者 Vault 路径没有写入权限。排查步骤先确认obsidian-cli可用obsidian-cli --version然后确认 Vault 路径可写。设置页中的 Obsidian 标签支持配置默认 Vault 路径与多个知识库路径。CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill 去完成检索、模板调用、读取、写入、移动与 wiki-link 安全操作不会把知识库先转成向量库。如果obsidian-cli不可用检查是否安装并加入 PATH。5.7 模型列表为空报错示例模型刷新后列表为空原因opencode models调用失败或者 provider 配置错误。排查步骤聊天页模型刷新会优先调用opencode models与 OpenCode CLI 的最新模型列表保持一致。你可以手动运行opencode models如果返回为空检查~/.config/opencode/opencode.json里的 provider 配置。确认baseURL是https://taotoken.net/apiapiKey正确。如果opencode models正常但 CodeBot 里为空检查opencode.cli_path是否正确。如果 CodeBot 进程 PATH 与终端不同可以在config.json的opencode.cli_path填写 opencode 可执行文件或所在目录也可以设置环境变量CODEBOT_OPENCODE_PATH。Windows 桌面端还会额外自动探测%APPDATA%\npm、Scoop shim、WinGet Links、Chocolatey bin 等常见 CLI 安装位置。5.8 定时任务不执行报错示例定时任务到点未执行原因executor字段配置错误或者execution_model过时。排查步骤定时任务会持久化executor字段。聊天中选择 Hermes 后沉淀的任务、成长候选接受后的任务和手动编辑为 Hermes 的任务到点执行时会调用 Hermes CLI选择 OpenCode 或未指定时走 OpenCode。聊天中创建定时任务时会把当时选择的主模型保存为任务的execution_model任务执行前会检查该模型是否仍在当前可用模型列表中如果模型过时或供应商不再提供会自动回退到「记忆 → 自动整理 → 整理使用模型」。在「定时任务」编辑窗口中可以为任务重新选择可用模型。如果任务不执行检查executor字段和execution_model字段。你可以在定时任务页编辑任务重新选择模型。5.9 分享链接无法访问报错示例分享链接打开后 404原因分享页面生成失败或者局域网地址不可达。排查步骤点击左侧对话更多菜单里的「分享」后系统会生成/share/{share_id}只读页面并复制基于局域网地址的链接。分享页面只展示对话内容不提供继续发送消息、删除或修改能力。如果链接无法访问检查 CodeBot 服务是否在运行以及局域网地址是否正确。你可以手动访问http://127.0.0.1:11200/share/{share_id}测试。5.10 归档对话找不到报错示例归档后对话消失原因归档后的对话不会显示在聊天页左侧普通对话列表中。排查步骤点击「归档」后对话仍保存在data/conversations.db中conversations.is_archived会被设置为 1。归档后的对话不会显示在聊天页左侧普通对话列表中可在「日志」页的「已归档对话」标签中查看、搜索和恢复。如果你需要恢复归档对话到「日志」页的「已归档对话」标签中操作。6. 把 CodeBot 接进你的知识工作流模型对话、Coding Plan 与接入文档CodeBot 跑通之后你可以把它接进日常的知识工作流。这里给出几个方向以及对应的 TaoToken 资源。如果你主要是做知识库问答和笔记整理用 Hermes Obsidian 模式就够了。聊天页通过#可多选知识库CodeBot 会把这些 Markdown 知识库当成原生 Obsidian wiki 结构直接处理优先引导调用obsidian-cli与相关 Obsidian skill 去完成检索、模板调用、读取、写入、移动与 wiki-link 安全操作不会把知识库先转成向量库。你可以直接问「检索我的 Obsidian 知识库中关于 X 的笔记总结要点」然后让 Hermes 把结果写回指定文件夹。如果你主要是做编码和 Agent 任务用 OpenCode 模式。聊天页模型刷新会优先调用opencode models与 OpenCode CLI 的最新模型列表保持一致。你可以用 CodeBot 做代码生成、重构、排错也可以创建定时任务做自动化。如果你需要长期稳定的模型调用可以考虑 TaoToken 的 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它适合需要长期编码或 Agent 任务的场景。如果你需要验证模型是否可用可以直接用 TaoToken 的模型对话功能https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。在配置 CodeBot 之前先用模型对话确认模型可用可以省去很多排查时间。如果你需要创建 API Key到控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后复制 Key填到opencode.json的apiKey字段。如果你需要查看接入文档到https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有 OpenAI 兼容接口的详细说明包括GET /v1/models和POST /v1/chat/completions的用法。如果你用的是 Claude Code 或 Anthropic 风格的接入可以参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 。CodeBot 的 OpenAI 兼容接口也支持类似用法。最后如果你需要直接调用 API地址是 https://taotoken.net/api 。注意这个地址不带 UTM 参数配置时直接写这个。CodeBot 的 4.3.0 版本把 Hermes 和 Obsidian 两条线都补得比较完整了。Hermes 接入从 Gateway 收敛为 CLI oneshot执行入口切换为 Hermes 官方--cli chat -q单次查询路径。Obsidian 支持多知识库聊天页通过#可多选知识库。模型管理上聊天页模型刷新会优先调用opencode models。对话级状态独立每个普通对话会独立保存当前模式、模型、Hermes/Obsidian 目标和已选知识库。定时任务会持久化executor字段支持 Hermes 和 OpenCode 两种执行器。我实测下来最容易卡住的地方是 PATH 和 provider 配置。如果你在终端里能跑opencode但 CodeBot 里模型刷新失败大概率是 PATH 问题。解决办法是在config.json的opencode.cli_path填写 opencode 可执行文件或所在目录或者设置环境变量CODEBOT_OPENCODE_PATH。Windows 桌面端还会额外自动探测%APPDATA%\npm、Scoop shim、WinGet Links、Chocolatey bin 等常见 CLI 安装位置。另一个容易忽略的是data/opencode-config/opencode.json和全局~/.config/opencode/opencode.json的合并关系。CodeBot 自己拉起 OpenCode Server 时会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json并通过OPENCODE_CONFIG_HOMEdata/opencode-config启动 OpenCode。如果data/opencode-config/opencode.json里有旧的 provider 配置可能会覆盖全局配置。你可以直接编辑data/opencode-config/opencode.json确保apiKey正确。流式链路采用prompt_async/global/event可实时看到工具调用与文本增量。前端按事件实时追加渲染步骤/工具事件逐条显示正文增量分块刷新不等待最终完成。从「技能/设置」等页面返回聊天页后会自动恢复当前对话的「处理中/排队中」状态并在任务结束后自动刷新最新消息。后台事件回放与数据库最终消息会做去重收敛避免同一回复先流式出现后又重复插入一次。记忆系统这次也补了不少聊天中手动「记住」时会优先识别偏好和习惯再识别联系方式和地址最后才判断个人信息避免使用偏好被误归为个人信息或联系人。AI 自动提取记忆时系统提示词包含严格的分类边界定义和示例。打开活跃记忆列表时会将生日类事实记忆自动补齐到长期记忆避免「有事实但列表为空」。删除带memory_key/fact_key的长期记忆时会同步归档对应事实。如果你需要查看记忆存储状态CodeBot 提供/api/memory/storage-status可直接查看当前数据库路径与表计数。活跃记忆页支持「一键自检」会检测数据库路径、关键表计数和接口读链路状态。定时任务页顶部的「开启通知」控制任务候选提醒。开启后聊天或自动整理把定时任务加入「成长候选」时会发送应用内/桌面操作提醒便于及时打开「成长候选」确认、编辑或接受。判断依据同时满足「触发词提醒/通知/闹钟等 时间或日期线索每天/周几/几点/10月20日等」时优先判为定时任务。聊天中的定时任务创建意图由 AI 结构化分类器判断只有判断为「创建/添加/设置 CodeBot 定时任务、提醒或闹钟」时CodeBot 才会写入内置定时任务系统或成长候选。普通排错、日志分析和文件处理会继续交给 OpenCode/Hermes CLI不会被误创建为任务。CodeBot 也不会让 CLI 立即创建 PowerShell 后台作业、Windows schtasks、cron/systemd/launchd 等系统级定时器。自动沉淀技能仅在复杂任务场景触发过滤寒暄类和系统提示词污染内容避免生成无意义技能。聊天页点击「生成技能」后后端会先调用find-skills搜索并评估现有 skill当最佳结果与需求差异小于 40%即相似度至少 60%时CodeBot 会基于该 skill 改造并保存否则会继续调用skill-creator创建新 skill。最终产物统一迁移或写入skills/auto_*在技能页中归类为「自动生成」。技能与 MCP 上下文仅用于内部推理不向用户直接展示「技能参考」等标签。回答入库与展示前会自动清洗system_policy/conversation_context等内部提示片段避免污染最终回复与对话标题。聊天时间显示会将 SQLite 的 UTC 时间戳按本地时区换算并正确显示「刚刚/分钟前/小时前」。聊天相对时间会自动刷新避免时间长期停留在「刚刚」。用户手动上滑查看历史消息时流式更新不再强制自动滚动到底部仅在接近底部或主动发送消息时自动跟随。消息操作按钮复制/撤销统一固定在回复气泡右下角。应用与对话回复头像使用logo.ico。如果你需要配置 Windows 任务计划程序实现opencode serve开机自启详细步骤已写入文档。桌面端会强制开启 OpenCode 自动拉起如果系统里已经有 OpenCode 桌面端或opencode serve在运行CodeBot 会直接复用现有健康服务并跳过额外安装检查。CodeBot 的 OpenAI 兼容接口GET /v1/models和POST /v1/chat/completions可以直接用 OpenAI SDK 调用。使用前请先请求/v1/models从返回结果里的id选择当前真实可用的模型。如果直接调用 HTTP 接口而不是 OpenAI SDKmodel字段可以省略此时后端会优先使用记忆自动整理模型memory.organize_model若未设置则回退到聊天页默认模型。如果你在配置过程中遇到问题先检查 TaoToken API Key 是否有效再检查opencode.cli_path和hermes.cli_path是否正确最后检查 Obsidian Vault 路径是否可写。大部分问题都出在这三个地方。