Obsidian + GitHub + MacBook 完整设置指南:打造跨设备知识库
Obsidian + GitHub + MacBook 完整设置指南:打造跨设备知识库
📚 为什么选择 Obsidian + GitHub?
Obsidian 是一款强大的知识管理工具,通过 Markdown 文件构建你的个人知识库。结合 GitHub 进行版本控制和跨设备同步,你可以:
– ✅ 在多设备间无缝同步笔记
– ✅ 享受完整的版本历史和回滚功能
– ✅ 离线工作,随时同步
– ✅ 与 AI 助手(如 OpenClaw)无缝集成
– ✅ 免费且安全(私有仓库)
🎯 本指南涵盖
1. 在 MacBook 上安装 Obsidian
2. 创建 GitHub 私有仓库
3. 配置 SSH 密钥
4. 设置 Git 同步
5. 配置 Obsidian Git 插件
6. 测试跨设备同步
7. 在 VPS 上集成 OpenClaw AI 助手(进阶)
—
📋 前置要求
– MacBook(macOS)
– GitHub 账户
– 基本的命令行操作能力
– VPS(用于 OpenClaw 集成,可选)
—
第一步:安装 Obsidian
方法 1:Homebrew 安装(推荐)
brew install --cask obsidian
方法 2:直接下载
1. 访问 https://obsidian.md/download
2. 下载 macOS 版本
3. 打开 .dmg 文件
4. 将 Obsidian 拖拽到 Applications 文件夹
5. 从 Applications 启动
—
第二步:创建 GitHub 仓库
1. 登录 GitHub
访问 https://github.com 并登录你的账户。
2. 创建新仓库
1. 点击右上角的 “+” → “New repository”
2. Repository name: obsidian-vault(或你喜欢的名称)
3. Description: Obsidian vault for personal knowledge base
4. Visibility: 选择 Private(私有)🔒
5. 重要: 不要勾选 “Initialize this repository with a README”
6. 点击 “Create repository”
3. 复制仓库 URL
创建后,你会看到类似这样的 URL:
https://github.com/yourusername/obsidian-vault.git
或 SSH URL:
git@github.com:yourusername/obsidian-vault.git
复制这个 URL,稍后会用到。
—
第三步:配置 SSH 密钥
为什么需要 SSH 密钥?
SSH 密钥让你的 MacBook 可以安全地与 GitHub 通信,无需每次输入密码。
1. 检查是否已有 SSH 密钥
ls -la ~/.ssh/
如果你看到 id_ed25519 或 id_rsa 文件,说明已有密钥。如果没有,继续下一步。
2. 生成新的 SSH 密钥
ssh-keygen -t ed25519 -C "your.email@example.com" -f ~/.ssh/id_ed25519_github -N ""
参数说明:
– -t ed25519: 使用 ED25519 算法(更安全、更快)
– -C: 添加注释(通常是你的邮箱)
– -f: 指定密钥文件名
– -N "": 不设置密码(方便自动同步)
3. 添加 SSH 密钥到 SSH 代理
# 启动 SSH 代理
eval "$(ssh-agent -s)"
# 添加密钥
ssh-add ~/.ssh/id_ed25519_github
4. 显示公钥
cat ~/.ssh/id_ed25519_github.pub
你会看到类似这样的输出:
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBRCAQXG6Lf2fV2KNJpqZR7VJ5XyoEhlShxeZB7DqxR1 your.email@example.com
复制这一整行(从 ssh-ed25519 开始到结尾)。
5. 添加 SSH 密钥到 GitHub
1. 访问 https://github.com/settings/keys
2. 点击 “New SSH key”
3. Title: MacBook Pro(或任何你喜欢的名称)
4. Key type: 选择 Authentication key(不是 Signing key)
5. Key: 粘贴刚才复制的公钥
6. 点击 “Add SSH key”
6. 测试 SSH 连接
ssh -T git@github.com
如果看到这样的消息,说明配置成功:
Hi yourusername! You've successfully authenticated, but GitHub does not provide shell access.
—
第四步:克隆 GitHub 仓库
1. 选择克隆位置
cd ~
这会将仓库克隆到你的用户主目录。
2. 克隆仓库
使用 SSH URL(推荐):
git clone git@github.com:yourusername/obsidian-vault.git ObsidianVault
或使用 HTTPS URL:
git clone https://github.com/yourusername/obsidian-vault.git ObsidianVault
3. 进入仓库目录
cd ObsidianVault
4. 配置 Git 用户信息(首次使用)
git config user.name "Your Name"
git config user.email "your.email@example.com"
—
第五步:初始化 Obsidian Vault
1. 创建基本文件夹结构
mkdir -p "Daily Notes" Projects Memory Inbox Templates
2. 创建初始文件
创建 README.md
cat > README.md << 'EOF'
# Obsidian Vault
This is my personal knowledge base powered by Obsidian and GitHub.
## 📁 Folder Structure
- **Daily Notes/** - Daily journal entries
- **Projects/** - Active projects
- **Memory/** - Long-term knowledge
- **Inbox/** - Quick capture
- **Templates/** - Note templates
## 🔄 Sync
This vault is synced via GitHub. Changes are automatically pushed and pulled.
## 🤖 AI Integration
This vault works with OpenClaw AI assistant for automated note management.
EOF
创建 index.md(主页)
cat > index.md << 'EOF'
---
cssclass: dashboard
---
# My Knowledge Base
## 📋 Quick Links
- [[Daily Notes]] - Journal entries
- [[Projects]] - Active projects
- [[Memory]] - Long-term knowledge
## 📝 Recent Notes
TABLE file.mtime as "Last Modified"
FROM ""
WHERE file.mtime >= date(today) - dur(7 days)
SORT file.mtime DESC
LIMIT 10
## 🎯 Today's Focus
-
## 📚 Resources
- [Obsidian Help](https://help.obsidian.md)
- [GitHub Repository](https://github.com/yourusername/obsidian-vault)
EOF
创建每日笔记模板
mkdir -p Templates
cat > "Templates/Daily Note.md" << 'EOF'
---
date: {{date}}
tags: [daily-note]
---
# {{date}}
## 📋 Today's Focus
-
## ✅ Completed
-
## 🔄 In Progress
-
## 📝 Notes
-
## 💡 Ideas
-
EOF
创建项目模板
cat > "Templates/Project.md" << 'EOF'
---
created: {{date}}
status: active
tags: [project]
---
# {{title}}
## 🎯 Goal
-
## 📋 Tasks
- [ ] Task 1
- [ ] Task 2
- [ ] Task 3
## 📝 Notes
-
## 🔗 Resources
-
## 📊 Progress
- Started: {{date}}
- Status: Active
- Last updated: {{date}}
EOF
3. 提交初始文件
git add .
git commit -m "Initial commit: Obsidian vault setup"
git push -u origin main
---
第六步:在 Obsidian 中打开 Vault
1. 启动 Obsidian
从 Applications 启动 Obsidian。
2. 打开 Vault
1. 点击 "Open folder as vault"
2. 导航到 ~/ObsidianVault
3. 点击 "Open"
3. 探索你的 Vault
你会看到:
- index.md - 你的主页
- README.md - 说明文档
- Templates/ - 模板文件夹
- Daily Notes/ - 每日笔记文件夹
- Projects/ - 项目文件夹
- Memory/ - 知识库文件夹
- Inbox/ - 收件箱文件夹
---
第七步:配置 Obsidian Git 插件
1. 启用社区插件
1. 点击左下角的 设置 图标(齿轮)
2. 点击 Community plugins
3. 关闭 Safe mode(如果开启)
4. 点击 Browse 搜索插件
2. 安装 Obsidian Git 插件
1. 在插件市场搜索 "Obsidian Git"
2. 点击 Install
3. 安装完成后,点击 Enable
3. 配置自动备份
在 Settings → Obsidian Git 中配置:
自动备份设置
- Auto backup: ✅ 启用
- Auto backup interval: 15 分钟
- Auto backup after changes: 5 个文件
提交信息
- Auto commit message: Auto commit: {{date}} {{time}}
拉取/推送设置
- Auto pull before backup: ✅ 启用
- Auto push after backup: ✅ 启用
分支设置
- Current branch: main
4. 测试插件
1. 点击左侧边栏的 Git 图标
2. 点击 Create backup(或按 Cmd+P,输入 "Git: Create backup")
3. 你应该看到:
- 检测到更改
- 创建提交
- 推送到远程
---
第八步:测试跨设备同步
1. 在 MacBook 上创建测试笔记
1. 在 Obsidian 中创建新笔记(Cmd+N)
2. 输入内容:
# Test Note
This is a test note from my MacBook!
Created: 2026-04-06
Testing the Obsidian + GitHub sync.
3. 重命名为 Test Note
4. 等待 15 分钟(或手动触发备份)
2. 验证同步
在 MacBook 上:
cd ~/ObsidianVault
git status
你应该看到 Test Note.md 已被提交。
在 GitHub 上:
访问你的仓库,你应该看到 Test Note.md 文件。
3. 在其他设备上拉取
如果你有其他设备(如 VPS),可以拉取更改:
cd /path/to/obsidian-vault
git pull origin main
---
第九步:与 AI 助手集成(可选)
如果你使用 OpenClaw 或其他 AI 助手,可以让它帮你管理笔记:
读取笔记
Read my index.md file
创建笔记
Create a daily note for today
更新笔记
Add "Tested Obsidian integration" to my daily note
搜索笔记
Find all notes tagged with #project
组织笔记
Move all notes tagged with #archive to the Memory folder
---
第十步:在 VPS 上集成 OpenClaw(进阶)
OpenClaw 是在你的 VPS 上运行的 AI 助手。让你的 Obsidian 知识库与 OpenClaw 集成,可以实现自动化笔记管理、内容分析和智能组织。
🎯 为什么要在 VPS 上集成 OpenClaw?
- ✅ 24/7 可用:OpenClaw 在 VPS 上持续运行
- ✅ 自动化任务:自动处理笔记、整理内容、生成报告
- ✅ 本地访问:直接读写你的 Obsidian vault
- ✅ 隐私保护:所有数据在你的 VPS 上,不经过第三方
- ✅ API 集成:可通过简单命令与笔记交互
📋 前置条件
- ✅ VPS 已安装 OpenClaw(本指南假设你已经设置好了)
- ✅ Obsidian vault 已创建在 VPS 上(例如:/root/.openclaw/workspace/obsidian-vault/)
- ✅ VPS 与 GitHub 已经同步(vault 已推送到 GitHub)
1. 将 Vault 链接到 OpenClaw
OpenClaw 会自动访问你的 vault 目录。在 VPS 上,确保 vault 位于 OpenClaw 的工作空间:
cd /root/.openclaw/workspace/
# vault 应该已经在那里
OpenClaw 默认工作空间:/root/.openclaw/workspace/
2. 配置 OpenClaw 访问权限
OpenClaw 已经有权访问工作空间中的所有文件。确保 vault 权限正确:
# 检查权限
ls -la /root/.openclaw/workspace/obsidian-vault/
# 确保 openclaw 用户可读可写(通常已经是)
chmod -R u+rw /root/.openclaw/workspace/obsidian-vault/
3. 测试 OpenClaw 读取笔记
向 OpenClaw 发送命令读取你的笔记:
Read my index.md file from my Obsidian vault
OpenClaw 会读取:
/root/.openclaw/workspace/obsidian-vault/index.md
并返回内容。
4. 测试 OpenClaw 创建笔记
Create a new daily note for today in my Obsidian vault
OpenClaw 会在你的 vault 中创建新的每日笔记。
5. 常见 OpenClaw 命令示例
读取特定笔记
Read the note "Project Planning" from my Obsidian vault
搜索笔记
Find all notes in my vault that contain the word "meeting"
更新笔记
Add "Meeting with team at 3pm" to my daily note for today
移动和组织笔记
Move all notes tagged with #draft to the Inbox folder
分析内容
Analyze my daily notes from the past week and summarize completed tasks
生成报告
Review my Projects folder and create a status report
6. 设置自动化工作流
你可以通过 OpenClaw 的定时任务自动管理笔记:
每日自动创建 Daily Note
创建一个定时任务(cron job)每天自动创建 daily note:
# 使用 OpenClaw CLI 设置定时任务
# 每天上午 9 点自动创建 daily note
openclaw cron add --name "Daily Note" --schedule "0 9 * * *" --payload '{"message": "Create a daily note for today and add yesterday's completed tasks"}'
每周自动生成周报
每周五下午 5 点自动生成周报:
openclaw cron add --name "Weekly Review" --schedule "0 17 * * 5" --payload '{"message": "Review all daily notes from this week, summarize accomplishments, and plan for next week"}'
自动整理笔记
每天午夜自动整理笔记:
openclaw cron add --name "Nightly Organizer" --schedule "0 0 * * *" --payload '{"message": "Move all notes older than 30 days with tag #temporary to Archive folder"}'
7. 与 Obsidian Git 插件配合使用
OpenClaw 可以直接修改 vault 中的文件,Obsidian Git 插件会自动检测更改并同步:
工作流程:
1. 你创建一个笔记(MacBook)
2. 快速编辑(MacBook)
3. 自动备份(Obsidian Git) → GitHub
4. OpenClaw 拉取最新(自动或手动)
5. OpenClaw 分析并更新笔记
6. OpenClaw 提交更改
7. Obsidian Git 检测到远程更新,自动拉取
8. 你看到 OpenClaw 的更改
8. 实际应用场景
场景 1:自动会议记录整理
你创建笔记: "Meeting with team - discussed project timeline"
OpenClaw 自动:
1. 读取该笔记
2. 提取 action items
3. 创建任务列表
4. 更新相关 project note
5. 标记为 #meeting #processed
场景 2:每日自动摘要
每天 18:00,OpenClaw:
1. 读取今日 daily note
2. 提取完成的 tasks
3. 更新 Projects 状态
4. 生成明日的 focus list
5. 保存到 Memory 作为知识积累
场景 3:知识自动关联
OpenClaw 定期:
1. 扫描所有笔记
2. 发现相关主题
3. 添加 [[wiki-links]] 自动关联
4. 创建主题聚合笔记
场景 4:自动备份报告
每周:
1. 收集所有变更
2. 生成 activity 报告
3. 保存在 Reports 文件夹
4. 发送摘要到指定渠道
9. 性能优化建议
- 限制扫描范围:使用指定文件夹而非整个 vault
- 分批处理:大量笔记时分批处理,避免内存溢出
- 缓存结果:缓存常用查询结果以提高速度
- 异步执行:长时间任务使用异步模式,不阻塞响应
10. 安全注意事项
- 🔒 确保 VPS 防火墙配置正确(仅允许必要端口)
- 🔑 不要将 SSH 私钥分享给他人
- 📝 vault 包含敏感信息时,确保 GitHub 仓库为 Private
- 🔄 定期检查 GitHub 仓库访问权限
- 🛡️ 考虑使用 Obsidian 加密插件保护敏感笔记
🤝 获取帮助
如果你在设置过程中遇到问题:
1. 检查 OpenClaw 状态:
openclaw status
2. 查看 vault 路径:
ls -la /root/.openclaw/workspace/obsidian-vault/
3. 测试读取权限:
cat /root/.openclaw/workspace/obsidian-vault/index.md
4. 联系支持: 在 helloai.jp 评论区或 Discord 社区提问
---
🎯 最佳实践
1. 定期提交
即使配置了自动备份,也要定期手动提交重要更改:
cd ~/ObsidianVault
git add .
git commit -m "Update: description of changes"
git push origin main
2. 使用有意义的提交信息
避免使用 "update" 或 "fix" 这样的模糊信息。使用描述性的信息:
git commit -m "Add project notes for Obsidian setup guide"
3. 定期备份
虽然 GitHub 很可靠,但定期备份到其他位置(如本地硬盘或云存储)是个好习惯。
4. 使用标签
在 Obsidian 中使用标签来组织笔记:
# Project Note
Tags: #project #active #obsidian
5. 创建模板
为不同类型的笔记创建模板,保持一致性。
---
🔧 故障排除
问题 1:SSH 连接失败
错误信息:
Permission denied (publickey)
解决方案:
1. 检查 SSH 密钥是否已添加到 GitHub
2. 确认使用的是正确的 SSH 密钥
3. 测试连接:ssh -T git@github.com
问题 2:推送失败
错误信息:
error: failed to push some refs to 'github.com'
解决方案:
git pull origin main
git push origin main
问题 3:Obsidian Git 插件不工作
解决方案:
1. 确认 Git 已安装:git --version
2. 检查插件设置
3. 查看插件日志
问题 4:合并冲突
解决方案:
git pull origin main
# 手动解决冲突
git add .
git commit -m "Resolve merge conflict"
git push origin main
---
📚 进阶技巧
1. 使用 Git 分支
为实验性内容创建分支:
git checkout -b experiment
# 做一些实验
git add .
git commit -m "Experiment: try new layout"
git checkout main
2. 使用 Git Hooks
创建自动化的 Git hooks:
# 创建 pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
# 在提交前运行检查
echo "Running pre-commit checks..."
EOF
chmod +x .git/hooks/pre-commit
3. 使用 GitHub Actions
设置自动化工作流:
# .github/workflows/backup.yml
name: Backup
on: [push]
jobs:
backup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
---
🎉 总结
通过本指南,你已经成功:
✅ 安装了 Obsidian
✅ 创建了 GitHub 私有仓库
✅ 配置了 SSH 密钥
✅ 设置了 Git 同步
✅ 配置了 Obsidian Git 插件
✅ 测试了跨设备同步
✅ 集成了 OpenClaw AI 助手(进阶) 🚀
现在你拥有了:
- 强大的知识管理工具(Obsidian)
- 可靠的版本控制(GitHub)
- 无缝跨设备同步(Git)
- AI 自动化助手(OpenClaw)
这是一个完整的、自动化的、智能化的个人知识管理系统!
📖 相关资源
- [Obsidian 官方文档](https://help.obsidian.md)
- [GitHub 官方文档](https://docs.github.com)
- [Git 官方文档](https://git-scm.com/doc)
- [Obsidian Git 插件文档](https://github.com/Vinzent03/obsidian-git)
- [OpenClaw 文档](https://docs.openclaw.ai)
---
祝你使用愉快! 🚀
如果你在设置过程中遇到任何问题,欢迎在评论区留言或联系我。
