这是一份基于真实对话和实操整理的详细避坑指南，带你从零开始在本地使用 Node.js 成功部署和配置 OpenClaw。
阶段一：前置准备与安装
Q: 我该怎么安装 OpenClaw？需要什么环境？ A: OpenClaw 的运行底座是 Node.js。如果你还没安装 Node，推荐使用 nvm (Node Version Manager) 来下载最新的企业稳定版。 在终端执行：
nvm install latest
nvm use <你下载的最新版本号，例如 25.8.1>
环境就绪后，直接通过 npm 包管理器全局安装它，npm版本最好24以上：
npm install –g openclaw@latest
新手疑团： 终端里出现了红黄色的 npm warn deprecated node-domexception@1.0.0… 是什么意思？ 解答： 这是极正常的现象！它只是个开发者级别的包过时“警告(warn)”，只要最后看到类似 changed 555 packages in 39s 字眼，就代表安装毫无问题，大功告成。
阶段二：配置向导 (Onboarding)
顺利安装核心程序后，我们需要给这个龙虾装上“大脑”并设定各项喜好。 在终端输入并运行以下初始化命令：
openclaw onboard —install-daemon
随后，你的终端屏幕会变成深色交互面板（可以使用键盘 ↑/↓ 上下箭头选择，Enter 确认）：
1. 选择大模型提供商 (Model/auth provider)
终端画面图示：弹出一列如 OpenAI、Anthropic、Google、DeepSeek、Minimax 等供你挑选 实录对话：
- Q：我怎么获取 Gemini 的 API Key？
- A: 去 Google AI Studio 登录账号，点击 Create API Key，复制那一长串字符。
- Q：通义千问大模型 (Qianwen) 的怎么获取？
- A: 去阿里云百炼控制台，开通大模型服务后，在 API-KEY 管理界面点击创建新 Key，复制以 sk- 开头的代码。然后在列表里选对应的服务商粘贴进去。
- Q：我想用 DeepSeek 的 API Key 呢！性价比高！
- A: 去 DeepSeek 开放平台 注册并进入“API Keys”，创建并复制你的专属 Key（离开页面后将无法再次查看完整 Key）。回到咱们的终端：
- 如果列表里有 DeepSeek，直接选中回车，并在提示时粘贴你的 API Key。
- 如果列表里没有直接写着 DeepSeek 的选项，你可以选择 OpenAI（两者接口完全兼容），在弹出的提示中填入你复制的 sk- 开头的 API Key。
- 接着它可能会要求你填写 API Base URL（自定义服务器地址），你需要输入：https://api.deepseek.com/v1 （或 https://api.deepseek.com）。
- 如果还需要手动填写模型名字（Model Name），填 deepseek-chat 或 deepseek-reasoner 即可体验最强逻辑模型。
2. 选择聊天渠道 (Select channel – QuickStart)
终端画面图示：弹出一列如 Telegram(Bot API)、Discord、飞书，以及往下隐藏的更多选项 实录对话：
- Q：我希望使用 QQ 作为前端聊天界面，怎么选？
- A: 往下滚动，选择 NapCatQQ (Websocket API) 选项。【避坑建议】 如果你没有折腾过 NapCatQQ（需要额外搭一个登录端），我非常建议小白第一次玩时，直接拉到最后选择 Web 网页版或者 Terminal 来快速体验。
3. 选择网页搜索提供商 (Search provider)
终端画面图示：弹出一列如 Brave Search, Gemini Google Search 等搜索引擎供大模型联网
- 建议操作： 对于首次测试的新手，直接拉到最底部选择 Skip for now (暂且跳过)。跳过后龙虾仍能对话写代码，只是暂不能去百度/谷歌实时冲浪。日后随时可加。
4. 安装技能依赖包 (Install missing skill dependencies)
终端画面图示：询问是否要一揽子安装 1password, github, camsnap 等一大串关联工具
- 建议操作： 强烈建议将光标留在第一行的 □ Skip for now 并按回车。
- 原因： 一次性装太多无关环境在 Windows 下极易因缺少 C++ 工具链报错。我们核心先跑起来，后面真需要让它接管你相册或 Github 时，再单独运行命令给它装。
5. 开启内部钩子 (Enable hooks)
终端画面图示：四个hooks，包含 boot-md, session-memory 等
- 建议操作： 全选！ 这几个是极其实用的自带扩展（比如自动记录你上次跟它聊到哪的“会话记忆”功能），不用白不用。
到这一步，你会看到一条红色字体的祝贺信息： Onboarding complete. Dashboard opened; keep that tab to control OpenClaw. （初始化结束！控制台面板已经为你打开！）
阶段三：运行后台并排查错误
本以为这就结束了，但在最后的“点火”阶段，我们遇上了拦路虎：
Q: 网页突然弹出来了，但是页面是一个错误文档图标，显示 ERR_CONNECTION_REFUSED 拒绝连接 ，这是怎么回事？ A: 因为虽然初始化完事儿了，但你的本地 Web 服务器（守护进程/Daemon）并没启动起来！
Q: 我该输入 openclaw start 启动它吗？终端报错 unknown command 'start'。 A: 不对，启动这只龙虾正确的长效命令是：
openclaw gateway
注意： 运行这个命令后终端会持续输出运行日志。只要你想用控制面板，这个黑终端窗口绝不能关掉！
Q: 我输入了 gateway 命令，它提示 Gateway failed to start: gateway already running (pid XXX) 是坏了吗？ A: 这是个好消息，说明你误打误撞或者通过内置唤醒，后台已经有一个实例跑起来了，不用管它！ 此时，你直接回到那个报“拒绝连接”的浏览器页面，按下键盘的 F5 刷新 —— 真正的图形化控制台 Dashboard 就展现出来了！
番外：进阶疑难杂症（或者使用npm install -g openclaw@2026.3.8回退版本可彻底解决）
Q: 历经千辛万苦刷新出来了，结果聊天页面主屏幕出现了一个超级大的“感叹号⚠”！怎么修？
- A: 这代表当前的会话状态卡死了或者你的大模型配置(API Key没钱/连不上)出错了。你可以试试绝招，通过别的终端强制给它发命令打破僵局：
openclaw agent —session-id main –m "删掉旧会话窗口，创建新会话窗口"
这个命令的厉害之处在于：它会绕过前端界面，在底层强行唤醒龙虾本体来帮你修自己的 Bug。（其实如果这招不奏效，最简单的终极必杀：把那个跑着 openclaw gateway 的黑窗 Ctrl+C 关了重开，包治百病。）
扩展：进如何接入qq
- A: 接入qq教程https://cloud.tencent.com/developer/article/2626045
