# 小唯控制台 API 参考 (v2)

> 控制台运行于 `http://127.0.0.1:3737`，Flask 后端 `app.py`，端口 3737

## 完整端点清单

### 聊天（Matrix 多 Agent）
| 端点 | 方法 | 参数 | 说明 |
|------|------|------|------|
| `/api/chat-agents` | GET | — | 返回可用账号列表 [{id, label}]，从 `~/matrix-tokens.json` 读取 |
| `/api/chat-send` | POST | `{sender, message}` | 发消息，sender=muchen/xiaowei/xiaoxue |
| `/api/chat-history` | GET | `?token=muchen&since=xxx&limit=50` | 拉取消息，token 指定用谁的 token |

**token 路径**：`/home/muc/matrix-tokens.json`（不是 `~/.hermes/memory/`）

**token 格式**（嵌套对象）：
```json
{ "muchen": { "user_id": "...", "token": "syt_xxx", "room_id": "..." }, ... }
```
读取时：`token = tokens[sender].get("token", "") if isinstance(tokens.get(sender), dict) else tokens.get(sender, "")`

### 网关
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/gateway-status` | GET | Gateway 运行状态 |
| `/api/gateway-restart` | POST | 重启 Gateway |

### OpenClaw
| 端点 | 方法 | 参数 | 说明 |
|------|------|------|------|
| `/api/openclaw-status` | GET | — | 安装状态/版本/gateway_mode |
| `/api/openclaw-install` | POST | `{version}` | npm install -g opencode-ai@version |
| `/api/openclaw-restart` | POST | — | pkill + 重拉 bridge |
| `/api/openclaw-models` | GET | — | models.json 内容 |
| `/api/openclaw-config` | GET | — | 读取 openclaw.json（含表单字段） |
| `/api/openclaw-config` | POST | `{gateway, model, providers, channels}` | 保存 openclaw.json |

### 系统
| 端点 | 方法 | 参数 | 说明 |
|------|------|------|------|
| `/api/system-update` | POST | `{action, install_source, dry_run}` | status/update/restore/install/self-check |
| `/api/self-check` | POST | — | 自检（5分钟缓存） |
| `/api/backup` | POST | — | 执行全量备份 |

### 飞书
| 端点 | 方法 | 参数 | 说明 |
|------|------|------|------|
| `/api/feishu-config` | GET | — | 读取状态 |
| `/api/feishu-config` | POST | 四个字段 | 保存 + 验证 + 重启 xiaoxue daemon |

## system-update action 参数

```python
POST /api/system-update
{
  "action": "install",          # 全新安装
  "install_source": "",         # 自定义下载源（留空用内置）
  "dry_run": True                # 仅测试连接
}
```

## openclaw-config POST 允许字段

只允许安全字段，写入时 deep-merge 到现有配置：
```python
allowed = {
    "gateway": body.get("gateway", {}),
    "model": body.get("model", {}),
    "providers": body.get("providers", {}),
    "channels": body.get("channels", {}),   # 含 channels.feishu
}
```

## 文件位置

| 文件 | 路径 |
|------|------|
| Flask 后端 | `~/mc/小唯/Hermes-恢复包/gui/app.py` |
| 前端 UI | `~/mc/小唯/Hermes-恢复包/gui/templates/index.html` |
| 启动脚本 | `~/mc/小唯/Hermes-恢复包/gui/start.sh` |
| systemd service | `~/mc/小唯/Hermes-恢复包/gui/xiaowei-gui.service` |
| PID 文件 | `/tmp/xiaowei-gui.pid` |
| 日志 | `/tmp/xiaowei-gui.log` |

## opencode subprocess 陷阱

```python
# ❌ 错误：shell=True + 列表参数会 hang
subprocess.run(["opencode", "--version"], shell=True, capture_output=True, text=True, timeout=5)

# ✅ 正确
subprocess.run(
    ["opencode", "--version"],
    capture_output=True, text=True, timeout=5,
    env={**os.environ, "HOME": os.path.expanduser("~")}
)
```