OpenClaw 镜像文档站点 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将 OpenClaw 文档站（yeuxuan/openclaw-docs）克隆到本地，替换品牌信息，配置好本地开发环境，并输出可部署到阿里云 ECS 的静态文件。

Architecture: 克隆 VitePress 文档源码仓库 → 修改 docs/.vitepress/config.mts 和首页 → npm run docs:build 生成 docs/.vitepress/dist/ → rsync 推送到 ECS Nginx 托管目录。

Tech Stack: VitePress 1.x、Vue 3、Node.js 18+ LTS、npm、Nginx（阿里云 ECS）

---

文件变更地图

操作	文件路径	说明
修改	docs/.vitepress/config.mts	站点标题、描述、社交链接、GitHub URL
替换	docs/public/logo.svg（或 .png）	站点 Logo
修改	docs/index.md	首页 Hero 标题、副文案、CTA 按钮
创建	deploy/nginx.conf	Nginx 配置文件（供上传到 ECS 用）
创建	deploy/deploy.sh	rsync 一键部署脚本

---

Task 1: 克隆仓库到 Desktop/ai workspace

Files:

• Create: C:/Users/Administrator/Desktop/ai workspace/openclaw-docs/（克隆目标）

• [ ] Step 1: 检查 Node.js 版本

node -v

期望输出：v18.x.x 或更高。若未安装，从 https://nodejs.org 下载 LTS 版本。

• [ ] Step 2: 克隆仓库

cd "C:/Users/Administrator/Desktop/ai workspace"
git clone https://github.com/yeuxuan/openclaw-docs.git
cd openclaw-docs

期望输出：Cloning into 'openclaw-docs'... 后完成，无报错。

• [ ] Step 3: 验证目录结构

ls docs/.vitepress/

期望输出：包含 config.mts 和 theme/ 目录。

• [ ] Step 4: 提交初始克隆记录

git log --oneline -3

记录当前最新 commit hash，作为基线备份参考。

---

Task 2: 安装依赖并验证开发服务器

Files:

• 无新增文件，node_modules/ 由 npm 自动生成

• [ ] Step 1: 安装依赖

cd "C:/Users/Administrator/Desktop/ai workspace/openclaw-docs"
npm install

期望输出：added XXX packages 无报错。若出现 ERESOLVE 依赖冲突，运行 npm install --legacy-peer-deps。

• [ ] Step 2: 启动开发服务器

npm run docs:dev

期望输出：

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

• [ ] Step 3: 浏览器确认首页可访问

打开 http://localhost:5173，确认：

• 首页正常渲染（有 Hero 区域和导航栏）

• 侧边栏可点击展开

• 页面无控制台报错

• [ ] Step 4: 停止开发服务器

按 Ctrl+C 停止。

---

Task 3: 读取并理解配置文件结构

Files:

• Read: docs/.vitepress/config.mts

• Read: docs/index.md

• [ ] Step 1: 查看 VitePress 配置

cat "docs/.vitepress/config.mts"

重点记录以下字段的当前值：

• title（站点名称）

• description（SEO 描述）

• themeConfig.logo（Logo 路径）

• themeConfig.socialLinks（社交链接数组）

• themeConfig.nav（顶部导航）

• [ ] Step 2: 查看首页内容

cat docs/index.md

重点记录：

• hero.name（大标题）
• hero.tagline（副标题）
• hero.actions（CTA 按钮及其链接）
• features（功能卡片列表）

---

Task 4: 替换站点品牌配置

Files:

• Modify: docs/.vitepress/config.mts

• [ ] Step 1: 修改站点标题和描述

打开 docs/.vitepress/config.mts，找到并修改（将下列值替换为你自己的内容）：

// 修改前（示例）
title: 'OpenClaw 中文社区',
description: 'OpenClaw 中文文档 ...',

// 修改后（按你的实际信息填写）
title: '你的站点名称',
description: '你的站点描述，用于 SEO',

• [ ] Step 2: 修改社交链接

在 themeConfig.socialLinks 中，将 GitHub 链接替换为你自己的仓库（如无自己的仓库可删除此项）：

socialLinks: [
  { icon: 'github', link: 'https://github.com/你的用户名/你的仓库' }
]

• [ ] Step 3: 修改顶部导航中的外链

找到 themeConfig.nav 数组，将指向 clawd.org.cn 论坛、Discord、赞助等外链替换为你自己的链接，或删除不需要的项。

• [ ] Step 4: 修改网站 favicon（如有）

若 head 配置中有 favicon 引用，更新为你的 favicon 路径：

head: [
  ['link', { rel: 'icon', href: '/favicon.ico' }]
]

• [ ] Step 5: 启动开发服务器验证修改

npm run docs:dev

打开 http://localhost:5173，确认浏览器标签页标题已变为新站点名称。按 Ctrl+C 停止。

• [ ] Step 6: 提交品牌配置修改

git add docs/.vitepress/config.mts
git commit -m "chore: replace site title, description and social links"

---

Task 5: 替换 Logo

Files:

• Replace: docs/public/logo.svg（或对应的 logo 文件）

• [ ] Step 1: 确认当前 Logo 文件路径

ls docs/public/

找到 logo 文件（通常为 logo.svg、logo.png 或 favicon.ico）。

• [ ] Step 2: 替换 Logo 文件

将你的 Logo 文件复制到相同路径，覆盖原文件。Logo 要求：

• SVG 格式（推荐）或 PNG
• 建议尺寸：32x32 到 64x64（导航栏 Logo）
• 文件名保持与原文件相同

# 示例：将你准备好的 logo.svg 复制过来
cp /path/to/your/logo.svg docs/public/logo.svg

若暂时没有 Logo，跳过此步，后续补充。

• [ ] Step 3: 验证 Logo 显示

npm run docs:dev

打开 http://localhost:5173，确认导航栏 Logo 已更新。按 Ctrl+C 停止。

• [ ] Step 4: 提交 Logo 替换

git add docs/public/
git commit -m "chore: replace site logo"

---

Task 6: 修改首页 Hero 内容

Files:

• Modify: docs/index.md

• [ ] Step 1: 修改 Hero 区域

打开 docs/index.md，找到 frontmatter 中的 hero 块，修改为你自己的内容：

---
layout: home

hero:
  name: "你的站点名称"
  tagline: 你的一句话介绍
  actions:
    - theme: brand
      text: 快速开始
      link: /start/getting-started
    - theme: alt
      text: GitHub
      link: https://github.com/你的用户名/你的仓库
---

• [ ] Step 2: 验证首页渲染

npm run docs:dev

打开 http://localhost:5173，确认首页 Hero 区域已显示新标题和副文案。按 Ctrl+C 停止。

• [ ] Step 3: 提交首页修改

git add docs/index.md
git commit -m "chore: update homepage hero content"

---

Task 7: 构建并验证输出

Files:

• Generated: docs/.vitepress/dist/（构建产物，不提交到 git）

• [ ] Step 1: 执行构建

npm run docs:build

期望输出：build complete in X.Xs，无红色报错（警告可忽略）。

• [ ] Step 2: 确认产物目录存在

ls docs/.vitepress/dist/

期望：包含 index.html、assets/ 等文件。

• [ ] Step 3: 本地预览构建产物

npm run docs:preview

期望输出：http://localhost:4173/。打开浏览器确认：

• 首页 Logo 和标题正确
• 侧边栏所有链接可访问
• 本地搜索功能可用（输入关键词有结果）
• 移动端宽度（调整浏览器窗口为窄屏）布局正常

按 Ctrl+C 停止。

• [ ] Step 4: 将 dist 加入 .gitignore（如未配置）

grep "dist" .gitignore || echo "docs/.vitepress/dist" >> .gitignore
git add .gitignore
git commit -m "chore: ignore vitepress dist output"

---

Task 8: 创建 Nginx 配置文件（ECS 部署准备）

Files:

• Create: deploy/nginx.conf

• Create: deploy/deploy.sh

• [ ] Step 1: 创建 deploy 目录

mkdir -p deploy

• [ ] Step 2: 创建 Nginx 配置文件

创建 deploy/nginx.conf，内容如下（替换 YOUR_DOMAIN 为你的真实域名）：

server {
    listen 80;
    server_name YOUR_DOMAIN www.YOUR_DOMAIN;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name YOUR_DOMAIN www.YOUR_DOMAIN;

    # 阿里云 SSL 证书路径（下载后上传到服务器的位置）
    ssl_certificate     /etc/ssl/YOUR_DOMAIN.pem;
    ssl_certificate_key /etc/ssl/YOUR_DOMAIN.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    root /var/www/docs/dist;
    index index.html;

    # VitePress SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源长缓存（VitePress 构建后文件名含 hash，可安全长缓存）
    location ~* \.(js|css|png|svg|ico|woff2|woff|ttf)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/html text/css application/javascript application/json image/svg+xml;
}

• [ ] Step 3: 创建部署脚本

创建 deploy/deploy.sh，内容如下（替换 ECS_USER 和 ECS_IP）：

#!/bin/bash
set -e

ECS_USER="root"            # 替换为你的 ECS 用户名
ECS_IP="your.ecs.ip"       # 替换为你的 ECS 公网 IP
REMOTE_DIR="/var/www/docs/dist"
LOCAL_DIST="docs/.vitepress/dist"

echo "Building..."
npm run docs:build

echo "Deploying to $ECS_USER@$ECS_IP:$REMOTE_DIR ..."
rsync -avz --delete "$LOCAL_DIST/" "$ECS_USER@$ECS_IP:$REMOTE_DIR/"

echo "Done. Site is live."

• [ ] Step 4: 设置脚本可执行权限

chmod +x deploy/deploy.sh

• [ ] Step 5: 提交部署配置

git add deploy/
git commit -m "chore: add nginx config and deploy script"

---

Task 9: ECS 服务器端 Nginx 配置（在 ECS 上操作）

⚠️ 此 Task 在 阿里云 ECS 服务器 上执行，不在本机。通过 SSH 连接后操作。

前置条件：

• 已在阿里云控制台为域名签发免费 SSL 证书，并下载了 Nginx 格式（.pem + .key 两个文件）

• [ ] Step 1: SSH 连接到 ECS

ssh root@your.ecs.ip

• [ ] Step 2: 安装 Nginx（若未安装）

apt update && apt install -y nginx

• [ ] Step 3: 创建静态文件目录

mkdir -p /var/www/docs/dist

• [ ] Step 4: 上传 SSL 证书

在本机执行（将证书上传到 ECS）：

scp your-domain.pem root@your.ecs.ip:/etc/ssl/
scp your-domain.key root@your.ecs.ip:/etc/ssl/

• [ ] Step 5: 上传并激活 Nginx 配置

在本机执行：

scp deploy/nginx.conf root@your.ecs.ip:/etc/nginx/sites-available/docs.conf

在 ECS 上执行：

ln -sf /etc/nginx/sites-available/docs.conf /etc/nginx/sites-enabled/docs.conf
nginx -t          # 验证配置语法
systemctl reload nginx

期望输出：nginx: configuration file /etc/nginx/nginx.conf test is successful

• [ ] Step 6: 首次部署静态文件

在本机执行：

bash deploy/deploy.sh

• [ ] Step 7: 验证线上访问

浏览器打开 https://YOUR_DOMAIN，确认：

• HTTPS 锁图标正常（证书有效）
• 首页 Logo 和标题正确
• 侧边栏导航可用
• 搜索功能正常

---

成功标准核对

• [ ] npm run docs:dev 本地预览正常（Task 2）
• [ ] npm run docs:build 无报错（Task 7）
• [ ] 品牌信息已替换：站名、描述、社交链接（Task 4）
• [ ] Logo 已替换（Task 5）
• [ ] 首页 Hero 内容已替换（Task 6）
• [ ] 通过域名 + HTTPS 可访问（Task 9）
• [ ] 本地搜索功能正常（Task 7 Step 3）
• [ ] 移动端响应式布局正常（Task 7 Step 3）