OpenClaw Skills Obsidian命令行工具技能手册

一、Obsidian-CLI 概述

Obsidian-CLI 是 Obsidian 笔记工具的命令行操作工具，可实现 Obsidian 笔记库（Vault）的自动化管理，无需手动打开 Obsidian 客户端即可完成笔记创建、搜索、移动、删除等核心操作，还能自动更新库内的 Wiki 链接和 Markdown 链接，是提升 Obsidian 批量操作效率的核心工具。

👤 作者：Peter Steinberger
👉 Skills 下载地址：obsidian-1.0.0.zip

二、环境准备与安装

2.1 系统兼容说明

Obsidian-CLI 优先支持 macOS 系统，基于 brew 包管理器安装；Linux/Windows 系统可通过源码编译或第三方适配方案使用（本文以 macOS 为例）。

2.2 安装步骤（带中文注释）

## 第一步：确保 brew 包管理器已安装（未安装则执行下方命令）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"


## 第二步：添加 Obsidian-CLI 的 brew 源（专属源，用于拉取工具包）
brew tap yakitrak/yakitrak


## 第三步：安装 Obsidian-CLI 核心工具
brew install obsidian-cli


## 第四步：验证安装是否成功（输出版本号即代表安装完成）
obsidian-cli --version

三、Obsidian Vault（笔记库）核心概念

3.1 Vault 本质

Obsidian 的笔记库（Vault）是本地磁盘上的普通文件夹，所有笔记、配置、附件均存储在该文件夹内，可通过任意编辑器修改，Obsidian 客户端会自动同步修改内容。

3.2 典型 Vault 目录结构（带中文注释）

你的Vault文件夹/
├── 日常笔记/          # 自定义笔记文件夹（可任意创建）
│   └── 2024年计划.md  # Markdown 格式笔记文件（核心存储载体）
├── .obsidian/         # Obsidian 配置目录（含插件、工作区设置，一般不手动修改）
│   ├── app.json       # 客户端基础配置
│   └── plugins/       # 已安装插件的配置文件
├── 项目画布.canvas     # Obsidian 画布文件（JSON 格式，可视化笔记关联）
└── 附件/              # 存储图片、PDF、音频等附件（路径可在 Obsidian 设置中自定义）

3.3 查找活跃 Vault 路径

## 方式1：获取 Obsidian 默认 Vault 的绝对路径（最常用）
obsidian-cli print-default --path-only  # 输出示例：/Users/你的用户名/Documents/我的Obsidian库


## 方式2：读取 macOS 下 Obsidian 配置文件，筛选已打开的 Vault（无默认时使用）
cat ~/Library/Application\ Support/obsidian/obsidian.json | grep -A 5 "open":true
## 注释：grep -A 5 表示匹配"open":true后，额外展示后续5行内容，便于定位Vault路径

四、Obsidian-CLI 核心命令（带中文注释）

4.1 基础配置：设置默认 Vault

## 设置默认 Vault（只需配置1次，后续命令无需重复指定Vault路径）
obsidian-cli set-default "我的Obsidian库"  
## 注释："我的Obsidian库" 是你本地Vault文件夹的名称，需与实际一致

4.2 笔记搜索：名称/内容检索

## 搜索笔记名称（模糊匹配，快速定位笔记）
obsidian-cli search "2024计划"  
## 输出示例：日常笔记/2024年计划.md


## 搜索笔记内容（精准检索，展示匹配片段+行号）
obsidian-cli search-content "项目复盘"  
## 注释：内容搜索会遍历所有.md文件，返回包含"项目复盘"的行及上下文，便于快速定位内容位置

4.3 笔记创建：指定路径+内容

## 创建新笔记，指定存储路径、内容，并自动打开Obsidian客户端
obsidian-cli create "工作笔记/2024Q2项目复盘" \
--content "# 2024Q2项目复盘\n1. 完成核心功能开发\n2. 待优化点：性能调优" \
--open
## 注释：
## 1. \ 是换行符，便于命令可读性；
## 2. --content 后为笔记内容，支持Markdown格式；
## 3. --open 参数表示创建后自动在Obsidian客户端打开该笔记

4.4 笔记移动/重命名：自动更新链接

## 移动（重命名）笔记，并自动更新库内所有关联的Wiki链接/Markdown链接
obsidian-cli move "工作笔记/2024Q2项目复盘" "复盘记录/2024/Q2项目复盘"
## 注释：Obsidian-CLI 核心优势，手动移动会导致链接失效，该命令自动修复所有关联链接

4.5 笔记删除：安全移除

## 删除指定笔记（比手动删除更安全，避免残留链接引用）
obsidian-cli delete "复盘记录/2024/Q2项目复盘"
## 注释：删除前建议先通过search-content确认是否有其他笔记引用该文件

五、实战教程：批量管理Obsidian笔记

5.1 场景1：批量创建月度复盘笔记

## 循环创建2024年1-12月的复盘笔记
for month in {1..12}; do
  # 拼接笔记路径和内容
  note_path="复盘记录/2024/${month}月复盘"
  note_content="# 2024年${month}月复盘\n## 完成事项\n## 待办事项\n## 问题总结"
  # 执行创建命令
  obsidian-cli create "${note_path}" --content "${note_content}"
  echo "已创建：${note_path}.md"
done
## 注释：
## 1. for循环遍历1-12月；
## 2. 动态拼接笔记路径和内容，实现批量创建；
## 3. echo 输出创建日志，便于核对创建结果

5.2 场景2：批量替换笔记内的关键词

## 步骤1：查找包含"旧项目名称"的所有笔记路径
note_paths=$(obsidian-cli search-content "旧项目名称" | grep -o "/.*\.md" | uniq)


## 步骤2：遍历笔记路径，替换关键词（需结合sed命令）
for path in $note_paths; do
  # 拼接完整的Vault路径（需替换为你的实际Vault路径）
  full_path="/Users/你的用户名/Documents/我的Obsidian库/${path}"
  # 替换关键词：将"旧项目名称"改为"新项目名称"
  sed -i '' 's/旧项目名称/新项目名称/g' "${full_path}"
  echo "已更新：${full_path}"
done
## 注释：
## 1. grep -o 提取笔记路径，uniq 去重；
## 2. sed -i '' 是macOS下的替换命令（Linux无需''）；
## 3. 该操作直接修改本地.md文件，Obsidian客户端会自动同步

六、常见问题与排错