Kalka
文档

故障排除

解决 macOS 和 Windows 的首次启动警告、Linux、更新、MCP 端口、浏览器中的自动保存等问题,以及如何报告错误。

docs / troubleshooting

macOS 无法打开 Kalka

测试版尚未使用 Apple Developer 证书签名,所以 macOS 会阻止首次启动。

  1. 先打开一次 Kalka,让 macOS 拒绝它。
  2. 打开 “系统设置”›“隐私与安全性”。
  3. 向下滚动到关于 Kalka 的提示,点击 “仍要打开”。
  4. 用密码或触控 ID 确认。Kalka 会打开,此后 macOS 不会再为这个版本询问。

在“终端”中移除隔离标记,然后再次打开:

xattr -dr com.apple.quarantine /Applications/Kalka.app

Windows SmartScreen 拦截了安装程序

SmartScreen 会对不常见的安装程序发出警告,而测试版尚未签名。在蓝色的“Windows 已保护你的电脑”窗口中,点击 “更多信息”,再点击 “仍要运行”。

Linux

Kalka 以 AppImage 形式发布。如果双击后无法启动,请先给它加上可执行权限:

chmod +x Kalka-*.AppImage

在 Windows 和 Linux 上,Kalka 的菜单位于窗口内部,而不是系统菜单栏中。

macOS 上无法安装更新

未签名的 Kalka 在 macOS 上无法替换自身。软件更新 窗口会说明这一点,并提供 下载:把新的 .dmg 安装到“应用程序”文件夹中,覆盖旧的 Kalka。你的文档和设置都会保留。

智能体连接不上 Kalka

MCP 服务器运行在桌面应用内部,使用端口 7600。智能体要连接它,Kalka 必须处于打开状态。

  • 设置 › MCP 中显示 “端口 7600 已被其他程序占用”:有其他程序占用了这个端口,通常是还在运行的 Kalka 开发服务器或另一个 Kalka 副本。退出它,然后在设置中重新启动服务器。
  • “MCP 服务器未及时响应” 或 “无法访问 MCP 服务器”:确认 Kalka 已打开,然后重启你的智能体,让它重新连接。
  • “MCP 服务器拒绝了本地连接”:重启 Kalka,它会签发新的本地令牌。

各个智能体的连接方法参见 MCP 与 ACP。

浏览器中的自动保存请求权限

在 Chrome 和 Edge 中,网页只有在你允许的情况下才能写入磁盘上的文件。当你为从磁盘打开的文件开启自动保存时,浏览器会询问一次。如果你拒绝,Kalka 就无法自动保存,并会告诉你。Safari 和 Firefox 等不支持文件访问的浏览器,每次保存时都会下载一份副本。

版本功能无法使用

历史面板需要桌面应用、保存在你电脑上的文档,以及已安装的 Git。在 macOS 上,用 xcode-select --install 安装 Git;在 Windows 上,从 git-scm.com 安装。要在线发布版本,你的电脑必须已经能用 Git 推送到该仓库。

动效太多

设置 › 通用 的外观部分中,动画 可以跟随系统的减弱动态效果设置,或直接关闭动画。减少智能体动画 会让智能体的新图层立即出现,而不是逐块浮现。

设置中的通用标签页:语言、主题、动画、减少智能体动画、你的名字和崩溃恢复
设置 › 通用,包括动画、减少智能体动画和崩溃恢复。

找回丢失的工作

如果 Kalka 在你保存前关闭了,请重新打开它:它会提示恢复未保存的文档。参见文件与版本。

报告错误

请在 github.com/leyscore/kalka/issues 提交 issue。如果 Kalka 无法启动,它的错误页面上有一个 Report a problem 链接,会打开一个已填好版本和系统信息的 issue。请写明你做了什么、预期的结果以及实际发生了什么;附上文件或截图会很有帮助。