YOHAN STUDIO GUIDE · 2026.08.14 기준
Codex 앱에 Luna · Max를
연결하는 설치 가이드
설치 명령과 실제 작동 여부는 다릅니다. 운영체제별 지원 상태를 먼저 확인한 뒤 검증된 환경에서만 진행해 주세요.
공식 v0.5.0은 Windows에서 PLUGIN_DATA 권한을 POSIX 방식으로 검사해 설정 MCP가 차단됩니다. PR #22 기반 로컬 수정본은 설정 저장과 검증을 통과했지만 공식 배포본이 아니며, 현재 Codex 호스트에는 필수 wait_threads 도구도 없습니다. maintainer가 수정본을 확정하고 Luna · Max 전체 경로가 통과하기 전에는 정상 지원으로 안내하지 않습니다.
CHOOSE YOUR PATH
먼저 사용 환경을 확인해 주세요
플러그인을 설치하는 장소와 Luna를 실행하는 장소가 다릅니다. 같은 명령을 모든 앱에 적용하면 동작하지 않습니다.
Windows PowerShell 또는 macOS 터미널에서 플러그인 명령을 실행합니다.
새 작업을 열고 현재 요청에 Luna 작업 경로 승인 문장을 넣습니다.
| 사용 환경 | 플러그인 설치 | Native 경로 | Luna · Max 경로 |
|---|---|---|---|
| Codex 앱 · Windows | 터미널에서 설치 | 공식 v0.5.0 설정 차단 | 필수 도구 5/6 |
| Codex 앱 · macOS | 터미널에서 설치 | 원본 절차 제공 | Yohan 실기기 미검증 |
| Codex CLI · Windows | CLI에서 설치 | v0.5.0 설정 차단 | 앱 작업 경로 아님 |
| Codex CLI · macOS/Linux | CLI에서 설치 | 원본 절차 제공 | 앱 작업 경로 아님 |
| Cursor·VS Code·Copilot·Kiro | 클라이언트별 별도 절차 | 원본의 클라이언트별 제한 확인 | 지원하지 않음 |
| 웹·모바일 | 범용 설치 없음 | 프롬프트 안내만 가능 | 지원하지 않음 |
Luna · Max 경로에는 list_projects, list_threads, create_thread, wait_threads, read_thread, send_message_to_thread가 모두 필요합니다. 하나라도 없으면 Sol Advisor는 다른 모델로 대체하지 않고 중단합니다.
Yohan Studio가 실제로 재현한 환경은 Windows입니다. macOS·Linux 표기는 원본 설치 계약을 반영한 것이며, 이 페이지에서 실기기 전체 경로를 통과했다고 주장하지 않습니다.
Windows 권한 검사 이슈 #20 확인 ↗Windows ACL 수정 PR #22 확인 ↗PREREQUISITES
Codex CLI와 Bun을 확인해 주세요
플러그인 명령에는 Codex CLI가, Sol Advisor의 MCP 서버에는 Bun이 필요합니다. 사용하는 터미널에서 두 명령을 차례로 확인해 주세요.
codex --versionnpm이 만든 codex.ps1이 먼저 선택된 환경에서는 아래처럼 codex.cmd를 사용해 주세요. 실행 정책을 변경하지 않아도 됩니다.
codex.cmd --versionbun --versionBun 설치 자체는 가능하지만 공식 Sol Advisor v0.5.0 설정 MCP는 이슈 #20으로 차단됩니다. 현재는 설치 확인까지만 진행해 주세요.
powershell -c "irm bun.sh/install.ps1|iex"Linux에서는 설치 전에 unzip 패키지가 필요할 수 있습니다.
curl -fsSL https://bun.com/install | bashPLUGIN
Sol Advisor를 Codex에 설치해 주세요
아래 두 줄은 Codex 앱의 채팅창이 아니라 터미널에 붙여넣어 주세요. Windows PowerShell과 macOS·Linux 터미널에서 같은 Codex 명령을 사용합니다.
codex plugin marketplace add DannyMac180/sol-advisor --ref main
codex plugin add sol-advisor@sol-advisorcodex가 실행 정책에 막힐 때오류가 없는 경우에는 위 공식 명령을 사용합니다. 스크립트 실행 차단 오류가 있을 때만 아래 대체 명령을 사용해 주세요.
codex.cmd plugin marketplace add DannyMac180/sol-advisor --ref main
codex.cmd plugin add sol-advisor@sol-advisor설치 뒤 codex plugin list를 실행해 목록에 sol-advisor가 보이는지 확인해 주세요. Windows 실행 정책 오류가 있었던 환경에서는 codex.cmd plugin list를 사용합니다.
설치 뒤 Codex 앱을 완전히 종료했다가 다시 실행해 주세요. 새 작업만 여는 것으로는 Bun PATH와 새 플러그인 도구가 반영되지 않을 수 있습니다.
Luna만 사용하신다면 필요하지 않습니다. 이 스크립트는 Native 호환 경로용이며 sh와 jq가 필요하므로 Windows PowerShell 명령으로 그대로 실행할 수 없습니다.
FIRST USE
새 작업에서 첫 설정을 완료해 주세요
지원되는 호스트에서 플러그인을 설치한 뒤 Codex 데스크톱 앱의 새 작업을 열어 주세요. Windows 공식 v0.5.0에서는 이 단계가 차단됩니다. 검증되지 않은 로컬 패치를 일반 설치 가이드로 사용하지 마세요.
Use $sol-advisor:setup in this parent chat for Codex project scope.
Enable the separate Luna / Max app-task lane.
Save logical preferences only; do not render or install native adapters and do not run scripts/install-agents.sh.
Ask me for the exact model IDs shown in /model.- 클라이언트는 Codex를 선택합니다.
- 프로젝트 범위와 실제 작업 폴더를 지정합니다.
- 모델 선택기 또는
/model에 표시되는 routine·high·advisor의 정확한 모델 ID를 확인합니다. - 읽기 전용 요청과 자동 대체 금지 설정을 확인합니다.
- 전체 설정값을 검토한 뒤 저장을 승인합니다.
어댑터 미리보기와 정확한 설치 토큰을 검토해 역할 파일을 설치하고, 그 뒤 새 작업을 열거나 Codex를 다시 불러옵니다. Luna 전용 사용자는 이 단계를 건너뜁니다.
Native 기본 권장값은 Terra / High 구현과 Sol / High 검토입니다. Luna / Max는 이 설정을 자동으로 대체하는 값이 아니라, 다음 단계에서 별도로 승인하는 앱 작업 경로입니다.
SMOKE TEST
읽기 전용 호환성 점검을 먼저 실행해 주세요
설치 목록만으로는 충분하지 않습니다. 아래 점검이 정확한 표식을 반환해야 플러그인 설정, Luna · Max, 필수 앱 작업 도구가 실제로 연결된 것입니다.
Use $sol-advisor:orchestration.
Use the Luna task lane for this feature.
Run a read-only smoke task that returns exactly SMOKE_LUNA_MAX_OK.
If Luna / Max, setup, or any required app-task tool is unavailable, do not fall back; report BLOCKED.다른 모델이나 Native 경로로 대신 진행하지 마세요. 앱 완전 재시작, 설정 완료 여부, 필수 앱 작업 도구 여섯 개를 확인한 뒤 다시 점검합니다.
LUNA · MAX
현재 요청에 Luna 작업 승인을 붙여 주세요
실제로 맡길 작업과 아래 두 문장을 같은 요청에 넣어 주세요. 마지막 문장이 있어야 Luna / Max 작업 경로가 활성화됩니다.
작업: <여기에 원하는 작업을 적어 주세요>
Use $sol-advisor:orchestration to build and verify this feature. Keep final diff review and acceptance in this primary task.
Use the Luna task lane for this feature.요청할 때마다 다시 입력해야 합니다. 이전 요청의 승인은 다음 요청으로 이어지지 않습니다.
TROUBLESHOOTING
여기서 막히면 확인해 주세요
bun을 찾지 못합니다
설치 뒤 기존 터미널을 계속 사용하면 PATH가 반영되지 않을 수 있습니다. 터미널과 Codex를 완전히 다시 열고 확인해 주세요.
플러그인이 보이지 않습니다
codex plugin list로 목록을 확인한 뒤, 설치 명령 두 줄이 모두 성공했는지 다시 확인해 주세요.
Luna 작업이 만들어지지 않습니다
현재 요청에 승인 문장이 있는지, 첫 설정이 끝났는지, Codex 앱에서 Luna·Max와 필수 앱 작업 도구 여섯 개를 모두 사용할 수 있는지 확인해 주세요.
Windows에서 설정 또는 Luna 도구가 막힙니다
설정 실패는 공식 v0.5.0의 이슈 #20과 일치할 수 있습니다. 설정이 통과해도 wait_threads 등 필수 앱 작업 도구 여섯 개가 모두 있어야 Luna 경로를 사용할 수 있습니다. Windows ACL을 임의로 변경하지 말고 maintainer가 확정한 수정본과 호스트 지원을 기다려 주세요.