zhensolid/obsidian

tags:

"#Claude_Obsidian"

created: 2026-05-11

Claude Obsidian / Claude Canvas 插件安装排错记录

适用环境：macOS + Claude Code v2.1.138
主题：安装 AgriciDaniel/claude-obsidian 与 AgriciDaniel/claude-canvas 过程中遇到的问题与解决方法

1. 安装目标

本次主要安装两个 Claude Code 插件：

插件	作用
`claude-obsidian`	用于 Claude Code + Obsidian，基于 Karpathy LLM Wiki 思路管理知识库
`claude-canvas`	用于生成 / 编辑 Obsidian Canvas，可做流程图、思维导图、知识图谱、演示画布等

最终安装结果：

claude-canvas@local-claude-marketplace
Version: 1.0.0
Scope: user
Status: enabled

claude-obsidian@claude-obsidian-marketplace
Version: 1.6.0
Scope: user
Status: enabled

2. `claude-obsidian` 安装过程

2.1 添加 marketplace 成功

执行：

claude plugin marketplace add AgriciDaniel/claude-obsidian

输出：

✔ Successfully added marketplace: claude-obsidian-marketplace

说明 marketplace 添加成功。

2.2 安装插件失败：GitHub SSH 22 端口被断开

执行：

claude plugin install claude-obsidian@claude-obsidian-marketplace

报错：

Connection closed by 198.18.1.34 port 22
fatal: Could not read from remote repository.

原因

claude plugin install 阶段尝试通过 GitHub SSH 克隆仓库，但本地网络 / 代理环境阻断了 GitHub SSH 的 22 端口。

即使已经添加了 marketplace，真正安装插件时仍然需要再次 clone 仓库。

3. GitHub SSH 问题处理

3.1 原先只有 Gitee SSH Key

检查：

ls ~/.ssh

当时只有：

config
id_ed25519_gitee
id_ed25519_gitee.pub

说明本机只有 Gitee 的 SSH key，没有 GitHub 专用 key。

3.2 创建 GitHub SSH Key

执行：

ssh-keygen -t ed25519 -C "zhensolid@outlook.com" -f ~/.ssh/id_ed25519_github

然后复制公钥：

pbcopy < ~/.ssh/id_ed25519_github.pub

去 GitHub 添加 SSH Key：

GitHub → Settings → SSH and GPG keys → New SSH key

Title 可写：

MacBook Claude Code

3.3 配置 GitHub SSH 走 443 端口

因为 22 端口被断开，所以需要让 GitHub SSH 改走 443 端口。

编辑配置：

nano ~/.ssh/config

加入或修改为：

Host github.com
  HostName ssh.github.com
  User git
  Port 443
  IdentityFile ~/.ssh/id_ed25519_github
  IdentitiesOnly yes

Host gitee.com
  HostName gitee.com
  User git
  IdentityFile ~/.ssh/id_ed25519_gitee
  IdentitiesOnly yes

设置权限：

chmod 600 ~/.ssh/config
chmod 600 ~/.ssh/id_ed25519_github

3.4 测试 GitHub SSH

执行：

ssh -T git@github.com

第一次会提示确认主机：

The authenticity of host '[ssh.github.com]:443 ...' can't be established.
Are you sure you want to continue connecting?

输入：

yes

成功输出：

Hi zhensolid! You've successfully authenticated, but GitHub does not provide shell access.

这说明 GitHub SSH 已成功通过 443 端口连接。

3.5 重新安装 `claude-obsidian`

执行：

claude plugin install claude-obsidian@claude-obsidian-marketplace

成功：

✔ Successfully installed plugin: claude-obsidian@claude-obsidian-marketplace

4. `/wiki` 命令不可用的问题

安装前，直接在 clone 下来的 claude-obsidian 文件夹里运行 Claude Code，输入：

/wiki

报错：

Unknown command: /wiki

原因

直接 git clone 项目作为 Vault，并不一定会自动注册 slash command。

clone 方式下，Claude Code 可以读取项目里的：

skills/wiki/SKILL.md
WIKI.md
CLAUDE.md

但 /wiki 这类 slash command 只有在插件安装成功后才会注册。

插件安装后实际命令

安装成功后，命令列表里看到的不是单独的：

/wiki

而是：

/claude-obsidian:wiki
/wiki-ingest
/wiki-query
/wiki-lint
/wiki-fold

对应关系：

命令	作用
`/claude-obsidian:wiki`	初始化或检查 claude-obsidian wiki vault
`/wiki-ingest`	导入资料，将 source 整理进 wiki
`/wiki-query`	基于 wiki 查询问题，优先读 hot cache 和 index
`/wiki-lint`	检查 wiki 健康度，如死链、孤立页面、重复页面
`/wiki-fold`	将 wiki log 汇总折叠成 meta 页面

所以实际应使用：

/claude-obsidian:wiki

而不是：

/wiki

5. `.raw/` 目录的问题

5.1 `.raw/` 是什么？

在 claude-obsidian 项目中：

.raw/ = 原始资料目录
wiki/ = Claude 整理后的知识库

.raw/ 下放原始资料，Claude 读取它，但默认不修改它。

整理后的内容会进入：

wiki/

5.2 `.raw/` 在 Obsidian 里可能看不到

因为 .raw 是点开头目录，macOS / Obsidian 可能默认隐藏。

这不是项目异常，而是隐藏目录机制导致。

5.3 是否建议改成 `raw/`？

不太建议随便改。

原因是项目可能使用：

.raw/.manifest.json

记录已 ingest 文件的 hash，用来避免重复处理。

所以更推荐保留官方默认结构：

.raw/

如果需要在 Finder 里显示隐藏文件，可按：

Command + Shift + .

5.4 推荐目录结构

claude-obsidian/
├── .raw/
│   ├── inbox/
│   ├── notes/
│   ├── articles/
│   ├── transcripts/
│   └── papers/
├── wiki/
│   ├── index.md
│   ├── hot.md
│   └── log.md

创建目录：

cd ~/Documents/claude-obsidian
mkdir -p .raw/inbox .raw/notes .raw/articles .raw/transcripts .raw/papers

日常使用：

/wiki-ingest .raw/inbox

或者自然语言：

请处理 .raw/inbox 里的新增资料，已 ingest 过的跳过，整理进 wiki，并更新 index、log、hot。

6. 是否每次都要手动输入文件路径？

不一定。

可以固定使用 .raw/inbox/ 作为资料入口。

日常流程：

把新资料丢进：
```
.raw/inbox/
```
在 Claude Code 里说：
```
处理 .raw/inbox 里的新增资料
```

或者：

/wiki-ingest .raw/inbox

已经整理过的文件可以通过 log / manifest 跳过，避免重复处理。

7. 是否每次提问都会读取全部资料？

不会。

正常设计是：

.raw/ = 原始资料，只在 ingest 时主要读取
wiki/ = 整理后的知识库，平时 query 主要读取
wiki/index.md = 索引
wiki/hot.md = 高频 / 最近上下文缓存
wiki/log.md = 操作记录

提问时应该是：

用户提问
    ↓
读取 wiki/hot.md
    ↓
读取 wiki/index.md
    ↓
定位相关 wiki 页面
    ↓
只读取相关页面
    ↓
必要时才回查 .raw/

为了省 token，可以这样问：

根据我的 wiki 回答，优先读取 hot 和 index，只打开相关 wiki 页面，不要重新读取全部 .raw/。

8. `claude-canvas` 安装问题

8.1 直接安装失败

执行：

claude plugin install AgriciDaniel/claude-canvas

报错：

Plugin "AgriciDaniel/claude-canvas" not found in any configured marketplace

原因：Claude Code 当前的插件系统不是直接用 GitHub 仓库名安装，而是从已配置 marketplace 中查找插件。

8.2 `marketplace add` 也失败

执行：

claude plugin marketplace add AgriciDaniel/claude-canvas

报错：

Marketplace file not found:
.claude-plugin/marketplace.json

原因：claude-canvas 仓库是一个 plugin 仓库，但不是 marketplace 仓库。它有：

.claude-plugin/plugin.json

但没有：

.claude-plugin/marketplace.json

8.3 `claude plugin add` 不存在

执行：

claude plugin add ~/Documents/claude-canvas

报错：

error: unknown command 'add'

原因：当前 Claude Code v2.1.138 不支持 plugin add 这个子命令。

9. `claude-canvas` 最终解决方案：自建本地 marketplace

9.1 先 clone 插件

cd ~/Documents
git clone https://github.com/AgriciDaniel/claude-canvas

9.2 创建本地 marketplace

mkdir -p ~/Documents/local-claude-marketplace/.claude-plugin
mkdir -p ~/Documents/local-claude-marketplace/plugins
cp -R ~/Documents/claude-canvas ~/Documents/local-claude-marketplace/plugins/claude-canvas

创建 marketplace 文件：

cat > ~/Documents/local-claude-marketplace/.claude-plugin/marketplace.json <<'EOF'
{
  "name": "local-claude-marketplace",
  "description": "Local marketplace for manually installed Claude Code plugins",
  "owner": {
    "name": "shen liang"
  },
  "plugins": [
    {
      "name": "claude-canvas",
      "description": "AI-orchestrated visual production for Obsidian Canvas",
      "source": "./plugins/claude-canvas"
    }
  ]
}
EOF

9.3 添加本地 marketplace 并安装

claude plugin marketplace add ~/Documents/local-claude-marketplace
claude plugin install claude-canvas@local-claude-marketplace
claude plugin list

成功输出：

✔ Successfully added marketplace: local-claude-marketplace
✔ Successfully installed plugin: claude-canvas@local-claude-marketplace

插件列表：

claude-canvas@local-claude-marketplace
Version: 1.0.0
Scope: user
Status: enabled

claude-obsidian@claude-obsidian-marketplace
Version: 1.6.0
Scope: user
Status: enabled

10. 插件安装范围

两个插件都显示：

Scope: user

说明它们是用户级安装，不是只能在某一个文件夹使用。

也就是说：

插件命令 = 全局可用
实际处理对象 = 当前 Claude Code 所在目录

例如：

cd ~/Documents/claude-obsidian
claude

这时插件处理的是：

~/Documents/claude-obsidian

如果进入另一个 Obsidian Vault：

cd ~/Documents/MyVault
claude

再运行插件命令，它会作用于当前这个 Vault。

11. 推荐最终使用方式

11.1 进入 Obsidian Vault

cd ~/Documents/claude-obsidian
claude

11.2 初始化或检查 Wiki

/claude-obsidian:wiki

11.3 导入资料

把资料放到：

.raw/inbox/

然后运行：

/wiki-ingest .raw/inbox

或者：

请处理 .raw/inbox 里的新增资料，已处理过的跳过，整理进 wiki，并更新 index、log、hot。

11.4 查询知识库

/wiki-query 实时字幕方案怎么搭建？优先基于 wiki，不要重读全部 .raw。

11.5 检查知识库

/wiki-lint

11.6 使用 Canvas

进入 Claude Code 后输入：

查看是否有 canvas 相关命令。

可以尝试：

请基于我的 wiki，生成一个“Mac 实时字幕方案”的 Obsidian Canvas 流程图。

12. 本次关键结论

claude-obsidian 推荐通过 marketplace 安装。
如果 GitHub SSH 22 端口失败，需要配置 github.com 走 ssh.github.com:443。
/wiki 不一定存在，实际命令是 /claude-obsidian:wiki。
.raw/ 是官方默认 source 目录，不建议随意改名。
平时 query 不会每次读取全部 .raw/，正常会先查 hot.md 和 index.md。
claude-canvas 不是 marketplace 仓库，当前环境需要自建本地 marketplace 安装。
两个插件都已安装为 user scope，全局可用。
插件全局可用，但操作对象取决于当前 cd 到哪个目录。

13. 常用命令速查

# 进入 vault
cd ~/Documents/claude-obsidian
claude

# 初始化 / 检查 wiki
/claude-obsidian:wiki

# 导入资料
/wiki-ingest .raw/inbox

# 查询知识库
/wiki-query 你的问题

# 检查 wiki
/wiki-lint

# 查看插件
claude plugin list

# 测试 GitHub SSH
ssh -T git@github.com

# 查看 GitHub SSH 配置
cat ~/.ssh/config

新增：清理项目与插件操作指南

如果你想彻底清理 Claude-Obsidian / Canvas 项目，可以按照以下步骤操作：

1. 卸载插件

在 Claude Code 中执行：

claude plugin uninstall claude-obsidian@claude-obsidian-marketplace
claude plugin uninstall claude-canvas@local-claude-marketplace

只会删除插件和注册命令
不会删除你的 .raw/ 或 wiki 文件

2. 删除本地项目仓库

rm -rf ~/Documents/claude-obsidian

3. 删除本地 marketplace（如有）

rm -rf ~/Documents/local-claude-marketplace

4. 备份或删除 `.raw/` 文件夹

如果想保留原始资料：

mv ~/Documents/claude-obsidian/.raw ~/Documents/备份_raw

5. 总结清理步骤

卸载插件
删除本地项目文件夹
删除本地 marketplace
备份或删除 .raw/（可选）

完成后，你的 Vault 和插件环境将干净，同时原始资料可以选择保留或删除。

1. 删除特定的 MCP 服务器

在终端输入以下命令：

Bash

claude mcp remove obsidian-vault

2. 如果添加时指定了作用域（Scope）

因为你之前添加时使用了 --scope user，为了确保彻底删除，建议也带上作用域：

Bash

claude mcp remove obsidian-vault --scope user

3. 验证是否删除成功

删除后，你可以再次查看列表来确认该服务器已经消失：

Bash

claude mcp list

补充说明：

只是想临时禁用？ 目前 Claude Code 的 MCP 管理主要是增删。如果你只是不想让它运行，目前最快的方法是将其删除，或者在 Obsidian 端关闭 Local REST API 插件，这样它就会显示为 Disconnected。
手动清理配置文件： MCP 的配置通常保存在本地的 JSON 文件中。在 macOS 上，你也可以直接去这个路径编辑或删除对应的 JSON 条目： ~/Library/Application Support/claude/claude_desktop_config.json (针对桌面端) 或 Claude Code 对应的用户配置文件。

Claude_Obsidian.md 14 KB Постоянная ссылка История Исходник

created: 2026-05-11

Claude Obsidian / Claude Canvas 插件安装排错记录

1. 安装目标

2. claude-obsidian 安装过程

2.1 添加 marketplace 成功

2.2 安装插件失败：GitHub SSH 22 端口被断开

原因

3. GitHub SSH 问题处理

3.1 原先只有 Gitee SSH Key

3.2 创建 GitHub SSH Key

3.3 配置 GitHub SSH 走 443 端口

3.4 测试 GitHub SSH

3.5 重新安装 claude-obsidian

4. /wiki 命令不可用的问题

原因

插件安装后实际命令

5. .raw/ 目录的问题

5.1 .raw/ 是什么？

5.2 .raw/ 在 Obsidian 里可能看不到

5.3 是否建议改成 raw/？

5.4 推荐目录结构

6. 是否每次都要手动输入文件路径？

7. 是否每次提问都会读取全部资料？

8. claude-canvas 安装问题

8.1 直接安装失败

8.2 marketplace add 也失败

8.3 claude plugin add 不存在

9. claude-canvas 最终解决方案：自建本地 marketplace

9.1 先 clone 插件

9.2 创建本地 marketplace

9.3 添加本地 marketplace 并安装

10. 插件安装范围

11. 推荐最终使用方式

11.1 进入 Obsidian Vault

11.2 初始化或检查 Wiki

11.3 导入资料

11.4 查询知识库

11.5 检查知识库

11.6 使用 Canvas

12. 本次关键结论

13. 常用命令速查

新增：清理项目与插件操作指南

1. 卸载插件

2. 删除本地项目仓库

3. 删除本地 marketplace（如有）

4. 备份或删除 .raw/ 文件夹

5. 总结清理步骤

1. 删除特定的 MCP 服务器

2. 如果添加时指定了作用域（Scope）

3. 验证是否删除成功

补充说明：

Claude_Obsidian.md 14 KB

Постоянная ссылка История Исходник

2. `claude-obsidian` 安装过程

3.5 重新安装 `claude-obsidian`

4. `/wiki` 命令不可用的问题

5. `.raw/` 目录的问题

5.1 `.raw/` 是什么？

5.2 `.raw/` 在 Obsidian 里可能看不到

5.3 是否建议改成 `raw/`？

8. `claude-canvas` 安装问题

8.2 `marketplace add` 也失败

8.3 `claude plugin add` 不存在

9. `claude-canvas` 最终解决方案：自建本地 marketplace

4. 备份或删除 `.raw/` 文件夹