# ❓ 常见问题（FAQ）

> 汇总安装和日常使用中最高频的问题。没找到答案可以在 [GitHub Issues](https://github.com/whiteguo233/OpenBiliClaw/issues) 提问，或加 README 里的用户交流群。

## 安装

### macOS 打开桌面安装包提示「无法验证开发者」或「未经安全验证」？

当前 Release 是 ad-hoc signed、未 notarized 的实验性预发布。先把应用拖进「应用程序」，再右键 / Control-click `OpenBiliClaw.app` →「打开」→ 在弹窗里再点「打开」；也可以到「系统设置 → 隐私与安全性」点击「仍要打开」。

### macOS 提示「OpenBiliClaw.app 已损坏，无法打开」？

通常是下载隔离属性导致。确认安装包来自本项目 [Releases](https://github.com/whiteguo233/OpenBiliClaw/releases/latest) 后运行：

```bash
APP="/Applications/OpenBiliClaw.app"
xattr -dr com.apple.quarantine "$APP"
```

然后再次打开应用。

### Windows 安装时弹出 SmartScreen 警告？

点「更多信息 → 仍要运行」。安装包未购买代码签名证书，属预期现象。

### Firefox 安装 `-firefox.zip` 提示「未通过验证 / could not be verified」？

`-firefox.zip` 是未签名开发包，只用于 `about:debugging` 临时加载。普通 Firefox 用户请优先安装 release 里的已签名 `openbiliclaw-extension-v*-firefox.xpi`（若该版本提供）；临时加载方式见 README 的 Firefox 折叠说明。

### Chrome 应用商店的版本比 GitHub Releases 旧？

正常。商店版受审核排期影响，通常滞后几天到一两周。想第一时间拿到新功能，从 [Latest Release](https://github.com/whiteguo233/OpenBiliClaw/releases/latest) 下载 zip 手动安装即可（缺点是需要手动更新）。

### 想用 Docker 部署后端？

不需要克隆源码：下载一个 compose 文件启动预构建镜像（自带 Ollama embedding sidecar），再打开 `http://127.0.0.1:8420/setup/` 完成初始化：

```bash
curl -fsSLO https://raw.githubusercontent.com/whiteguo233/OpenBiliClaw/main/docker-compose.prebuilt.yml
docker compose -f docker-compose.prebuilt.yml up -d
```

升级到最新版：`docker compose -f docker-compose.prebuilt.yml pull` 再 `up -d`。源码构建、代理与排查见 [Docker 部署指南](docker-deployment.md)。

## 连接与初始化

### 插件显示「后端还没开张」/ 连不上后端？

按顺序排查：

1. 后端在跑吗？桌面包看菜单栏 / 托盘图标；源码安装跑 `openbiliclaw start`。
2. 浏览器访问 `http://127.0.0.1:8420/api/health`，有 JSON 返回说明后端正常。
3. 插件默认连 `127.0.0.1:8420`；如果你改过端口，在插件设置里同步修改。
4. 后端启动后插件会在 1 秒内自动重连，不需要手动刷新。

### 初始化需要哪些前置条件？

三样：① 至少一个已登录且能拉到信号的内容平台（B 站默认勾选，可换成小红书 / 抖音 / YouTube / X / 知乎 / Reddit）；② 一个可用的 LLM provider（自己的 API Key）；③ embedding 服务（桌面包内置，其他安装方式可用 Ollama）。引导初始化会先真实验证 LLM 和 embedding 再开跑，不会硬跑出空画像。

### 不想为 embedding 单独配 API Key？

装一次 [Ollama](https://ollama.com/download)，然后运行 `openbiliclaw setup-embedding`，向导会自动拉取 `bge-m3`（约 568MB，CPU 可跑）并写入配置。桌面安装包已内置，无需额外操作。

### 手机打不开移动端 Web（`/m/`）？

1. 手机和电脑要在同一个局域网。
2. 后端要绑定 `0.0.0.0`：桌面包默认如此；源码安装检查 `config.toml` 的 `[api].host`（`0.0.0.0` = 同时监听可用的 IPv4 / IPv6，`127.0.0.1` = 仅本机）。
3. 用插件顶部手机图标的二维码打开最稳，它会优先展示电脑的 IPv4 局域网地址；没有可用 IPv4 时会回退到 IPv6，并自动生成 `http://[IPv6]:8420/m/` 格式的地址。

## 更新与数据

### 后端设置里没有「立即应用」更新按钮？

「立即应用」只对源码安装（`install_mode="git"`）显示。桌面安装包用户请直接从 [Latest Release](https://github.com/whiteguo233/OpenBiliClaw/releases/latest) 下载新版安装包覆盖安装，数据目录不受影响。

### 点「立即应用」提示更新未开始 / 被拒绝？

后端自动更新有安全守卫：本地有未提交改动（`dirty_worktree`）、remote 不受信任（`untrusted_remote`）、分支无法快进（`branch_not_fast_forwardable`）等情况会拒绝更新，插件会展示具体原因。源码安装用户可进仓库目录手动处理后重试（如 `git status` 清理本地改动）。

### 点「立即应用」后显示「更新后依赖安装失败」？

旧更新器会把仓库里存在 `uv.lock` 错当成系统已安装 `uv`：使用官方 pip/venv fallback 安装时，源码已经快进到新 tag，随后却因找不到 `uv` 停在重启前，所以卡片仍显示旧进程版本。包含修复的新版本会先探测真实可用工具，无 `uv` 时自动改用当前虚拟环境的 pip，并在失败时显示工具与退出码摘要。

已卡住的安装需要**人工重启一次后端**加载磁盘上的新源码；若要一次性修复依赖环境，先停止当前后端，再重跑原来的一句话安装命令（`config.toml`、`data/` 与 Cookie 都会保留）。也可在安装目录手动执行：有 uv 时运行 `uv sync`；pip/venv 安装运行 `.venv/bin/python -m pip install -e .`（Windows：`.\.venv\Scripts\python.exe -m pip install -e .`），然后用同一个 Python 执行 `-m openbiliclaw.cli start`。

### 一直提示「git 远端不在允许列表，更新被阻止」？

老版本（≤0.3.153）的允许列表按**精确字符串**匹配 `origin` 地址，`git clone` 时少写 `.git` 后缀、或用了与列表拼法不一致的 HTTPS/SSH 地址都会被永久拦住——而且被拦住的安装无法通过自动更新拿到修复版本，需要一次手动解锁（进入安装目录执行）：

```bash
git remote -v                      # 先看实际的 origin 地址
git pull --ff-only                 # 手动拉一次最新代码即可解锁
# 或者把 origin 改成官方地址后重试自动更新：
git remote set-url origin https://github.com/whiteguo233/OpenBiliClaw.git
```

新版本起允许列表按规范化形式比较（`.git` 后缀可省、HTTPS/SSH 拼法等价、大小写不敏感），正常克隆不会再触发；通过 GitHub 镜像克隆的安装把镜像地址加入 `config.toml` 的 `[scheduler] auto_update_allowed_remotes` 即可。被拒绝时后端日志会打出实际的 remote 地址和修复命令。

### 我的数据存在哪里？会上传吗？

所有数据存在本机的一个 SQLite 文件里，数据目录为 `~/OpenBiliClaw`（macOS / Linux）或 `%USERPROFILE%\OpenBiliClaw`（Windows），升级和卸载不会动它。插件不会把数据发送到 OpenBiliClaw 开发者运营的服务器；只有你配置了云端 LLM / embedding 时，相关内容才会按你的配置发给对应服务商。详见 [隐私政策](privacy.md)。

### 配置文件写坏了导致启动失败？

桌面包（v0.3.152+）会自动把坏的 `config.toml` / `config.local.toml` 备份为 `*.invalid`、重建默认配置并打开 `/setup/` 重新初始化；`data/` 不会被删除。源码安装可对照 `config.example.toml` 手动修复。