diff --git a/retrospectives/paperclip-xuan-20261006.md b/retrospectives/paperclip-xuan-20261006.md
new file mode 100644
index 0000000..3738d6d
--- /dev/null
+++ b/retrospectives/paperclip-xuan-20261006.md
@@ -0,0 +1,61 @@
+# 事故复盘 — Xuan paperclip 首个 agent 首跑失败(适配器默认选错 + 模型名无效)
+
+> 迭代周期:2026-10-06 单事故(装机当天)
+> 方法:Loong Workflow 复盘清单(DATA / ANAL / ACT / LOOP / SAFE)
+> 复盘人:kenyang + ZCode Agent
+> 环境:Xuan(阿里云上海 16C/30G),paperclipai 2026.1001.0,opencode_local 适配器,GLM 编程计划(glmplan)
+
+---
+
+## 1. 数据(DATA)
+
+**现象**:agent(CEO)雇用后首次唤醒连续失败 2 次(13:43、13:52),`heartbeat_runs.error_code = configuration_incomplete`。
+
+**报错原文**:
+
+```
+configuration incomplete: no Codex credentials available for managed home
+".../companies/<id>/codex-home". Sign in to Codex on the host with a ChatGPT
+subscription, or bind a per-agent OPENAI_API_KEY secret for this agent.
+```
+
+**时间线**:
+
+| 时刻 | 事件 |
+|---|---|
+| 13:42 | 界面雇用 CEO agent,适配器默认落在 codex_local |
+| 13:43 / 13:52 | 两次运行失败(缺 Codex 凭据) |
+| 15:23 | 手工改为 opencode_local,但模型填 `glm/glm-4-flash`(provider 不存在) |
+| 15:4x | 模型改为 `glmplan/glm-5.3-flash` 后运行 **succeeded**,链路恢复 |
+
+## 2. 根因(ANAL)
+
+两层叠加,且错误信息只暴露第一层:
+
+1. **雇用向导默认适配器是 codex_local**——它要求 ChatGPT 订阅凭证或 OPENAI_API_KEY;我们的大模型栈(GLM 编程计划)不在 codex 上,首跑必挂。
+2. 人工改选 opencode_local 后,**模型 ID 填错**:有效 provider 是 `glmplan`(opencode 配置文件里定义的 key),模型全名必须是 `glmplan/glm-5.3-flash`;写成 `glm/glm-4-flash` 这类想当然的名字,opencode 侧解析不到。
+3. 报错文案指向 "Codex credentials",第一次排障时容易误判为"要去搞 OpenAI 凭据",实际是适配器选错——**错误信息描述的是被选错的路径,不是该走的路径**。
+
+## 3. 行动(ACT)— 正确配置清单
+
+雇用任何 agent 时固定两步:
+
+- [ ] 适配器选 **opencode_local**(本机 GLM 栈唯一正确选项;codex_local/claude_local 需要各自订阅凭证,当前没有)
+- [ ] 模型选 **`glmplan/glm-5.3-flash`**(或 `glmplan/glm-5.3`)——严格用 `glmplan/` 前缀,不要手输 `glm/...`
+
+支撑层已就位并验证(变更时保持同步):
+
+- opencode 全局配置 `~/.config/opencode/opencode.json`(paperclip 服务用户与 root 双份):定义 glmplan provider,baseURL `https://open.bigmodel.cn/api/coding/paas/v4`(编程计划专用端点;普通 `/api/paas/v4` 端点对编程计划 key 报余额不足),key 按服务器各用各的(Xuan/Loong 各一把团队 key)
+- opencode 默认模型已设 `glmplan/glm-5.3-flash`(不带 `-m` 裸跑 `opencode run` 验证过)
+- 全局指令 `~/.config/opencode/AGENTS.md`:默认简体中文工作
+
+## 4. 预防(LOOP / SAFE)
+
+1. **把"适配器+模型"写进雇用入口的可见提示**:任何人在界面雇 agent 前先看本清单第 3 节两行,可消除该类事故。
+2. **报错先查配置归属,再按报错文案行动**:configuration_incomplete 类错误先 `select adapter_type, adapter_config->>'model' from agents` 对一眼,别急着按报错去申请凭据。
+3. **模型名以 `opencode models` 输出为准**:provider 前缀来自 opencode 配置,不靠记忆猜。
+4. 验证手段:`curl :3100/api/agents/<id>/wakeup` 触发一次按需运行,查 `heartbeat_runs.status`,succeeded 即链路通。
+
+---
+
+*证据:本机 postgres `heartbeat_runs` 表两次 failed 记录与修复后 succeeded 记录;journalctl `paperclipai` 用户单元日志。*