Obsidian Sync

核心用法

obsidian-sync 是一个轻量级文件同步服务器，作为 OpenClaw Obsidian 插件 的后端组件运行。用户通过 Node.js 启动本地服务，绑定指定工作目录，即可在 Obsidian 笔记库与 Clawdbot 代理工作空间之间建立双向同步通道。

典型工作流程：
1. 配置环境变量（SYNC_TOKEN、SYNC_WORKSPACE、SYNC_ALLOWED_PATHS）
2. 启动同步服务器（默认端口 18790）
3. 配合 Obsidian 插件进行实时文件读写、冲突检测与版本同步
4. 可选通过 Tailscale serve 实现安全远程访问

API 设计精简： 提供状态检查、目录列表、文件读取、带冲突检测的写入四个核心端点，覆盖笔记管理全生命周期。

显著优点

| 维度 | 亮点 |

|------|------|

| **生态整合** | 与 OpenClaw 插件深度耦合，形成「聊天→操作→同步」完整闭环 |

| **安全模型** | 路径白名单机制 + Bearer Token 认证 + 自动拦截目录遍历攻击 |

| **部署灵活** | 支持本地开发、systemd 用户服务、Tailscale 内网穿透多种模式 |

| **冲突处理** | 写入接口内置冲突检测逻辑，降低多终端编辑覆盖风险 |

| **密钥管理** | Obsidian 端集成 OS 钥匙串，避免明文存储敏感 token |

潜在缺点与局限性

• 单点依赖：必须配合 Obsidian 插件使用，脱离前端则仅为原始文件 API，价值大幅缩水
• 无原生加密：传输层依赖用户自行配置 HTTPS（Tailscale 或反向代理），默认 HTTP 存在中间人风险
• 冲突策略保守：检测到冲突时行为未明确说明（覆盖/合并/提示），可能产生人工处理成本
• Node.js 运行时依赖：对非技术用户不够友好，需手动维护 Node 环境与服务进程
• 社区规模有限：GitHub 星数与维护者单一（AndyBold），长期可持续性存观察空间

适合人群

• 已在 Obsidian 构建第二大脑的知识管理重度用户
• 希望将 AI 对话与笔记系统打通的 Clawdbot 早期采用者
• 具备基础 Linux/Node.js 运维能力的技术型用户
• 接受「本地服务 + 内网穿透」架构的隐私敏感型用户

常规风险

| 风险类别 | 具体说明 | 缓释建议 |

|---------|---------|---------|

| 令牌泄露 | SYNC_TOKEN 若泄露可导致工作空间文件被读写 | 使用 Clawdbot Gateway Token、定期轮换、限制 SYNC_ALLOWED_PATHS 最小范围 |

| 路径遍历绕过 | 服务端虽拦截 `../`，但自定义配置或版本回退可能引入漏洞 | 保持技能更新、审计 allowed paths 配置 |

| 数据丢失 | 同步冲突处理不当或客户端 bug 可能导致笔记覆盖 | 开启 Obsidian 原生版本历史、定期 vault 备份 |

| 服务可用性 | Node 进程崩溃或端口冲突导致同步中断 | 配置 systemd 自动重启、监控 `/sync/status` 健康端点 |

核心用法

obsidian-sync 是一个轻量级 Node.js 文件同步服务器，用于在 Clawdbot AI 工作区与 Obsidian 笔记库之间实现双向 Markdown 文件同步。用户启动服务后，配合 OpenClaw Obsidian 插件即可完成：笔记列表获取、文件读取、带冲突检测的写入等操作。

快速启动：设置 SYNC_TOKEN 环境变量后运行 node scripts/sync-server.mjs，服务默认监听 localhost:18790，可通过 Tailscale 安全暴露至远程。

典型工作流：
1. 在 Obsidian 中通过侧边栏与 Clawdbot 对话
2. 直接让 AI 创建、编辑或删除笔记
3. 双向自动同步保持两端内容一致

显著优点

| 优势 | 说明 |

|------|------|

| **零依赖架构** | 仅使用 Node.js 内置模块（http/fs/path/crypto），彻底消除供应链攻击风险 |

| **纵深防御设计** | 路径遍历防护（阻止 `../`）、绝对路径拒绝、目录白名单、仅允许 `.md` 文件 |

| **乐观锁冲突检测** | 基于 MD5 哈希的版本校验，防止并发写入导致数据丢失 |

| **最小权限原则** | 默认绑定 localhost、无外部 API 调用、无硬编码敏感信息 |

| **生产级部署支持** | 提供 systemd 服务配置示例，支持 loginctl 开机自启 |

潜在缺点与局限性

• 无加密传输：本地 HTTP 明文通信，公网暴露需配合 Tailscale/Nginx 等反向代理
• 无速率限制：高并发场景缺乏请求限流保护
• 无访问日志：当前版本未记录操作审计日志，故障排查依赖手动调试
• 无文件大小限制：大文件上传可能导致磁盘资源耗尽
• 单文件架构：409 行代码承载全部功能，长期维护性有限

适合人群

• Obsidian 重度用户：希望将 AI 对话能力与本地笔记库深度整合
• 隐私敏感用户：数据完全本地化处理，无需上传云端
• 开发者/极客用户：理解环境变量配置、systemd 服务管理、Tailscale 网络隧道
• 不适合：寻求开箱即用图形界面、或无 Node.js 运行环境的普通用户

常规风险

| 风险类型 | 等级 | 说明 |

|----------|------|------|

| 路径遍历攻击 | 极低 | 已实现多层防护，通过安全认证 |

| Token 泄露 | 中 | Bearer Token 需妥善保管，建议定期轮换 |

| 本地网络嗅探 | 低 | localhost 通信无加密，共享主机环境需注意 |

| 供应链攻击 | 极低 | 零第三方依赖，无可利用的攻击面 |

使用建议：生产环境务必通过 Tailscale serve 或 HTTPS 反向代理暴露服务，避免直接公网访问 plaintext HTTP。