夜雨聆风最近几个月深度调研了 OpenClaw，在各种复杂环境下踩了不少坑，终于整理出一套最稳的安装与配置说明。如果你在部署时遇到障碍，欢迎找我交流，希望能帮你省下反复 Debug 的时间。在 OpenClaw 的基础上，我也在同步推进 Hermes、Harness等 Agent 框架的实战应用。目前在电商自动化、深度数据分析、业务流程自动化等场景已有成熟方案。如果你有相关需求或想一起折腾 Agent，欢迎随时勾搭。
很多人第一次接触 OpenClaw，会觉得它像一个“能聊天的 Agent 框架”。但真正上手之后就会发现，OpenClaw 的价值远不只是聊天，而是把 模型、工具、记忆、渠道接入、多 Agent 协作 放进了一套可运行、可扩展的系统里。
如果只是把命令装上去，OpenClaw 并不算复杂；真正容易卡住的地方，往往出现在 Node 环境、模型配置、记忆能力、渠道绑定、Windows 权限和多 Agent 路由 这些细节上。
这篇文章就按照完整落地顺序，把 OpenClaw 从安装到可用的过程系统讲清楚：
环境准备 Node 与 pnpm 安装 OpenClaw 安装与初始化 模型配置 Memory 记忆能力配置 ClawHub 与技能体系 浏览器扩展 Feishu / 企业微信接入 多 Agent 配置 Windows 常见问题 安装后的检查方法
一、先认识几类配置字段
在 OpenClaw 的配置过程中，经常会看到一些固定字段。理解这些字段的含义，比死记命令更重要。
1.1 模型相关字段
<MODEL_BASE_URL>：模型服务地址，也就是 OpenClaw 请求大模型时要访问的接口地址 <MODEL_API_KEY>：模型服务的鉴权密钥 api：接口协议类型，例如 openai-responses、anthropic-messagesmodels：该 provider 下可调用的模型列表 id：模型的真实 ID name：模型显示名称 reasoning：是否支持推理模式 input：支持的输入类型，例如 text或image
1.2 渠道相关字段
<FEISHU_APP_ID>：飞书应用的 App ID <FEISHU_APP_SECRET>：飞书应用的 App Secret <WECOM_BOT_ID>：企业微信机器人 ID <WECOM_SECRET>：企业微信机器人密钥 accountId：某个渠道账号在 OpenClaw 里的内部标识 agentId：某个 Agent 的内部标识 bindings：路由规则，用于决定哪个渠道账号交给哪个 Agent 处理
1.3 权限与登录相关字段
<CLAWHUB_TOKEN>：ClawHub 登录令牌 <OPERATOR_TOKEN>：高权限操作令牌 <YOUR_TOKEN>：任意需要手动填入的 token 占位词 <GATEWAY_TOKEN>：gateway 或审批通信相关的 token
简单理解就是：
- URL / Base URL
决定往哪里发请求 - Key / Secret / Token
决定有没有权限发请求 - accountId / agentId / bindings
决定消息最终由谁处理
二、安装前准备：先把基础环境搭起来
在安装 OpenClaw 之前，建议先准备好以下几项：
Git Node.js pnpm 稳定网络环境 代理工具（如有需要）
如果终端使用频率较高，也可以顺手配置一个常用别名：
bash echo"alias ll='ls -alhF'" >> ~/.bashrcsource ~/.bashrcecho"alias ll='ls -alhF'" >> ~/.zshrcsource ~/.zshrc
这不是必须步骤，但对后续查看目录、排查问题会方便很多。
三、安装 Git、nvm 和 Node.js
OpenClaw 对 Node 环境比较敏感，因此推荐使用 nvm 管理 Node 版本，而不是直接手装一个固定版本。
3.1 Git 下载地址
Windows
Git for Windows：https://gh.llkk.cc/https://github.com/git-for-windows/git/releases/download/v2.53.0.windows.1/Git-2.53.0-64-bit.exe
Git 官方地址：https://git-scm.com/download/win
macOS / Linux
可直接使用系统包管理器安装，或访问：https://git-scm.com/downloads
3.2 nvm 下载与安装
Windows
nvm-windows：https://gh.llkk.cc/https://github.com/coreybutler/nvm-windows/releases/download/1.2.2/nvm-setup.exe
GitHub 项目地址：https://github.com/coreybutler/nvm-windows
Linux / macOS
任选以下任一命令：
bash wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
或：
bash curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
nvm 官方仓库：https://github.com/nvm-sh/nvm
3.3 配置 Node 与 npm 镜像
如果网络环境一般，建议先配置国内镜像：
bash nvm node_mirror https://npmmirror.com/mirrors/node/nvm npm_mirror https://npmmirror.com/mirrors/npm/
镜像站：https://npmmirror.com/
3.4 安装 Node 24
bash nvm install 24nvm use 24
建议统一使用 Node 24。原因很简单：
版本一致更方便排查问题 减少跨机器兼容性差异 后面安装 OpenClaw、pnpm、浏览器能力时更稳
四、安装 pnpm
Node 环境准备好之后，就可以安装 pnpm 了：
bash npm config set registry https://registry.npmmirror.comnpm config get registrynpm install -g pnpmpnpm setuppnpm config set registry https://registry.npmmirror.com
如果执行完 pnpm setup 后命令没有立即生效，可以刷新 shell：
bash source ~/.bashrc
pnpm 官网：https://pnpm.io/
五、正式安装 OpenClaw 与 ClawHub
完成 Node 与 pnpm 安装后，接下来就可以安装主程序。
bash pnpm add -g openclaw@latestpnpm add -g clawhub@latest
安装完成后，先检查命令是否生效：
bash openclaw --helpclawhub --help
OpenClaw 文档地址：https://docs.openclaw.ai
OpenClaw GitHub：https://github.com/openclaw/openclaw
ClawHub：https://clawhub.ai
OpenClaw 社区 Discord：https://discord.com/invite/clawd
六、首次初始化：安装完成不等于可用
OpenClaw 安装结束后，还要做一轮初始化和修复。
6.1 执行初始化
bash openclaw onboard --install-daemon
6.2 执行自动修复
bash openclaw doctor --fix
6.3 配置基础权限与行为
bash openclaw config set tools.profile fullopenclaw config set channels.feishu.requireMention false
这几条命令分别对应：
onboard：完成系统引导和 daemon 安装 doctor --fix：自动修复常见问题 tools.profile full：启用更完整的工具能力 channels.feishu.requireMention false：让飞书群聊场景下不必强制 @ 才响应
如果目标只是“先把 OpenClaw 跑起来”，做到这里已经完成了最核心的一段。
七、模型配置：决定 OpenClaw 是否真正能工作
OpenClaw 的核心能力依赖模型。命令安装再顺，只要模型没接好，系统依然跑不起来。
7.1 最基础的模型配置结构
json {"models":{"mode":"merge","providers":{"openai":{"baseUrl":"<MODEL_BASE_URL>","apiKey":"<MODEL_API_KEY>","api":"openai-responses","models":[{"id":"gpt-5.4","name":"gpt-5.4","reasoning":true,"input":["text","image"]}]}}}}
这段结构可以理解为：
provider 名称叫 openai请求地址是 <MODEL_BASE_URL>使用 <MODEL_API_KEY>鉴权挂载了一个 gpt-5.4模型
7.2 多 provider 配置示例
如果要同时接多个模型服务商，可以这样写：
json {"models":{"mode":"merge","providers":{"openai":{"baseUrl":"<MODEL_BASE_URL>","apiKey":"<MODEL_API_KEY>","api":"openai-responses","models":[{"id":"gpt-5.3-codex","name":"gpt-5.3-codex","reasoning":true,"input":["text"]}]},"anthropic":{"baseUrl":"<MODEL_BASE_URL>","apiKey":"<MODEL_API_KEY>","auth":"api-key","api":"anthropic-messages","models":[{"id":"claude-opus-4-6","name":"Claude Opus 4.6","api":"anthropic-messages","reasoning":false,"input":["text"]},{"id":"claude-sonnet-4-6","name":"Claude Sonnet 4.6","api":"anthropic-messages","reasoning":false,"input":["text"]}]}}}}
7.3 设置主模型与备用模型
建议在接入模型之后，顺手把主模型与备用模型也设好。
例如：
bash openclaw config set agents.defaults.model.primary openai/gpt-5.4openclaw config set agents.defaults.model.fallbacks.0 minimax/MiniMax-M2.7
也可以这样配：
bash openclaw config set agents.defaults.model.primary anthropic/claude-sonnet-4-5-20250929openclaw config set agents.defaults.model.fallbacks.0 openai/gpt-5.4
这样做的意义在于：主模型异常时，系统仍然可以自动切换到备用模型，避免整个流程直接断掉。
7.4 预留上下文压缩空间
bash openclaw config set agents.defaults.compaction.reserveTokensFloor 200000
如果后续会频繁处理长文档、复杂任务或多轮上下文，这个配置很有价值。
7.5 模型配置最容易错的地方
真正排查模型问题时，优先看下面几项：
baseUrl是否正确 api类型是否匹配 auth写法是否正确 apiKey是否失效 模型 id是否与 provider 实际支持的名称一致图像输入模型是否误配成纯文本模型
结论非常直接：OpenClaw 真正能不能工作，不是看装没装成功，而是看模型链路有没有打通。
八、Memory 记忆能力配置
如果希望 Agent 拥有长期记忆和语义检索能力，就需要配置 memorySearch。
8.1 下载 embedding 模型
使用 Ollama 时，可以先拉取 embedding 模型：
bash ollama pull ryanshillington/Qwen3-Embedding-0.6B
其他可选模型：
bash ollama pull nomic-embed-textollama pull mxbai-embed-large
Ollama 官网：https://ollama.com/
8.2 memorySearch 配置示例
json {"memorySearch":{"enabled":true,"provider":"openai","model":"ryanshillington/Qwen3-Embedding-0.6B:latest","fallback":"none","remote":{"baseUrl":"http://127.0.0.1:11434/v1","apiKey":"ollama-local","batch":{"enabled":false}},"store":{"driver":"sqlite"}}}
8.3 建立索引与检查状态
bash openclaw memory status --deepopenclaw memory index --verboseopenclaw memory search "你的搜索关键词"
8.4 配置 memory 时要注意什么
先确认 Ollama 服务已启动 embedding 模型体积不同，占用资源不同 首次索引通常需要一些时间 如果 memory status --deep异常，优先排查 embedding 服务与本地接口
大多数情况下，记忆功能的问题并不是 OpenClaw 主程序坏了，而是 embedding 模型、Ollama 服务、索引状态 这三件事没有对齐。
九、ClawHub 登录与技能体系
如果后续要安装技能、同步技能、扩展能力，通常还需要登录 ClawHub。
bash clawhub auth login --no-browser --token <CLAWHUB_TOKEN>
ClawHub 官网：https://clawhub.ai
常见技能方向包括：
find-skill weather proactive-agent self-improving / self-improving-agent github skill-vetter akshare-stock stock-price-query stock-screener-cn market-analysis-cn duckduckgo-search openclaw-tavily-search
如果要把 OpenClaw 用在更长期的项目里，比较推荐把技能体系按用途拆分成几类：
通用能力包 自动化与浏览器包 数据分析包 股票分析包 自我改进与工作流包
十、浏览器扩展安装
如果需要浏览器自动化能力，可以执行（注意 在2026.3.28以及之后的版本就不需要了）：
bash openclaw browser extension installopenclaw browser extension path
适用场景包括：
页面自动化采集 浏览器页面交互 和本地浏览器协同处理任务
如果扩展已经安装，但浏览器能力还是不可用，优先检查：
扩展路径是否正确 浏览器端是否已加载扩展 本地浏览器是否满足运行要求
十一、飞书 Feishu 接入
很多用户真正把 OpenClaw 用起来时，第一条接入渠道通常是 Feishu。 这一部分最关键的，不是配置格式本身，而是 accountId、agentId、bindings 三者能否严格对齐。
11.1 Feishu channels 配置示意
json {"channels":{"feishu":{"enabled":true,"accounts":{"default":{"appId":"<FEISHU_APP_ID>","appSecret":"<FEISHU_APP_SECRET>","botName":"DGX小龙虾","dmPolicy":"open"},"tracer-fs":{"appId":"<FEISHU_APP_ID>","appSecret":"<FEISHU_APP_SECRET>","botName":"Tracer","dmPolicy":"open"},"clawa-fs":{"appId":"<FEISHU_APP_ID>","appSecret":"<FEISHU_APP_SECRET>","botName":"虾秘书","dmPolicy":"open"}},"connectionMode":"websocket","domain":"feishu","groupPolicy":"open"}}}
飞书开放平台：https://open.feishu.cn/
11.2 bindings 路由配置示意
json {"bindings":[{"type":"route","agentId":"main","match":{"channel":"feishu","accountId":"default"}},{"type":"route","agentId":"tracer","match":{"channel":"feishu","accountId":"tracer-fs"}},{"type":"route","agentId":"clawa","match":{"channel":"feishu","accountId":"clawa-fs"}}]}
11.3 Feishu 配置时最容易错的地方
accountId与 bindings 不一致 agentId实际并不存在 改完配置后忘记重启 gateway 多账号命名混乱，后面无法维护
所以更推荐一开始就统一命名规范，例如：
defaulttracer-fsmarcus-fsmarketer-fs
配置修改完成后，执行：
bash openclaw gateway restart
十二、企业微信 WeCom 接入
如果不走 Feishu，而是要接企业微信，也遵循同样的思路：先配置 channels，再配置 bindings。
12.1 WeCom channels 配置示意
json {"channels":{"wecom":{"enabled":true,"defaultAccount":"default","accounts":{"default":{"botId":"<WECOM_BOT_ID>","secret":"<WECOM_SECRET>"},"agent1_app":{"botId":"<WECOM_BOT_ID>","secret":"<WECOM_SECRET>"},"agent2_app":{"botId":"<WECOM_BOT_ID>","secret":"<WECOM_SECRET>"}},"allowFrom":[],"dmPolicy":"open"}}}
企业微信开放平台：https://developer.work.weixin.qq.com/
12.2 WeCom bindings 配置示意
json {"bindings":[{"agentId":"main","match":{"channel":"wecom","accountId":"default"}},{"agentId":"agent_a","match":{"channel":"wecom","accountId":"agent1_app"}},{"agentId":"agent_b","match":{"channel":"wecom","accountId":"agent2_app"}}]}
12.3 WeCom 配置注意点
botId和 secret要与实际机器人一致channels 与 bindings 必须同步修改 多机器人接入时，一定要确认 accountId和agentId一一对应
十三、多 Agent 配置
OpenClaw 支持多 Agent，这是它在复杂业务场景里非常有价值的一部分。 但多 Agent 越多，配置难度也会同步上升。
13.1 添加 Agent
bash openclaw agents add exp
13.2 打开 Agent-to-Agent 能力
bash openclaw config set tools.agentToAgent.enabled trueopenclaw config set tools.agentToAgent.allow '["main","coding","review"]' --strict-jsonopenclaw config set tools.sessions.visibility "all"openclaw gateway restart
13.3 多 Agent 的本质是什么
很多人理解多 Agent，只停留在“多建几个角色”。 但在实际部署里，多 Agent 的本质不是“建几个名字”，而是：
哪个渠道账号进来 被哪个 Agent 接住 是否允许 Agent 之间互相调用 是否允许跨会话可见
所以多 Agent 出问题时，最先检查的一定不是代码，而是：
bindings 是否完整 agentId 是否正确 accountId 是否对齐 gateway 是否已重启
十四、Windows 下最容易踩的坑
如果是在 Windows 环境部署 OpenClaw，需要额外注意三个问题：
PowerShell 权限 路径配置 残留 node 进程
14.1 PowerShell 执行策略
如果脚本执行受限，可以执行：
powershell Set-ExecutionPolicy-ExecutionPolicy RemoteSigned -Scope CurrentUser
14.2 Git 网络兼容设置
bash git config --global http.sslverify "false"git config --global url."https://".insteadOf git://
这里需要特别说明：
url."https://".insteadOf git://主要用于兼容某些拉取方式 http.sslverify false会降低安全性，适合明确存在证书问题时临时排查，不建议长期默认开启
14.3 control-ui 路径问题
如果遇到类似下面的错误：
text Not foundC:\Users\Administrator\AppData\Local\pnpm\global\5\node_modules\openclaw\dist\control-ui
可以显式指定路径：
json {"controlUi":{"root":"C:\\Users\\Dell\\.openclaw\\control-ui"}}
14.4 Windows 启动 bat 示例
bat @echo offsetlocalchcp65001 >nultitle OpenClaw Gateway (UTF-8)echo [1/3] 正在关闭所有 Node.js 进程...taskkill /F /IM node.exe >nul2>nulif%errorlevel%==0 (echo 已关闭 node.exe) else (echo 未发现运行中的 node.exe（或无需关闭）)echo.echo [2/3] 启动 OpenClaw Gateway...openclaw gatewayREM 如果上面命令不可用，用：REM npx openclaw gatewayecho.echo [3/3] Gateway 已退出pauseendlocal
这个脚本的作用很明确：
切换控制台为 UTF-8 关闭旧的 Node 进程 启动 OpenClaw gateway
对于 Windows 用户来说，这类 bat 脚本很实用。
十五、执行权限与高敏感配置
在一些部署资料中，经常会混入：
exec approvals 配置 socket token operator token 审批与高权限操作配置
这些内容属于高敏感信息，理解结构是有必要的，但不适合直接写真实值。
例如：
json {"version":1,"socket":{"path":"/root/.openclaw/exec-approvals.sock","token":"<GATEWAY_TOKEN>"},"defaults":{"security":"full","ask":"off","askFallback":"full","autoAllowSkills":true}}
以及：
json {"version":1,"deviceId":"<DEVICE_ID>","tokens":{"operator":{"token":"<OPERATOR_TOKEN>","role":"operator","scopes":["operator.read","operator.admin","operator.write","operator.approvals","operator.pairing"]}}}
理解这些结构的意义在于：
socket.path表示本地通信通道位置 token表示通信鉴权凭证 security表示默认执行安全级别 ask表示是否默认需要批准 operator表示高权限操作身份 scopes表示该身份可执行的权限范围
如果此前这些真实值已经出现在共享文档中，后续应该考虑及时轮换。
十六、安装完成后，按这个顺序检查
真正稳定的安装，不是命令执行完就结束，而是要做一次完整自检。
16.1 检查主程序
bash openclaw --help
16.2 检查 gateway
bash openclaw gateway status
16.3 检查 memory
bash openclaw memory status --deep
16.4 检查浏览器扩展
bash openclaw browser extension path
16.5 检查模型链路
重点确认：
baseUrl是否正确 apiKey是否正确 provider 协议是否匹配 主模型与 fallback 是否生效
16.6 检查渠道路由
重点确认：
channels中账号是否存在 bindings中 accountId 与 agentId 是否对应 gateway 是否已经重启
十七、适合新手的最短安装路径
如果目标只是快速把 OpenClaw 跑起来，可以先走最短路径：
bash # 1. 安装 Node 24nvm install 24nvm use 24# 2. 安装 pnpmnpm install -g pnpmpnpm setup# 3. 安装 OpenClaw 与 ClawHubpnpm add -g openclaw@latestpnpm add -g clawhub@latest# 4. 初始化openclaw onboard --install-daemon# 5. 自动修复openclaw doctor --fix# 6. 设置基础配置openclaw config set tools.profile fullopenclaw config set channels.feishu.requireMention false
在这套流程基础上，再逐步补上：
模型 provider memorySearch 浏览器扩展 Feishu / WeCom 多 Agent
这种写法也最适合做成公众号里的“快速上手版”。
十八、最后总结
如果只看安装命令，OpenClaw 并不复杂；真正容易卡住的地方，通常集中在这些环节：
Node 版本不统一 pnpm setup 后没有刷新 shell 模型 provider 配错 accountId、agentId、bindings 对不上 修改完配置忘了重启 gateway Windows 权限与路径没处理干净 Memory 依赖的本地 embedding 服务没启动 多 Agent 之间没有形成清晰的路由结构
所以更准确地说：OpenClaw 难的不是“安装”，而是“把模型、渠道、记忆、Agent 路由和权限体系一起配置正确”。
一旦把这些基础设施搭好，OpenClaw 才真正从一个命令行工具，变成一套可长期运行、可不断扩展的 Agent 系统。
参考链接汇总
OpenClaw
官方文档：https://docs.openclaw.ai GitHub：https://github.com/openclaw/openclaw 社区 Discord：https://discord.com/invite/clawd
ClawHub
官网：https://clawhub.ai
Git
官网：https://git-scm.com/ Windows 下载：https://git-scm.com/download/win
nvm
nvm（Linux / macOS）：https://github.com/nvm-sh/nvm nvm-windows：https://github.com/coreybutler/nvm-windows
pnpm
官网：https://pnpm.io/
镜像站
npmmirror：https://npmmirror.com/
Ollama
官网：https://ollama.com/
飞书开放平台
https://open.feishu.cn/
企业微信开放平台
https://developer.work.weixin.qq.com/
