URI 协议
概述
Obsidian URI 协议允许你通过 URL 来控制 Obsidian，非常适合自动化工作流、外部工具集成和跨应用操作。
版本说明
URI 协议是 Obsidian 的核心功能，所有版本均支持。v1.11+ 新增了 paneType 参数。
URI 安全策略
1.13 曾引入外部 URI 安全确认弹窗，但在 1.13.6（2026-08-10）已移除。升级到 1.13.6+ 后，调用 obsidian:// 等 URI 不再弹出确认对话框，依赖 URI 的自动化（快捷指令、命令行、AutoHotkey、第三方工具如 Advanced URI）可无感执行。
在 1.13.6 前的版本（1.13 → 1.13.5）调用 URI 时会先弹出安全确认对话框，可勾选「不再询问」加入允许列表。若你的环境仍在使用旧版本，请留意首次触发时的人工确认。
基本语法
URI 格式
url
obsidian://action?param1=value1¶m2=value2参数编码
- 空格编码为
%20 - 特殊字符需要 URL 编码
- 仓库名和文件名需要编码
支持的操作
打开仓库
url
obsidian://open?vault=仓库名称打开文件
url
# 按仓库名和文件名打开
obsidian://open?vault=我的笔记&file=笔记名称
# 打开指定路径的文件
obsidian://open?vault=我的笔记&file=文件夹/子文件夹/笔记
# 打开并跳转到标题
obsidian://open?vault=我的笔记&file=笔记名称%23标题名创建新笔记
url
# 创建新笔记
obsidian://new?vault=我的笔记&name=新笔记名称
# 创建并写入内容
obsidian://new?vault=我的笔记&name=新笔记&content=笔记内容
# 指定保存路径
obsidian://new?vault=我的笔记&name=新笔记&path=文件夹/新笔记.md搜索
url
# 打开搜索面板
obsidian://search?vault=我的笔记
# 执行搜索
obsidian://search?vault=我的笔记&query=搜索关键词追加内容
url
# 追加到现有笔记
obsidian://append?vault=我的笔记&file=目标笔记&content=追加的内容
# 在后台追加（不打开窗口）
obsidian://append?vault=我的笔记&file=目标笔记&content=内容&silent=true插入内容
url
# 在光标位置插入（需打开笔记）
obsidian://insert?vault=我的笔记&file=目标笔记&content=插入内容执行命令
url
# 执行 Obsidian 命令
obsidian://command?vault=我的笔记&command=command-id
# 常用命令示例
obsidian://command?vault=我的笔记&command=app:open-vault
obsidian://command?vault=我的笔记&command=daily-notes
obsidian://command?vault=我的笔记&command=app:toggle-left-sidebar参数详解
vault（仓库参数）
指定目标仓库，支持两种方式：
| 方式 | 说明 | 示例 |
|---|---|---|
| 名称 | 仓库名称 | vault=我的笔记 |
| UID | 仓库唯一标识 | vault=abc123 |
paneType（打开方式）
v1.11+ 新增
控制文件打开的窗格类型。
| 值 | 说明 |
|---|---|
tab | 在新标签页打开（默认） |
split | 在分栏中打开 |
window | 在新窗口打开（仅桌面端） |
url
# 在新窗口打开
obsidian://open?vault=我的笔记&file=笔记&paneType=window
# 在分栏中打开
obsidian://open?vault=我的笔记&file=笔记&paneType=split编码处理
python
# Python 编码示例
import urllib.parse
vault = "我的笔记"
file = "文件夹/笔记名称"
content = "笔记内容，包含空格和特殊字符！"
encoded_vault = urllib.parse.quote(vault)
encoded_file = urllib.parse.quote(file)
encoded_content = urllib.parse.quote(content)
uri = f"obsidian://new?vault={encoded_vault}&file={encoded_file}&content={encoded_content}"
print(uri)使用场景
浏览器书签
将常用操作保存为浏览器书签：
url
<!-- 快速打开日记 -->
obsidian://open?vault=我的笔记&file=日记/2024-02-23
<!-- 快速创建会议笔记 -->
obsidian://new?vault=我的笔记&name=会议记录&path=会议/
<!-- 快速搜索待办事项 -->
obsidian://search?vault=我的笔记&query=tag:#待办iOS 快捷指令
在 iOS Shortcuts 中使用：
yaml
URL 操作:
1. 添加「URL」操作
2. 输入: obsidian://open?vault=我的笔记&file=今日任务
3. 添加「打开 URL」操作macOS 自动化
使用 AppleScript 或 Shortcuts：
applescript
-- AppleScript 打开 Obsidian
tell application "Obsidian"
open location "obsidian://open?vault=我的笔记&file=日记"
end tell其他工具集成
Alfred Workflow
bash
# Alfred Script Filter
obsidian://search?vault=我的笔记&query={query}VS Code Tasks
json
{
"label": "Open in Obsidian",
"type": "shell",
"command": "open",
"args": ["obsidian://open?vault=我的笔记&file=${fileBasenameNoExtension}"]
}Terminal
bash
# macOS
open "obsidian://open?vault=我的笔记&file=笔记"
# Linux
xdg-open "obsidian://open?vault=我的笔记&file=笔记"
# Windows
start "obsidian://open?vault=我的笔记&file=笔记"命令 ID 参考
常用命令
| 命令 ID | 功能 |
|---|---|
app:open-vault | 打开仓库 |
app:reload | 重新加载 |
app:toggle-left-sidebar | 切换左侧边栏 |
app:toggle-right-sidebar | 切换右侧边栏 |
command-palette:open | 打开命令面板 |
daily-notes | 打开日记 |
file-explorer:new-file | 新建笔记 |
graph:open | 打开图谱 |
markdown:toggle-preview | 切换预览 |
switcher:open | 打开快速切换 |
获取命令 ID
- 打开设置 → 快捷键
- 找到目标命令
- 点击命令右侧的「复制命令 ID」
安全注意事项
注意事项
- URI 操作会直接修改你的笔记
- 谨慎处理来自不可信来源的 URI 链接
- 追加操作可能覆盖重要内容
权限确认
1.13.6+ 已移除确认弹窗：自 1.13.6 起，外部 URI 调用不再弹出确认对话框。此前的确认机制（信任此域名 / 允许一次 / 拒绝）仅适用于 1.13 → 1.13.5 期间的旧版本。
首次使用 URI 时（1.13 → 1.13.5），Obsidian 会请求确认：
- 信任此域名：始终允许来自该域的请求
- 允许一次：仅本次允许
- 拒绝：拒绝本次请求
调试技巧
测试 URI
在浏览器地址栏直接输入 URI 测试：
url
obsidian://open?vault=我的笔记&file=测试笔记检查编码
使用浏览器开发者工具：
javascript
// 解码 URI
decodeURIComponent("obsidian://open?vault=%E6%88%91%E7%9A%84%E7%AC%94%E8%AE%B0")
// 编码参数
encodeURIComponent("我的笔记")下一步
- 命令行界面 (CLI) - 终端控制 Obsidian
- iOS 快捷指令 - iOS 自动化集成
- 自动化工作流 - 构建自动化流程