> 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` 房间中的每个角色都需要自己的 Character ID。两个角色不能共用同一个，而且 SDK 会在编辑场景时以及房间连接时检查这一点。

### 为什么一个 ID 不能共享

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

复制一个可用角色是场景获得第二个角色的常见方式，而副本会带着原角色的 Character ID。下面这两个检查就是为了这种情况而存在的。

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

选择一个 `ConvaiCharacter` 其 Character ID 与已加载场景中的另一个角色相同，而其检查器会显示一个标题为 **另一个角色已使用此 Character ID**:

```
“<other character>” 在已加载场景中使用了同一个 ID。SDK 会以 Character ID 为键来处理所有权、参与者
以及音频，所以两个共享同一个 ID 的角色会发生冲突，而不是各自拥有自己的——
房间会将两者都路由给先注册的那个。请从
Convai 仪表板。
```

该消息会列出所有与该 ID 共享的其他角色，而不仅仅是找到的第一个。无论是否启用了多角色会话，检查都会运行——重复的 ID 在任何场景中都是错误的，因为注册表会始终按它对路由进行键控，而不管房间形态如何。

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

### 房间连接时的拒绝

如果某个房间的已激活、已启用角色中包含两个具有相同 Character ID 的角色，它会拒绝连接。 `ConvaiOperationException` 会带有此消息：

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

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

### Character ID 格式

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

| 条件      | 消息                                                                                            |
| ------- | --------------------------------------------------------------------------------------------- |
| 字段为空    | `需要 Character ID。请从你在 Convai 仪表板上的角色页面复制它。`                                                   |
| 前导或尾随空白 | `Character ID 前后有空格。请删除多余空格。`                                                                 |
| 长度错误    | `Character ID 应为 36 个字符，而这个是 <length> 个字符。请从 Convai 仪表板复制完整 ID。`                              |
| 不是 GUID | `Character 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 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-unity-sdk/features/multi-character-sessions/character-identity.md?ask=<question>&goal=<endgoal>
```

`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.