Openclaw 原生满血本地部署（一）：WSL2 / macOS / Linux 三端配置骨架与验证

1. 先把最小链路跑通Openclaw 三端部署到底在解决什么问题Openclaw 是一个把大模型能力接到本地工作流里的开源网关工具你可以把它理解成一个「本地中转站」上游对接各家模型 API下游对接飞书、Telegram、终端 TUI 等入口中间用一份配置文件把路由、权限、会话都管起来。它适合谁适合想在自己机器上跑一套可控 Agent 链路、又不想把数据全丢给第三方托管平台的开发者。这篇是「原生满血本地部署」系列的第一篇只做一件事在 WSL2、macOS、Linux 三端把环境、依赖、模型通道全部验证通过拿到一个能响应请求的最小可用实例。很多人卡在第一步不是因为 Openclaw 难装而是环境本身有坑WSL2 的 systemd 没开、macOS 的 Homebrew 路径没进 PATH、Linux 的 Node 版本太老。这些问题的共同点是——安装脚本跑完了但openclaw doctor一跑全是红的。所以这篇不急着接飞书、不急着配机器人先把「装完能自检、自检能通过、通过后能发一条真实请求」这条链路走完。模型通道这块我用 TaoToken 的统一 Key 来接入原因是它一个 Key 能覆盖 Claude、GPT、Gemini 等多家模型省得你在配置文件里维护一堆 provider 分支对三端统一配置特别友好。下面按「环境准备 → 安装 → 配置骨架 → 验证请求 → 排障」的顺序走每一步都给出可直接复制的命令和配置。你不需要全部照抄但建议至少把验证环节完整跑一遍因为后面接渠道、写 Agent 逻辑时任何通道问题都会伪装成「机器人不回消息」到时候排查成本高得多。2. 三端环境准备与 Openclaw 安装2.1 WSL2 端先确认 systemd 和版本WSL2 最容易踩的坑是 systemd 没启用导致 Openclaw 的守护进程装不上。先在 PowerShell 里确认 WSL 版本wsl --version wsl --list --verbose如果VERSION列显示 1先升级到 WSL2wsl --set-version Ubuntu-22.04 2进入 WSL 后编辑/etc/wsl.conf确保有这两段[boot] systemdtrue [interop] enabledtrue appendWindowsPathtrue保存后回到 PowerShell 执行wsl --shutdown再重新进入。验证 systemd 是否生效systemctl is-system-running # 期望输出 running 或 degraded不能是 offlineUbuntu 20.04 及以上都满足要求内存建议给到 8GB 以上低于这个数跑 Agent 会话会明显卡顿。WSL2 默认会吃掉宿主机一半内存可以在用户目录下建.wslconfig限制[wsl2] memory8GB processors42.2 macOS 端Homebrew 与 Node 版本macOS 上先确认 Homebrew 可用然后装 Node 20 以上brew --version brew install node20 echo export PATH/opt/homebrew/opt/node20/bin:$PATH ~/.zshrc source ~/.zshrc node -v # 期望 v20.x 或更高Intel 芯片的路径是/usr/local/opt/node20/bin别抄错。如果你之前用 nvm 装过旧版本先nvm alias default 20切过去否则安装脚本会调用到旧 Node。2.3 Linux 端依赖补齐Debian/Ubuntu 系先补基础依赖sudo apt update sudo apt install -y curl git build-essential curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs node -v npm -vCentOS/RHEL 系把apt换成dnfNodeSource 脚本地址不变。装完确认npm全局目录在 PATH 里npm config get prefix # 如果是 /usr/local确认 /usr/local/bin 在 PATH2.4 安装 Openclaw 并自检macOS 和 Linux 用同一条命令curl -fsSL https://openclaw.bot/install.sh | bashWindows 侧在 PowerShell 里执行iwr -useb https://openclaw.ai/install.ps1 | iex如果 PowerShell 闪退用管理员权限重开一个窗口再跑或者重启机器后重试。安装完成后验证版本和帮助openclaw -V openclaw --help-V会打印类似2026.3.2的版本号--help会列出gateway、models、channels、doctor等子命令。看到这两条输出说明 CLI 本体没问题。接着跑一次健康检查openclaw doctor这一步会检查 Node 版本、配置目录权限、端口占用、网关状态。首次运行大概率会提示「未初始化配置」这是正常的下一步就来解决。3. TaoToken 统一 Key 接入与 config.toml 骨架3.1 为什么用统一 Key 而不是逐家配Openclaw 原生支持 Anthropic、OpenAI、Gemini、Ollama 等多个 provider但如果你每个都单独配 Key配置文件会变成一坨分支切换模型时还要改 provider 字段。用 TaoToken 的统一 Key你只需要在配置里声明一个 OpenAI 兼容的 base_url模型名通过参数切换即可。对三端统一部署来说这意味着 WSL2、macOS、Linux 可以共用同一份配置骨架只改路径不改结构。先去控制台拿 Key入口在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite拿到形如sk-xxxx的字符串后不要直接写进配置文件明文提交到 Git。Openclaw 支持从环境变量读取推荐做法是在 shell 配置里导出export TAOTOKEN_API_KEYsk-你的keyWSL2 和 Linux 写进~/.bashrcmacOS 写进~/.zshrc然后source一下。3.2 config.toml 骨架Openclaw 的配置目录默认在~/.openclaw/主配置文件是openclaw.json但模型 provider 部分可以用 TOML 风格的片段来组织。下面这份骨架三端通用你只需要确认路径和 Key 环境变量名# ~/.openclaw/config.toml [gateway] port 18789 host 127.0.0.1 [models.default] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-20250514 timeout 60 [models.fallback] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model gpt-4o-mini timeout 30 [agent] workspace ~/.openclaw/workspace max_turns 20几个关键点base_url填https://taotoken.net/api不要带 UTM 参数那是给网页跳转用的api_key_env指向你刚才导出的环境变量名model字段按你实际要用的模型填Claude 和 GPT 系列都走同一个 base_url。gateway.port默认 18789如果你本机这个端口被占改成 18790 之类后面验证时同步改。3.3 settings.json 补充项有些渠道和 UI 相关的配置走settings.json和config.toml并存。最小骨架如下{ ui: { theme: dark, language: zh-CN }, logging: { level: info, file: ~/.openclaw/logs/gateway.log }, security: { allowLocalOnly: true, maskSecrets: true } }allowLocalOnly设为 true 时网关只监听 127.0.0.1外部机器访问不到本地开发阶段建议保持这个设置。maskSecrets会在日志里把 Key 打码避免排障时把密钥贴到聊天窗口。3.4 初始化配置目录如果~/.openclaw/还不存在跑一次初始化openclaw setup或者用交互式向导openclaw onboard --install-daemon向导会问你选哪个 provider、填 Key、选渠道。如果你已经手写好配置文件可以直接跳过向导用非交互方式校验openclaw config validate输出config is valid就说明语法和字段都没问题。4. 启动网关并验证请求4.1 启动 Gateway前台启动方便看日志openclaw gateway --port 18789看到Gateway listening on ws://127.0.0.1:18789就说明起来了。如果你想让它作为系统服务常驻用openclaw gateway --install-daemonWSL2 下需要 systemd 已启用前面确认过macOS 下会走 launchdLinux 下走 systemd。装完用openclaw status看服务状态。4.2 用 models 命令验证通道这是最关键的一步确认模型通道真的通。先列出可用模型openclaw models list如果配置正确你会看到default和fallback两个条目provider 显示为 openai-compatible。接着发一条真实请求openclaw models test --model default --prompt 用一句话说明你是什么模型期望输出是一段模型回复而不是超时或 401。如果返回 401说明 Key 没读到检查echo $TAOTOKEN_API_KEY是否有值如果返回 404检查base_url是不是写成了https://taotoken.net/api/带了多余斜杠。4.3 用 agent 命令跑一轮完整会话模型通道通了之后验证 Agent 链路openclaw agent --message 列出当前工作目录下的文件 --deliver这条命令会让 Agent 走一轮完整的「接收指令 → 调用模型 → 执行工具 → 返回结果」流程。如果模型通道正常但 Agent 报错问题通常在 workspace 权限或工具白名单跟模型无关。4.4 打开控制台确认浏览器访问http://127.0.0.1:18789/首次加载可能要几秒。控制台里能看到当前会话、日志、模型状态。在对话框里输入一句话如果收到回复说明从 CLI 到 Web UI 的整条链路都通了。到这一步你的 Openclaw 最小可用实例就算部署完成后面接飞书、配机器人都是在这个基础上叠加。5. 本篇常见报错排查5.1openclaw: command not found安装脚本跑完了但命令找不到通常是 npm 全局 bin 目录不在 PATH。先确认npm config get prefix ls $(npm config get prefix)/bin | grep openclaw如果文件在但 PATH 没有把 prefix 的 bin 目录加进去。macOS 上如果是/opt/homebrew/bin确认/opt/homebrew/bin在~/.zshrc的 PATH 里。5.2 WSL2 下systemctl报System has not been booted with systemd说明/etc/wsl.conf的systemdtrue没生效。检查文件是否写对然后必须wsl --shutdown完全重启 WSL只关终端窗口不算。重启后systemctl is-system-running应该返回 running。5.3 网关启动报端口占用openclaw gateway --force--force会杀掉占用默认端口的进程再启动。如果不想杀改端口openclaw gateway --port 18790记得同步改config.toml里的gateway.port否则控制台访问地址对不上。5.4 模型请求超时先确认网络能到taotoken.netcurl -I https://taotoken.net/api如果 curl 都超时是网络层问题跟 Openclaw 无关。如果 curl 通但models test超时把timeout从 60 调到 120 再试有些模型首 token 延迟较高。另外确认base_url没有多余路径正确值是https://taotoken.net/api。5.5 配置文件改了不生效Openclaw 启动时读一次配置改完要重启网关openclaw gateway restart或者前台模式下 CtrlC 再重新跑。改完先用openclaw config validate校验语法避免因为一个逗号导致整个配置被忽略。5.6 日志在哪看openclaw logs --tail 100或者直接看文件~/.openclaw/logs/gateway.log。排障时优先看error和warn级别info级别信息量大但噪音也多。如果日志里出现 Key 相关字样确认maskSecrets是开着的。6. 下一步从最小链路到可用工作流环境、依赖、通道这三样验证通过之后你就有了一个能响应请求的本地 Openclaw 实例。接下来可以按需往下走想接飞书机器人去开放平台建应用、配长连接、填appId和appSecret想跑长期编码任务或 Agent 工作流可以了解 Coding Plan 的配额和路由策略想先试试不同模型的实际效果直接在控制台里切换模型对话就行。几个入口按用途分模型对话体验https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你在验证阶段遇到models test返回 401 或超时优先去 API Keys 页面确认 Key 状态和额度再对照接入文档检查base_url拼写。通道问题解决后后面接渠道、写 Agent 逻辑都会顺很多。下一篇会在这个骨架上接飞书长连接把消息入口打通。