macOS 无法打开 Kalka
测试版尚未使用 Apple Developer 证书签名,所以 macOS 会阻止首次启动。
- 先打开一次 Kalka,让 macOS 拒绝它。
- 打开 “系统设置”›“隐私与安全性”。
- 向下滚动到关于 Kalka 的提示,点击 “仍要打开”。
- 用密码或触控 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。请写明你做了什么、预期的结果以及实际发生了什么;附上文件或截图会很有帮助。