腾讯云部署OpenClaw：从零到跑通第一个Skill

项目标题是“手把手教你在腾讯云部署OpenClaw”。这里先简单说一下背景：OpenClaw是最近挺热的一个开源智能体运行框架，核心价值是把大模型能力、技能扩展、多端连接整合在一个服务里。你可以在本地跑，但更实际的做法是放到一台云服务器上，让它7x24小时在线，手机、电脑随时能连。这篇就记录我在腾讯云上的完整部署过程，从买机器到跑通第一个Skill，包括中间踩过的坑和排查思路。适合有基本Linux和Docker经验的开发者，也适合想把自己的AI助手搬到云端长期运行的人。

我前前后后部署了三遍才把整套流程理顺。第一遍基本是按文档盲操作，第二遍处理各种环境问题，第三遍才把模型接入、向量库、域名的链路彻底跑通。下面这套步骤就是把三次经验压缩之后的可复现流程。

1. 先弄清楚OpenClaw到底部署的是什么，再动手

1.1 OpenClaw的核心组件拆解

部署OpenClaw之前，如果你以为它只是一个“把大模型API包装成聊天机器人”的脚本，那后面配置Skill和向量库的时候会很痛苦。我理解的OpenClaw由四部分组成：

• 核心服务端：负责接收指令、调度技能、管理会话状态。它本身不产生智能，智能来自背后接入的模型API。
• 模型接入层：统一管理多家模型供应商的API密钥、Token配额和路由规则。这里就涉及热搜里反复出现的TokenPlan、ccswitch接Codex——它们本质上都是模型接入层的组件，解决的是“多个模型密钥和额度怎么分配”的问题。
• Skill技能系统：OpenClaw的能力扩展点。每个Skill是一段可复用指令集或插件，比如联网搜索、读取网页、查数据库。部署时要把Skill目录挂载到正确位置，并配置启停规则。
• Companion端：包括Windows Companion桌面伴侣和安卓手机端。它不承载核心逻辑，只是与服务端保持长连接，把用户输入转发到云端，再把结果推回来。

理清这四个组件，你就明白腾讯云在这里扮演的角色：它提供一台长期开机的“宿主”，承载核心服务端和Skill运行环境；再提供一个可选的向量数据库，让OpenClaw具备长期记忆和知识检索能力。手机和电脑上的Companion只是遥控器。

1.2 为什么选腾讯云而不选本地电脑

很多人第一反应是“我有台旧笔记本，为什么不直接跑”。我试过，问题很具体：

• 家庭宽带的公网IP不固定，Companion要连回来就得配动态域名，折腾且不稳定。
• OpenClaw跑起来会持续占用内存和CPU，旧笔记本常年开机发热，风扇噪音和电费都是隐形成本。
• 一旦家里停电、路由器重启，服务就断了，你出差在外根本没法恢复。

腾讯云这边我选的是轻量应用服务器，因为OpenClaw这种场景不需要太高的计算规格，反而更看重稳定带宽和公网连通性。轻量服务器自带固定公网IP，安全组规则配置简单，价格也比同配置的云服务器CVM低不少。再加上它支持一键重装系统、快照回滚，部署翻车了能快速恢复，这点在反复调试时特别重要。

如果你已经有CVM实例，完全没问题，部署方式一致。核心诉求就一个：这台机器要能稳定出网访问模型API，同时能被你的手机、Windows客户端通过公网访问。

1.3 整体部署架构与请求路径

我第一次部署时是边看文档边装，结果系统装了又卸，最后重来。第二次我先把架构画了一遍，再动手就顺畅很多。整体链路是这样的：

1. 手机/Windows客户端通过HTTPS或WebSocket连到腾讯云服务器的某个端口。
2. OpenClaw核心服务端收到请求后，判断这个指令是否需要调用Skill。如果需要，就加载对应的Skill执行。
3. 涉及知识检索或长期记忆的，核心服务端请求腾讯云VectorDB，把用户问题向量化后做相似度检索。
4. 最终拼接上下文，调用模型API（通过TokenPlan或ccswitch等接入层转发），拿到回复后返回给客户端。

这个架构里最容易出错的是第2步和第4步的衔接：Skill的输出格式不对，模型接到的上下文就是乱的；模型接入层的Token额度用尽，服务端日志一堆报错但客户端只看到“无响应”。所以部署时要先把模型接入调通，再挂Skill，最后再接向量库。顺序错了，排查成本翻倍。

2. 腾讯云资源开通与基础环境准备

2.1 服务器选型与规格测算

OpenClaw本身不大，但Docker镜像、模型缓存、logs目录都会占磁盘。我的测算基准是这样：

• 纯服务端+两三个小型Skill：2核4G内存足够，系统盘40G起步。
• 如果跑了较大的Skill（比如网页解析、文档处理）：建议4核8G，磁盘升到80G。
• 带宽：Companion传输的是文本和少量结构化数据，3Mbps足够；如果你计划接图片生成类的Skill，5Mbps起步。

系统镜像我推荐Ubuntu 22.04 LTS。原因不是它“最新”，而是Docker和Systemd生态在Ubuntu上兼容性最好，网上能查到的踩坑案例也最多。CentOS系虽然也能跑，但维护节奏跟不上的话，依赖源容易出问题。

地域选择原则是“离你和你的主要访问端近”。如果你自己在国内使用，选腾讯云的北京、上海、广州地域都行；如果你需要让海外节点也能稳定连接，选香港地域会更合适。这个要根据你实际的使用场景决定，不是越近越好。

2.2 SSH密钥登录与安全组放通

我第一台服务器用的是密码登录，结果不到三天就有爆破尝试日志。后来老老实实改成密钥登录。在腾讯云控制台创建实例时可以选“密钥登录”，也可以创建完再绑定密钥。公钥会写入到实例的~/.ssh/authorized_keys，你只需要用私钥连接：

chmod 600 ~/.ssh/tencent_openhcaw.pem ssh -i ~/.ssh/tencent_openhcaw.pem ubuntu@你的服务器公网IP

这里有个细节：Ubuntu镜像默认用户是ubuntu，不是root。用ubuntu登录后需要提权再安装软件：

sudo apt update && sudo apt upgrade -y sudo apt install -y curl wget git tree

安全组放通建议少而精确。OpenClaw如果是纯API服务，只放通你将要使用的端口，比如8080或8443，来源IP先限制成你自己的公网IP，调通后再放宽。SSH端口（22）只允许你自己的IP访问，不要对全互联网开放。如果你需要从手机上管理服务器，可以考虑用腾讯云App的运维助手，而不是直接暴露SSH。

2.3 安装Docker并调整系统参数

OpenClaw官方README以及社区最常见的部署方式是用Docker Compose拉起一组容器，包括服务端、模型接入层代理、可选的向量库客户端。这样后续升级镜像、备份数据都方便。

安装Docker的常规操作：

curl -fsSL https://get.docker.com | sudo sh sudo usermod -aG docker $USER sudo systemctl enable docker sudo systemctl start docker

装完后一定要重新登录（exit再SSH进来），否则当前用户的docker组权限不会生效。然后验证：

docker version docker compose version

Docker装好后，需要调整一个系统参数：vm.max_map_count。OpenClaw如果内置了嵌入式索引或者向量缓存，ES、Redis类的组件会要求这个值不低于262144。Ubuntu默认是65530，不调的话容器启动一段时间后会出现内存映射异常：

sudo sysctl -w vm.max_map_count=262144 echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf

这个参数坑了我第二遍部署，容器反复OOM重启，日志里却是“max virtual memory areas vm.max_map_count 65530 is too low”，不看日志根本联想不到。

2.4 配置可选域名与HTTPS证书

OpenClaw的Companion客户端支持直连IP+端口，但如果你要用手机流量访问、或者想通过Web端管理服务，域名和HTTPS几乎是必须的。原因很简单：手机网络环境下，许多运营商或公共Wi-Fi会对非标准端口的明文流量做干扰或拦截。

配置流程不复杂，前提是域名已解析到服务器公网IP：

A记录 openclaw.你的域名.com -> 服务器公网IP

然后安装Nginx作反向代理，把外部443端口转发到OpenClaw服务端口。证书部分我直接用腾讯云提供的免费证书，配合Certum ACME客户端或社区常见的acme.sh做自动续期，比手动上传过期证书靠谱得多。

这里可以借助一些自动部署工具（热搜里提到的ssldun就是干这个的），把证书拉取、安装、续期这条链路自动化。我的建议是：哪怕前期用临时端口测试，也要在正式使用前把HTTPS配好，因为Companion客户端的Token在明文HTTP下传输确实不安全。

3. 核心配置解析：模型接入、TokenPlan与VectorDB

3.1 模型接入层为什么要单独拆出来

OpenClaw设计里有一个容易被新手忽略的点：它默认不绑定任何单一模型供应商，而是通过一套“接入层”配置来路由请求。你可以在同一个服务里，给日常聊天用常规模型，给编程类任务用Codex专用通道，再给成本敏感场景设置额度上限。这样做的好处是灵活，代价是配置项多、概念多。

热搜里反复出现的TokenPlan，我理解它的定位是一个“Token配额管理组件”——你可以给不同客户端、不同用户、不同Skill分配独立的Token额度，避免某个高频请求把整个月的预算烧光。ccswitch则是“模型通道切换器”，负责按照规则把请求路由到对应的模型服务，比如把代码生成类的请求转给Codex通道。

这两个组件在部署时通常以独立容器或进程方式运行，OpenClaw通过环境变量和配置文件中声明的接口地址来调用它们。所以你在看部署文档时，会看到类似TOKENPLAN_BASE_URL、CCSWITCH_ENDPOINT这样的环境变量。

3.2 关键环境变量与配置文件示例

我用的docker-compose.yml中，OpenClaw核心服务段的配置大致是这样：

services: openclaw: image: openclaw/openclaw:latest container_name: openclaw-core restart: unless-stopped ports: - "8080:8080" environment: OPENCLAW_HOST: 0.0.0.0 OPENCLAW_PORT: 8080 OPENCLAW_DATA_DIR: /data OPENCLAW_SKILL_DIR: /skills # 模型接入层 TOKENPLAN_BASE_URL: http://tokenplan:8400 TOKENPLAN_API_KEY: ${TOKENPLAN_API_KEY} CCSWITCH_ENDPOINT: http://ccswitch:8300 CCSWITCH_API_KEY: ${CCSWITCH_API_KEY} # 向量数据库 VECTORDB_URL: ${VECTORDB_URL} VECTORDB_USER: ${VECTORDB_USER} VECTORDB_PASSWORD: ${VECTORDB_PASSWORD} # 主模型默认路由 MODEL_PROVIDER: ccswitch MODEL_NAME: codex-mini volumes: - openclaw_data:/data - ./skills:/skills

注意几个关键点：

• OPENCLAW_DATA_DIR是OpenClaw的状态目录，会话记录、用户配置都放这里，必须持久化挂载。
• OPENCLAW_SKILL_DIR是Skill目录，热词里提到的“Skill不生效”问题，90%是目录挂载位置不对，或者Skill子目录名和配置里的ID不一致。
• 模型相关配置，我全部用环境变量而不是写死在配置文件里，因为改模型通道不需要重建容器。
• 不要在Compose文件里硬编码密钥，用${VAR}占位再加一个.env文件。

如果走HTTP方式接入模型API，需要把模型供应商提供的API密钥配到TokenPlan或ccswitch里。具体操作是编辑这两个组件的配置文件，添加provider列表，包括端点、密钥、默认模型、并发限制。以ccswitch为例，它的配置大致是：

providers: - name: codex base_url: https://你的模型网关地址/v1 api_key: sk-xxx models: - codex-mini - codex-large rate_limit: 50

这里的base_url是“你的模型网关地址”，不是某个固定厂商的地址。OpenClaw的优势正在于此：只要这个网关返回OpenAI兼容的/chat/completions格式，它就能接入。所以你可以接自己的私有化模型服务，也可以接云厂商的模型API，差异只在这一个base_url上。

3.3 腾讯云VectorDB的接入与使用位置

为什么OpenClaw需要一个向量数据库？因为会话记忆和知识库检索都依赖它。简单讲，大模型本身记不住你的历史对话，OpenClaw会把历史消息和知识文档切块，转成向量存起来；下次你再问相似问题时，它先去向量库里找出最相关的几段，再喂给模型生成回答。这就实现了“长期记忆”和“基于自有知识的问答”。

腾讯云VectorDB可以直接在控制台创建实例。创建时注意两点：

• 选择与服务器相同的地域，这样两者通信走内网，几乎没有延迟，也不占用公网带宽。
• 提前设计好Collection的字段结构。我自己用的结构是id（雪花ID）、vector（1536维浮点数组）、text（原始文本切片）、metadata（JSON，存来源文档名、时间戳、Skill标识），索引类型选HNSW，度量方式“余弦距离”。

数据库创建完成后，把连接信息配置到OpenClaw的环境变量里。如果服务端和VectorDB在同一VPC下，VECTORDB_URL直接填内网地址，不要用公网地址，同一个云账号下的内网互通既快又免费用量。

接入后验证是否正常，可以用OpenClaw自带的管理命令查询Collection列表。如果命令返回空或连接超时，优先检查安全组是否有放通对应端口，以及认证密钥是否粘贴了多余空格。

4. 完整实操：从空白服务器到OpenClaw跑通

4.1 一步步部署核心服务

前置目录准备：

mkdir -p ~/openclaw/{data,skills,logs} cd ~/openclaw touch docker-compose.yml

把上一节给的Compose内容写入docker-compose.yml，再写.env文件：

cat > .env << 'EOF' TOKENPLAN_API_KEY=你的TokenPlan密钥 CCSWITCH_API_KEY=你的ccswitch密钥 VECTORDB_URL=内网或公网地址 VECTORDB_USER=root VECTORDB_PASSWORD=你的密码 EOF

然后拉取镜像并启动：

docker compose up -d docker compose logs -f openclaw

第一次启动是信息量最大的时候。日志里能看到核心服务是否成功注册、模型接入层是否握手成功、Skill目录是否被扫描到。如果看到skill loaded: xxx这样的输出，说明Skill解析正常；如果看到skill skipped，多半是目录权限或manifest格式问题。

启动后，用健康检查接口确认服务状态：

curl http://127.0.0.1:8080/health

返回{"status":"ok"}就说明核心服务活着。注意这一步先不要开公网访问，先保证本机通，再考虑对外。

4.2 配置Windows Companion和安卓端连接

Windows端我踩过最大的坑是“Companion连上了服务端，但一发送消息就断开”。排查到最后，问题不是OpenClaw，而是Companion默认走WebSocket加密连接（wss://），而我只开了HTTP端口8080，导致握手失败。

解决办法：在Nginx里配置WebSocket代理：

location /ws { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; }

Windows端配置时，服务器地址填wss://你的域名/ws，Token填OpenClaw生成的客户端密钥，而不是模型API密钥。安卓端我用Termux安装是一次性通过的，关键在于Termux内不能直接用Docker，需要本机安装OpenClaw的轻量版客户端，通过同样的wss://地址连接云端服务。也就是说，安卓端只是遥控器，真正干活的服务在腾讯云上。

如果你也想在安卓上跑完整核心服务，要在Termux里装Python和依赖，性能受限且存储空间紧张，体验远不如云端部署。我的建议是：安卓端只装连远端的轻量方案，别折腾在手机上跑核心服务。

4.3 配置VectorDB并挂上第一个Skill

创建Collection的操作可以在腾讯云控制台做，也可以直接用SDK调API。我习惯用Python脚本一次性把表和测试数据建好：

from tcvectordb import VectorDBClient, CollectionModel, EmbeddingModel client = VectorDBClient( url="内网或公网地址", username="root", key="你的密码", ) db = client.create_database("openclaw_memory") collection = db.create_collection( name="conversation_memory", shard=1, replicas=2, description="OpenClaw长期记忆", embeddings=EmbeddingModel(), ) print(collection.collection_name)

建好后再给OpenClaw配一下VECTORDB_URL，重启容器：

docker compose restart openclaw

Skill这边，我写了一个非常简单的“查服务器状态”Skill，用来验证Skill系统是否工作。目录结构是：

skills/ └── server_status/ ├── manifest.yaml └── main.py

manifest.yaml的内容：

name: server_status description: 查询云服务器的CPU、内存和磁盘使用率 version: 1.0.0 entry: main.py

main.py的内容：

import psutil def run(params, context): cpu = psutil.cpu_percent(interval=1) mem = psutil.virtual_memory().percent disk = psutil.disk_usage('/').percent return { "cpu": cpu, "memory": mem, "disk": disk, "message": f"CPU占用{cpu}%，内存占用{mem}%，磁盘占用{disk}%", }

配置好后，重启容器让Skill生效。在Windows Companion里对OpenClaw说“查询服务器状态”，如果返回了真实数据，说明从客户端到核心服务再到Skill的整条链路已经打通。这也是我最推荐新手做的第一个验证动作——它不依赖外部模型API，出了问题能快速定位是Skill本身的问题还是链路的问题。

4.4 守护进程与开机自启

Docker Compose里已经设置了restart: unless-stopped，理论上容器在机器重启后会自动拉起。但我在实际使用中发现，如果服务依赖VectorDB等外部组件，启动顺序不当仍然会闪退。这时候可以加一个top-level的depends_on声明，或者直接用Systemd管理Compose：

sudo tee /etc/systemd/system/openclaw.service > /dev/null << 'EOF' [Unit] Description=OpenClaw Compose Requires=docker.service After=docker.service [Service] Type=oneshot RemainAfterExit=yes WorkingDirectory=/home/ubuntu/openclaw ExecStart=/usr/local/bin/docker compose up -d ExecStop=/usr/local/bin/docker compose down [Install] WantedBy=multi-user.target EOF sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw

后面再想管理服务，直接用systemctl status openclaw或journalctl -u openclaw -f，比docker ps信息更完整。

5. 常见问题与排查技巧实录

5.1 端口不通与公网访问失败

症状：本机curl通了，但从手机或另一台电脑访问超时。

排查顺序：

1. 先看腾讯云安全组是否放通了对应端口。
2. 再看服务器防火墙：sudo ufw status，Ubuntu默认可能开着。
3. 最后看服务监听地址是不是0.0.0.0，如果只监听127.0.0.1，外网肯定连不进。

经验：安全组放通后，一定要用nc -vz 服务器IP 端口从外部试，别在服务器本机自测。本机自测成功不代表公网通。

5.2 模型接入总是401或429

401是密钥错误，先看环境变量里有没有多余的空格。429是额度或并发限制，去TokenPlan的监控面板看是哪个key被打满了。我遇到过一个隐蔽问题：两个容器共用同一个api_key，一个高频轮询任务把共享额度耗尽了，导致正常对话全部429。解决办法是新建独立Key并把这个Key的配额单独拉高。

5.3 Skill不生效的两种典型情况

第一种是manifest文件格式错误。YAML对缩进非常敏感，一个Tab混进空格就会解析失败，OpenClaw启动时会跳过这个Skill但没有明显报错。建议写完后用命令验证：

python -c "import yaml; print(yaml.safe_load(open('skills/server_status/manifest.yaml')))"

第二种是Skill目录挂载到了容器里，但manifest里声明的entry文件名和实际文件大小写不一致。Linux容器是区分大小写的，Main.py和main.py是不同文件。我第二遍部署时就是这里翻车，花了半小时排查。

5.4 数据备份与版本升级建议

OpenClaw的data目录里存着会话和用户数据，升级前建议先做快照。腾讯云轻量服务器可以直接在控制台创建快照，免费额度够日常使用。升级镜像时执行：

docker compose pull openclaw docker compose up -d

如果新版本自动迁移了数据结构，旧容器停止时会把数据写到data目录，新容器启动后读取；如果是破坏性变更，建议先克隆一台测试机验证一遍再操作正式机。我自己升级前都会脚本打包data和skills目录到COS对象存储：

tar czf openclaw_backup_$(date +%F).tar.gz data skills .env

恢复时只需要解压覆盖再重启容器。复杂操作往往不需要重装系统，一次备份恢复就能解决。

5.5 日志排查的黄金组合

排查OpenClaw问题，不要只看核心服务日志。三段日志要配合：

• OpenClaw核心日志：docker compose logs -f openclaw
• 模型接入层日志：docker compose logs -f ccswitch tokenplan
• Nginx访问日志：sudo tail -f /var/log/nginx/access.log

大部分问题的规律是：客户端有响应但内容不对，问题在模型层；客户端直接断连，问题在网络层；客户端一直转圈且请求没到Nginx，问题在安全组或域名解析。

我最后再分享一个经验：部署OpenClaw这类项目，最大的成本其实不在服务器，而在理清“哪个组件负责什么”。很多人部署完卡住，就是把模型接入、向量库、Skill三者的边界搞混了。你照着上面这套流程，把每个环节的日志留好、逐步验证，腾讯云上跑通OpenClaw只是时间问题。