AI原生笔记应用Tolaria

发表于 分类于 Waline： 阅读次数： 本文字数： 7.5k 阅读时长 ≈ 7 分钟
Tolaria 是一个 AI 原生的本地 markdown 笔记管理桌面应用，原生集成 Claude Code、OpenCode、Gemini 等 CLI 代理。

简介

什么是 Tolaria ？

Tolaria 是一个 AI 原生的本地 markdown 笔记知识库桌面应用。它把”纯 markdown 文件 + git 仓库 + AI 代理”这三件事打包到一起，开箱即用，专为 AI 时代的”第二大脑”设计。

项目作者 Luca Rossi 是 Refactoring 通讯（170,000+ 订阅）的创办者，自己用 Tolaria 管理 10,000+ 条个人笔记。项目以 AGPL-3.0 协议开源，2026 年 2 月发布，3 个月内 GitHub 攒到了 10K+ Star。

主要特点

  • AI 原生设计：开箱即用支持 Claude Code、Codex CLI、OpenCode、Pi、Gemini 五个本地 CLI 代理；同时支持自定义 OpenAI 兼容 model provider（API 直连模式）
  • Files-first：每条笔记都是磁盘上的 markdown 文件 + YAML frontmatter，任何编辑器（VSCode、Vim、Notepad）都能直接编辑，零专属格式锁定
  • Git-first：每个 vault 都是一个 git 仓库，commit / push / history 全部内嵌到 app 里，跨设备同步用你已经信任的 git 即可
  • Offline-first, zero lock-in：无账号、无订阅、无云端依赖，完全离线工作；停止使用 Tolaria 不会损失任何数据
  • 块级富文本编辑器：slash 命令、wikilinks、whiteboard、媒体预览、原始 markdown 模式自由切换
  • 类型作为视角而非约束：可以为笔记打”类型”（如 person、project、event），但不强制 schema 验证，只用来辅助导航
  • 关系有类型、可独立查询:除了普通 wikilinks,还支持有名字的关系(如 “references”、”author of”、”part of”),关系是双向的,可以按关系类型筛选笔记
  • MCP server 内嵌：自带 mcp-server，外部 AI 工具可通过 MCP 协议直接搜索/读取/打开 vault 笔记
  • 键盘优先：Command Palette、快捷键贯穿整个 UI，鼠标可有可无
  • 真开源免费：基于 AGPL-3.0-or-later 协议开源

应用场景

  • 个人 second brain：替代 Notion / Evernote / Apple Notes，把零散信息整理成结构化知识网络
  • AI 上下文持久化：把你跟 AI 的讨论结果、长期记忆、procedure 存进 vault，下次让 AI 通过 MCP 直接读出来继续工作
  • 写作工作流：写作者用它管理素材库、文章草稿、参考资料；作者本人就是这么用的
  • 团队文档与公司知识库：把公司文档存成 markdown + git，团队可以用任何 IDE 编辑，也可以让 AI 代理基于这些文档生成内容
  • 代码项目辅助笔记：跟代码仓库平行存储 ADR、设计文档、调研笔记，让本地 AI 代理同时操作代码和笔记

Tolaria 是给 AI 时代写作者和知识工作者准备的本地优先笔记应用，把”文件、git、AI”三件事一站式整合，避开了 Notion 的云端锁定和 Obsidian 的插件繁琐。

与 Obsidian 详细对比

Tolaria 和 Obsidian 对比，两者都是本地 markdown 知识库工具，但定位有显著差异。以下从十个维度详细对比：

维度 Tolaria Obsidian
开源协议 AGPL-3.0，完全开源 闭源（免费个人使用，商用需付费授权）
数据格式 Markdown + YAML frontmatter Markdown + YAML frontmatter（兼容）
同步方案 内建 Git 客户端，commit/push/history 全在 app Obsidian Sync 付费云（$8/月），或装第三方 Git 插件
AI 代理集成 原生支持 Claude Code / Codex / OpenCode / Pi / Gemini 五个 CLI 代理 + API model provider 需装插件（如 Smart Connections、Copilot 等），各家集成深浅不一
MCP 协议 内嵌 MCP server，外部 AI 直接搜笔记、读笔记、改笔记 需第三方插件（如 obsidian-mcp），且能力有限
关系建模 Wikilinks + 有类型的双向关系 + 类型化属性 仅 Wikilinks，关系靠手动 frontmatter 字段约定
插件生态 较小（项目仅 3 个月），主要功能内建 1500+ 社区插件，生态成熟
移动端 暂无 iOS / Android 官方 app
团队协作 通过 git remote 共享 vault（公开/私有仓库均可） Obsidian Publish 付费（$10/月）
项目年龄 2026 年 2 月，10K Star，新生态 2020 年，成熟工具

选哪个？

选 Tolaria 如果：

  • 你深度使用 Claude Code / OpenCode / Codex CLI 这类命令行 AI 代理
  • 你希望 AI 通过 MCP 协议直接读写你的笔记 vault
  • 你看重真正的开源（AGPL），不接受闭源核心
  • 你用 git 做同步、版本控制是自然选择
  • 你不依赖移动端

选 Obsidian 如果：

  • 你需要海量社区插件覆盖各种小众需求（PDF 标注、Anki 同步、Dataview 查询等）
  • 你需要 iOS / Android 移动端
  • 你不太在意闭源
  • 你的 AI 使用主要是聊天侧栏，不需要 AI 操作 vault 文件

两者并不互斥：vault 文件格式高度兼容（都是 markdown + YAML），可以在两个 app 之间切换。我自己的体验是 Tolaria 在”AI 直接操作笔记”这件事上做得显著更深，而 Obsidian 在”细节插件”这件事上仍然遥遥领先。

安装

Tolaria 是 Tauri 桌面应用（Rust + React），跨平台支持 macOS、Windows、Linux 三大主流系统。

macOS

方式一：Homebrew（推荐）

1
brew install --cask tolaria

方式二：官方 dmg 下载

  • Intel 芯片：Tolaria_2026.5.14_macOS_Intel.dmg（15 MB）
  • Apple Silicon：Tolaria_2026.5.14_macOS_Silicon.dmg（14 MB）

下载后双击挂载、拖到 Applications 文件夹即可。

Windows

下载 Tolaria_2026.5.14_x64-setup.exe（10 MB），双击安装。

安装目录默认在 %LOCALAPPDATA%\Tolaria\，配置在 %APPDATA%\com.tolaria.app\。

Linux

三种打包格式任选其一：

格式 大小 适用发行版
Tolaria_2026.5.14_amd64.deb 14 MB Debian / Ubuntu 22.04+
Tolaria-2026.5.14-1.x86_64.rpm 14 MB Fedora / RHEL / openSUSE
Tolaria_2026.5.14_amd64.AppImage 89 MB 任意发行版（免安装）

依赖：Tauri 2 在 Linux 需要 WebKit2GTK 4.1。Ubuntu 用户参考：

1
2
sudo apt install libwebkit2gtk-4.1-dev libxdo-dev libssl-dev \
  libayatana-appindicator3-dev librsvg2-dev libsoup-3.0-dev patchelf

首次启动

  1. 创建或克隆 vault：首次启动 Tolaria 会问你要不要克隆官方的 getting-started vault，这是一个带教程的演示 vault，推荐新用户克隆体验
  2. 打开本地 markdown 文件夹：如果你已经有 Obsidian / Logseq vault 或纯 markdown 文件夹，直接 Open Vault 选中目录即可，Tolaria 会自动识别
  3. 初始化 git：Tolaria 强烈建议每个 vault 都是 git 仓库，会在你确认后跑 git init。如果想连远程 GitHub 仓库，可以在设置里配置 SSH key 或 token
  4. 配置 AI 代理（可选但强烈推荐，下一节详述）

配置 AI 代理

Tolaria 最大的差异化卖点是原生 AI 代理集成。它不内置任何 AI 模型，而是检测并桥接你本机已安装的 CLI 代理：

代理 包名 主要用途
Claude Code @anthropic-ai/claude-code Anthropic 官方,工具调用最完善
Codex CLI OpenAI Codex OpenAI 的代码 CLI
OpenCode opencode-ai 开源多模型聚合 CLI
Pi CLI Pi.ai Inflection 的对话型 CLI
Gemini CLI @google/gemini-cli Google 官方

任选其一安装即可，Tolaria 启动时自动扫描 where claude / where opencode 等 + 一组硬编码候选目录（如 ~/.local/bin/、~/.npm-global/bin/、AppData/Roaming/npm/ 等）。

安装示例（任选一个用 npm 全局装）：

1
2
3
npm install -g @anthropic-ai/claude-code   # 或
npm install -g opencode-ai                  # 或
npm install -g @google/gemini-cli

装完后在 CLI 里跑一次 claude auth login / opencode auth login / 启动 gemini 完成 OAuth 登录。然后重启 Tolaria，AI 面板的状态栏会显示”AI Agents”徽章，列出已识别的代理。

两种 AI 工作模式：

  • Chat 模式：跟笔记内容对话，不修改文件；可以用 API model provider（OpenAI / 本地 Ollama / SiliconFlow 等）
  • Agent 模式：让 AI 真的去改 vault 里的笔记（Edit/Write 工具开放），必须用 CLI 代理（不能用纯 API provider）

可以在 Tolaria 设置里把默认的 default_ai_agent（写文件 agent 引擎）和 default_ai_target（AI 面板默认目标）分别配置成不同的代理。

Windows 用户的坑与临时解决方案

Tolaria 在 macOS 和 Linux 上工作得很顺，但在 Windows + nvm-for-windows + 较新版本 claude-code / opencode-ai 组合下有几个坑值得提前避雷。

坑一：Claude Code 和 OpenCode 报 os error 193

症状：Tolaria AI 面板能”检测到” Claude / OpenCode，但不显示版本号，实际调用时报：

1
Error: Failed to spawn claude: %1 不是有效的 Win32 应用程序。 (os error 193)

OpenCode 同样报这个错。Gemini 不受影响。

AI 给的原因分析：

claude-code 2.x 和 opencode-ai 改用了 native launcher 打包，npm 生成的 claude.cmd / opencode.cmd 内部不再指向 .js bundle，而是直接指向 node_modules\@anthropic-ai\claude-code\bin\claude.exe 这类 native .exe。

Tolaria 在 src-tauri/src/cli_agent_runtime.rs 里有 Windows 专用逻辑试图把 .cmd shim 替换成 node script.js 启动（绕开 CreateProcessW 不能执行 .cmd 的限制），但它的解析器只识别 .js / .mjs / .cjs 扩展名，遇到 .exe 就 fallback 到直接 spawn .cmd，触发 Windows 的 ERROR_BAD_EXE_FORMAT（os error 193）。

Gemini CLI 仍是经典 npm shim 格式（.cmd → gemini-cli/bundle/gemini.js），所以走得通。

临时解决方案：

让 Tolaria 直接找到 .exe 而不是 .cmd。把 npm 包内的 .exe 复制一份到 Tolaria 会扫的候选目录 ~/.local/bin/：

1
2
3
4
5
6
7
mkdir -p ~/.local/bin
cp "C:/nvm4w/nodejs/node_modules/@anthropic-ai/claude-code/bin/claude.exe" ~/.local/bin/
cp "C:/nvm4w/nodejs/node_modules/opencode-ai/bin/opencode.exe" ~/.local/bin/

# 屏蔽掉原 .cmd（让 Tolaria 不会优先命中它）
mv C:/nvm4w/nodejs/claude.cmd C:/nvm4w/nodejs/claude.cmd.disabled
mv C:/nvm4w/nodejs/opencode.cmd C:/nvm4w/nodejs/opencode.cmd.disabled

重启 Tolaria 即可。不需要修改系统 PATH ——Tolaria 自己会扫 ~/.local/bin/claude.exe 候选路径。

坑二：OpenCode 报 “exit code: 1”

修完坑一之后 OpenCode 能启动了，但实际调用可能报：

1
Error: opencode exited with status exit code: 1

直接命令行跑 opencode run --format json "hi" 才能看到真实错误：

1
Model not found: opencode/glm-4.7-free. Did you mean: deepseek-v4-flash-free, glm-5, glm-5.1?

AI 给的原因分析：opencode-ai 1.15.x 的 run --format json 模式不读 disk 上的 ~/.config/opencode/opencode.json（不像交互模式），只认 -m 命令行参数；而 Tolaria 写死的命令是 ["run", "--format", "json"]，没传 -m。结果 OpenCode fallback 到内置 free 档位的默认 model opencode/glm-4.7-free ，这个 model 已被 OpenCode Zen 服务端下线。

临时解决方案：在 Tolaria UI 把 AI 默认目标切到 claude_code（设置里的 default_ai_target 字段）。等 Tolaria 后续版本透传 -m 参数后再切回 OpenCode。

坑三：Gemini 的警告被当成错误抛

Gemini 偶尔会显示这样的”错误”：

1
2
3
Error: Warning: Windows 10 detected. Some UI features like smooth scrolling may be degraded.
Warning: 256-color support not detected.
YOLO mode is enabled.

这其实是 Gemini CLI 自己向 stderr 输出的环境警告，不是真错误。Tolaria 的 format_gemini_error 在 Gemini 进程退出码非零时把 stderr 前 3 行原样转发，给人误判错误的观感。

临时缓解：

  • 在 Tolaria UI 把 Permission Mode 切到 Safe（避免 YOLO 模式触发 gemini-cli 内部判错）
  • 确保 vault 目录是 git 仓库（.git/ 存在）

更完整的踩坑分析、ADR 引用、修复方案对比，我整理了一份 tolaria-windows-ai-agent-fix.md。等作者更新吧

注意事项

  1. macOS 平台测试最充分：作者自己用 Mac 日常开发，macOS 下体验最完整；Windows / Linux 偶有上游 CLI 兼容性问题(见上节)
  2. AGENTS.md 文件：可以在每个 vault 根目录放一个 AGENTS.md，告诉 AI 代理这个 vault 的约定（类型定义、命名规范、目录布局）。它和 Claude Code 的 CLAUDE.md / Gemini 的 GEMINI.md 是同一类东西，Tolaria 启动 AI 代理时会让代理读这个文件
  3. 数据备份：vault 是 git 仓库，强烈建议 git remote 推到 GitHub / Gitea / 自建 git server。Tolaria 不替你管云端
  4. 多 vault：Tolaria 支持同时打开多个 vault，会在状态栏切换。但 AI 代理一次只能操作 active vault
  5. MCP server 反向连接：Tolaria 内嵌的 mcp-server 通过 WebSocket（默认 9711）反向连 Tolaria 主进程才能工作。所以从外部工具（如外部 Claude Code / OpenCode）调 Tolaria MCP 时，Tolaria 主进程必须在运行
  6. 稳定性预期：项目仅 3 个月，处于快速迭代期。如果想用稳定通道，在 settings 里把 release_channel 留空（默认 stable）；想吃最新功能可以切到 alpha

参考文档

refactoringhq/tolaria: A second brain for the AI era. Free forever.
地址：https://github.com/refactoringhq/tolaria

Tolaria 官方网站（含下载和完整文档）
地址：https://tolaria.md

Tolaria 安装指南
地址：https://tolaria.md/start/install

Tolaria AI 概念文档
地址：https://tolaria.md/concepts/ai

Tolaria Configure AI Models 指南
地址：https://tolaria.md/guides/configure-ai-models

Tolaria AI Agent Not Found 故障排查
地址：https://tolaria.md/troubleshooting/ai-agent-not-found

Getting Started Vault（含 walkthrough 的演示 vault）
地址：https://github.com/refactoringhq/tolaria-getting-started