> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant/quick-start.md). # AI 编码助手快速入门 在 Convai 编辑器窗口中打开“设置 AI 编码”，选择一个编码代理，重启编辑器，并确认 Convai 工具已注册。 将受支持的编码代理连接到已安装 Convai 插件的 Unreal 项目，这样代理就可以调用 Convai 的编辑器操作并读取其技能文档。首次在项目中设置 AI 编码时，请使用此快速入门。最后，如果你选择了 Convai 入门说明，代理的上下文文件中会包含它；而且代理可以通过引擎的 MCP 服务器访问 Convai 的工具。 {% embed url="" %} 设置 MCP 并使用编码代理驱动编辑器 {% endembed %} ### 先决条件 * Unreal Engine **5.8 或更高版本**。在 UE 5.0–5.7 中， `ConvaiToolset` 模块会编译为空，并且 **设置 AI 编码（MCP）** 菜单项不会出现。 * 一个 **编辑器** 项目的构建版本——AI 编码工具没有运行时依赖，且仅存在于编辑器中。 * 已安装并启用 Convai 插件。参见 [安装 Convai 插件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md). * 在你的机器上安装了受支持的编码代理。参见 [受支持的编码代理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant/supported-coding-agents.md) 以查看完整列表。 ### 打开“设置 AI 编码”对话框 {% stepper %} {% step %} #### 打开设置下拉菜单 在 Convai 编辑器窗口中，单击 **设置** 图标并选择 **设置 AI 编码（MCP）** 下拉菜单中的该项。此项仅在 UE 5.8 或更高版本中显示。 {% endstep %} {% step %} #### 选择一个代理 在 **为此项目设置 AI 编码（MCP）** 对话框中，使用 **AI 代理** 下拉菜单选择 `Claude Code`, `Cursor`, `VS Code`, `Gemini`，或 `Codex`. {% endstep %} {% endstepper %} ### 设置配置选项 在确认前设置对话框中的每个选项。默认值来自 `FConvaiMcpSetupOptions`. | 选项 | 默认值 | 作用 | | -------------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bAutoStartServer` | 在 | 标记为以下内容的复选框 **在编辑器启动时自动启动 MCP 服务器**。可使引擎的 MCP 服务器在之后的编辑器启动中自动保持运行。 | | `bConfigureTerminal` | Off | 标记为以下内容的复选框 **配置 Terminal 插件，使打开终端时从此项目开始并运行代理**。仅适用于 CLI 代理（`Claude Code`, `Codex`, `Gemini`）。会在 Terminal 插件的设置中写入一条启动命令，将目录切换到你的项目目录并启动代理的 CLI 命令。对以下项已禁用： `Cursor` 和 `VS Code`，它们是 GUI 应用程序。 | | `bAddPrimer` | Off | 标记为以下内容的复选框 **将 Convai 指令添加到代理的上下文文件**。会将 Convai 入门说明写入代理自己的上下文文件——参见 [受支持的编码代理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant/supported-coding-agents.md) 以了解每个代理对应哪个文件。如果该文件已存在，请选择 **追加** 以保留现有内容，或 **替换** 以覆盖该文件； **追加** 为默认选项。 | | `bCodexAutoApprove` | Off | 标记为以下内容的复选框 **让 Codex 无人值守运行，不显示批准提示（绕过 Codex 的沙箱）**. `Codex` 仅限。会修改终端启动命令，使其在没有审批提示且无沙盒的情况下运行。参见 [受支持的编码代理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant/supported-coding-agents.md#codex-auto-approve) 后再启用它。 | {% hint style="warning" %} 启用 **让 Codex 无人值守运行，不显示批准提示（绕过 Codex 的沙箱）** 会在没有审批提示且无沙盒的情况下运行 Codex——它可以完全访问你的机器。只有在你信任代理将在此项目中运行的内容时，才启用它。 {% endhint %} ### 完成设置并重启 点击 **启用并重启**。插件会启用引擎的 `ModelContextProtocol`, `AllToolsets`，以及 `Terminal` 插件在项目描述文件中并重启编辑器。下次启动时，它会写入代理的 MCP 客户端配置，应用你选择的终端和入门说明选项，并启动 MCP 服务器。 ### 验证代理能看到 Convai 的工具 编辑器重启后，出现一条以 `Convai MCP ready.` 表示客户端配置已写入，并告诉你如何连接到代理——对于 CLI 代理，是在终端中运行的具体命令；对于 GUI 代理，则是在项目文件夹中打开它。打开你的编码代理并让它列出可用的 MCP 工具。正常工作的设置会将引擎自身的 Unreal MCP 工具与七个 Convai Toolset 操作一起显示。 {% hint style="success" %} 当代理在其可用工具中列出 Convai 的编辑器操作，并且如果你添加了入门说明，其上下文文件中包含位于……之间的代码块时，设置即完成 `` 和 ``. {% endhint %} ### 故障排查 #### Codex 配置已存在 **症状：** 设置通知显示为 `Codex 配置已存在 - 保持未修改；请手动将 unreal MCP 服务器添加到其中（http://127.0.0.1:8000/mcp）。` **原因：** 引擎的 `ModelContextProtocol.GenerateClientConfig` 控制台命令不会覆盖现有的 `.codex/config.toml` 在项目中。 **解决方法：** 打开 `.codex/config.toml` 并将 Unreal MCP 服务器添加到 `http://127.0.0.1:8000/mcp` 中，手动完成。 **验证：** 让 Codex 列出其 MCP 工具，并确认 Unreal 服务器以及其上的 Convai 操作都已列出。 #### Terminal 选项未生效 **症状：** 你已启用终端选项，但在项目中打开终端并不会启动你的代理。 **原因：** 引擎的 `Terminal` 应用设置时模块未加载，因此插件跳过了终端配置。 **解决方法：** 请确认 `Terminal` 插件已在以下位置启用： **Edit > Plugins**，重启编辑器，然后重新打开 **设置 AI 编码（MCP）** 并重新启用终端选项。 **验证：** 在项目中打开一个新终端。它应切换到项目目录并自动启动代理。 ### 下一步 {% content-ref url="/pages/6c5b338b9a5aeacf26b73bf6839fa355e17f8687" %} [AI 编码助手](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant.md) {% endcontent-ref %} {% content-ref url="/pages/bd854b0a181a4f4a7045d8d8362563af4a4e3ea7" %} [受支持的编码代理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant/supported-coding-agents.md) {% endcontent-ref %} {% content-ref url="/pages/0eefa31119f629a5166503c9151f405117e822a4" %} [Convai 工具集参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant/convai-toolset-reference.md) {% endcontent-ref %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/ai-coding-assistant/quick-start.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.