Obsidian Headless

Obsidian Headless - 无头 Obsidian 管理工具

在无显示器/无 图形界面 环境下通过自然语言指令管理 Obsidian 笔记仓库。

适用场景 在 SSH 远程服务器上管理 Obsidian 笔记 无显示器环境（如 VPS、Docker 容器） 不想启动 Obsidian 图形界面 桌面应用时 需要通过脚本自动化管理笔记时 文档 USAGE.md - 完整使用手册（包含快速参考、详细说明、示例、故障排除） 目录结构 obsidian-headless/ ├── obs # 便捷入口脚本 ├── 安装.sh # 安装脚本 ├── 技能.md # 本文件（技能说明） ├── USAGE.md # 完整使用手册 ├── bin/ │ └── obsidian-headless.sh # 主程序 ├── examples/ │ └── examples.sh # 使用示例脚本 └── tests/ └── test.sh # 测试脚本

配置文件

首次使用时会提示输入仓库路径，配置保存在：

~/.config/obsidian-headless/vault-path

快速开始

• 安装

或手动使用：

~/.OpenClaw/技能s/obsidian-headless/obs "obs指令"

指令格式

所有指令都支持 obs 前缀（大小写不敏感），obs 和指令之间可以有空格、-、_、: 等连接符：

格式 示例 obs指令 obs创建笔记 新笔记 obs 指令 obs 创建笔记 新笔记 obs-指令 obs-创建笔记 新笔记 OBS指令 OBS创建笔记 新笔记

推荐使用 obs指令 格式，避免误触。

• 配置仓库路径

首次使用： 运行任意命令时会提示输入仓库路径，路径会保存到配置文件中供后续使用。

首次使用 Obsidian Headless ==========================

请输入 Obsidian 仓库路径: /home/user/my-vault ✓ 已保存配置

手动配置（可选）：

方式 1 - 环境变量（优先级最高）：

导出 OBSIDIAN_VAULT=/path/to/your/vault

方式 2 - 删除配置文件重新输入：

rm ~/.config/obsidian-headless/vault-path # 下次运行时会重新提示输入

• 使用

# 或直接调用 ~/.OpenClaw/技能s/obsidian-headless/obs "搜索内容 home 助手"

支持的指令 创建笔记 obs创建笔记 [文件名] [可选内容]

说明：

文件名 支持路径，如 文件夹/笔记名 或 笔记名 如果只输入文件名（无内容），创建空笔记文件 如果输入了内容，内容直接写入文件，不会自动添加标题 笔记的标题需要用户在 内容 中自行定义（如 # 我的标题） 文件名和内容之间可以用空格或换行符分隔

示例：

obs创建笔记 待办清单 → 创建空文件 待办清单.md obs创建笔记 项目想法 这个项目的核心目标是... → 文件内容为 "这个项目的核心目标是..." obs创建笔记 AI/总结 # AI 总结\n\n今天学习了... → 文件内容包含自定义标题

多行内容示例：

obs创建笔记 笔记名 # 标题 内容第一行 内容第二行

删除笔记（带确认） obs删除笔记 [文件名]

删除确认流程：

单个匹配时：

即将删除笔记: 标题: xxx 路径: /path/to/xxx.md

内容预览 (共 15 行): # xxx ...

请回复确认: [Y] 确认删除 [N] 取消

多个匹配时：

找到多个匹配的笔记:

[1] 笔记A 位置: folder1/ 大小: 20 行

[2] 笔记B 位置: folder2/ 大小: 35 行

请回复要删除的笔记编号 (或 0 取消)

查看笔记内容 obs查看笔记 [文件名]

搜索笔记标题 obs搜索标题 [关键词]

搜索笔记内容 obs搜索内容 [关键词]

模糊搜索（标题+内容） obs模糊搜索 [关键词]

创建/打开今天日记 obs今天日记 [可选内容]

自动在 日记/ 文件夹下创建 YYYY-MM-DD.md

修改库路径 obs修改库路径 obs修改库目录 obs更改路径 obs切换仓库

交互式修改仓库路径，保存到配置文件。

示例：

obs修改库路径 → 提示输入新路径 obs-修改库目录 → 同上 列出所有笔记 obs列出所有

列出所有文件夹 obs列出文件夹

显示最近修改的笔记 obs最近笔记

前置要求

Obsidian 仓库： 首次使用时会提示输入仓库路径

依赖:

bash (必须) find (必须) grep (必须) ripgrep (rg) (推荐，搜索更快)

安装 ripgrep：

# Ubuntu/Debian sudo apt 安装 ripgrep

# macOS brew 安装 ripgrep

测试

运行测试脚本验证功能：

cd ~/.OpenClaw/技能s/obsidian-headless ./tests/test.sh

查看示例

运行示例脚本查看各种用法：

cd ~/.OpenClaw/技能s/obsidian-headless ./examples/examples.sh

与 obsidian-命令行工具 的对比 功能 obsidian-命令行工具 obsidian-headless 依赖 Obsidian 图形界面 是（需要索引） 否 搜索-content 依赖索引，常失败 使用 ripgrep，可靠 删除确认 无 有（显示预览） 多匹配处理 无 列出序号选择 自然语言支持 有限 完整支持 无头环境 不支持 专门设计 故障排除 提示"未找到 Obsidian 仓库路径" 首次使用时会自动提示输入路径 或手动设置环境变量： 导出 OBSIDIAN_VAULT=/path/to/your/vault

或删除配置重新输入： rm ~/.config/obsidian-headless/vault-path

修改已保存的仓库路径 # 方法1: 使用环境变量覆盖 导出 OBSIDIAN_VAULT=/new/path

# 方法2: 删除配置，下次重新输入 rm ~/.config/obsidian-headless/vault-path

搜索速度慢

安装 ripgrep：

sudo apt 安装 ripgrep # Ubuntu/Debian brew 安装 ripgrep # macOS

删除时找不到笔记

使用更精确的标题，或使用"模糊搜索"先找到准确标题。

脚本说明 脚本 用途 obs 便捷入口，推荐日常使用 bin/obsidian-headless.sh 主程序 安装.sh 安装脚本，设置别名和快捷方式 tests/test.sh 功能测试 examples/examples.sh 使用示例