> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/scene-editor/extend-with-code/ai-assistant.md). # AI 어시스턴트 Creator Hub 안에서 AI 어시스턴트와 채팅하며 씬을 구축하고 변경하세요. Creator Hub는 열린 장면을 보고 사용자를 대신해 편집하는 AI 어시스턴트를 실행할 수 있습니다. 항목 배치, 동작 연결, 스크립트 작성, 또는 미리 보기 실행 후 결과 확인을 요청하세요. {% hint style="warning" %} **📔 참고**: 어시스턴트는 설치하고 로그인한 코딩 CLI를 실행하며, 터미널에서와 같은 수준으로 기기에 대한 전체 접근 권한을 가집니다. 요청한 작업을 신뢰할 수 있을 때만 활성화하세요. {% endhint %} ## 설정 위치 어시스턴트는 기본적으로 켜져 있습니다. 설정에는 별도의 탭이 있습니다: 1. 왼쪽 상단의 Creator Hub 로고를 클릭하고 **설정**. 2. 으로 이동하세요. **AI** 탭. 그 탭에는 다음 항목이 있습니다: **AI 어시스턴트 활성화** 토글, **대신 이 비용을 API 키로 청구** 옵션, **연결** 할 코딩 CLI 목록, 그리고 **AI 어시스턴트 MCP 서버 노출** 설정. 어시스턴트가 켜져 있으면 **AI 어시스턴트** 버튼(반짝이 아이콘)이 에디터 상단 바에서 **Code** 버튼 왼쪽에 나타납니다. 클릭하면 장면 옆에 채팅 패널이 열립니다. ![왼쪽에 장면 이름이 있고, 오른쪽에 반짝이 AI 어시스턴트 아이콘, Code, Preview, Publish 버튼이 있는 에디터 상단 바.](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-7db0716b3d034ba09084bf784488209d7d77caad%2Feditor-top-bar.png?alt=media\&token=e00db1c0-c8c4-42c2-bd13-d5c2ab00f63e) ![처음 열었을 때의 AI 어시스턴트 패널: 상단에 New chat 드롭다운과 Claude라고 표시된 CLI 드롭다운, 환영 메시지, About AI usage 카드, 선택한 엔티티 이름이 표시된 Selection 칩, 하단의 Ask Assistant 입력창.](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-078c9e0dec3b2886d4216fad423c9fddd492bf0c%2Fai-assistant-panel.png?alt=media\&token=b4720826-136f-4743-9a1f-db5663cbd47f) ## 코딩 CLI 연결 어시스턴트는 자체 API 키를 사용하지 않습니다. 설치하고 로그인한 코딩 CLI를 실행하므로, 작업 비용은 그 도구의 구독에 청구됩니다. 네 가지가 지원됩니다. 대부분은 터미널에서 설정합니다. 설정 화면에는 자신의 운영 체제에 맞는 설치 명령, 로그인 명령, 그리고 공급업체의 설치 가이드 링크가 표시되므로, 각 항목을 차례로 복사할 수 있습니다. | CLI | macOS 및 Linux에 설치 | Windows에 설치 | 로그인 | | ------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------- | | Claude | `curl -fsSL https://claude.ai/install.sh \| bash` | `winget install Anthropic.ClaudeCode` | `claude auth login` | | Codex | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` | `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"` | `codex login` | | Cursor | `curl https://cursor.com/install -fsS \| bash` | `powershell -ExecutionPolicy ByPass -c "irm 'https://cursor.com/install?win32=true' \| iex"` | `cursor-agent login` | | Gemini | `npm install -g @google/gemini-cli` | `npm install -g @google/gemini-cli` | 실행 `gemini` | Codex는 예외입니다. 또한 **Codex로 로그인** 버튼도 제공하며, 이를 누르면 로그인 절차가 실행되고 브라우저가 열립니다. Claude, Cursor, Gemini는 터미널에서만 설치하고 로그인할 수 있습니다. CLI를 설치한 후 **다시 확인** 을 설정 화면에서 클릭하세요. Creator Hub를 재시작할 필요 없이 새 설치를 바로 인식합니다. {% hint style="warning" %} **📔 참고**: Claude Desktop은 Claude Code와 같은 것이 아닙니다. 어시스턴트에는 터미널 도구인 Claude Code가 필요하며, 데스크톱 앱에 로그인해도 자동으로 로그인되지는 않습니다. Creator Hub가 Claude Code 없이 Claude Desktop을 찾으면 그렇게 알리고 설치 명령을 보여줍니다. Gemini CLI에는 유료 Gemini API 키 또는 Gemini Code Assist Standard나 Enterprise 라이선스가 필요합니다. {% endhint %} 같은 설정 화면은 CLI가 연결되지 않은 상태로 처음 열었을 때 채팅 패널 자체에도 나타나며, 설정의 **AI** 탭에서 **연결**. CLI의 저장된 로그인 세션이 만료되면 상태가 **로그인 필요** 로 바뀌고, 패널에 로그아웃 및 로그인 명령이 하나씩 표시됩니다. 순서대로 실행한 다음 메시지를 다시 보내세요. {% hint style="info" %} **💡 팁**: 로그인된 CLI가 둘 이상 있으면, 채팅 패널의 드롭다운에서 전환할 수 있습니다. {% endhint %} ### 대신 API 키로 청구 CLI 구독 대신 토큰 단위로 비용을 지불하고 싶다면, 설정의 **대신 이 비용을 API 키로 청구** 에서 **AI** 탭을 켜세요. 그러면 환경 변수에서 제공자의 API 키를 읽습니다: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `CURSOR_API_KEY` 또는 `GEMINI_API_KEY`. 이 기능은 기본적으로 꺼져 있습니다. ## 할 수 있는 작업 어시스턴트는 열려 있는 장면에서 작업합니다. 다음을 할 수 있습니다: * **장면 편집**: 엔티티 생성 및 삭제, 컴포넌트 변경, [스마트 아이템](/creator/content-creator-ko/scene-editor/interactivity/smart-items.md) 배치, [스크립트](/creator/content-creator-ko/scene-editor/extend-with-code/script-component.md) 연결, 그리고 `scene.json`. * **코드 작성** 장면 파일 내에서. * **미리 보기 실행** 및 제어: 스크린샷 찍기, 돌아다니기, 클릭하기, 로그 읽기, 성능 확인하기. * **선택 항목 읽기**, 엔티티를 선택한 뒤 "이것을 더 크게 만들어 줘"라고 말할 수 있습니다. 변경 사항은 발생하는 즉시 저장되며 일반 실행 취소 기록에 들어갑니다. 한 번에 전체 대화를 되돌리려면 **AI 변경 사항 실행 취소** 를 어시스턴트의 답변에서 사용하세요. ![엔티티 이름 변경과 Mesh Renderer 추가 요청 후 에디터 오른쪽에 도킹된 AI 어시스턴트 패널: 답변에 실행한 도구, 결과 설명, 아래의 AI 변경 사항 실행 취소 버튼이 표시됨.](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-06054ee50124b89ef317fcecd4f797d7c71896a2%2Fai-assistant-reply.png?alt=media\&token=a107e7b4-4862-4630-9591-1bca87e32b17) 어시스턴트가 작업하는 동안, 변경 사항이 엔티티 트리와 캔버스에 실시간으로 표시됩니다. ![오른쪽에 AI 어시스턴트 패널이 도킹되어 있고, 엔티티 트리에는 이름이 바뀐 Stage 엔티티가 보이며, 어시스턴트의 답변 끝에 AI 변경 사항 실행 취소가 있는 전체 Scene Editor.](https://3980763956-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-5867011b5b777986587d4cce33d0554e24101b69%2Fai-assistant-docked.png?alt=media\&token=2caa43b5-acc6-4e1b-a90e-85ccddd5bc0f) ## 채팅 사용하기 * **새 채팅** 새 대화를 시작합니다. * **채팅 기록** 이전에 진행한 대화와 실행된 지 얼마나 지났는지 표시합니다. 대화는 프로젝트별로 저장되므로, 장면을 다시 열면 채팅도 함께 돌아옵니다. * **별도 창에서 열기** 어시스턴트를 별도의 창으로 분리하며, 두 번째 모니터에서 유용합니다. **에디터에 다시 도킹** 합니다. * 패널은 더 넓게 또는 더 좁게 드래그할 수 있습니다. 하나의 **AI 사용량 정보** 카드는 어시스턴트가 연결된 계정의 토큰을 사용한다는 점을 알려줍니다. 해당 계정의 사용량을 주시하세요. ### 프롬프트에 파일 첨부 가끔은 어시스턴트에게 무언가를 설명하는 것보다 보여 주는 편이 더 쉽습니다. 다음 세 가지 방법으로 어떤 메시지에도 파일을 첨부할 수 있습니다: * 메시지 상자 왼쪽의 종이클립 아이콘을 클릭하고 **파일 첨부**라고 표시된 후 하나 이상의 파일을 선택하세요. * 파일 탐색기에서 파일을 메시지 상자로 끌어다 놓으세요. 끌어오는 동안 **파일을 놓아 첨부** 힌트가 나타납니다. * 예를 들어 방금 찍은 스크린샷처럼 클립보드에서 이미지를 바로 붙여넣을 수 있습니다. 첨부된 각 파일은 메시지 상자 위에 칩 형태로 표시되며, 종류를 나타내는 아이콘이 있습니다: 이미지, 3D 모델(`.glb`, `.gltf`), 오디오(`.mp3`, `.wav`, `.ogg`, `.m4a`, `.flac`), 또는 그 밖의 일반 파일. 보내기 전에 칩의 **제거** X를 클릭해 빼낼 수 있습니다. 한 메시지에 최대 8개 파일을 첨부할 수 있으며, 텍스트 없이도 첨부 파일만 보낼 수 있습니다. 드래그하거나 디스크에서 선택한 파일은 실제 경로로 어시스턴트에 전달되므로 복사본이 만들어지지 않고 크기 제한도 없습니다. 어시스턴트는 이미지를 직접 볼 수 있으며, 장면 코드를 작성할 때 모델이나 오디오 파일을 경로로 참조할 수 있습니다. 붙여넣은 이미지는 디스크에 파일이 없으므로 Creator Hub가 먼저 임시 파일로 저장합니다. 이 파일은 각각 8MB로 제한됩니다. Claude CLI가 너무 오래된 경우, 패널에 경고가 표시됩니다. 문제를 해결하려면 터미널에서 `claude update` 를 실행하세요. ### 프롬프트에서 에셋 가리키기 파일을 첨부하면 그 내용이 전송됩니다. 에셋을 언급하는 것은 더 가볍습니다. 프로젝트의 어떤 에셋을 뜻하는지 어시스턴트에 알려 주기만 하므로, 경로를 직접 입력하는 대신 "이것을 사용해"라고 말할 수 있습니다. 어시스턴트가 열린 상태에서 **로컬 에셋** 탭의 아무 에셋이나 더블클릭하세요. 메시지 상자 위에 칩으로 표시되며 **에셋: *****파일명*** 또는 **기본 제공 애니메이션: *****이름*** 중 하나로 표시됩니다. * 원하는 만큼 많은 에셋을 언급할 수 있습니다. 각 항목마다 별도의 칩과 별도의 **제거** X * 가 생깁니다. 언급한 항목은 **선택** 칩 옆에 표시되므로, 장면의 엔티티와 에셋을 동시에 가리킬 수 있습니다: "이 애니메이션을 저 NPC에 적용해". * 언급은 다음 메시지에만 적용됩니다. 메시지를 보내면 지워집니다. {% hint style="info" %} **💡 팁**: Scene 루트를 선택하는 것은 아무것도 선택하지 않은 것으로 간주되므로 어시스턴트에게 절대 전송되지 않습니다. 어시스턴트가 특정 엔티티에 작업하길 원할 때는 실제 엔티티를 선택하세요. {% endhint %} ## Decentraland 스킬은 자동으로 설치됩니다 어시스턴트가 실행되면 Creator Hub가 공식 [Decentraland SDK Skills](/creator/content-creator-ko/sdk7/getting-started/vibe-coding.md) 를 다운로드해 프로젝트에 연결하므로, 어시스턴트는 추측하지 않고 검증된 SDK7 패턴을 따릅니다. 연결 위치는 `.claude/skills` 및 `.agents/skills` 이며, 둘 다 프로젝트 폴더 안에 있는 `.gitignore` 에 추가되므로 저장소에 포함되지 않습니다. ## 어시스턴트가 장면 폴더에 남기는 파일 어시스턴트는 로컬 MCP 서버를 통해 열려 있는 장면을 읽고 편집할 수 있습니다. 각 CLI는 그 서버를 서로 다르게 인식하므로, 사용하는 도구에 따라 프로젝트에 새 파일이 생길 수 있습니다: | CLI | 장면 폴더에 나타나는 항목 | | ------ | -------------------------------------------------------- | | Cursor | `.cursor/mcp.json`, 그리고 `.cursor/rules/creator-hub.mdc` | | Gemini | `.gemini/settings.json` | | Claude | 아무것도 없습니다. 구성은 프로젝트 외부의 임시 파일에 들어갑니다. | | Codex | 아무것도 없습니다. 구성은 명령줄로 전달됩니다. | 이미 이러한 구성 파일 중 하나가 있다면, Creator Hub는 자신의 서버를 덮어쓰지 않고 해당 항목을 병합합니다. {% hint style="warning" %} **📔 참고**: `.cursor/mcp.json` 는 액세스 토큰 자체가 들어 있는 유일한 파일입니다. Cursor의 구성 형식은 환경에서 토큰을 읽을 방법이 없기 때문입니다. Creator Hub는 작성하기 전에 토큰을 `.gitignore` 에 추가하므로, 그 줄을 커밋하거나 삭제하지 마세요. Gemini 파일은 대신 `$CREATOR_HUB_MCP_TOKEN` 환경 변수를 통해 토큰을 참조하므로 비밀 정보가 없고 무시되지도 않습니다. {% endhint %} ## 대신 자체 AI 도구 사용 이미 Claude Code, Cursor, Codex 또는 MCP를 지원하는 다른 도구를 사용 중이라면, 내장 패널 대신 열려 있는 장면을 가리키도록 할 수 있습니다. MCP(Model Context Protocol)는 AI 도구가 다른 프로그램을 호출할 수 있도록 하는 표준 방식입니다. 1. Creator Hub 로고에서 기본 메뉴를 열고 **설정**, 그리고 **AI** 탭에서 확장 **AI 어시스턴트 MCP 서버 노출**. 2. 클릭 **구성 복사**. 3. 그것을 도구의 MCP 구성에 붙여넣으세요. 복사된 구성은 실제 포트와 토큰이 채워진 상태로 다음과 같습니다: ```json { "mcpServers": { "creator-hub": { "type": "http", "url": "http://127.0.0.1:/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Claude Code의 경우, 대신 장면 폴더의 터미널에서 추가할 수 있습니다: ```bash claude mcp add --transport http --scope local creator-hub http://127.0.0.1:/mcp \ --header "Authorization: Bearer " ``` {% hint style="warning" %} **📔 참고**: 포트와 토큰은 Creator Hub가 시작될 때마다 새로 생성됩니다. 도구에서 갑자기 `401` 오류가 나면, 구성을 다시 복사하세요. 서버는 자신의 기기에서만 수신 대기하며, 항상 열려 있는 장면에 대해서만 작동합니다. {% endhint %} ## 관련 페이지 * [AI와 함께하는 Vibe Coding](/creator/content-creator-ko/sdk7/getting-started/vibe-coding.md): SDK Skills와 프롬프트 작성법에 대한 전체 가이드입니다. * [코드와 결합](/creator/content-creator-ko/scene-editor/extend-with-code/overview.md): 코드 편집기에서 장면을 엽니다. * [Script Component 사용하기](/creator/content-creator-ko/scene-editor/extend-with-code/script-component.md): 파일에서 엔티티에 동작을 추가합니다. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.decentraland.org/creator/content-creator-ko/scene-editor/extend-with-code/ai-assistant.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.