1. Openclaw 源码部署第一步到底卡在哪环境配置与 HTTPS 访问的真实门槛Openclaw 是一个开源、可本地部署的个人 AI 智能体核心能力是真正动手做事——执行终端命令、管理文件、写代码、跑浏览器自动化还带两周记忆和跨平台交互。它适合愿意自己掌控数据、想给 AI 开系统级权限的开发者也适合拿一台闲置机器长期挂着的折腾党。但很多人第一次源码部署卡住的地方往往不是代码本身而是三件事Node 环境版本对不上、模型 Key 到处散落难管理、以及那个绕不过去的报错disconnected (1008): control ui requires HTTPS or localhost (secure context)。我试过在一台干净的 Ubuntu 24.04 上从零走一遍整个过程大概两三个小时其中一半时间花在证书和 nginx 上。这篇就把环境配置、TaoToken 统一 Key 接入、nginx 反代加 SSL 证书这条链路拆开讲清楚每一步都给可复制的命令和配置。你跟着做能少走不少弯路。先说清楚 Openclaw 的架构理解了这个后面配置才知道每步在干什么。它分四层Gateway 负责连接外部交互入口把消息路由给 AgentAgent 是核心推理决策单元接 Claude、OpenAI 或本地模型处理上下文和记忆Skills 是可扩展操作能力网页调研、邮箱读写、浏览器自动化都靠它Memory 是持久化知识库两周对话记录和工作习惯以 Markdown 文件本地保存。这四层里Agent 接哪个模型、Key 怎么管就是本篇要解决的核心问题之一。为什么强调用统一 Key 通道因为 Openclaw 的 Agent 层可以接多家模型如果你每个模型都单独配一套 Key、单独记一套 Base URL配置文件会越来越乱换模型时改到崩溃。用 TaoToken 这类统一通道一个 Key 打通多个模型Base URL 只写一处后面想切模型只改 Model ID 就行。这对源码部署场景特别友好因为你要反复重启 gateway 调配置Key 越集中越省事。环境这块Ubuntu 24.04 是当前比较稳的选择。不建议直接用 root 跑 Openclaw它权限极高能操作软件、执行终端命令给它单独整一台机子或者单独开一个角色更安全。下面从建角色开始一步步来。2. TaoToken 前置准备统一 Key 与 API 通道怎么配进 Openclaw在动 Openclaw 源码之前先把模型通道准备好这样 onboard 的时候直接填不用中途停下来找 Key。TaoToken 的作用是提供一个统一的 API 入口你拿到一个 Key配上 Base URL就能在 Openclaw 里调用多个模型。对源码部署来说这意味着你的配置文件里模型相关的东西集中在一处排查问题也方便。第一步是拿 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进控制台在 API Keys 页面创建一个新 Key。创建时给它起个能认出来的名字比如openclaw-local方便以后区分。Key 只在创建时完整显示一次复制下来存好别直接贴在会提交到 git 的文件里。拿到 Key 之后记下两个关键信息Base URL 是https://taotoken.net/apiModel ID 按你要用的模型填。Openclaw 的 Agent 层支持 Claude、OpenAI 以及国内的千问、MiniMax、GLM 等你可以在模型对话页面先确认目标模型的准确 ID再填进配置。这一步别偷懒Model ID 写错是最常见的 401 和 404 来源。如果你后面打算长期跑编码类 Agent 任务可以了解下 Coding Plan它针对持续编码场景做了额度安排只是验证模型连通性的话用模型对话页面测一下就行。接入文档在 doc 页面里面有各语言的调用示例配 Openclaw 时对着看 Base URL 和鉴权头的写法。这里要提醒一点TaoToken 是合规的 API 通道服务不是所谓的中转配置时按官方文档的 Base URL 和鉴权方式写就行。把 Key 和 Base URL 准备好接下来进服务器配环境。3. 可复制配置从建角色到 nginx SSL 证书全流程这一节是重头戏所有命令和配置都可以直接复制。我按顺序来建角色、配 git、装 Node、拉源码、配 nginx、申请证书。先建一个专用角色别用 root 跑# 创建角色 sudo useradd -m -s /bin/bash openclaw # 修改密码 sudo passwd openclaw # 加入 sudo 组 sudo usermod -aG sudo openclaw然后退出 root用这个新角色重新登录。如果你本身就是被分配好的普通角色跳过这步。配 git 基本信息并生成公钥git config --global user.name YourName git config --global user.email youexample.com ssh-keygen -t rsa -C youexample.com把~/.ssh/id_rsa.pub内容复制到 GitHub 的 Settings → SSH and GPG keys → New SSH key。到这里 git 配置完成。装 Node用 nvm 管理版本最省心# 安装 nvm curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash # 赋予执行权限 chmod x ~/.nvm/nvm.sh # 刷新环境变量 source ~/.bashrc # 安装 LTS 版本 nvm install --lts nvm use --lts node -v # 安装 pnpm npm install -g pnpm # 换国内源加速 pnpm config set registry https://registry.npmmirror.com/ npm config set registry https://registry.npmmirror.com/拉源码并构建git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm ui:build pnpm build pnpm openclaw onboard --install-daemononboard 过程中会让你选模型通道。这里填 TaoToken 的 Base URLhttps://taotoken.net/api和你的 KeyModel ID 按目标模型填。渠道和 skill 这步可以先跳过后面再补。完成后会给出一个本地访问地址形如http://localhost:18789/#tokenxxxx本地能打开但云服务器远程访问会报disconnected (1008): control ui requires HTTPS or localhost (secure context)因为 control UI 只认 HTTPS 或 localhost。下面配域名和证书。先把域名解析到服务器公网 IP然后验证nslookup your.domain.com看到解析到你的公网 IP 就对了。接着装 certbot 申请 Lets Encrypt 证书sudo apt update sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d your.domain.com第一次会让你输邮箱、同意条款按提示走。成功后证书路径一般是/etc/letsencrypt/live/your.domain.com/fullchain.pem /etc/letsencrypt/live/your.domain.com/privkey.pemfullchain.pem是域名证书加中间证书的完整链nginx 里用ssl_certificate指定privkey.pem是私钥用ssl_certificate_key指定必须保密。如果 80/443 没开放或域名没解析对申请会报错如果标准证书在 80 端口不可用可以降级到 DNS 验证sudo certbot certonly --manual --preferred-challengesdns -d *.your.domain.com装 nginx 并配置sudo apt update sudo apt install nginx sudo vim /etc/nginx/nginx.conf下面这份配置可以直接用把域名和证书路径替换成你自己的worker_processes auto; events { worker_connections 1024; } http { include mime.types; default_type application/octet-stream; client_max_body_size 10M; sendfile on; keepalive_timeout 65; # HTTP 强制跳转 HTTPS server { listen 80; server_name your.domain.com; return 301 https://$host$request_uri; } # HTTPS 配置 server { listen 443 ssl; server_name your.domain.com; ssl_certificate /etc/letsencrypt/live/your.domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your.domain.com/privkey.pem; root /usr/share/nginx/html; location / { proxy_pass http://localhost:18789/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 86400s; proxy_send_timeout 86400s; } error_page 404 /404.html; location /404.html { internal; } error_page 500 502 503 504 /50x.html; location /50x.html { internal; } } }检测并重载nginx -t sudo systemctl reload nginx从域名访问报错会从secure context变成disconnected (1008): pairing required。这是因为 control UI 还没允许 HTTPS 来源在 Openclaw 配置里加上controlUi: { allowedOrigins: [ http://localhost:18789, http://127.0.0.1:18789, https://your.domain.com ], allowInsecureAuth: true }改完重启服务pnpm openclaw gateway restart访问https://your.domain.com/#tokenxxxx就能正常进了。4. 验证请求curl 测通 TaoToken 接口与 Openclaw 服务状态配置写完不算完得验证。分两步先确认 TaoToken 接口通再确认 Openclaw 服务活着。测 TaoToken 接口连通性用 curl 发一个最小请求。把 Key 和 Model ID 换成你自己的curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { model: YOUR_MODEL_ID, messages: [{role: user, content: ping}], max_tokens: 16 }返回里能看到choices数组和内容说明 Key、Base URL、Model ID 三者都对。如果返回 401是 Key 问题返回 404 或提示模型不存在是 Model ID 写错返回reading choices相关错误多半是响应结构没解析对检查请求体格式。再验证 Openclaw 服务状态pnpm openclaw gateway status看到 running 就对了。然后浏览器打开https://your.domain.com/#tokenxxxx如果页面正常加载、能发消息并收到模型回复整条链路就通了。这一步的 curl 验证很关键它把模型通道和 Openclaw 服务解耦开出问题时能快速定位是哪一层。如果你在 onboard 时选了 TaoToken 通道Openclaw 内部调用走的就是同一个 Base URLcurl 通了基本就稳了。实测下来大部分接入失败都发生在 Key 复制带了空格、Model ID 大小写不对、或者 Base URL 多写了斜杠这几种情况。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 逐个拆部署过程里报错集中在几个地方我按真实遇到的顺序列出来。401 UnauthorizedKey 不对或没带上。检查 curl 里的Authorization: Bearer后面有没有多余空格Key 是不是复制完整。Openclaw 配置里如果 Key 写在 JSON 里注意引号别漏。local proxy failed通常是 Openclaw 的 gateway 没起来或者 nginx 反代的目标端口不对。先pnpm openclaw gateway status确认服务在跑再检查 nginx 里proxy_pass http://localhost:18789/端口和 Openclaw 实际监听端口一致。如果改了 Openclaw 端口nginx 也要同步改。reading choices类错误模型返回结构和你预期的不一样常见于 Model ID 填错导致返回了错误对象或者请求体里messages格式不对。用第 4 节的 curl 单独测一次确认返回里有choices。OAuth相关报错如果你在 onboard 时选了需要 OAuth 的通道但没完成授权流程会卡在这。源码部署场景建议先用 API Key 方式接 TaoToken稳定后再考虑其他通道。disconnected (1008): control ui requires HTTPS or localhost没配 HTTPS 或没走 localhost。按第 3 节配 nginx 和证书。disconnected (1008): pairing requiredHTTPS 配好了但 control UI 没允许该来源。在配置里加allowedOrigins和allowInsecureAuth重启 gateway。证书申请报错80/443 没开放或域名没解析到本机 IP。先nslookup确认解析再检查安全组端口。标准证书不可用时降级 DNS 验证。这里涉及 Base URL、Key、Model ID 三件套的地方务必三个一起核对。任何一个写错都会表现成不同报错排查时先怀疑这三样。6. 后续接入与长期使用从模型对话到 Coding Plan 的路径环境通了、HTTPS 能访问了接下来就是让它真正干活。你可以先在模型对话页面把要用的几个模型都测一遍确认哪个在 Openclaw 里响应稳定再决定长期用哪个。如果打算让它跑编码类 Agent 任务Coding Plan 的额度安排更适合持续调用场景比按次调用省心。源码部署的好处是更新快Openclaw 版本迭代频繁源码方式能第一时间跟上。代价是每次更新要重新pnpm install和pnpm build所以建议把配置和 Key 放在独立文件里别混进源码目录更新时不至于被覆盖。下一章会讲怎么配企业微信和飞书的 channel在通讯工具里直接和 Openclaw 交互。那部分涉及 Gateway 层的消息路由和本篇的模型通道是两条线配好之后你的 Openclaw 才算真正能远程使唤。最后给个实用技巧把pnpm openclaw gateway restart和nginx -t sudo systemctl reload nginx写成两个 alias改配置后一条命令重启省得每次翻历史。证书 90 天到期certbot 装好后可以加个定时续期sudo certbot renew --dry-run先测一次确认自动续期能跑通免得某天突然 HTTPS 失效。