跳到主要内容
云猴智能体云猴智能体
下载 Kaya
本页内容

常见问题

AI 能不能读取我的文件?#

默认不能。cat、head、grep 等命令默认被拦截。如果你需要 AI 读取文件,把文件放到 ~/.kaya/ 下,然后告诉 AI 路径。详见 让 AI 读取文件。

粘贴的密钥会被发出去吗?#

Kaya 会按聊天内容保护规则处理命中的敏感文本，再发送到当前模型。被替换的部分会显示“已脱敏”标记；未命中的密钥、图片内部文字等仍可能随请求发送，脱敏不构成绝对保证。请在发送前自行检查。

API Key 安全吗?#

当前配置的 API Key 使用系统凭据存储与运行时内存，仅在向对应模型端点发起请求时用于鉴权，不进入提示词正文。当前托管的网关配置使用占位凭据。历史配置、接管快照或迁移备份可能仍保留旧凭据，需另行检查和清理。

云端模型会收到什么?#

联网聊天会发送经脱敏的用户输入、工具结果及本回合所需的上下文。使用内置模型时，内容经登录令牌发往 yunhou 第一方 /chat 服务，由服务端调用模型；使用 BYOK 时，内容发往你配置的供应商，API Key 仅放在该请求的鉴权头里，不进入提示词正文；Ollama 的推理与对话内容留在本机。聊天不会改道到可选的编程 Agent 模型网关。

怎么用本地模型?#

先在终端启动 ollama serve,再打开 ⚙ 设置 → 模型 → + 添加供应商,在目录里选择 Ollama;本地端点已预填,不需要 API Key。LM Studio、vLLM 等本地 OpenAI 兼容端点选择 自定义 接入。推理、对话与工具内容都留在本机。使用情况心跳默认开启：登录后每 5 分钟向 yunhou 发送活跃时长、平台、应用版本、日期及事件标识，不含对话或文件内容；可在 设置 → 账户 单独关闭。它与云端 Token 用量同意是独立开关，使用本地模型不会自动关闭这类统计通道。云端 Token 上传仍需另外阅读清单并同意。

AI 误操作把我的文件删了怎么办?#

Kaya 自带 AI 的查询工具不提供任意文件修改或删除能力，rm、sudo 等删除或提权命令会被拦截。终端中的外部编程 Agent 仍按它自己的权限读写文件；授权其执行前，请检查操作范围。被 Kaya 工具门禁拒绝时，界面会显示原因。

为什么命令被拒绝?#

AI 试着执行的命令可能落在以下情况:

  • 命令在白名单之外,默认拒绝(你可以换个问法)

  • 命令是破坏性命令(如 rm -rf)

  • 命令是交互式程序(如 vim、REPL)

  • 命令会修改系统(如 brew install、sudo)

UI 上会显示具体的拒绝原因。

为什么 macOS 弹文件夹访问权限?#

当 AI 试图读取你受 macOS 保护目录(桌面、下载、文稿)下的文件时,macOS 会弹出权限请求。这是 macOS 自身的隐私保护机制,所有类似工具都会触发。详见 让 AI 读取文件 章节,推荐把文件放在 ~/.kaya/ 下避免。

怎么让 AI 读取指定文件?#

把文件放进 ~/.kaya/,然后在对话里告诉 AI 路径。详见 让 AI 读取文件。

怎么恢复断开的标签页?#

打开 ⚙ 设置 → 通用 标签页的 Shell 小节,点击「立即重连」重连该会话对应的 PTY。

为什么连接 LLM 时也报超时?#

首次连接 LLM 服务商最长 30 秒握手超时(网络不通、API Key 错误、Provider 限流都可能触发),UI 会显示"LLM 连接超时"横幅。检查网络与 API Key 后重试。

怎么查看 AI 的历史操作?#

打开 ⚙ 设置 → 审计,选择会话,查看事件流或运行评估。详见 安全审计。

支持哪些平台?#

当前同时发布 macOS 与 Windows 版本:

  • macOS:需要 macOS 12 或更高,Apple Silicon 和 Intel 通用(同一个 universal DMG)

  • Windows:x64,提供 NSIS(.exe)与 MSI 两种安装包,任选一个;终端为 PowerShell(pwsh 7 优先,Windows PowerShell 5.1 兜底)

模型网关会不会拖慢速度?#

通常只多一跳 127.0.0.1 本机回环转发。开销与请求大小、规则和档位有关；推荐保持默认 strict，只自动拦截具名 secret。如需自动处理普通 PII，再显式选择 balanced 或 aggressive；更强处理也可能增加误拦与还原失败风险。

为什么 Agent 里模型名变成 kaya/xxx?#

这是网关形态：配置里只写模型别名与友好名称，网关再解析成库里的真实模型，避免真实供应商、端点和 key 进入 Agent 配置。

Agent 报 400「模型未纳入网关」怎么办?#

请求模型名不是可解析的 kaya/<别名>。常见原因是手工改成裸上游模型名，或其他工具使用了默认模型。改回目录页列出的别名，或点「重新接入」；网关不会偷偷转发未纳管模型。

网关会存我的请求内容吗?#

网关脱敏审计事件只记类别计数、字节数和实际路由，不记请求正文。「隐私保护统计」是独立的本地敏感存储，保存命中片段原文与替换令牌，默认遮罩，不自动进入 LLM 上下文或诊断导出。清空当前筛选只清命中明细；全量清空还会连带清除请求事件。聊天审计日志另行保存脱敏后的正文，不能与零内容的网关审计混为一谈。

脱敏等级有什么差别?#

三套档位互相独立：聊天输入恒 aggressive；工具输出默认 aggressive，可在通用设置调整；模型网关默认 strict，只自动拦截具名 secret，普通 PII 不自动改写。balanced 会处理具名 secret 与 PII，高熵兜底只告警；aggressive 还会处理更多高熵字符串，误拦风险更高。三者独立，不把网关设置套到聊天请求上。

故障排查#

终端无响应#

  • 按 Esc 中断 AI 当前回合

  • 打开 ⚙ 设置 → 通用 标签页的 Shell 小节,点击「立即重连」重连 PTY

  • 仍无响应,尝试 ⌘W 关闭当前标签页,再 ⌘T 新建

AI 回复很慢#

  • 检查网络连接

  • 开启思考模式会增加延迟(推理本身需要时间)

  • 在设置里切换到更快的模型

工具调用被拒绝#

UI 会显示具体拒绝原因。常见的:

  • 命令是破坏性或交互式命令:换条路径

  • 命令超出白名单:换个等价工具

  • 试图读取 ~/.kaya/ 之外的文件:把文件放进 ~/.kaya/

粘贴失效#

确认焦点在正确的输入框:终端输入框的粘贴会进入终端,对话输入框的粘贴会发给 AI。

会话丢失#

检查 ~/.kaya/conversations/ 目录是否被清理。重启应用后,旧会话应自动从磁盘恢复。如果仍然看不到,可能需要清除应用本地状态后重新开始。

AI 一直不响应#

流式响应静默 30 秒会自动超时,UI 上会有超时提示。可以按 Esc 或 ⏹ 按钮手动中断。

macOS 弹文件夹权限#

把要读取的文件放进 ~/.kaya/ 下,不要让 AI 直接访问桌面、下载、文稿等受保护目录。

内置模型报「上游拒绝了本次请求 (502)」#

这是上游模型服务拒绝了请求（上下文超长、内容审核或额度问题都有可能）。Kaya 会先在后台自动压缩早期对话历史后重试一次（重试时消息流里会有「已自动压缩早期消息」的提示）；仍然失败时，错误卡片会显示具体原因。上下文超长时会提供 「开新会话」按钮；内容审核或额度不足时按对应提示处理。现有终端 tab 与运行中的 Agent 不受影响。

网关提示「被占用」或无法启动#

开发版与正式版网关互斥。关掉占用它的那个实例(通常是开发版)后重新开启即可。若端口被其他程序占用,网关会自动改用下一个可用端口。

网关已开启但 Agent 报 401 / 403#

检查 Agent 的连接状态:凭据缺失、OAuth 过期或端点被禁用都会这样。重新授权或恢复密钥;若显示已连接,用「测试连接」区分是端点不通还是凭据有问题。

网关已开启但 Agent 长时间没有输出#

上游 120 秒没有数据时,网关会中止请求并按 Agent 的协议返回错误帧,Agent 可以重试。频繁出现说明网络或上游有问题。超时诊断只含路由 ID 与耗时秒数,不含请求内容。

诊断日志#

遇到其他问题,打开 ⚙ 设置 → 日志与调试,点击「打开日志目录」查看 ~/.kaya/logs/ 下的日志文件,这些日志包含 Kaya 运行时的诊断信息(不含你的对话内容)。