---
title: "故障排除 | Kalka docs"
description: "解决 macOS 和 Windows 的首次启动警告、Linux、更新、MCP 端口、浏览器中的自动保存等问题，以及如何报告错误。"
url: https://kalka.design/zh/docs/troubleshooting
language: zh-Hans
---

## macOS 无法打开 Kalka

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

- 先打开一次 Kalka，让 macOS 拒绝它。

- 打开 **“系统设置”›“隐私与安全性”**。

- 向下滚动到关于 Kalka 的提示，点击 **“仍要打开”**。

- 用密码或触控 ID 确认。Kalka 会打开，此后 macOS 不会再为这个版本询问。

**提示“‘Kalka’已损坏，无法打开”？**这是下载的文件被隔离了，Kalka 并没有损坏。

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

```
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](https://kalka.design/zh/docs/mcp)。

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

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

## 版本功能无法使用

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

## 动效太多

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

_设置中的通用标签页：语言、主题、动画、减少智能体动画、你的名字和崩溃恢复_

设置 › 通用，包括动画、减少智能体动画和崩溃恢复。

## 找回丢失的工作

如果 Kalka 在你保存前关闭了，请重新打开它：它会提示恢复未保存的文档。参见[文件与版本](https://kalka.design/zh/docs/files-versions)。

## 报告错误

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