1. 为什么第一次装 OpenClaw 总卡在环境这一步OpenClaw 是一个可以跑在自己机器或云服务器上的开源智能体框架能接飞书、钉钉、企业微信做远程控制也能在本地直接对话调用大模型 API。它适合想自己掌控数据、又希望有个 7×24 小时在线助手的开发者。但很多人第一次装它不是卡在 Nodejs 版本不对就是卡在 WSL 没装好或者 Git 拉代码时网络超时。我自己第一次装的时候在 Windows 上直接npm install报了一堆gyp错误后来才发现是没走 WSL。换到阿里云上装又因为安全组没开端口飞书回调一直失败。这些坑其实都有固定解法。这篇教程把 OpenClaw 的三种安装路径拆开讲阿里云云端部署、WSL 本地部署、Nodejs/Git 裸机部署。每种方式都给可复制的命令、config.toml骨架以及用 TaoToken 统一 Key 接入的配置。TaoToken 的作用是把多家模型的 API Key 收口成一个省得你在 OpenClaw 里来回换 base_url 和 key。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。三种方式没有绝对好坏阿里云适合要公网访问和团队协作的WSL 适合 Windows 本地开发Nodejs/Git 裸机适合 Linux 服务器或 Mac。你可以按自己的机器条件选一条走通再考虑要不要换。2. 装之前先把 TaoToken 的 Key 和模型入口准备好OpenClaw 本身不绑定任何一家模型它通过config.toml里的base_url和api_key去调 OpenAI 兼容接口。如果你直接用某一家厂商的 Key换模型时得改配置、重启服务。用 TaoToken 的好处是一个 Key 对应多个模型OpenClaw 里只写一个base_url模型名换一下就行。2.1 拿到统一 Key打开 TaoToken 控制台进 API Keys 页面创建一个新 Key。建议命名成openclaw-prod这种带用途的名字方便后面排查。创建后复制那串sk-开头的字符串只显示一次丢了就重建。注意Key 不要写进 Git 仓库也不要贴在聊天记录里。OpenClaw 的config.toml如果提交到公开仓库Key 会泄露。2.2 确认模型入口和可用模型名TaoToken 的 API 入口是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions路径。也就是说 OpenClaw 里base_url填https://taotoken.net/api/v1api_key填你刚建的 Key。模型名按你实际要用的填比如claude-sonnet-4-20250514、gpt-4o这类。具体可用列表在模型对话页面能看到也可以直接调/v1/models查。如果你后面要跑长期编码任务建议单独开一个 Coding Plan 的入口额度策略和普通对话不一样。2.3 先验证 Key 能不能通在装 OpenClaw 之前先用 curl 确认 Key 有效省得装完了才发现是 Key 的问题curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 只回复 ok}], max_tokens: 10 }返回里如果有choices字段且内容正常说明 Key 和网络都没问题。如果返回 401检查 Key 有没有复制全返回 404检查base_url是不是写成了https://taotoken.net/api而漏了/v1。3. 方式一阿里云轻量服务器部署 OpenClaw云端部署的核心优势是公网可达、7×24 小时在线飞书或钉钉的回调能直接打到服务器上。代价是要付云服务器费用配置也比本地多几步。3.1 买一台轻量应用服务器登录阿里云控制台进轻量应用服务器选 Ubuntu 24.04 镜像配置 2 核 4G 起步。OpenClaw 跑起来内存占用不算大但如果你要同时跑多个技能和模型请求4G 更稳。买完后在防火墙里放行 22SSH和你后面要用的服务端口比如 3000。3.2 装 Nodejs 和 GitSSH 连上服务器后先更新包索引再装 Nodejs 20 和 Gitsudo apt update sudo apt upgrade -y curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs git node -v npm -v git --versionnode -v应该输出v20.x。如果还是旧版本检查是不是系统自带的 Nodejs 抢了 PATH用which node确认路径。3.3 拉取 OpenClaw 并安装依赖git clone https://github.com/openclaw/openclaw.git cd openclaw npm installnpm install如果卡在某个包上先换 npm 源再重试npm config set registry https://registry.npmmirror.com npm install3.4 写 config.toml 接入 TaoToken在项目根目录创建config.toml最小骨架如下[server] host 0.0.0.0 port 3000 [model] provider openai-compatible base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken Key model claude-sonnet-4-20250514 max_tokens 4096 [channels.feishu] enabled true app_id cli_你的飞书AppID app_secret 你的飞书AppSecrethost写0.0.0.0是为了让公网能访问本地调试可以改127.0.0.1。飞书那段如果暂时不接把enabled设成false就行。3.5 启动并验证npm run start看到监听 3000 端口的日志后在本地浏览器访问http://服务器公网IP:3000/health返回{status:ok}说明服务起来了。如果访问不通先查阿里云安全组有没有放行 3000再查服务器上ufw status是不是拦了。4. 方式二WSL 本地部署Windows 用户WSL 是在 Windows 上跑 Linux 的兼容层OpenClaw 的很多依赖在 Linux 下更顺。如果你主力机是 Windows又不想买云服务器这条路最合适。4.1 安装 WSL 和 Ubuntu以管理员身份打开 PowerShell执行wsl --install重启后设置 Ubuntu 用户名和密码。注意输入密码时屏幕不显示任何字符这是正常的记住就行。如果wsl --install报错先执行wsl --list --verbose看有没有已装发行版没有的话手动装wsl --install -d ubuntu-24.04装完进 Ubuntu 终端先sudo apt update。4.2 在 WSL 里装 Nodejs 和 Git和阿里云那步一样curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs git node -v git --version4.3 拉代码、装依赖、写配置git clone https://github.com/openclaw/openclaw.git cd openclaw npm installconfig.toml和云端版基本一致区别是host可以写127.0.0.1因为本地访问不需要暴露公网[server] host 127.0.0.1 port 3000 [model] provider openai-compatible base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken Key model claude-sonnet-4-20250514 max_tokens 40964.4 启动并验证npm run start在 Windows 浏览器访问http://127.0.0.1:3000/health能返回 ok 就通了。WSL 的一个坑是如果你在 Windows 侧改了代码WSL 里的文件监听可能不触发建议代码直接放在 WSL 文件系统里别放/mnt/c/下。5. 方式三Nodejs/Git 裸机部署Linux/Mac如果你有一台 Linux 服务器或 Mac不需要 WSL 这层直接装 Nodejs 和 Git 就行。这是最轻的方式也最适合放进 Docker 或 CI 流程。5.1 装 Nodejs 20 和 GitUbuntu/Debiancurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs gitMac 用 Homebrewbrew install node20 git验证node -v npm -v git --version5.2 拉取并安装git clone https://github.com/openclaw/openclaw.git cd openclaw npm install如果npm install报EACCES权限错误别用sudo npm install而是修 npm 全局目录权限mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH npm install5.3 config.toml 骨架[server] host 0.0.0.0 port 3000 [model] provider openai-compatible base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken Key model claude-sonnet-4-20250514 max_tokens 4096 [logging] level info5.4 用 systemd 常驻可选裸机部署如果想开机自启写一个 systemd unit[Unit] DescriptionOpenClaw Afternetwork.target [Service] WorkingDirectory/home/你的用户/openclaw ExecStart/usr/bin/npm run start Restartalways User你的用户 [Install] WantedBymulti-user.target存到/etc/systemd/system/openclaw.service然后sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw6. 三种方式装完后怎么验证 API 真的通了不管走哪条路装完都要做一次端到端验证确认 OpenClaw 能通过 TaoToken 调到模型。6.1 用健康检查确认服务活着curl -s http://127.0.0.1:3000/health返回{status:ok}只说明进程在不代表模型能调通。6.2 发一条真实对话请求OpenClaw 一般会暴露一个对话接口路径可能是/api/chat或/v1/chat/completions以你实际版本为准。用 curl 打一条curl -s http://127.0.0.1:3000/api/chat \ -H Content-Type: application/json \ -d { message: 用一句话说明你现在用的是哪个模型, session_id: test-001 }如果返回里有模型生成的文本说明 OpenClaw → TaoToken → 模型这条链路通了。如果返回 500先看 OpenClaw 日志里有没有401或connection refused。6.3 检查日志里的 base_urltail -n 50 logs/openclaw.log日志里应该能看到请求发往https://taotoken.net/api/v1/chat/completions。如果看到的是别的域名说明config.toml没生效检查文件是不是放在项目根目录、有没有被环境变量覆盖。7. 本篇常见报错排查7.1 npm install 报 node-gyp 错误这是缺少编译工具链。Ubuntu 下装sudo apt install -y build-essential python3Mac 下装 Xcode Command Line Toolsxcode-select --install然后删掉node_modules重装。7.2 WSL 里 localhost 访问不通WSL2 的网络和 Windows 是隔离的但一般127.0.0.1能通。如果不行在 WSL 里查 IPip addr show eth0 | grep inet用那个 IP 在 Windows 浏览器访问。或者直接在 WSL 里用curl http://127.0.0.1:3000/health确认服务本身没问题。7.3 阿里云安全组开了还是访问不通先确认服务监听的是0.0.0.0而不是127.0.0.1ss -tlnp | grep 3000如果显示127.0.0.1:3000改config.toml里的host为0.0.0.0重启。再查服务器本机防火墙sudo ufw status sudo ufw allow 30007.4 调模型返回 401九成是 Key 问题。先确认config.toml里的api_key没有多余空格再确认base_url是https://taotoken.net/api/v1。如果 Key 是从控制台复制的注意别把前后引号也复制进去。7.5 调模型返回 404通常是base_url少了/v1。OpenClaw 拼路径时一般会补/chat/completions所以base_url要写到/v1这一层。写成https://taotoken.net/api就会 404。7.6 飞书回调验证失败检查三处飞书后台的事件订阅地址是不是http://公网IP:3000/channels/feishu/eventconfig.toml里的app_id和app_secret有没有填错服务器时间是不是准的时间偏差超过几分钟会导致签名校验失败。用date命令看一下不准就sudo ntpdate ntp.aliyun.com。8. 装完之后把 Key 和入口收口到一处三种方式走下来你会发现真正容易出问题的不是 OpenClaw 本身而是模型接入那一段。每换一个模型就改一次base_url和 Key时间都花在配置上了。用 TaoToken 把模型入口统一成https://taotoken.net/api/v1之后OpenClaw 的config.toml基本不用再动换模型只改model字段。如果你后面要跑长期编码或 Agent 任务建议单独开一个 Coding Plan 的 Key和日常对话的 Key 分开方便看额度和排查。接入文档里有完整的参数说明和错误码对照排障时对着查比猜快。模型对话页面可以直接试模型名和返回格式省得在 OpenClaw 里反复重启验证。装完先跑通一条对话请求再去接飞书或钉钉。顺序反了的话回调失败和模型失败混在一起排查会多花一倍时间。 OpenClaw三种方式安装：手把手保姆级教程（含TaoToken配置）
1. 为什么第一次装 OpenClaw 总卡在环境这一步OpenClaw 是一个可以跑在自己机器或云服务器上的开源智能体框架能接飞书、钉钉、企业微信做远程控制也能在本地直接对话调用大模型 API。它适合想自己掌控数据、又希望有个 7×24 小时在线助手的开发者。但很多人第一次装它不是卡在 Nodejs 版本不对就是卡在 WSL 没装好或者 Git 拉代码时网络超时。我自己第一次装的时候在 Windows 上直接npm install报了一堆gyp错误后来才发现是没走 WSL。换到阿里云上装又因为安全组没开端口飞书回调一直失败。这些坑其实都有固定解法。这篇教程把 OpenClaw 的三种安装路径拆开讲阿里云云端部署、WSL 本地部署、Nodejs/Git 裸机部署。每种方式都给可复制的命令、config.toml骨架以及用 TaoToken 统一 Key 接入的配置。TaoToken 的作用是把多家模型的 API Key 收口成一个省得你在 OpenClaw 里来回换 base_url 和 key。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。三种方式没有绝对好坏阿里云适合要公网访问和团队协作的WSL 适合 Windows 本地开发Nodejs/Git 裸机适合 Linux 服务器或 Mac。你可以按自己的机器条件选一条走通再考虑要不要换。2. 装之前先把 TaoToken 的 Key 和模型入口准备好OpenClaw 本身不绑定任何一家模型它通过config.toml里的base_url和api_key去调 OpenAI 兼容接口。如果你直接用某一家厂商的 Key换模型时得改配置、重启服务。用 TaoToken 的好处是一个 Key 对应多个模型OpenClaw 里只写一个base_url模型名换一下就行。2.1 拿到统一 Key打开 TaoToken 控制台进 API Keys 页面创建一个新 Key。建议命名成openclaw-prod这种带用途的名字方便后面排查。创建后复制那串sk-开头的字符串只显示一次丢了就重建。注意Key 不要写进 Git 仓库也不要贴在聊天记录里。OpenClaw 的config.toml如果提交到公开仓库Key 会泄露。2.2 确认模型入口和可用模型名TaoToken 的 API 入口是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions路径。也就是说 OpenClaw 里base_url填https://taotoken.net/api/v1api_key填你刚建的 Key。模型名按你实际要用的填比如claude-sonnet-4-20250514、gpt-4o这类。具体可用列表在模型对话页面能看到也可以直接调/v1/models查。如果你后面要跑长期编码任务建议单独开一个 Coding Plan 的入口额度策略和普通对话不一样。2.3 先验证 Key 能不能通在装 OpenClaw 之前先用 curl 确认 Key 有效省得装完了才发现是 Key 的问题curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 只回复 ok}], max_tokens: 10 }返回里如果有choices字段且内容正常说明 Key 和网络都没问题。如果返回 401检查 Key 有没有复制全返回 404检查base_url是不是写成了https://taotoken.net/api而漏了/v1。3. 方式一阿里云轻量服务器部署 OpenClaw云端部署的核心优势是公网可达、7×24 小时在线飞书或钉钉的回调能直接打到服务器上。代价是要付云服务器费用配置也比本地多几步。3.1 买一台轻量应用服务器登录阿里云控制台进轻量应用服务器选 Ubuntu 24.04 镜像配置 2 核 4G 起步。OpenClaw 跑起来内存占用不算大但如果你要同时跑多个技能和模型请求4G 更稳。买完后在防火墙里放行 22SSH和你后面要用的服务端口比如 3000。3.2 装 Nodejs 和 GitSSH 连上服务器后先更新包索引再装 Nodejs 20 和 Gitsudo apt update sudo apt upgrade -y curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs git node -v npm -v git --versionnode -v应该输出v20.x。如果还是旧版本检查是不是系统自带的 Nodejs 抢了 PATH用which node确认路径。3.3 拉取 OpenClaw 并安装依赖git clone https://github.com/openclaw/openclaw.git cd openclaw npm installnpm install如果卡在某个包上先换 npm 源再重试npm config set registry https://registry.npmmirror.com npm install3.4 写 config.toml 接入 TaoToken在项目根目录创建config.toml最小骨架如下[server] host 0.0.0.0 port 3000 [model] provider openai-compatible base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken Key model claude-sonnet-4-20250514 max_tokens 4096 [channels.feishu] enabled true app_id cli_你的飞书AppID app_secret 你的飞书AppSecrethost写0.0.0.0是为了让公网能访问本地调试可以改127.0.0.1。飞书那段如果暂时不接把enabled设成false就行。3.5 启动并验证npm run start看到监听 3000 端口的日志后在本地浏览器访问http://服务器公网IP:3000/health返回{status:ok}说明服务起来了。如果访问不通先查阿里云安全组有没有放行 3000再查服务器上ufw status是不是拦了。4. 方式二WSL 本地部署Windows 用户WSL 是在 Windows 上跑 Linux 的兼容层OpenClaw 的很多依赖在 Linux 下更顺。如果你主力机是 Windows又不想买云服务器这条路最合适。4.1 安装 WSL 和 Ubuntu以管理员身份打开 PowerShell执行wsl --install重启后设置 Ubuntu 用户名和密码。注意输入密码时屏幕不显示任何字符这是正常的记住就行。如果wsl --install报错先执行wsl --list --verbose看有没有已装发行版没有的话手动装wsl --install -d ubuntu-24.04装完进 Ubuntu 终端先sudo apt update。4.2 在 WSL 里装 Nodejs 和 Git和阿里云那步一样curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs git node -v git --version4.3 拉代码、装依赖、写配置git clone https://github.com/openclaw/openclaw.git cd openclaw npm installconfig.toml和云端版基本一致区别是host可以写127.0.0.1因为本地访问不需要暴露公网[server] host 127.0.0.1 port 3000 [model] provider openai-compatible base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken Key model claude-sonnet-4-20250514 max_tokens 40964.4 启动并验证npm run start在 Windows 浏览器访问http://127.0.0.1:3000/health能返回 ok 就通了。WSL 的一个坑是如果你在 Windows 侧改了代码WSL 里的文件监听可能不触发建议代码直接放在 WSL 文件系统里别放/mnt/c/下。5. 方式三Nodejs/Git 裸机部署Linux/Mac如果你有一台 Linux 服务器或 Mac不需要 WSL 这层直接装 Nodejs 和 Git 就行。这是最轻的方式也最适合放进 Docker 或 CI 流程。5.1 装 Nodejs 20 和 GitUbuntu/Debiancurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs gitMac 用 Homebrewbrew install node20 git验证node -v npm -v git --version5.2 拉取并安装git clone https://github.com/openclaw/openclaw.git cd openclaw npm install如果npm install报EACCES权限错误别用sudo npm install而是修 npm 全局目录权限mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH npm install5.3 config.toml 骨架[server] host 0.0.0.0 port 3000 [model] provider openai-compatible base_url https://taotoken.net/api/v1 api_key sk-你的TaoToken Key model claude-sonnet-4-20250514 max_tokens 4096 [logging] level info5.4 用 systemd 常驻可选裸机部署如果想开机自启写一个 systemd unit[Unit] DescriptionOpenClaw Afternetwork.target [Service] WorkingDirectory/home/你的用户/openclaw ExecStart/usr/bin/npm run start Restartalways User你的用户 [Install] WantedBymulti-user.target存到/etc/systemd/system/openclaw.service然后sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw6. 三种方式装完后怎么验证 API 真的通了不管走哪条路装完都要做一次端到端验证确认 OpenClaw 能通过 TaoToken 调到模型。6.1 用健康检查确认服务活着curl -s http://127.0.0.1:3000/health返回{status:ok}只说明进程在不代表模型能调通。6.2 发一条真实对话请求OpenClaw 一般会暴露一个对话接口路径可能是/api/chat或/v1/chat/completions以你实际版本为准。用 curl 打一条curl -s http://127.0.0.1:3000/api/chat \ -H Content-Type: application/json \ -d { message: 用一句话说明你现在用的是哪个模型, session_id: test-001 }如果返回里有模型生成的文本说明 OpenClaw → TaoToken → 模型这条链路通了。如果返回 500先看 OpenClaw 日志里有没有401或connection refused。6.3 检查日志里的 base_urltail -n 50 logs/openclaw.log日志里应该能看到请求发往https://taotoken.net/api/v1/chat/completions。如果看到的是别的域名说明config.toml没生效检查文件是不是放在项目根目录、有没有被环境变量覆盖。7. 本篇常见报错排查7.1 npm install 报 node-gyp 错误这是缺少编译工具链。Ubuntu 下装sudo apt install -y build-essential python3Mac 下装 Xcode Command Line Toolsxcode-select --install然后删掉node_modules重装。7.2 WSL 里 localhost 访问不通WSL2 的网络和 Windows 是隔离的但一般127.0.0.1能通。如果不行在 WSL 里查 IPip addr show eth0 | grep inet用那个 IP 在 Windows 浏览器访问。或者直接在 WSL 里用curl http://127.0.0.1:3000/health确认服务本身没问题。7.3 阿里云安全组开了还是访问不通先确认服务监听的是0.0.0.0而不是127.0.0.1ss -tlnp | grep 3000如果显示127.0.0.1:3000改config.toml里的host为0.0.0.0重启。再查服务器本机防火墙sudo ufw status sudo ufw allow 30007.4 调模型返回 401九成是 Key 问题。先确认config.toml里的api_key没有多余空格再确认base_url是https://taotoken.net/api/v1。如果 Key 是从控制台复制的注意别把前后引号也复制进去。7.5 调模型返回 404通常是base_url少了/v1。OpenClaw 拼路径时一般会补/chat/completions所以base_url要写到/v1这一层。写成https://taotoken.net/api就会 404。7.6 飞书回调验证失败检查三处飞书后台的事件订阅地址是不是http://公网IP:3000/channels/feishu/eventconfig.toml里的app_id和app_secret有没有填错服务器时间是不是准的时间偏差超过几分钟会导致签名校验失败。用date命令看一下不准就sudo ntpdate ntp.aliyun.com。8. 装完之后把 Key 和入口收口到一处三种方式走下来你会发现真正容易出问题的不是 OpenClaw 本身而是模型接入那一段。每换一个模型就改一次base_url和 Key时间都花在配置上了。用 TaoToken 把模型入口统一成https://taotoken.net/api/v1之后OpenClaw 的config.toml基本不用再动换模型只改model字段。如果你后面要跑长期编码或 Agent 任务建议单独开一个 Coding Plan 的 Key和日常对话的 Key 分开方便看额度和排查。接入文档里有完整的参数说明和错误码对照排障时对着查比猜快。模型对话页面可以直接试模型名和返回格式省得在 OpenClaw 里反复重启验证。装完先跑通一条对话请求再去接飞书或钉钉。顺序反了的话回调失败和模型失败混在一起排查会多花一倍时间。