요약 (TL;DR): OpenOPC는 목표를 중심으로 AI 에이전트 팀을 구성하고, 이들이 스스로 조직화하며, 업무를 인계하고, 매 실행으로부터 학습하는 오픈 소스 Python 프레임워크입니다. 이 포스트에서는 uv를 이용한 설치, 첫 번째 작업, Company Mode(기업 모드), 그리고 Office UI에 대해 살펴봅니다.

OpenOPC의 실체

몇 주 전 OpenOPC를 처음 접했을 때, 저는 이것이 단순히 LLM을 터미널에 연결하고 "AI 개발자"라고 부르는 또 다른 에이전트 래퍼(agent wrapper)일 것이라고 생각했습니다. 하지만 그렇지 않았습니다.

HKUDS 연구 그룹이 구축한 OpenOPC는 조정 런타임(coordination runtime)입니다. 당신이 목표를 부여하면, OpenOPC는 역할(roles)과 보고 체계(reporting lines)를 갖춘 조직을 구축합니다. 그런 다음 해당 역할에 AI 직원들을 배치하고, 업무를 항목으로 분해하며, 작업이 완료될 때까지 회사를 운영합니다.

세 가지 메커니즘이 이를 구동합니다 (이것은 제 말이 아닌 프로젝트 자체의 표현입니다):

• 자체 구축 (Self-Built) — 목표가 주어지면, OpenOPC는 조직도(org chart)를 초안하고 각 역할을 채웁니다. 리크루터 에이전트(recruiter agent)는 기존의 숙련된 직원(이전 실행을 통해 형성된 직원)을 재사용할지, 아니면 인재 풀에서 신입 사원을 채용할지를 결정합니다.

• 자체 운영 (Self-Run) — 작업 항목 상태 머신(work-item state machine)이 작업 분해(task decomposition), 의존성 해결(dependency resolution), 병렬 실행(parallel execution), 검토(reviews) 및 인계(handoffs)를 처리합니다. 차단 요소(Blockers)는 자동으로 에스컬레이션(escalate)됩니다. 먼저 팀 내부에서 처리되며, 팀의 권한을 초과하는 경우 당신에게 보고됩니다.

• 자체 성장 (Self-Grown) — 매 실행이 끝난 후, 결과는 특정 역할에 귀속됩니다. 교훈은 역할별 경험 프로필(experience profiles)로 추출됩니다. 반복되는 교훈은 신입 사원이 상속받는 공유 플레이북(playbooks)으로 승격됩니다.

"1인 기업"이라는 프레임워크는 문자 그대로입니다. 당신은 소유자(owner)이고, AI는 직원(staff)입니다.

시작하기 전에 필요한 사항

사전 요구 사항은 최소한입니다:

• Python 3.10+ — 설치 스니펫(snippets)은 3.12를 사용하지만, 3.10 이상이면 무엇이든 작동합니다.

• uv — Astral의 빠른 Python 패키지 매니저 (기술적으로는 선택 사항이지만, 프로젝트가 이를 중심으로 구축되어 있습니다)

• LLM API 키 — OpenRouter, OpenAI 또는 LiteLLM 호환 제공업체

• Node.js 18+ — Office UI 프론트엔드를 빌드해야 할 때만 필요합니다 (첫 실행 시 자동으로 빌드됩니다)

• Git — 리포지토리(repo)를 클론(clone)하기 위해 필요합니다

선택 사항: 브라우저 도구(페이지 탐색, 스크린샷, 양식 채우기)를 위한 playwright.

OpenOPC 단계별 설치 방법

리포지토리를 클론하고 환경을 설정하세요. 저는 macOS를 사용 중이지만, Linux도 거의 동일합니다.

# Clone
git clone https://github.com/HKUDS/OpenOPC.git
cd OpenOPC
...

opc init은 리포지토리 루트에 템플릿 설정(config), 메모리 및 스킬(skills) 폴더, 로그 디렉토리, 그리고 선택 사항인 첫 번째 프로젝트가 포함된 .opc/ 디렉토리를 생성합니다. 가장 먼저 신경 써야 할 파일은 .opc/config/llm_config.yaml입니다. 이 파일을 열고 API 키를 추가하세요:

llm:
  default_model: "openai/gpt-4o"
  api_base: "https://openrouter.ai/api/v1"
...

default_model을 사용 중인 제공업체의 라우팅 모델로 설정하세요 — 템플릿에는 합리적인 기본값이 포함되어 있습니다; 실제로 접근 가능한 모델로 교체하십시오. 만약 키를 파일에 남겨두고 싶지 않다면, api_key를 비워두고 api_key_env를 해당 키를 보유한 환경 변수(environment variable)의 이름으로 설정하세요 (예: OPENROUTER_API_KEY).

모든 것이 제대로 연결되었는지 확인합니다:

uv run opc status

에이전트(agents)를 위한 브라우저 도구가 필요한 경우:

uv run python -m playwright install chromium

첫 번째 작업: 태스크 모드(Task Mode) 사용하기

태스크 모드(Task Mode)는 OpenOPC를 사용하는 가장 간단한 방법입니다. 이는 단일 에이전트 작업 공간(single-agent workspace)입니다 — 당신의 프로젝트 도구에 접근할 수 있는 한 명의 AI 직원과 직접 대화한다고 생각하면 됩니다.

uv run opc chat -p demo --mode task --agent native

이 명령을 실행하면 대화형 채팅(interactive chat) 상태로 진입합니다. native 에이전트는 OpenOPC의 내장 런타임 (runtime)이므로 별도의 CLI가 필요하지 않습니다. 또한 codex, claude_code, cursor 또는 opencode가 설치되어 있다면 이를 사용할 수도 있습니다.

수행할 작업을 입력하세요:

Inspect the project structure and summarize what each top-level directory does

에이전트는 셸 (shell), 파일 (file), 검색 (search) 도구를 사용하여 탐색하고 응답할 것입니다. 대화형 채팅 없이 단발성 스크립팅 (one-shot scripting)을 수행하려면 opc exec를 사용하세요:

uv run opc exec -p demo --mode task --agent native --json "Summarize the current repo status"

--json 플래그를 사용하면 다른 도구로 파이프 (pipe) 할 수 있는 구조화된 출력 (structured output)을 얻을 수 있으며, 이는 CI 또는 자동화에 유용합니다. (결과가 생성되는 대로 확인하고 싶다면 --stream-json 플래그도 있습니다.)

대화형 opc chat 세션 내에서는 슬래시 명령 (slash commands)을 통해 빠른 제어가 가능합니다:

/status          # 현재 프로젝트/세션 상태
/mode task       # 태스크 모드 (task mode)로 전환
/agent codex     # 실행 에이전트 (execution agent) 전환
...

규모 확장하기: 컴퍼니 모드 (Company Mode)

이 부분이 OpenOPC가 흥미로워지는 지점입니다. 컴퍼니 모드 (Company Mode)는 단순히 하나의 에이전트를 실행하는 것이 아니라, 팀 전체를 구축합니다.

uv run opc chat -p demo --mode company --company-profile corporate \
  "Plan, implement, review, and document a REST API for user management"

이후 진행되는 과정은 다음과 같습니다:

1. OpenOPC가 내장된 corporate 아키텍처 (architecture)를 읽습니다 (.opc/config/company_corporate_config.yaml에 정의됨).

2. 해당 작업을 위한 조직도 (org chart)를 초안합니다. 예를 들어 프로젝트 매니저 (project manager), 백엔드 개발자 (backend developer), 코드 리뷰어 (code reviewer), 기술 작가 (technical writer) 등이 구성될 수 있습니다.

3. 각 역할에 인원이 배치됩니다. 이전 실행에서 경험이 쌓인 직원들이 우선순위를 가지며, 부족한 부분은 신규 채용 인력이 채웁니다.

4. 작업은 의존성 (dependencies)이 있는 항목들로 분해됩니다. 독립적인 항목은 병렬로 실행되며, 의존성이 있는 항목은 대기합니다.

5. 각 역할은 업무를 인계하고, 서로의 결과물을 검토하며, 차단 요소 (blockers)를 에스컬레이션 (escalate) 합니다.

이 과정이 전개되는 것을 Office UI(아래에서 자세히 설명)를 통해 실시간으로 지켜보거나, CLI에서 추적할 수 있습니다:

uv run opc runtime status -p demo
uv run opc work-item list -p demo

Company Mode (기업 모드)의 핵심 설정은 .opc/config/system_config.yaml 파일의 자율성 (autonomy) 설정입니다:

autonomy:
  max_auto_approve_risk: medium   # low | medium | high | critical
  allow_native_tool_auto_approval: true
...

medium (기본값) 설정에서는 일반적인 명령어가 묻지 않고 실행됩니다. 위험한 작업 — rm -rf, 강제 푸시 (force push), 자격 증명 (credential) 접근 — 은 high/critical 위험으로 분류되어 항상 사용자에게 승인을 요청합니다. 공유 환경이나 운영 (production) 머신에서는 안전한 허용 목록 (allowlist, ls, git status 등)에 없는 모든 사항을 승인하고 싶다면 low로 설정하십시오.

Office UI — 당신의 AI 기업 대시보드

CLI는 기능적이지만, 실제로 어떤 일이 일어나고 있는지 눈으로 확인할 수 있는 곳은 Office UI입니다.

uv run opc ui

http://localhost:8765를 여십시오 (기본 포트이며, opc ui --port 9000으로 변경 가능합니다). 세 개의 페이지가 있습니다:

Workspace (워크스페이스) — 메인 인터페이스입니다. 왼쪽에는 세션 목록이, 중앙에는 워크플로 (workflow)에 따라 이동하는 작업 항목 (work items)을 보여주는 칸반 보드 (kanban board)가, 오른쪽에는 채팅, 에이전트 상태, 통신 (comms) 및 팀 정보가 포함된 컨텍스트 패널 (context panel)이 있습니다.

Office (오피스) — 애니메이션화된 픽셀 아트 사무실 (프론트엔드는 React + Phaser 사용)로, 각 에이전트가 책상에 앉은 캐릭터로 나타납니다. 누가 작업 중인지, 누가 유휴 (idle) 상태인지, 어떤 도구 (tool)를 실행 중인지, 어떤 태스크 (task)를 담당하고 있는지 확인할 수 있습니다. 이는 단순한 장식이 아닙니다. 에이전트를 클릭하면 해당 에이전트의 실행 세부 정보를 열 수 있습니다.

Org (조직) — 기업 아키텍처 (architecture) 편집기입니다. 기업용 또는 사용자 정의 조직 템플릿 간에 전환하고, 역할을 추가하거나 제거하며, 보고 체계 (reporting lines)를 조정하고, 인재 시장에서 인력을 채용하며, 역할별 런타임 정책 (runtime policy)을 검사할 수 있습니다.

UI에서 작업을 시작하려면: 프로젝트를 생성하고,

Task Mode(태스크 모드)와 Company Mode(컴퍼니 모드)에 익숙해지면, 다음과 같은 몇 가지 방향이 열립니다.

외부 에이전트 (External agents). OpenOPC는 Codex, Claude Code, Cursor, 그리고 OpenCode에 작업을 위임할 수 있습니다. .opc/config/agent_config.yaml에서 이들의 명령 경로(command paths)와 타임아웃(timeouts)을 설정하세요. Company Mode에서는 개별 역할(roles)별로 특정 외부 에이전트를 선호하도록 설정할 수 있습니다.

uv run opc chat -p demo --mode task --agent codex "Refactor this module"

채널 (Channels). OpenOPC를 Slack, Telegram, Discord, Feishu, Email, Matrix, WhatsApp 등과 연결할 수 있습니다. 각 채널은 추가 설치(install extra) 항목입니다:

uv run pip install -e .[channels-slack]
uv run opc channels login slack
uv run opc channels start -p demo
...

인바운드 메시지(Inbound messages)가 들어오면 적절한 프로젝트로 라우팅되어 에이전트 작업을 트리거합니다. 발신자 목록은 기본적으로 거부(deny-by-default) 상태이므로, 사용자가 허용하기 전까지는 아무것도 실행되지 않습니다.

인재와 마켓플레이스 (Talent and the marketplace). 커뮤니티 인재 라이브러리(talent libraries)를 가져오고, 특정 템플릿을 역할(roles)로 채용하며, 조직 전체를 공유 가능한 .opcpkg 파일로 내보낼 수 있습니다:

uv run opc talent import /path/to/agency-agents
uv run opc market export --id my_company --name "My Company" --output-dir packages

브라우저 도구 (Browser tools). Playwright가 설치되어 있으면 에이전트는 네이티브 브라우저 도구인 browser_navigate, browser_snapshot, browser_click, browser_type, browser_take_screenshot 등을 사용할 수 있습니다. system_config.yaml에서 헤드리스(headless)/헤디드(headed) 모드를 설정하세요.

MCP 서버 (MCP servers). OpenOPC는 MCP(Model Context Protocol)도 지원합니다. system_config.yaml의 mcp_servers 항목 아래에 로컬(stdio) 또는 원격(HTTP/SSE) 서버를 등록하면, 충돌을 방지하기 위해 서버 접두사(prefix)와 함께 해당 도구들이 나타납니다. 서버를 설정하는 대신 직접 구축하고 싶다면, mcpkit을 사용하여 OpenAPI 명세(specs), 데이터베이스 또는 YAML로부터 MCP 서버를 생성할 수 있습니다.

이 프로젝트는 MIT 라이선스이며 활발하게 개발되고 있습니다. GitHub repo에서 전체 문서를 확인할 수 있습니다. 저는 제 자신의 저장소(repos)를 대상으로 실행되는 Company Mode(기업 모드)에 어느 정도의 자율성(autonomy)을 부여할지 여전히 고민 중이지만, Task Mode(태스크 모드)는 이미 단순한 채팅 세션보다 유용한 진전이라고 느껴집니다. 또한 자율성 조절 다이얼(autonomy dial)을 통해 처음에는 엄격하게 시작하고 신뢰가 쌓임에 따라 점차 완화할 수 있습니다. 도구(tooling)와 제품 출시(shipping)에 대한 저의 생각에 대해 더 자세히 알고 싶다면, journal에서 나머지 내용을 다루고 있습니다.