手把手教你部署 OpenClaw：从 NodeJS 到 Swift/Kotlin 的多语言接入实践

1. OpenClaw 多语言部署到底难在哪NodeJS、Swift、Kotlin 三端接入的真实场景OpenClaw 是一个把 AI 能力封装成可跨端调用的网关型工具它本身跑在 NodeJS 运行时上同时对外暴露 WebSocket 与 HTTP 接口让 SwiftiOS/macOS、KotlinAndroid/JVM这类客户端也能接入同一套模型能力。说白了你只需要在一台服务器上把 OpenClaw 跑起来手机端、桌面端、脚本端都能通过统一通道调用大模型而不用每个端各自维护一套 API Key 和请求逻辑。适合谁用三类人最需要一是做跨端产品的独立开发者iOS 用 Swift、Android 用 Kotlin后端又不想重复写模型调用二是想把 AI 能力塞进现有 App 的移动端工程师三是需要统一管理多个模型供应商、又不想在每个客户端硬编码密钥的团队。核心检索词就是 OpenClaw 部署 与 NodeJS Swift Kotlin 多语言接入。我踩过的坑主要集中在三块第一OpenClaw 依赖 NodeJS 版本较新服务器自带的 Node 往往太旧openclaw onboard直接报模块找不到第二Swift 端用 URLSession 连 WebSocket 时如果 Gateway 只绑定 127.0.0.1模拟器根本连不上第三Kotlin 端 OkHttp 默认不允许明文 ws://需要额外配置网络安全策略。这三个问题后面会逐一给出可复制的解法。还有一个容易被忽略的点模型鉴权。OpenClaw 自身不管模型 Key 的轮换它只是把请求转发出去。如果你在 NodeJS、Swift、Kotlin 三端各自填一遍 Key维护成本极高一旦 Key 泄露或过期三端都要改。所以更合理的做法是让 OpenClaw 作为唯一出口客户端只跟 OpenClaw 通信模型 Key 统一放在服务端配置里。这也是本文要重点讲的统一 Key/API 通道思路。下面按「环境准备 → 统一通道配置 → 三语言接入 → 连通性验证 → 排障」的顺序展开每一步都给完整命令和配置片段你可以直接复制改参数。2. 部署前的统一通道准备用 TaoToken 打通模型鉴权与 API 入口在动手装 OpenClaw 之前先把模型通道这件事定下来。OpenClaw 支持 OpenAI 兼容接口也就是说只要有一个返回openai-completions格式的 baseUrl 和 apiKey就能接进去。TaoToken 提供的正是这样一个统一入口官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 不带任何多余参数。为什么建议用统一通道而不是每个模型单独配因为 OpenClaw 的配置文件~/.openclaw/openclaw.json里providers 是按供应商分组的如果你同时用三四个模型每个都要填 baseUrl、apiKey、models 列表改起来很痛苦。统一通道的好处是 baseUrl 只有一个Key 也只有一个模型 ID 通过请求参数区分客户端侧完全不用感知后端换了哪家模型。具体操作先到 https://taotoken.net/api-keys 创建一个 API Key记下来。然后在 OpenClaw 的配置文件里把 provider 的 baseUrl 指向https://taotoken.net/apiapi 字段写openai-completions。这样 OpenClaw 转发出去的请求就会走统一通道模型 ID 你填什么通道就路由到什么模型。这里有个细节要注意OpenClaw 的models.mode建议设为merge这样它会把内置模型列表和自定义 provider 合并不会因为覆盖而丢掉默认项。如果你设成replace内置模型全没了调试时容易懵。另外TaoToken 的 Coding Plan 适合长期挂后台写代码的场景模型对话入口适合临时验证模型是否通接入文档里有各语言的调用示例。这三个入口按需选排障和接入看 API Keys 加接入文档验证模型通不通用模型对话长期编码或跑 Agent 用 Coding Plan。地址分别是 https://taotoken.net/api-keys 、 https://taotoken.net/doc 、 https://taotoken.net/chat 、 https://taotoken.net/coding-plan 都带上 utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite 即可。把这一步做完你手里应该有一个可用的 API Key 和一个统一的 baseUrl。接下来装 OpenClaw 时模型配置直接引用这两个值三端接入就都省事了。3. 可复制配置NodeJS 环境安装 OpenClaw 与 openclaw.json 完整片段NodeJS 是 OpenClaw 的运行基础版本不对后面全白搭。实测 NodeJS 20 LTS 最稳18 也能跑但部分依赖会警告。先确认版本node -v # 期望输出 v20.x.x 或 v18.x.x npm -v如果版本太低用 nvm 装一个curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20然后全局安装 OpenClawnpm install -g openclaw openclaw --version安装完成后执行配置向导openclaw onboard向导里几个关键选择Onboarding mode 选 QuickStartConfig handling 首次随便选Model/auth provider 如果暂时不想配模型可以 Skip for nowDefault model 随便占位Select channel 选 Skip for nowSkills status 选 Yes 并空格多选常用工具最后 Hatch in TUI 通过终端使用。向导结束后会输出一段信息务必保存里面有 Gateway 地址和初始 token。接下来是核心编辑~/.openclaw/openclaw.json。下面这份配置把模型通道指向 TaoToken 统一入口同时保留并发和 workspace 设置。请把${TAOTOKEN_API_KEY}替换成你在上一步创建的真实 Key{ agents: { defaults: { model: { primary: taotoken/gpt-4o-mini }, maxConcurrent: 4, subagents: { maxConcurrent: 8 }, workspace: /root/.openclaw/workspace } }, models: { mode: merge, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, api: openai-completions, models: [ { id: gpt-4o-mini, name: GPT-4o mini via TaoToken }, { id: claude-3-5-sonnet, name: Claude 3.5 Sonnet via TaoToken } ] } } } }这份 JSON 里三件套齐全Base URL 是https://taotoken.net/apiKey 是${TAOTOKEN_API_KEY}Model ID 是gpt-4o-mini或claude-3-5-sonnet。OpenClaw 启动时会读取这个文件把 provider 注册进去。改完配置重启 Gatewayopenclaw gateway stop openclaw gateway start如果启动报reading choices之类的解析错误八成是 JSON 里多了逗号或少了引号用python -m json.tool ~/.openclaw/openclaw.json校验一下。NodeJS 侧还有一个可选步骤如果你想让 OpenClaw 以服务方式常驻可以写一个 systemd unit或者用 pm2npm install -g pm2 pm2 start openclaw --name openclaw -- gateway start pm2 save这样服务器重启后 OpenClaw 自动拉起不用每次手动敲命令。到这一步NodeJS 环境就算跑通了接下来验证请求。4. 连通性验证Swift 与 Kotlin 客户端如何调用 OpenClaw 并拿到模型返回先验证 NodeJS 侧本身通不通。OpenClaw 提供 CLI 对话入口直接发一条消息openclaw chat 用一句话解释什么是 WebSocket如果返回模型输出说明 OpenClaw 到 TaoToken 通道这条链路是通的。如果报 401检查openclaw.json里的 apiKey 是否替换成功如果报local proxy failed检查 baseUrl 是否写成了https://taotoken.net/api而不是带路径的地址。接下来是 Swift 端。Swift 通过 URLSession 的 WebSocket 任务连 OpenClaw Gateway。假设 Gateway 跑在ws://your-server-ip:18789token 是向导输出的那个。先看配置在openclaw.json里把 Gateway 的 bind 改成 lanmode 改成 remote这样外部才能连。# 查看当前 token cat ~/.openclaw/openclaw.json | grep tokenSwift 侧代码片段import Foundation let url URL(string: ws://your-server-ip:18789?tokenYOUR_GATEWAY_TOKEN)! let task URLSession.shared.webSocketTask(with: url) task.resume() let payload {type:chat,model:taotoken/gpt-4o-mini,messages:[{role:user,content:你好}]} task.send(.string(payload)) { error in if let error error { print(发送失败: \(error)) } } task.receive { result in switch result { case .success(let message): switch message { case .string(let text): print(收到: \(text)) case .data(let data): print(收到二进制: \(data.count) 字节) unknown default: break } case .failure(let error): print(接收失败: \(error)) } }注意 iOS 默认 ATS 策略会拦截明文 ws://需要在 Info.plist 里加NSAppTransportSecurity的NSAllowsArbitraryLoads为 true仅测试环境这么干生产建议上 wss。Kotlin 端用 OkHttp 的 WebSocketimport okhttp3.* import java.util.concurrent.TimeUnit val client OkHttpClient.Builder() .readTimeout(0, TimeUnit.MILLISECONDS) .build() val request Request.Builder() .url(ws://your-server-ip:18789?tokenYOUR_GATEWAY_TOKEN) .build() val ws client.newWebSocket(request, object : WebSocketListener() { override fun onOpen(webSocket: WebSocket, response: Response) { val payload {type:chat,model:taotoken/gpt-4o-mini,messages:[{role:user,content:你好}]} webSocket.send(payload) } override fun onMessage(webSocket: WebSocket, text: String) { println(收到: $text) } override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) { println(失败: ${t.message}) } })Android 端如果连明文 ws://需要在AndroidManifest.xml的 application 标签加android:usesCleartextTraffictrue或者配 network security config 只对特定域名放行。三端都连上后你会看到同一个模型返回结果因为模型调用统一走 OpenClaw 转发到 TaoToken 通道客户端只负责收发消息。这就是统一 Key/API 通道的价值Swift 和 Kotlin 里没有出现任何模型供应商的 Key只有 Gateway token。5. 常见报错排查401、local proxy failed、reading choices、OAuth 逐个击破排障第一步永远是看日志。OpenClaw 的日志在~/.openclaw/logs/下tail -f盯着看报错信息比终端输出详细得多。401 Unauthorized两种可能。一是 Gateway token 不对检查 URL 里的?token是否和openclaw.json里一致二是模型通道的 apiKey 不对检查${TAOTOKEN_API_KEY}是否真的替换成了 Key而不是留着占位符。用curl直接测通道curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer YOUR_KEY \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:ping}]}如果这条 curl 返回 401说明 Key 本身有问题跟 OpenClaw 无关。local proxy failed通常是 baseUrl 写错。OpenClaw 期望的 baseUrl 是https://taotoken.net/api它内部会拼/v1/chat/completions。如果你写成https://taotoken.net/api/v1就会变成/v1/v1/chat/completions直接 404 或 proxy failed。改回不带/v1的地址即可。reading choices 报错这是 OpenClaw 解析模型返回时找不到choices字段。原因一般是通道返回了非 OpenAI 格式的错误响应比如 HTML 错误页。用上面的 curl 确认返回是标准 JSON如果返回的是网关错误页检查请求头是否带了Content-Type: application/json。OAuth 相关报错如果你在向导里选了 OAuth 登录某个模型供应商但服务器没有浏览器会卡住。解决办法是跳过 OAuth改用 API Key 方式。在openclaw.json里删掉 OAuth 相关 provider换成 apiKey 字段。Codex 的auth.json如果存在冲突把它备份后清空让 OpenClaw 重新生成。Gateway 连不上先确认端口监听ss -tlnp | grep 18789如果只监听 127.0.0.1说明 bind 还是 loopback改成 lan 并重启。云服务器还要检查安全组是否放行了 18789 端口。pairing required公网访问时出现这个说明设备没授权。执行openclaw devices list找到 Pending 列表复制 Request ID然后openclaw devices approve request-id刷新页面即可。CC Switch / Cline MCP 场景如果你在 Cline 里配 MCP 连 OpenClaw三件套要写全Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填gpt-4o-mini。少任何一个都会连不上。CC Switch 切换配置时同理别只改 Key 不改 baseUrl。把这几类报错对照日志逐个排掉端到端链路基本就稳了。最后提醒一句生产环境别用--allow-unconfigured启动那个模式没有任何鉴权等于把模型通道裸奔在公网上。6. 从跑通到用好多语言接入后的统一 Key 管理与调用入口跑通之后真正影响长期使用的是 Key 管理和调用入口的稳定性。三端接入 OpenClaw 后客户端侧只认 Gateway token模型 Key 只在服务端openclaw.json里出现一次。这意味着你换模型、换供应商、轮换 Key都只改一个文件Swift 和 Kotlin 代码一行不用动。统一入口建议固定用 https://taotoken.net/api 配合 https://taotoken.net/api-keys 管理 Key。如果你要长期挂后台跑编码任务Coding Plan 入口 https://taotoken.net/coding-plan 更合适临时验证模型通不通用模型对话 https://taotoken.net/chat 最快接入细节查文档 https://taotoken.net/doc 。这四个入口按场景分流别只收藏首页。一个实用技巧在openclaw.json里给不同客户端配不同的 agent比如 Swift 端走gpt-4o-mini省成本Kotlin 端走claude-3-5-sonnet要质量通过请求里的 model 字段区分。OpenClaw 的agents.defaults.model.primary只是默认值客户端可以覆盖。最后定期用openclaw devices list清理不再使用的授权设备避免 token 泄露后被人白嫖模型额度。Key 轮换时先在新 Key 生效后再删旧 Key中间留个重叠期防止正在跑的请求断掉。