2026 年 OpenClaw 首次 onboard 后仍异常：credentials、环境变量与模型提供方切换的最小闭环与分层排障手册
onboard 把入口脚本跑通不等于生产可用：运行网关的 Unix 用户能否读到同一 ~/.openclaw/credentials/、systemd EnvironmentFile 是否在守护进程启动前注入、以及 模型 ID 前缀与当前选中的提供方是否一致，决定「CLI 能 chat、网关里却 401/429」的经典分叉。本文与《官方快速排障阶梯》互补：彼文先钉 RPC/探测，本文钉凭证与提供方层；读完再按需跳转《pairing 断开》《split brain》《Docker Compose 令牌》。
目录 (TOC)
1. 三类分叉：HOME 漂移、空 credentials、提供方字符串
HOME 漂移：终端里 onboard 写在用户 A 的 home，launchctl 却以用户 B 启网关，credentials 路径对 A 存在、对 B 为空。
空目录误读：~/.openclaw/credentials 存在但无密钥文件，doctor 可能只给弱提示，模型调用才爆 401。
提供方前缀：配置里模型串与 openclaw models status 实际路由不一致，日志出现 provider mismatch 类签名。
- 先确认谁在跑网关，再谈文件权限。
- 再确认env 与 JSON谁覆盖谁。
- 最后再拆429 与通道无回复（见《通道无回复》）。
2. 决策矩阵：API Key、OAuth、多提供方并存
| 维度 | API Key 文件落盘 | OAuth / 订阅桥接 | 多提供方轮换 |
|---|---|---|---|
| 密钥落点 | credentials 目录 + chmod 600 | 令牌刷新与回调 URL | 分文件或分 env 前缀 |
| 守护进程友好 | EnvironmentFile 显式列路径 | 需保证刷新 job 同用户 | 路由表要单一真相 |
| 排障顺序 | 先 ls 再 doctor | 先 OAuth 日志再模型 | 先 models status 再 channels |
3. How-to：onboard 后七步最小闭环
# 1) 确认网关进程用户与 HOME
ps aux | grep -i openclaw
echo "$HOME"
ls -la ~/.openclaw/credentials/- 把 User= 与 plist/unit 里 WorkingDirectory 写进变更单。
- 对 credentials 文件做 最小权限，避免仓库误提交。
- 用 同一 shell 跑
openclaw status与openclaw gateway status，避免 PATH 漂移。 - 改 env 后 完整重启网关，热重载不总刷新密钥句柄。
- 切提供方时只改最小 diff：模型串、路由块、credentials 文件名三处对齐。
- 跑
openclaw doctor并保存脱敏输出。 - 再按《官方阶梯》补
gateway probe与channels探测收据。
# 2) systemd 示例：显式注入凭据目录（示意）
Environment=OPENCLAW_HOME=/home/oc/.openclaw4. 分层排障与日志里该搜什么
顺序：status → gateway status → doctor → 日志搜 401、403、429、credential、provider。若 RPC 已绿仍无回复，回到《通道无回复》文拆插件双开关。
与 split brain 的边界：若 gateway status --deep 显示 CLI 与服务二进制路径不一致，先修 PATH 再回本文凭证层。
与 安装路径 文的关系：若 which openclaw 与守护进程 unit 内路径不同，先对齐《安装方式对比》再谈 credentials，否则会出现「手动能跑、服务永远读旧配置」的假阳性。
5. 可引用数据：时间线与工单字段
工单应附：运行用户、credentials inode 列表、doctor 摘要、模型串一行、最近一次完整重启时间。回滚窗口用「上一次已知 good 的配置 tarball」比口头描述可靠。
6. FAQ
问：Docker 里 credentials 挂卷？答：见《Docker Compose 令牌》卷的 uid 映射。
问：能否跳过 doctor？答：不建议；它会聚合多数低级错误。
7. 总结与远程 Mac 托管收束
凭证层排通后，网关才能在可重复环境里稳定调用模型与通道。
笔记本休眠、多用户 HOME 与家庭宽带上行仍会让「排障正确、运行仍抖」。
若要把7×24 网关 + 可审计目录做成默认能力，可看 SFTPMAC 远程 Mac 与帮助页，把 OpenClaw 与产物同步放在同一托管面。