常见问题
安装与启动
macOS 提示”无法验证开发者”
macOS 的安全机制会阻止未经 Apple 签名的应用。解决方法：
- 打开「系统设置」→「隐私与安全性」
- 在页面下方找到被阻止的旗鱼应用
- 点击「仍要打开」
或者在终端中执行：
xattr -cr /Applications/SailFish.app
Windows 提示”Windows 已保护你的电脑”
点击「更多信息」→「仍要运行」即可。
应用闪退或无法启动
- 尝试删除配置文件后重启：
- macOS:
~/Library/Application Support/SailFish/ - Windows:
%APPDATA%/SailFish/ - Linux:
~/.config/SailFish/
- macOS:
- 查看日志文件定位问题（同目录下的
logs/文件夹）
AI 相关
AI 不回复或一直”思考中”
- 检查 AI 模型配置是否正确（API Key、API 地址、模型名称）
- 检查网络连接（海外模型可能需要代理）
- 查看日志中是否有错误信息
- 尝试切换到另一个模型测试
回复质量不好
- 尝试更换模型（Claude、GPT-4o 等通常效果更好）
- 提供更详细的需求描述
- 在对话中提供更多上下文信息
Token 超限错误
当前对话上下文太长。可以：
- 清空对话后重新开始
- 在设置中增大上下文长度限制
- 把复杂任务拆分成多次对话
SSH 连接
连接超时
- 确认服务器 IP 和端口正确
- 检查本机网络是否能 ping 通服务器
- 确认服务器的 SSH 服务正在运行
- 检查防火墙是否放行了 SSH 端口
密钥认证失败
- 确认选择了正确的私钥文件
- 确认服务器的
~/.ssh/authorized_keys中包含对应的公钥 - 确认私钥文件权限正确（
chmod 600 ~/.ssh/id_rsa） - 如果私钥有密码短语，确认输入正确
中文乱码
- 在终端设置中确认编码为 UTF-8
- 检查服务器的
LANG环境变量是否设为en_US.UTF-8或zh_CN.UTF-8
远程访问
IM 机器人不回复
- 确认旗鱼正在运行
- 确认 IM 连接状态为「已连接」
- 群聊中需要 @机器人
- 检查 AI 模型配置是否正常
飞书/钉钉连接失败
- 确认凭证正确（注意不要有多余空格）
- 飞书需要先在旗鱼中连接再提交审核
- 钉钉确认已开启 Stream 模式
- 检查网络是否能访问对应平台的服务器
Web 远程无法访问
- 确认网关已启用
- 确认端口未被防火墙阻挡
- 同一网络下尝试用 IP:端口 访问
- 外网访问需要配置端口转发或内网穿透
文件和 SFTP
文件上传失败
- 检查目标目录是否有写入权限
- 确认磁盘空间充足
- 大文件上传可能需要更长时间，请耐心等待
编辑器打开文件为空
- 可能是二进制文件，内置编辑器只支持文本文件
- 尝试用其他方式查看（右键 → 下载到本地）
性能
应用占用内存较高
旗鱼基于 Electron 框架，基础内存约 200-300MB。如果内存异常高：
- 关闭不需要的终端标签页
- 清理长时间未使用的 SSH 连接
- 重启应用
终端输出卡顿
- 减小终端的滚动缓冲区大小
- 避免在终端中输出超大量文本（如
cat大文件） - 对于大量输出，建议重定向到文件后再查看