OpenDocs — 마크다운을 공유 가능한 URL과 PDF/DOCX로 게시하기
OpenDocs는 모든 마크다운 파일을 깔끔하고 읽을 수 있는 URL로 변환하고, 동시에 사용자가 오프라인으로 공유할 수 있는 브랜딩된 PDF나 Word 문서로 내보냅니다. opendocs CLI를 통해 상호작용합니다.
빠른 참조
opendocs login --email [email protected] # 로그인 또는 회원가입: 6자리 코드 이메일 전송
opendocs login --email [email protected] --code 123456 # 완료: API 키 저장
opendocs login --browser # 사람 친화적인 브라우저 로그인
opendocs login --key od_live_xxxxx # 기존 API 키 사용
opendocs publish doc.md # 하나의 마크다운 파일 게시 → URL 획득
opendocs publish doc.md # ...같은 문서 업데이트 (중복 생성 안 함)
opendocs publish doc.md --anonymous # 계정 없음: 24시간 동안 누구나 열 수 있는 링크 + 클레임 URL
opendocs clone # 워크스페이스를 ./<workspace>로 다운로드하여 편집
opendocs status # 마지막 동기화 이후 로컬/온라인 변경 사항
opendocs history <doc> # 게시된 모든 버전
opendocs rollback <doc> <version> # 버전 복원 (새 버전으로)
opendocs move <doc> --project "Archive" # 프로젝트 간 이동
opendocs share <doc> [email protected] @acme.com # 워크스페이스 외부 사용자에게 액세스 부여
opendocs team invite [email protected] # 팀원 초대 (이메일로 수락)
opendocs team join # 나에게 전송된 초대 수락
opendocs theme # PDF/DOCX 내보내기에 사용되는 브랜드 색상, 글꼴, 로고, 바닥글
opendocs theme set --preset editorial --yes # 내보내기 테마 변경 (사용자 확인 필요)
opendocs integrations # Google Drive / DocuSeal: 연결된 항목, 명명된 Drive 폴더
opendocs save <doc> --folder "Board Minutes" # PDF (또는 --format docx|md)를 명명된 Drive 폴더에 저장
opendocs sign request <doc> --signer "Employee=John Adams <[email protected]>" # 서명 요청 초안 생성 (전송 안 함)
opendocs sign send <id> --yes # 사용자가 모든 서명자를 확인한 후에만 초안 전송
opendocs sign status <id> # 서명한 사람, 서명 목록/다운로드/저장/취소 가능
opendocs workspace create "Acme Research" # 새 워크스페이스 생성
opendocs project link "Acme launch" # 이 폴더에서 게시된 문서를 해당 프로젝트로 연결
opendocs config set organize auto # 에이전트가 질문 없이 문서를 프로젝트로 자동 분류
opendocs claim # 이 폴더에서 게시된 익명 문서 클레임
opendocs publish *.md # 여러 파일 게시 (자동 배치, 최대 500개)
opendocs publish ./vault --tags obsidian # 폴더/볼트 재귀적으로 게시
opendocs publish *.md --export pdf # 게시 및 내보내기 — PDF가 각 소스 파일 옆에 생성됨
opendocs update doc.md --post-id <id|slug> # 기존 게시물 업데이트 (새 버전)
opendocs list # 활성 워크스페이스의 문서 목록 (별칭: `opendocs ls`)
opendocs list --all # 속한 모든 워크스페이스의 문서 목록
opendocs project create <name> --use # 관련 문서 배치를 위한 프로젝트 생성/전환
opendocs project use <slug> # 활성 프로젝트 전환
opendocs list --tag <tag> # 태그로 필터링 (배치 찾기에 유용)
opendocs search <words> # 모든 프로젝트에서 제목 또는 요약으로 문서 검색
opendocs get <id|slug> # 게시물 세부 정보 보기
opendocs pull <id|slug> # 원시 마크다운 다운로드
opendocs pull --project # 활성 프로젝트의 모든 문서 다운로드
opendocs pull --workspace # 활성 워크스페이스의 모든 문서 다운로드
opendocs export <id|slug> --format pdf # 게시된 게시물을 PDF (또는 docx)로 내보내기
opendocs export a b c --format pdf # 최대 10개 게시물을 한 번에 배치 내보내기 (UUID 또는 슬러그)
opendocs unpublish <id|slug> # 게시물을 오프라인으로 전환 (콘텐츠와 기록은 유지, 재게시 불가)
opendocs visibility <id|slug> <level> # 마크다운을 재업로드하지 않고 가시성 변경
opendocs delete <id|slug> --yes # 게시물 영구 삭제 (슬러그 및 할당량 슬롯 해제)
opendocs whoami # 현재 사용자/워크스페이스/프로젝트 표시
opendocs workspace list # 속한 모든 워크스페이스 목록 (별칭: `workspace ls`)
opendocs workspace use <slug> # 활성 워크스페이스 전환 (별칭: `workspace switch`)
opendocs agent # 간결한 AI 에이전트 지침 출력
opendocs agent --full # 전체 번들 SKILL.md 출력
opendocs agent --install # 이 머신의 모든 에이전트에 이 스킬 설치
opendocs mcp add # 코딩 도구에 OpenDocs MCP 서버 등록
opendocs mcp connect claude # Claude 앱에 OpenDocs 추가 (또는: chatgpt)
opendocs logout # 저장된 자격 증명 지우기
모든 명령어는 --json을 지원하여 기계가 읽을 수 있는 출력을 제공하고, --api-url <url>로 API 엔드포인트를 재정의할 수 있습니다. 프로그래밍 방식으로 실행할 때는 항상 --json을 전달하세요. 표준 출력은 단일 파싱 가능한 JSON 객체가 되고, 오류는 표준 오류로 전달되며, 사람이 읽을 수 있는 스피너는 표시되지 않습니다.
<postId>를 받는 모든 명령어는 slug도 허용합니다. slug는 URL에서 사람이 읽을 수 있는 경로 세그먼트이며 활성 프로젝트 내에서 고유합니다. 사용자가 자연어로 문서를 지정할 때는 post slug를 선호하세요. opendocs get my-report는 opendocs list --json에서 UUID를 복사하는 것보다 친숙합니다. 내부적으로 API는 활성 워크스페이스/프로젝트로 범위가 지정된 인덱스 조회를 통해 slug를 postId로 확인한 다음 UUID 경로와 동일한 소유권 검사를 수행합니다.
워크스페이스 slug와 사용자 이름은 서로 다릅니다. URL은 사용자 이름이 아닌 워크스페이스 slug로 구성됩니다. 기본 프로젝트 문서는 opendocs.cc/<workspace>/<post>를 사용합니다. 기본이 아닌 프로젝트 문서는 opendocs.cc/<workspace>/projects/<project>/<post>를 사용합니다. 사용자 이름은 UI에서 속성 표시용으로 여전히 존재하지만 게시된 URL에는 나타나지 않습니다.
MCP를 통한 OpenDocs
OpenDocs는 https://mcp.opendocs.cc/mcp에서 원격 MCP 서버도 실행합니다 (가이드: https://opendocs.cc/mcp). 각 앱은 처음 사용할 때 OAuth로 사용자를 OpenDocs에 로그인시킵니다. API 키는 필요하지 않습니다.
- 채팅 앱 (Claude, ChatGPT): 해당 URL로 사용자 정의 커넥터로 추가합니다.
opendocs mcp connect claude는 OpenDocs.cc가 미리 채워진 Claude의 "사용자 정의 커넥터 추가" 대화상자를 엽니다.opendocs mcp connect chatgpt는 ChatGPT의 플러그인 페이지를 엽니다 (그런 다음 "+" → "사용자 정의 MCP 서버 추가"). 둘 다 URL을 클립보드에 복사합니다. - 코딩 도구:
opendocs mcp add는 찾은 모든 도구 (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini, opencode, Kiro)에 등록하고 다른 도구를 위한 한 줄 지침을 출력합니다.--agent <id...>는 도구를 선택하고,--dry-run은 변경 사항을 미리 보여주며,opendocs mcp remove는 다시 제거하고,opendocs agent --install --mcp는 이 스킬과 서버를 함께 설치합니다. - MCP 도구 또는 CLI? OpenDocs MCP 도구를 사용할 수 있고 셸 명령을 실행할 수 없는 경우 CLI 대신 사용하세요. MCP 도구는 마크다운 텍스트를 직접 받습니다. 셸을 사용할 수 있는 경우 로컬 파일, 폴더 및 이미지에 대해 CLI를 선호하세요. 로컬 이미지를 업로드하고, 전체 폴더를 배치로 게시하며, 각 폴더가 게시한 내용을 기억합니다.
설정
설치
에이전트에 OpenDocs를 설치하는 방법:
# Node.js 20+: 전체 CLI (권장), 그런 다음 찾은 모든 에이전트에 이 스킬 설치
npm install -g @opendocs.cc/cli
opendocs agent --install # SKILL.md + scripts/opendocs.sh, 네트워크 필요 없음
# Node.js 22+: skills CLI를 통한 동일한 스킬
npx skills add opendocs-cc/skills --skill opendocs -g -y
# Node.js 없음: 이 스킬 + scripts/opendocs.sh 설치 (curl + jq)
curl -fsSL https://opendocs.cc/install.sh | bash
opendocs agent --install은 구성 폴더가 존재하는 각 에이전트의 전역 스킬 폴더에 설치합니다: ~/.claude/skills (Claude Code), 공유 ~/.agents/skills (Codex, Cursor, GitHub Copilot, Gemini CLI, opencode, OpenClaw, Windsurf, Amp, Goose, Grok Build), ~/.cline/skills, ~/.hermes/skills 및 ~/.kiro/skills. opendocs agent --list는 각 에이전트의 폴더와 발견 여부를 표시합니다. --agent <id...>는 발견되지 않은 에이전트에 대해서도 특정 에이전트용으로 설치합니다 (--agent claude-code codex). CLI를 업데이트한 후 다시 실행하여 스킬을 업데이트하세요. 어떤 폴더에 썼는지 출력합니다. --json과 함께 사용하면 installed[]에 agent, path 및 status가 포함됩니다.
Claude Code에서는 OpenDocs.cc 플러그인으로도 설치할 수 있습니다. 이 플러그인은 /opendocs-cc:publish 및 /opendocs-cc:export를 추가하고, MCP 서버를 연결하며, 스킬을 최신 상태로 유지합니다: /plugin marketplace add opendocs-cc/skills, 그런 다음 /plugin install opendocs-cc@opendocs-cc. Codex에서: codex plugin marketplace add opendocs-cc/skills, 그런 다음 codex plugin add opendocs-cc@opendocs-cc.
npx skills add는 ✗ opendocs → PromptScript: PromptScript does not support global skill installation으로 끝날 수 있습니다. 이는 PromptScript에만 영향을 미치는 알려진 설치 프로그램 버그입니다. 스킬은 설치되므로 계속 진행하세요.
opendocs 명령을 사용할 수 없고 Node.js가 설치되지 않은 경우 대신 bash scripts/opendocs.sh (이 스킬의 폴더에 있음)를 사용하세요. "Node.js 없이" 아래를 참조하세요. 이 가이드의 다른 모든 내용은 둘 다에 적용됩니다.
CLI 설치 및 인증 확인
opendocs --version # 설치된 CLI 버전 출력
opendocs whoami # 사용자 이름 + 워크스페이스 이름 표시 (URL slug는 JSON 출력에 있음)
opendocs whoami --json은 에이전트에게 가장 유용한 진단 명령어입니다. 게시물 URL 구축을 위한 CLI의 활성 워크스페이스 slug와 계정/워크스페이스 컨텍스트 및 문서 할당량을 한 번에 반환합니다:
{
"userId": "...",
"onboarding": { "username": "...", "workspace": { "id": "...", "name": "Acme Docs", "slug": "acme-docs" } },
"quota": { "documents": { "plan": "free", "limit": 50, "used": 3, "remaining": 47 } }
}
Pro/Team 워크스페이스의 경우 quota.documents.limit 및 remaining은 null입니다 (무제한 의미). 게시 엔드포인트는 요청 본문의 명시적 workspaceId에 대해 할당량을 다시 확인하므로 오래된 로컬 구성으로 서버 적용을 우회할 수 없습니다.
CLI가 없는 경우:
npm install -g @opendocs.cc/cli
사용자가 로그인하지 않은 경우, 첫 게시 전에 터미널에서 이메일로 전송된 코드를 사용하여 가입 (또는 로그인)시키세요. 브라우저나 API 키 복사가 필요 없습니다. 계정은 최대 50개 문서까지 무료이며 링크가 유지되고, 워크스페이스에 대해 비공개로 유지되며, 제자리에서 업데이트되고 PDF로 내보낼 수 있으므로 기본적으로 사용자가 원하는 것입니다.
- 사용자에게 이메일 주소를 요청하세요.
opendocs login --email <email> --json을 실행합니다. 6자리 코드를 이메일로 보내고 즉시{"status": "code_sent", ...}와 함께 종료됩니다.- 사용자에게 "OpenDocs에서 보낸 받은 편지함의 로그인 코드를 확인하여 여기에 붙여넣으세요."라고 알립니다.
opendocs login --email <email> --code <code> --json을 실행합니다.
이메일이 새로운 경우 계정, 사용자 이름, 워크스페이스 (opendocs.cc/<username>) 및 기본 프로젝트를 생성한 다음 에이전트 이름 (예: claude-code)의 새 API 키를 CLI 구성에 저장합니다. 기존 계정은 새 키만 얻습니다. opendocs signup은 별칭입니다. 코드는 10분 후 만료되며 5번의 시도를 허용합니다. invalid_code의 경우 최신 이메일을 요청하고, code_expired의 경우 2단계를 다시 실행하세요.
사용자가 아직 계정을 원하지 않는 경우에만 대신 익명 게시를 제공하세요:
opendocs publish notes.md --anonymous --json
반환된 url이 있는 사람은 누구나 24시간 동안 읽을 수 있으며 그 후에는 삭제됩니다. 반환된 대로 claimUrl을 사용자에게 정확히 공유하고, 저장을 위해 가입을 제안하세요. 나중에 같은 폴더에서 opendocs login --email ...을 실행하면 자동으로 새 워크스페이스에 클레임됩니다 (또는 opendocs claim 실행). 사용자가 누구나 열 수 있는 링크가 괜찮다고 동의하지 않는 한 익명으로 게시하지 마세요.
로그인하는 다른 방법: 터미널의 사람은 opendocs login --browser를 사용할 수 있습니다. 스크립트 및 CI는 기존 키를 사용할 수 있습니다:
opendocs login --key od_live_xxxxx
# 또는 스크립트/CI를 위해 환경 변수로 전달:
export OPENDOCS_API_KEY=od_live_xxxxx && opendocs login
에이전트에서 opendocs login을 그대로 실행하지 마세요. --email, --key 또는 환경 변수 없이 표준 입력에서 API 키를 요청하고 도구 호출이 중단됩니다. OPENDOCS_API_URL은 기본 https://api.opendocs.cc 엔드포인트를 재정의합니다.
여러 워크스페이스 작업
사용자는 둘 이상의 워크스페이스에 속할 수 있습니다. 개인 무료 워크스페이스와 Team 플랜 워크스페이스, 여러 Team 워크스페이스 또는 모든 조합이 가능합니다. CLI는 ~/.config/opendocs/config.json에 한 번에 하나의 활성 워크스페이스를 저장합니다. publish 및 update는 해당 활성 워크스페이스 (URL 접두사, 할당량 및 모든 것)에 대해 작동합니다. list도 기본적으로 활성 워크스페이스를 대상으로 하며, 사용자가 모든 워크스페이스의 게시물을 한 번에 보려는 경우 --all이 탈출구입니다. 변경 명령어에는 명령어별 --workspace 플래그가 없습니다. 전환은 한 번 구성되고 변경할 때까지 지속됩니다.
프로젝트 작업
각 워크스페이스에는 기본 프로젝트와 선택적 명명된 프로젝트가 있습니다. 에이전트가 제품, 출시, 클라이언트, 실험 또는 리포지토리에 대한 일관된 문서 배치를 게시할 때마다 프로젝트를 사용하세요. 기본 프로젝트는 일회성 문서에 가장 적합합니다.
opendocs project list --json
opendocs project create "OpenClaw docs" --slug openclaw-docs --use --json
opendocs publish ./docs --json
opendocs project use default --json
opendocs workspace use <slug>는 활성 프로젝트를 해당 워크스페이스의 기본 프로젝트로 재설정합니다. opendocs list는 기본적으로 활성 프로젝트를 표시하고 문서 수를 알려줍니다. 여러 문서를 게시할 때 디렉터리당 하나의 프로젝트를 생성하는 것이 좋습니다.
게시 후 프로젝트 연결
이미 게시된 문서를 프로젝트에 다시 연결할 수 있습니다. opendocs move <postId> --project <slug>를 사용하세요.
게시 흐름
opendocs publish는 소스 파일에 도우미를 추가하지 않고, 변환하지 않으며, 포크를 만들지 않습니다. 수정 없이 마크다운을 업로드하고 URL을 반환합니다. 마크다운에서 지원하는 모든 것 (이미지, 표, 수식, 코드 블록)이 그대로 작동합니다.
# 단일 파일
opendocs publish report.md
# 여러 파일 (모든 `.md` 파일)
opendocs publish *.md
# 폴더 (재귀적으로, Obsidian 볼트에 적합)
opendocs publish ./vault --tags obsidian
# 게시 및 PDF/DOCX로 내보내기
opendocs publish blog-post.md --export pdf
--export를 publish에 추가하면 게시를 완료한 후 내보내기가 실행됩니다. 수동 단계보다 빠르고, 특히 배치의 경우 더욱 그렇습니다. 각 내보내기 파일은 소스 마크다운과 같은 디렉토리에 저장됩니다.
내부적으로 publish는 항상 새 게시물을 만드는 POST 요청을 보내거나 X-HTTP-Method-Override: PUT을 사용하여 동일한 내용의 문서를 업데이트합니다. 게시물 ID는 UUID 형식이며 콘텐츠 무결성을 보장합니다. URL은 마크다운 파일 이름이 아닌 제목에서 생성됩니다.
새 버전 게시
opendocs publish updated-report.md --post-id <id|slug>
opendocs update updated-report.md --post-id <id|slug> # 동일
--post-id는 기존 게시물에 새 버전을 추가합니다. URL은 그대로 유지되고 방문자에게 새 콘텐츠가 표시됩니다. 게시 기록은 유지되며 opendocs history로 검사하고 opendocs rollback으로 복원할 수 있습니다.
게시물 살펴보기
게시된 문서를 나열하고, 검색하고, 다운로드하는 가장 일반적인 명령어:
opendocs list # 현재 프로젝트의 게시물
opendocs list --all # 모든 워크스페이스의 모든 게시물
opendocs search "Q3 report" # 제목/요약으로 검색
opendocs get my-report # 세부 정보 (슬러그 사용)
opendocs pull my-report # 원시 마크다운 다운로드
opendocs pull --project # 프로젝트의 모든 마크다운 다운로드
게시물 내보내기
브랜딩된 PDF 또는 Word 문서 생성:
opendocs export my-report --format pdf
opendocs export my-report --format docx
opendocs export a b c --format pdf # 배치 내보내기 (최대 10개)
내보내기 테마를 변경하려면 opendocs theme set을 사용하세요. opendocs theme은 현재 테마를 표시합니다.
게시물 관리
게시물 상태 관리:
opendocs unpublish my-report # 오프라인으로 전환
opendocs visibility my-report public # 공개로 변경
opendocs delete my-report --yes # 영구 삭제
Google Drive 통합
연결된 Google Drive 폴더에 문서 저장:
opendocs save my-report --folder "Board Minutes" # PDF로 저장
opendocs save my-report --folder "Board Minutes" --format docx # DOCX
opendocs save my-report --folder "Board Minutes" --format md # 마크다운
DocuSeal 전자 서명
서명 요청 보내기:
opendocs sign request doc.md --signer "Employee=John Adams <[email protected]>"
opendocs sign send <id> --yes
opendocs sign status <id>
--json을 지원합니다. opendocs sign 컴플리트 명령어로 가능한 모든 작업을 확인하세요:
opendocs sign --help
MCP 서버 연결
코딩 도구에 OpenDocs MCP 서버 추가:
opendocs mcp add # 찾은 모든 도구에 등록
opendocs mcp add --agent codex # 특정 도구만
opendocs mcp connect claude # Claude 앱
opendocs mcp connect chatgpt # ChatGPT
opendocs mcp remove # 모든 도구에서 제거
opendocs mcp --help는 전체 옵션을 보여줍니다.
팀
팀원 초대 및 관리:
opendocs team invite [email protected] # 이메일로 초대
opendocs team invite @acme.com # 도메인으로 초대
opendocs team join # 초대 수락
워크스페이스 관리
워크스페이스 생성 및 전환:
opendocs workspace create "Acme Research"
opendocs workspace use acme-research # 슬러그 사용
opendocs workspace list