Agent 接入开放了什么

Agent 接入允许本机上的程序读取和修改 Studio 中打开的项目，本页说明这项能力建立在哪些保障之上

开启之前不监听任何端口

新配置中 允许 Agent 连接 是关闭的，在开启之前 Studio 不提供任何服务。关闭后端点立即停止

仅限本机

端点只绑定在 127.0.0.1 上，其他机器无法访问。但仅限本机还不够，作者打开的任何网页都能向本机发送请求，因此每个请求在读取内容之前都要经过以下检查：

• 带有 Origin 请求头的请求一律拒绝：浏览器会发送该请求头，而 MCP 客户端是独立程序，不会发送。这样可以挡住向该端口发请求的网页，包括把自身主机名解析到 127.0.0.1 的网页
• Host 请求头必须指向端点本身：127.0.0.1 或 localhost 加上端口
• 请求必须携带访问令牌，形式为 Authorization: Bearer <token>，缺少令牌或令牌错误的请求会被拒绝
• 单个请求最大 4 MB：Agent 发送的最大内容是以文本表示的一个场景或一个页面

请求中的任何内容都不会被当作代码执行，每次调用的参数在执行前都会按该工具的参数结构校验

访问令牌

Studio 把令牌和其他 Agent 接入设置一起保存在用户数据目录下的 agent-mcp.json 中。在 macOS 和 Linux 上，该文件仅当前账户可读；在 Windows 上，它依赖用户数据目录本身的权限。令牌不放在 Studio 的通用设置中，因为通用设置经常被导出和分享

在 Agent 接入开启期间，任何能读取令牌的程序都能修改作者的项目，因此应像对待密码一样对待它。更换令牌 → 重新生成 会立即签发新令牌，使用旧令牌配置的客户端从下一次请求起被拒绝，需要重新复制配置；stdio 条目不含令牌，不受影响

令牌不会进入项目窗口。项目窗口运行插件代码，因此它的智能体菜单只能得知 Agent 接入是否开启、是否允许修改、是否开启了完全访问以及端点是否在运行；从该菜单复制配置时，复制操作在窗口之外完成，直接写入剪贴板

Agent 可以修改什么

默认不允许修改：允许 Agent 修改工程 关闭时，Agent 可以读取打开的项目，所有修改操作都会被拒绝。在项目窗口的智能体菜单中打开该开关时，Studio 会先用自己的窗口询问 允许 Agent 修改工程？，项目窗口中的插件代码无法代为回答，见在 Studio 自己的窗口中询问；关闭该开关则无需确认。完全访问同样允许修改

暂停只作用于一个项目：Agent 暂停期间，它对该项目的所有修改都会被拒绝，读取不受影响

项目繁忙时拒绝修改：项目冻结期间不接受任何修改，包括正在查看历史版本、作者手动冻结、版本控制合并未完成、Studio 处于恢复模式，以及项目已被另一个 Studio 窗口接管。Team 实时会话进行期间，Agent 的修改同样被拒绝，以免与会话中的成员相互冲突

修改经由 Studio 完成：Agent 没有直接写入项目目录文件的工具。每次修改都经过与手动编辑相同的服务，因此会显示在编辑器中、记为一步撤销，并像手动编辑一样接受检查；未通过检查的场景、页面或蓝图不会被写入

未受信任的项目不能运行：不是由 Studio 创建的项目在受信任之前不能试玩或构建，对 Agent 和作者都是如此。点击状态栏中的 未受信任，或在设置 → 数据 → 受信任的项目中，可以信任该项目

项目以外的文件夹

Agent 会读取本机上的文件并导入项目：美术、音频和字体，以及用来构建分层立绘角色的 PSD。项目目录内以及 允许导入素材的文件夹 中列出的文件夹里的文件，无需询问即可读取

其他文件夹需要询问作者：某次调用需要其他位置的文件时，Studio 会在项目窗口上方打开 允许 Agent 读取文件夹？ 窗口。该调用并非由屏幕前的作者发起，因此窗口不会从其他应用抢占前台：它停留在发起请求的项目窗口上方，同时 macOS 上 Studio 的程序坞图标会跳动，Windows 和 Linux 上其任务栏按钮会闪烁。Studio 已在前台时，窗口会获得焦点。窗口列出发起请求的客户端和存放这些文件的各个文件夹，一次最多五个。Agent 用 request_folder_access 事先请求时，窗口还会以 Agent 说明的用途： 开头，原样显示它给出的用途。Studio 询问的是文件所在的文件夹，而不是更大的范围，只有需要的文件夹超过五个且其中一些有共同的上级文件夹时才会合并

• 允许访问此目录 或 允许访问这些目录：Agent 可以读取这些文件夹，它们会被添加到 允许导入素材的文件夹，之后可以用 移除 撤回
• 拒绝：拒绝本次调用。拒绝之后的 60 秒内，同一文件夹会直接答复为已拒绝而不再弹窗，因此立即重试的 Agent 无法反复把同一个问题推到作者面前。Agent 会被告知不要再次请求，改为在对话中询问作者
• 关闭窗口或按 Escape 等同于 拒绝

无论哪个项目窗口发起请求，同一时间只显示一个询问窗口。一次调用最多等待约 50 秒，作者届时仍未回答的，Agent 会被告知该文件夹正在等待作者答复，询问窗口保持打开；作者允许之后，Agent 的下一次尝试即可通过

有些文件夹永远不会开放，无论是否开启完全访问：磁盘或文件系统的根目录，整个主文件夹，任何包含主文件夹的文件夹，以及 Studio 自身的文件夹，即保存设置和访问令牌的文件夹与应用程序本身，包括任何包含它们的文件夹。Agent 请求这些文件夹时，会被告知改为指明其中实际存放文件的那个文件夹

完全访问

设置 → Agent 接入 中的 完全访问，与项目窗口智能体菜单中的 允许 Agent 完全访问 是同一个开关，默认关闭。无论从哪里打开，Studio 都会先询问 允许 Agent 完全访问？；关闭则无需确认

开启期间：

• 无论 允许 Agent 修改工程 是否打开，Agent 都可以修改工程。该开关显示为已打开，在关闭完全访问之前不能切换
• Agent 可以不经询问读取任意文件夹中的文件，这些文件夹不会添加到 允许导入素材的文件夹
• 永远不会开放的文件夹仍然关闭：Studio 自身的文件夹、整个主文件夹以及磁盘根目录
• 暂停、项目冻结、Team 实时会话以及每次修改都要经过的检查依然有效

在 Studio 自己的窗口中询问

Agent 接入向作者提出的每个问题，都在标题为 Agent 接入 的 Studio 窗口中打开：是否允许修改、是否给予完全访问、是否允许读取某个文件夹，以及导出的 Skill 是否替换同名文件。该窗口由 Studio 自己在项目窗口之外打开，项目窗口中运行的插件代码既看不到也无法回答它。作者自己触发的询问，即打开某个开关或导出 Skill 时，窗口会出现在前台；Agent 发起的文件夹询问则不抢占前台，见项目以外的文件夹。只有窗口中的允许或替换按钮才算同意，按 Escape、关闭该窗口或关闭它所属的项目窗口都视为拒绝

插件工具

插件可以为 Agent 提供自己的工具，见插件工具

接受同样的检查：修改项目的插件工具，在未允许修改、Agent 暂停、项目冻结以及实时会话期间都会被拒绝，与 Studio 自身的工具完全相同。插件无法绕过这些检查

只读工具无法写入：插件注册为只读的工具运行期间，该插件保存的数据拒绝任何写入。写入工具对这些数据的修改记为一步撤销

事先告知作者：插件提供 Agent 工具时，安装提示会在 AI Agent 一项中说明，并给出工具数量以及其中可修改项目的数量。后续版本新增工具，或把只读工具改为可修改项目的工具时，会再次询问

可以关闭某个插件的工具：设置 → Agent 接入 → 插件工具 列出提供工具的已启用插件，每个插件都有一个 允许 … 的 Agent 工具 开关。在此关闭的插件，其工具不会向 Agent 列出，调用也会被拒绝

作为插件代码运行：插件工具在项目窗口中以该插件自身的权限运行，与插件的其他代码相同。插件不在沙箱中运行，安装时对插件的信任同样适用于它的工具，见安装插件

Agent 能触及的范围

Agent 可以按路径打开本机上的任何项目目录，也可以在任何文件夹中新建项目，与作者在 Studio 中能做的一样。构建产物默认写入项目的构建目录，除非 Agent 指定其他位置。Agent 接入并不限制 Agent 打开哪个项目，上述开关限制的是它在项目中能做什么。它能读取项目以外的哪些文件，见项目以外的文件夹

Agent 做过的事记录在项目窗口的 Agent 日志 和 Studio 自身的日志中，见用 Agent 制作游戏