企业官网建设流程全解析

1. 为什么选择 OpenClaw：项目定位与核心价值

OpenClaw 这个名字可能不少同学已经在技术社区刷到过，简单来说它是一个开源的、可本地化部署的 AI 智能体运行框架。你可以把它理解成一个“AI 管家”的中枢系统——它负责把底层的大语言模型、外部工具链、消息渠道（比如 Teams、Obsidian、数据库）串在一起，让你通过统一的接口去调度这些能力。真正吸引我去折腾它的原因有两点：一是它完全开源，数据不出本地；二是它的插件化架构非常灵活，今天接一个 Qwen 模型，明天挂一个 Teams 机器人，后天再连上 MySQL 做数据检索，基本不用改核心代码，改配置就行。

这篇文档不是官方 README 的翻译，而是把我从零开始部署 OpenClaw 的完整过程、踩过的坑、以及最终跑通之后的配置心得都写出来。适合这三类人看：第一类是完全没接触过 WSL 和 Node.js 的小白，想找一个能照抄的详细步骤；第二类是已经装过一遍但卡在某个环节（比如 WSL 无法安全验证、MySQL 连不上）的折腾型选手；第三类是想把 OpenClaw 接入团队协作工具或云服务器的进阶用户。我会尽量把每一步背后的“为什么”也讲清楚，毕竟知其然不知其所以然，换个环境你照样会卡住。

我自己的环境是 Windows 11 专业版 + WSL2 + Ubuntu 22.04，主程序跑在 WSL 里，Windows 侧只保留 VSCode 和浏览器作为操作界面。这套组合是目前社区里最主流的部署方式，也是官方文档默认推荐的环境路径。下面我会按实际安装顺序，从环境选型开始一步步往下走。

2. 环境选型与前置准备

2.1 为什么首选 WSL2 而不是双系统或虚拟机

OpenClaw 官方支持 Linux、macOS 和 Windows，但如果你用的是 Windows，我强烈建议优先走 WSL2 这条路。原因有三个。第一，WSL2 不是传统意义上的虚拟机，它用的是轻量级实用工具（utility VM），启动速度几乎和原生进程一样快，内存占用也比 VMware 或 Hyper-V 完整虚拟机低得多；第二，WSL2 的文件系统访问效率比第一代 WSL 提升了好几个量级，跑 Node.js 和 Python 这种 IO 密集型任务时体感差别特别明显；第三，你可以在 Windows 侧直接用 VSCode 的 WSL 插件连接进去写代码，文件读写、端口转发都是自动处理的，不需要额外配置网络映射。

有人可能会问：那我直接装一个 Ubuntu 双系统不更省事吗？如果你手头只有一台开发机，而且日常还要用 Windows 上的办公软件，双系统来回切换的成本远高于 WSL2。我自己之前也踩过 VMware 的坑——网络模式搞不好，Windows 访问虚拟机里的服务还要配端口转发，调试起来非常痛苦。WSL2 最舒服的一点是 localhost 天然互通，你在 WSL 里起的服务，Windows 浏览器直接访问http://localhost:端口就能看到，省掉一整层网络代理的维护成本。

2.2 基础组件清单与版本选择

开始安装之前，先把需要的组件列一个清单，后面每一步都是照着这个清单来执行的：

这里特别提醒一下 Node.js 的版本选择。OpenClaw 官方要求 Node.js 20 以上，我一开始图省事装了系统源里的 18 版本，结果启动时直接报错，说缺少某些 ES Module 特性。后来换成 20 LTS 一路顺畅。如果你拿不准，就装最新的 LTS 版本，不要追最新的 Current 版本，稳定压倒一切。Python 建议 3.10 起步，因为有些文档解析插件用到了较新的语法特性，太老的版本会跑不起来。

2.3 WSL2 环境初始化与常见报错处理

打开 PowerShell（管理员模式），执行以下的命令来安装 WSL2 和 Ubuntu：

wsl --install

这条命令会默认安装 WSL2 和 Ubuntu 发行版。安装完成后系统会提示你重启电脑。重启之后第一次进入 Ubuntu 需要设置用户名和密码，这个密码后面用sudo的时候要用到，记好别忘。

重启之后如果发现 Ubuntu 没有自动启动，在 PowerShell 里运行wsl --status检查状态。这里就遇到了很多新手会卡住的经典问题——系统提示“WSL 无法安全验证”或者状态显示异常。我当时的处理办法是到“控制面板 - 启用或关闭 Windows 功能”里，把“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个选项都勾上，然后在管理员 PowerShell 里执行：

wsl --update wsl --set-default-version 2

执行完再次重启，问题就消失了。如果你用的是公司电脑，有可能被组策略限制了虚拟化功能，这种情况需要找 IT 管理员确认 BIOS 里的虚拟化（VT-x / AMD-V）是否开启。进入 WSL 后，先换源再装软件。Ubuntu 默认源在国内速度很慢，我把 apt 源切换到了国内镜像源，具体方法是编辑/etc/apt/sources.list，把archive.ubuntu.com替换成对应镜像地址，然后执行sudo apt update和sudo apt upgrade。

3. 核心依赖安装：Node.js、Python 与 Git

3.1 Node.js 20 LTS 的安装与版本管理

Node.js 是整个 OpenClaw 的主运行时，它的安装质量直接决定了后面会不会出现莫名其妙的模块兼容问题。我推荐用 nvm（Node Version Manager）来管理 Node.js 版本，这样以后要切换版本或者升级都很方便。安装 nvm 的命令是：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后，重新加载 shell 配置（source ~/.bashrc），然后执行：

nvm install 20 nvm use 20 nvm alias default 20

最后设置默认版本，不然每次新开终端都要手动nvm use。验证是否成功：

node -v npm -v

我在这一步犯过一个低级错误：直接用sudo apt install nodejs装的是 Ubuntu 源里的旧版本，而且没有 npm，后来还得重新卸掉再走 nvm 流程。如果你已经用 apt 装过，建议先apt remove nodejs npm清理干净再继续。

另外提醒一句，OpenClaw 的依赖安装用的是 npm，但国内 npm 源速度一般，我建议把 npm 的 registry 切换到国内镜像：

npm config set registry https://registry.npmmirror.com

这样后面npm install的速度会快很多，尤其是装那些体积比较大的依赖包时，体感差异特别明显。

3.2 Python 3.10+ 与 Git 的配置要点

Python 在 OpenClaw 里主要用于执行一些数据处理的插件脚本（比如文档解析、文本向量化）。Ubuntu 22.04 自带 Python 3.10，基本满足要求。如果没有，用 apt 安装：

sudo apt install python3 python3-pip python3-venv

装完建议把 pip 也换成国内镜像源，修改~/.pip/pip.conf：

[global] index-url = https://pypi.tuna.tsinghua.edu.cn/simple trusted-host = pypi.tuna.tsinghua.edu.cn

Git 是拉取 OpenClaw 源码的必备工具，Ubuntu 里用一行命令搞定：

sudo apt install git

装完之后配置你的用户信息，这个不配置的话后续 git 提交会报错：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

如果你是从国内网络拉取 GitHub 仓库速度不理想，可以把 OpenClaw 仓库的 remote 地址改成镜像地址。这个操作不是必须的，但是实测下来速度差别很大，尤其是仓库体积比较大的时候。改 remote 的命令是git remote set-url origin 新地址，具体镜像地址可以在代码托管平台的帮助文档里找到。

3.3 VSCode 远程开发环境配置

Windows 侧的 VSCode 是主要操作界面。安装 VSCode 后，搜索并安装两个扩展：WSL和Remote Development。装完之后，点击左下角的绿色远程连接按钮，选择“Connect to WSL”，VSCode 会自动初始化 WSL 侧的 VS Code Server，然后你就有了一个完整的 Linux 开发环境，但操作界面还是熟悉的 VSCode。

我强烈建议把这步做好再继续下面的部署。因为 OpenClaw 的日志输出很頻繁，在 VSCode 的集成终端里查看日志比 ssh 连接过去要舒服得多，而且可以直接在编辑器里改配置文件，配合保存时自动格式化，效率高很多。如果你之前没用过 WSL 扩展，可能会遇到“VS Code Server 下载失败”的问题，这时候手动下载对应版本的 VS Code Server 包，解压到~/.vscode-server/bin目录下就能解决，具体版本号看报错信息。

4. OpenClaw 主程序部署与配置核心

4.1 拉取源码与依赖安装

在 WSL 终端里，选一个你喜欢的目录，我先在 home 下建了一个workspace目录专门放项目代码：

mkdir ~/workspace && cd ~/workspace git clone https://github.com/openclaw/openclaw.git cd openclaw

依赖安装是整个过程中最容易出问题的一步。OpenClaw 的依赖项比较多，分组也复杂，官方文档建议先安装核心依赖，后续按需安装扩展插件。我先执行了npm install来安装核心依赖，这里用到了前面配置的国内 npm 镜像源，速度还不错。如果某个依赖安装失败，先不要急着重试，看一下报错信息，常见的无非两种：一是网络超时，直接重试大概率能过；二是缺少系统级依赖库，比如某些原生模块需要build-essential，用 apt 装上再重试：

sudo apt install build-essential python3-dev

依赖装完后，项目根目录会生成一个.env文件，这是 OpenClaw 的核心配置入口。第一次生成时只有模板内容，所有配置项都在注释状态，下一步就是逐个激活和修改。

4.2 核心配置文件逐项解析

打开.env文件，你会看到大量以#开头的注释行。这里挑几个必须修改的项说清楚，其他保持默认就好：

# 指定运行端口 PORT=3000 # 指定数据目录，建议放到独立磁盘 DATA_DIR=/home/你的用户名/openclaw-data # 开启日志记录 LOG_LEVEL=info # 设置访问密钥，相当于你的 API Token API_KEY=请修改为随机字符串

其中API_KEY一定要改成足够复杂的随机字符串。这个密钥就是你通过 API 调用 OpenClaw 能力的凭证，如果留默认值，等于把你的 AI 服务裸奔在网络上，别人扫描到端口就能直接调用，产生的 token 消耗都是你买单。我习惯用openssl rand -hex 32生成一段随机字符串，粘贴进去用。

DATA_DIR建议指定到 WSL 文件系统内部路径，不要放到/mnt/c/这种 Windows 挂载目录。原因很简单：WSL2 访问 Windows 文件系统的 I/O 性能开销非常大，尤其是这种频繁读写的小文件场景，放/mnt/c会导致性能断崖式下跌。默认的~/openclaw-data就比较合理，让它在 Linux 原生文件系统里跑。

4.3 首次启动验证与模式选择

配置好.env后，执行npm start启动 OpenClaw。第一次启动会有一堆信息输出，观察控制台日志里是否出现Server is running on port 3000或者类似的关键词。在 WSL 终端里用curl验证一下服务状态：

curl http://localhost:3000/health

如果返回{"status":"ok"}这类 JSON，说明核心服务已经跑起来了。Windows 浏览器访问http://localhost:3000如果也能看到页面，说明端口转发一切正常。

OpenClaw 有两种运行模式：前台模式和守护进程模式。前台模式适合调试，日志直接打在终端里，ctrl+c 就停止；守护进程适合长期挂机，我用的是 pm2 来做进程守护。pm2 的用法很简单：

npm install -g pm2 pm2 start ecosystem.config.js pm2 save pm2 startup

pm2 startup会生成一条开机自启命令，执行它输出的那行命令后，OpenClaw 就会在系统重启后自动拉起。这个在本地开发的时候可能体验不出来，但把服务部署到服务器上的时候，少了这一步你就得每次手动 ssh 进去重启服务。

4.4 插件机制说明与基础插件安装

OpenClaw 的核心机制是插件。它跟手机 App Store 的逻辑差不多——核心是个空壳，能力全靠插件往里面填。我花了不少时间才理解这个设计思路，它不是功能做不全，而是故意把内核保持精简，把扩展能力让给社区，这样每个人都可以按需组合自己的工具链。

安装插件的方式有三种：第一种是从内置插件市场安装，执行openclaw plugin install 插件名；第二种是从本地目录加载，适合自己开发的插件；第三种是直接在.env里启用已有插件。前两种是主流方式，第三种一般是自己手动改动时才用。

我建议先装这些基础插件：mysql（数据库连接）、teams（微软 Teams 接入）、obsidian（知识库接入）、document-parser（文档解析）。装完插件后，.env里会多出对应的配置项，逐个填上你的实际信息即可。插件不是越多越好，装多了反而容易因为配置缺漏导致启动报错，建议装一个配一个，确认能跑再装下一个。

5. 数据库接入与模型关联配置

5.1 MySQL 8.0 安装与基础调优

OpenClaw 中很多能力需要持久化存储，默认的 SQLite 在轻量场景下够用，但一旦接入文档知识库、聊天记录、用户行为分析等场景，MySQL 会是更可靠的选择。安装 MySQL 8.0 我走的还是 apt 路线：

sudo apt install mysql-server sudo systemctl status mysql

安装完成后，MySQL 的 root 默认密码是空的，但如果你后续要通过 TCP 端口连接，需要做几步安全设置：

sudo mysql_secure_installation

这个交互式脚本会引导你设置 root 密码、禁用匿名用户、移除测试数据库等，全程一路 Y 就行。然后创建一个 OpenClaw 专用的数据库和用户，不要把 root 密码直接给应用用，这是安全底线：

CREATE DATABASE openclaw DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'openclaw'@'localhost' IDENTIFIED BY '你的强密码'; GRANT ALL PRIVILEGES ON openclaw.* TO 'openclaw'@'localhost'; FLUSH PRIVILEGES;

注意字符集一定要选 utf8mb4 而不是 utf8mb3，因为 OpenClaw 会存大量用户输入的文本、文档碎片，其中可能包含 emoji 和各种生僻汉字，utf8mb3 存不了 emoji，到时候查出来的全是问号，排查起来非常恼火。

5.2 OpenClaw 连接 MySQL 的配置写法

回到.env文件，找到 MySQL 插件对应的配置块，填上刚才创建的信息。这里我直接把最简版本的写法贴出来，标注一下每一行的含义：

# 启用 MySQL 插件 ENABLE_MYSQL=true # 连接主机，如果你是本地 WSL，用 127.0.0.1，不要用 localhost MYSQL_HOST=127.0.0.1 # 端口默认 3306 MYSQL_PORT=3306 # 刚才创建的数据库名 MYSQL_DATABASE=openclaw # 用户名 MYSQL_USER=openclaw # 密码 MYSQL_PASSWORD=你的强密码 # 连接池上限，同时并发量大就调高一点 MYSQL_POOL_MAX=10

这里有个细节坑：MYSQL_HOST用127.0.0.1还是localhost有讲究。在 WSL 里，localhost可能被解析为 IPv6 的::1，而 MySQL 默认监听的是 IPv4 的 3306 端口，导致连接直接 refused 报错。指定127.0.0.1强制走 IPv4 就不会有这个问题。如果你把 MySQL 也装在同环境的 WSL 里，这个配置一样适用；如果 MySQL 装在别的服务器上，这里就填那台服务器的 IP。

改完.env记得重启 OpenClaw 让配置生效。验证连接是否成功，最直接的办法是在 WSL 终端里看启动日志，如果出现MySQL connection established之类的字样，说明连上了。如果报错，先检查 MySQL 用户权限和 bind-address 设置。

5.3 关联 Qwen2.5 模型的完整步骤

OpenClaw 本身不带模型能力，它依赖外部大模型 API。我接入的是通义千问的 Qwen2.5-3B 模型，理由很简单：本地部署性价比高，响应速度比云端大模型快，而且数据不出内网。先要通过 ollama（一个本地模型运行工具）把模型拉起来，然后在 OpenClaw 里配置模型端点。

如果本地没有装 ollama，先装：

curl -fsSL https://ollama.com/install.sh | sh

然后拉取模型：

ollama pull qwen2.5:3b

启动 ollama 服务（默认监听 11434 端口），然后在 OpenClaw 的.env里配置模型接入信息：

# 启用模型插件 ENABLE_LLM=true # 模型提供方选择 ollama LLM_PROVIDER=ollama # 模型名称，要和 ollama pull 下来的名字一致 LLM_MODEL=qwen2.5:3b # ollama 的 API 地址 LLM_API_BASE=http://127.0.0.1:11434/v1 # 请求超时时间，本地模型一般不会太慢，但以防万一 LLM_TIMEOUT=120

配好后重启服务，在 OpenClaw 的界面上发一个测试消息。如果返回正常回复，说明整条链路已经打通。这里有个容易忽略的点：ollama 默认只监听127.0.0.1，如果你要把 OpenClaw 部署到别的机器，然后远程调用本机的 ollama，需要在 ollama 服务里设置环境变量OLLAMA_HOST=0.0.0.0让它监听所有网卡接口。

6. 扩展接入：Teams、Obsidian与云服务器部署

6.1 接入 Microsoft Teams 机器人

OpenClaw 的一个亮点是可以作为机器人接入 Microsoft Teams，这样团队成员可以直接在聊天框里和 AI 交互。接入的前提是你在 Azure 门户注册一个机器人应用，拿到 App ID 和 Client Secret。这块流程略微繁琐，注册入口在 Azure 门户的 Bot Services 服务里。注册时选“Single Tenant”类型，然后把生成的 App ID 和 Secret 记下来。

拿到凭证后，回到 OpenClaw 的.env，找到 Teams 插件的配置块：

ENABLE_TEAMS=true TEAMS_APP_ID=你的应用ID TEAMS_APP_SECRET=你的客户端密钥 TEAMS_TENANT_ID=你的企业租户ID

TEAMS_TENANT_ID是微软租户的唯一标识，在 Azure 门户的“租户属性”里可以看到，一串 UUID 格式。配好后重启服务，然后在 Teams 客户端里搜索你注册的机器人名字，发一条消息测试。如果机器人没反应，先看 OpenClaw 日志里有没有报错，常见问题是 App Secret 复制的时候带了多余空格，这种细节很难一眼发现。

6.2 接入 Obsidian 知识库

如果你平时用 Obsidian 做笔记，OpenClaw 可以直接读取你的笔记库作为知识来源，让 AI 回答问题时带上你自己的笔记内容。配置思路很简单：把 Obsidian 的笔记库路径暴露给 OpenClaw，插件会扫描并索引这些 Markdown 文件。

ENABLE_OBSIDIAN=true OBSIDIAN_VAULT_PATH=/home/你的用户名/笔记库路径 OBSIDIAN_SCAN_INTERVAL=60

SCAN_INTERVAL是扫描间隔（单位秒），默认 60 秒足够。如果你的笔记库特别大，首次扫描会花一点时间，日志里会输出索引进度。这里有性能上的注意点：如果你超过 5 万条笔记，跑在DATA_DIR里的 SQLite 会开始吃力，这也是我前面建议上 MySQL 的原因。索引完成后，在对话里 @ 机器人的时候，它会自动检索相关笔记内容作为上下文参考。

6.3 部署到阿里云免费服务器的完整流程

本地跑通之后，把它部署到一台公网服务器上是有实际意义的——你可以从手机、公司电脑任何地方访问自己的 AI 服务。阿里的云服务器有一个免费试用套餐，配置一般，但跑 OpenClaw + Qwen2.5-3B 足够。

服务器拿到手之后，先做基础环境初始化。Ubuntu 22.04 系统，然后用同样的流程安装 Node.js、Git、WSL 相关组件（云服务器本身就是 Linux，不需要 WSL），再装 MySQL。部署 OpenClaw 的步骤和前面本节的内容基本一致，但有几个位置和本地部署存在差异，需要留意：

• 服务器上的.env中，MYSQL_HOST要填127.0.0.1没有区别，因为数据库也装在同一台机器上；但模型端点LLM_API_BASE如果 ollama 也装同一台机器，同样是127.0.0.1。
• 服务器的安全组规则一定要在云控制台放行3000和11434端口，不然外部访问不到。这个是最常被忽略的一步，我认识的人里十个有八个卡在这里，客户端显示连接超时，排查半天最后发现是安全组没放行。
• 用 pm2 守护进程，然后同样执行pm2 startup设置开机自启。

部署完成后，通过浏览器访问http://服务器公网IP:3000就能看到 OpenClaw 界面。友情提醒：公网环境务必把API_KEY设置成强随机字符串，并且不要把默认端口 3000 暴露太久，可以考虑换一个高位端口，恶意扫描器喜欢扫默认端口。

7. 常见问题排查与避坑实录

7.1 "WSL 无法安全验证" 的完整处理思路

这个报错在社区里上镜率极高，也是在 powershell 里运行wsl -- status后发现的问题。我先说结论：绝大多数情况是 Windows 的“虚拟机平台”功能没有完整启用，或者是 WSL 内核版本过旧。处理流程按顺序执行：

1. 管理员 PowerShell 执行wsl --update，拉取新内核。
2. 打开“控制面板 - 程序 - 启用或关闭 Windows 功能”，确认“适用于 Linux 的 Windows 子系统”和“虚拟机平台”都勾选。
3. 重启电脑，再执行wsl --status检查。

如果还不行，进 BIOS（开机按 Del/F2/F12 进入，不同主板不一样），确认 CPU 虚拟化技术（Intel 叫 VT-x，AMD 叫 SVM）已经开启。在 Windows 的“任务管理器 - 性能 - CPU”页面右下角，你可以看到“虚拟化”这一栏是否显示“已启用”。如果显示“已禁用”，那必然是 BIOS 里没开，需要在 BIOS 里找到相关开关改掉。

7.2 OpenClaw 启动报错与日志定位技巧

启动时报错是很常见的事，关键是学会看日志。OpenClaw 的日志默认输出到 stderr，如果你用 pm2 管理，可以用pm2 logs查看实时日志。最常见的日志问题有三类：

• 端口占用：报错EADDRINUSE 0.0.0.0:3000，说明 3000 端口被别的进程占了。用lsof -i:3000找出占用进程，要么杀掉它，要么在.env里改PORT。
• 依赖缺失：报错里提示某个 module not found，在项目目录执行npm install重新安装一遍，通常能解决。如果装了多次仍失败，检查是不是 npm 版本太低，执行npm install -g npm@latest升级一下。
• 配置格式错误：.env文件里某项的值包含了中文字符引号，或者多了一个空格。.env的解析非常严格，值两边不要加引号（除非值本身包含空格），不要用中文引号，这些细节很容易忽略。

我踩过最坑的一次是.env里API_KEY的值里不小心带了一个换行符，导致后面所有配置项全部失效，报错信息指向完全无关的地方。排查到最后才发现问题是多了一个看不见的字符。所以建议你用 VSCode 编辑.env，打开显示不可见字符的功能，关键时刻能救命。

7.3 端口连通性验证与防火墙设置

本地 WSL 里服务能起但浏览器打不开，这种问题通常是防火墙拦截。WSL2 默认的 NAT 模式对外部输入有严格限制，但 localhost 转发一般没问题。如果你端口本来就监听在0.0.0.0但外部还是连不上，检查 Windows 防火墙是否放行了对应端口。用管理员 PowerShell 执行：

New-NetFirewallRule -DisplayName "OpenClaw" -Direction Inbound -LocalPort 3000 -Protocol TCP -Action Allow

云服务器上的情况类似，但除了系统防火墙还有一层云控制台的安全组，两层都要各放行一次。验证思路是：先在本机curl http://127.0.0.1:3000/health，如果通，再换到另一台机器上curl http://服务器IP:3000/health。第一层通第二层不通，就是防火墙/安全组问题；两层都不通，优先看服务是否真的监听在了0.0.0.0上（ss -tlnp | grep 3000看一下监听地址）。

7.4 依赖安装慢与失败的加速方案

国内网络环境拉取大量 npm 依赖时经常遇到两个问题：速度慢和偶尔失败。前面已经提到把 npm registry 换成国内镜像源，但如果某条特定依赖在镜像源上没及时同步，还是会失败。这时候的备选方案是用npx npkill或者直接清掉 node_modules 重装：

rm -rf node_modules package-lock.json npm cache clean --force npm install

千万别在npm install中途频繁断开重试，这样很容易把 node_modules 目录搞成半损坏状态。一次装完如果报错，先记录错误信息，再决定是否清掉重来。另一条思路是：先看报错里是哪个具体的包下载失败，单独用npm install 包名 --verbose装它，成功后再整包安装，这样可以精准定位问题。

Ubuntu 的 apt 包管理器也类似，装系统库时如果速度慢，同样先把源换成国内镜像，然后执行sudo apt update刷新索引。换源属于基础操作中的基础操作，推荐先处理好再开始装东西，不然每一步都可能卡在网络问题上。

8. 部署完成后的日常维护与升级建议

8.1 日志清理与磁盘空间管理

OpenClaw 跑久了之后，日志文件和数据库会慢慢变大。尤其是日志，如果不做轮转，几个月可能积攒好几个 GB 的文本文件。pm2 自带日志轮转功能，安装 pm2-logrotate 模块来自动切割日志文件：

pm2 install pm2-logrotate pm2 set pm2-logrotate:max_size 50M pm2 set pm2-logrotate:retain 7

这样每个日志文件超过 50MB 会自动切割，保留最近 7 份。另外DATA_DIR下的数据文件如果增长过快，定期检查哪些插件在大量写数据，该关的索引机制关掉。

8.2 如何平滑升级 OpenClaw 版本

OpenClaw 迭代速度很快，社区基本上每周都有新版本，升级的操作方式也有讲究：

cd ~/workspace/openclaw git pull npm install pm2 restart openclaw

逻辑顺序是先拉新代码，再装新依赖，最后重启服务。如果小版本升级，这么操作基本零风险。但如果遇到大版本号变更，升级前一定要先备份数据和.env文件：

cp .env .env.bak cp -r ~/openclaw-data ~/openclaw-data.bak

万一升级后启动失败，把.env恢复回去，再回退 git 版本，操作就是反方向执行git checkout 旧版本号。我升级过几次踩过坑，最严重的一次是插件配置格式变了，旧配置项被完全弃用，恢复备份后重新手工比对官方文档才解决。从那以后我每次都先看官方更新的 Changelog，确认有哪些重大变更再动手升级，不再盲目冲最新版。

8.3 个人经验：一些容易被忽略的小建议

最后分享几个用下来觉得非常实用的习惯。一是给 WSL 设置内存限制，默认 WSL2 会占用你一半物理内存，如果你还要跑 Windows 侧的大型软件，建议在用户目录下加一个.wslconfig文件：

[wsl2] memory=4GB swap=2GB

这个文件位于 Windows 用户目录下（C:\Users\你的用户名\.wslconfig），改完在 PowerShell 里执行wsl --shutdown重新启动 WSL 让它生效。二是建议把 OpenClaw 的服务开成每天凌晨自动备份数据库，用 cron 加一条简单命令，把 MySQL 的 dump 文件复制到独立目录。这不是什么高级操作，但真到了数据丢失的那一天，你会庆幸当时多花了几分钟配这个定时任务。三是多关注官方社区和 GitHub 讨论区的 Issue，很多你踩到的坑别人已经记录过解决方案，搜索效率远比你自己瞎试来得高。

我在实际部署过程中最大的体会是：这类开源项目的配置难点从来不在某一个单点上，而是在“链条完整性”。从 WSL 环境、Node.js 版本、Python 依赖、数据库连接、模型接入，到最终通过 Teams 和 Obsidian 变成可用的服务，任何一环掉链子都会导致整体不可用。所以建议你每一步都跑通验证后再进入下一步，不要攒着一堆问题最后一起爆发。按照这篇文档的顺序一步步来，大概率一次就能搭起来。