docs: add upgrade recovery guide and troubleshooting table

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -136,12 +136,58 @@ Add to your `~/.zshrc`:
 bash ~/.openclaw/projects/claude-proxy/start.sh 2>/dev/null
 ```
 
+## OpenClaw 升级后恢复
+
+OpenClaw 升级（`npm update -g openclaw`）**不会覆盖** `~/.openclaw/openclaw.json` 用户配置。但如果 claude-local 模型不可用，按以下步骤排查：
+
+### 快速诊断
+
+```bash
+# 1. 检查 proxy 是否运行
+curl http://127.0.0.1:3456/health
+# 应返回: {"status":"ok"}
+
+# 2. 检查 Claude CLI 是否正常
+claude -p "hello" --model sonnet --output-format text
+# 应返回文本回复
+
+# 3. 检查 OpenClaw 配置
+cat ~/.openclaw/openclaw.json | grep -A3 claude-local
+```
+
+### 常见故障与恢复
+
+| 症状 | 原因 | 恢复方法 |
+|------|------|---------|
+| Agent 不回复，proxy 无日志 | Gateway 未加载 claude-local provider | 检查 `openclaw.json` 中 `models.providers.claude-local` 配置 |
+| Proxy 报 `exit 1` | Claude CLI 未登录或 token 过期 | 运行 `claude login` 重新认证 |
+| `🔑 unknown` 显示 | 正常现象（无 API key，走 OAuth） | 不影响功能，可忽略 |
+| `/status` 显示 Context 0% | 消息未到达 proxy（SSE 格式问题） | 确保 proxy 是最新版本，支持 streaming |
+| Gateway 报 `invalid api type` | OpenClaw 新版本改了 API 类型名 | 检查 `api` 字段是否仍为有效值（如 `openai-completions`） |
+| Proxy 启动但 `EADDRINUSE` | 端口 3456 被占用 | `lsof -i :3456` 找到并杀掉旧进程 |
+
+### 一键恢复
+
+```bash
+cd ~/.openclaw/projects/claude-proxy   # 或你 clone 的位置
+git pull                                # 拉取最新版本
+node setup.mjs                          # 重新配置 OpenClaw + 启动 proxy
+openclaw gateway restart
+```
+
+### 升级前备份（推荐）
+
+```bash
+cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
+```
+
 ## Notes
 
 - Cost shows as $0 because billing goes through your Claude subscription
 - The `🔑` field in `/status` may show the dummy auth key — this is normal
 - Each request spawns a `claude -p` process; concurrent requests are supported
 - The proxy must run on the same machine as the Claude CLI (uses local OAuth)
+- 同一个 Claude 账号可在多台机器上使用（共享用量额度）
 
 ## License