> 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-unity-sdk/features/multi-character-sessions/character-identity.md).

# 角色身份

为共享同一 Convai 房间的角色分配 Character ID 的参考，以及检测两个角色使用同一 ID 的检查机制。

每个 `ConvaiCharacter` 在房间中都需要自己的角色 ID。两个角色不能共用同一个，SDK 会在编辑场景时以及房间连接时检查这一点。

### 为什么 ID 不能共享

SDK 会按角色 ID 路由所有权、参与者和音频。两个持有相同 ID 的角色不会各自获得独立路由——第二个会与第一个冲突，房间会通过最先注册的那个来响应两者，而不是将它们分开。

复制一个可正常工作的角色，是场景获得第二个角色的常规方式，而副本会带着原角色的角色 ID。正因如此，下面的两个检查才会存在。

### 角色检查器中的编辑模式警告

选择一个 `ConvaiCharacter` 它与另一个角色共享同一个角色 ID，且该角色位于已加载的场景中，而其检查器显示一个标题为 **另一个角色拥有此角色 ID**:

```
“<other character>” 在已加载的场景中使用了同一个 ID。SDK 依据角色 ID 来键入所有权、参与者
和音频，因此两个共享同一个 ID 的角色会发生冲突，而不是各自获得独立处理——
房间会将两者路由给最先注册的那个。请从
Convai 仪表板为这个角色分配自己的 ID。
```

该消息会列出所有与该 ID 共享的其他角色，而不只是找到的第一个。无论是否启用了多角色会话，检查都会运行——在任何场景中，重复的 ID 都是不正确的，因为注册表会无论房间结构如何都按它作为路由键。

{% hint style="info" %}
`Convai.ValidateSetup` 会将相同的冲突报告为错误，因此持续集成运行或编辑器脚本可以在无需打开检查器的情况下捕获它。
{% endhint %}

### 房间连接时的拒绝

如果一个房间中处于活动且已启用的角色里包含两个拥有相同角色 ID 的角色，房间将拒绝连接。 `ConvaiOperationException` 会带有这条消息：

```
“<first character>” 和 “<second character>” 都使用角色 ID <id>。一个房间中的两个角色
不能共享同一个 ID——SDK 会按它路由所有权、参与者和音频，因此它们会冲突
而不是分别响应各自。请从 Convai
仪表板为每个角色分配自己的角色 ID。
```

此检查会在进入房间名册的两条路径上运行：连接时提交的完整角色列表，以及房间已经运行后稍后添加的单个角色。无论哪种情况，房间都不会连接——或者不会接受该添加——而不是让这两个角色发生冲突后继续连接。

### 角色 ID 格式

该 **角色 ID** 上的字段 `ConvaiCharacter` 会独立于重复检查进行验证。无效值会在检查器中产生以下消息之一：

| 条件      | Message                                                                              |
| ------- | ------------------------------------------------------------------------------------ |
| 字段为空    | `必须提供角色 ID。请从 Convai 仪表板上角色页面复制它。`                                                   |
| 前导或尾随空白 | `角色 ID 前后有空格。请删除多余空格。`                                                               |
| 长度错误    | `角色 ID 应为 36 个字符，而当前这个为 <length>。请从 Convai 仪表板复制完整 ID。`                              |
| 不是 GUID | `角色 ID 的格式不是预期的 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。请从 Convai 仪表板重新复制——很容易误选成角色名称。` |

重复 ID 的比较会忽略大小写和首尾空白，因此 `AB12…` 和 `ab12…` 会被视为相同的 ID。没有 ID 的角色会被重复检查跳过，而是由上面的格式检查报告。

### 相关

{% content-ref url="/pages/1de47e20d64086de6ea2148c4871a665eec92182" %}
[多角色会话工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/how-multi-character-sessions-work.md)
{% endcontent-ref %}

{% content-ref url="/pages/a6e9c177aa5c598a856889f7e4baf09e8b838a4d" %}
[构建你的第一个多角色会话](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/quick-start.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/multi-character-sessions/character-identity.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.