docs(desktop): document headless H5 access (#1027)

docs/desktop/04-installation.md

@@ -65,6 +65,30 @@ bun run dev --host 127.0.0.1 --port 2024
 
 启动后浏览器访问 `http://127.0.0.1:2024` 即可。
 
+本机通过 `127.0.0.1` 使用 Web UI 时，不需要开启 H5 访问，也不需要填写 H5 Token。服务端会把真正的本机回环请求视为可信本地访问；这个豁免不会扩展到局域网地址或反向代理。
+
+### 无界面 Linux 服务器
+
+如果服务器没有桌面环境，推荐先使用 SSH 同时转发前端和后端端口：
+
+```bash
+# 在服务器上分别启动后端与前端，仍只监听回环地址
+SERVER_PORT=3456 bun run src/server/index.ts
+cd desktop
+bun run dev --host 127.0.0.1 --port 2024
+
+# 在自己的电脑上执行
+ssh -L 2024:127.0.0.1:2024 -L 3456:127.0.0.1:3456 user@example.com
+```
+
+然后在自己的电脑上打开：
+
+```text
+http://127.0.0.1:2024/?serverUrl=http%3A%2F%2F127.0.0.1%3A3456
+```
+
+这条路径不把服务暴露到局域网，因此同样不需要 H5 Token。如果确实要从局域网或反向代理访问，请按 [H5 访问](./06-h5-access.md#无桌面界面时开启) 在服务器本机启用 Token、配置允许来源，再让服务监听外部接口。
+
 ## 常见问题
 
 **Q: 这个版本会自动更新吗？**

docs/desktop/06-h5-access.md

@@ -9,13 +9,46 @@ H5 访问是一个可选的个人/团队使用入口。开启后，你可以把
 1. 在桌面端打开 `设置 -> General -> H5 访问`。
 2. 打开 `启用 H5 访问`。
 3. 点击生成或重新生成 Token。
-4. 立即复制生成的 Token。Token 原文只显示一次；丢失后只能重新生成。
+4. 复制生成的 Token。之后仍可在本机设置页或本机可信接口中取回；需要撤销旧 Token 时再重新生成。
 5. 按你的访问方式填写允许来源：
    - 局域网访问：例如 `http://192.168.1.20:5173`
    - 反向代理访问：例如 `https://cc.example.com`
 6. 如果你使用固定域名，可以填写公开访问地址，设置页会据此生成 H5 URL。
 
-H5 设置保存到 `~/.claude/cc-haha/settings.json`。系统只保存 Token 哈希，不保存 Token 明文。
+H5 设置保存到 `~/.claude/cc-haha/settings.json`。为让已配对设备在重启后继续使用，当前版本会持久化完整 Token；只有本机可信的控制接口可以读回它。请像保护 API Key 一样保护这个文件和 Token。
+
+### 无桌面界面时开启
+
+无界面的 Linux 服务器也可以通过只允许本机调用的控制接口启用 H5。先启动服务端；需要局域网或反向代理访问时，让它监听外部接口：
+
+```bash
+SERVER_HOST=0.0.0.0 SERVER_PORT=3456 bun run src/server/index.ts
+```
+
+再从服务器本机的另一个终端生成 Token。响应 JSON 的 `token` 字段就是浏览器需要填写的完整 Token：
+
+```bash
+curl -sS -X POST http://127.0.0.1:3456/api/h5-access/enable
+```
+
+配置实际前端来源；`allowedOrigins` 必须写浏览器地址栏中前端页面的来源，不能使用通配符。使用反向代理时还可以设置公开访问地址：
+
+```bash
+curl -sS -X PUT http://127.0.0.1:3456/api/h5-access \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "allowedOrigins": ["https://cc.example.com"],
+    "publicBaseUrl": "https://cc-api.example.com"
+  }'
+```
+
+稍后需要重新取回完整 Token 或核对配置时，只能在服务器本机调用：
+
+```bash
+curl -sS http://127.0.0.1:3456/api/h5-access
+```
+
+如果只是通过 SSH 端口转发在自己的电脑上访问，请保持服务监听 `127.0.0.1`，无需开启 H5；完整命令见 [安装指南](./04-installation.md#无界面-linux-服务器)。
 
 ## 访问地址
 
@@ -84,7 +117,7 @@ Electron 桌面端仍保留原来的布局和交互。
 ## 安全注意
 
 - H5 默认关闭。
-- Token 原文只出现一次。
+- 完整 Token 会持久化，并可从本机可信的设置界面或控制接口读回。
 - 远程 API、代理接口和 WebSocket 都需要 H5 Token。
 - CORS 只允许设置页配置的来源。
 - 禁用 H5 或重新生成 Token 后，旧 Token 会失效。