> For the complete documentation index, see [llms.txt](https://docs.acestudio.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acestudio.ai/docs/product-wiki-zh/ai-zhi-neng-ti/external-agent-access.md).

# 外部代理访问

通过 MCP 和 CLI，将 ACE Studio 连接到 AI 助手和代理。

{% hint style="warning" %}

#### 实验状态

ACE Studio 中的外部代理访问目前仍处于试验阶段，并在积极开发中。

**请注意：**

* **破坏性变更：** 工具命令、格式和约定可能会在不同更新之间发生变化。
* **开发进行中：** 目前并非所有 ACE Studio 功能都已对代理完全开放。
* **尚有待打磨之处：** 随着我们持续优化代理交互，您可能会遇到错误、意外的边缘情况或不自然的行为。

如果您遇到问题或有建议，请告诉我们： [**support@acestudio.ai**](mailto:support@acestudio.ai).
{% endhint %}

将 AI 助手和代理（如 Claude、ChatGPT、OpenClaw 或 Hermes Agent）直接连接到 ACE Studio，以便实时理解并编辑你的音乐工程。

### 你的代理可以做什么

连接后，代理即可在 ACE Studio 的大部分功能中查看并编辑你的工程：

* **编曲与作曲** — 管理轨道、片段、音符、歌词、和弦和播放头。
* **歌声与乐器** — 调整声线模型、音源、多歌手合唱层和人声参数（音高、呼吸、张力），并加载第三方乐器插件。
* **时序与结构** — 设置 BPM、拍号、循环段标记和走带。
* **制作与 AI 工具** — 触发添加层、人声转 MIDI、音轨分离、音乐增强，并加载 FX 链或预设。
* **会话控制与交付** — 创建并保存工程，导入音频和 MIDI，并导出完整混音、单独音轨、视频等。

只需用自然语言描述您的需求，您的助手便会检查工程并进行更改。

***

### 连接您的助手

选择适合您工作流程的设置方式：

#### 路径 A：让您的 AI 代理为您完成配置

如果您使用可访问本地环境或计算机的代理（例如 **Claude Code**, **Codex**, **OpenClaw**，或 **Hermes Agent**），它可以自动配置。

{% hint style="info" %}
此方式需要在与 ACE Studio 同一台电脑上运行的代理，并授予其执行命令和编辑配置文件的权限。
{% endhint %}

最快的方法是在 ACE Studio 内完成。点击 **代理图标** 在窗口右下角，选择 **ChatGPT**, **Claude**，或 **其他代理**，并按照所示的三个步骤操作：打开你的代理，复制连接提示，其中包含 **复制** 按钮并发送，然后使用其中一个示例提示开始创建。

这里也复现了相同的连接提示。将其复制并粘贴到你的代理中，然后点击发送：

```
使用 acetudio-cli 或 MCP 为我连接到 ACE Studio。

默认位置：
- macOS MCP："/Applications/ACE Studio.app/Contents/Helpers/ace-mcp-server"
- macOS CLI："/Applications/ACE Studio.app/Contents/Helpers/acestudio-cli"
- Windows MCP："C:\Program Files\ACE Studio\ace-mcp-server.exe"
- Windows CLI："C:\Program Files\ACE Studio\acestudio-cli.exe"

请先尝试使用 CLI，并将工具路径记入你的指令/记忆中。如果 CLI 访问因沙箱或权限限制而受限，请注册 MCP 服务器（名称为“ace-studio”，作用域为用户/全局）。如果在默认位置找不到，请向我索取 ACE Studio 的偏好设置 → 常规 → 外部代理访问中的路径。

然后，从 ACE Studio 的官方仓库 https://github.com/BeatMagic/acestudio_agent_plugin 安装 skills/代理插件。安装并可用这一插件非常重要，因为它会提供你在与 ACE Studio 交互时所需的知识。

如果你需要关于 ACE Studio 及其代理集成的更多上下文，请参阅 https://docs.acestudio.ai/llms.txt 中的文档。如果你的运行环境无法自行配置或执行本地命令，请引导我完成你平台上的手动设置步骤。
```

***

#### 路径 B：在你的运行环境中手动配置

如果你的代理运行环境无法自动配置，你需要将 ACE Studio 的 MCP 服务器手动添加到其配置中。

[模型上下文协议（MCP）](https://modelcontextprotocol.io/docs/getting-started/intro) 是一种连接 AI 助手与外部应用程序的开放标准。ACE Studio 作为本地 STDIO 服务器运行，允许任何兼容 MCP 的客户端使用启动命令直接连接。

**通过终端配置**

如果你使用 Claude 或 Codex，并偏好直接在终端中配置：

{% tabs %}
{% tab title="Claude" %}
在终端中运行：

**macOS：**

```bash
claude mcp add --scope user ace-studio -- "/Applications/ACE Studio.app/Contents/Helpers/ace-mcp-server"
```

**Windows：**

```cmd
claude mcp add --scope user ace-studio -- "C:\Program Files\ACE Studio\ace-mcp-server.exe"
```

{% endtab %}

{% tab title="Codex" %}
在终端中运行：

**macOS：**

```bash
codex mcp add ace-studio -- "/Applications/ACE Studio.app/Contents/Helpers/ace-mcp-server"
```

**Windows：**

```cmd
codex mcp add ace-studio -- "C:\Program Files\ACE Studio\ace-mcp-server.exe"
```

{% endtab %}
{% endtabs %}

**桌面聊天应用**

如需带有配置演示的完整分步指南：

* [**Claude Desktop 与 Cowork**](/docs/product-wiki-zh/ai-zhi-neng-ti/external-agent-access/claude-desktop-and-cowork.md) — 提供带配置文件演示的 Claude Desktop 分步配置。
* [**桌面版 ChatGPT**](/docs/product-wiki-zh/ai-zhi-neng-ti/external-agent-access/chatgpt-for-desktop.md) — ChatGPT Work 和 Codex 模式的分步设置。

**其他运行环境与 IDE（VS Code、Cursor、自定义客户端）**

大多数 MCP 客户端和 IDE 需要相同的配置参数：

* **走带类型：** STDIO（有时标记为“Local”或“Command”）
* **命令：** 从 ACE Studio 复制的启动命令
* **参数 / 环境：** 无

对于通过 JSON 文件配置的运行环境：

{% tabs %}
{% tab title="标准 MCP 配置（Cursor 等）" %}
供 Cursor 使用（`~/.cursor/mcp.json` 或 `.cursor/mcp.json`）以及大多数标准 MCP 运行环境：

```json
{
  "mcpServers": {
    "ace-studio": {
      "command": "/Applications/ACE Studio.app/Contents/Helpers/ace-mcp-server"
    }
  }
}
```

{% endtab %}

{% tab title="VS Code（GitHub Copilot）" %}
添加到 `.vscode/mcp.json` 在你的工程工作区中：

```json
{
  "servers": {
    "ace-studio": {
      "type": "stdio",
      "command": "/Applications/ACE Studio.app/Contents/Helpers/ace-mcp-server"
    }
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**JSON 中的 Windows 路径转义：** 如果你在 JSON 文件中手动编写使用反斜杠的 Windows 路径，请将每个反斜杠转义为双反斜杠（`\\`），或使用正斜杠（`/`).
{% endhint %}

{% hint style="warning" %}
**基于浏览器的 AI 助手：**\
ACE Studio 的 MCP 服务器通过 STDIO 在你的机器上本地运行。仅限网页的界面（例如在网页浏览器中的 ChatGPT 或 Claude）无法直接连接到本地 STDIO 服务器。请改用各自的桌面应用程序或终端客户端。
{% endhint %}

{% hint style="info" %}
**自定义安装路径：** 如果你将 ACE Studio 安装到自定义目录，请打开 **偏好设置 → 通用 → 外部代理访问** 在 ACE Studio 中：

* 点击 **复制命令** 旁边 **MCP 服务器（stdio）** 用于 MCP 服务器路径。
* 点击 **复制** 旁边 **acestudio-cli 可执行文件路径** 用于 CLI 路径。
  {% endhint %}

***

### 正在验证连接

请确保 ACE Studio 已打开并正在运行，然后向你的助手询问：

```
请检查当前 ACE Studio 工程信息
```

如果你的助手返回工程的曲速、调号和轨道列表，则说明设置已完成并可使用。

***

### 创意提示示例

以下是一些在 ACE Studio 中与 AI 助手协作的实际示例：

#### 1. 人声制作与多歌手和声

```
在主人人声轨道（轨道 1）上启用合唱模式，添加两位伴唱歌手
声线，拓宽立体声声场，并将其电平降低 -3 dB，以营造丰满的背景和声。
```

#### 2. 自定义声音混合

```
在轨道 2 上创建自定义混合声线：混合 70% 温暖的原声流行声线种子
与 30% 轻盈、带气声的声线种子，然后将该混合声线命名为“Velvet 气声”。
```

#### 3. 和弦与歌曲草稿创作

```
在和弦轨的第 1–8 小节中，插入一段新灵魂乐和弦进行：
Ebmaj9 — G7#9 — Cm9 — F13（各 2 小节）。
然后添加一条罗德钢琴轨道，并创建一条跟随根音、富有律动感的贝斯线。
```

#### 4. AI 伴奏与音频提取

```
将轨道 1 中导入的音频片段分割为人声、鼓、贝斯及其他音轨。
然后对提取出的人声音轨运行人声转 MIDI，以创建可编辑的演唱轨道。
```

#### 5. 生成式歌曲创意与层

```
试听从小节 9 到 25 的编曲，并使用添加层来生成
与当前工程曲速匹配的电影感弦乐铺底伴奏层。
```

#### 6. 富有表现力的人声调音与动态

```
检查轨道 1 上副歌的人声音符：平滑音高过渡，
增加起始音符的气声感，并为延长音符添加细微的颤音曲线。
```

#### 7. FX 链与音轨交付

```
将一款复古人声压缩器和温暖的板式混响加载到主人声 FX 链上，
然后将所有单独轨道导出为 24 位 48kHz WAV Stem，保存到我桌面上的“Stem”文件夹中。
```


---

# 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.acestudio.ai/docs/product-wiki-zh/ai-zhi-neng-ti/external-agent-access.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.