Obsidian接入任意大模型：Codex+Claude+CC Switch全流程教程

Obsidian是目前最受欢迎的本地笔记工具之一，但笔记和AI之间的割裂感一直是个痛点——把内容复制到AI工具里，处理完再粘贴回来，笔记一多版本就混乱。有没有一种方式，让AI直接"长"在Obsidian里面？

B站上有一期保姆级的Obsidian插件教程，详细演示了如何通过Cloudian插件，把Claude Code、Codex等AI Agent CLI接入Obsidian，实现笔记与大模型的直接对话。整个过程不需要写代码，零基础也能跟着做。

为什么不直接用AI Agent读取笔记？

市面上很多AI Agent都能读取Obsidian的笔记内容、调用知识库，但它们和Obsidian之间缺乏原生关系。你需要把内容复制过去，等它处理完再粘贴回来；它生成的笔记内容，又得回到Obsidian中才能编辑。笔记一多，版本就容易混乱。

Cloudian插件解决的就是这个问题。它直接嵌入Obsidian笔记软件内部，调用的是你自己已经付费的AI大模型。用视频里的话说："你的笔记在哪，它就在哪。"

先搞懂四层结构，再动手安装

安装之前，需要厘清四个部分的层级关系，否则后面配置时容易一头雾水：

Obsidian 是桌面界面，也就是你看到的笔记软件主体。Cloudian插件起到桥梁和嫁接的作用，连接Obsidian和AI能力。真正调用本地大模型的是各个 AI Agent的CLI（命令行界面）。大模型的API则提供真正的动力来源——你可以在系统中配置不同模型的API。

Cloudian本身不是一个独立的模型，它只是把笔记软件的能力对接到CLI Agent上，由Agent去完成具体动作。

CLI是什么？为什么AI偏爱它？

CLI的全称是Command Line Interface，即命令行界面。相比于用鼠标和菜单按钮操作的桌面端页面，CLI看起来就是"黑乎乎的那一团"，对初学者非常不友好。

但AI反而更喜欢CLI。原因在于：对AI来说，找到按钮、识别按钮位置并不容易，而用命令直接告诉Agent要做什么，后台逻辑更简单，执行效率更高。

**软链接（Symbolic Link）**是文件系统中的一种特殊文件，它并不存储实际数据，而是像快捷方式一样指向另一个文件或文件夹的真实位置。在 macOS 和 Linux 中通过 ln -s 源路径 目标路径 命令创建。文章中被多次提到的软链接正是利用这一特性：把统一技能库 ~/.agents/skills 中的技能文件夹链接到各个 Agent 的技能目录（如 .claude/skills），因此当你在统一库中新增或修改技能时，所有 Agent 都能立即生效，无需多次复制文件，也避免了多份副本不同步的问题。

API Key 是调用大模型服务的身份凭证，相当于一把只属于你账号的钥匙。它通常由模型供应商（如 Kimi、智谱、DeepSeek^广告 等）的工作台生成，形如一段长字符串。调用模型时，客户端会把它放进请求头，服务端据此验证身份、计费并控制权限。因为 API Key 具备直接扣费的能力，务必妥善保管，不要截图外发或写入公开仓库；一旦泄露，应立即在供应商后台吊销并重新生成。

安装Claude Code CLI：推荐新手首选

作者推荐优先安装Claude Code CLI而非Codex CLI。原因很实际：Claude Code对大部分模型的兼容性更好，而Codex如果配置自定义大模型，还需要安装路由等额外组件，对新手来说容易报错。如果你使用的是Claude模型或者采购的国产大模型，Claude Code CLI是更稳妥的选择。

安装方式很简单。打开Claude Code官方安装页面，切换到Terminal终端页面，复制对应的安装命令粘贴执行即可。macOS用户习惯用Homebrew的话，直接用Homebrew的安装命令即可。安装完成后，在终端输入命令验证是否成功，再通过claude --version查看版本号确认。

CC Switch：模型配置的管理中枢

安装完Claude CLI之后，先别急着进入Claude。作者强烈建议先安装CC Switch（官网ccswitch.io，免费下载），用管理模型配置，比手动编辑后台配置文件直观得多。

CC Switch的配置有几个关键点：

语言和主题根据个人习惯设置即可。主页显示选择你希望在界面右上角展示的AI Agent和CLI。技能（Skills）存储位置默认在第一个位置，但作者推荐改到统一文件夹（~/.agents/skills），这样无论哪个Agent配置的技能都存在同一个地方。技能同步方式勾选"软链接"，相当于创建快捷方式，让不同项目的Agent都能调用通用技能库中的技能。

配置国产大模型

以Kimi为例：在CC Switch中点击加号选择供应商，填入API Key（需要去Kimi工作台新建），然后进行模型映射。

模型映射的核心逻辑是：当你切换到Claude的Sonnet时，实际调用的模型是哪个。比如Claude的模型分为Haiku（最轻便快速）、Sonnet和Opus（中规中矩），你就可以把Haiku映射到Kimi 2.7 Code，把Sonnet和Opus映射到Kimi 3。如果最新模型支持100万Token，记得勾选相应选项。

配置完成后点击测试连通，确认没问题再点击启用。注意顺序：必须先在CC Switch中应用新模型，再登录Claude，否则历史配置会残留导致切换失败。

重新进入终端输入Claude命令，你会发现模型已经切换到了Kimi。问它"你现在用的是什么模型"，它会告诉你当前是K3套着Claude Code的壳。

Token 是大模型处理文本的基本单位，可以粗略理解为"字词片段"。英文中一个 Token 大约对应 0.75 个单词，中文通常一个汉字消耗 1 到 2 个 Token。上下文窗口（Context Window）指的是模型单次对话能同时"记住"的 Token 总量，包括你的输入和模型的输出。当模型支持 100 万 Token 时，意味着它可以一次性读入并处理体量极大的文档，例如整本技术手册或超长视频文稿，这正是文章中提示"如果最新模型支持 100 万 Token，记得勾选相应选项"的意义——开启后插件在处理长笔记时会更少因截断而丢失上下文。

模型映射是 CC Switch 这类中转工具的核心功能。由于 Claude Code 等 CLI 在内部写死了对 Haiku、Sonnet、Opus 三种模型的调用名称，当你使用第三方模型时，就需要用映射把这些名称"重定向"到你实际购买的模型上。映射的层级设计（快→Haiku、主→Sonnet、强→Opus）能保证 CLI 在不同场景下自动选用你指定的对应模型，而不必修改 CLI 源码。

安装Cloudian插件：让AI住进Obsidian

回到Obsidian，通过Command + ,进入设置，找到第三方插件，打开社区插件市场，搜索Cloudian。目前有多个版本，Cloud Plus增加了Kimi K3的支持能力，按需选择即可。

安装后启用插件，进入配置页面。重点配置项：打开"启动Cloud"开关，输入Claude CLI路径（在终端输入which claude获取），修改默认模型名称。建议打开安全模式和"加载用户Claude设置"，保持与CC Switch的配置统一。

实际使用体验

作者用一篇通过Obsidian Web Clipper下载的YouTube英文视频文稿做测试：勾选需要翻译的段落，在对话框中输入需求（翻译为中文、重点内容加Note格式），回车后大约一分钟就完成了。每个英文段落后面都附上了中文翻译，提到的相关模型也以Note形式插入了解释。

Cloudian还支持用@方式模糊搜索关联笔记中的其他内容，让AI基于多个文档给出综合结论。

Obsidian 社区插件是 Obsidian 的扩展机制，依托官方插件市场分发，安装后可在设置中独立启用或关闭。出于安全考虑，Obsidian 默认禁用第三方社区插件，首次使用需要先关闭"受限模式"（Restricted Mode），插件才能读取并写入你的笔记库。这也是文章强调"安全模式"开关的原因：开启后插件只能操作当前笔记库，不会越界访问其他文件夹，降低潜在风险。

Cloudian 通过调用本地 CLI 进程来实现 AI 能力，因此需要你提供 CLI 的可执行文件路径。在 macOS/Linux 中可用 which claude、which codex 获取，在 Windows 的 PowerShell 中则对应 where claude。这一路径就是插件与 CLI 之间的"接口地址"，若填错或 CLI 未安装，插件就无法启动对话。

Codex CLI安装（可选）

如果你确实是Codex用户，安装路径和Claude Code相同。安装完成后需要在CC Switch的认证页面中，通过ChatGPT进行登录认证。认证完成后，在Cloudian配置中切换启用Codex，同样用which codex获取安装路径填入即可。

作者不建议在Codex中添加其他第三方模型，因为需要打开路由并进行设置，如果同时使用跨域上网软件可能会引起冲突。

技能系统的使用

Cloudian的技能调用方式和常规AI Agent不同。它用add方式添加文件，用斜杠命令调用技能。Claude调用的技能存储在.claude/skills文件夹，Codex调用的存在.agents/skills。

通过软链接（ln -s命令）可以把通用技能库中的技能链接到Agent的技能文件夹中，然后在对话中用斜杠命令加载。作者演示了一个基于知识库整理名词解释的技能，AI会先读取技能要求，再读取规范文件，最后基于知识库内容输出结果，并附带文档跳转链接。

从统一管理角度，作者建议所有配置都通过CC Switch完成，保持Claude Code CLI、Claude Desktop和Cloudian配置的一致性，避免多套配置各自为政。