> 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 Assistant 활성화** 스위치, **대신 이 항목을 API 키로 청구** 옵션, **연결** 코딩 CLI 목록, 그리고 **AI 어시스턴트 MCP 서버 노출** 설정이 있습니다.

어시스턴트가 켜져 있으면 **AI Assistant** 버튼(반짝이 아이콘)이 편집기 상단 바의 **Code** 버튼 왼쪽에 표시됩니다. 이를 클릭하면 씬 옆에 채팅 패널이 열립니다.

![왼쪽에는 씬 이름이 있고 오른쪽에는 반짝이 AI Assistant 아이콘, 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 Assistant 패널: 상단에 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    | 설치                                   | 로그인                  |
| ------ | ------------------------------------ | -------------------- |
| Claude | `npm i -g @anthropic-ai/claude-code` | `claude`             |
| Codex  | `npm i -g @openai/codex`             | `codex login`        |
| Cursor | `npm i -g cursor-agent`              | `cursor-agent login` |
| Gemini | `npm i -g @google/gemini-cli`        | `gemini`             |

이는 Creator Hub 내부에서 할 수 있습니다. 설정에서 **AI** 탭의 **연결**에서 각 감지된 CLI는 상태와 **로그인** 링크가 표시되며, 이를 클릭하면 로그인 절차가 실행되고 브라우저가 열립니다. 초록색 점과 **연결됨** 은 준비되었음을 의미합니다. **로그아웃** 는 연결을 해제합니다.

직접 하고 싶다면, CLI 아래의 **터미널을 통해** 섹션을 여세요. 정확한 **설치** 과 **로그인** 명령을 복사할 수 있습니다.

{% hint style="warning" %}
**📔 참고**: Gemini에는 **로그인** 버튼이 없습니다. 로그인은 대화형 세션으로만 실행되므로, 터미널에서 `gemini` 를 실행해 로그인하거나, `GEMINI_API_KEY` 를 환경 변수로 설정하세요.
{% endhint %}

동일한 설정 카드가, 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 Assistant 패널: 응답에는 실행한 도구들이 나열되고 결과가 설명되며, 아래에 Undo AI changes 버튼이 표시됩니다.](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 Assistant 패널이 도킹되어 있고, 엔티티 트리에는 이름이 바뀐 Stage 엔티티가 보이며, 어시스턴트 응답의 끝에는 Undo AI changes가 있는 전체 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개의 파일을 첨부할 수 있으며, 텍스트 없이도 첨부 파일만 보낼 수 있습니다.

Claude CLI가 너무 오래되었다면 패널에 경고가 표시됩니다. 터미널에서 `claude update` 를 실행해 수정하세요.

## 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:<PORT>/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}
```

Claude Code의 경우, 대신 씬 폴더의 터미널에서 추가할 수 있습니다:

```bash
claude mcp add --transport http --scope local creator-hub http://127.0.0.1:<PORT>/mcp \
  --header "Authorization: Bearer <TOKEN>"
```

{% hint style="warning" %}
**📔 참고**: 포트와 토큰은 Creator Hub가 시작할 때마다 새로 생성됩니다. 도구에 갑자기 `401` 오류
{% endhint %}

## 관련 페이지

* [AI와 함께하는 바이브 코딩](/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=<question>&goal=<user_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.