WorkBuddy 接入 Obsidian：把本地 CLI 变成笔记里的 AI 聊天面板

Mon, 28 Sep 2026 15:10:00 +0800

本文记录的是 Windows 本机实操过程，路径中的 %APPDATA%、%USERPROFILE% 需替换为你自己的实际值。全过程已端到端验证通过（2026-09-28 15:07，模型正常返回）。

想让 Obsidian 里的 AI 插件直接调用 WorkBuddy，第一反应通常是：把 base_url 填进插件设置。这条路走不通，而且会浪费你一个下午。

先说结论

WorkBuddy 桌面版不对外提供 OpenAI 兼容的 HTTP 接口，所以「把它填进普通 AI 插件（Aide、Text Generator 等）的 base_url」这条路是死的。

官方可行路线只有一条：

flowchart LR
 A["Obsidian 插件
Workbuddian"] -->|"ACP 协议（stdio）"| B["本地 CodeBuddy CLI
npm 完整版"]
 B -->|HTTPS| C["WorkBuddy 云端"]
 style A fill:#2d6cdf,stroke:#1c4a9e,color:#fff
 style B fill:#3a7d44,stroke:#245c2c,color:#fff
 style C fill:#7a4fbf,stroke:#553394,color:#fff

也就是说：插件本身不含模型，它只是把本地 CLI 包装成笔记内的聊天面板。

明白这一点，修复顺序就确定了：先让 CLI 独立跑通，再回 Obsidian。反过来做只会陷入「插件里发消息一直报错，但不知道错在哪一层」。

最终配置

项目	值	说明
插件	Workbuddian v2.6.10（作者 jiang198012）	已装已启用
备用插件	Agent Client v0.13.0	通用 ACP 客户端，可追加 WorkBuddy 条目
CLI 路径	`%APPDATA%\npm\node_modules\@tencent-ai\codebuddy-code\bin\codebuddy`	完整版 v2.159.0（必须用这个）
Node 路径	`%USERPROFILE%\.workbuddy-ai\binaries\node\versions\22.22.2-3\node.exe`	需写入用户级 PATH
插件配置	`<库>\.obsidian\plugins\workbuddian\data.json` → `settings.codebuddyPath`	已改为完整版路径
配置备份	`data.json.bak-20260928`	改错了可回滚
认证方式	`cli-external-link`（浏览器授权）	凭据已就绪

最大的坑：两个 CLI 不是一个东西

本机存在两个 CodeBuddy CLI，功能不同，选错就永远用不了：

	内置裁剪版 ❌	npm 完整版 ✅
路径	`%PROGRAMFILES%\WorkBuddyAI\...\cli\bin\codebuddy`	`%APPDATA%\npm\node_modules\@tencent-ai\codebuddy-code\bin\codebuddy`
版本	随桌面版	v2.159.0
TUI 登录	无（报 `Cannot find module '../dist/codebuddy'`）	有
独立认证	不行（实测仍报 `Authentication required`）	可以
结论	不可用于 Obsidian	用这个

而插件默认指向的正是内置裁剪版——这就是「面板里发消息返回 本轮中断：refusal」的根因。

四处改动

1. 把 Node 写入用户级 PATH

CLI 是 Node 脚本，而 node 不在系统 PATH，直接跑会报 env: 'node': No such file or directory。把 %USERPROFILE%\.workbuddy-ai\binaries\node\versions\22.22.2-3 写入用户级 PATH 即可。

2. 修复 npm 全局入口，建立稳定路径

完整版 CLI 被装在异常目录 @tencent-ai\.codebuddy-code-bIfWIhdo（. 前缀导致 npm 生成的 codebuddy.cmd 指向失效）。建立目录链接，使下列路径等效可用：

%APPDATA%\npm\node_modules\@tencent-ai\codebuddy-code ──▶ .codebuddy-code-bIfWIhdo

后面那个随机后缀是升级的大敌，见文末「升级后路径失效」。

3. 完成 CLI 独立登录

桌面版登录 ≠ CLI 登录。CLI 走的是 cli-external-link 外链授权，必须单独登录一次。

授权地址：https://copilot.tencent.com/login?platform=CLI&...
授权成功后凭据落盘，内置版仍读不到，完整版可正常鉴权（已在 ACP 全链路验证）
授权前的报错，留个对照：

{"statusCode":401,"message":"Authentication required",
 "auth-type:cli-external-link,"token-type":"Bearer","token-length":1382}

4. 插件配置改指完整版 CLI

// .obsidian/plugins/workbuddian/data.json
"settings": {
 "codebuddyPath": "C:\\Users\\<你>\\AppData\\Roaming\\npm\\node_modules\\@tencent-ai\\codebuddy-code\\bin\\codebuddy",
 "nodePath": "C:\\Users\\<你>\\.workbuddy-ai\\binaries\\node\\versions\\22.22.2-3\\node.exe",
 "backend": "codebuddy",
 "permissionMode": "default"
}

最后一步：重载插件（约 10 秒）

插件配置是启动时读入内存的，运行中的 Obsidian 仍持有旧路径。

设置 → 第三方插件 → 把「Workbuddian」关闭，再打开（或直接重启 Obsidian）。

⚠️ 重载之前，不要进入该插件的设置界面改动任何选项——那会把内存里的旧路径重新写回文件。（会话记录保存不受影响，它会先重新读盘再写。）

重载后：点左侧机器人图标 → 发一条消息 → 应正常流式回复。

如果仍然失败

打开插件设置，把 CodeBuddy CLI 路径手动粘贴为完整版路径，保存即可。这条操作会以正确值覆写，反而更稳。

日常用法

操作	说明
`@`	引用四个来源：当前笔记 / 全部笔记 / 选中文本 / 附件
`/`	调用命令与 Skills（如 `/background`、`/branch`）
`#`	写入常驻指令（长期生效的偏好）
权限模式	`default` 每次询问 / `acceptEdits` 自动接受编辑 / `plan` 只读规划
模型	面板内可切换（`hy3` 免费档、`hy4-preview` 等，按云币计费）

维护与排障

症状 → 原因 → 处置

症状	原因	处置
`本轮中断：refusal`	CLI 未登录 / token 失效	重新登录
`env: 'node': No such file or directory`	node 不在 PATH	检查用户级 PATH，重开终端
找不到 CLI	路径指向内置裁剪版	改为完整版路径
401 endpoint mismatch	认证过期	重新登录

重新登录 CLI（token 过期时）

$cb = "$env:APPDATA\npm\node_modules\@tencent-ai\codebuddy-code\bin\codebuddy"
& "$env:USERPROFILE\.workbuddy-ai\binaries\node\versions\22.22.2-3\node.exe" $cb

进入 TUI 后输入 /login，选中国站登录，浏览器完成微信扫码授权。

自检一条龙

$node = "$env:USERPROFILE\.workbuddy-ai\binaries\node\versions\22.22.2-3\node.exe"
$cb = "$env:APPDATA\npm\node_modules\@tencent-ai\codebuddy-code\bin\codebuddy"
& $node $cb -p "回复四个字：接入成功" --output-format json

能返回文字即链路完好；返回 Authentication required 则需重新登录。

升级后路径失效怎么办

WorkBuddy 或 CLI 升级后，.codebuddy-code-<随机后缀> 目录名可能变化，导致稳定链接失效。重建链接：

$base = Join-Path $env:APPDATA "npm\node_modules\@tencent-ai"
$real = Get-ChildItem $base -Directory | Where-Object { $_.Name -like ".codebuddy-code-*" } | Select-Object -First 1
if ($real) {
 $link = Join-Path $base "codebuddy-code"
 if (Test-Path $link) { Remove-Item $link -Force }
 New-Item -ItemType Junction -Path $link -Target $real.FullName
 Write-Output "链接已重建 → $($real.Name)"
}

备用方案：Agent Client

在通用 ACP 客户端 Agent Client 中追加一个自定义代理，直接以绝对路径拉起 node：

{
 "id": "codebuddy-workbuddy",
 "displayName": "WorkBuddy (CodeBuddy)",
 "command": "C:\\Users\\<你>\\.workbuddy-ai\\binaries\\node\\versions\\22.22.2-3\\node.exe",
 "args": ["C:\\Users\\<你>\\AppData\\Roaming\\npm\\node_modules\\@tencent-ai\\codebuddy-code\\bin\\codebuddy", "--acp"],
 "env": [],
 "enabled": true
}

重载插件后，在 Agent Client 的代理下拉里选 WorkBuddy (CodeBuddy) 即可（它默认仍是 Codex，需要手动切换）。

诊断记录（留档）

时间	事件
09:45	Workbuddian v2.6.10 装入
11:xx	面板发 `hi` → 返回 `本轮中断：refusal`
14:5x	定位根因：`refusal classified: category=auth`
14:57	完成 CLI 外链授权（凭据落盘）
15:01	ACP 全链路验证通过，模型返回「成功」
15:07	按插件真实配置复验通过，返回「接入成功」

关键日志位置：~/.codebuddy/logs/<日期>/Obsidian__*.log

一句话总结

问题不在插件，也不在 Obsidian，而在「CLI 用错了版本 + 从未独立登录」。

改用完整版 CLI 并完成一次外链授权后，链路即通。下次再遇到 refusal，先翻回这张表：版本对不对、登录过没有、node 在不在 PATH。

CodeBuddy on 我的博客