메인 콘텐츠로 건너뛰기
Tilnote
Tilnote로 만들기
로버트
로버트
조회수 162•

생성형 AI 도구를 활용하여 작성 및 편집된 노트입니다.

OpenClaw에서 옵시디언(Obsidian)과 깃허브(GitHub) 연동 방법

OpenClaw 완전정복 : 설치부터 응용 사례까지

사전 준비물

GitHub 쪽 준비부터 정리한다. GitHub 계정이 있어야 하고, 저장소는 Private를 기본값으로 추천한다. 저장소 이름은 obsidian-vault처럼 용도가 드러나게 짓는다.

인증 수단은 두 가지 중 하나를 준비한다. 권장은 SSH(키 기반)이고, 대안은 HTTPS + PAT(Personal Access Token)이다. 둘 다 "OpenClaw 내부에서 Git이 인증 정보를 읽을 수 있느냐"가 핵심이다.

로컬(=OpenClaw에서 보이는 파일시스템)에는 볼트 폴더를 하나 정한다. 예시는 아래처럼 잡으면 관리가 쉽다.

~/vaults/my-vault/ (Obsidian Vault 루트)

~/vaults/my-vault/.obsidian/ (Obsidian 설정 폴더)

~/vaults/my-vault/.git/ (Git 메타데이터, 연결 후 생성)

OpenClaw에서 먼저 확인할 것(체크리스트)

아래 항목이 안 되면, 플러그인 설정을 아무리 잘해도 중간에 막힌다.

  • 네트워크: github.com에 나가는 아웃바운드가 되는지, 방화벽/프록시가 있는지 확인한다. (특히 SSH 22번 포트가 막히면 HTTPS로 우회해야 한다.)

  • 파일 권한: 볼트 폴더에 읽기/쓰기 권한이 있는지 확인한다. (동기화 시 .git/와 .obsidian/도 수정된다.)

  • Git 바이너리: OpenClaw 환경에서 git 실행이 가능한지 확인한다.

    git --version
which git

  • SSH 키 보관 위치: 일반적으로 ~/.ssh/를 쓴다. OpenClaw가 홈 디렉터리를 유지하는지(재시작 시 초기화되는지) 확인한다.

  • SSH 에이전트/환경변수: SSH_AUTH_SOCK가 잡히는지, 에이전트에 키를 올릴 수 있는지 확인한다. (안 되면 "에이전트 없이 키 파일을 직접 쓰는 방식"으로 운영해야 한다.)

  • 백그라운드 작업 제약: OpenClaw가 백그라운드 프로세스를 제한하면 "자동 푸시/풀"이 기대대로 동작하지 않을 수 있다. 이 경우 자동 기능을 줄이고 수동 버튼 위주로 운영한다.

  • 장기 실행 자격증명 저장: 세션이 짧게 끊기면 PAT/SSH 키를 매번 다시 주입해야 할 수 있다. 안전한 보관 방식을 먼저 정한다.

GitHub 인증 방식 1: SSH(권장)

SSH는 한 번 잘 잡으면 가장 덜 번거롭다. 순서는 "키 생성 → GitHub에 공개키 등록 → OpenClaw에서 연결 테스트 → remote 설정"이다.

OpenClaw에서 키를 만든다(이미 키가 있으면 생략). 이메일은 GitHub 계정 메일을 넣는다.

mkdir -p ~/.ssh
chmod 700 ~/.ssh

ssh-keygen -t ed25519 -C "you@example.com"
# 저장 경로: ~/.ssh/id_ed25519 (기본값 권장)
# 패스프레이즈: 가능하면 설정(세션 유지가 불안정하면 운영 편의와 보안 사이에서 선택)

공개키를 확인하고 복사한다.

cat ~/.ssh/id_ed25519.pub

GitHub 웹에서 등록한다.

GitHub → Settings → SSH and GPG keys → New SSH key → 붙여넣기 → Add

연결 테스트를 한다.

ssh -T git@github.com

처음이면 호스트 키 확인이 나오고, yes를 입력한다. 성공 메시지가 나오면 다음으로 간다.

원격 URL은 SSH 형태를 사용한다.

git@github.com:<OWNER>/<REPO>.git

GitHub 인증 방식 2: HTTPS + PAT(대안)

SSH 22번이 막히거나 키 보관이 어려우면 PAT를 쓴다. PAT는 "비밀번호 대신 쓰는 토큰"이라 노출 위험이 크므로 권한을 최소화한다.

GitHub에서 PAT 생성:

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) 또는 Fine-grained token

권한은 보통 아래면 충분하다.

  • (Fine-grained) 해당 repo에만 권한 부여 + Contents: Read and write

  • (Classic) repo 범위(가능하면 private repo만 쓰고 토큰 만료일 설정)

원격 URL은 HTTPS 형태를 사용한다.

https://github.com/<OWNER>/<REPO>.git

인증 입력이 필요할 때는 사용자명은 GitHub 아이디, 비밀번호 칸에는 PAT를 넣는다. 토큰을 평문으로 파일에 저장하는 방식은 피하고, OpenClaw가 제공하는 안전한 시크릿 저장소가 있으면 거기에 넣는 쪽을 우선한다.

첫 연결 시나리오 A: GitHub에서 클론해서 볼트로 사용(클론 → Obsidian에서 열기)

이미 GitHub에 저장소가 있고 그 내용을 그대로 볼트로 쓰고 싶을 때 적합하다.

  1. OpenClaw에서 작업 폴더를 만든다.

mkdir -p ~/vaults
cd ~/vaults

  1. 저장소를 클론한다.

SSH:

git clone git@github.com:OWNER/REPO.git my-vault

HTTPS:

git clone https://github.com/OWNER/REPO.git my-vault

  1. Obsidian에서 볼트를 연다.

Obsidian → Open folder as vault → ~/vaults/my-vault 선택

  1. Obsidian Git 플러그인을 설치하고(아래 섹션 참고) "Pull on startup"를 켜서 시작 시 최신화되게 한다.

첫 연결 시나리오 B: 기존 볼트를 GitHub로 올리기(기존 폴더 → git init → 첫 push)

이미 OpenClaw에 볼트가 있고, 이걸 원격으로 올리고 싶을 때 적합하다.

  1. 볼트 루트로 이동한다.

cd ~/vaults/my-vault

  1. Git 초기화 및 기본 브랜치 설정(선호에 따라 main).

git init
git branch -M main

  1. .gitignore를 만든다(예시는 아래 "보안/운영 팁" 참고).

nano .gitignore

  1. 첫 커밋을 만든다.

git add .
git commit -m "Initial commit"

  1. 원격을 추가하고 푸시한다.

SSH:

git remote add origin git@github.com:OWNER/REPO.git
git push -u origin main

HTTPS:

git remote add origin https://github.com/OWNER/REPO.git
git push -u origin main

Obsidian Git 플러그인 설치와 기본 설정(권장 값 포함)

Obsidian Git 플러그인은 "볼트 안에서 커밋/풀/푸시"를 누를 수 있게 해준다. 다만 실제 Git 실행은 OpenClaw의 환경과 인증 설정에 의존한다.

설치:

Obsidian → Settings → Community plugins → Turn off Safe mode(필요 시) → Browse → "Obsidian Git" 검색 → Install → Enable

기본 설정(메뉴 경로: Obsidian → Settings → Obsidian Git):

  • Vault backup interval(자동 커밋 주기): 5~15분 권장. OpenClaw가 자주 잠들거나 백그라운드가 불안정하면 더 길게 잡는다.

  • Auto commit: 켠다. 메시지 템플릿을 정해두면 히스토리가 깔끔해진다.

  • Auto push: 환경이 안정적이면 켠다. 불안정하면 끄고 수동 push로 운영한다.

  • Pull on startup: 켠다. (시작할 때 원격 변경을 먼저 받아 충돌을 줄인다.)

  • Push on commit: 켜면 커밋과 동시에 푸시한다. 네트워크가 불안정하면 오히려 실패가 잦아질 수 있어 상황에 맞춘다.

  • Commit message template 예시:

    • vault: {{date}} {{time}}

    • 또는 Update notes ({{date}} {{time}})

  • Commit author: 가능하면 GitHub와 같은 이름/이메일로 맞춘다.

자주 쓰는 명령(커맨드 팔레트):

Obsidian → Command palette → "Git: Pull", "Git: Push", "Git: Commit", "Git: Commit-and-sync"

플러그인이 "저장소 경로"를 따로 묻는 경우는 보통 볼트 루트(= .git이 있는 폴더) 기준으로 잡는다. 즉 ~/vaults/my-vault가 Git 루트여야 한다.

데스크톱/모바일 차이(운영 관점)

데스크톱(OpenClaw 포함)은 대체로 Git 바이너리 실행이 가능해서 Obsidian Git 플러그인이 잘 맞는다. 핵심은 "인증(SSH/PAT)과 파일 권한"이다.

모바일은 제약이 많다. iOS는 특히 파일 시스템 접근과 백그라운드 작업 제한이 강해서 "자동 동기화"가 끊기기 쉽고, Obsidian Git이 기대만큼 안정적으로 동작하지 않을 수 있다. iOS에서는 대안으로 전용 Git 클라이언트(Working Copy 등)와 함께 쓰거나, 최소한 "수동 pull/push"를 습관화하는 방식이 현실적이다.

충돌 처리(merge conflict) 기본 루틴

충돌은 "서로 다른 기기에서 같은 파일을 동시에 수정"하면 생긴다. 플러그인으로도 해결은 가능하지만, 원리를 알고 접근하는 편이 빠르다.

  1. 먼저 Pull을 시도한다. Pull에서 충돌이 나면 중단하지 말고 상태를 본다.

git status

  1. 충돌 파일을 열면 <<<<<<<, =======, >>>>>>> 같은 표시가 있다. 둘 중 하나를 고르거나 내용을 합쳐서 표시를 제거한다.

  2. 해결한 파일을 추가하고 커밋한다.

git add 충돌난파일.md
git commit -m "Resolve merge conflict"
git push

노트 파일은 "문장 단위로 줄바꿈이 자주 바뀌는 스타일"이면 충돌이 더 잘 난다. 자주 충돌이 나면 "한 파일을 여러 기기에서 동시에 건드리는 습관"부터 줄이는 게 효과가 크다.

흔한 문제 해결

권한 오류(SSH, 파일 권한)

SSH가 거부되면 먼저 이걸 본다.

ssh -T git@github.com
ls -la ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

파일 권한 오류는 볼트 폴더 권한과 소유자를 확인한다.

ls -la ~/vaults/my-vault

Line ending(LF/CRLF)로 변경이 쏟아질 때

윈도우/리눅스가 섞이면 줄바꿈 변환 때문에 변경 파일이 폭증한다. 가능한 한 저장소 정책을 고정한다.

예: 모든 텍스트를 LF로 통일(권장). 필요하면 .gitattributes를 둔다.

* text=auto eol=lf

대용량 파일(이미지/동영상/첨부)

GitHub는 큰 파일에 제한이 있고, Git은 바이너리 변경에 약하다. 첨부가 많으면 저장소가 금방 비대해진다. 선택지는 셋이다.

첫째, 첨부 폴더를 아예 Git에서 제외한다.

둘째, 첨부를 최소화하고 이미지 크기를 줄인다.

셋째, 꼭 버전 관리가 필요하면 Git LFS를 고려한다(환경 제약이 있으면 운영이 복잡해질 수 있음).

.obsidian 폴더를 추적할지 여부

.obsidian에는 플러그인/테마/핫키 같은 개인 설정이 있다. 팀 공유가 아니라 개인 볼트라면 "핵심만 추적"이 보통 더 낫다. 예를 들어 워크스페이스 레이아웃처럼 기기마다 다른 설정은 제외하는 식이다.

동기화 루프(계속 커밋이 생김)

자동 포맷, 플러그인 캐시, 워크스페이스 변경 등이 원인이다. 해결은 "변경이 자주 생기는 파일을 ignore"하거나 "자동 커밋 간격을 늘리는 것"이다. 특히 아래는 루프 원인이 되기 쉬워서 제외 후보가 된다.

  • .obsidian/workspace*

  • .obsidian/cache

  • 일부 플러그인의 데이터 폴더

파일명 충돌(대소문자)

macOS/Windows는 대소문자 구분이 약한 파일시스템이 많고, 리눅스는 구분한다. Note.md와 note.md를 동시에 만들면 어떤 기기에서는 충돌한다. 파일명 규칙을 정해 예방한다(예: 소문자+하이픈만 사용).

모바일 iOS 제한

iOS에서는 백그라운드 실행이 제한적이라 자동 push/pull이 끊기기 쉽다. iOS에서 Git 기반 동기화를 고집한다면 "앱 전환/잠금 전에 수동 sync"를 루틴으로 잡는 게 낫다.

보안/운영 팁(.gitignore 예시 포함)

개인키/토큰 관리는 "유출 시 즉시 폐기 가능"하게 만든다. PAT는 만료일을 두고, SSH 키는 가능하면 패스프레이즈를 건다. OpenClaw에 키나 토큰을 둘 때는 세션/파일 시스템이 공유되는 환경인지부터 확인하고, 공유 가능성이 있으면 저장을 피하거나 권한을 강하게 잠근다.

저장소는 기본적으로 Private를 권한다. 노트에 개인정보, 업무 정보, 학습 기록이 섞이면 공개 저장소는 리스크가 크다.

브랜치 전략은 단순하게 간다. 혼자 쓰는 볼트는 main 단일 브랜치로 충분하다. 실험을 많이 하면 main은 안정용, wip 같은 브랜치를 임시로 두고 정리될 때만 main에 합친다.

백업/복구는 "GitHub 외부 백업"을 하나 더 둔다. GitHub 자체도 사고(삭제, 계정 문제)가 날 수 있으니, 주기적으로 ZIP 백업을 로컬/클라우드에 하나 더 만든다.

.gitignore 예시는 아래에서 시작해, 실제로 변화가 잦은 파일을 보며 조정한다.

# OS
.DS_Store
Thumbs.db

# Obsidian - 자주 변하는 UI/캐시 (필요에 따라 조정)
.obsidian/workspace*
.obsidian/cache/

# 특정 플러그인 데이터(예: 인덱스/캐시 성격)
.obsidian/plugins/**/data.json
.obsidian/plugins/**/cache/

# 로그/임시파일
*.log
*.tmp

반대로, 여러 기기에서 동일하게 유지하고 싶은 설정(핵심 플러그인 목록, 설정 파일 등)은 ignore하지 말고 추적한다. 결론은 "동기화 가치가 있는 것만 남기고, 기기/세션마다 흔들리는 파일은 빼서 충돌과 루프를 줄이는 것"이다.

이 노트는 요약·비평·학습 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.