自托管AI网关OpenClaw部署指南：统一管理多模型API，打造私有AI调度中心

1. 项目概述：为什么需要一个自托管的AI网关？

如果你和我一样，尝试过将不同的AI模型（比如Claude、Gemini、GPT-4o）集成到自己的自动化脚本、智能助手或者开发工具链里，那你一定遇到过这些麻烦：每个AI服务商都有自己的一套API格式、认证方式和计费规则；想切换个模型，就得重写一大段代码；更别提那些API调用限制、网络延迟和隐私顾虑了。OpenClaw Gateway 就是为了解决这些问题而生的。它是一个开源的、可自托管的AI网关，你可以把它理解为你本地网络里的一个“AI路由器”。

它的核心价值在于统一和控制。通过一个统一的API端点（兼容OpenAI的格式），你可以接入Google Gemini、Anthropic Claude、OpenRouter、Ollama本地模型等十几种AI服务。这意味着你的应用程序只需要写一套代码，就能在后台灵活调用不同的模型，甚至根据成本、速度或任务类型自动选择最合适的那个。更重要的是，所有数据都流经你自己的服务器，你完全掌控日志、缓存、费用和隐私。这对于有合规要求的企业、注重数据隐私的开发者，或者只是想折腾点好玩智能家居项目的极客来说，吸引力是巨大的。

这个项目本身是用Node.js写的，但官方提供了Docker镜像，这让部署变得极其简单。无论你用的是闲置的树莓派、家里的Synology NAS、云服务器，还是Windows/Mac开发机，只要装了Docker，就能在几分钟内跑起来一个属于你自己的AI调度中心。接下来，我会带你从零开始，手把手完成部署、配置、安全加固到日常维护的全过程，并分享一些我踩过坑才总结出来的实战经验。

2. 核心设计思路与架构拆解

在动手之前，理解OpenClaw Gateway是怎么工作的，能帮你更好地规划部署和排查问题。它的架构设计得很清晰，主要分为三层：网关核心、配置与数据持久化、以及外围服务。

2.1 网关核心：Docker容器内的微服务

项目提供的docker-compose.yml文件定义了两个核心服务：

1. openclaw-gateway: 这是主角，基于ghcr.io/openclaw/openclaw:main镜像运行。它暴露了两个端口：

   • 18789: 主网关端口。承载Web UI用户界面、WebSocket实时通信，以及最重要的——OpenAI兼容的API（路径为/v1/*）。你的所有客户端应用（如Open WebUI、Cursor编辑器）都通过这个端口与之通信。
   • 18790: 辅助端口。用于桥接协议或节点间连接，比如未来连接多个树莓派节点构成分布式集群时会用到。 容器启动时，会执行一个组合命令：首先设置一个关键配置gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback为true，这允许网关在通过反向代理（如Nginx Proxy Manager）访问时能正确工作；然后以--allow-unconfigured模式启动，这意味着即使你还没配置任何AI供应商的API密钥，网关也能先跑起来，方便你通过Web UI完成后续设置。

2. watchtower: 这是一个独立的自动更新工具。它每天凌晨4点检查一次Docker Hub或GHCR上的镜像是否有更新。如果发现openclaw-gateway镜像有新版本，它会自动拉取并重启容器，实现无人值守更新。最贴心的是，它采用了“标签作用域”模式，只更新那些明确打上了com.centurylinklabs.watchtower.enable: "true"标签的容器。所以你完全不用担心它会动你的其他服务（比如Plex、Home Assistant数据库）。

2.2 数据持久化：Volume映射的智慧

Docker容器本身是无状态的，重启后所有改动都会丢失。因此，将关键数据“映射”到宿主机是必须的操作。OpenClaw通过volumes指令映射了两个目录：

• ./config:/home/node/.openclaw: 这里存放网关的所有配置，包括你添加的AI供应商API密钥（加密后存储）、设备配对令牌、网关设置等。这是你的命根子，务必定期备份。
• ./workspace:/home/node/.openclaw/workspace: 这是AI代理的工作空间。你可以在这里放置AGENTS.md（定义代理行为）、SOUL.md（定义代理“性格”），以及代理生成或需要的文件。这相当于给了AI一个本地硬盘。

重要经验：在Linux或NAS上，权限问题是第一大坑。容器内的应用默认以用户node(UID=1000) 运行。如果你在宿主机上用root创建了config和workspace文件夹，容器就会因权限不足而启动失败，报EACCES错误。解决方法很简单，在启动容器前，先执行sudo chown -R 1000:1000 ./config ./workspace把文件夹所有权改过来。

2.3 环境变量与安全基石：.env文件

OPENCLAW_GATEWAY_TOKEN是这个系统安全的第一道闸门。它相当于网关的管理员密码。没有这个令牌，即使有人知道了你的IP和端口，也无法接入。这个令牌在.env文件中定义，并通过环境变量注入容器。务必使用强随机字符串，比如用openssl rand -hex 32生成一个64位的十六进制密钥。永远不要使用默认值或简单的密码。

3. 多平台部署实战与避坑指南

官方文档给出了四大平台的部署步骤，看似雷同，但每个平台都有独特的“坑点”。我结合自己的经验，为你提炼出每个平台的关键操作和注意事项。

3.1 在Synology NAS上部署：利用闲置资源

群晖NAS是绝佳的家庭服务器选择，7x24小时低功耗运行。部署的核心在于通过SSH连接到NAS的底层系统（DSM是基于Linux的）。

关键步骤与避坑：

1. 开启SSH：在DSM的“控制面板” -> “终端机和SNMP”中启用SSH服务，记住端口号（默认22）。
2. 连接与导航：使用任何SSH客户端（如PuTTY、Terminal）连接。重要：登录后，你通常位于/var/services/homes/你的用户名目录，但Docker数据一般放在存储卷上，例如/volume1/docker。我建议在这里创建项目目录，因为它的空间通常更大，且不受用户家目录影响。
3. 使用正确的命令行工具：较新版本的DSM（7.2+）和Container Manager已经支持docker compose命令（注意是空格，不是旧版的docker-compose）。如果你遇到命令未找到，可能需要通过套件中心安装“Docker”套件，它通常会包含。
4. 权限与路径：在SSH中执行docker命令通常需要sudo或root权限。你可以将当前用户加入docker组：sudo synogroup --add docker $USER，然后注销重登。另外，DSM的路径是Linux风格，使用正斜杠/。

一个完整的部署命令序列如下：

# 切换到Docker常用目录 cd /volume1/docker # 创建项目目录并进入 sudo mkdir -p openclaw && cd openclaw # 克隆仓库（需要安装git，可通过套件中心安装“Git Server”或使用ipkg/opkg） sudo git clone https://github.com/Luprintech/openclaw-docker.git . # 复制环境变量模板 sudo cp .env.example .env # 编辑环境变量，生成强令牌 sudo vi .env # 在vi中，按 `i` 进入编辑模式，找到 OPENCLAW_GATEWAY_TOKEN，将其值替换为 `openssl rand -hex 32` 生成的结果。按ESC，输入 `:wq` 保存退出。 # 修改文件夹权限（预防EACCES错误） sudo chown -R 1000:1000 . # 启动服务 sudo docker compose up -d

3.2 在树莓派（Raspberry Pi）上部署：打造边缘AI盒子

树莓派是学习、开发和轻量级应用的理想平台。确保你使用的是 Raspberry Pi OS（原Raspbian）64位版本，以获得更好的Docker兼容性。

关键步骤与避坑：

1. 安装Docker：官方的一键脚本curl -fsSL https://get.docker.com | sh在树莓派上工作良好。完成后，务必执行sudo usermod -aG docker pi（假设用户是pi）并注销后重新登录，这样你才能不用sudo运行docker命令。
2. 资源考量：树莓派4B 4GB内存是起步配置。如果你计划同时运行Ollama本地模型（如Llama 3.1 8B），内存可能会紧张。建议先从云API（如Gemini）开始，稳定后再尝试本地模型。
3. 部署流程：与Linux类似，在用户目录下操作即可。

   mkdir -p ~/docker/openclaw && cd ~/docker/openclaw git clone https://github.com/Luprintech/openclaw-docker.git . cp .env.example .env nano .env # 树莓派上nano编辑器更友好 # 编辑并保存后 docker compose up -d

4. 访问与端口：树莓派启动后，你可以在同一局域网的电脑上，通过浏览器访问http://树莓派IP:18789来管理网关。如果需要从外网访问，必须配置HTTPS反向代理，下文会详述。

3.3 在通用Linux服务器上部署：生产级稳定运行

在Ubuntu、Debian、CentOS等主流Linux发行版上部署是最标准的流程。除了安装Docker，还需要注意防火墙设置。

关键步骤与避坑：

1. 防火墙放行端口：如果你的服务器启用了UFW或firewalld，记得放行18789和18790端口。

   # 对于UFW (Ubuntu) sudo ufw allow 18789/tcp sudo ufw allow 18790/tcp sudo ufw reload

2. 使用非root用户运行：最佳实践是创建一个专用用户来管理Docker服务，而不是一直用root。可以参考树莓派部分的命令将用户加入docker组。
3. 系统服务化（可选）：如果你希望网关在服务器重启后自动启动，可以创建一个systemd服务单元文件。但使用Docker Compose的restart: unless-stopped策略，在大多数情况下已经足够了。

3.4 在Windows上部署：开发测试利器

在Windows上使用Docker Desktop部署，非常适合前期开发和测试。需要注意Windows和Linux在路径和命令行上的差异。

关键步骤与避坑：

1. 启用WSL2后端：安装Docker Desktop时，强烈建议使用WSL2（Windows Subsystem for Linux）作为后端，而不是传统的Hyper-V。WSL2的性能和兼容性要好得多，而且让你能在Windows上使用几乎原生的Linux命令行体验。
2. PowerShell是首选：虽然CMD也能用，但PowerShell功能更强大，且与新的Windows Terminal集成更好。本文所有Windows命令均以PowerShell为例。
3. 路径与权限：在PowerShell中操作，路径分隔符使用反斜杠\或正斜杠/均可。注意，你克隆代码的目录最好在用户目录下，避免Windows系统目录的权限问题。

   # 在PowerShell中 cd C:\Users\你的用户名 mkdir docker\openclaw -Force cd docker\openclaw git clone https://github.com/Luprintech/openclaw-docker.git . copy .env.example .env # 用记事本或其他编辑器编辑.env文件，设置令牌 notepad .env # 启动容器 docker compose up -d

4. Windows防火墙：首次运行时，Windows Defender防火墙可能会弹出警告，询问是否允许Docker访问网络。请选择允许，否则同一局域网内的其他设备将无法访问你的网关。

4. 初始配置与安全配对：从“进不去”到“用起来”

容器启动成功后，访问http://你的服务器IP:18789，你会遇到两个必经的“门槛”，这恰恰是OpenClaw安全设计的体现。

4.1 第一步：输入网关令牌

你会看到一个简单的认证页面，提示“gateway-token-missing”。这不是错误，而是让你输入之前设置在.env文件里的OPENCLAW_GATEWAY_TOKEN。复制粘贴进去，提交。这一步验证你是网关的合法所有者。

4.2 第二步：设备配对（核心安全机制）

提交令牌后，你很可能会看到一个“Pairing Required”的页面。这是最关键也最容易让人困惑的一步。OpenClaw采用了一种“一次一设备”的强认证模型。即使你有正确的网关令牌，每个新的浏览器（甚至同一个浏览器的无痕模式）都被视为一个新设备，需要管理员在后台手动批准一次。

为什么这么设计？想象一下，如果你的网关令牌意外泄露，没有这个二次确认，攻击者就可以直接接入。配对机制确保了即使令牌泄露，攻击者也无法从新的设备上直接登录，因为你会在后台看到陌生的配对请求。

如何完成配对？

1. 保持“Pairing Required”页面打开。
2. 打开终端，进入你的openclaw-docker项目目录。
3. 执行命令查看待处理的配对请求：

   docker compose exec openclaw-gateway node dist/index.js devices list

   你会看到一个表格，其中“Request”列下有一个UUID（类似a1b2c3d4-...）。
4. 批准这个请求：

   docker compose exec openclaw-gateway node dist/index.js devices approve <刚才看到的UUID>

5. 回到浏览器，刷新页面。现在你应该能看到OpenClaw的Web管理界面了。

实操心得：这个配对过程只需要每个浏览器做一次。批准后，该浏览器的信息会被加密保存在本地存储中。如果你清除了浏览器缓存或换了电脑，就需要重新配对。这是一个非常好的安全实践，请务必向你的共同使用者解释清楚这个流程。

5. 配置AI供应商与模型：连接智能大脑

进入管理界面后，你会发现还没有AI模型可用。我们需要运行内置的配置向导。不要尝试在Web UI里找添加API密钥的地方，目前主要配置需要通过命令行完成。

在项目目录下，运行：

docker compose exec openclaw-gateway node dist/index.js onboard

这是一个交互式命令行向导。它会引导你：

1. 选择AI供应商（如Google Gemini、OpenRouter、Anthropic等）。
2. 输入该供应商的API密钥。
3. 选择要启用的模型（例如，Gemini-1.5 Pro、Claude 3.5 Sonnet等）。
4. 向导会将配置写入容器的config目录，并映射到本地的./config文件夹。

完成后，刷新浏览器，你就能在OpenClaw的UI中看到可用的模型，并开始创建AI代理（Agent）或直接通过API调用了。

关于API密钥的注意事项：

• 免费资源：对于个人项目，可以优先考虑Google Gemini API和OpenRouter。Gemini提供免费的每日配额，足够轻度使用。OpenRouter则聚合了众多模型，并提供:free后缀的免费模型（通常有速率限制）。
• 本地模型：如果你有强大的显卡，可以部署Ollama，然后在OpenClaw中将其配置为一个“供应商”。这样你就可以免费使用Llama、Mistral等本地模型，数据完全不出局域网。
• 密钥安全：所有密钥通过向导加密后存储在./config目录下。请确保这个目录的备份安全。如果怀疑泄露，应立即在对应供应商的控制台重置密钥，并在OpenClaw中重新运行onboard向导更新。

6. 配置HTTPS与反向代理：实现安全外网访问

如果你只在内网使用，HTTP+设备配对已经提供了基本安全。但如果你想在外出时也能使用，或者想用一些更漂亮的WebUI客户端（如Open WebUI），HTTPS是必须的。原因有两个：1) 浏览器安全策略要求某些高级API（如Web Cryptography API）必须在安全上下文（HTTPS）中运行，否则OpenClaw的Web界面可能无法加载或功能不全。2) 在公网传输密码和API请求明文是极度危险的。

这里我强烈推荐使用Nginx Proxy Manager (NPM)，它把复杂的Nginx配置变成了网页上的简单表单操作。

6.1 准备工作：域名与动态DNS

你需要一个域名来申请SSL证书。有三种主流选择：

以最通用的DuckDNS为例：

1. 访问 duckdns.org ，用GitHub或Google账号登录。
2. 创建一个子域名，例如myai.duckdns.org。
3. 它会显示你当前的公网IP。由于家庭宽带IP经常变化，你需要在其提供的脚本中选一个（如Shell脚本），部署到你的服务器或路由器上，定时更新IP。很多开源路由器系统（如OpenWrt）或群晖NAS都内置了DuckDNS客户端。

6.2 部署Nginx Proxy Manager

同样使用Docker Compose部署NPM，这里提供一个简化的docker-compose.npm.yml示例：

version: '3.8' services: nginx-proxy-manager: image: 'jc21/nginx-proxy-manager:latest' container_name: npm restart: unless-stopped ports: - '80:80' # 不建议直接暴露，可能被DSM占用 - '81:81' # NPM管理界面 - '443:443' # HTTPS environment: DB_SQLITE_FILE: "/data/database.sqlite" volumes: - ./npm-data:/data - ./npm-letsencrypt:/etc/letsencrypt

运行docker compose -f docker-compose.npm.yml up -d启动。然后访问http://你的服务器IP:81进入管理界面，初始账号为admin@example.com，密码为changeme，登录后会强制修改。

6.3 配置端口转发与代理主机

这是最关键的一步，涉及路由器和服务器的网络配置。

1. 路由器端口转发：登录你家宽带路由器的管理后台（通常是192.168.1.1）。找到“端口转发”或“虚拟服务器”设置。添加两条规则，将外网的访问请求转发到运行NPM的服务器内网IP。

   • 规则1：外部端口443(HTTPS) -> 内部IP:443
   • （可选）规则2：外部端口80(HTTP) -> 内部IP:80（用于自动申请证书的HTTP验证）

2. 在NPM中添加代理主机：

   • 登录NPM管理界面(:81)。
   • 点击“Proxy Hosts” -> “Add Proxy Host”。
   • Details 标签页：
     • Domain Names: 填写你的域名，如myai.duckdns.org。
     • Scheme:http
     • Forward Hostname / IP: 填写你运行OpenClaw的服务器内网IP，例如192.168.1.100。
     • Forward Port:18789(OpenClaw网关端口)。
     • 务必勾选“Websocket Support”，否则OpenClaw的实时通信功能会失效。
     • 可以勾选“Block Common Exploits”增加安全性。
   • SSL 标签页：
     • SSL Certificate: 选择 “Request a new SSL Certificate”。
     • 勾选 “Force SSL” 和 “HTTP/2 Support”。
     • 输入你的邮箱（用于证书到期提醒）。
     • 勾选 “I agree to the Let's Encrypt Terms of Service”。
     • 点击“Save”。NPM会自动为你申请并配置免费的Let‘s Encrypt证书。

配置完成后，稍等片刻（证书申请可能需要一两分钟），你就可以通过https://myai.duckdns.org安全地访问你的OpenClaw网关了。此时，之前可能出现的“不安全连接”警告将消失，所有功能均可正常使用。

7. 高级应用：作为OpenAI兼容API网关使用

OpenClaw最强大的功能之一，就是它提供了一个OpenAI兼容的API端点。这意味着任何支持自定义OpenAI API Base URL的客户端，都可以直接对接你的OpenClaw网关，由网关来调度后端的各种AI模型。

7.1 API接入配置

在你的客户端应用中，需要进行如下配置：

7.2 推荐客户端与应用场景

1. Open WebUI / LobeChat: 这是功能最丰富的自托管ChatGPT式Web界面。在它的设置中，填入上述API信息，你就可以在一个漂亮的界面里，自由切换使用Gemini、Claude、Ollama等各种模型进行对话，历史记录完全私有。
2. Cursor / Windsurf / Bloop 等AI编程助手: 这些新一代的AI编程IDE通常允许你设置自定义的AI提供商。将Base URL指向你的OpenClaw，你就可以在写代码时，使用你喜欢的、或成本更低的模型来获得代码建议和补全。
3. 自动化脚本与工作流: 你可以用Python、Node.js等任何语言，像调用OpenAI官方API一样调用你的网关。例如，一个自动总结邮件的脚本，可以通过你的网关灵活选择使用免费的Gemini API，而另一个需要深度推理的任务，则可以指定使用Claude。

示例：使用curl测试API

curl https://myai.duckdns.org/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer 你的网关令牌" \ -d '{ "model": "gemini-1.5-pro", "messages": [{"role": "user", "content": "Hello, world!"}], "stream": false }'

8. 运维、更新与故障排查实录

8.1 日常更新与维护

手动更新：进入项目目录，执行两条命令即可。

docker compose pull # 拉取最新镜像 docker compose up -d # 重启容器，使用新镜像

你的config和workspace数据因为做了卷映射，会被完整保留。

自动更新：项目自带的Watchtower服务默认在每天凌晨4点检查更新。它只更新带有特定标签的容器，不会影响其他服务。如果你不希望自动更新，只需在docker-compose.yml中注释掉或删除整个watchtower服务定义块。

备份策略：最重要的就是./config和./workspace两个目录。你可以定期将它们打包压缩，备份到其他位置。一个简单的cron任务即可完成：

# 每周日凌晨2点备份 0 2 * * 0 tar -czf /path/to/backup/openclaw-backup-$(date +\%Y\%m\%d).tar.gz -C /path/to/openclaw-docker config workspace

8.2 常见问题与解决方案速查表

以下是我在长期使用中遇到的最典型问题及其解决方法：

8.3 性能监控与日志查看

• 查看实时日志：docker compose logs -f openclaw-gateway。-f参数可以持续跟踪输出，对于调试API调用问题非常有用。
• 查看容器状态：docker compose ps可以查看所有服务的运行状态。
• 资源占用：使用docker stats可以查看容器的CPU、内存实时占用情况。OpenClaw网关本身非常轻量，内存占用通常在100-200MB。主要资源消耗取决于你通过它调用的AI模型。

部署和运行OpenClaw Gateway的过程，本质上是在构建一个属于你自己的、可编程的AI基础设施层。它解耦了应用和具体的AI模型，给了你前所未有的灵活性和控制力。从在树莓派上搭建一个玩具，到在服务器上部署供团队使用的生产级服务，这个项目都能很好地胜任。遇到问题多查日志，善用社区，这个开源世界的乐趣就在于不断探索和解决问题。