项目标题是“手把手教你在腾讯云部署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 整体部署架构与请求路径我第一次部署时是边看文档边装结果系统装了又卸最后重来。第二次我先把架构画了一遍再动手就顺畅很多。整体链路是这样的手机/Windows客户端通过HTTPS或WebSocket连到腾讯云服务器的某个端口。OpenClaw核心服务端收到请求后判断这个指令是否需要调用Skill。如果需要就加载对应的Skill执行。涉及知识检索或长期记忆的核心服务端请求腾讯云VectorDB把用户问题向量化后做相似度检索。最终拼接上下文调用模型API通过TokenPlan或ccswitch等接入层转发拿到回复后返回给客户端。这个架构里最容易出错的是第2步和第4步的衔接Skill的输出格式不对模型接到的上下文就是乱的模型接入层的Token额度用尽服务端日志一堆报错但客户端只看到“无响应”。所以部署时要先把模型接入调通再挂Skill最后再接向量库。顺序错了排查成本翻倍。2. 腾讯云资源开通与基础环境准备2.1 服务器选型与规格测算OpenClaw本身不大但Docker镜像、模型缓存、logs目录都会占磁盘。我的测算基准是这样纯服务端两三个小型Skill2核4G内存足够系统盘40G起步。如果跑了较大的Skill比如网页解析、文档处理建议4核8G磁盘升到80G。带宽Companion传输的是文本和少量结构化数据3Mbps足够如果你计划接图片生成类的Skill5Mbps起步。系统镜像我推荐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 versionDocker装好后需要调整一个系统参数vm.max_map_count。OpenClaw如果内置了嵌入式索引或者向量缓存ES、Redis类的组件会要求这个值不低于262144。Ubuntu默认是65530不调的话容器启动一段时间后会出现内存映射异常sudo sysctl -w vm.max_map_count262144 echo vm.max_map_count262144 | 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会对非标准端口的明文流量做干扰或拦截。配置流程不复杂前提是域名已解析到服务器公网IPA记录 openclaw.你的域名.com - 服务器公网IP然后安装Nginx作反向代理把外部443端口转发到OpenClaw服务端口。证书部分我直接用腾讯云提供的免费证书配合Certum ACME客户端或社区常见的acme.sh做自动续期比手动上传过期证书靠谱得多。这里可以借助一些自动部署工具热搜里提到的ssldun就是干这个的把证书拉取、安装、续期这条链路自动化。我的建议是哪怕前期用临时端口测试也要在正式使用前把HTTPS配好因为Companion客户端的Token在明文HTTP下传输确实不安全。3. 核心配置解析模型接入、TokenPlan与VectorDB3.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、vector1536维浮点数组、text原始文本切片、metadataJSON存来源文档名、时间戳、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_USERroot 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://你的域名/wsToken填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内网或公网地址, usernameroot, key你的密码, ) db client.create_database(openclaw_memory) collection db.create_collection( nameconversation_memory, shard1, replicas2, descriptionOpenClaw长期记忆, embeddingsEmbeddingModel(), ) print(collection.collection_name)建好后再给OpenClaw配一下VECTORDB_URL重启容器docker compose restart openclawSkill这边我写了一个非常简单的“查服务器状态”Skill用来验证Skill系统是否工作。目录结构是skills/ └── server_status/ ├── manifest.yaml └── main.pymanifest.yaml的内容name: server_status description: 查询云服务器的CPU、内存和磁盘使用率 version: 1.0.0 entry: main.pymain.py的内容import psutil def run(params, context): cpu psutil.cpu_percent(interval1) mem psutil.virtual_memory().percent disk psutil.disk_usage(/).percent return { cpu: cpu, memory: mem, disk: disk, message: fCPU占用{cpu}%内存占用{mem}%磁盘占用{disk}%, }配置好后重启容器让Skill生效。在Windows Companion里对OpenClaw说“查询服务器状态”如果返回了真实数据说明从客户端到核心服务再到Skill的整条链路已经打通。这也是我最推荐新手做的第一个验证动作——它不依赖外部模型API出了问题能快速定位是Skill本身的问题还是链路的问题。4.4 守护进程与开机自启Docker Compose里已经设置了restart: unless-stopped理论上容器在机器重启后会自动拉起。但我在实际使用中发现如果服务依赖VectorDB等外部组件启动顺序不当仍然会闪退。这时候可以加一个top-level的depends_on声明或者直接用Systemd管理Composesudo tee /etc/systemd/system/openclaw.service /dev/null EOF [Unit] DescriptionOpenClaw Compose Requiresdocker.service Afterdocker.service [Service] Typeoneshot RemainAfterExityes WorkingDirectory/home/ubuntu/openclaw ExecStart/usr/local/bin/docker compose up -d ExecStop/usr/local/bin/docker compose down [Install] WantedBymulti-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通了但从手机或另一台电脑访问超时。排查顺序先看腾讯云安全组是否放通了对应端口。再看服务器防火墙sudo ufw statusUbuntu默认可能开着。最后看服务监听地址是不是0.0.0.0如果只监听127.0.0.1外网肯定连不进。经验安全组放通后一定要用nc -vz 服务器IP 端口从外部试别在服务器本机自测。本机自测成功不代表公网通。5.2 模型接入总是401或429401是密钥错误先看环境变量里有没有多余的空格。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 tokenplanNginx访问日志sudo tail -f /var/log/nginx/access.log大部分问题的规律是客户端有响应但内容不对问题在模型层客户端直接断连问题在网络层客户端一直转圈且请求没到Nginx问题在安全组或域名解析。我最后再分享一个经验部署OpenClaw这类项目最大的成本其实不在服务器而在理清“哪个组件负责什么”。很多人部署完卡住就是把模型接入、向量库、Skill三者的边界搞混了。你照着上面这套流程把每个环节的日志留好、逐步验证腾讯云上跑通OpenClaw只是时间问题。