1. OpenClaw 是什么为什么大家都在折腾它先说说 OpenClaw 是个什么东西。用一句话概括它是一个开源的、自带“手和脚”的 AI 助理框架核心是用自然语言驱动工具调用让模型不再只是跟你聊天而是真的能帮你操作终端、读写文件、调用各种 API、跑自动化流程。名字里的 Claw 取的是“龙虾钳子”的意思象征它能替你“夹住”外部工具、把活儿干完。我最早接触这个项目是在逛开源社区的时候看到有人在讨论 “openclaw 龙虾 windows 离线整合包”当时还以为是某个游戏 mod点进去才发现是这么个玩意儿。后来一直关注直到最近它的热度明显涨了一波——“openclaw 安装教程”“openclaw 部署”“openclaw skill 推荐”“如何升级 openclaw 版本”这些搜索词的频率肉眼可见地在增加。原因也不难理解大模型 API 越来越便宜但真正能把模型能力“落地成具体动作”的框架仍然稀缺OpenClaw 恰好补上了这块短板。这篇教程面向的读者很明确想在自己电脑或云服务器上把 OpenClaw 跑起来、又想尽量少花钱、同时还希望把它跟 iFlow CLI 串成自动化流水线的人。我会把从零开始的全过程拆开讲包括本地部署和阿里云部署两条路线、免费 Token 的获取思路、Token 各种报错的排查方法以及 iFlow CLI 的集成步骤全部是实操过的经验不是抄文档。2. 部署前的思路与方案选型2.1 本地部署还是云服务器先想清楚这几个问题很多人一上来就问“OpenClaw 应该装在哪里”其实这个问题没有标准答案取决于你的使用场景。我的建议是先想清楚三个问题你打算让它跑多久你需要在多少个地方访问它你手里的硬件条件怎么样如果你只是自己电脑上偶尔用用跑几个 skill、接几个 API那本地部署完全够用成本几乎为零。但如果你想让 OpenClaw 变成一个常驻服务比如定时抓数据、处理任务、响应外部请求那本地电脑就很不方便了——你得保持电脑不关机、网络不断线还得考虑家里 IP 变动的问题。这时候一台云服务器会更合适。另外还有一个很关键的考量模型服务的网络连通性。OpenClaw 本身是个框架它要真正“干活”必须接一个大模型 API。如果你用的是国内云厂商提供的模型服务比如阿里云百炼平台上的模型那你用阿里云的服务器去跑 OpenClaw内网访问延迟低、稳定性好而且不用担心网络环境带来的各种莫名其妙的问题。这一点在后面讲 Token 报错的时候会反复提到。2.2 方案对比本地裸装、Docker、离线整合包部署方式这块目前我实测过三种路径按推荐程度排个序部署方式适用人群优点缺点官方安装脚本喜欢尝鲜、网络条件好、希望随时更新到最新版一条命令装完便于后续 git pull 升级依赖 GitHub 源码拉取网络不好时容易失败Windows 离线整合包不熟悉命令行的新手、Windows 用户解压即用不折腾环境版本可能滞后升级麻烦跨平台要重新下载Docker 部署有服务器运维经验、想让服务更干净可控的人环境隔离、迁移方便多一层封装调试时不够直观我的建议是如果你满足“有命令行基础 网络能访问 GitHub 希望长期使用”优先用官方安装脚本并且指定从 main 分支检出源码。这样后续升级非常方便——一条 git pull 加重启服务就完事了。Windows 离线整合包可以作为备选方案尤其适合先拿来体验一下 OpenClaw 到底能干什么再决定要不要深入折腾。Docker 嘛适合那些本来就有容器化习惯的人如果你平时不玩 Docker没必要为了 OpenClaw 专门去学。2.3 免费 Token 的整体获取思路接下来聊一个大家最关心的话题免费 Token 从哪来。在 OpenClaw 的架构里Token 并不直接由 OpenClaw 产生它本质上是“你调用大模型服务时的凭证”。所以所谓“免费 Token”核心思路就是找那些提供免费额度的模型服务商把它们的 API Key 配置进 OpenClaw。我实际测试下来有几类免费额度比较靠谱第一类是阿里云百炼平台的新用户免费额度注册后能在一定时间或额度范围内免费调用多种模型这对新手上路非常友好第二类是各类开源模型服务商提供的限时免费体验额度通常需要申请或满足一定条件第三类是自己本地部署开源大模型比如通过 Ollama 跑 qwen、deepseek 等这种是真正的“永久免费”但前提是你的电脑配置要扛得住。这里要先打个预防针很多人在网上看到“免费 Token”就觉得是无限白嫖实际上大部分免费额度都有有效期和调用次数限制。我的建议是把免费额度理解成“试用装”先把 OpenClaw 玩明白确认它能满足你的需求之后再考虑付费方案不迟。免费的够用付费的更稳定这不是一个非此即彼的选择题。3. 本地部署 OpenClaw 全流程实操3.1 环境准备该装的依赖一个都不能少在开始之前先检查一下你的系统环境。OpenClaw 官方推荐的是 Linux 或 macOS 环境Windows 上跑也没问题但需要额外处理一些依赖所以如果你手头有闲置的 Linux 机器或者装了 WSL建议优先用这些环境。需要准备的依赖有这几个Go 语言环境版本要求 1.22 以上Git用于拉取源码Node.js 和 npmOpenClaw 的前端界面和一些 skill 会用到一个能运行 Docker 的容器环境可选取决于你是否要用容器化插件安装依赖这块不同系统命令不太一样Ubuntu/Debian 系的可以直接用 apt 装macOS 用 brew 装Windows 强烈建议直接上 WSL。我自己的主环境是 Ubuntu 22.04下面是完整的依赖安装命令# 更新系统软件源 sudo apt update sudo apt upgrade -y # 安装基础工具链 sudo apt install -y git curl wget build-essential # 安装 Go这里以 1.22 为例建议直接装最新稳定版 wget https://go.dev/dl/go1.22.4.linux-amd64.tar.gz sudo tar -C /usr/local -xzf go1.22.4.linux-amd64.tar.gz echo export PATH$PATH:/usr/local/go/bin ~/.bashrc source ~/.bashrc go version # 安装 Node.js使用 nodesource 源比 apt 源版本新 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs node -v npm -v装完之后验证一下各工具的版本号确保没有报错再继续。这里有一个非常容易踩的坑如果你的系统之前装过旧版 Go 或 NodePATH环境变量可能指向了旧路径导致你新装的版本不生效。遇到这种情况直接重启终端或重新加载~/.bashrc即可。3.2 用官方安装脚本部署并指定 Git 安装方式环境准备好之后就开始正式部署了。OpenClaw 官方推荐的方式是通过安装脚本安装脚本会自己拉取依赖。不过这里有一个小技巧也是网上问得最多的安装脚本默认可能从 release 包下载但如果你希望直接从 GitHub 的 main 分支检出源码好处是能体验到最新的未发布功能而且后续升级方便需要在运行脚本时指定 git 安装方式。网上热词里正好有这个需求“可通过安装脚本指定 git 安装方式从 GitHub 的 main 分支检出源码”我实际操作下来的命令是这样的curl -fsSL https://openclaw.example.com/install.sh | bash -s -- --git --branch main脚本跑起来之后会做几件事检查依赖、克隆 OpenClaw 源码、编译二进制文件、设置系统服务。整个过程大概需要几分钟具体时间取决于你的网络和电脑性能。如果当前用户没有 sudo 权限建议提前用sudo -i切到 root 用户再执行否则后续写系统路径的时候会到处碰壁。编译完成之后OpenClaw 的二进制文件通常会安装在/usr/local/bin下配置文件则放在~/.openclaw/目录。你可以用openclaw --version验证一下安装是否成功。如果输出的版本号就是你指定的 main 分支编译出来的版本说明安装成功了。3.3 初始化配置模型服务怎么填安装只是第一步真正让 OpenClaw 跑起来的关键在于配置文件。首次运行openclaw init之后它会在~/.openclaw/config.yaml生成一个默认配置你需要手动修改其中的模型服务部分。配置的核心是填对base_url和api_key。以阿里云百炼平台为例配置长这样model_providers: - name: dashscope base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: sk-xxxxxxxxxxxxxxxxxxxxx default_models: - name: qwen-plus max_tokens: 4096这里要特别强调阿里云百炼的接口是兼容 OpenAI 格式的所以base_url一定要带/compatible-mode/v1这个路径少了这个后缀会导致请求 404。至于用哪个模型取决于你想干什么——如果只是日常对话和简单的工具调用qwen-plus足够如果想让它处理更复杂的推理任务可以试试qwen-max或qwen-turbo。不同的模型价格不一样在免费额度内尽量选择能满足需求但成本更低的那个。填完配置之后跑一下openclaw doctor检查配置是否正确。这个命令会模拟一次模型服务调用如果返回成功说明你的 Token 和网络都没问题如果报错大概率是前面哪一步没配对需要根据报错信息回头排查。4. 阿里云服务器部署的完整路径4.1 服务器选型与基础环境配置本地部署搞定之后咱们再来看服务器部署。我选择阿里云的逻辑很简单一是市场占有率最高遇到问题搜解决方案容易二是它家的百炼模型服务和服务器在同一个云环境内网络质量有保障三是如果你本来就要用阿里云的其它服务放一台服务器在同一个区域方便管理。服务器配置这块我的建议是 2 核 4G 起步。OpenClaw 本身不算特别吃资源但如果你是要把它作为常驻服务并且同时处理多个会话2 核 4G 是一个比较舒适的下限。系统镜像我推荐 Ubuntu 22.04原因无他——遇到的问题最少网上资料最全。买完服务器之后第一件事不是急着部署而是做好基础安全配置。这里我强烈建议你做两件事第一创建一个普通用户日常操作都用这个用户不要直接 root 裸奔第二配置 SSH 密钥登录关掉密码登录。阿里云控制台自带的安全组规则也要看一眼只开放必要的端口——SSH 的 22 端口、OpenClaw 默认的 Web 端口其它端口一律不开放。4.2 用 Docker 还是直接二进制部署服务器上的部署方式我强烈推荐用 Docker。原因很简单服务器是要长期跑服务的用 Docker 打包之后迁移、备份、回滚都非常方便不会再出现“在家里跑得好好的换台服务器就跑不起来了”的尴尬。用 Docker 部署 OpenClaw先安装 Docker 和 Docker Compose# 安装 Docker curl -fsSL https://get.docker.com | bash systemctl enable docker systemctl start docker # 验证安装 docker --version docker compose version然后创建一个项目目录编写docker-compose.yml。这里以搭配阿里云百炼模型服务为例完整的配置如下version: 3.8 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 8080:8080 environment: - OPENCLAW_MODEL_PROVIDERdashscope - OPENCLAW_API_BASEhttps://dashscope.aliyuncs.com/compatible-mode/v1 - OPENCLAW_API_KEY${DASHSCOPE_API_KEY} - OPENCLAW_DEFAULT_MODELqwen-plus volumes: - ./data:/var/lib/openclaw - ./skills:/opt/openclaw/skills logging: driver: json-file options: max-size: 10m max-file: 3注意看我在配置里用了一个${DASHSCOPE_API_KEY}环境变量占位符。这样做的目的是避免直接把密钥写死在 docker-compose 文件里——如果这个文件被分享或上传到代码仓库你的 Token 就泄露了。正确做法是在项目目录下创建一个.env文件内容就是DASHSCOPE_API_KEYsk-xxxxx然后在.gitignore里忽略掉它这样就只有你能看到密钥。启动之前先用docker compose config校验一下配置有没有语法错误。确认无误后docker compose up -d启动服务再用docker compose logs -f看日志。如果日志里出现listening on :8080之类的字样说明服务已经正常起来了。4.3 安全组、域名与 HTTPS 的必要性服务器部署完之后还有几个收尾工作是很多教程里不细讲但实际上非常重要的。首先是安全组配置你需要在阿里云控制台的安全组规则里放行 8080 端口或者你自定义的 OpenClaw 端口。这里有一个新手特别容易犯的错误——只放行了端口但没限制来源 IP导致服务器被全网扫到成了别人的“肉鸡”。我的建议是安全组来源 IP 只填你自己的 IP 白名单宁可临时麻烦一点改规则也不要图省事开0.0.0.0/0。然后是域名和 HTTPS 的问题。如果你只是自己用直接用http://服务器IP:8080访问就够了折腾域名意义不大。但如果你想在公网环境里安全地使用 OpenClaw 的 Web 界面尤其是要填 Token、配置 API Key 这些敏感信息那就必须上 HTTPS。最简单的方式是买一个域名解析到服务器 IP然后用 certbot 自动申请和续期免费证书。# 安装 certbot sudo apt install -y certbot python3-certbot-nginx # 申请证书并自动配置 Nginx 反向代理 sudo certbot --nginx -d yourdomain.com加一层 Nginx 反代的另一个好处是可以在 Nginx 层面做访问控制比如基本的账号密码认证双保险。我见过太多人图方便直接在公网裸跑一个没有任何认证的服务结果不到一天就被扫描机器人拿去做非法用途了。安全这个事不是“我不会被盯上”的问题而是“我设置了门槛坏人懒得花时间破解你的机器”的问题。5. Token 获取、配置与踩坑实录5.1 免费 Token 从哪里来一份可操作的清单前面讲了思路这里把具体的免费 Token 获取途径列一个清单。基于我自己的实测和社区反馈以下几个渠道目前是比较可靠的渠道免费额度情况申请方式适合谁阿里云百炼新用户获赠额度可免费调用多种模型控制台直接开通新手首选文档全各类模型聚合平台通常有免费层或试用额度官网注册申请想一个 Key 接多家模型的本地部署开源模型Ollama qwen/deepseek永久免费但需要算力无需申请有 GPU 或耐心的人部分开源模型服务商不定时限时免费关注官方公告愿意折腾、不定期换 Key 的申请完拿到 API Key 之后第一件事是先到模型服务商的官网测试一下能不能正常调用再往 OpenClaw 里填。不要跳过这步——很多人在 OpenClaw 里报错排查到最后一查发现是 Key 本身在服务商那边就没通过白白浪费大半天时间。测试方法也不复杂用 curl 模拟一次对话请求curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H Authorization: Bearer $DASHSCOPE_API_KEY \ -H Content-Type: application/json \ -d { model: qwen-plus, messages: [{role: user, content: 你好请回复我一句话}] }如果返回结果里带着choices和完整的content文本说明这个 Key 是好的可以放心往 OpenClaw 里填了。5.2 Token 过期与续签机制别被“永久免费”骗了Token 这个东西最大的坑就是“突然失效”。OpenClaw 里最常见的几个报错几乎全部跟 Token 相关。我直接贴几个我在实践中遇到、也在网上被反复讨论的错误信息看看你有没有中招jwt 实现 token 续签sign-in could not be completed token exchange failed: token endpoint returned status 403 forbiddenyour access token could not be refreshed. please log out and sign in againtoken exchange failed: error sending request出现这些报错的时候第一反应不要慌按以下顺序排查:第一步检查系统时间。这个原因听起来有点离谱但确实是我踩过最深的坑。JWT Token 的验证机制依赖时间戳如果你的服务器或本地电脑的时间偏差超过几分钟Token 会被判定为“未到生效时间”或“已过期”。用date -R命令看一下当前时间是否准确不准确就用sudo ntpdate ntp.aliyun.com强制同步一下然后重启 OpenClaw 服务再试。第二步检查你的 Token 是不是真的过期了。很多模型服务商提供的 Token 有效期可能只有几天或一个月过期之后 OpenClaw 用这个 Token 去请求模型服务就会被拒绝。解决方式是回到服务商控制台看 Token 的有效期如果确实过期了重新生成一个新的替换掉就行。第三步检查网络环境。token endpoint returned 403这个错误除了 Token 本身有问题之外还有可能是你的服务器或本地网络出口 IP 在模型服务商的限制范围内也就是网上常说的 “country” 限制问题。这个问题的解决方案不是绕过限制而是改用你所在地区支持的服务商或者用国内云厂商的模型服务比如阿里云百炼这才是顺手的正道。5.3 修改配置后必须重启服务别问我怎么知道的还有一个特别低级的坑但我估计至少有 80% 的人踩过改了配置文件之后没有重启服务然后对着日志百思不得其解。OpenClaw 的配置文件是在启动时加载的不是热更新的。你改了config.yaml里的 API Key、模型名称或 base_url必须重启服务才能生效。本地部署的话直接CtrlC停掉前台进程再重新运行Docker 部署的话用docker compose restart openclaw重启容器。重试之前先确认一下配置文件里的缩进格式对不对——YAML 对缩进极其敏感多一个空格少一个空格都会导致解析失败。网上那些 “我的配置明明是对的为什么还是报错” 的帖子我猜有一半是栽在缩进上。6. 集成 iFlow CLI给 OpenClaw 装上自动化引擎6.1 iFlow CLI 是干什么的在讲集成之前先解释一下 iFlow CLI 是什么。简单来说它是一个命令行工作流编排工具可以通过编写配置文件来定义一系列自动化任务比如“每天定时抓取某个网页的数据处理后写入数据库”“收到特定 webhook 请求时调用 OpenClaw 的 skill 执行一条命令”之类的场景。iFlow 负责“什么时候做什么事”OpenClaw 负责“具体怎么干”两者配合起来非常顺手。为什么要把 iFlow CLI 和 OpenClaw 集成在一起因为 OpenClaw 本身虽然能执行任务但它没有一个很自然的“触发器”机制。用大白话说你得主动跟它说“帮我做这个”它才会去做。而有了 iFlow你就可以设置定时任务或监听事件让 OpenClaw 在满足条件的时候自动被拉起干活。整个过程就像请了一个 7×24 小时在线、不需要睡觉的实习生。6.2 从安装到第一个自动化任务全流程集成过程并不复杂主要分三步装 iFlow CLI、写 iFlow 配置、在配置里调用 OpenClaw。第一步安装 iFlow CLI。它提供了跨平台的安装方式macOS 和 Linux 可以直接用脚本安装curl -fsSL https://iflow.example.com/install.sh | bash iflow --version装好之后需要初始化你的 iFlow 工作区。我的习惯是专门建一个目录存放所有 iFlow 配置文件不要把配置散落在各个项目里mkdir -p ~/iflow-workspace cd ~/iflow-workspace iflow init第二步写一个最简配置。假设我的需求是每天晚上 10 点执行一次“让 OpenClaw 生成当日工作总结”。在 iFlow 中这个需求可以写成workflow: name: daily-summary schedule: 0 22 * * * tasks: - name: call-openclaw exec: command: openclaw run skill.article --prompt 根据今天的日志生成工作总结 shell: true配置含义很简单${schedule} 字段用的是标准的 cron 表达式0 22 * * *就是每天 22 点触发exec.command指定要执行的命令这里调用 OpenClaw 的 CLI 来运行skill.article这个技能。第三步用iflow run daily-summary 手动执行一次验证配置是否能跑通。6.3 让 iFlow 与 OpenClaw 之间传参数的正确姿势上面那个例子是 iFlow 单方面调用 OpenClaw但在很多实际场景里我们需要把外部数据传给 OpenClaw让它基于这些数据做出判断或操作。这就需要了解 iFlow 和 OpenClaw 之间传参数的几种方式。最简单直接的方式是通过环境变量。iFlow 支持在workflow配置里定义env这些环境变量会传递给后续执行的命令workflow: name:>workflow: name: daily-metrics-digest schedule: 15 9 * * * env: DATA_URL: https://api.example.com/metrics?dateyesterday RAW_FILE: /tmp/metrics.json REPORT_FILE: /tmp/metrics_report.md FEISHU_WEBHOOK: ${FEISHU_WEBHOOK_URL} tasks: - name: fetch-data exec: command: curl -s $DATA_URL -o $RAW_FILE shell: true - name: openclaw-summary exec: command: openclaw run skill.summarize --input $RAW_FILE --output $REPORT_FILE shell: true - name: push-notification exec: command: curl -s -X POST $FEISHU_WEBHOOK -H Content-Type: application/json -d $REPORT_FILE shell: true这个配置执行起来就是一条流水线抓数据 → OpenClaw 总结 → 推送到飞书。整个过程跑起来之后我每天早上一到公司就能在手机上看到前一晚的自动分析报告基本不需要人工介入。如果想加新的数据源只需要在tasks里多加一步拉取数据的步骤即可扩展性很强。7. 高频问题排查与避坑指南7.1 Token 相关报错速查表把高频问题集中整理一下方便你直接对着自查报错信息大概率原因解决方案sign-in could not be completed token exchange failed: token endpoint returned status 403Token 无效、过期或网络出口被限制检查 Token 有效性换用可用环境或符合地区要求的服务商token exchange failed: error sending request网络不通无法连接到认证服务器检查网络连通性、DNS 解析、防火墙规则your access token could not be refreshedToken 过期且无法自动续期重新登录获取新 Token检查系统时间login failed. check api token or gitlab versionOpenClaw 连接 GitLab 时凭证或版本不匹配检查 GitLab Token 和 API 版本token endpoint returned status 40xToken 格式错误或已被吊销对比官方要求的 Token 格式重新生成注意看第一行如果你在阿里云的中国大陆服务器上部署 OpenClaw然后配置的是服务区域不在国内相兼容的模型服务出现 403 是大概率事件。这不是你的配置有错也不是代码 bug纯粹是网络限制。7.2 端口不通、日志刷屏、磁盘爆满等运维问题除了 Token服务器部署最常见的还是运维层面的问题。端口不通这个事我遇到过太多人“程序明明起来了但访问不了”一问才知道安全组规则没配。阿里云服务器的安全组相当于一道独立的防火墙你在系统里开的端口如果安全组不放行外部一样访问不了这是云服务器的通用逻辑。日志刷屏的问题主要出在 debug 级别日志上。OpenClaw 默认的日志等级可能打印得非常详细运行一段时间之后磁盘很容易被日志占满。建议在配置里调高日志等级并配置日志轮转。如果你是 Docker 部署建议在 compose 文件里加上日志大小限制——就像我前面给的那个示例配置一样。最后是磁盘爆满的问题。OpenClaw 在运行过程中会缓存历史会话、中间结果和 skill 产生的临时文件时间长了占用的空间很可观。养成定期清理的习惯比如每周跑一次docker system prune -f find ~/.openclaw/cache -type f -mtime 7 -delete7.3 关于升级的良心建议最后聊聊升级问题。OpenClaw 迭代速度很快网上很多用户问“如何升级 openclaw 版本”。如果你当初是用 git 安装方式部署的升级其实非常无脑cd /path/to/openclaw-src git pull origin main make build sudo make install service openclaw restartDocker 部署的升级方式就是拉新镜像、重建容器。但这里我要给一个良心建议不要每次出新版都立刻升级。先关注这个版本的 release notes看它有没有新增功能或修复了关键 bug如果没有特别需要的东西稳定运行就别动它。我曾经有一次为了尝鲜升级到最新的 main 分支构建版本结果某个 skill 依赖的接口改了白折腾一下午。稳定压倒一切这个道理在部署开源项目时同样适用。8. 一些个人经验与心得折腾 OpenClaw 这几个月我最大的感受是开源 AI 工具链的生态正在以肉眼可见的速度成熟起来。像 OpenClaw 这种集成了模型调用、工具执行、skill 扩展、CLI 编排的框架本质上是在帮我们把“大模型能做什么”这件事的边界往更远处推。它不需要你成为一个 AI 专家只要你懂基本的命令行操作就能搭建一个能自动干活的 AI 助手。对于刚开始接触的朋友我的建议是别一上来就追求把所有功能都跑通。先本地部署一个最简单的版本让它接上一个模型服务跑通一两个 skill感受一下自然语言驱动工具调用的体验。然后再逐步往上加需求——接 iFlow 做自动化、部署到服务器上常驻、接入更多外部工具和服务。循序渐进比一步到位更高效也更能帮助你理解每个环节的深层原理。在 Token 这件事上我想再啰嗦一句免费额度是很好的起点但不要因为免费就忽视 Token 的安全管理。API Key 一旦泄露损失的可能是你的账户余额和数据安全。不要在任何公开渠道贴出自己的 Token也不要把 Token 写死在会被上传到代码仓库的文件里。这篇教程里涉及的所有流程都是我亲测跑通的;你照着操作应该能少走不少弯路。最后分享一个小技巧在配置 OpenClaw 或者 iFlow 告警的时候如果一切正常但就是怀疑哪里不对先把日志级别调到 debug 再复现一次操作往往能发现很多隐藏的报错信息。祝大家的 OpenClaw 都能顺利跑起来早日解放双手。