从安装、Gateway、模型、渠道到安全沙箱，一篇讲清楚本地 AI 助手怎么搭
| 提示：本文面向想把 OpenClaw 部署在个人电脑、Linux 服务器或 Docker 环境中的读者。正文命令以官方文档为基础，并加入中文用户常见的 WSL2、端口、模型、API Key 与渠道配置排查。 |
一、爆款标题
- 把 AI 助手装进自己的电脑：OpenClaw 本地部署完整教程
- OpenClaw 保姆级部署指南：从 0 到 1 搭建本地 AI 管家
- 不只聊天：用 OpenClaw 搭建能执行任务的本地 AI 助手
- OpenClaw 怎么安装？Gateway、模型、Telegram、Docker 一篇搞定
二、文章摘要
OpenClaw 是一个面向个人与开发者的本地优先 AI 助手项目。它的核心不是单纯“问答聊天”，而是通过本地 Gateway 把模型、聊天渠道、工具、技能、记忆、工作区和自动化任务连接起来，让用户可以像给同事发消息一样，让 AI 帮你处理文件、执行命令、管理提醒、对接聊天软件，甚至结合代码工具完成自动化工作流。
这篇教程会从新手角度出发，完整讲清楚 OpenClaw 的安装准备、macOS/Linux/Windows/WSL2 部署、Docker 容器化部署、模型接入、Dashboard 验证、Telegram 等渠道配置、安全策略、更新维护和常见报错。
三、OpenClaw 是什么？
如果说 ChatGPT、Claude、Gemini 更像“网页里的 AI 对话窗口”，OpenClaw 更像一个“可以运行在你自己电脑上的 AI 助手中枢”。它通过本地 Gateway 管理会话、模型、工具、渠道和事件，再通过 Telegram、WhatsApp、Slack、Discord、Matrix、Teams 等入口与你交互。
| 模块 | 作用 | 新手理解 |
| Gateway | 本地控制平面，负责会话、渠道、工具和事件调度 | OpenClaw 的“大脑调度中心” |
| Dashboard / Control UI | 浏览器里的控制面板，可测试聊天、配置设备和查看状态 | 第一次安装后先从这里验证是否成功 |
| Agents | 不同助手角色或工作区，可绑定不同模型、工具和权限 | 可区分生活助手、代码助手、发布助手 |
| Models | 模型提供商与模型策略，支持主模型和 fallback | 可接 OpenAI、Anthropic、DeepSeek、Ollama、LM Studio 等 |
| Channels | 聊天入口，如 Telegram、WhatsApp、Slack、Discord、Matrix 等 | 让 AI 出现在你常用的聊天软件里 |
| Tools / Skills | 执行文件、浏览器、终端、定时任务、插件等能力 | 让 AI 不只回答，还能“做事” |
| 安全提醒：OpenClaw 可以接触文件、终端、聊天消息、浏览器和第三方账号，权限远高于普通聊天机器人。新手只建议从本机、本账号、可信模型和官方安装源开始，不要随便安装来路不明的 Skills、插件或第三方仓库。 |
四、安装前准备：先确认这 5 件事
| 准备项 | 建议配置 | 说明 |
| 操作系统 | macOS / Linux / Windows / WSL2 | Windows 用户优先推荐 WSL2，体验更接近 Linux，兼容性更好 |
| Node.js | Node 24 推荐，Node 22.14+ 也支持 | OpenClaw 官方文档明确要求 Node 24 或 Node 22.14+ |
| 模型账号 | 至少一个模型提供商 API Key 或 OAuth | 可选 OpenAI、Anthropic、Google、DeepSeek、OpenRouter，也可接本地模型 |
| 终端工具 | Terminal / PowerShell / Ubuntu WSL | 需要执行安装、启动、诊断和更新命令 |
| 安全意识 | 只从官方源安装，先本地测试 | 不要直接把 Gateway 暴露到公网；聊天渠道要启用配对和白名单 |
| node –version npm –version # 建议看到 Node 24.x，至少要 Node 22.14+ |
五、部署路线图：新手该选哪种安装方式？
| 安装方式 | 适合谁 | 优点 | 注意事项 |
| 官方安装脚本 | macOS / Linux / WSL2 新手 | 最快，自动处理 Node、OpenClaw 和 onboarding | 执行远程脚本前确认域名和来源 |
| Windows PowerShell 脚本 | 想在原生 Windows 上快速体验的人 | 不用先装 WSL，也能运行核心 CLI/Gateway | 官方仍更推荐 WSL2 作为完整体验路线 |
| npm / pnpm / bun 全局安装 | 已熟悉 Node 环境的开发者 | 命令透明，升级方便 | pnpm 全局安装后要 approve-builds |
| 源码安装 | 需要二次开发或调试的人 | 可改源码、插件和 UI | 依赖较多，需要 pnpm build |
| Docker / Docker Compose | VPS、NAS、隔离部署、长期在线 | 环境可复现，便于持久化和迁移 | 要处理端口、卷权限、token、防火墙 |
六、方式一：macOS / Linux / WSL2 推荐安装
这是最适合新手的路线。官方安装脚本会检测系统环境，必要时安装 Node，并引导进入 onboarding。
| curl -fsSL https://openclaw.ai/install.sh | bash |
安装完成后，执行：
| openclaw –version openclaw doctor openclaw gateway status |
如果你想先安装 CLI，不立即进入 onboarding，可以使用：
| curl -fsSL https://openclaw.ai/install.sh | bash -s — –no-onboard |
| 提示：onboarding 是 OpenClaw 的新手引导流程，会询问模型提供商、API Key、Gateway、工作区和渠道配置。大多数用户不建议跳过。 |
七、方式二：Windows 用户推荐 WSL2 路线
OpenClaw 支持原生 Windows 和 WSL2，但官方文档明确表示 WSL2 更稳定，适合完整体验。Windows 用户建议先安装 Ubuntu WSL，再在 WSL 内按 Linux 方式安装。
| # 以管理员身份打开 PowerShell wsl –install # 或指定 Ubuntu 版本 wsl –list –online wsl –install -d Ubuntu-24.04 |
进入 Ubuntu 后，建议启用 systemd，方便 OpenClaw Gateway 以用户服务方式运行：
| sudo tee /etc/wsl.conf >/dev/null <<‘EOF’ [boot] systemd=true EOF # 回到 PowerShell 执行 wsl –shutdown # 重新打开 Ubuntu 后验证 systemctl –user status |
然后在 WSL 内安装 OpenClaw：
| curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard –install-daemon openclaw gateway status |
| 安全提醒：WSL 内的 127.0.0.1 和 Windows 网络有时会涉及端口转发。如果要让手机或局域网设备访问 Gateway，不要盲目开放公网端口，应优先使用可信隧道、反向代理鉴权或仅限局域网。 |
八、方式三：原生 Windows PowerShell 安装
如果只是想快速体验 OpenClaw CLI 和 Gateway，也可以在 PowerShell 里直接安装：
| iwr -useb https://openclaw.ai/install.ps1 | iex |
如果不想立即进入 onboarding：
| & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard |
原生 Windows 上如需启动 Gateway：
| openclaw onboard –non-interactive –skip-health openclaw gateway run # 或尝试安装托管启动 openclaw gateway install openclaw gateway status –json |
| 提示：原生 Windows 的服务安装可能会尝试 Scheduled Task。如果系统策略阻止创建任务，OpenClaw 会退回到当前用户 Startup 文件夹方式。 |
九、方式四：npm / pnpm / bun 全局安装
如果你已经熟悉 Node 环境，可以直接用包管理器安装：
| # npm npm install -g openclaw@latest openclaw onboard –install-daemon # pnpm pnpm add -g openclaw@latest pnpm approve-builds -g openclaw onboard –install-daemon # bun bun add -g openclaw@latest openclaw onboard –install-daemon |
如果 npm 安装时出现 sharp / libvips 相关构建错误，可尝试：
| SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest |
十、方式五：Docker / Docker Compose 部署
Docker 适合想要容器化 Gateway、跑在 VPS/NAS、或需要隔离环境的人。官方说明 Docker 是可选路线：个人电脑快速体验通常用普通安装更简单。
| Docker 部署前检查 | 建议 |
| Docker 与 Compose | 安装 Docker Desktop 或 Docker Engine + Docker Compose v2 |
| 内存 | 至少 2GB；构建时如果 exit 137，通常是内存不足 |
| 磁盘 | 预留镜像、日志、workspace、media 和会话文件空间 |
| 公网访问 | 先读安全加固，不要直接裸奔暴露 18789 |
| 持久化 | 配置目录和工作区目录要挂载，否则容器重建会丢配置 |
典型 Docker 流程：
| git clone https://github.com/openclaw/openclaw.git cd openclaw ./scripts/docker/setup.sh |
如果想使用预构建镜像：
| export OPENCLAW_IMAGE=”ghcr.io/openclaw/openclaw:latest” ./scripts/docker/setup.sh |
启动后打开本地控制台：
| # 浏览器访问 http://127.0.0.1:18789/ # 或查看 Dashboard 链接 docker compose run –rm openclaw-cli dashboard –no-open |
健康检查命令：
| curl -fsS http://127.0.0.1:18789/healthz curl -fsS http://127.0.0.1:18789/readyz |
如果 Docker 目录出现权限错误：
| sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace |
| 提示：容器默认用户是 node（uid 1000）。如果宿主机挂载目录属于 root 或其他用户，常见现象就是 EACCES、无法写入配置、日志或 workspace。 |
十一、第一次启动：Onboarding 应该怎么选？
安装后执行下面命令进入向导：
| openclaw onboard –install-daemon |
向导通常会引导你完成以下几件事：
- 选择模型提供商：OpenAI、Anthropic、Google、DeepSeek、OpenRouter、本地 OpenAI-compatible 服务等。
- 填写或授权 API Key / OAuth。
- 创建 Gateway 配置，默认监听本地端口 18789。
- 安装 daemon / user service，让 Gateway 后台常驻。
- 配置基础 workspace、默认 agent 和 Dashboard 访问。
完成后检查：
| openclaw gateway status openclaw dashboard openclaw doctor |
| 提示：如果 Dashboard 能打开，并且本地聊天可以正常回复，说明基础部署已经跑通。此时再去配置 Telegram、WhatsApp、Slack 等外部渠道会更稳。 |
十二、模型配置：云端模型、本地模型都能接
OpenClaw 的模型策略可以理解为“主模型 + fallback”。主模型负责高质量推理，fallback 可用于备用、降本或应对限流。官方模型命令可查看状态、列表、设置默认模型和 fallback。
| 模型来源 | 典型选择 | 适合场景 |
| OpenAI / Anthropic / Google | GPT、Claude、Gemini 系列 | 综合能力强，适合工具调用和复杂任务 |
| DeepSeek / Qwen / GLM / Doubao | 中文模型或国内 API | 中文内容创作、国内网络环境 |
| OpenRouter / LiteLLM | 统一代理多个模型 | 想集中管理多模型和 fallback |
| Ollama / LM Studio | 本地 OpenAI-compatible 服务 | 隐私、本地测试、小模型任务 |
| vLLM / LocalAI | 本地或服务器模型 API | 高并发、生产 API、私有部署 |
常用模型命令：
| openclaw models status openclaw models list openclaw models list –all openclaw models set <provider/model> openclaw models fallbacks add <provider/model> openclaw models fallbacks list |
在聊天里也可以用斜杠命令切换当前会话模型：
| /model /model list /model 3 /model openai/gpt-5.4 /model status |
| 安全提醒：不要只追求便宜或小模型。能执行工具、读写文件、调用浏览器的 agent 对模型可靠性要求更高。对于重要自动化任务，建议优先使用你信任的强模型，并为低风险任务单独设置便宜 fallback。 |
十三、接入 Telegram：最适合新手的手机聊天入口
如果你想在手机上和 OpenClaw 聊天，Telegram 通常是最快的入门渠道：只需要创建 Bot，拿到 Bot Token，再写入 OpenClaw。
- 在 Telegram 搜索 BotFather，创建一个新 Bot。
- 复制 BotFather 返回的 Bot Token。
- 在本机执行渠道添加命令。
| openclaw channels add –channel telegram –token “<你的 Bot Token>” openclaw gateway restart |
Docker 部署时使用 CLI 容器执行：
| docker compose run –rm openclaw-cli channels add –channel telegram –token “<你的 Bot Token>” |
| 安全提醒：把 Telegram Bot 当成“入口门禁”。不要公开转发 token，不要把机器人拉进陌生群，初期建议启用 pairing/allowlist，只允许自己或可信账号发消息。 |
十四、配置安全：本地 AI 助手最容易被忽视的一步
OpenClaw 的强大之处在于它能“做事”，这也意味着风险更高。官方文档提醒：OpenClaw 连接真实消息渠道时，应把外部 DM 视为不可信输入。默认策略通常使用 pairing：未知发送者只能收到配对码，不会被直接处理。
| 安全项 | 建议设置 | 原因 |
| DM pairing | 保持 pairing，手动 approve 可信用户 | 避免陌生人直接驱动你的 agent |
| allowlist | 只允许自己的账号或可信群组 | 减少提示注入和越权指令 |
| Sandbox | 非 main 会话启用 non-main sandbox | 群聊、多人协作、未知输入应隔离执行 |
| Skills / Plugins | 只装官方或审计过的插件 | 插件可能拥有文件、命令和网络权限 |
| Gateway 暴露 | 默认只本地访问；公网部署加反代鉴权和防火墙 | 裸露端口风险高 |
| 日志与备份 | 保留配置备份，定期查看 doctor 输出 | 便于排错和回滚 |
配对审批示例：
| openclaw pairing approve <channel> <code> |
沙箱配置示例：
| { “agents”: { “defaults”: { “sandbox”: { “mode”: “non-main”, “scope”: “agent” } } } } |
构建默认沙箱镜像：
| scripts/sandbox-setup.sh |
十五、结合本地自动化：让 OpenClaw 帮你做网站发布任务
对于 AI 工具站、自媒体站或技术博客站，OpenClaw 的价值在于可以把“聊天指令”变成“可执行工作流”。例如：让它检查选题、生成文章、调用本地脚本、整理素材、触发 WordPress REST API 自动发文。
| 工作流环节 | OpenClaw 可以做什么 | 建议做法 |
| 选题收集 | 定时读取 RSS、网页、文件夹、表格 | 先让 agent 只输出候选清单，不直接发布 |
| 文章生成 | 根据标题生成正文、FAQ、SEO 信息 | 固定模板，要求输出 Markdown / JSON |
| 素材整理 | 下载封面、生成图片说明、整理链接 | 图片和外链要人工复核版权和来源 |
| 脚本执行 | 调用 Python 发布脚本、检查返回结果 | 只给脚本目录最小权限，不开放全盘写入 |
| 发布前审核 | 生成预览、检查分类、标签和摘要 | 关键任务保留“人工确认”步骤 |
| 发布后复盘 | 记录文章 URL、时间、状态和报错 | 写入日志或表格，方便追踪 |
| # 示例：让本地 agent 检查发文清单 openclaw agent –message “检查 ~/ai_web_bot/draft.md 和 meta.json，确认是否符合 WordPress 发布要求，只给出问题清单，不要执行发布。” –thinking high |
| 安全提醒：涉及邮箱、日历、网站后台、支付、服务器 SSH、数据库等高权限动作时，不建议让 agent 完全自动执行。更稳妥的做法是：AI 生成命令或草稿，人确认后再运行。 |
十六、更新、维护与健康检查
OpenClaw 更新频繁，建议养成“先 update，再 doctor，最后 restart/health”的习惯。
| openclaw update openclaw doctor openclaw gateway restart openclaw health |
如果想预览更新但不立即应用：
| openclaw update –dry-run |
如果需要切换 beta 或指定标签：
| openclaw update –channel beta openclaw update –tag main |
npm 回滚到指定版本：
| npm i -g openclaw@<version> openclaw doctor openclaw gateway restart |
| 提示：建议在重大更新前备份 ~/.openclaw 目录，尤其是 channels、credentials、workspace、agents、openclaw.json 等配置和状态文件。 |
十七、常见问题排查
| 问题 | 排查命令 | 解决方向 |
| openclaw: command not found | node -v / npm prefix -g / echo $PATH | 把 npm 全局 bin 目录加入 PATH，重新打开终端 |
| Gateway 没启动 | openclaw gateway status | 执行 openclaw gateway restart 或重新 run/onboard |
| Dashboard 打不开 | openclaw dashboard / curl 127.0.0.1:18789/healthz | 确认端口、token、防火墙、Docker 映射 |
| 模型不允许 / 不回复 | openclaw models status / /model list | 调整 agents.defaults.models allowlist 或设置有效模型 |
| API Key 无效 | openclaw models status –probe | 重新写入 provider auth 或检查账号额度 |
| Docker exit 137 | docker compose logs | 通常是内存不足，换大机器或减少构建负载 |
| Docker EACCES | ls -la 挂载目录 | chown 到 uid 1000 或调整挂载权限 |
| WSL systemd 不可用 | systemctl –user status | 编辑 /etc/wsl.conf，wsl –shutdown 后重启 |
| Telegram 没反应 | 检查 token、BotFather、渠道配置 | 确认 pairing/allowlist、gateway logs 与 webhook/polling 状态 |
十八、FAQ
1. OpenClaw 和 ChatGPT 有什么区别？
ChatGPT 更像云端对话产品，OpenClaw 更像本地优先的 AI 助手框架。它可以连接聊天渠道、模型、工具、文件、终端、定时任务和插件，让 AI 不只回答问题，还能执行操作。
2. 新手应该用 Docker 还是普通安装？
个人电脑新手建议先用普通安装脚本或 npm 安装；Docker 更适合 VPS、NAS、长期在线、隔离测试或团队部署。
3. Windows 用户一定要 WSL2 吗？
不是必须，但官方文档推荐 WSL2 作为更稳定的完整体验路线。原生 Windows 可运行核心 CLI/Gateway，但部分服务和工具链兼容性不如 WSL2。
4. 可以接本地大模型吗？
可以。你可以通过 Ollama、LM Studio、vLLM、LocalAI 等提供 OpenAI-compatible API，再在 OpenClaw 中配置为模型提供商或自定义 endpoint。
5. 默认端口是多少？
常见本地 Gateway 端口是 18789，Dashboard 通常可通过 http://127.0.0.1:18789/ 访问。
6. 为什么 Dashboard 提示未授权或需要 pairing？
通常是 token、设备审批或安全策略问题。重新运行 openclaw dashboard 获取链接，或用 devices list / devices approve 完成审批。
7. OpenClaw 能不能接 Telegram？
可以。新手常用 Telegram Bot Token 接入，步骤相对简单，适合先在手机上测试 AI 助手。
8. 要不要把 Gateway 暴露到公网？
不建议新手直接暴露。OpenClaw 拥有较高权限，公网部署必须考虑认证、防火墙、反向代理、TLS、IP 限制、日志审计和安全更新。
9. Skills 和 Plugins 可以随便装吗？
不可以。第三方 Skills/Plugins 可能包含危险命令或恶意脚本，只应安装官方、可信、可审计的扩展。
10. 更新后出问题怎么办？
先运行 openclaw doctor 查看迁移和配置问题，再 restart/health。如果仍不行，可回滚到指定 npm 版本或使用备份恢复配置。
官方参考来源
| 来源 | 链接 |
| OpenClaw GitHub README | https://github.com/openclaw/openclaw |
| OpenClaw 官网 | https://openclaw.ai/ |
| OpenClaw Getting Started | https://docs.openclaw.ai/start/getting-started |
| OpenClaw Install Overview | https://docs.openclaw.ai/install |
| OpenClaw Windows 平台说明 | https://docs.openclaw.ai/platforms/windows |
| OpenClaw Docker 部署文档 | https://docs.openclaw.ai/install/docker |
| OpenClaw Models CLI | https://docs.openclaw.ai/concepts/models |
| OpenClaw Updating | https://docs.openclaw.ai/install/updating |
| OpenClaw Releases | https://github.com/openclaw/openclaw/releases |
