FAQ常见问题
Start with engine capabilities, then follow its installation, model sync and workspace guide. Pi remains experimental; engine capabilities differ.先了解各引擎能力，再按目标完成安装、模型同步和工作台配置。Pi 仍为实验版，各引擎功能并不相同。
常见问题 (FAQ)
安装问题
Q: Windows 安装时提示「Windows 已保护你的电脑」怎么办？
A: 先确认安装包来自本站官方下载页或 GitHub Release，且文件名、版本与下载页一致。确认无误后再点击「更多信息」→「仍要运行」；来源不明的安装包不要继续。
Q: macOS 提示「无法打开 ClawPanel，因为无法验证开发者」？
A: 先确认安装包来自官方发布页。确认后前往「系统设置 → 隐私与安全性」，找到 ClawPanel 并点击「仍要打开」。终端解除 quarantine 只建议在你确认包来源可信时使用。
Q: Linux 安装后找不到 OpenClaw？
A: 确保 Node.js 和 npm 在 PATH 中。如果使用 systemd 部署，需要在 service 文件中设置正确的 PATH 环境变量。
使用问题
Q: 控制台显示 Gateway 或运行时未运行？
A: 先确认当前选择的引擎。只有 OpenClaw 路径依赖 OpenClaw Gateway；Hermes、DSH、OpenCode 和 Pi 按各自页面检查运行时、日志和启停状态。Web 场景还需检查服务端 PATH、Node.js 版本、systemd 和反向代理。Gateway 进程在运行不等于 WebSocket 握手成功。
Q: 如何切换模型或渠道？
A: 「通用 → 模型渠道」保存后，需要显式同步到所选引擎；修改已同步渠道后再次同步。到目标聊天页或工作台选模型并验证完整回复，配置回读不等于真实调用成功。消息渠道按各引擎自己的入口配置。
Q: API Key 安全吗？
A: 请以你实际部署方式为准。桌面和本地 Web 部署通常将配置保存在本机或服务器本地目录；如果你把 Web 版暴露到公网，务必使用 HTTPS、访问控制和强密码。
Q: 支持哪些模型供应商？
A: 统一渠道支持多种 API 类型，但各目标的转换和认证范围不同，参见引擎与驱动。DeepSeek、Kimi、自定义网关等实际可用性取决于账号权限、模型 ID、协议和引擎版本；同步成功后仍需真实对话验证。
Q: 为什么浏览器访问的 Web 版找不到我电脑的模型或项目？
A: Web 的「本地」指面板服务器或容器。模型地址必须从服务端可达，项目目录需位于服务器或已挂载的容器目录；浏览器电脑的回环地址和磁盘不会自动共享。
Q: Pi 和 DSH 是稳定版吗？心甜Claw 是第六个驱动吗？
A: Pi 仍为实验版；DSH 默认目标 0.2.0-rc.2 是候选版，0.2.1-alpha.2 为显式测试通道，不代表上游稳定正式版。心甜Claw 是产品介绍与下载入口，不计入五个受管引擎。
网络问题
Q: npm install 时出现网络错误？
A: 可以使用国内 npm 镜像：npm config set registry https://registry.npmmirror.com
Q: GitHub 下载太慢？
A: 可以在 下载页面 使用官方下载线路；如果当前线路不可用，也可以切换到 GitHub Releases。
FAQ
Installation
Q: Windows shows SmartScreen. What should I do?
A: Only continue if the file comes from the official download page or GitHub release. Then choose More info and Run anyway.
Q: macOS says the developer cannot be verified.
A: Open System Settings, Privacy & Security, and allow ClawPanel. You can also remove the quarantine attribute if you trust the official package.
Q: Linux cannot find OpenClaw after installation.
A: Confirm Node.js and npm are in PATH. For systemd deployment, set a correct PATH in the service file.
Usage
Q: The console says Gateway or runtime is not running.
A: Check the selected engine first. Only OpenClaw depends on OpenClaw Gateway; Hermes, DSH, OpenCode and Pi have their own runtime, logs and lifecycle. For Web deployment also check server PATH, Node.js, systemd and reverse proxy settings. A running Gateway process does not prove a successful WebSocket handshake.
Q: How do I switch models or channels?
A: Save General → Model channels, then explicitly sync to the selected engine; sync again after edits. Select a model in its chat or workspace and verify a complete reply. Readback does not prove a real model call. Configure message channels in their engine-specific pages.
Q: Why does Web mode not see models or projects on my browser computer?
A: Local means the panel server or container. The model address must be reachable from that server, and projects must exist on it or in mounted container directories. Browser-side loopback addresses and disks are not shared automatically.
Q: Are Pi and DSH stable, and is XintianClaw a sixth driver?
A: Pi remains experimental. The default DSH target 0.2.0-rc.2 is a release candidate; 0.2.1-alpha.2 is an explicit test channel, not an upstream stable release. XintianClaw is a product information/download entry, not a sixth managed engine.
Q: Is my API key safe?
A: It depends on your deployment. Local desktop and self-hosted Web deployments usually store configuration locally. If Web is public-facing, use HTTPS, access control and strong credentials.
Network
Q: GitHub downloads are slow.
A: Use the official download page. Release files are served through the site download service, with R2 as the primary mirror and the site-hosted local mirror as fallback.