Obsidian URI Scheme 调用文档

更新日期: 2026-03-14
文档版本: 1.0

Obsidian URI Scheme 调用文档

更新日期: 2026-03-14 文档版本: 1.0

目录

  1. URI Scheme 概述
  2. 原生 URI API
  3. Advanced URI 插件
  4. 跨平台调用
  5. 与其他应用集成
  6. 实用脚本示例

一、URI Scheme 概述

1.1 什么是 URI Scheme？

URI Scheme 是 Obsidian 的自定义 URL 协议，允许通过 URL 触发 Obsidian 操作：

obsidian://动作?参数1=值1&参数2=值2

1.2 两种 URI 方式

方式 插件 功能范围
原生 URI 内置 基础操作（打开、新建、搜索）
Advanced URI 需安装 高级操作（追加、执行命令、设置）

1.3 使用场景

┌─────────────────────────────────────────────────────────────┐
│                    URI Scheme 使用场景                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  🔗 网页链接                                                 │
│     └── 点击网页链接打开笔记                                 │
│                                                             │
│  📱 快捷指令 (Shortcuts/Raycast)                             │
│     └── 一键创建/追加笔记                                    │
│                                                             │
│  🤖 脚本自动化                                               │
│     └── Python/Shell 调用                                   │
│                                                             │
│  📋 其他应用                                                 │
│     └── Alfred/Keyboard Maestro/启动器                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

二、原生 URI API

2.1 基础格式

obsidian://动作?vault=仓库名&参数=值

2.2 支持的动作

open - 打开笔记

obsidian://open?vault=MyVault&file=Notes/MyNote
参数 必填 说明
vault ✅ 仓库名称
file ✅ 文件路径（相对于仓库根目录）

示例:

# 打开根目录笔记
obsidian://open?vault=MyVault&file=README.md

# 打开子文件夹中的笔记
obsidian://open?vault=MyVault&file=Projects/App/Design.md

# 打开并定位到标题
obsidian://open?vault=MyVault&file=Notes/MyNote%23Section

new - 新建笔记

obsidian://new?vault=MyVault&name=NewNote
参数 必填 说明
vault ✅ 仓库名称
name ✅ 笔记名称
content ❌ 初始内容
path ❌ 保存路径

示例:

# 新建空白笔记
obsidian://new?vault=MyVault&name=MyNewNote

# 新建带内容的笔记
obsidian://new?vault=MyVault&name=MyNote&content=Hello%20World

# 指定路径
obsidian://new?vault=MyVault&name=MyNote&path=Notes/

search - 搜索

obsidian://search?vault=MyVault&query=关键词
参数 必填 说明
vault ✅ 仓库名称
query ✅ 搜索关键词

示例:

obsidian://search?vault=MyVault&query=机器学习

daily - 打开日记

obsidian://daily?vault=MyVault

三、Advanced URI 插件

3.1 安装

  1. 设置 → 第三方插件 → 浏览
  2. 搜索 "Advanced URI"
  3. 安装并启用

3.2 基础格式

obsidian://advanced-uri?vault=MyVault&参数=值

3.3 支持的动作

新建笔记 (new)

obsidian://advanced-uri?vault=MyVault&filepath=Notes/NewNote.md&data=内容
参数 说明
filepath 文件路径（含扩展名）
data 笔记内容
mode overwrite / append / prepend
openmode 打开方式

追加内容 (append)

obsidian://advanced-uri?vault=MyVault&filepath=Notes/MyNote.md&data=追加内容&mode=append

读取笔记 (read)

obsidian://advanced-uri?vault=MyVault&filepath=Notes/MyNote.md&mode=read

打开设置

obsidian://advanced-uri?vault=MyVault&settingid=editor

可用的设置 ID: - editor - 编辑器 - file - 文件与链接 - appearance - 外观 - hotkeys - 快捷键 - core-plugins - 核心插件

执行命令

obsidian://advanced-uri?vault=MyVault&commandid=editor:save-file

常用命令 ID: | 命令 | ID | |------|-----| | 保存 | editor:save-file | | 撤销 | editor:undo | | 重做 | editor:redo | | 切换预览 | markdown:toggle-preview | | 搜索 | editor:open-search |

打开工作区

obsidian://advanced-uri?vault=MyVault&workspace=MyWorkspace

创建日记

obsidian://advanced-uri?vault=MyVault&daily=true&data=日记内容&mode=append

3.4 x-callback-url 支持

Advanced URI 支持 x-callback-url 协议：

obsidian://advanced-uri?vault=MyVault&filepath=Test.md&x-success=myapp://success&x-error=myapp://error

四、跨平台调用

4.1 macOS

# 使用 open 命令
open "obsidian://open?vault=MyVault&file=Notes/MyNote"

# AppleScript
osascript -e 'open location "obsidian://new?vault=MyVault&name=NewNote"'

4.2 Windows

# PowerShell
Start-Process "obsidian://open?vault=MyVault&file=Notes/MyNote"

# CMD
start "" "obsidian://open?vault=MyVault&file=Notes/MyNote"

4.3 Linux

# xdg-open
xdg-open "obsidian://open?vault=MyVault&file=Notes/MyNote"

# gtk-launch
gtk-launch obsidian "obsidian://open?vault=MyVault&file=Notes/MyNote"

4.4 iOS

# Shortcuts 中使用
URL: obsidian://new?vault=MyVault&name=QuickNote

# 从其他 App 调用
UIApplication.shared.open(URL(string: "obsidian://daily?vault=MyVault")!)

4.5 Android

// Kotlin
val intent = Intent(Intent.ACTION_VIEW, Uri.parse("obsidian://open?vault=MyVault&file=Notes/MyNote"))
startActivity(intent)

五、与其他应用集成

5.1 macOS Shortcuts

┌─────────────────────────────────────────────────────────────┐
│  快捷指令: 快速收集                                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 获取剪贴板内容                                          │
│     ↓                                                       │
│  2. 询问输入标题                                            │
│     ↓                                                       │
│  3. URL 操作                                                │
│     obsidian://new?vault=MyVault&name=[标题]&content=[内容] │
│     ↓                                                       │
│  4. 打开 URL                                                │
│     ↓                                                       │
│  5. 显示通知 "已保存到 Obsidian"                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

5.2 Raycast 扩展

// Raycast Extension
import { showToast, Toast, LaunchProps } from "@raycast/api";

interface Arguments {
  content: string;
}

export default async function (props: LaunchProps<{ arguments: Arguments }>) {
  const content = encodeURIComponent(props.arguments.content);
  const url = `obsidian://new?vault=MyVault&name=QuickNote&content=${content}`;

  // 打开 URL
  await open(url);

  await showToast(Toast.Style.Success, "已保存到 Obsidian");
}

5.3 Alfred Workflow

# Alfred Script Filter
#!/bin/bash

QUERY="{query}"
ENCODED_QUERY=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$QUERY'))")

# 追加到今日日记
open "obsidian://advanced-uri?vault=MyVault&daily=true&mode=append&data=$ENCODED_QUERY"

5.4 Keyboard Maestro

Macro: 快速追加到日记
Trigger: ⌃⌥D
Actions:
  1. Get Clipboard
  2. Execute Shell Script:
     open "obsidian://advanced-uri?vault=MyVault&daily=true&mode=append&data=$(pbpaste)"

5.5 网页集成

<!-- 在网页中添加链接 -->
<a href="obsidian://open?vault=MyVault&file=Notes/MyNote">
  在 Obsidian 中打开
</a>

<a href="obsidian://new?vault=MyVault&name=FromWeb&content=Hello">
  创建新笔记
</a>

5.6 VS Code 集成

// tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Open in Obsidian",
      "type": "shell",
      "command": "open",
      "args": [
        "obsidian://open?vault=MyVault&file=${file}"
      ],
      "problemMatcher": []
    }
  ]
}

六、实用脚本示例

6.1 Python 快速收集脚本

#!/usr/bin/env python3
"""
Obsidian 快速收集工具
使用 URI Scheme 追加内容到日记
"""

import subprocess
import urllib.parse
import sys
from datetime import datetime

def open_url(url: str):
    """跨平台打开 URL"""
    import platform
    system = platform.system()

    if system == "Darwin":  # macOS
        subprocess.run(["open", url])
    elif system == "Windows":
        subprocess.run(["start", "", url], shell=True)
    else:  # Linux
        subprocess.run(["xdg-open", url])

def quick_capture(content: str, vault: str = "MyVault"):
    """快速收集到 Inbox"""
    encoded = urllib.parse.quote(content)
    url = f"obsidian://new?vault={vault}&name=QuickNote&content={encoded}"
    open_url(url)

def append_daily(content: str, vault: str = "MyVault"):
    """追加到今日日记"""
    timestamp = datetime.now().strftime("%H:%M")
    full_content = f"\n## {timestamp}\n{content}"
    encoded = urllib.parse.quote(full_content)
    url = f"obsidian://advanced-uri?vault={vault}&daily=true&mode=append&data={encoded}"
    open_url(url)

def search(query: str, vault: str = "MyVault"):
    """搜索笔记"""
    encoded = urllib.parse.quote(query)
    url = f"obsidian://search?vault={vault}&query={encoded}"
    open_url(url)

# 命令行入口
if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法: obsidian-capture.py <内容>")
        sys.exit(1)

    content = " ".join(sys.argv[1:])
    append_daily(content)
    print(f"✓ 已追加到日记: {content}")

6.2 Shell 快捷函数

# 添加到 ~/.zshrc 或 ~/.bashrc

# 追加到日记
obs-daily() {
    local content="$*"
    local encoded=$(python3 -c "import urllib.parse; print(urllib.parse.quote('\n## $(date +%H:%M)\n$content'))")
    open "obsidian://advanced-uri?vault=MyVault&daily=true&mode=append&data=$encoded"
    echo "✓ 已追加到日记"
}

# 快速收集
obs-capture() {
    local content="$*"
    local encoded=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$content'))")
    open "obsidian://new?vault=MyVault&name=Capture-$(date +%Y%m%d%H%M%S)&content=$encoded"
    echo "✓ 已收集"
}

# 搜索
obs-search() {
    local query="$*"
    open "obsidian://search?vault=MyVault&query=$query"
}

# 打开笔记
obs-open() {
    local file="$1"
    open "obsidian://open?vault=MyVault&file=$file"
}

使用示例:

# 追加到日记
obs-daily "完成了项目文档的编写"

# 快速收集
obs-capture "看到一个有趣的想法"

# 搜索
obs-search "机器学习"

# 打开笔记
obs-open "Projects/MyApp/设计.md"

6.3 自动化 Cron 任务

# crontab -e

# 每天早上 8 点创建日记
0 8 * * * open "obsidian://daily?vault=MyVault"

# 每周五下午 5 点打开周回顾
0 17 * * 5 open "obsidian://open?vault=MyVault&file=Reviews/Weekly.md"

七、URI vs REST API 对比

特性 URI Scheme Local REST API
安装 内置/插件 需要插件
功能 基础/中等 完整
调用方式 URL HTTP 请求
需要运行 否 是
安全性 无认证 API Key
跨设备 是 仅本地
适合场景 快捷操作 复杂自动化

八、常见问题

Q1: URI 不生效？

检查： 1. Obsidian 是否正在运行 2. 仓库名称是否正确（区分大小写） 3. URL 编码是否正确

Q2: 如何获取仓库名称？

在 Obsidian 左下角查看仓库名称，或查看仓库文件夹名称。

Q3: 特殊字符如何处理？

使用 URL 编码： | 字符 | 编码 | |------|------| | 空格 | %20 | | # | %23 | | / | %2F | | ? | %3F | | & | %26 |

九、参考资源

  • 官方文档: https://help.obsidian.md/Extending+Obsidian/Obsidian+URI
  • Advanced URI: https://github.com/Vinzent03/obsidian-advanced-uri
  • 中文教程: https://pkmer.cn

文档生成时间: 2026-03-14