适用场景：在 员工 onboarding 或 admin 运营手册 上某一步卡住、报错、看到非预期空状态。下方按角色 (Tabs) + 场景 (AccordionGroup) 排版，先按身份对号入座再找症状。
- 员工视角
- Admin 视角
装机 / 启动
首次启动报 "文件已损坏" / "来自身份不明的开发者"
首次启动报 "文件已损坏" / "来自身份不明的开发者"
macOS Gatekeeper 拦截未公证 dmg — Terminal 跑：然后重新启动 DOSIA。
DOSIA 启动后无 "ByteSpike 共享" provider
DOSIA 启动后无 "ByteSpike 共享" provider
按顺序排查（最常见在前）：
- 企业模式没切 → 进 Settings → Deploy Mode，确认显示「企业版」非「个人版」
- 企业服务地址 typo → 同页核对地址，admin 给的字符串复制要完整（默认
http://122.51.0.230:3012） - admin 没 publish token → 联系 admin 在 DOSIA Settings → ByteSpike tab 顶部应有「已配置 · 员工启动时自动拉取」绿条；如缺，admin 重新 publish 一次
- 员工 lark OAuth 过期 → DOSIA Settings → “我的账户” 看 SSO 状态；过期就点退出 + 重登
- 全做完仍无 → 截图 lark 群 @ByteSpike Ops
lark 授权后 DOSIA 卡死 / 反复登录
lark 授权后 DOSIA 卡死 / 反复登录
清掉本地 auth state 重启：重启 DOSIA 触发新 OAuth。如还不行，截图 + lark 私聊 admin。
模型权限
对话框报 "无权限" / "model not allowed"
对话框报 "无权限" / "model not allowed"
Admin 没给你的组开通该模型权限。联系 admin 在 llm.bytespike.ai/admin → Users → 你的账户 → Allowed Models 勾上对应模型组。
测试连接 modelCount = 0（DOSIA 配置面板）
测试连接 modelCount = 0（DOSIA 配置面板）
DOSIA Settings → ByteSpike tab 测试连接时显示
modelCount: 0：- 之前 W1/W2 修过
/admin/available-models401 → 现在用/me/available-models，对正常用户应该 ≥ 1 - 仍为 0 → admin 没给 user 绑 group。按上一条联系 admin 处理
- token 本身有问题 → 见下「测试连接报 401」
图片识别报错 (vision)
图片识别报错 (vision)
选的模型不含 vision capability。在 console.bytespike.ai/zh/models 「模型库」找带 vision 标签的（如 Claude Sonnet 4.6、GPT-5-4、Gemini 3.1 Pro），切回 DOSIA 选这些模型再重试。
图像 / 视频生成 tab 看不到
图像 / 视频生成 tab 看不到
多模态权限是独立 grant 的（独立于文本模型）。Admin 在 llm.bytespike.ai/admin → 你的组 → 加上
image / video capability，DOSIA 重启即可看到对应工具。余额 / 测试
对话框报 "余额不足"
对话框报 "余额不足"
组织钱包余额耗尽。截图 + 联系 admin，admin 在 console.bytespike.ai/billing 充值后立即恢复。
测试连接报 401 (token invalid)
测试连接报 401 (token invalid)
Token 失效。回 console.bytespike.ai/keys 重新创建一个 key，粘贴到 DOSIA Settings → ByteSpike tab → 重测连接。如新 key 仍 401 → 联系 admin 检查你的 user 状态（可能被暂停了）。
还是搞不定？
- 员工：lark 群 @ByteSpike Ops
- Admin / OP：lark 私聊 W1，或者直接 SSH lisahost (
38.78.146.204) + 122.51 backend 自查 - 集成 issue：GitHub Issues（仓库内部，需登录）