> 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-pt/scene-editor/expandir-com-codigo/ai-assistant.md).

# Assistente de IA

Crie e altere a sua cena ao conversar com um assistente de IA dentro do Creator Hub.

O Creator Hub pode executar um assistente de IA que vê a cena aberta e a edita por si. Peça-lhe para colocar itens, configurar comportamentos, escrever scripts ou executar a pré-visualização e verificar o resultado.

{% hint style="warning" %}
**📔 Nota**: o assistente executa uma CLI de programação que instala e na qual inicia sessão, com acesso total à sua máquina — o mesmo alcance que tem no terminal. Ative-o apenas se confiar no que lhe pede para fazer.
{% endhint %}

## Onde estão as definições

O assistente está ativado por predefinição. As respetivas definições têm um separador próprio:

1. Clique no logótipo do Creator Hub no canto superior esquerdo e selecione **Definições**.
2. Aceda ao separador **IA** .

Esse separador contém o interruptor **Ativar o assistente de IA** , a opção **Faturar antes a uma chave de API** , a lista **Ligar** de CLIs de programação e o interruptor **Permitir que outras aplicações de IA editem as suas cenas** . Consulte [Utilizar outra ferramenta de IA](#use-your-own-ai-tool-instead).

Quando o assistente está ativado, aparece um botão **Assistente de IA** (o ícone de brilhos) na barra superior do editor, à esquerda do botão **Código** . Clique nele para abrir o painel de chat junto à cena.

![A barra superior do editor, com o nome da cena à esquerda e os botões do ícone de brilhos do assistente de IA, Código, Pré-visualizar e Publicar à direita.](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-5516232f864b551063cdf029cd723cc22197619b%2Feditor-top-bar.webp?alt=media)

![O painel do Assistente de IA quando é aberto pela primeira vez: um menu pendente Novo chat e um menu pendente de CLI com Claude selecionado, na parte superior; uma mensagem de boas-vindas; um cartão Sobre a utilização da IA; uma etiqueta Seleção com o nome da entidade selecionada; e o campo Perguntar ao assistente na parte inferior.](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-3e74b15f7db55896cba85385feecde0cb90f69ce%2Fai-assistant-panel.webp?alt=media)

## Ligar uma CLI de programação

O assistente não utiliza uma chave de API própria. Executa uma CLI de programação que instala e na qual inicia sessão, pelo que o trabalho é faturado à subscrição dessa ferramenta.

São suportadas quatro: Claude, Codex, Cursor e Gemini. Instale cada uma com o instalador do respetivo fornecedor, a partir de um terminal.

### Instalar uma CLI

Execute o comando correspondente ao seu sistema operativo:

| CLI    | macOS e Linux                                           | Windows                                                                                      |
| ------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Claude | `curl -fsSL https://claude.ai/install.sh \| bash`       | `winget install Anthropic.ClaudeCode`                                                        |
| Codex  | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` | `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"`   |
| Cursor | `curl https://cursor.com/install -fsS \| bash`          | `powershell -ExecutionPolicy ByPass -c "irm 'https://cursor.com/install?win32=true' \| iex"` |
| Gemini | `npm install -g @google/gemini-cli`                     | `npm install -g @google/gemini-cli`                                                          |

Não precisa de copiar estes comandos manualmente. O Creator Hub apresenta os comandos exatos para o seu sistema operativo em dois locais, juntamente com uma ligação para o guia de instalação do fornecedor:

* O cartão de configuração no painel de chat, que aparece na primeira vez que abre o painel sem nenhuma CLI ligada.
* As definições, no separador **IA** separador abaixo **Conectar**, na **Via Terminal** secção abaixo de cada CLI. Cada comando tem um botão **Copiar** .

Guias dos fornecedores:

* [Guia de instalação do Claude Code](https://code.claude.com/docs/en/terminal-guide)
* [Guia de instalação do Codex CLI](https://developers.openai.com/codex/cli)
* [Guia de instalação do Cursor CLI](https://cursor.com/docs/cli/installation)
* [Guia de instalação do Gemini CLI](https://www.geminicli.com/docs/get-started/installation)

Após a instalação, clique em **Verificar novamente** no cartão de configuração do painel de chat para que o Creator Hub detete o novo CLI, sem precisar de reiniciar a aplicação. O separador **IA** volta a verificar automaticamente sempre que o abre.

{% hint style="warning" %}
**📔 Nota**: Claude Desktop não é a mesma coisa que Claude Code. O assistente precisa do Claude Code, a ferramenta de terminal da Anthropic, e iniciar sessão na aplicação de ambiente de trabalho não inicia sessão nessa ferramenta. Se o Creator Hub encontrar o Claude Desktop, mas não o Claude Code, informa-o e mostra o comando de instalação.

O Gemini CLI requer uma chave da API Gemini paga ou uma licença Gemini Code Assist Standard ou Enterprise.
{% endhint %}

### Iniciar sessão

| CLI    | Iniciar sessão                        |
| ------ | ------------------------------------- |
| Claude | `claude auth login`                   |
| Codex  | `codex login`                         |
| Cursor | `cursor-agent login`                  |
| Gemini | execute `gemini` e siga as instruções |

Execute o comando de início de sessão num terminal. O processo é concluído no browser.

O Codex tem um atalho: se ainda não estiver instalado, o Creator Hub pode instalá-lo e iniciar sessão por si. Clique em **Iniciar sessão com o Codex** no cartão de configuração do painel de chat ou em **Iniciar sessão** junto ao Codex, em **Conectar** no separador **IA**  . O Creator Hub executa o início de sessão e abre o browser; em seguida, aparece um link para **Terminar sessão** no mesmo local. Se instalou o Codex por conta própria usando o comando acima, não há botão: inicie sessão num terminal, como nos outros casos.

Um ponto verde e o estado **Ligado** junto a um CLI indicam que está pronto a usar.

{% hint style="info" %}
**💡 Sugestão**: se tiver sessão iniciada em mais de um CLI, um menu pendente no painel de chat permite alternar entre eles.
{% endhint %}

### Quando um agente lhe pede para iniciar sessão novamente

Uma sessão iniciada e guardada pode expirar enquanto o CLI ainda parece estar ligado. Quando um CLI responde a uma mensagem com «not logged in», o Creator Hub apresenta o estado **É necessário iniciar sessão** com um ponto âmbar, em vez de encaminhar a linha de comandos em bruto para o chat.

O painel de chat e a opção **Via Terminal** secção sobre o **IA** o separador mostra os dois comandos a executar, um de cada vez, terminando no navegador:

| CLI    | Termine sessão e, em seguida, inicie sessão novamente         |
| ------ | ------------------------------------------------------------- |
| Claude | `claude auth logout`, depois `claude auth login`              |
| Codex  | `codex logout`, depois `codex login`                          |
| Cursor | `cursor-agent logout`, depois `cursor-agent login`            |
| Gemini | execute `gemini`, depois `/auth logout`, depois `/auth login` |

Se o Creator Hub instalou o Codex por si, use **Terminar sessão** e depois **Iniciar sessão** no separador **IA** em vez disso.

Envie novamente a sua mensagem depois de iniciar sessão. O agente permanece ativado durante todo o processo, por isso não precisa de o configurar de raiz.

### Cobrar antes a uma chave de API

Se preferir pagar por token em vez de usar uma subscrição da CLI, ative **Cobrar isto antes a uma chave de API** no **separador IA** das definições. O sistema lê a chave de API do seu fornecedor a partir do ambiente: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `CURSOR_API_KEY` ou `GEMINI_API_KEY`. Esta opção está desativada por predefinição.

Esta opção também permite contornar um início de sessão que não consegue concluir. Quando uma CLI está no estado **É necessário iniciar sessão** , o Creator Hub apresenta uma sugestão **Ou use uma chave de API** com o nome da variável correspondente.

## O que pode fazer

O assistente trabalha na cena que tem aberta. Pode:

* **Editar a cena**: criar e eliminar entidades, alterar componentes, colocar [smart items](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/smart-items.md), anexar [scripts](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/script-component.md)e ler e escrever `scene.json`.
* **Escreva código** nos ficheiros da sua cena.
* **Execute a pré-visualização** e controle-a: faça capturas de ecrã, caminhe, clique nos elementos, leia os registos e verifique o desempenho.
* **Leia a sua seleção**, para poder selecionar uma entidade e dizer «torne esta mais alta».

As alterações são guardadas à medida que são feitas e entram no histórico normal de anulação. Para reverter uma conversa inteira de uma só vez, use **Anular alterações da IA** na resposta do assistente.

![O painel AI Assistant, encaixado à direita do editor após um pedido para mudar o nome de uma entidade e adicionar um Mesh Renderer: a resposta lista as ferramentas utilizadas, descreve o resultado e apresenta um botão Anular alterações da IA por baixo.](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-4e0b285e70788ec073c3e07c3b5867a71086f2a6%2Fai-assistant-reply.webp?alt=media)

Enquanto o assistente trabalha, as alterações aparecem em tempo real na árvore de entidades e no canvas.

![O Scene Editor completo, com o painel AI Assistant encaixado à direita, a entidade Stage com o nome alterado visível na árvore de entidades e a resposta do assistente a terminar com Anular alterações da IA.](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-28b283daab3156dbe54a3fa2227903c628eefb0f%2Fai-assistant-docked.webp?alt=media)

## Trabalhar com a conversa

* **Nova conversa** inicia uma nova conversa.
* **Histórico de conversas** apresenta as conversas anteriores e há quanto tempo ocorreram. As conversas são guardadas por projeto, por isso, ao reabrir uma cena, as respetivas conversas voltam a aparecer.
* **Abrir numa janela separada** abre o assistente numa janela própria, o que é útil quando utiliza um segundo monitor. **Voltar a encaixar no editor** volta a encaixá-lo.
* Pode arrastar o painel para o tornar mais largo ou mais estreito.

Um **cartão Sobre a utilização da IA** lembra que o assistente consome tokens da sua conta associada. Acompanhe a utilização dessa conta.

O assistente processa uma mensagem de cada vez. Enquanto uma resposta está a ser gerada, um indicador **A pensar…** permanece visível até a interação terminar, incluindo durante chamadas demoradas a ferramentas. Enviar uma segunda mensagem não cancela a primeira: aguarde pela resposta ou prima **Parar** para terminar a interação.

Algumas respostas fazem-lhe uma pergunta antes de continuar. Se não responder durante demasiado tempo, a pergunta é encerrada com «This question is no longer active.» e pode voltar a perguntar.

### Anexar ficheiros a uma instrução

Por vezes, é mais fácil mostrar algo ao assistente do que descrevê-lo. Pode anexar ficheiros a qualquer mensagem de três formas:

* Clique no ícone de clipe à esquerda da caixa de mensagem, com o rótulo **Anexar ficheiros**, e escolha um ou mais ficheiros.
* Arraste ficheiros do explorador de ficheiros para a caixa de mensagem. Enquanto arrasta, aparece uma indicação **Largue os ficheiros para os anexar** .
* Cole uma imagem diretamente da área de transferência, por exemplo, uma captura de ecrã que acabou de fazer.

Cada ficheiro anexado aparece como uma etiqueta acima da caixa de mensagem, com um ícone que indica o tipo: imagem, modelo 3D (`.glb`, `.gltf`), áudio (`.mp3`, `.wav`, `.ogg`, `.m4a`, `.flac`), ou um ficheiro genérico para qualquer outro tipo. Clique no **Remover** cruz num chip para o remover antes de enviar. Pode anexar até 8 ficheiros a uma única mensagem e enviar anexos sem qualquer texto.

Os ficheiros que arrasta ou seleciona no disco são disponibilizados ao assistente através do respetivo caminho real, por isso nada é copiado e não existe limite de tamanho. O assistente consegue analisar imagens diretamente e pode referenciar um modelo ou ficheiro de áudio pelo caminho quando escreve código de cena. As imagens coladas não têm um ficheiro no disco, por isso o Creator Hub guarda-as primeiro num ficheiro temporário; estes ficheiros têm um limite de 8 MB cada.

Se a sua versão do Claude CLI for demasiado antiga, o painel apresenta um aviso. Execute `claude update` num terminal para corrigir o problema.

### Referencie um asset no seu pedido

Anexar um ficheiro envia o respetivo conteúdo. Referenciar um asset é mais simples: apenas indica ao assistente a que asset do seu projeto se refere, para poder dizer «use este» em vez de escrever um caminho.

Com o assistente aberto, faça duplo clique em qualquer asset no separador **Local Assets** . Surge como um chip acima da caixa de mensagem, com o texto **Asset:&#x20;*****nome do ficheiro***, ou **Animação integrada:&#x20;*****nome*** para uma das animações de avatar integradas.

* Pode referenciar quantos assets quiser. Cada um tem o seu próprio chip e a sua própria cruz para **Remover** .
* As referências aparecem junto ao chip **Selection** , para poder indicar uma entidade na sua cena e um asset ao mesmo tempo: «coloque esta animação nesse NPC».
* As referências aplicam-se apenas à mensagem seguinte. São limpas depois de a enviar.

{% hint style="info" %}
**💡 Dica**: Selecionar a raiz da Scene equivale a não selecionar nada, por isso nunca é enviada ao assistente. Selecione uma entidade real quando quiser que o assistente atue sobre ela.
{% endhint %}

## As skills da Decentraland são instaladas por si

Quando o assistente é executado, o Creator Hub transfere as [Decentraland SDK Skills](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md) oficiais e cria ligações para elas no seu projeto, para que o assistente siga padrões SDK7 verificados em vez de tentar adivinhar.

As ligações são criadas em `.claude/skills` e `.agents/skills` na pasta do projeto, e ambas são adicionadas a um ficheiro `.gitignore` por si, para que nunca acabem no seu repositório.

### Mantenha atualizada a cópia das skills da sua cena

Essas ligações permanecem no seu computador e nunca chegam ao seu repositório. Uma cena também pode ter a sua própria cópia das skills, que pode incluir no controlo de versões e partilhar, por exemplo, para as utilizar com a sua própria ferramenta de IA. Sempre que abre uma cena, o Creator Hub compara as skills da cena com a versão mais recente e propõe instalá-las ou atualizá-las:

* **Esta cena não tem as skills de IA da Decentraland**, com um botão **Instalar** . Esta indicação aparece sempre que abre uma cena sem essas skills.
* **Está disponível uma atualização das skills de IA para esta cena**, com um botão **Atualizar** .

A instalação ou atualização apresenta **A instalar as competências de IA mais recentes...** e, em seguida, **As competências de IA estão atualizadas**. O Creator Hub cria pastas de competências reais em `.claude/skills` e `.agents/skills`, além de um ficheiro `skills-lock.json` para que possa incluí-las no commit juntamente com a sua cena. Instala todas as competências, exceto as de criação, publicação e migração de cenas, tarefas que o Creator Hub executa por si.

A verificação segue a definição **Scene Dependencies** no separador **SCENES** das definições, o mesmo que gere as atualizações do SDK. Consulte [Alterar a pasta das cenas](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/primeiros-passos/manage-scenes.md#change-the-scenes-folder).

* **Notificar-me sobre novas atualizações de versão**: mostra as notificações acima.
* **Atualizar automaticamente todas as minhas cenas**: instala ou atualiza as competências sem pedir confirmação e, em seguida, mostra **As competências de IA estão atualizadas**.
* **Não fazer nada**: não verifica.

## Ficheiros que o assistente deixa na pasta da sua cena

O assistente pode ler e editar a cena aberta através de um servidor MCP local. Cada CLI é configurada de forma diferente para utilizar esse servidor, por isso, dependendo da que usar, poderá encontrar novos ficheiros no seu projeto:

| CLI    | O que aparece na pasta da cena                                               |
| ------ | ---------------------------------------------------------------------------- |
| Cursor | `.cursor/mcp.json`, além de `.cursor/rules/creator-hub.mdc`                  |
| Gemini | `.gemini/settings.json`                                                      |
| Claude | Nada. A configuração é guardada num ficheiro temporário fora do seu projeto. |
| Codex  | Nada. A configuração é fornecida através da linha de comandos.               |

Se já tiver um desses ficheiros de configuração, o Creator Hub integra nele a respetiva entrada, em vez de substituir os servidores que já tem.

{% hint style="warning" %}
**📔 Nota**: `.cursor/mcp.json` é o único ficheiro que contém o próprio token de acesso, porque o formato de configuração do Cursor não permite obtê-lo do ambiente. O Creator Hub adiciona-o ao seu `.gitignore` antes de o escrever, por isso, não o inclua no commit nem remova essa linha. O ficheiro do Gemini referencia o token através da variável de ambiente `$CREATOR_HUB_MCP_TOKEN` em vez disso, por isso não contém segredos e não é ignorado.
{% endhint %}

## Utilizar outra ferramenta de IA

Se já trabalha com Claude Code, Cursor, Codex ou outra ferramenta compatível com MCP, pode ligá-la à cena aberta em vez de usar o painel integrado. O MCP (Model Context Protocol) é uma forma padronizada de permitir que uma ferramenta de IA chame outro programa.

Esta opção está desativada por predefinição. Para a ativar:

1. Abra o menu principal através do logótipo do Creator Hub, selecione **Definições**, e aceda ao separador **IA** .
2. Ative **Permitir que outras aplicações de IA editem as suas cenas**.

![The AI tab of App Preferences with Allow other AI apps to edit your scenes switched on, showing the configuration box with the server URL and a hidden token, and the Copy configuration button](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-1cf9ab531f0aa6c9e346d6071ac280881a01d6b6%2Fai-settings-external-access.webp?alt=media) Esta opção é independente de **Ativar o Assistente de IA**: o assistente integrado não precisa dela, e desativá-la não afeta o assistente.

### Ligar ao Claude Code

Enquanto a opção estiver ativada, o Creator Hub grava um ficheiro `.mcp.json` na cena que tem aberta no editor. O Claude Code, quando iniciado na pasta dessa cena, lê o ficheiro e liga-se automaticamente, sem configuração.

O Creator Hub só grava este ficheiro se a sua cena ainda não tiver um ficheiro `.mcp.json` próprio. Primeiro, adiciona-o ao seu `.gitignore` e elimina-o quando fecha a cena, desativa a opção ou sai do Creator Hub.

### Ligar outra ferramenta

Por baixo da opção, clique em **Copiar configuração** e cole-a na configuração MCP da sua ferramenta. O aspeto é este, com uma porta e um token reais preenchidos:

```json
{
  "mcpServers": {
    "creator-hub": {
      "type": "http",
      "url": "http://127.0.0.1:<PORT>/mcp",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}
```

O Creator Hub também guarda os mesmos detalhes num ficheiro `mcp-server.json` na pasta de dados da aplicação, para que as ferramentas que saibam onde procurar os encontrem sem que tenha de copiar nada.

### Quando uma aplicação de IA pede acesso

Uma aplicação de IA no seu computador pode pedir para se ligar enquanto a opção está desativada. Nesse caso, o Creator Hub apresenta: **Uma aplicação de IA neste computador quer ver e alterar a cena que tem aberta.** Clique em **Permitir** para ativar a opção, ou em **Não permitir** para a manter desativada. Nada se liga até clicar em **Permitir**.

### O que as ferramentas ligadas podem fazer

Uma ferramenta ligada opera na cena que tem aberta no editor. Quando não há nenhuma cena aberta, recebe a resposta **Não há nenhuma cena aberta.**

Se uma ferramenta externa alterar a cena enquanto o assistente integrado estiver a responder, a opção **Anular alterações da IA** dessa resposta não será executada, pois também removeria as alterações da outra ferramenta. Em vez disso, use **Anular** no editor.

{% hint style="warning" %}
**📔 Nota**: Só as aplicações no seu próprio computador podem ligar-se. A porta e o token mudam sempre que o Creator Hub reinicia. Desativar a opção também substitui o token e desliga imediatamente todas as ferramentas, mas a porta permanece igual. Se a sua ferramenta receber subitamente um `401` erro, copie novamente a configuração.
{% endhint %}

## Páginas relacionadas

* [Programar com IA](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md): o guia completo sobre as SDK Skills e como criar bons prompts.
* [Combinar com código](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/overview.md): abra a sua cena num editor de código.
* [Utilizar o componente Script](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/script-component.md): associe um comportamento a uma entidade a partir de um ficheiro.


---

# 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-pt/scene-editor/expandir-com-codigo/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.
