本文档面向 AI 智能体。用户将此链接交给你后，你应能独立完成 Obsidian + OpenCode AI 知识库的全部部署工作。
帮用户在本地 macOS 机器上搭建一个 Obsidian + OpenCode AI 知识库。部署完成后，用户可以在 Obsidian 里直接和 AI 对话，让 AI 帮忙录入、查询、整理笔记。
检查环境 → 安装依赖 → 克隆仓库 → 运行部署脚本 → 引导用户完成剩余步骤
在用户机器上依次检查以下条件：
uname -s必须是 Darwin（macOS）。如果是 Linux，流程类似但 open 命令需替换为 xdg-open、Homebrew 需改用系统包管理器；如果是 Windows，暂不支持一键脚本，建议用户使用 WSL2。
node -v- 已安装 → 记录版本号，继续
- 未安装 → 执行安装：
# 优先用 Homebrew
if command -v brew &>/dev/null; then
brew install node
else
# 没有 Homebrew，先装 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install node
fi如果用户不愿意装 Homebrew，打开 https://nodejs.org/zh-cn 让用户手动下载。
ls /Applications/Obsidian.app 2>/dev/null && echo "installed" || echo "not installed"- 未安装 → 打开 https://obsidian.md 让用户下载，拖入「应用程序」
git clone https://github.com/zxfccmm4/Obsidian-OpenCode-Knowledge.git ~/Desktop/Obsidian-OpenCode-Knowledge如果用户希望放在其他位置，替换路径即可。
cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash setup.sh如果你只是想预演流程、不真正安装，可以改用：
cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash setup.sh --dry-run --non-interactive --provider skip| 提示 | 建议回答 | 备注 |
|---|---|---|
| 知识库存放位置 | 直接回车（默认 ~/Desktop/我的知识库） |
可按用户意愿修改 |
| 目录已存在怎么处理 | 1（保留笔记，只更新规则和技能） | 脚本不会删除任何文件；选 2 会把旧目录改名备份后新建 |
| Node.js 安装方式 | 1（Homebrew 自动安装） | 前面已装好则不会出现 |
| 检测到已有 agent 配置是否更新 | 必须问用户 | 脚本会先备份旧配置 |
| 选择 AI 服务提供商 | 见下方决策表 | 必须问用户 |
| 粘贴 API Key | 用户提供的 Key | 必须问用户 |
如果你需要完全自动化执行，可以改用这些参数组合：
bash setup.sh --non-interactive --vault "<路径>" --provider openai --api-key "<KEY>" --keep-existing --overwrite-config
⚠️ 不要自己rm -rf用户已有的知识库目录。目录已存在时用--keep-existing（保留笔记）；确实要重新开始时用--overwrite-existing，脚本会把旧目录改名备份。
问用户：「你想用哪个 AI 服务？」
| 选项 | 适合谁 | 注册地址 |
|---|---|---|
| 1 - 智谱 GLM ⭐ | 国内用户，中文场景，注册简单 | https://open.bigmodel.cn |
| 2 - Anthropic | 有 Claude API Key 的用户 | https://console.anthropic.com/settings/keys |
| 3 - OpenAI | 有 OpenAI API Key 的用户 | https://platform.openai.com/api-keys |
| 4 - Google Gemini | 有 Google AI API Key 的用户 | https://aistudio.google.com/apikey |
| 5 - OpenRouter | 想用一个 Key 访问多个模型的用户 | https://openrouter.ai/settings/keys |
| 6 - DeepSeek | 国内用户，性价比高 | https://platform.deepseek.com/api_keys |
| 7 - 跳过 | 用户暂时没有 Key | 稍后手动配置 |
如果用户没有 API Key：
- 打开对应注册地址
- 指导用户注册并创建 Key
- 拿到 Key 后继续
如果 setup.sh 运行失败，按以下步骤手动完成：
💡 多 Agent 支持： 本知识库支持 OpenCode / Claude Code / Codex。下面以默认的 OpenCode 为例；若用户选了其他 agent，安装对应的 npm 包并参考
docs/agents.md的配置差异。
| Agent | npm 包 | 配置文件 |
|---|---|---|
| OpenCode（默认） | opencode-ai |
~/.config/opencode/opencode.json |
| Claude Code | @anthropic-ai/claude-code |
~/.claude/settings.json |
| Codex | @openai/codex |
~/.codex/config.toml |
# OpenCode（默认）
npm install -g opencode-ai
# 或 Claude Code：npm install -g @anthropic-ai/claude-code
# 或 Codex：npm install -g @openai/codex权限不足时加 sudo。
npm install -g @jackwener/opencli权限不足时加 sudo。
OpenCLI 是社交媒体采集功能的驱动工具，支持 100+ 网站适配器（小红书、抖音、Twitter 等）。
目标目录必须还不存在（已存在时不要删除它，改用 setup.sh --keep-existing 或换一个路径）：
VAULT_PATH="$HOME/Desktop/我的知识库"
cp -R ~/Desktop/Obsidian-OpenCode-Knowledge/vault-template "$VAULT_PATH"
find "$VAULT_PATH" -name ".gitkeep" -delete根据用户选择的 provider，写入 ~/.config/opencode/opencode.json：
mkdir -p ~/.config/opencode如果这个文件已经存在，先备份：
cp ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.backup-$(date +%Y%m%d-%H%M%S)然后根据用户选择的 provider 生成配置。以下是各 provider 的配置模板：
智谱 GLM：
{
"$schema": "https://opencode.ai/config.json",
"agent": { "build": { "options": { "store": false } }, "plan": { "options": { "store": false } } },
"model": "zhipuglm/glm-5.2",
"provider": {
"zhipuglm": {
"name": "智谱 GLM",
"npm": "@ai-sdk/openai-compatible",
"models": { "glm-5.2": { "name": "GLM-5.2" }, "glm-5.1": { "name": "GLM-5.1" }, "glm-5": { "name": "GLM-5" } },
"options": { "apiKey": "<用户的API Key>", "baseURL": "https://open.bigmodel.cn/api/coding/paas/v4" }
}
}
}Anthropic：
{
"$schema": "https://opencode.ai/config.json",
"agent": { "build": { "options": { "store": false } }, "plan": { "options": { "store": false } } },
"model": "anthropic/claude-opus-4-8",
"provider": {
"anthropic": {
"models": { "claude-opus-4-8": { "name": "claude-opus-4-8" }, "claude-sonnet-4-6": { "name": "claude-sonnet-4-6" } },
"options": { "apiKey": "<用户的API Key>" }
}
}
}OpenAI：
{
"$schema": "https://opencode.ai/config.json",
"agent": { "build": { "options": { "store": false } }, "plan": { "options": { "store": false } } },
"model": "openai/gpt-5.5",
"provider": {
"openai": {
"models": { "gpt-5.5": { "name": "gpt-5.5" }, "gpt-5.4-mini": { "name": "gpt-5.4-mini" } },
"options": { "apiKey": "<用户的API Key>" }
}
}
}Google Gemini：
{
"$schema": "https://opencode.ai/config.json",
"agent": { "build": { "options": { "store": false } }, "plan": { "options": { "store": false } } },
"model": "google/gemini-3.1-pro-preview",
"provider": {
"google": {
"models": { "gemini-3.1-pro-preview": { "name": "gemini-3.1-pro-preview" }, "gemini-3-flash": { "name": "gemini-3-flash" } },
"options": { "apiKey": "<用户的API Key>" }
}
}
}OpenRouter：
{
"$schema": "https://opencode.ai/config.json",
"agent": { "build": { "options": { "store": false } }, "plan": { "options": { "store": false } } },
"model": "openrouter/anthropic/claude-opus-4.8",
"provider": {
"openrouter": {
"models": { "anthropic/claude-opus-4.8": { "name": "claude-opus-4.8" }, "openai/gpt-5.5": { "name": "gpt-5.5" } },
"options": { "apiKey": "<用户的API Key>", "baseURL": "https://openrouter.ai/api/v1" }
}
}
}DeepSeek：
{
"$schema": "https://opencode.ai/config.json",
"agent": { "build": { "options": { "store": false } }, "plan": { "options": { "store": false } } },
"model": "deepseek/deepseek-v4-pro",
"provider": {
"deepseek": {
"name": "DeepSeek",
"npm": "@ai-sdk/openai-compatible",
"models": { "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" }, "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" } },
"options": { "apiKey": "<用户的API Key>", "baseURL": "https://api.deepseek.com/v1" }
}
}
}
⚠️ DeepSeek 旧的deepseek-chat/deepseek-reasoner模型名将于 2026-07-24 下线，已改用 V4-Pro / V4-Flash。
VAULT_PATH="$HOME/Desktop/我的知识库"
OPENCODE_PATH=$(command -v opencode)
NODE_PATH=$(command -v node)
PLUGIN_DIR="$VAULT_PATH/.obsidian/plugins/opencode-obsidian"
mkdir -p "$PLUGIN_DIR"
cat > "$PLUGIN_DIR/data.json" << EOF
{
"port": 14096,
"hostname": "127.0.0.1",
"autoStart": true,
"opencodePath": "$OPENCODE_PATH",
"startupTimeout": 45000,
"defaultViewLocation": "sidebar",
"injectWorkspaceContext": false,
"maxNotesInContext": 20,
"maxSelectionLength": 2000,
"customCommand": "$NODE_PATH $OPENCODE_PATH serve --port 14096 --hostname 127.0.0.1 --cors app://obsidian.md",
"useCustomCommand": true
}
EOF脚本或手动部署完成后，告诉用户还需要做以下 3 件事（脚本无法自动完成）：
- 打开 Obsidian
- 点击「打开文件夹作为仓库」
- 选择
~/Desktop/我的知识库（或用户指定的路径）
推荐通过 BRAT 安装：
- Obsidian 设置 → 第三方插件 → 浏览 → 搜索「BRAT」→ 安装并启用
⌘ P打开命令面板 →「BRAT: Add a plugin」- 输入
mtymek/opencode-obsidian→ 安装并启用
在 Obsidian 侧边栏找到 OpenCode 图标，打开面板，等连接成功后，试着说：
帮我创建一篇笔记，标题是《我的第一篇 AI 笔记》
如果部署失败，先让用户运行只读检查：
cd ~/Desktop/Obsidian-OpenCode-Knowledge && bash scripts/verify.sh --vault "$HOME/Desktop/我的知识库"部署完成后，逐项确认：
| 检查项 | 命令/方法 | 预期结果 |
|---|---|---|
| Node.js | node -v |
v21+ |
| OpenCode | opencode --version |
有版本号输出 |
| OpenCLI | opencli --version |
有版本号输出（社交媒体采集需要） |
| 知识库目录 | ls ~/Desktop/我的知识库 |
看到 AGENTS.md, AI_CONFIG.md, raw/, wiki/, assets/ |
| AI 配置 | cat ~/.config/opencode/opencode.json |
包含用户选择的 provider 和 API Key |
| Obsidian 插件 | ls ~/Desktop/我的知识库/.obsidian/plugins/opencode-obsidian/ |
看到 data.json |
全部通过 → 部署成功。
| 问题 | 原因 | 解决方案 |
|---|---|---|
npm install -g opencode-ai 权限不足 |
全局 npm 目录权限问题 | 加 sudo：sudo npm install -g opencode-ai |
brew: command not found |
未安装 Homebrew | 先装 Homebrew，或让用户手动下载 Node.js |
| OpenCode 面板连接失败 | API Key 无效或网络问题 | 检查 ~/.config/opencode/opencode.json 中的 apiKey |
| OpenCode 面板显示空白 | 插件未启用 | Obsidian 设置 → 第三方插件 → 启用 opencode-obsidian |
git clone 失败 |
网络问题 | 检查网络连接，或让用户手动下载 ZIP |
Obsidian-OpenCode-Knowledge/
├── setup.sh ← 一键部署脚本（交互式）
├── deployment-guide.md ← 面向人类的部署文档
├── GUIDE_FOR_AI.md ← 你正在读的这个文件
├── README.md ← 项目说明（中文）
├── README.en.md ← 项目说明（英文）
├── LICENSE ← MIT
├── CONTRIBUTING.md ← 贡献指南
├── .github/ ← Issue/PR 模板
└── vault-template/ ← 知识库模板
├── AGENTS.md ← AI 规则（Ingest/Query/Lint/Social Ingest 四种行为）
├── AI_CONFIG.md ← 用户可编辑的 AI 配置（知识域/触发词/语言/自定义规则）
├── raw/ ← 原始素材目录（AI 只读）
├── wiki/ ← AI 维护的笔记
│ ├── index.md ← 全局索引
│ ├── log.md ← 操作日志
│ └── 使用指南.md
├── assets/ ← 配图
└── .opencode/skill/ ← 预装 AI 技能（共 9 个）
├── obsidian-cli/ ← Obsidian 操作能力
├── obsidian-markdown/ ← Markdown 生成
├── defuddle/ ← 网页内容提取
├── opencli-usage/ ← OpenCLI 命令参考（100+ 适配器）
├── smart-search/ ← 智能搜索路由
├── opencli-browser/ ← 浏览器自动化
├── opencli-autofix/ ← 适配器自动修复
├── opencli-explorer/ ← 适配器开发指南
└── opencli-oneshot/ ← 单点快速 CLI 生成