Unity 공식 Codex·Claude Code 플러그인 설치와 활용 가이드

9월 23, 2026

Unity 프로젝트에 AI 코딩 에이전트를 연결할 때 가장 곤란한 문제는 코드가 전혀 나오지 않는 것이 아니라, 예전 Unity 관습과 현재 API가 섞인 그럴듯한 코드가 나오는 것입니다. Unity는 이 문제를 줄이기 위해 Claude Code와 Codex용 공식 플러그인을 공개했습니다. 일반 튜토리얼을 넓게 참조하게 두는 대신, Unity 기능 담당 팀이 작성한 스킬을 에이전트가 필요할 때 불러오게 하는 방식입니다.

이 글은 Unity 6 이상 프로젝트를 기준으로 설치 위치, 정상 설치 확인, Codex와 Claude Code의 차이, 실제 요청을 작성하는 법, 보안과 실패 복구 순서를 정리합니다. 직접 프로젝트를 실행한 후기가 아니라 2026년 9월 23일 확인한 Unity 공식 문서와 공개 자료를 바탕으로 설명합니다.

먼저 결론
Unity 공식 플러그인은 Asset Store 패키지가 아니라 코딩 에이전트에 설치하는 스킬 묶음입니다. Unity 6.0 이상이 필요하며, Codex판은 31개 스킬과 Unity CLI 중심이고 공식 안내상 MCP 서버가 아닙니다. Claude Code판은 29개 스킬과 Unity CLI를 제공하며 라이브 에디터 작업 흐름까지 안내합니다. 어느 쪽이든 변경 전 브랜치와 테스트 기준은 사용자가 준비해야 합니다.

무엇이 달라졌나: 모델 지식보다 작업 지침을 앞에 둔다

일반 코딩 에이전트는 인터넷에 축적된 여러 세대의 Unity 자료를 함께 학습했기 때문에, 이미 바뀐 렌더링 방식이나 오래된 UI 선택을 현재 프로젝트에 제안할 수 있습니다. 공식 플러그인은 이를 새로운 모델로 해결하지 않습니다. 대신 UI Toolkit, uGUI, 2D 타일맵, URP, Shader Graph, 오디오, 물리, 멀티플레이, 인앱결제, 현지화처럼 반복되는 작업마다 Unity 엔지니어가 정리한 지침을 제공합니다.

사용자가 “설정 화면을 만들어 줘”라고 요청하면 에이전트는 관련 UI 스킬을 불러오고, 프로젝트가 사용하는 UI 체계를 먼저 구분하도록 안내받습니다. 결과가 이상할 때는 해당 스킬의 references/ 자료를 읽고 다시 시도하라고 지시할 수도 있습니다. 즉 플러그인의 핵심은 에이전트가 모든 것을 더 잘 안다고 가정하는 것이 아니라, 필요한 순간에 현재 Unity 방식의 참고서를 펼치게 하는 것입니다.

개발 요청이 Unity 공식 스킬, CLI와 프로젝트 검증 단계로 이어지는 흐름 — 요청을 바로 코드로 넘기지 않고 공식 스킬, 실행 도구, 테스트·로그 검증으로 나누는 흐름

Codex와 Claude Code, 같은 플러그인처럼 보여도 범위가 다르다

항목	Codex	Claude Code
공개 시점	2026년 9월 16일	2026년 9월 9일
초기 스킬 수	31개	29개
설치 위치	Codex CLI 또는 플러그인 디렉터리	Claude Code 세션·CLI 또는 Claude 데스크톱
에디터 연결	공식 포럼 안내상 스킬 패키지이며 MCP 서버가 아님	Unity CLI 스킬로 라이브 에디터 작업 흐름 지원
공통 조건	Unity 6.0 이상, 프로젝트별 검토와 검증 필요

두 버전을 스킬 숫자만으로 비교하면 안 됩니다. Codex에는 BIRP에서 URP로 옮기는 지침처럼 추가된 작업이 있고, Claude Code는 설치 범위를 사용자·프로젝트·로컬 단위로 고를 수 있습니다. 현재 사용하는 에이전트와 팀의 공유 방식, 라이브 에디터 조작 필요 여부가 선택 기준입니다.

시작 전 준비사항

Unity 버전 확인: 플러그인은 Unity 6.0 이상을 전제로 합니다. 오래된 LTS 프로젝트라면 플러그인 설치보다 업그레이드 계획과 패키지 호환성 점검이 먼저입니다.
변경 격리: 새 브랜치나 복제 프로젝트를 만들고, Library 같은 생성 폴더가 아니라 실제 추적 대상 파일의 변경을 확인할 수 있게 준비합니다.
에이전트 업데이트: Codex의 plugin 명령이나 Claude Code의 /plugin 명령이 제공되는 버전인지 확인합니다.
완료 기준 작성: 컴파일 성공만 보지 말고, 플레이 모드 동작, 콘솔 오류, 씬·프리팹 변경, 빌드 대상, 성능과 권한을 무엇으로 확인할지 미리 정합니다.
비밀정보 정리: 결제 키, 서명 파일, 서비스 계정, 광고·분석 토큰이 프로젝트 안에 있다면 에이전트가 읽어도 되는 경로와 제외할 경로를 구분합니다.

Codex에 설치하고 확인하는 순서

터미널에서 마켓플레이스를 추가한 뒤 플러그인을 설치합니다.

codex plugin marketplace add Unity-Technologies/unity-agent-plugin
codex plugin add unity@unity-agent-plugin

설치 후에는 기존 세션을 계속 쓰지 말고 새 Codex 세션을 시작합니다. /unity:를 입력했을 때 스킬 목록이 나타나는지 확인하고, 터미널에서는 다음 명령으로 unity가 설치·활성 상태인지 확인합니다.

codex plugin list

업데이트가 필요하면 codex plugin marketplace upgrade unity-agent-plugin, 제거하려면 codex plugin remove unity@unity-agent-plugin을 사용합니다. 플러그인을 설치했다고 Unity 프로젝트가 자동으로 안전해지는 것은 아닙니다. Codex판은 공식 포럼 설명상 MCP 서버가 아니므로, 실행 중인 에디터를 직접 제어한다고 가정하지 말고 파일·CLI 작업과 실제 에디터 확인을 구분해야 합니다.

Unity 공식 문서의 Codex 플러그인 설치와 확인 명령 — Unity 공식 문서의 Codex 설치·검증 명령. 출처: Unity Docs, 2026년 9월 23일 확인

Claude Code에 설치할 때는 범위를 먼저 고른다

Claude Code 세션 안에서는 다음 두 줄을 슬래시 명령으로 입력합니다.

/plugin marketplace add Unity-Technologies/unity-agent-plugin
/plugin install unity@unity-agent-plugin

여러 Unity 프로젝트에서 혼자 사용할 때는 사용자 범위, 저장소의 팀 표준으로 공유할 때는 프로젝트 범위, 현재 저장소에서 자신만 시험할 때는 로컬 범위가 적합합니다. 터미널에서 현재 저장소에만 설치하려면 다음처럼 지정할 수 있습니다.

claude plugin install unity@unity-agent-plugin --scope local

/unity:로 스킬 목록을, /plugin으로 활성 상태를 확인합니다. 자동 업데이트가 꺼진 마켓플레이스라면 /plugin marketplace update unity-agent-plugin으로 새 버전을 불러옵니다. 설치 후 스킬이 보이지 않을 때는 버전을 확인하고 터미널을 재시작한 뒤, 공식 문제 해결 순서에 따라 플러그인 캐시를 비우고 재설치합니다.

에이전트에게 맡기기 좋은 세 가지 예시

1. 새 설정 화면: UI 체계를 명시한다

“설정 화면을 만들어 줘”만 입력하면 UI Toolkit과 uGUI 중 무엇을 써야 하는지부터 흔들릴 수 있습니다. 새 프로젝트라면 다음처럼 프레임워크와 산출물, 중단 지점을 함께 적습니다.

Unity 6 프로젝트에 UI Toolkit 기반 설정 화면을 추가해 줘.
오디오 음량과 자막 크기만 포함하고, 기존 씬 구조를 먼저 읽어.
관련 Unity 스킬의 references를 확인한 뒤 변경 계획을 보여 줘.
UXML·USS·C# 변경 파일을 나열하고, 플레이 모드 검증 전에는 멈춰.

검토할 것은 화면이 보이는지뿐 아니라 UIDocument와 PanelSettings 연결, 값 저장 위치, 키보드·게임패드 이동, 기존 UI 체계와의 충돌입니다.

2. 한중일 글꼴 문제: 증상과 대상 플랫폼을 함께 준다

TextMeshPro에서 한글이나 중국어가 네모로 보인다면 “글꼴을 고쳐 줘”보다 사용 중인 폰트 에셋, 대상 언어, 메모리 제약, 동적 폴백 허용 여부를 적어야 합니다. /optimize-text-mesh-pro 스킬을 명시하고 현재 에셋을 먼저 조사하게 한 뒤, 폴백 아틀라스와 패딩·샘플링 설정을 제안하도록 요청할 수 있습니다. 결과는 실제 문자열 표본, 빌드 플랫폼, 메모리 프로파일로 확인해야 합니다.

3. BIRP에서 URP 이동: 한 번에 바꾸지 않는다

Codex판의 마이그레이션 지침은 재질·셰이더, 핑크 재질, 2D URP, 조명, 라이트맵, 반사 프로브 같은 확인 항목을 제공합니다. 그러나 큰 프로젝트를 한 번에 변환하라고 맡기면 원인 추적이 어려워집니다. 패키지와 렌더러 자산 준비, 대표 씬 한 개 변환, 커스텀 셰이더 분류, 시각 비교, 나머지 씬 확대 순서로 나누고 각 단계에서 커밋을 남기는 편이 안전합니다.

요청문은 ‘작업·제약·검증·중단점’ 네 부분으로 쓴다

작업: 무엇을 만들거나 고칠지 한 문장으로 지정합니다.
제약: Unity 버전, UI 체계, 렌더 파이프라인, 대상 플랫폼, 수정 금지 폴더를 적습니다.
검증: 컴파일, 테스트, 콘솔 로그, 씬 비교, 빌드 결과 중 필요한 것을 지정합니다.
중단점: 패키지 추가, 대량 파일 변경, 결제·광고 설정, 프로젝트 업그레이드 전에는 승인을 기다리게 합니다.

스킬이 자동으로 선택되지 않으면 이름을 직접 지정합니다. 결과가 현재 Unity 방식과 맞지 않아 보이면 “해당 스킬의 references/ 파일을 읽고 근거를 다시 확인하라”고 요청하는 것이 공식 권장 방식입니다. 자동화 파이프라인에서는 에이전트의 추가 질문이 작업을 멈출 수 있으므로, 필요한 결정과 기본값을 처음부터 더 자세히 제공해야 합니다.

권한·비용·보안에서 놓치기 쉬운 부분

Unity는 이 플러그인을 자사 엔지니어가 유지하고 보안 검토를 거친 공식 통합으로 설명하지만, Codex와 Claude Code 자체는 제3자 제품입니다. 플러그인 설치가 각 에이전트의 이용약관, 구독, API 비용, 데이터 처리 조건을 대신하지 않습니다. 공식 문서에 별도의 무료 사용 보장이 명시된 것은 아니므로 현재 사용하는 에이전트 요금제와 Unity 라이선스를 각각 확인해야 합니다.

특히 인앱결제, LevelPlay 광고, 멀티플레이와 라이브 서비스 작업은 코드만의 문제가 아닙니다. 스토어 상품 ID, 영수증 검증, 개인정보 동의, ATT, 서버 권한과 운영 환경 분리가 함께 필요합니다. 에이전트에는 최소 권한만 주고, 실제 결제 상품 생성이나 배포 키 변경처럼 되돌리기 어려운 작업은 관리 콘솔에서 사람이 확인하는 편이 안전합니다.

자주 막히는 상황과 해결 순서

명령을 인식하지 못함: Codex 또는 Claude Code 버전을 확인하고 업데이트한 뒤 새 세션을 엽니다.
설치했지만 스킬이 없음: /unity:와 플러그인 목록을 각각 확인합니다. Claude Code는 필요하면 캐시 삭제 후 재설치합니다.
엉뚱한 UI 방식 선택: UI Toolkit 또는 uGUI를 요청 첫 문장에 명시합니다.
답변이 오래된 방식처럼 보임: 관련 스킬과 references/를 직접 읽고 다시 계획하게 합니다.
자동화가 질문에서 멈춤: 대상 플랫폼, 기본값, 수정 범위, 승인 없이 진행 가능한 단계를 요청문에 포함합니다.
간단한 uGUI 작업에서 차이가 작음: 공식 문서도 단순 uGUI 작업은 수동 작업 대비 이점이 적을 수 있다고 안내합니다. 복잡한 렌더링, 현지화, 결제, 마이그레이션처럼 최신 지식과 점검표가 중요한 작업부터 적용합니다.

누구에게 유용하고, 언제 기다려야 하나

Unity 6 프로젝트를 운영하면서 에이전트가 오래된 API나 서로 다른 UI 체계를 섞는 문제를 자주 겪는 팀이라면 가치가 큽니다. 특히 신규 프로젝트 설정, URP 검토, 다국어 글꼴, 패키지 관리처럼 반복 작업과 확인 항목이 많은 분야에 적합합니다. 반대로 Unity 6 이전 프로젝트, 엄격한 폐쇄망, 제3자 에이전트에 프로젝트 파일을 제공할 수 없는 조직, 이미 자체 지침과 검증 파이프라인이 잘 구축된 팀은 도입 효과가 제한될 수 있습니다.

이전의 Diagram Design 설치·활용 가이드가 에이전트에 시각화 능력을 추가하는 방법을 다뤘다면, 이번 Unity 플러그인은 도메인별 공식 작업 지침을 주입하는 사례입니다. 둘 다 설치 자체보다 “어떤 결과를 만들고 무엇으로 검증할지”를 먼저 정해야 한다는 점은 같습니다.

공식 자료

자료 확인일: 2026년 9월 23일. 플러그인과 베타 문서는 변경될 수 있으므로 설치 전 최신 명령과 지원 범위를 다시 확인하세요.

다른 언어로 읽기
Read in English

이 블로그 검색

스택핀치