---
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，可做流程图、思维导图、知识图谱、演示画布等 |

最终安装结果：

```text
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 成功

执行：

```bash
claude plugin marketplace add AgriciDaniel/claude-obsidian
```

输出：

```text
✔ Successfully added marketplace: claude-obsidian-marketplace
```

说明 marketplace 添加成功。

---

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

执行：

```bash
claude plugin install claude-obsidian@claude-obsidian-marketplace
```

报错：

```text
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

检查：

```bash
ls ~/.ssh
```

当时只有：

```text
config
id_ed25519_gitee
id_ed25519_gitee.pub
```

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

---

### 3.2 创建 GitHub SSH Key

执行：

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

然后复制公钥：

```bash
pbcopy < ~/.ssh/id_ed25519_github.pub
```

去 GitHub 添加 SSH Key：

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

Title 可写：

```text
MacBook Claude Code
```

---

### 3.3 配置 GitHub SSH 走 443 端口

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

编辑配置：

```bash
nano ~/.ssh/config
```

加入或修改为：

```sshconfig
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
```

设置权限：

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

---

### 3.4 测试 GitHub SSH

执行：

```bash
ssh -T git@github.com
```

第一次会提示确认主机：

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

输入：

```text
yes
```

成功输出：

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

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

---

### 3.5 重新安装 `claude-obsidian`

执行：

```bash
claude plugin install claude-obsidian@claude-obsidian-marketplace
```

成功：

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

---

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

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

```text
/wiki
```

报错：

```text
Unknown command: /wiki
```

### 原因

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

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

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

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

---

### 插件安装后实际命令

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

```text
/wiki
```

而是：

```text
/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 页面 |

所以实际应使用：

```text
/claude-obsidian:wiki
```

而不是：

```text
/wiki
```

---

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

### 5.1 `.raw/` 是什么？

在 `claude-obsidian` 项目中：

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

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

整理后的内容会进入：

```text
wiki/
```

---

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

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

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

---

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

不太建议随便改。

原因是项目可能使用：

```text
.raw/.manifest.json
```

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

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

```text
.raw/
```

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

```text
Command + Shift + .
```

---

### 5.4 推荐目录结构

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

创建目录：

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

日常使用：

```text
/wiki-ingest .raw/inbox
```

或者自然语言：

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

---

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

不一定。

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

日常流程：

1. 把新资料丢进：

```text
.raw/inbox/
```

2. 在 Claude Code 里说：

```text
处理 .raw/inbox 里的新增资料
```

或者：

```text
/wiki-ingest .raw/inbox
```

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

---

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

不会。

正常设计是：

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

提问时应该是：

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

为了省 token，可以这样问：

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

---

## 8. `claude-canvas` 安装问题

### 8.1 直接安装失败

执行：

```bash
claude plugin install AgriciDaniel/claude-canvas
```

报错：

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

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

---

### 8.2 `marketplace add` 也失败

执行：

```bash
claude plugin marketplace add AgriciDaniel/claude-canvas
```

报错：

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

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

```text
.claude-plugin/plugin.json
```

但没有：

```text
.claude-plugin/marketplace.json
```

---

### 8.3 `claude plugin add` 不存在

执行：

```bash
claude plugin add ~/Documents/claude-canvas
```

报错：

```text
error: unknown command 'add'
```

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

---

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

### 9.1 先 clone 插件

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

---

### 9.2 创建本地 marketplace

```bash
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 文件：

```bash
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 并安装

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

成功输出：

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

插件列表：

```text
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. 插件安装范围

两个插件都显示：

```text
Scope: user
```

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

也就是说：

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

例如：

```bash
cd ~/Documents/claude-obsidian
claude
```

这时插件处理的是：

```text
~/Documents/claude-obsidian
```

如果进入另一个 Obsidian Vault：

```bash
cd ~/Documents/MyVault
claude
```

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

---

## 11. 推荐最终使用方式

### 11.1 进入 Obsidian Vault

```bash
cd ~/Documents/claude-obsidian
claude
```

---

### 11.2 初始化或检查 Wiki

```text
/claude-obsidian:wiki
```

---

### 11.3 导入资料

把资料放到：

```text
.raw/inbox/
```

然后运行：

```text
/wiki-ingest .raw/inbox
```

或者：

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

---

### 11.4 查询知识库

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

---

### 11.5 检查知识库

```text
/wiki-lint
```

---

### 11.6 使用 Canvas

进入 Claude Code 后输入：

```text
/
```

查看是否有 canvas 相关命令。

可以尝试：

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

---

## 12. 本次关键结论

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

---

## 13. 常用命令速查

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

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

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

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

```text
# 检查 wiki
/wiki-lint
```

```bash
# 查看插件
claude plugin list
```

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

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

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

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

### 1. 卸载插件

在 Claude Code 中执行：

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

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

### 2. 删除本地项目仓库

```bash
rm -rf ~/Documents/claude-obsidian
```

### 3. 删除本地 marketplace（如有）

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

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

如果想保留原始资料：

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

### 5. 总结清理步骤

1. 卸载插件
2. 删除本地项目文件夹
3. 删除本地 marketplace
4. 备份或删除 `.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 对应的用户配置文件。