《从 0 到 1：我在 WSL2 中部署 OpenClaw 的完整实战记录（含安全配置、MiniMax 接入、踩坑复盘）》

清空mega2026-03-17 11:40

前言

今天我做了一件非常有价值的事：
在 Windows 的 WSL2 环境中，成功部署了 OpenClaw，并完成了相对安全的本机配置，同时把默认模型从失败的 OpenAI OAuth 切换到了可用的 MiniMax。

这件事看起来只是"装一个工具"，但实际上我学到的远不止安装命令本身。

整个过程涉及：

  • WSL2 与 Ubuntu 基础环境

  • systemd 的作用

  • OpenClaw 的架构与安全边界

  • Gateway / Dashboard / Token 的关系

  • OAuth 与 API Key 的区别

  • 环境变量与 systemd 服务环境隔离

  • .env 配置文件的用途

  • 模型 provider 切换

  • OpenAI 与 MiniMax 的接入方式差异

  • 报错排查与部署思维

所以这篇文章不只是"记录安装过程"，更是一次完整的实战学习总结。

一、我今天到底做成了什么

先说结论。

我最终成功实现了以下目标：

  1. 在 Windows 的 WSL2（Ubuntu-24.04） 中安装 OpenClaw

  2. 开启并正确配置了 systemd

  3. 安装并启用了 OpenClaw Gateway systemd 用户服务

  4. 将 Gateway 配置为：

    • 仅本机监听 127.0.0.1

    • 端口 18789

    • 使用 token 认证

  5. 关闭了额外暴露面：

    • 没开 Tailscale

    • 没开外部聊天渠道

    • 没配 web search

    • 没开 skills / hooks

  6. 成功打开并连接了 OpenClaw Dashboard

  7. 将默认模型从失败的 OpenAI Codex OAuth 切换到了 MiniMax CN API Key

  8. 学会了让 WSL shell 环境变量 和 systemd 后台服务环境 同时生效

  9. 发现并解决了：

    • OpenAI OAuth 地区限制

    • Dashboard token 认证失败

    • systemd 服务拿不到环境变量

    • MiniMax 401 鉴权错误

    • 会话仍残留旧 OpenAI 模型的问题

所以，今天不是"装了个软件"，而是真正完成了一次带安全意识的本地 AI Agent 部署实战。

二、OpenClaw 是什么，我今天理解了什么

一开始如果只看名字，很容易把 OpenClaw 当成一个普通聊天程序。

但实际部署后我发现，它更像是：

一个可以运行在本地或服务器上的 AI Agent 控制平台。

它不是单纯的模型客户端，而是一个"带控制平面"的系统。

它内部至少有几个重要概念：

1. Gateway

Gateway 可以理解成 OpenClaw 的核心后端服务。

它负责：

  • 提供 WebSocket / HTTP 接口

  • 连接 Dashboard 控制台

  • 承载模型调用

  • 管理 agent、会话、工具、渠道等能力

所以 Gateway 是整个系统的中枢。

2. Dashboard / Control UI

Dashboard 是浏览器里的控制界面。

本质上它不是"独立服务"，而是去连接 Gateway。

也就是说：

  • Gateway 是后端

  • Dashboard 是前端

如果 Gateway 没起来，Dashboard 就只是个空壳。

3. Agent

Agent 可以理解成"被配置出来的一个 AI 助手实例"。

它不只是一个模型名，而是一整套东西的组合：

  • 默认模型

  • 认证配置

  • 会话记录

  • 工具权限

  • 技能与钩子

  • memory / search / channel 行为

这让我意识到：

Agent ≠ 模型

Agent 是"模型 + 配置 + 权限 +上下文"的组合体。

三、为什么 OpenClaw 推荐部署在 WSL2

今天我学到的第一件关键事，就是：

Windows 上官方更推荐通过 WSL2 部署 OpenClaw，而不是直接裸跑在原生 Windows 环境里。

为什么？

因为 OpenClaw 很依赖 Linux 风格的运行环境，特别是：

  • systemd

  • shell 环境变量

  • 文件权限

  • 后台用户服务

  • Node 运行时生态

WSL2 本质上是在 Windows 里面跑了一套真正的 Linux 用户空间，所以对这类工具更友好。

我对 WSL2 的理解也更清晰了

WSL2 不是"终端皮肤"，而是：

Windows 内部的一套轻量 Linux 虚拟化环境。

它有自己的：

  • 文件系统

  • 用户目录

  • 进程空间

  • 网络环境

  • systemd 服务体系

这也是为什么 OpenClaw 更适合跑在 WSL2 中。

四、systemd 是什么，为什么这一步至关重要

今天最重要的一个底层知识点，就是 systemd。

1. systemd 是 Linux 中的服务管理系统

你可以把它理解成：

Linux 里的"后台服务总管"。

很多长期运行的程序不会靠你手动开一个终端一直挂着，而是交给 systemd 管理。

它能负责：

  • 开机启动

  • 用户级服务

  • 守护进程管理

  • 自动重启

  • 状态查询

2. 为什么 OpenClaw 需要它

因为 OpenClaw 里的 Gateway 不是一次性命令，而是要长期驻留的服务。

如果不用 systemd，那么你每次想用都得自己重新开终端跑。

而用了 systemd 以后，OpenClaw 就能被注册成用户服务，比如：

复制代码 
~/.config/systemd/user/openclaw-gateway.service

这样它就能在后台稳定运行。

3. 为什么 WSL2 里要手动开 systemd

WSL2 默认不一定启用 systemd，所以要在：

复制代码 
/etc/wsl.conf

里写：

复制代码 
[boot]
systemd=true

然后执行：

复制代码 
wsl --shutdown

重启 WSL 生效。

这一步让我真正理解了：

很多 Linux 工具部署失败，不是工具有问题，而是运行环境没达到要求。

五、OpenClaw 安装过程让我学到的事

安装 OpenClaw 时，我不是直接 npm 硬装，而是用了官方推荐脚本：

复制代码 
curl -fsSL https://openclaw.ai/install.sh | bash

这让我明白了两个原则：

1. 官方安装脚本通常比手搓更稳

因为它会自动做：

  • 环境检测

  • Node 版本检查

  • 安装逻辑分发

  • 初始化引导

2. Node 运行时是 OpenClaw 的核心依赖之一

我这次使用的是：

  • Node v22

  • npm v10

而且后面在配置 Gateway runtime 时，官方也明确推荐 Node 而不是 Bun。

这让我知道：

对于需要稳定运行的后台服务，运行时兼容性非常重要。

"能跑"和"适合长期跑"是两回事。

六、我对"安全部署"真正学到了什么

这是今天最有价值的部分之一。

以前很多人一提部署，只想着"跑起来就行"。

但这次我真正理解了：

AI Agent 不是普通软件，安全边界比安装命令更重要。

OpenClaw 在 onboarding 一开始就不断强调：

  • 它默认适合单一可信操作者

  • 不是面向 hostile multi-tenant 的强隔离系统

  • 如果启用了工具，就可能读文件、执行动作

  • 如果暴露给不可信用户，风险会放大

我今天理解的几个核心安全原则

1. Loopback-only 是第一道防线

我把 Gateway 绑定到了：

复制代码 
127.0.0.1

这意味着：

  • 只有本机能访问

  • 局域网别的机器不能直接访问

  • 公网更不可能直接访问

这是最基础也最有效的安全收缩。

2. Token 认证不是可有可无

即使 Gateway 只监听本机，我依然保留了 token 认证。

因为"只本机访问"并不等于"本机所有进程都可信"。

所以我理解到：

本地访问控制也需要认证，不是只有公网服务才需要。

3. 不该一开始就开外部渠道

OpenClaw 支持各种 chat channels，但我没有配置：

  • Telegram

  • Discord

  • Slack

  • Signal

  • WhatsApp 等

原因不是不会配，而是现在没必要。

只要一接外部渠道，输入面立刻变复杂：

  • 多用户输入

  • 恶意提示

  • 越权触发

  • 渠道权限问题

所以第一次部署的正确策略是：

先把本机单人使用跑通，再逐步开放能力。

4. Token、API Key 都是凭证，泄露后就该轮换

今天我还意识到一个非常重要的安全习惯：

任何凭证一旦公开暴露，就应该视为泄露并轮换。

不管是：

  • Gateway token

  • MiniMax API Key

  • OpenAI API Key

都不该直接发到聊天记录里。

因为它们本质上就是"数字钥匙"。

七、OAuth 和 API Key，我今天彻底分清了

今天一个很大的转折点，就是 OpenAI OAuth 失败。

1. OAuth 是什么

OAuth 不是直接给你 API key，而是通过：

  • 浏览器登录

  • 授权页面

  • 回调地址

  • code 换 token

来完成授权。

在 OpenClaw 中，OpenAI Codex 的 OAuth 流程大概就是：

  1. 打开浏览器去 OpenAI 登录

  2. 登录成功跳到 localhost 回调

  3. 把 code 交回 CLI

  4. CLI 再去交换令牌

2. 它为什么失败

失败的根本原因不是 OpenClaw，而是 OpenAI 返回了：

  • 403

  • unsupported_country_region_territory

也就是说：

认证流程本身没错，但 OpenAI 不接受当前网络/地区判定。

这让我学到：

  • 工具部署失败，未必是部署问题

  • 有时是 provider 平台层面的限制

3. API Key 和 OAuth 的区别

今天之后，我对两者理解更清晰了：

OAuth

优点：

  • 对用户更友好

  • 不必自己管理 key

  • 常见于网页登录授权

缺点：

  • 依赖浏览器回调

  • 更容易受网络、地区、登录态影响

  • 自动化环境里更麻烦

API Key

优点：

  • 简单直接

  • 更适合服务端 / 本地工具

  • 配置路径清晰

缺点：

  • 要自己保管

  • 泄露风险完全自己承担

这也是为什么我最终切到 MiniMax 时，优先走了 API Key 路线。

八、为什么我最终改用 MiniMax

OpenAI OAuth 因地区限制失败后，我选择了方案 B：

不继续死磕 OpenAI，而是换一个可用 provider。

这次我选择的是 MiniMax。

为什么选 MiniMax

因为：

  • OpenClaw 内置支持 MiniMax provider

  • MiniMax 提供 API Key 方式

  • 我可以绕开 OAuth 带来的地区问题

  • 接入路径更直接

这让我明白一个很重要的部署思路：

部署时不要执着于"必须用某一个 provider"，而应该优先保证整体链路跑通。

MiniMax 也有 CN / Global 的区别

这是今天另一个非常实用的知识点。

我最开始还误以为所有 MiniMax key 都一样，后来才搞清楚：

  • minimax.io 对应 Global

  • minimaxi.com 对应 CN

而我获取 key 的页面是：

复制代码 
platform.minimaxi.com

所以我必须在 OpenClaw 中选择：

MiniMax CN --- API Key (minimaxi.com)

这说明：

平台、域名、provider 选项、API key 必须成套匹配。

否则就会 401。

九、环境变量是什么，我今天为什么会踩坑

今天我还真正搞懂了"环境变量"在部署中的角色。

1. 什么是环境变量

环境变量可以理解成：

进程启动时能读取到的一组键值对配置。

比如：

复制代码 
export MINIMAX_API_KEY=xxxxx

这里 MINIMAX_API_KEY 就是变量名，xxxxx 是值。

程序运行时可以去读它。

2. 为什么我最开始以为配置成功，其实 dashboard 还不行

因为我曾经在当前 shell 里执行过：

复制代码 
export MINIMAX_API_KEY=...

所以我运行：

复制代码 
openclaw models status --probe

时显示 ok。

但 dashboard 实际连接的是 systemd 用户服务中的 Gateway，不是当前 shell 里的临时进程。

这就引出了今天最重要的一个环境隔离知识点：

当前终端 shell 的环境变量，不一定会自动传给 systemd 后台服务。

这也是为什么：

  • CLI probe 成功

  • Dashboard 实际调用却报 401

十、为什么要写 ~/.openclaw/.env

为了解决上面的环境隔离问题，我学到了一个非常关键的方案：

把 provider 的 API key 写进 OpenClaw 自己读取的 .env 文件中。

路径是：

复制代码 
~/.openclaw/.env

内容格式必须严格正确，例如：

复制代码 
MINIMAX_API_KEY=你的真实完整key

注意点：

  • 不加引号

  • 等号两边不加空格

  • 不写 Bearer

  • 不写 URL

  • 必须是完整 key，不是页面截断显示

为什么 .env 有用

因为 OpenClaw 的后台服务会从这里读取配置。

这让 systemd 服务不再依赖你当前 shell 的临时 export。

所以我今天真正学会了：

.env 是服务型应用常见的"持久化环境配置入口"。

十一、401 报错到底意味着什么

在切到 MiniMax 后，我还遇到了：

复制代码 
HTTP 401 authentication_error
请在请求头部的"授权"字段中携带 API 密钥

这个报错让我真正理解了 HTTP 鉴权里的 401。

401 的本质

401 通常表示：

认证失败，服务端没有接受你提供的凭据。

可能的原因包括：

  • 根本没传 key

  • key 为空

  • key 写错

  • key 平台不匹配

  • 格式不对

为什么这个报错比"找不到模型"更有价值

因为它说明一件事：

请求已经到了 provider，只是 provider 不认可这把钥匙。

所以 401 比"配置没生效"更进一步。

这也帮助我定位到问题其实在 .env 和服务读取凭据这条链路上。

十二、我还学会了如何判断问题出在哪一层

今天最大的收获之一是：

我不再只会说"报错了"，而是开始知道报错属于哪一层。

1. 环境层

比如：

  • WSL2 是否正常

  • Ubuntu 是否正常

  • systemd 是否开启

2. 服务层

比如：

  • Gateway 是否运行

  • 端口是否监听

  • openclaw gateway status 是否正常

3. 认证层

比如：

  • token 是否正确

  • OpenAI OAuth 是否成功

  • MiniMax API key 是否有效

4. provider 层

比如：

  • OpenAI 地区限制

  • MiniMax key 与平台是否匹配

  • 模型 provider 是否真的接通

5. 前端会话层

比如：

  • 当前聊天窗口顶部到底选的是哪个模型

  • 是不是还残留旧的 openai-codex 会话模型

  • dashboard 有没有刷新

这让我真正开始拥有一种"分层排障"的思路，而不是只会盯着最终报错看。

十三、我今天还学会了 nano 的保存退出

虽然这是个小点，但非常实用。

在 nano 里：

  • Ctrl + O：保存

  • Enter：确认文件名

  • Ctrl + X：退出

很多新手第一次进 Linux 编辑器都会慌，但今天我也把这个最基础的编辑操作学会了。

十四、整个部署过程我形成的方法论

如果让我总结今天真正学到的"底层方法"，我会提炼成这几条：

1. 先跑通最小闭环，再加功能

不要一开始就想：

  • 外部聊天渠道

  • web search

  • skills

  • hooks

  • 多 provider

  • 远程访问

正确顺序是：

WSL2 → systemd → Gateway → Dashboard → 模型 provider → 对话成功

2. 优先排"链路"而不是排"表面报错"

比如今天的链路是：

  • WSL2 环境

  • systemd 服务

  • Gateway 运行

  • Dashboard 连接

  • 模型 provider

  • API key / OAuth

  • 当前会话模型

只要链路里有一环错，整体就会失败。

3. 凭证问题永远优先严肃处理

包括：

  • token 不乱发

  • API key 不乱发

  • 泄露后轮换

  • 写进 .env 而不是随手贴聊天

4. CLI 成功 ≠ 后台服务成功

这是今天非常重要的认知升级。

当前终端里 export 生效，不代表 systemd 服务就能读到。

所以：

命令行 probe 成功，不一定等于 dashboard 真能用。

十五、我现在这套 OpenClaw 配置是什么状态

如果总结我现在的最终配置，大致是：

环境

  • Windows + WSL2

  • Ubuntu 24.04

运行时

  • Node

Gateway

  • 本机模式

  • 127.0.0.1

  • 端口 18789

  • token 认证

  • Tailscale 关闭

Dashboard

  • 本机浏览器访问

  • 通过 token 连接

Provider

  • MiniMax CN API Key

  • 模型 MiniMax-M2.5

安全策略

  • 不开外部渠道

  • 不开 web search

  • 不开 hooks

  • 不开 skills

  • 只本机 loopback

  • token 认证保留

这已经是一套相对稳妥、适合个人使用的 OpenClaw 本地部署基线。

十六、今天这次实战对我的意义

今天这件事最大的意义，不是"我能和 OpenClaw 聊天了"。

而是我第一次真正经历了一次完整的：

  • Linux 环境准备

  • 服务部署

  • 安全配置

  • provider 切换

  • 认证排错

  • 配置持久化

  • 前后端联调

这种实践和单纯看教程完全不是一个级别。

它让我知道：

真正的工程问题，往往不是"不会敲命令"，而是"不知道系统在分几层工作"。

当你知道：

  • 谁在运行

  • 谁在读配置

  • 谁在负责认证

  • 谁在真正发请求

很多问题就不再是"玄学"。

十七、结语

如果今天让我用一句话总结这次学习，我会说：

我不是简单地安装了 OpenClaw，而是借这个过程补上了本地 AI Agent 部署、安全配置、认证机制、Linux 服务管理和 provider 接入的一整套基础能力。

这次踩了很多坑：

  • OpenAI OAuth 失败

  • token 用错位置

  • 当前会话模型残留

  • systemd 服务拿不到环境变量

  • MiniMax 401

但也正因为这些坑，我学到的东西才真正扎实。

以后再遇到类似工具部署，我不会只会说"怎么又报错了"，而是会先问：

  • 是环境问题？

  • 是服务问题？

  • 是认证问题？

  • 是 provider 问题？

  • 还是前端会话缓存问题？

这就是今天最大的成长。

相关推荐
一个平凡而乐于分享的小比特2 小时前
深度拆解OpenClaw：引爆“赛博养虾”狂潮的技术内核、产业重构与暗面危机
openclaw·未来思考·产业重构·风险危机
Bruce_Liuxiaowei2 小时前
深入浅出：清理 OpenClaw 会话记录的完整操作解析
人工智能·大模型·智能体·openclaw
绘绘～2 小时前
openClaw安装到飞书配置
服务器·asp.net·飞书·openclaw
|华|2 小时前
Nginx安全防护与HTTPS部署
nginx·安全
小尔￥2 小时前
Nginx安全
运维·nginx·安全
智慧地球（AI·Earth）2 小时前
OpenClaw设置教程之安全篇
人工智能·安全·openclaw
一起来学吧3 小时前
【OpenClaw系列教程】第三篇：OpenClaw能做什么？ AI能力全解与实战案例
人工智能·openclaw
大傻^3 小时前
OpenClaw 生产级部署实录：Ubuntu 服务器 × MiniMax × 飞书(Lark) 完整集成指南
服务器·ubuntu·飞书·minimax·openclaw
weixin_427179283 小时前
openclaw
openclaw
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03OpenClaw 使用和管理 MCP 完全指南04OpenClaw Control UI安全上下文访问配置05UV安装并设置国内源06OpenClaw macOS 完整安装与本地模型配置教程（实战版）07本地部署 OpenClaw + DeepSeek-R1 完全指南08Openclow安装保姆级教程09Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services10让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南