AI 에이전트와 같이 쓰는 옵시디언 셋업기 (1) — 설치부터 동기화·버전관리까지

Markdown의 세상

Gen AI 시대가 되면서, 컴퓨터가 읽기 쉬운 — 컴퓨터와 사람이 동일한 인식으로 하나의 문서를 이해할 수 있는 — 가장 간단한 포맷인 마크다운(MD)이 문서의 표준처럼 변해가고 있는 요즘이다.

훨씬 전부터 MD 파일을 쓰고 다뤄 왔지만 (Notion 초창기 때부터 썼으니 못해도 7~8년은 썼다고 봐도 될 듯) 요즘처럼 MD 파일이 넘쳐나는 세상에서 가장 효율적인 에디터가 뭘까 이리저리 찾아보다가, 결국 옵시디언으로 정착하게 되었다.

얼핏 보면 Notion과 비슷해 보이기도 하지만, 클라우드 기반의 플랫폼 성격이 강한 Notion과는 달리 Obsidian은 로컬 기반의, 오픈소스 느낌의, 그래서 손이 많이 가지만 내 목적에 맞게 세팅이 더 편리하고, 의외로 생태계에 기여하는 개발자들이 많은 그런 프로그램이라 써보니 장점이 많았다.

나는 옵시디언을 Hermes Agent가 적극적으로 문서 작성에 개입하면서 나도 같이 문서를 작성하고 열람하는 구조로 사용해 보려고 한다. 그리고 가지고 있는 디바이스를 적극 활용해서 최대한 구독료나 장비 투자가 없는 상황에서 효율을 극대화하기 위한 설치 및 운영 세팅을 지향한다.

첫 설치부터 Vault 설정까지

Obsidian 공식 홈페이지에서 다운로드 받을 수 있다.

Obsidian — Sharpen your thinking

The free and flexible app for your private thoughts.
obsidian.md

생각보다 간단하게 뚝딱 설치된다.

MD 기반의 지식 저장소를 Notion도 써보고 Confluence도 쓰고 있지만, PDF export 기능을 포함해서 기본기에 제일 충실한 게 Obsidian이라는 생각이 많이 드는 요즘이다.

PDF 추출에 있어서 Confluence는 정말 최악이다.

첫 설치를 하고 나면 Vault 설정을 해야 한다. 파일들을 저장하는 루트 폴더를 지정해 주는 과정이다. 미리 폴더를 만들어 놓고 그걸 지정해도 되고, 신규로 vault를 만들면서 폴더를 생성시켜도 된다.

여러 개의 vault를 만들어서 각각 관리하는 방법도 있는데, 나는 개인적으로 life, work, build 세 가지 vault를 만들어서 분리 운영하려고 한다. (회사와 나를 철저히 분리하고자 하는 노력...)

미리 Documents 폴더 하위에 obsidian 폴더를 만들고, 그 하위에 life, work, build 폴더를 각각 만들어 둔다.

/Documents/obsidian/
  │
  ├── work/     ← Vault 1: 회사
  ├── life/      ← Vault 2: 개인
  └── build/    ← Vault 3: 개발/기술 영역

이런 폴더 구조로 각각 vault를 binding해 줄 예정.

✅ 세 개의 vault 생성 완료.

플러그인 설치

옵시디언 그 자체로는 로컬에 있는 MD 파일을 만들고 쓰게 해주는 에디터일 뿐이니, 이걸 동기화하고 나중에 AI 에이전트에게 공유까지 시킬 계획으로 여러 가지 플러그인을 설치해야 한다.

이 부분이 사실 🐰 Rabbit hole인데, 좋은 플러그인이 너무 많아서 설치해도 해도 또 깔고 싶어진다. 하지만 너무 많이 깔면 PC에 부하가 생기니, 필요한 것만 딱 설치하는 절제된 자세가 필요하다.

🚫 비활성화할 Core Plugin

플러그인 설치하기 전에, 옵시디언에 기본 설치되어 있는 core plugin 중 비활성화할 것들도 정리하자.

기본적으로 선택 해제되어 있는 코어 플러그인들도 있는데, 켜져 있는 것들 중에 끌 것들도 있다. "안 쓸 예정인" 플러그인들만 미리 정리하자면 다음과 같다.

Audio recorder — 나중에 Whisper 설치해서 대체될 예정

Random note

Slash commands — make.md로 대체됨

Slides

Publish — 옵시디언 구독 안 하면 무쓸모

Sync — 동기화는 커뮤니티 플러그인으로 대체

Workspaces

Format converter

Unique note creator — Zettelkasten 메모법 쓰면 좋은 플러그인이라는데, 나는 안 써서 비활성화

Outgoing links — Backlinks로 충분

Graph view — 보기엔 멋지지만 안 씀

✨ 설치할 Community Plugin

make.md

옵시디언을 Notion처럼 보이고 쓸 수 있게 해주는 플러그인. 하도 Notion을 오래 써서 그런지 깔자마자 친숙해짐. 특히 /로 시작하는 명령어 입력과 표 만들기는 기존 옵시디언보다 훨씬 좋음.

Self-hosted LiveSync

CouchDB 기반 다중 디바이스 실시간 동기화 플러그인. 동기화 설정된 디바이스들 사이의 vault 데이터 즉시 반영. Synology NAS에 CouchDB 설치해서 이 플러그인으로 동기화 진행할 예정.

Templater

동적 템플릿 엔진 (날짜 자동 삽입, JS 실행, 사용자 입력, 자동 노트 생성). 일일 계획·회의록·프로젝트 노트 자동 생성의 핵심 엔진. Hermes Agent에게 문서 생성 자동화 시킬 때 표준 양식 강제 도구.

Calendar

사이드바 월간 달력 + 날짜 클릭으로 daily note 자동 열기. 캘린더는 빠질 수 없음.

Periodic Notes

Daily 외에 Weekly / Monthly / Quarterly / Yearly 노트 지원. 주간 회고, 월간 정리 자동화의 기반.

Git (Obsidian Git)

Vault를 git 저장소로 자동 commit/push, 시점별 백업과 복원. 에이전트 자동화 시스템의 안전망. 사고 시 5분 전으로 복원 가능.

QuickAdd

한 단축키/명령으로 노트 생성·라인 추가·매크로 실행. "지금 떠오른 아이디어 inbox로", "회의록 새로 만들기" 같은 마이크로 워크플로 자동화.

Linter

저장 시 자동 정리 (YAML 프론트매터 정렬, 헤딩 양식 통일, created_at 자동 추가). Hermes가 노트 만들 때 형식 일관성 강제, 인덱싱용 메타데이터 자동 생성.

이 정도까지 설치하고 나면 집중력이 떨어질 때가 되었으니, 잠시 딴짓 좀 하다가... 이제 Synology NAS (사실 다른 NAS를 써도 무방함. 모두 Docker에 올려서 Obsidian에 connect 시킬 것들이라...)를 설정하러 가야 한다.

NAS에 필요한 프로그램들 설치하기

왜 NAS로 갑자기 넘어왔는가? 두 가지를 설치해야 하는데, 하나는 CouchDB이고 다른 하나는 Gitea이다. 둘 다 데이터 동기화에 관련된 프로그램인데, 내 Obsidian 모두에 연결해서 동기화와 최신성, 롤백 가능성을 확보해야 한다.

특히 Agent와 함께 글을 쓰고 수정하고 생성하고 삭제하는 구조로 사용하려면 두 가지는 반드시 필요하다.

📦 CouchDB 설치

Synology NAS 기준으로 (그리고 아마 다른 NAS 프로그램들도 Docker를 지원할 테니 근본적으로 같을 것이다) Container Manager로 들어가서 CouchDB를 설치한다.

Project 생성에서 아래 스크립트를 입력 (Docker Compose를 입력하는 것과 같음).

docker-compose.yml — CouchDB

version: '3.8'

services:
  couchdb:
    image: couchdb:3.3.3  # 가장 안정적인 최신 버전 계열
    container_name: couchdb-obsidian
    restart: always
    environment:
      - COUCHDB_USER=<입력>          # 관리자 아이디 (변경 가능)
      - COUCHDB_PASSWORD=<입력>  # 관리자 비밀번호 (강력하게 설정하세요)
    ports:
      - "5984:5984"  # CouchDB 기본 포트
    volumes:
      - ./data:/opt/couchdb/data        # 데이터 저장소
      - ./etc:/opt/couchdb/etc/local.d  # 설정 파일 저장소
    networks:
      - obsidian-net

networks:
  obsidian-net:
    driver: bridge

CouchDB 컨테이너가 정상 작동하는 것을 확인하고 다음 설치로 넘어간다. (디테일한 설정은 Docker 쪽 설치 다 하고 나서.)

🐙 Gitea 설치

여러 가지 git 설치 옵션이 있지만, 개인 NAS에서 돌리기에는 Gitea가 가장 가벼운 선택이다.

역시 Project 생성에서 스크립트 입력해 주는 것으로 서비스를 구동한다.

docker-compose.yml — Gitea

version: "3"

networks:
  gitea:
    external: false

services:
  server:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1026  # 제어판 > 터미널 > SSH 접속 후 'id' 입력하여 본인 계정 UID 확인
      - USER_GID=100   # users 그룹
    restart: always
    networks:
      - gitea
    volumes:
      - ./data:/data   # 데이터 영구 보존
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"    # 웹 UI 포트 (NAS 방화벽 오픈 필요)
      - "2223:22"      # SSH 포트 (Git SSH 클론용, NAS의 22번과 충돌 방지)

✅ 이렇게 해서 NAS에서 돌아가는 두 가지 서비스 설치는 완료. 세팅하러 가자.

NAS에 설치한 두 가지 프로그램 설정

⚙️ CouchDB 설정

총 3개의 DB를 만들어야 한다. Vault가 3개이기 때문에.

웹으로 config에 들어갈 수 있는데, 접속 주소는 <NAS내부망IP>:5984

이렇게 3개의 Database를 만들어 준다.

[CouchDB 서버 — 1개로 충분]
  ├── Database: obsidian-life     ← LIFE vault만 동기화
  ├── Database: obsidian-work    ← WORK vault만 동기화
  └── Database: obsidian-build   ← BUILD vault만 동기화

일단 여기까지 하고 넘어간다. (나의 분절적인 생각의 흐름...)

⚙️ Gitea 설정

웹으로 Gitea 접속 — <NAS-IP>:3000

repo를 세 개 만들어야 한다.

[Mac (vault 위치)]
    ↓ git push
[Gitea 서버 — 자가 호스팅]
  ├── repo: obsidian-life   (private)
  ├── repo: obsidian-work (private)
  └── repo: obsidian-build (private)

그리고 Gitea 쪽에 내 디바이스의 ssh-key를 등록해 놓아서, ssh로 로그인 없이 git push, pull 할 수 있도록 해 놓아야 한다.

나는 이 git을 이미 repo로 여러 프로젝트에 쓰고 있어서 이게 되어 있음. 그래서 포스팅에서는 생략.

Vault 공통 vs 개별 plugin 구분

플러그인 중, 하나만 설정해 놓고 나머지 두 가지 vault에 설정 복사해서 바로 쓸 plugin이 있고, 각 vault별로 따로 설정해야 하는 plugin이 있다.

공통 설정으로 쓸 plugin들은 설정 미리 다 해놓고 복사 붙여넣기로 공수를 줄이자.

✅ 그대로 복사 OK — 5개

Templater · Calendar · QuickAdd · Linter · MAKE.md

⚠️ 거의 공통, 미세조정 — 1개

Periodic Notes
(vault별로 daily/weekly 활성화 여부만 조정)

🚨 vault별 반드시 다르게 — 2개

Self-hosted LiveSync
(Database name)
Git (Remote URL)

이 가이드라인에 따라서 5개 plugin은 life vault만 켜고 빡세게 설정한다.

📌 Plugin별 세팅은 글이 너무 길어져서 다음 글로 넘겨야 할 듯.
📌 여기에서는 설정을 복사해서 다른 vault에 붙이는 것까지만 설명한다.

Plugin을 vault들에 복사하기

모든 옵시디언을 종료 처리한다. (백그라운드에서도 돌아가는 것이 없도록.)

CLI로 들어간다. vault 폴더 하위에 .obsidian이라는 숨겨진 폴더가 있는데, 이걸 복사해서 각각의 vault에 붙여넣으면 된다.

아래 커맨드 라인을 복붙하면 된다.

bash

cd ~/Documents/obsidian

[ -d work/.obsidian ] && mv work/.obsidian work/.obsidian.bak
[ -d build/.obsidian ] && mv build/.obsidian build/.obsidian.bak

cp -R life/.obsidian work/.obsidian
cp -R life/.obsidian build/.obsidian

정상적으로 복사가 되었는지는 work vault, build vault 들어가서 플러그인 설정들이 붙여넣어졌는지 확인.

CouchDB 기반의 동기화 설정

이제 드디어 동기화 세팅까지 왔다. (거의 다 왔고, 제일 중요한 부분이다.)

Self-hosted LiveSync plugin을 이용해서 동기화할 예정. NAS에 미리 띄워놓은 CouchDB를 호스트로 사용.

CouchDB 연동을 해 주면 되는데, 나는 이상하게 auto가 안 되어서 manual로 직접 다 입력해 줬다.

그리고 나서 LiveSync를 켜 주면 DB 동기화 완료.

세 vault 모두 설정해 주면 된다. 각각 Database name이 다른 것을 체크해서 연동하자.

Git 연결해서 버전 관리

이건 Agent가 내 Obsidian에 있는 문서들을 수정할 수도, 새로 생성할 수도 있게 되기 때문에 버전 관리를 하기 위해 세팅하는 일종의 안전장치이다.

⚠️ Claude Code로 코딩하는 회사들 중 한 곳에서 (이런 일이 정말로 일어날 수 있다) 어떤 직원이 Claude Code에게 어찌어찌 무슨 명령을 한 것 같은데, DB를 통째로 날려버린 일이 있었다. 복구 안 됨.

Agent와 함께 일하면서 버전 관리와 복구 가능성을
항상 염두에 두고 이중 삼중으로 준비해야 한다.
AI는 내 생각보다 과감하고, 뒤가 없으며, 그냥 해버린다.

Obsidian의 Git plugin은 이미 연결된 git을 자동으로 push 해 주고 merge 해주는 기능이다. 그런고로, 첫 git 연동은 내가 직접 vault마다 해 줘야 한다.

터미널을 열어서 폴더를 찾아가서 git init 해 주자.

bash — git 초기화

cd ~/Documents/obsidian/life

# git 저장소 초기화
git init
git branch -M main

Git에서 버전 관리하지 않을 파일들은 미리 commit 대상에서 제외하자.

bash — .gitignore 생성

cat > .gitignore <<'EOF'
# Obsidian 작업 캐시
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/cache

# CouchDB LiveSync 임시 파일
.obsidian/livesync.lock

# OS 파일
.DS_Store
Thumbs.db

# 임시 파일
*.tmp
*.bak

# 백업 폴더
.obsidian.backup_*
EOF

일단 .git 폴더를 만들어서 여기가 git 연결되는 폴더라는 것을 명시해 주고, 이제 repo 연결 진행.

bash — remote 연결

git remote add origin <repo에서 clone 주소 받아와서 여기 넣기>

이렇게 work와 build까지 다 연결하면 완료.

이제 git이 연결되고 나면, initial commit을 한번 해 줘야 옵시디언 안의 git plugin이 정상 인식하고, 각종 설정을 할 수 있게 된다.

기본 설정 대비 살짝 바꿔줄 것들을 바꿔주고 나면 세팅 완료.

✨ 이 과정을 PC들마다 다 해주면 된다......

STUDIO 남두오성

CATEGORIES