1. 先搞清楚 OpenClaw 到底能帮你做什么OpenClaw 是一个本地优先的 Agent AI 运行时你可以把它理解成装在自己电脑里的 AI 助理。它和网页版对话工具最大的区别在于它常驻在你机器上有身份、有记忆、有工具调用能力能读写文件、执行命令、访问网络还能通过 Telegram 这类渠道远程接收指令。适合谁适合想把 AI 从聊天窗口变成能干活的手的开发者、运维、独立创作者尤其是需要跨 Windows、macOS、Linux 三平台统一环境的人。整套系统由几个核心模块组成。Gateway 是常驻后台的调度进程默认监听 127.0.0.1:18789负责接收所有渠道消息、管理会话、调度 Agent。Agent Loop 是智能体的思考引擎走感知 → 规划 → 调工具 → 执行 → 观察结果 → 再规划的循环直到任务完成。SOUL.md 定义 Agent 的人格与边界决定它是谁、该说什么、能做什么、不能做什么。Skills 是技能插件浏览器、Shell、GitHub、PDF、定时任务都能挂上去。Memory 是跨会话的长期记忆让 Agent 记住你的偏好、历史决策和项目上下文。我试过在三台不同系统的机器上从零搭一遍踩过的坑主要集中在 Node 版本、端口占用和模型接入这三块。这篇教程会把每一步的可复制命令、配置文件模板和验证方法都写清楚并且用 TaoToken 统一 Key 接入模型省去在多个平台之间来回切换的麻烦。TaoToken 官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 后面配置里会反复用到。先明确一个前提OpenClaw 大量使用 Node 22 的新特性用 18 或 20 装上去会各种诡异报错。所以环境准备阶段Node 版本是头号杀手务必先确认。下面按 macOS、Linux、Windows 三条线分别给出前置检查命令你可以直接跳到对应系统。2. 三平台环境准备与依赖安装2.1 通用依赖一览不管什么系统以下依赖是硬性要求。Node.js 最低 22推荐 24.x LTS 或 26.xnpm 10.x 最新稳定版Git 2.x 最新磁盘空间至少 2 GB建议 5 GB含技能缓存内存至少 2 GB建议 4 GB。检查命令很简单node --version、npm --version、git --version三条都过再往下走。2.2 macOS 前置准备macOS 13 Ventura 及以上即可Apple SiliconM1/M2/M3/M4和 Intel 都支持。第一步装 Homebrew如果没装过执行官方安装脚本# 检查是否已安装 which brew # 如果没有执行官方安装脚本 /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)第二步装或升级 Node.js推荐用 Homebrew 或 nvm# 用 Homebrew 安装推荐 brew install node22 # 或者用 nvm 管理多版本更灵活 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.zshrc nvm install 22 nvm use 22 nvm alias default 22 # 验证 node --version npm --version第三步装辅助工具代码高亮、JSON 处理后续调试会用到brew install jq tree2.3 Linux 前置准备Ubuntu / Debian 为例以 Ubuntu 22.04 / 24.04 为基准其他发行版原理相同包管理器换成对应的即可。第一步更新系统sudo apt update sudo apt upgrade -y第二步装 Node.js两种方法任选# 方法 A用 NodeSource 官方源推荐版本新 curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs # 方法 B用 nvm适合需要多版本切换的开发者 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 nvm alias default 22 # 验证 node --version npm --version第三步装辅助依赖sudo apt install -y git curl wget jq tree第四步服务器场景建议创建专用用户不建议用 root 跑 Gatewaysudo useradd -m -s /bin/bash openclaw sudo usermod -aG sudo openclaw su - openclaw2.4 Windows 前置准备原生 WSL2Windows 用户面临一个关键选择原生 PowerShell 还是 WSL2WSL2 兼容性最好和 Linux 完全一致Shell 工具链完整代价是需要开启虚拟化、占用约 2~5 GB 磁盘强烈推荐。原生 PowerShell 不用装额外子系统开箱即用但路径处理、权限、Shell 技能经常踩坑能用但不省心。方案一 WSL2推荐# 以管理员身份打开 PowerShell执行 wsl --install # 这会自动安装 Ubuntu 发行版。装完后重启电脑 # 首次进入会要求设置用户名和密码。 # 进入 Ubuntu 后按「2.3 Linux 前置准备」的步骤装 Node.js 即可。如果你的 Windows 版本较老可能需要手动开启虚拟化控制面板 → 程序 → 启用或关闭 Windows 功能 → 勾选虚拟机平台和适用于 Linux 的 Windows 子系统。方案二原生 Windows# 安装 Chocolatey 包管理器如果没有 Set-ExecutionPolicy Bypass -Scope Process -Force [System.Net.ServicePointManager]::SecurityProtocol [System.Net.ServicePointManager]::SecurityProtocol -bor 3072 iex ((New-Object System.Net.WebClient).DownloadString(https://community.chocolatey.org/install.ps1)) # 用 Chocolatey 安装 Node.js choco install nodejs-lts -y # 或者用 wingetWindows 11 自带 winget install OpenJS.NodeJS.LTS # 验证 node --version npm --version3. 安装 OpenClaw 与 TaoToken 统一 Key 接入3.1 四种安装方式任选准备工作做完终于可以装主角了。OpenClaw 提供四种安装方式按场景选择。方式一一键脚本macOS / Linux / WSL2 推荐最简单、最不容易出错curl -fsSL https://openclaw.ai/install.sh | bash执行后你会看到类似这样的输出Detecting system... OS: macOS 14.5 (Apple Silicon) Node.js: v22.11.0 npm: v10.9.0 Installing OpenClaw... Downloading package... Installing dependencies... Setting up directories... OpenClaw installed successfully! Next step: run openclaw onboard to configure your Agent.方式二npm / pnpm / bun 全局安装适合已熟悉 Node.js 生态、想自己管理版本的开发者# npm npm config set registry https://registry.npmmirror.com # 国内用户建议换源 npm install -g openclawlatest openclaw --version # pnpm pnpm add -g openclawlatest pnpm approve-builds -g # 重要否则部分原生模块不会被构建 openclaw --version # bun bun add -g openclawlatest openclaw --version方式三Docker 容器部署适合无头服务器、云主机或想环境隔离的场景docker pull openclaw/openclaw:latest docker run -d \ --name openclaw \ --restart unless-stopped \ -p 18789:18789 \ -v ~/.openclaw:/root/.openclaw \ -v ~/Documents:/root/Documents \ openclaw/openclaw:latest docker logs -f openclaw docker exec -it openclaw openclaw --version参数说明-p 18789:18789把容器内的 Gateway 端口映射到宿主机-v ~/.openclaw:/root/.openclaw持久化配置和记忆数据-v ~/Documents:/root/Documents让 Agent 能访问你的文档目录按需调整。方式四Windows 原生 PowerShell 安装Set-ExecutionPolicy RemoteSigned -Scope CurrentUser iwr -useb https://openclaw.ai/install.ps1 | iex openclaw --version3.2 用 TaoToken 统一 Key 接入模型OpenClaw 的模型配置非常灵活支持同时配置多个提供商并按需切换。所有认证信息集中存放在auth-profiles.json中。配置文件位置macOS / Linux / WSL2 是/Users/你的用户名/.openclaw或/home/你的用户名/.openclawWindows 原生是C:\Users\你的用户名\.openclaw。也可以用openclaw config path命令查看确切位置。这里推荐用 TaoToken 作为统一 API 通道一个 Key 就能覆盖多个模型省去在 Anthropic、OpenAI、DeepSeek 之间来回申请和切换的麻烦。TaoToken 的 API 入口是 https://taotoken.net/api 兼容 OpenAI 格式配置时把 baseURL 指向它即可。编辑~/.openclaw/agents/main/agent/auth-profiles.json写入以下配置{ profiles: [ { id: taotoken-main, type: api-key, provider: openai, apiKey: sk-你的taotoken-key, baseURL: https://taotoken.net/api/v1, model: claude-sonnet-4-6 } ], default: taotoken-main }如果你需要多模型热切换可以在 profiles 数组里加多个条目比如一个走 TaoToken 的 Claude、一个走 TaoToken 的 DeepSeek然后在对话中用--profile参数临时切换# 临时切换到 Opus 处理复杂任务 openclaw agent --agent main --profile taotoken-opus --message 帮我重构这段复杂代码 # 切回默认模型 openclaw agent --agent main --message 继续之前的话题Key 的获取和查看可以走 TaoToken 的 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你更习惯用 Claude Code 那套工作流TaoToken 也提供了对应的接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。3.3 初始化配置onboard 向导全解读不管用哪种方式安装最终都要跑一次 onboard 向导。这是整个搭建过程中最关键的一步它会帮你生成所有配置文件openclaw onboard --install-daemon--install-daemon参数的作用是让 Gateway 注册为系统服务实现开机自启。macOS 走 LaunchAgentLinux/WSL2 走 systemd 用户服务Windows 走计划任务。向导会交互式地问你一系列问题逐条拆解第 1 步接受风险声明输入 Yes 继续第 2 步选 QuickStart第 3 步选模型提供商这里选 Custom / OpenAI-Compatible因为我们要走 TaoToken第 4 步粘贴你的 TaoToken Key第 5 步选默认模型日常用 Sonnet 性价比最高第 6 步配置消息渠道建议先 Skip后面专门配第 7 步安装技能插件选 Minimal第 8 步注册守护进程选 Yes。完成后你会看到类似这样的目录结构~/.openclaw/ ├── config.yaml # 主配置文件 ├── openclaw.json # 运行时状态 ├── agents/ │ └── main/ │ ├── agent/ │ │ ├── auth-profiles.json # API Key / OAuth 认证信息 │ │ └── config.json # Agent 级配置 │ ├── SOUL.md # Agent 人格定义 │ ├── memory/ # 长期记忆存储 │ └── sessions/ # 会话记录 ├── skills/ # 已安装的技能 ├── cron/ # 定时任务配置 └── logs/ # 运行日志4. 启动 Gateway 并验证请求成功4.1 启动与状态检查所有配置就绪后启动 Gateway# 前台运行方便看日志 openclaw gateway start # 或者后台运行推荐日常使用 openclaw gateway start --daemon # 检查状态 openclaw gateway status期望输出类似Gateway is running PID: 12345 Listening on: 127.0.0.1:18789 Uptime: 0h 2m 15s打开 Web 控制台openclaw dashboard这会自动在浏览器打开 http://127.0.0.1:18789你会看到一个简洁的聊天界面。4.2 发第一条测试消息在桌面创建一个叫AI 笔记的文件夹然后在里面写一个 hello.txt内容是OpenClaw 搭建成功。如果一切正常你会看到 Agent 思考了几秒能看到它的推理过程执行了 mkdir 和 echo 命令报告任务完成。去文件系统检查一下文件确实在那里——恭喜你全链路打通了。4.3 用 curl 直接验证 TaoToken 通道如果 Web 控制台报错可以先用 curl 单独验证 TaoToken 通道是否通curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的taotoken-key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-6, messages: [{role: user, content: 回复 OK 两个字}] }返回里能看到choices字段和正常内容说明 Key 和通道都没问题问题就出在 OpenClaw 的配置上。想直接在网页里试模型效果可以走模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。5. 常见报错排查对照表5.1 通用排查表先跑一键全面诊断这是必背命令openclaw doctordoctor 命令会检查 Node 版本、配置文件语法、API Key 有效性、端口占用、技能兼容性、日志异常等并给出修复建议。下面是高频报错对照现象可能原因解决方案openclaw: command not foundnpm 全局 bin 不在 PATHexport PATH$(npm prefix -g)/bin:$PATH写入 .zshrcGateway 起不来18789 端口被占用lsof -i :18789Mac/Linux或netstat -ano | findstr 18789Win找进程杀掉API 无响应Key 错误或 baseURL 不对检查 auth-profiles.json用 curl 手动测 APISkill 不生效没重启 Gatewayopenclaw gateway restart对话突然中断Token 超限用/compact压缩上下文或换更大上下文的模型内存暴涨会话太长 / 记忆未清理清理 sessions/ 旧文件压缩 memory/模型回复质量差模型选太小 / SOUL.md 太模糊换更强模型细化 SOUL.md 规则5.2 真实报错逐条拆解401 Unauthorized最常见的是 Key 粘贴时带了空格或者 baseURL 写成了https://taotoken.net/api而漏了/v1。正确写法是https://taotoken.net/api/v1。另外检查 auth-profiles.json 里provider字段是否写成了openai走 TaoToken 统一通道时必须是 openai 兼容格式。local proxy failed / connection refused说明 OpenClaw 尝试连本地代理但没连上。检查系统环境变量里是否有HTTP_PROXY、HTTPS_PROXY残留有的话清掉再重启 Gateway。Docker 场景下容器内访问宿主机服务要用host.docker.internal而不是127.0.0.1。reading choices of undefined这个报错几乎都是 API 返回结构不对导致的。要么是 baseURL 指向了错误的路径要么是模型 ID 写错了。用 4.3 节的 curl 命令单独测一次看返回里有没有choices数组。如果 curl 正常但 OpenClaw 报错检查 auth-profiles.json 的 JSON 语法多一个逗号都会导致解析失败。OAuth 登录失败如果你用的是 Anthropic OAuth 模式而非 API Key首次使用会弹出浏览器要求登录 Claude.ai 授权。如果弹窗被拦截手动复制终端里打印的 URL 到浏览器打开。OAuth 模式下不需要 apiKey 字段但需要确保type写成oauth。CC Switch / Cline MCP / Codex auth.json 三件套如果你同时用这些工具配置时务必确认三件套齐全——Base URL 指向https://taotoken.net/api/v1Key 用同一个 TaoToken KeyModel ID 写完整如claude-sonnet-4-6。三者缺一都会导致连接失败。Codex 的 auth.json 里字段名是OPENAI_BASE_URL别写成baseURL。5.3 三平台专属问题macOS 专属Apple Silicon 原生模块编译失败npm install报 node-gyp 错误先装 Xcode Command Line Toolsxcode-select --install。权限弹窗频繁去系统设置 → 隐私与安全手动授权终端/Node 的权限。LaunchAgent 不生效检查~/Library/LaunchAgents/ai.openclaw.gateway.plist是否存在用launchctl load手动加载。Linux 专属systemd 用户服务不运行systemctl --user报连接失败确保XDG_RUNTIME_DIR已设置或改用全局服务。端口被防火墙拦外部无法访问 18789sudo ufw allow 18789Ubuntu或配置 iptables。npm 全局安装权限不足报 EACCES不要用 sudo npm改 npm 默认目录npm config set prefix ~/.npm-global并加入 PATH。Windows 专属执行策略拦脚本报因为在此系统上禁止运行脚本Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。路径分隔符问题Skill 脚本里/和\混用报错统一用 PowerShell 的 Join-Path。杀毒软件拦截Gateway 启动后被 Windows Defender 干扰把.openclaw目录和 Node.js 加入 Defender 排除列表。WSL2 和 Windows 文件互访慢在/mnt/c/下操作文件极慢尽量把项目放在 WSL2 原生文件系统~目录下。6. 长期编码与 Agent 工作流建议环境跑通只是起点。如果你打算把 OpenClaw 当成日常编码和 Agent 任务的长期工具建议走 Coding Plan 通道额度和稳定性更适合持续使用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。控制台里可以统一管理 Key、查看用量、切换模型https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后给一个最小可用清单逐项核对全部打勾代表你的 OpenClaw Agent AI 已完整跑通Node.js 22 已安装openclaw --version能正常输出版本号openclaw doctor全部通过无报错auth-profiles.json 至少配置了一个可用模型SOUL.md 已编写openclaw gateway status显示 running on port 18789openclaw dashboard能打开且能正常对话Agent 能成功执行一条文件操作命令至少一个 Skill 安装并可正常使用Gateway 已注册为系统服务重启后自动运行。搭完之后你会发现Agent AI 不是未来是现在。它不完美——Skill 质量参差不齐Token 消耗是笔隐形支出复杂任务偶尔犯傻——但它已经能实实在在帮你干活了。关键是它跑在你的机器上数据在你手里规则你说了算。