常见问题

找到你需要的答案，快速解决使用中的疑问。

安全与隐私

我的 API Key 安全吗？

API Key 仅保存在你的本地电脑上（存储在 ~/.openclaw/ 目录下），不会上传到任何服务器。即使你开启了云端模式，你的本地 API Key 也不会被同步。你可以在桌面端的「安全设置」页面随时查看和管理所有密钥。

我的对话数据存在哪里？

默认情况下，所有对话数据仅保存在你的本地电脑上。如果你登录了云端账号，对话记录会加密同步到云端，方便多设备使用。云同步是完全可选的，你可以随时关闭。

SPA 会收集我的个人信息吗？

SPA 不会收集你的个人信息。应用运行完全在本地，不会追踪你的使用行为。云端服务仅在你主动注册和登录后才会工作，且仅存储必要的账户信息和你选择同步的数据。

使用云端模式时，我的对话内容会被看到吗？

云端模式下，你的对话内容会通过我们的代理服务器转发给 AI 服务商（如 OpenAI、Anthropic 等）。我们不会保存或查看你的对话内容，仅记录用量用于计费。如果你对隐私有更高要求，建议使用本地模式，直接用自己的 API Key 与服务商通信。

与市面 OpenClaw 的区别

SPA 和 OpenClaw 是什么关系？

OpenClaw 是一个优秀的开源 AI 智能体网关引擎，SPA 基于 OpenClaw 构建。安装 SPA 桌面端时会自动安装 OpenClaw 引擎，你无需手动安装任何依赖。SPA 在 OpenClaw 之上提供了精美的图形界面、云端账户、一键安装、自动更新等功能。

SPA 和市面上其他 OpenClaw 云端版本有什么区别？

市面上的 OpenClaw 云端版本通常将 Gateway 部署在云服务器上，适合开发者和团队使用。SPA 的核心区别是：1）OpenClaw Gateway 运行在你自己的电脑上，数据完全本地化；2）提供精美的桌面端界面，无需命令行操作；3）有云端账户系统，支持免 Key 使用和数据同步；4）一键安装，无需配置 Node.js 等开发环境。

SPA 是免费的吗？

SPA 桌面端完全免费下载和使用。使用本地模式时，你只需向 AI 服务商（如 OpenAI）支付 API 调用费用。使用云端模式时，你需要购买云端额度。两种模式可以随时切换。

常见使用问题

如何切换语言和主题？

在桌面端的「设置」页面，你可以切换界面语言（中文/英文）和主题（浅色/深色/跟随系统）。

支持哪些 AI 模型？

SPA 支持几乎所有兼容 OpenAI API 格式的 AI 模型，包括但不限于：OpenAI（GPT-4o、GPT-4o-mini 等）、Anthropic（Claude 3.5 Sonnet、Claude 3 Opus 等）、DeepSeek（DeepSeek-V3、DeepSeek-R1 等）、Google Gemini、Groq、Mistral、通义千问、Moonshot、硅基流动（SiliconFlow）、OpenRouter 等。如果你的服务商提供 OpenAI 兼容格式的 API，只需填入自定义 Base URL 即可接入。

如何创建 AI 助手？

进入「AI 助手」页面，点击「创建助手」。填写名称、选择模型、编写系统提示词来定义助手的角色和能力。你可以创建多个助手用于不同场景（如编程、写作、翻译等），在对话时随时切换。

如何使用工具和技能？

进入「AI 助手」→ 编辑某个助手 → 「工具」区域，开启你需要的内置工具（如文件读写、网页搜索、代码执行等）。也可以通过 ClawHub 市场安装第三方技能。助手在对话中会根据需要自动调用已开启的工具。

飞书机器人不回复消息怎么办？

请逐项检查：1）飞书开发者后台是否已发布最新版本（这是最常见的原因）；2）事件订阅是否选择了「长连接」模式；3）im.message.receive_v1 事件是否已添加；4）im:message 和 im:message:send_as_bot 权限是否已开通；5）SPA 桌面端是否正在运行且 Gateway 已连接。

环境搭建问题

安装时提示网络错误怎么办？

SPA 在安装过程中需要下载 Node.js 和 OpenClaw 引擎。如果网络不佳，应用会自动尝试使用国内镜像。你也可以在「设置」→「代理」中手动配置 HTTP 代理地址来加速下载。

需要自己安装 Node.js 吗？

不需要。SPA 桌面端会自动下载和管理一个独立的 Node.js 运行环境，不会与你系统中已安装的 Node.js 冲突。

数据目录在哪里？

SPA 有两个数据目录：1）引擎数据目录 ~/.openclaw/（Windows: C:\Users\你的用户名\.openclaw\）— 存放 OpenClaw 引擎、Gateway 配置和对话数据等；2）应用设置目录 ~/Library/Application Support/spaclaw（macOS）或 %APPDATA%\spaclaw（Windows）— 存放桌面端应用设置、便携版 Node.js/Python 等。程序本体安装在操作系统的默认应用程序位置（macOS: /Applications/SPA.app，Windows: 默认安装路径）。

故障排查

遇到问题实在解决不了怎么办？

如果遇到无法解决的问题，可以尝试以下步骤：1）完全退出 SPA（包括系统托盘中的图标）；2）删除引擎数据目录 ~/.openclaw/（Windows: C:\Users\你的用户名\.openclaw\）；3）删除应用设置目录：macOS 上是 ~/Library/Application Support/spaclaw，Windows 上是 %APPDATA%\spaclaw；4）到官网下载最新版本重新安装。这会重置所有配置和数据，相当于全新安装。

Gateway 一直显示「未连接」怎么办？

1）检查是否有其他程序占用了 18789 端口；2）尝试在「设置」中手动重启 Gateway；3）查看「调试」页面中的日志信息，通常会有详细的错误提示；4）如果依然无法解决，尝试按上述方法清除数据目录后重装。

应用启动后白屏怎么办？

白屏属于低概率异常，正常使用一般不会出现。若极少数情况下出现，可尝试：1）完全退出后重新启动；2）若仍反复白屏，同时删除 ~/.openclaw/ 和应用设置目录（macOS: ~/Library/Application Support/spaclaw，Windows: %APPDATA%\spaclaw）后重启，应用会重新进入设置向导。

如何完全卸载 SPA？

完全卸载需要三步：1）卸载 SPA 应用程序（Windows: 设置 → 应用 → 找到 SPA 卸载；macOS: 将 SPA.app 从应用程序文件夹移到废纸篓）；2）删除引擎数据目录 ~/.openclaw/（Windows: C:\Users\你的用户名\.openclaw\）；3）删除应用设置目录：macOS 上是 ~/Library/Application Support/spaclaw，Windows 上是 %APPDATA%\spaclaw。三步完成后即为完全卸载，不会留下任何残留数据。

macOS 如何卸载 OpenClaw 并重新走安装向导？

如果想重新走安装向导，打开终端依次执行：rm -rf ~/.openclaw 与 rm -rf ~/Library/Application\ Support/spaclaw。第一条删除 OpenClaw 引擎、Gateway 配置和对话数据，第二条删除桌面端应用设置（其中包含安装向导完成标记，不删除此目录将无法重新进入向导）。重新打开 SPA 后会自动进入安装向导。如果还想完全卸载 SPA 桌面端本身，将 /Applications/SPA.app 拖入废纸篓即可。