# 常见问题

租户控制台常见问题与异常处理速查手册

建议使用浏览器页内搜索（Ctrl+F / Cmd+F），直接搜索报错文字或关键词。

| 问题涉及 | 小节 |
| --- | --- |
| 登录、RAM 子账号、菜单或空间不可见 | [账号与访问控制](#faq-access) |
| 表单提交、密码校验、未保存提示 | [表单与输入](#faq-form) |
| API Key 创建、密钥查看 | [API Key](#faq-apikey) |
| 预算策略、共享组、加油包 | [预算管理](#faq-quota) |
| 运行环境、通道集成 | [运行环境与通道](#faq-infra) |
| Webhook 回调地址、运行时变量与调试 | [Webhook](#faq-webhook) |
| 会话列表、搜索无结果 | [会话查询](#faq-query) |
| 知识文档上传、生成与恢复 | [知识管理](#faq-knowledge) |
| Mulerun 授权、第三方面板 | [第三方集成](#faq-integration) |

## 账号与访问控制

**Q: RAM 子账号看不到某个菜单或应用空间**

- **原因：** 租户可能开启了「RAM 子账号权限限制」，菜单权限和空间开放范围由主账号分别配置。
- **处理：** 请主账号在「租户设置 → 访问控制」检查该子账号的可访问菜单；再到「租户设置 → 应用空间 → 访问设置」检查空间是否对该子账号开放。

**Q: 指定子账号可见时为什么不能保存空名单？**

- **原因：** 一个子账号都不选，会让该空间对所有 RAM 子账号不可见，系统要求明确确认至少一个可访问人。
- **处理：** 至少勾选一个子账号；如果所有子账号都应访问，改选「全部子账号可见」。

**Q: SSO 免登用户为什么不能重置密码？**

- **原因：** SSO 用户来自客户自有登录体系，密码由客户侧管理，点金控制台没有其密码。
- **处理：** 在客户侧登录体系完成密码操作。删除 SSO 用户后，如果它再次免登会重新开户，历史会话与记忆不再关联。

## 表单与输入

**Q: 必填项为空时无法提交**

带 `*` 的字段为必填。按界面补齐字段，并留意长度限制（空间名称 ≤128、描述 ≤512、Hook 名称 1~128、Hook 描述 0~512 等）。

**Q: 创建或重置用户时提示密码不符合规则**

密码必须：不少于 8 位、包含大写字母、包含小写字母、包含数字、包含特殊字符、且不包含用户名。建议点击「自动生成」，并保证两次输入一致。

**Q: Webhook / Hook 表单离开时提示有未保存修改**

系统检测到配置已经变化。先点击「创建 Webhook / 创建 Hook」或「保存更改」；确认不需要这些修改时，才选择放弃离开。

## API Key

**Q: 关闭创建结果窗口后无法再次查看 API Key 明文**

出于安全设计，API Key 明文只在创建时展示一次。创建时先复制到安全的密钥管理工具，再点击「我已保存，关闭」；如果遗失，只能创建新 Key、完成调用方切换后删除旧 Key。

## 预算管理

**Q: 删除预算策略时提示仍有绑定账户**

策略下还有成员全局预算、成员智能体共享组或智能体预算账户时，后端会拒绝删除。先在成员页和智能体页逐个解除绑定，再删除策略。解绑会级联作废**该账户**下的加油包，请先确认剩余额度。

**Q: 解绑预算后哪些加油包会作废？**

只作废当前被解绑账户名下的加油包。例如解除一个成员智能体共享组，不会影响该成员的全局预算及其他共享组。历史流水保留可查。

**Q: 成员为什么既有全局预算又有智能体预算？**

全局预算限制成员在本应用所有智能体上的总消耗；智能体预算为这个成员选定的一组智能体设置共享额度。两者同时生效，任一耗尽都拦截。一个成员只有一个全局预算，但可以有多个智能体共享组。

**Q: 用量通知里选不到 Webhook**

下拉框只显示触发规则为「预算配额通知」的应用级 Webhook。请先在「Webhook 管理」中新建这类 Webhook；它不能与智能体触发时机组合，也不能挂载到智能体。

## 运行环境与通道

**Q: 运行环境达到数量上限，创建按钮被禁用**

运行环境上限按**整个租户**跨应用空间合计，默认 10 个。运行中的环境需先「停用」再「归档」，归档后释放额度；也可以联系管理员提高租户配额。

**Q: 通道的创建按钮不可用**

通道创建或修改前必须先通过「测试连接」。请按类型核对凭证：钉钉为 Bot Code / Client Secret，企业微信为 Bot ID / 应用密钥（以及可选 Corp ID），飞书为 App ID / App Secret。钉钉选流式回复时还必须填写卡片模板 ID。

**Q: 为什么能筛选微信通道，却不能创建？**

当前控制台保留「微信」筛选项，用于查看已有或通过其他方式接入的数据，但创建下拉框暂时只支持钉钉、企业微信和飞书。

## Webhook

**Q: 回调地址提示协议、主机或端口必须固定**

回调地址只允许在 path 和 query 参数值中使用运行时变量，协议、主机、端口、Query 参数名必须是固定值。地址还必须是完整的 HTTP / HTTPS URL，不能包含 fragment 或用户信息。

**Q: 运行时变量语法不合法或没有被替换**

变量必须写成 `${sys.变量名}` 或 `${ctx.自定义名}`。系统变量支持 principalId、sessionId、agentId、requestId；ctx 变量要由调用方通过 `runtimeVariables` 参数传入。预算配额通知 Webhook 不支持运行时变量。

**Q: 调试结果异常，如何快速定位？**

先确认左侧名称、执行时机和回调地址完整，再点击「运行调试」。在结果中查看「概览 / 请求 / 响应 / 耗时分析」，也可以点击「帮我看看」生成诊断报告并「复制诊断」。配置变化后需要重新运行。

## 会话查询

**Q: 会话列表查询没有结果**

放宽时间范围、清空精确 ID 条件，并确认当前应用空间正确。填写 Session ID 后会按 ID 单独查询，其他筛选条件不生效；右上角「搜索会话」不是执行筛选，而是打开按标题和内容检索的全文搜索弹窗。

## 知识管理

**Q: 知识文档选择后没有进入上传队列**

检查文件：不能是空文件，单个不超过 100MB；普通文档支持 PDF、Word、TXT、Markdown、JPG、PNG，一次最多 20 个；Excel / CSV 必须逐个导入并配置列映射。不支持的类型会直接提示原因。

**Q: 刷新页面后上传中断**

批量上传支持最小化和站内切换，但刷新或关闭页签会停止未完成任务。上传期间不要刷新；中断后检查文档列表，再重试失败项。

**Q: 提示受理结果未确认，是否直接重试？**

不要立即重试。上次请求可能已在服务端成功受理，先检查文档列表；确认没有重复文档后再点「确认重试」，否则可能重复导入。

**Q: 智能体删除的文档如何恢复？**

进入知识库详情的「智能体删除的文档」视图，打开「Agent 变更记录」，查看删除前后差异并选择「恢复文档」。手动删除的文档不会出现在这里，也不能通过该功能恢复。

## 第三方集成

**Q: Mulerun 授权面板无法加载**

浏览器广告拦截扩展或安全策略可能拦截了无影沙箱页面。暂时禁用 AdBlock、uBlock Origin 等扩展，或把 `wy.aliyun.com` 加入白名单，然后刷新重试。