1. Ubuntu 部署 OpenClaw 到底难在哪从零跑通 ApiKey 与飞书接入OpenClaw 是一个可以跑在自有服务器上的 AI Agent 网关它能对接多种大模型服务把对话、工具调用、消息通道统一管理起来。你可以把它理解成一个「AI 管家」模型是大脑OpenClaw 是神经中枢飞书、GUI 面板这些就是它的手脚和嘴巴。适合谁适合手里有一台 Ubuntu 服务器、想让 AI 帮自己干活装软件、查状态、收发飞书消息的开发者或运维同学。很多人第一次部署 OpenClaw 会卡在三个地方一是 ApiKey 拿到手不知道怎么正确写进配置二是飞书机器人接进去之后消息发不出来三是服务起来了但 GUI 打不开、状态查不到。这篇教程就按「环境准备 → ApiKey 配置 → 服务启动 → 飞书接入 → 连通性验证 → 报错排查」的顺序把每一步的命令和配置文件都给你照着敲就能跑通。我用的环境是 Ubuntu 20.04、2C4G 的云服务器这个配置跑 OpenClaw 完全够用。下面所有命令都可以直接复制路径和字段名保持和实际配置文件一致你替换成自己的 IP、Key、AppId 即可。先说清楚整体链路你在模型服务商那边创建一个 ApiKey把它写进 OpenClaw 的模型配置里OpenClaw 启动网关后监听 18789 端口GUI 和飞书都通过这个网关和 Agent 通信。飞书那边你要建一个企业自建应用拿到 AppId 和 AppSecret通过openclaw channels login --channel feishu把通道接上。整条链路任何一环断了消息都收发不了所以每一步都要验证。2. 部署前的环境准备与 OpenClaw 安装Ubuntu 手动装 Node 24 避免安装失败OpenClaw 安装脚本会自动装环境但实测下来网络波动经常导致 Node 安装中断所以建议先手动把基础环境装好再跑安装脚本。这一步能省掉后面很多莫名其妙的报错。先更新源并安装基础工具sudo apt-get update sudo apt-get install -y curl git jq ca-certificates接着装 Node.js 24。OpenClaw 对 Node 版本有要求版本太低会在启动时报语法错误curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - sudo apt-get install -y nodejs装完确认版本正常应该看到 v24.xnode -v npm -v然后跑 OpenClaw 官方安装脚本curl -fsSL https://openclaw.ai/install.sh | bash安装过程中会交互式问你几个问题一路yes回车继续。到了大模型配置环节选择「更多」找到你用的模型服务商比如百炼模式选「标准 Api 模式」然后粘贴你的 ApiKey模型名自己手动输入。安装完成后就能和 Agent 对话了按两次CtrlC退出。退出后检查服务状态这两个命令很关键openclaw gateway status openclaw status --all如果gateway status显示 running说明网关起来了。接下来配置 GUI 访问地址编辑配置文件vim ~/.openclaw/openclaw.json搜索bind字段把它改成lan这样局域网内可以访问。改完重启网关openclaw gateway restart然后设置允许访问 GUI 的来源地址。第二段填你服务器的内网地址第三段填公网地址没有公网就删掉那一段openclaw config set gateway.controlUi.allowedOrigins [http://127.0.0.1:18789,http://192.168.60.100:18789,http://你的公网IP:18789] openclaw config set gateway.controlUi.allowInsecureAuth true openclaw config set gateway.controlUi.dangerouslyDisableDeviceAuth true检查配置是否写进去了openclaw config get gateway.controlUi.allowInsecureAuth cat ~/.openclaw/openclaw.json | grep -i -A2 -B2 device期望看到true和dangerouslyDisableDeviceAuth: true。确认无误后重启服务生效openclaw gateway restart openclaw dashboard --no-open浏览器访问http://你的服务器IP:18789如果提示要 token用这个命令找grep token ~/.openclaw/openclaw.json把 token 填进去就能进 GUI 了。进去之后 Agent 会让你给它取个名字取完就可以让它干活了。这里有个小坑Ubuntu 默认不允许 root 登录Agent 在装 nginx 这类需要提权的操作时会权限不够它会给你两个方案——它自己装或者你给它权限。我试过把权限交给它它会自动配置清华源镜像、改端口装完还会自己验证确实省事。3. ApiKey 配置与 settings 片段把 Key、Base URL、Model ID 三件套写对ApiKey 配置是整篇教程的核心配错了后面全白搭。OpenClaw 的模型配置写在~/.openclaw/openclaw.json里你需要保证三件套齐全Base URL、ApiKey、Model ID。缺任何一个请求都会失败。如果你用的是兼容 OpenAI 协议的服务配置片段大概长这样路径和字段名以你实际文件为准{ models: { providers: { custom: { baseUrl: https://taotoken.net/api, apiKey: sk-你的ApiKey, models: [ { id: claude-sonnet-4-5, name: Claude Sonnet 4.5 } ] } } } }如果你更习惯用环境变量管理 Key可以写一个.env模板避免 Key 硬编码进配置文件# ~/.openclaw/.env OPENCLAW_MODEL_BASE_URLhttps://taotoken.net/api OPENCLAW_MODEL_API_KEYsk-你的ApiKey OPENCLAW_MODEL_IDclaude-sonnet-4-5然后在openclaw.json里引用这些变量。这样换 Key 的时候只改一个地方不用满文件找。关于 ApiKey 的获取你需要在模型服务商的控制台创建一个。创建成功后立刻保存很多平台只显示一次关掉页面就查不到了。如果是试用额度记得勾选「免费额度用完即停」避免产生意外扣费。如果你用的是 Claude Code 这类需要 Anthropic 协议的工具配置方式略有不同Base URL 和 Model ID 要按对应文档填。OpenClaw 支持多种协议选「标准 Api 模式」时根据你的模型类型来选选错了会报 401 或协议不匹配。配置写完后用这个命令验证配置是否被正确读取openclaw config get models如果输出里能看到你的 baseUrl 和 model id说明写对了。看不到就检查 JSON 格式逗号、引号最容易出错。改完配置记得重启网关openclaw gateway restart这里强调一下Base URL 不要带多余的路径后缀Model ID 要和平台文档里写的完全一致大小写敏感。我踩过的坑就是 Model ID 多写了个-latest结果一直报模型不存在。4. 飞书机器人接入与连通性验证从创建应用到消息收发测试飞书接入分两步飞书后台建应用拿凭证服务器上用 OpenClaw 命令接通道。先去飞书开发者后台创建一个企业自建应用创建完在「凭证与基础信息」里拿到 AppId 和 AppSecret这两个待会要用。然后给应用开通机器人能力配置好权限至少要有收发消息的权限。回到服务器安装飞书插件并登录通道openclaw channels login --channel feishu按提示输入 AppId 和 AppSecret一路回车对接完成。然后登录飞书找到你的机器人发条消息试试。如果机器人回复权限不足它会给你一条命令在服务器上执行openclaw pairing approve feishu 2LGF7WYA这个2LGF7WYA是配对码每次不一样以实际输出为准。执行完再发消息机器人就能正常回复了。验证连通性除了飞书发消息还可以用命令行直接测网关curl -s http://127.0.0.1:18789/health返回ok或类似状态就说明网关正常。再查一下通道状态openclaw channels status看到 feishu 显示 connected 就说明通道通了。如果显示 disconnected检查 AppId/AppSecret 是否填错或者飞书后台的权限有没有开全。GUI 那边也可以验证浏览器进http://你的IP:18789在对话窗口发一句话Agent 能回就说明模型链路通了。飞书那边发消息Agent 能回就说明通道链路通了。两条链路都通整个部署就算完成。5. 常见报错排查401、local proxy failed、reading choices、OAuth 逐个击破部署过程中最容易遇到的几个报错我按实际碰到的整理一下对照着查。401 UnauthorizedApiKey 错了或者没生效。先确认 Key 有没有多余空格再确认 Base URL 和 Key 是不是配套的不同服务商的 Key 不能混用。改完配置一定要openclaw gateway restart不然读的还是旧配置。local proxy failed通常是网关没起来或者端口被占。先openclaw gateway status看状态没起来就openclaw gateway restart。端口被占的话检查 18789 是不是被别的进程用了lsof -i:18789reading choices 报错这个多半是模型返回格式和 OpenClaw 预期不一致常见于 Model ID 填错或者协议选错。确认你选的模式标准 Api 模式和模型类型匹配Model ID 和平台文档完全一致。OAuth 相关报错如果你用的是需要 OAuth 的通道或模型检查 token 有没有过期。飞书通道的凭证是 AppId/AppSecret不是 OAuth token别搞混。Claude Code 这类工具的 OAuth 配置要单独走它的认证流程。GUI 打不开先确认allowedOrigins里有没有你访问用的地址allowInsecureAuth和dangerouslyDisableDeviceAuth是不是都设成了 true。再看防火墙有没有放行 18789 端口sudo ufw status sudo ufw allow 18789飞书消息发不出去先openclaw channels status看通道状态再检查飞书后台的机器人权限和事件订阅有没有配好。配对码那步别忘了执行openclaw pairing approve feishu 配对码。排查的核心思路就一条先确认网关活着再确认配置读对了最后确认通道连上了。三层都过问题基本就定位到了。6. 跑通之后怎么用把 OpenClaw 接进日常开发流部署跑通只是开始真正省事的是把它接进日常流程。GUI 面板适合临时对话和调试飞书适合随时随地发指令命令行适合脚本化调用。如果你要长期用 OpenClaw 做编码或 Agent 任务建议走 Coding Plan额度和稳定性比按量付费更适合高频场景。需要管理多个 Key 或者查看用量去控制台。想先试试模型对话效果可以直接在模型对话页面体验。ApiKey 的创建和管理在 API Keys 页面接入文档在文档中心Claude Code 相关的配置参考 ClaudeCodeAnthropic 页面。日常使用中我建议把常用的 Agent 指令存成脚本比如「检查服务状态」「重启网关」「查看通道连接」这样不用每次手敲。飞书那边可以建个群把机器人拉进去团队一起用。最后提醒一句dangerouslyDisableDeviceAuth这个选项方便但有风险只在你信任的网络环境里开。公网暴露的服务器建议配合防火墙白名单或者反向代理加认证别裸奔。配置改完记得重启网关这是最容易忘的一步。