diff --git a/docs/shared/openclaw-install-guide.md b/docs/shared/openclaw-install-guide.md
new file mode 100644
index 0000000..9b70105
--- /dev/null
+++ b/docs/shared/openclaw-install-guide.md
@@ -0,0 +1,327 @@
+# 🦞 OpenClaw 安装指南
+
+> 新设备从零到 Agent 上线的一站式指南。5 分钟内完成。
+
+---
+
+## 前提条件
+
+| 依赖 | 最低版本 | 安装方式 |
+|------|---------|---------|
+| Node.js | v20+ （推荐 v22） | [nvm](https://github.com/nvm-sh/nvm) / [nvm-windows](https://github.com/coreybutler/nvm-windows) |
+| Git | 任意 | 系统包管理器 |
+| pnpm | 最新 | `npm install -g pnpm` |
+
+??? tip "各平台安装 Node.js"
+
+    === "Ubuntu / Debian / WSL"
+
+        ```bash
+        curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+        source ~/.bashrc
+        nvm install 22
+        ```
+
+    === "macOS"
+
+        ```bash
+        curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+        source ~/.zshrc
+        nvm install 22
+        ```
+
+    === "Windows (PowerShell)"
+
+        1. 下载安装 [nvm-windows](https://github.com/coreybutler/nvm-windows/releases)
+        2. 重启 PowerShell
+
+        ```powershell
+        nvm install 22
+        nvm use 22
+        ```
+
+---
+
+## Step 1：安装 OpenClaw
+
+```bash
+npm install -g openclaw
+```
+
+验证：
+
+```bash
+openclaw --version
+# 应输出类似: OpenClaw 2026.4.8 (9ece252)
+```
+
+---
+
+## Step 2：初始化 & 启动
+
+```bash
+# 首次启动，自动生成配置文件
+openclaw gateway start
+```
+
+配置文件位置：
+
+- Linux / macOS / WSL: `~/.openclaw/openclaw.json`
+- Windows: `C:\Users\<用户名>\.openclaw\openclaw.json`
+
+---
+
+## Step 3：配置 LLM Provider
+
+编辑 `~/.openclaw/openclaw.json`，添加 LLM 提供商。
+
+### 方式 A：LiteLLM Proxy（团队推荐 ⭐）
+
+所有沙洲小队统一用 KUMA 上的 LiteLLM Proxy：
+
+```json
+{
+  "providers": {
+    "litellm": {
+      "type": "openai",
+      "baseUrl": "http://kuma-vm-west:4000/v1",
+      "apiKey": "<找小墨要 LiteLLM key>"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": "litellm/claude-sonnet-4"
+    }
+  }
+}
+```
+
+!!! note "获取 LiteLLM Key"
+    联系小墨 🖊️ 或主人获取 LiteLLM API Key 和 VPN 配置。
+    如果无法直连 KUMA，需要先配置 VPN 或 Tailscale。
+
+### 方式 B：直接配 API Key
+
+如果你有自己的 API Key（OpenAI / Anthropic / DashScope 等）：
+
+```json
+{
+  "providers": {
+    "openai": {
+      "type": "openai",
+      "apiKey": "sk-..."
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": "openai/gpt-4o"
+    }
+  }
+}
+```
+
+### 方式 C：Copilot API（有 GitHub Copilot 订阅）
+
+```json
+{
+  "providers": {
+    "copilot-api": {
+      "type": "copilot",
+      "apiKey": "<copilot-token>"
+    }
+  }
+}
+```
+
+---
+
+## Step 4：配置 Exec 安全策略
+
+Agent 需要执行命令的权限。**本地受信环境**用 `full`：
+
+```bash
+openclaw config set tools.exec.security full
+```
+
+!!! warning "安全提示"
+    公网 / VPS 环境请用 `allowlist` 模式，只允许白名单命令。
+
+---
+
+## Step 5：配置 Telegram 通道
+
+在 `openclaw.json` 中添加 Telegram bot：
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "botToken": "<你的 Bot Token>"
+    }
+  }
+}
+```
+
+??? tip "如何获取 Bot Token"
+    1. 在 Telegram 找 [@BotFather](https://t.me/BotFather)
+    2. 发送 `/newbot`，按提示起名
+    3. 复制返回的 token（格式：`123456:ABC-DEF...`）
+    4. 在 bot settings 里关闭 "Group Privacy"（如需群聊）
+
+配置完重启：
+
+```bash
+openclaw gateway restart
+```
+
+---
+
+## Step 6：创建 Agent 身份
+
+在工作目录 `~/.openclaw/workspace/` 下创建身份文件：
+
+### SOUL.md — 你是谁
+
+```markdown
+# SOUL.md
+
+## 身份
+**<你的名字>** <emoji> — <一句话描述>
+
+## 核心原则
+- 专业简洁
+- 主动思考
+- 用行动证明
+```
+
+### USER.md — 你的主人
+
+```markdown
+# USER.md
+
+- **Name:** Scott Wei
+- **What to call them:** 主人
+- **Timezone:** Asia/Shanghai (UTC+8)
+- **Notes:** 偏好中文交流
+```
+
+### AGENTS.md — 行为规范
+
+从现有队友那里复制一份 `AGENTS.md`，或参考 [M2 三层管理模式](m2-manager-pattern.md)。
+
+---
+
+## Step 7：设为系统服务（可选但推荐）
+
+开机自启，断线自动重连：
+
+```bash
+openclaw gateway install
+```
+
+=== "Linux / WSL"
+
+    安装为 systemd 服务：
+
+    ```bash
+    openclaw gateway install
+    # 检查状态
+    systemctl --user status openclaw-gateway
+    ```
+
+=== "macOS"
+
+    安装为 launchd 服务：
+
+    ```bash
+    openclaw gateway install
+    # 检查状态
+    launchctl list | grep openclaw
+    ```
+
+=== "Windows"
+
+    以管理员 PowerShell 运行：
+
+    ```powershell
+    openclaw gateway install
+    ```
+
+---
+
+## Step 8：接入 A2A 跨队通信（可选）
+
+连接其他小队的 Agent，实现跨设备协作：
+
+```json
+{
+  "a2a": {
+    "peers": {
+      "kuma": {
+        "url": "https://oc-kuma.shazhou.work"
+      },
+      "neko": {
+        "url": "https://oc-neko.shazhou.work"
+      }
+    }
+  }
+}
+```
+
+详见 [A2A 跨队通信配置](a2a-setup.md)。
+
+---
+
+## 验证清单
+
+安装完成后逐项检查：
+
+- [ ] `openclaw --version` 输出版本号
+- [ ] `openclaw gateway status` 显示 running
+- [ ] Telegram bot 能收发消息
+- [ ] Agent 能回复你的消息
+- [ ] `openclaw status` 显示 agent 在线
+
+---
+
+## 常用命令速查
+
+```bash
+openclaw gateway start          # 启动
+openclaw gateway stop           # 停止
+openclaw gateway restart        # 重启
+openclaw gateway status         # 查看状态
+openclaw status                 # Agent 总览
+openclaw logs --follow          # 实时日志
+openclaw config get             # 查看配置
+openclaw config set <key> <val> # 修改配置
+```
+
+---
+
+## 遇到问题？
+
+| 症状 | 可能原因 | 解决方案 |
+|------|---------|---------|
+| `command not found: openclaw` | Node.js 未安装或 PATH 问题 | 检查 `node --version`，重新 `npm install -g openclaw` |
+| Gateway 启动后无响应 | 没配 LLM provider | 检查 `openclaw.json` 中的 providers 配置 |
+| Telegram bot 无回复 | botToken 错误或未重启 | 检查 token，`openclaw gateway restart` |
+| Agent 报 401 / model not found | API Key 无效或模型名错误 | 检查 provider 配置和 model 名称 |
+| 日志显示 exec denied | 安全策略限制 | 调整 `tools.exec.security` |
+
+更多排障参考 [Gateway 配置红线](gateway-safety.md)。
+
+---
+
+## 相关文档
+
+- [Gateway 本地搭建详细指南](gateway-setup.md) — 完整配置参考
+- [Bootstrap 新设备](bootstrap-onboarding.md) — 一行命令自动化部署
+- [Onboarding Checklist](onboarding-checklist.md) — 完整检查清单
+- [A2A 跨队通信](a2a-setup.md) — 连接其他小队
+- [Gateway 配置红线](gateway-safety.md) — 避免踩坑
+
+---
+
+*最后更新: 2026-04-13 · 小墨 🖊️（KUMA Team）*
diff --git a/mkdocs.yml b/mkdocs.yml
index 938540f..ef00403 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -118,6 +118,7 @@ nav:
           - OGraph 对象模型与 API Protocol: shared/ograph-object-model.md
           - OGraph Task 系统接入指南: shared/ograph-task-onboarding.md
       - 基础设施:
+          - OpenClaw 安装指南: shared/openclaw-install-guide.md
           - Bootstrap 新设备: shared/bootstrap-onboarding.md
           - Onboarding Checklist: shared/onboarding-checklist.md
           - 帮外部用户 Setup: shared/external-setup-guide.md