https://obsidian.md/help/uri

Obsidian URI 是一种自定义 URI 协议（`obsidian://`），用于从外部应用触发 Obsidian 的各种操作，实现自动化与跨应用工作流。

#### URI 通用格式

`obsidian://action?param1=value&param2=value`

**重要提示**：参数值必须进行 **URI 编码**，如空格  需编码为 `%20`，正斜杠 `/` 需编码为 `%2F`。

---

### 支持的动作一览

|动作|功能说明|
|---|---|
| `open` |打开仓库或仓库内的笔记|
| `new` |创建新笔记（或添加到已有笔记）|
| `daily` |创建/打开每日笔记（需启用 Daily notes 插件）|
| `unique` |创建唯一笔记（需启用 Unique note creator 插件）|
| `search` |打开搜索面板并可选执行搜索|
| `choose-vault` |打开仓库管理器|
| `hook-get-address` |与 Hook 应用集成使用|

---

### 各动作详解

#### 1. `open` — 打开笔记/仓库

**示例**

```text
// 仅打开仓库
obsidian://open?vault=my%20vault
// 通过仓库 ID 打开（更稳定）
obsidian://open?vault=ef6ca3e3b524d22f
// 打开仓库中的指定笔记
obsidian://open?vault=my%20vault&file=my%20note
// 通过绝对路径打开（自动定位仓库）
obsidian://open?path=%2Fhome%2Fuser%2Fmy%20vault%2Fpath%2Fto%2Fnote
// 打开笔记中的标题或块
obsidian://open?vault=my%20vault&file=note%23Heading
obsidian://open?vault=my%20vault&file=note%23%5EBlock
```

**参数说明**

|参数|说明|
|---|---|
| `vault` |仓库名称或仓库 ID（推荐使用 ID，避免改名后失效）|
| `file` |文件名（可省略 `.md`）或从仓库根目录起的路径|
| `path` |文件的绝对路径，使用此参数将覆盖 `vault` 和 `file` |
| `prepend` |将内容添加到文件顶部，并尝试合并属性|
| `append` |将内容添加到文件末尾，并尝试合并属性|
| `paneType` |指定打开位置：`tab`（新标签页）/ `split`（新分屏）/ `window`（新窗口，仅桌面版）|

> **获取仓库 ID**：在仓库切换器中，右键点击目标仓库，选择“复制仓库 ID”。

#### 2. `new` — 创建新笔记

**示例**

```text
// 在默认位置创建
obsidian://new?vault=my%20vault&name=my%20note
// 在指定路径创建
obsidian://new?vault=my%20vault&file=path%2Fto%2Fmy%20note
```

**参数说明**

|参数|说明|
|---|---|
| `vault` |仓库名称或仓库 ID|
| `name` |文件名（存放在“新笔记默认位置”）|
| `file` |仓库内的完整路径（含名称），会覆盖 `name` |
| `path` |系统绝对路径，会覆盖 `vault` 和 `file` |
| `content` |笔记内容（需编码）|
| `clipboard` |使用剪贴板内容作为笔记内容|
| `silent` |包含此参数则不打开新笔记|
| `append` |若文件已存在则追加内容|
| `overwrite` |若文件已存在则覆盖（优先级低于 `append`）|
| `paneType` |同 `open` 动作|
| `x-success` / `x-error` |用于回调的 URL|

#### 3. `daily` — 每日笔记

**前置条件**：需启用 Daily notes 插件。

**示例**


obsidian://daily?vault=my%20vault

**参数**：同 `new` 动作。

#### 4. `unique` — 唯一笔记

**前置条件**：需启用 Unique note creator 插件。

**示例**


obsidian://unique?vault=my%20vault
obsidian://unique?vault=my%20vault&content=Hello%20World

**参数**：支持 `vault`, `paneType`, `content`, `clipboard`, `x-success`。

#### 5. `search` — 打开搜索

**示例**



// 仅打开搜索面板
obsidian://search?vault=my%20vault
// 打开并执行搜索
obsidian://search?vault=my%20vault&query=Obsidian

**参数**：`vault`（必填），`query`（搜索词，可选）。

#### 6. `choose-vault` — 打开仓库管理器

**示例**



obsidian://choose-vault

**参数**：无。

#### 7. `hook-get-address` — 与 Hook 集成

**示例**



obsidian://hook-get-address

**参数**：

- `vault`（可选）：不提供则使用当前/最后聚焦的仓库。
    
- `x-success` / `x-error`：用于回调。
    

**行为**：若提供 `x-success`，回调返回 `name`、`url`、`file`；否则将当前笔记的 `obsidian://open` 链接复制到剪贴板。

---

### x-callback-url 参数

部分动作支持 `x-success` 和 `x-error`，用于跨应用回调。

**回调返回参数**：

|参数|说明|
|---|---|
| `name` |文件名（不含扩展名）|
| `url` |该笔记的 `obsidian://` URI|
| `file` |该笔记的 `file://` URL（仅桌面版）|

**示例**：  
原始 URI：`obsidian://...?x-success=myapp://x-callback-url`  
回调结果：`myapp://x-callback-url?name=note&url=obsidian%3A%2F%2Fopen...&file=file%3A%2F%2F...`

---

### 速记格式

两种快捷写法，等价于对应的 `open` 动作：

|速记格式|等价完整格式|
|---|---|
| `obsidian://vault/仓库名/笔记名` | `obsidian://open?vault=仓库名&file=笔记名` |
| `obsidian:///绝对路径/到/笔记` | `obsidian://open?path=绝对路径/到/笔记` |

**示例**：


obsidian://vault/my%20vault/my%20note
obsidian:///home/user/my%20vault/note.md

---

### 故障排查：注册 Obsidian URI

- **Windows / macOS**：运行一次 Obsidian 即可自动注册 URI 协议。
    
- **Linux**：需要手动配置，确保 `.desktop` 文件的 `Exec` 字段指定为 `Exec=可执行文件路径 %u`，其中 `%u` 用于传递 `obsidian://` URI。