docs(openclaw): 完善个人部署实战指南

src/ai/openclaw.md

@@ -1,17 +1,248 @@
 ---
-title: OpenClaw
+title: OpenClaw 个人 24 小时在线部署实战
 icon: mdi:robot-outline
-date: 2026-03-06
+date: 2026-03-10
 category:
   - AI
+  - 部署实践
 tag:
   - OpenClaw
+  - Telegram
+  - 飞书
+  - Linux
 ---
 
-# OpenClaw
+# OpenClaw 个人 24 小时在线部署实战
 
-OpenClaw 使用记录与实践。
+最近把 OpenClaw 在个人 Linux 机器上完整跑通了。
+这篇不是理想教程，而是可复现的真实部署记录：初始化、守护进程常驻、
+渠道接入、Web 搜索和安全收紧。
 
 <!-- more -->
 
-后续补充：场景、配置和最佳实践。
+适合人群：
+
+- 个人单用户场景
+- 希望 24 小时在线
+- 想接 Telegram 或飞书
+- 想一次把常见坑踩完
+
+---
+
+## 一、初始化与守护进程安装
+
+先执行初始化：
+
+```bash
+openclaw onboard --install-daemon
+```
+
+如果流程卡在风险确认，可以补上：
+
+```bash
+openclaw onboard --install-daemon --accept-risk --non-interactive --flow quickstart
+```
+
+安装后重点确认：
+
+```bash
+systemctl --user status openclaw-gateway.service --no-pager
+```
+
+看到 `active (running)` 基本就对了。
+
+---
+
+## 二、24 小时在线关键：开启 linger
+
+如果希望退出登录后仍运行、重启后自动恢复，必须开启 `linger`：
+
+```bash
+sudo loginctl enable-linger <你的用户名>
+loginctl show-user <你的用户名> -p Linger
+```
+
+目标是 `Linger=yes`。
+
+不开 `linger` 的典型现象：退出图形会话或 SSH 后，user service 会停掉。
+
+---
+
+## 三、Dashboard token 报错处理（高频坑）
+
+常见报错：
+
+> unauthorized: gateway token missing
+
+处理方式：
+
+```bash
+openclaw dashboard --no-open
+```
+
+复制输出的完整 URL（包含 `#token=...`）到浏览器打开。
+如果是旧标签页，先关闭再开新链接。
+
+---
+
+## 四、模型配置确认
+
+检查当前默认模型：
+
+```bash
+openclaw models status --plain
+openclaw models list
+```
+
+如果模型已配置但仍无法工作，优先排查这三项：
+
+- 网关 token
+- 渠道配对状态
+- 工具权限策略
+
+---
+
+## 五、Telegram 接入（个人单用户推荐）
+
+最短流程：
+
+1. 用 `@BotFather` 创建 bot，拿到 token
+2. 运行配置向导
+
+```bash
+openclaw configure --section channels
+```
+
+3. 选择 Telegram，建议 `dmPolicy=pairing`
+4. 重启网关
+
+```bash
+systemctl --user restart openclaw-gateway.service
+```
+
+5. 私聊机器人后审批配对码
+
+```bash
+openclaw pairing list telegram
+openclaw pairing approve telegram <CODE>
+```
+
+---
+
+## 六、飞书接入（真实坑点）
+
+如果遇到报错：
+
+> 未检测到应用连接信息，请确保长连接建立成功后再保存配置
+
+重点检查：
+
+- 飞书应用是否已发布版本
+- 机器人能力是否开启
+- 事件订阅是否为长连接，且包含 `im.message.receive_v1`
+- 应用可用范围是否包含你自己的账号
+
+实践上建议先在 OpenClaw 侧加渠道，再回飞书保存长连接，成功率更高。
+
+---
+
+## 七、开启 Web 能力：`web_fetch` 与 `web_search`
+
+先开基础配置：
+
+```bash
+openclaw config set tools.web.fetch.enabled true
+openclaw config set tools.web.search.enabled true
+```
+
+Gemini 搜索示例：
+
+```bash
+openclaw config set tools.web.search.provider '"gemini"'
+openclaw config set tools.web.search.gemini.apiKey '"AIza...你的key..."'
+systemctl --user restart openclaw-gateway.service
+```
+
+---
+
+## 八、核心坑：有 key 也搜不了
+
+当时现象是 key 已配置，但 `web_search` 仍提示不可用。
+
+根因：工具策略限制，`tools.profile: coding` 默认不包含 `group:web`。
+
+临时打通方式：
+
+```bash
+openclaw config set tools.profile '"full"'
+systemctl --user restart openclaw-gateway.service
+```
+
+`full` 权限面比较大，建议只作为排障手段，跑通后再收紧。
+
+---
+
+## 九、安全加固（强烈建议）
+
+先做检查：
+
+```bash
+openclaw security audit --deep
+openclaw doctor
+```
+
+我最后收敛到这组配置：
+
+- 工具权限从 `full` 降回 `coding`
+- 显式插件白名单，防止任意扩展加载
+- 清理重复或社区扩展，仅保留稳定内置插件
+- 关闭不必要的飞书文档创建能力
+- 收紧 `~/.openclaw` 目录权限
+
+关键命令：
+
+```bash
+openclaw config set tools.profile '"coding"'
+openclaw config set plugins.allow '["feishu","telegram"]'
+openclaw config set channels.feishu.tools.doc false
+systemctl --user restart openclaw-gateway.service
+```
+
+最终安全摘要降到 `0 critical`（仅保留 loopback 场景可接受告警）。
+
+---
+
+## 十、密钥安全：暴露后立即轮换
+
+如果你在聊天、日志或截图里暴露过 API key，建议立刻轮换。
+
+以 Gemini 为例：
+
+1. 去 `https://aistudio.google.com/apikey` 新建 key
+2. 删除旧 key
+3. 更新 OpenClaw 配置并重启
+
+---
+
+## 十一、日常运维命令（常用）
+
+```bash
+openclaw status
+openclaw logs --follow
+systemctl --user status openclaw-gateway.service --no-pager
+openclaw security audit --deep
+```
+
+---
+
+## 结语
+
+这套下来，个人单用户场景基本就稳定了：
+
+- 24 小时在线
+- Telegram / 飞书可用
+- Web 能力可用
+- 安全面可控
+
+建议先追求稳、可恢复、最小权限，再逐步加功能；
+不要一上来就长期 `full` 权限常驻。