AI 지식관리 파이프라인

학습 목표

• AI 코딩 에이전트 실습 환경(OpenCode, Codex CLI, Obsidian)을 구축한다
• OpenCode에 OpenAI provider를 연결하고 동작을 검증한다
• oh-my-openagent(omo) 플러그인으로 멀티 에이전트 환경을 완성한다

시작 전 확인

• ChatGPT Plus/Pro 이상 계정이 필요합니다 (Codex CLI 로그인용). 강의에서 배포한 class 계정을 사용하세요.
• 모든 실습은 WSL(Ubuntu) 안에서 진행합니다. Windows PowerShell/CMD가 아니라 Ubuntu 터미널에서 명령을 실행하세요 (Obsidian만 예외 — Windows 앱).

강의 슬라이드 — 새로운 지식관리 패러다임

이 장의 이론 배경(왜 지식관리인가, 검증 대역폭, PARA·제텔카스텐)을 다루는 강의 슬라이드입니다. 실습 전에 훑어보세요.

PDF 다운로드전체 화면에서 ←/→ 또는 스크롤로 이동 · Esc로 복귀

0. WSL 활성화 (Windows 필수)

CLI 에이전트들은 Linux 환경을 전제로 동작합니다. Windows에서는 WSL2 + Ubuntu를 먼저 준비합니다.

0.1 WSL 설치

PowerShell을 관리자 권한으로 열고:

wsl --install

• Ubuntu가 기본 배포판으로 함께 설치됩니다
• 완료 후 재부팅 필수

재부팅 후 Ubuntu 창이 열리면 사용할 UNIX 사용자명/비밀번호를 설정합니다 (Windows 계정과 무관).

이미 WSL이 있거나 오류가 나면

• 설치 확인: wsl --version (WSL2인지 확인), wsl -l -v (Ubuntu가 VERSION 2인지)
• WSL1로 잡혀 있다면: wsl --set-version Ubuntu 2
• wsl --install이 옵션 목록만 출력하면 이미 설치된 상태 — wsl --install -d Ubuntu로 배포판만 추가
• 가상화 오류(0x80370102): BIOS에서 가상화(VT-x/AMD-V) 활성화 필요

가상화를 켤 수 없는 PC라면 (BIOS 잠김·구형 CPU)

WSL1으로 폴백하세요 — 가상화 없이 동작합니다:

wsl --install -d Ubuntu
wsl --set-version Ubuntu 1

이 과정의 실습 도구(Node 기반 CLI)는 WSL1에서도 동작합니다. 폴백으로 진행하는 경우 강사에게 알려주세요 — 필요 시 원격 실습 계정을 지원합니다.

0.2 WSL 관리 명령어 레퍼런스

앞으로 자주 쓰게 될 명령들입니다. 모두 PowerShell(또는 CMD)에서 실행합니다:

목적	명령
설치된 배포판 목록 + 상태·버전	wsl -l -v
설치 가능한 배포판 목록	wsl --list --online
특정 배포판 설치	wsl --install -d <배포판>
기본 배포판 지정	wsl --set-default <배포판> (단축: wsl -s)
기본 배포판 실행	wsl
특정 배포판 지정 실행	wsl -d <배포판>
특정 사용자로 실행	wsl -d <배포판> -u <사용자>
WSL 버전 전환 (1↔2)	wsl --set-version <배포판> 2
상태·기본값 확인	wsl --status
WSL 자체 업데이트	wsl --update
특정 배포판 종료	wsl --terminate <배포판>
전체 종료 (VM 셧다운)	wsl --shutdown
배포판 삭제	wsl --unregister <배포판>
백업 (tar로 내보내기)	wsl --export <배포판> backup.tar
복원 (새 이름으로 가져오기)	wsl --import <새이름> <설치경로> backup.tar

삭제는 되돌릴 수 없다

wsl --unregister는 해당 배포판의 모든 파일을 즉시 삭제합니다 (휴지통 없음). 실습 vault가 안에 있다면 먼저 wsl --export로 백업하거나 파일을 복사해 두세요.

자주 쓰는 시나리오:

# 지금 뭐가 깔려 있고 뭐가 기본인지 확인
wsl -l -v

# Ubuntu를 기본으로 지정 → 이후 `wsl`만 치면 Ubuntu
wsl --set-default Ubuntu

# 실습 환경이 꼬였을 때 — 완전 초기화 (백업 후!)
wsl --export Ubuntu C:\backup\ubuntu-backup.tar
wsl --unregister Ubuntu
wsl --install -d Ubuntu

0.3 Ubuntu 기본 도구 준비

여기서부터 끝까지 전부 Ubuntu 터미널입니다:

sudo apt update && sudo apt install -y curl git unzip

0.4 Node.js 설치 (nvm 권장)

OpenCode·Codex·omo가 Node 기반이므로 먼저 설치합니다. sudo npm 권한 문제를 피하기 위해 nvm을 사용합니다:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
node --version   # v22+ 확인

0.5 WSL 성능 특성 — 파일을 어디에 두느냐가 전부다

WSL2는 경량 가상 머신입니다. 자원별 성능 특성이 다릅니다:

자원	성능	이유
CPU / 메모리 / GPU	네이티브 근접	경량 VM이 하드웨어를 거의 직접 사용
디스크 I/O — WSL 내부 (~/...)	빠름 (네이티브 ext4)	VM 전용 가상 디스크(ext4.vhdx) 직접 접근
디스크 I/O — OS 경계 통과	매우 느림	9P 네트워크 프로토콜로 파일 요청을 중계

OS 경계 통과란 양방향 모두입니다:

• WSL에서 Windows 파일 접근: /mnt/c/...
• Windows에서 WSL 파일 접근: \\wsl.localhost\...

얼마나 느린가 — 실측 기준

Microsoft 공식 문서도 "Linux 명령줄 작업 시 파일을 WSL 파일시스템에 저장하라"고 명시합니다. 실측으로는 대용량 순차 읽기·쓰기는 수 배 수준이지만, 작은 파일 수천 개를 반복 여닫는 작업(git, npm install, 에이전트의 코드 탐색 — 즉 우리 실습 전부)은 /mnt/c에서 수십 배까지 느려집니다 (microsoft/WSL#9430 벤치마크: 동일 작업 0.075초 vs 7초).

→ 실습 파일(vault, 프로젝트)은 반드시 WSL 홈(~/) 안에. /mnt/c에 프로젝트를 두는 순간 에이전트가 굼떠지는 이유가 이것입니다.

(Obsidian이 \\wsl.localhost로 vault를 여는 건 괜찮은가? — 사람이 노트를 읽고 쓰는 빈도는 낮아서 체감 문제가 없습니다. 반면 에이전트·git·빌드는 초당 수백 번 파일을 만지므로 반드시 WSL 내부에서 실행합니다.)

1. 설치

1.1 코드 에디터 — Zed (권장) 또는 VS Code

에이전트가 생성·수정한 코드를 읽고 검증할 에디터입니다. 둘 중 하나를 설치하세요.

Zed (권장)

Rust로 개발된 차세대 에디터입니다. Electron 기반 에디터(VS Code 등)와 달리 네이티브로 동작해 시작 속도·타이핑 반응·메모리 사용 모두 눈에 띄게 가볍고 빠릅니다. 마크다운 미리보기·AI 기능이 내장되어 있습니다.

# Windows PowerShell에서
winget install Zed.Zed

또는 zed.dev에서 Windows 인스톨러를 받으세요 (Windows 10 1903+ / 11 지원).

• 마크다운 미리보기: Ctrl+K V (편집 + 미리보기 나란히)

Zed는 WSL에서 어떻게 동작하나

Zed는 WSL을 네이티브로 지원합니다 (SSH 터널링 아님). 처음 WSL 폴더를 열면 Zed가 zed-remote-server라는 경량 서버를 WSL 안에 자동 설치(~/.zed_server/)하고, 이후 모든 파일 작업을 이 서버가 대신 수행합니다:

역할 분담이 핵심입니다:

Windows 쪽 (UI)	WSL 쪽 (서버)
화면 렌더링, 문법 하이라이팅	파일 읽기/쓰기 전부
미저장 변경 캐시	LSP(자동완성·오류 진단), 터미널, git, 빌드/테스트

파일 I/O·터미널·git이 전부 WSL 안에서 실행되므로, 0.5절의 9P 경계 페널티가 발생하지 않습니다 — 에이전트(opencode/codex)와 Zed가 같은 Linux 파일시스템을 보는 구조입니다.

WSL 폴더 여는 법:

방법 A — Zed에서: Ctrl+Alt+Shift+O → Add WSL Distro → Ubuntu → 폴더 선택
방법 B — WSL 터미널에서: cd ~/aiops-vault && zed .

알려진 한계

• 10만 파일 이상의 초대형 디렉토리(/, ~ 전체 등)를 여는 것은 느림 — 프로젝트 폴더 단위로 열 것
• WSL 안의 Zed 터미널에서 zed 파일명으로 새 파일 열기는 미지원

VS Code (대안)

이미 익숙하다면 VS Code도 좋습니다. WSL 연동이 원클릭입니다.

# Windows PowerShell에서
winget install Microsoft.VisualStudioCode

설치 후 WSL 확장(ms-vscode-remote.remote-wsl)을 설치하면, WSL 터미널에서 code .만으로 현재 폴더가 열립니다.

어느 쪽이든

에디터는 Windows에 설치하되, 열어서 작업하는 폴더는 항상 WSL 안(~/...)입니다 — vault/프로젝트 파일 위치 원칙과 동일합니다.

1.2 OpenCode

터미널 기반 AI 코딩 에이전트입니다. 이번 과정의 주력 도구로, 이후 모든 모듈에서 사용합니다.

# WSL(Ubuntu) 터미널에서
curl -fsSL https://opencode.ai/install | bash

# 또는 npm
npm install -g opencode-ai@latest

설치 확인:

opencode --version

설치가 실패한다면

• command not found: 터미널을 재시작하거나 source ~/.zshrc (설치 스크립트가 PATH를 수정함)
• npm 권한 오류: sudo 대신 nvm으로 Node를 설치한 뒤 재시도

1.3 Codex CLI

OpenAI의 코딩 에이전트 CLI입니다. ChatGPT 구독 계정으로 로그인해 사용합니다.

# WSL(Ubuntu) 터미널에서
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 또는 npm
npm install -g @openai/codex

첫 실행 및 로그인:

codex
# → "Sign in with ChatGPT" 선택
# → 브라우저가 열리면 배포받은 class 계정으로 인증

WSL에서 브라우저가 자동으로 안 열리면

터미널에 출력된 인증 URL(https://...)을 복사해서 Windows 브라우저에 붙여넣으면 됩니다. 인증 완료 후 터미널로 자동 복귀합니다.

로그인 확인 — 프롬프트에 간단한 요청을 입력해 응답이 오면 성공:

> 현재 디렉토리의 파일 목록을 보여줘

1.4 Obsidian

마크다운 기반 지식 관리 도구입니다. 우리의 지식 vault가 곧 에이전트의 작업 공간이 됩니다.

Obsidian만 유일하게 Windows 쪽에 설치합니다 (GUI 앱):

# Windows PowerShell에서
winget install Obsidian.Obsidian

또는 공식 다운로드 페이지에서 Windows 인스톨러를 받으세요.

vault는 WSL 안에 만들고, Obsidian에서 네트워크 경로로 엽니다:

# WSL(Ubuntu) 터미널에서 — vault 디렉토리 생성
mkdir -p ~/aiops-vault

Obsidian 실행 → 보관소로 폴더 열기 → 경로 입력:

\\wsl.localhost\Ubuntu\home\<사용자명>\aiops-vault

왜 이렇게 나누나

• vault는 WSL에: 에이전트(WSL에서 실행)가 빠르게 읽고 쓰기 위해
• Obsidian은 Windows에: GUI 렌더링이 네이티브라서 쾌적
• 같은 폴더를 양쪽에서 보는 구조 — 에이전트가 노트를 수정하면 Obsidian에 즉시 반영됩니다

2. 설정 — OpenCode에 OpenAI provider 연결

OpenCode는 여러 LLM provider를 지원합니다. provider 연결과 모델 선택 모두 TUI 명령으로 처리합니다.

2.1 provider 연결 — /connect

opencode

TUI에서:

/connect
# → provider 목록에서 OpenAI 선택
# → API 키 입력 (강의에서 배포)

API 키 주의

API 키를 설정 파일이나 git 저장소에 절대 넣지 마세요. /connect로 등록하면 OpenCode가 키를 안전한 자격 증명 저장소에 보관합니다. 키가 코드에 들어가는 순간 유출 사고입니다.

2.2 모델 선택 — /models

/models
# → 연결된 provider의 모델 목록이 뜸
# → 강의에서 안내하는 모델 선택 (예: gpt-4o 계열)

선택한 모델은 이후 세션에도 유지됩니다.

참고 — 설정 파일로 고정하기 (선택)

매번 선택하지 않고 프로젝트/전역 기본 모델을 고정하려면 ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openai/<model-id>"
}

형식은 "<provider>/<model-id>". 팀 전체가 같은 모델을 쓰도록 표준화할 때 유용합니다 (API 키는 절대 여기에 넣지 않습니다).

2.3 동작 검증

opencode

프롬프트에 입력:

> 안녕? 지금 어떤 모델로 동작 중이야?

모델 응답이 돌아오면 provider 연결 성공입니다.

3. oh-my-openagent (omo) 플러그인 설치

OpenCode에 다음을 추가하는 플러그인입니다. 이후 모듈(멀티 에이전트, 장애 분석)의 실습이 이 기능들 위에서 진행됩니다.

• 공식 저장소: github.com/code-yeongyu/oh-my-openagent

기능	설명
메인 에이전트	Sisyphus — 계획·위임·완료까지 오케스트레이션
병렬 백그라운드 에이전트	Oracle(아키텍처·디버깅 자문), Librarian(문서·코드 검색), Explore(코드베이스 검색), Hephaestus(자율 실행)
LSP/AST 도구	정밀한 코드 탐색·리팩토링, Hash-Anchored Edit
큐레이션된 MCP	Exa(웹 검색), Context7(공식 문서), Grep.app(GitHub 검색)
ultrawork	프롬프트에 한 단어 — 전체 에이전트 활성화, 끝날 때까지 자동 진행

이름 변경 안내

oh-my-opencode에서 oh-my-openagent로 리네이밍됐습니다 (2026). 전환기라 npm 패키지·설정 파일은 옛 이름도 함께 인식됩니다 — 문서·블로그에서 두 이름이 혼용돼도 같은 프로젝트입니다.

3.1 설치

# 대화형 설치 (Bun 권장, npm도 가능)
bunx oh-my-openagent install
# 또는
npx oh-my-openagent install

설치 마법사가 에이전트 구성을 안내합니다 — 기본값으로 진행해도 됩니다.

3.2 설정 파일 위치

범위	경로
사용자 전역	~/.config/opencode/oh-my-openagent.jsonc
프로젝트별	.opencode/oh-my-openagent.jsonc

(구 이름 oh-my-opencode.json[c]도 전환기 동안 인식됩니다)

3.3 설치 확인

OpenCode를 재시작한 뒤:

opencode
# 에이전트 목록에 Sisyphus, oracle, librarian, explore가 보이면 성공

문제가 있으면 내장 진단 도구를 실행하세요:

bunx oh-my-opencode doctor
# 플러그인 등록·설정·모델·환경을 자동 점검

체크포인트 — 여기까지 완료하면

✅ WSL2 + Ubuntu ✅ opencode ✅ codex ✅ obsidian (Windows) + WSL vault 연결 ✅ 에디터 (Zed 권장) ✅ OpenAI provider ✅ omo 플러그인

다음 장부터 이 환경 위에서 Obsidian vault ↔ 에이전트 연동과 지식 파이프라인 구축을 진행합니다.

다음 단계

• vault를 에이전트 작업 디렉토리로 연결
• 운영 지식 노트 작성 → 노트 기반 자동 구현 실습

관련 노트

• 교재 목차