obsidian-direct

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

obsidian-direct

Purpose

用途

This skill enables direct programmatic access to Obsidian vaults for tasks like file creation, editing, template insertion, Dataview queries, and plugin API calls, allowing automation of note-taking workflows.

本Skill可实现对Obsidian库的程序化直接访问，支持文件创建、编辑、模板插入、Dataview查询和插件API调用等任务，从而自动化笔记工作流。

When to Use

使用场景

Use this skill for automating Obsidian interactions in scripts, such as generating daily notes from external data, updating files based on user input, or running Dataview queries to fetch metadata. Apply it in scenarios where manual vault management is inefficient, like in CI/CD pipelines or AI-driven content creation.

在脚本中自动化Obsidian交互时使用本Skill，例如从外部数据生成每日笔记、根据用户输入更新文件，或运行Dataview查询以获取元数据。适用于手动管理库效率低下的场景，比如CI/CD流水线或AI驱动的内容创建。

Key Capabilities

核心功能

Create new files or folders in the vault using specified paths and content.
Edit existing files by appending, overwriting, or inserting text at specific lines.
Insert templates (e.g., from a predefined .md template file) into new or existing notes.
Execute Dataview queries to retrieve or manipulate note metadata.
Call Obsidian plugin APIs for custom extensions, such as querying plugin-specific data.

使用指定路径和内容在库中创建新文件或文件夹。
通过追加、覆盖或在特定行插入文本的方式编辑现有文件。
将模板（例如预定义的.md模板文件）插入新笔记或现有笔记中。
执行Dataview查询以检索或操作笔记元数据。
调用Obsidian插件API进行自定义扩展，例如查询插件特定数据。

Usage Patterns

使用模式

Invoke the skill via a function call like

call_skill('obsidian-direct', subcommand, params)

, where subcommand is one of: create-file, edit-file, insert-template, run-query, or plugin-call. Always include required params as a dictionary, e.g., {'path': 'notes/file.md', 'content': 'Text here'}. For authenticated actions, pass the API key via env var

$OBSIDIAN_API_KEY

. Structure calls sequentially: first create a file, then edit it. Use JSON for complex params, e.g., {'query': '{"from": "folder", "where": "file.name contains 'key'"}'}. Avoid concurrent calls to prevent vault conflicts.

通过函数调用

call_skill('obsidian-direct', subcommand, params)

来调用本Skill，其中子命令为以下之一：create-file、edit-file、insert-template、run-query或plugin-call。务必以字典形式传入必填参数，例如

{'path': 'notes/file.md', 'content': 'Text here'}

。对于需要认证的操作，通过环境变量

$OBSIDIAN_API_KEY

传递API密钥。按顺序调用：先创建文件，再编辑它。复杂参数使用JSON格式，例如

{'query': '{"from": "folder", "where": "file.name contains \\'key\\'"}'}

。避免并发调用以防止库冲突。

Common Commands/API

常用命令/API

API Endpoint: Use POST to

https://api.openclaw.com/v1/obsidian/vault/{vault-id}/files

for file operations, with JSON body like {"path": "notes/file.md", "content": "Hello"}. CLI equivalent:

obsidian-direct create-file --vault-id myvault --path "notes/file.md" --content "Hello" --api-key $OBSIDIAN_API_KEY

Code Snippet:

skill

params = {'path': 'Daily/daily.md', 'content': 'Today\'s notes'}
result = call_skill('obsidian-direct', 'create-file', params)
print(result['file_path'])  # Outputs: Daily/daily.md

For Dataview:

obsidian-direct run-query --vault-id myvault --query "LIST file.name FROM \"folder\" WHERE file.mtime > date(2023-01-01)" --api-key $OBSIDIAN_API_KEY

Config Formats: Params must be JSON objects, e.g., {"template": "path/to/template.md", "insert_at": 5} for insert-template. Flags: --vault-id (required), --dry-run (simulates without changes), --force (overwrites files).

API端点：文件操作使用POST请求到

https://api.openclaw.com/v1/obsidian/vault/{vault-id}/files

，JSON请求体示例为

{"path": "notes/file.md", "content": "Hello"}

。对应的CLI命令：

obsidian-direct create-file --vault-id myvault --path "notes/file.md" --content "Hello" --api-key $OBSIDIAN_API_KEY

。

代码片段：

skill

params = {'path': 'Daily/daily.md', 'content': 'Today\\'s notes'}
result = call_skill('obsidian-direct', 'create-file', params)
print(result['file_path'])  # Outputs: Daily/daily.md

Dataview相关命令：

obsidian-direct run-query --vault-id myvault --query "LIST file.name FROM \\"folder\\" WHERE file.mtime > date(2023-01-01)" --api-key $OBSIDIAN_API_KEY

。

配置格式：参数必须为JSON对象，例如插入模板时使用

{"template": "path/to/template.md", "insert_at": 5}

。可用标志：--vault-id（必填）、--dry-run（模拟操作不实际修改）、--force（覆盖文件）。

Integration Notes

集成说明

Integrate by passing outputs from other skills as inputs, e.g., use a search skill's result as content for create-file. Authentication: Set

$OBSIDIAN_API_KEY

in your environment, e.g.,

export OBSIDIAN_API_KEY=your_api_key

, and include it in calls. Ensure the vault is synced via Obsidian's sync plugin if remote. For multi-skill workflows, chain with tools like file-system skills by using the returned file paths as arguments. Test integrations in a local vault first to avoid data loss.

通过将其他Skill的输出作为输入来进行集成，例如使用搜索Skill的结果作为create-file的内容。认证方式：在环境中设置

$OBSIDIAN_API_KEY

，例如

export OBSIDIAN_API_KEY=your_api_key

，并在调用时传入。如果是远程库，确保通过Obsidian的同步插件完成同步。对于多Skill工作流，可与文件系统类Skill联动，将返回的文件路径作为参数使用。请先在本地库中测试集成，避免数据丢失。

Error Handling

错误处理

Always wrap skill calls in try-except blocks to catch exceptions like VaultError (e.g., 404 for missing files) or AuthError (e.g., 403 for invalid API key). Check response codes: if result['status'] == 'error', log the message and retry with exponential backoff. Common issues: Handle file conflicts with --force flag, or parse Dataview errors for query syntax. Example:

Code Snippet:

skill

try:
    call_skill('obsidian-direct', 'edit-file', {'path': 'notes/file.md', 'content': 'Updated text'})
except VaultError as e:
    if e.code == 404:
        call_skill('obsidian-direct', 'create-file', {'path': 'notes/file.md', 'content': 'Default'})
    else:
        raise

务必将Skill调用包裹在try-except块中，以捕获VaultError（例如文件不存在的404错误）或AuthError（例如API密钥无效的403错误）等异常。检查响应状态码：如果

result['status'] == 'error'

，记录错误信息并使用指数退避策略重试。常见问题：使用--force标志处理文件冲突，或解析Dataview查询语法错误。示例：

代码片段：

skill

try:
    call_skill('obsidian-direct', 'edit-file', {'path': 'notes/file.md', 'content': 'Updated text'})
except VaultError as e:
    if e.code == 404:
        call_skill('obsidian-direct', 'create-file', {'path': 'notes/file.md', 'content': 'Default'})
    else:
        raise

Concrete Usage Examples

具体使用示例

Automate daily note creation: First, get current date via another skill, then call
```
obsidian-direct create-file --vault-id myvault --path "Daily/{date}.md" --content "Notes for {date}" --api-key $OBSIDIAN_API_KEY
```
. This creates a new file like Daily/2023-10-01.md with initial content.

Run and insert Dataview results: Query tasks with

obsidian-direct run-query --vault-id myvault --query "TASK FROM \"Tasks\" WHERE !completed"

, then use the output in

obsidian-direct edit-file --path "Summary.md" --append result['query_output']

to append results to a summary note.

自动化每日笔记创建：首先通过其他Skill获取当前日期，然后调用
```
obsidian-direct create-file --vault-id myvault --path "Daily/{date}.md" --content "Notes for {date}" --api-key $OBSIDIAN_API_KEY
```
。这将创建一个类似Daily/2023-10-01.md的新文件，并包含初始内容。

运行并插入Dataview结果：使用

obsidian-direct run-query --vault-id myvault --query "TASK FROM \\"Tasks\\" WHERE !completed"

查询任务，然后将输出用于

obsidian-direct edit-file --path "Summary.md" --append result['query_output']

，将结果追加到汇总笔记中。

Graph Relationships

关联关系

Related to: community cluster (e.g., shares tags with file-management skills).
Connected to: obsidian-related skills like "obsidian-sync" for vault syncing.
Links with: general API skills for authentication handling.
Overlaps with: note-taking cluster for content manipulation.

关联社区集群：例如与文件管理类Skill共享标签。
连接Obsidian相关Skill：如用于库同步的“obsidian-sync”。
链接通用API Skill：用于认证处理。
与笔记集群重叠：用于内容操作。",