常见问题

本机使用：http://localhost:9899（控制台）。桌面客户端：客户端自带界面，后端默认监听 9876。 团队版：走门户地址，登录后自动进入控制台。

确认改的是运行中实例实际读取的那份配置（源码部署是 config.json；Docker 是环境变量）。 改完需要重启服务（cow restart 或 systemctl restart）。

默认只监听 127.0.0.1。要公网访问需要 ① 改 web_host 或用 nginx 反代 ② 放行防火墙/安全组 ③ 设好 web_password。推荐用反代，不要直接把端口暴露出去。

常见于 nginx 反代漏了 Upgrade / Connection 头（流式输出与 WebSocket 依赖它）。 另外把 proxy_read_timeout 调大、proxy_buffering 关掉。

不必。模型可一键切换，也支持任何兼容 OpenAI 协议的私有化/网关服务（见自定义模型）。

依次检查：Key 是否填对、账户是否有余额、是否开了对应模型的权限、 国内服务器到该厂商的网络是否可达（必要时配置代理）。

配置读取接口可能返回明文 Key（这是上游设计）。所以不要把它直接挂到公网， 加固方式见公网访问加固。

团队版由平台统一提供模型能力，成员不必各自配 Key； 桌面版是各人自己的运行环境，默认需要各自配置（也可由管理员下发预置版本）。

分两处：数据目录（配置、日志，桌面版为 %USERPROFILE%\.cow；服务器版为其等价目录） 与工作空间（对话、记忆、知识库、技能、产出文件，默认 ~/cow）。 备份这两处 = 备份了全部。

停服务 → 打包数据目录 + 工作空间 → 新机器上装好程序 → 放回两个目录 → 启动。 换机器时注意路径变化（配置里写死了工作空间绝对路径时要一起改）。

记忆索引依赖 SQLite 的 FTS5 trigram 分词器（需 SQLite ≥ 3.34）。 低版本会静默降级成模糊匹配，只在日志里留一行警告。升级 SQLite 或让 Python 使用新版 sqlite 模块即可。

对话与记忆都是本地文件（Markdown 等可读格式），直接复制即可； 知识库本身就是一个 Markdown wiki，可以整体拷走。

不互通。桌面版数据在你自己电脑上，网页版在工作台。 需要团队共享的内容请放在工作台的知识库里。

客户端内「检查更新」→ 下载新包 → 解压替换。绿色版没有安装器，更新=换一个目录。 详见桌面客户端更新。

未签名的可执行程序常见现象，可先用下载页给出的 SHA256 自行校验。

九成是没有 HTTPS：浏览器只在 HTTPS 或 localhost 下允许麦克风。 其次是权限被拒或设备不可用。

检查 text_to_voice 引擎的 Key、voice_reply_voice / always_reply_voice 是否开启。 详见语音合成。

音色 ID 与引擎不匹配时会静默回退，不报错。核对 ID 与引擎属于同一家服务商。

源码/服务器版：git pull 后重启（有自动更新脚本的按脚本走）； 桌面版：客户端内检查更新，或下载新包替换目录。

会——如果定制是"直接改源码里的文字/图标"，git checkout 会还原它。 正确做法是把定制脚本化、声明化，更新后重跑一遍并校验。

保留更新前的代码版本与数据快照；更新脚本应当在健康检查失败时自动回滚， 并把失败原因写进日志（而不是静默变成"起不来了"）。