企业官网建设流程全解析

1. CodeBot 是什么：OpenCode 之上的 AI 助手，兼容 Hermes 与 Obsidian

CodeBot 是一个跑在本地、以 OpenCode 为执行内核的 AI 助手，它把「模型对话」「技能调用」「知识库读写」「定时任务」这几件事收拢到一个聊天界面里。你可以把它理解成一层薄适配层：底层真正干活的是 OpenCode CLI 和 Hermes CLI，CodeBot 负责把模型网关、记忆库、技能目录、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 类，也不用维护自定义 runner，CodeBot 只做三件事：写共享配置、起子进程、把 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 SDK，model字段可以省略；此时后端会优先使用记忆自动整理模型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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数，配置时直接写这个。

你需要准备的东西：

• 一个 TaoToken 账号，并在控制台创建一个 API Key。控制台地址：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite
• 本地已安装 Node.js（建议 18+）和 npm。
• 本地已安装 OpenCode CLI。如果没装，可以用 npm 全局安装，具体命令参考 OpenCode 官方文档。
• 本地已安装 Hermes CLI。Hermes 的安装方式参考其官方说明，CodeBot 只负责调用hermes命令。
• Obsidian 已安装，并且你有一个或多个 Vault 路径。

关于 API Key 的获取，你可以直接访问 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 创建。创建后复制 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_HOME=data/opencode-config启动 OpenCode。这意味着你可以在全局opencode.json里配置 TaoToken 的 provider，CodeBot 会自动合并。

如果你还没有配置过 OpenCode 的 provider，可以参考 TaoToken 的接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。文档里有 OpenAI 兼容接口的详细说明。

最后，如果你打算长期用 CodeBot 做编码或 Agent 任务，可以考虑 TaoToken 的 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它适合需要稳定模型调用的场景。

3. 可复制配置：opencode.json、config.json 与 Hermes/Obsidian 参数

这一节给出可以直接复制的配置片段。路径和原文一致，你按自己的实际路径替换即可。

3.1 OpenCode provider 配置（opencode.json）

CodeBot 自己拉起 OpenCode Server 时，会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json，并通过OPENCODE_CONFIG_HOME=data/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验证 Key：

curl -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 SDK，model字段可以省略；此时后端会优先使用记忆自动整理模型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 控制台重新创建 Key：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite

如果 curl 返回正常，但 CodeBot 里仍然 401，检查 CodeBot 是否合并了全局配置。CodeBot 自己拉起 OpenCode Server 时，会将用户全局~/.config/opencode/opencode.json里的 provider 合并到data/opencode-config/opencode.json，并通过OPENCODE_CONFIG_HOME=data/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 共享目录」的 skill，CodeBot 会先检测 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/api，apiKey正确。

如果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 Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它适合需要长期编码或 Agent 任务的场景。

如果你需要验证模型是否可用，可以直接用 TaoToken 的模型对话功能：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。在配置 CodeBot 之前，先用模型对话确认模型可用，可以省去很多排查时间。

如果你需要创建 API Key，到控制台：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建后复制 Key，填到opencode.json的apiKey字段。

如果你需要查看接入文档，到：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。文档里有 OpenAI 兼容接口的详细说明，包括GET /v1/models和POST /v1/chat/completions的用法。

如果你用的是 Claude Code 或 Anthropic 风格的接入，可以参考：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude-code-anthropic&utm_campaign=rewrite 。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_HOME=data/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 SDK，model字段可以省略；此时后端会优先使用记忆自动整理模型memory.organize_model，若未设置则回退到聊天页默认模型。

如果你在配置过程中遇到问题，先检查 TaoToken API Key 是否有效，再检查opencode.cli_path和hermes.cli_path是否正确，最后检查 Obsidian Vault 路径是否可写。大部分问题都出在这三个地方。