升级到 OpenClaw 模型管理 V2026.3.11 之后的第一个下午，我只做了一件事：用几条指令把同一个推理服务从本地模型切到 API 模型，再切回来，中间没有改配置文件，也没有重启任何进程。这个版本把“模型管理”从一件靠记忆和体力完成的杂活，变成了一套能写进脚本的标准流程。这篇文章会把我在 Ubuntu 上的安装部署过程、官方指令简版的常用命令、接入 Microsoft Teams 和 Obsidian 的配置，以及用阿里云免费试用服务器跑 OpenClaw 的实测记录完整拆开来讲，适合正在自托管 AI 服务、想用一套稳定方式管理多个模型的人参考。
1. V2026.3.11 的模型管理到底在管什么
1.1 自托管 AI 服务最容易失控的地方
如果你同时跑着本地大模型和几个在线的 API 模型，很快会发现，真正的麻烦不是模型本身，而是“管模型”这件事。
我最早用 OpenClaw 的时候，是靠环境变量加配置文件来切换模型的。今天要用本地模型处理一轮私有数据，就得把配置改成 A；明天要拿更大的在线模型写一篇长文，又要改回 B。改完还得重启服务，等接口就绪，再手工发一条请求验证。机器上跑了三个模型之后，我连当前对外提供服务的到底是哪一个都说不准，更别提还在别人机器上部署的实例了。
V2026.3.11 把模型管理收敛成了一个明确的模块。用官方文档的说法，就是“模型注册表 + 运行时切换”。你先把所有可用模型注册进去，然后通过指令指定当前生效模型，系统负责路由和切换，不需要再动配置文件，也不需要重启进程。对我这种记性一般、又必须保证服务在线的人来说，这等于把“改配置—重启—验证”的流程压缩成了三条命令。
1.2 “官方指令简版”到底简了什么
标题里的“官方指令简版”值得解释一下。OpenClaw 本身有一个完整的管理面，包括 Web 控制台、REST API 和完整的命令行工具。官方针对日常运维，单独整理了一套精简指令集，只保留高频操作：模型注册、切换、删除、测试、状态检查。这套指令的好处是参数收敛，每个指令只有两三个可选参数，适合写进脚本，也适合照着文档复现。
我第一次用的时候，最深的感受是命令名足够直觉。要列出模型就是list，要切换就是set，要验证能不能用就是test。不需要翻几十页文档，记住这几个动词，配合模型名就能操作。简版指令本质上是把底层 API 的多步调用合并成了单步指令，比如set一条指令背后至少包含更新路由表、刷新健康检查缓存、发送切换信号三件事。
我在下面章节里用到的指令都来自这套简版。如果你手里的版本号不同，个别参数可能有差异，但整体思路是通用的。抛开版本差异，这版的变化可以总结成一张对照表：
| 操作 | 旧做法 | V2026.3.11 做法 |
|---|---|---|
| 切换模型 | 改配置文件 + 重启服务 | openclaw model set 模型名 |
| 新增模型 | 手工编辑路由表 | openclaw model add |
| 验证可用性 | 发一条请求看返回 | openclaw model test |
| 排查异常 | 逐行翻日志 | openclaw model status看健康历史 |
1.3 版本号 V2026.3.11 背后的发布节奏
这个版本号是年月日格式，代表 2026 年 3 月 11 日发布的版本。项目采用日期版本号，意味着发布节奏比较快、迭代频繁。好处是你永远知道当前版本是什么时候的，坏处是升级后配置兼容性需要额外留意。
我在升级策略上吃过亏，后来养成了两个习惯：升级之前先把当前版本的配置目录完整备份一份，升级完立刻跑一遍模型状态检查。V2026.3.11 相比上个版本最实质的变化，是模型注册表的存储格式从单文件改成了目录结构，并且增加了模型健康检查的历史记录。这个变化对日常使用影响不大，但对老配置文件迁移有要求。如果你是从更早版本升上来的，建议先跑迁移工具，而不是直接拿旧配置覆盖新版本。
这版还顺手解决了一个老问题：当活跃模型连续失败时，可以配置自动回退到备用模型。以前要实现类似效果，得自己写守护脚本轮询接口状态。现在注册表里每个模型有一个priority字段，数字越小优先级越高，连不上主模型时自动切到下一个。这一点在接入 Teams 的场景里尤其有用，后面会细说。
2. Ubuntu 环境准备：从裸机到跑通第一条模型指令
2.1 先算账再动手：显存、内存和硬盘
装 OpenClaw 之前，我建议先花十分钟算一笔资源账，而不是直接抄网上配置。账户怎么算？模型权重占用的显存，粗略公式是“参数量 × 每权重比特数 ÷ 8”。一个 7B 模型用 4 bit 量化，权重约 3.5 GB，加上 KV Cache 和推理开销，实际建议给 8 GB 以上显存；13B 用 4 bit 约 6.5 GB，建议 12 GB 以上；70B 用 4 bit 约 35 GB，基本就要上 40 GB 的单卡，或者拆到多卡跑。
如果你想在纯 CPU 机器上跑，权重放在内存里，速度会差很多，但 1B 到 3B 的小模型做普通问答、摘要，日常用是能接受的。我有一个 2 核 4 GB 的旧笔记本，跑 3B 模型生成一段 200 字的回复大概要 20 到 30 秒，虽然慢，但胜在随时可用、不占显存。
硬盘方面同样要提前规划。7B 的 GGUF 文件约 4 到 5 GB，70B 的量化文件要到 35 GB 以上，再加上日志、向量库、临时文件，我给部署机准备的参考值是：最低 50 GB，推荐 100 GB 起。如果你的系统盘只有 20 GB，别硬装，把模型目录用软链接指到数据盘，这是最省事的办法。
2.2 依赖安装的顺序和理由
依赖安装的顺序很重要，我踩过一次坑之后就把顺序固定成了下面这样：
- 先更新系统：
sudo apt update && sudo apt upgrade -y - 再装显卡驱动：Ubuntu 22.04 下用
sudo apt install nvidia-driver-550，装完必须重启，nvidia-smi能看到显卡才算过 - 如果打算用 Docker 方式跑，再装 Docker 和 NVIDIA Container Toolkit
- 然后装 Python 3.11 环境，用 venv 隔离
- 最后装 git 和 git-lfs，用来拉模型文件
为什么是这个顺序？因为 OpenClaw 部署完第一步就是自检，doctor指令会检查 GPU 是否可见。如果你先把 Docker 装好了再装驱动，Docker 守护进程和容器运行时是看不到新驱动的，必须把 Docker 服务重启一遍才能识别显卡。而 Python 环境晚点装没关系，部署脚本自己会处理，但把系统依赖先配好，脚本跑起来会顺很多。
2.3 本地一键部署脚本实际跑起来是什么样
官方文档里说的“本地一键部署”，实际执行起来大致是这几步。先拉代码，再跑安装脚本，然后初始化，最后自检：
git clone https://github.com/openclaw/openclaw.git cd openclaw ./install.sh openclaw init openclaw doctorinstall.sh会做三件事：检测硬件环境（有没有 GPU、显存多大）、创建 Python 虚拟环境、把基础配置模板写进用户目录。整个过程在干净机器上大概 5 到 10 分钟，大部分时间花在下载依赖包上。openclaw init会问你几个初始化问题，比如实例名、监听端口、是否开启健康检查，这些默认值都够用，我基本一路回车。
如果要下载本地模型，可以走官方源，也可以直接从 Hugging Face 拉文件：
openclaw model pull qwen2.5-7b-instruct-q4_k_m # 或者 git lfs install git clone https://huggingface.co/Qwen/Qwen2.5-7B-Instruct-GGUF我个人更推荐官方model pull，它会顺带校验文件完整性并写进注册表，省得后面手工注册时还要核对路径。
2.4 装完之后先别急着接模型
部署完成后的第一件事，不是急着加模型，而是把环境跑一遍自检。openclaw doctor会检查 GPU 可见性、监听端口占用、磁盘剩余空间、配置目录权限这几项。我反复遇到过的问题有两个：一是doctor报告 GPU 不可见，基本是驱动装完没重启或者 Docker 运行时没装 NVIDIA Container Toolkit；二是监听端口被其他服务占用，OpenClaw 默认监听 8443，很多机器上已经被别的管理面板占了，改配置里的server.port就能解决。
自检通过后再看一眼模型列表，应该是空的或者只有一个示例模型：
openclaw model list这时候整个环境才算真正可用。接下来就是模型管理指令的核心操作了。
3. 模型管理指令实操：注册、切换、回退、健康检查一条龙
3.1 先懂注册表，再懂指令
指令只是表面，真正起作用的是模型注册表。V2026.3.11 的注册表是 YAML 格式的配置文件，默认位置在配置目录下的models.yaml。一个典型的配置长这样：
models: - name: local-7b kind: local path: ./models/qwen2.5-7b-instruct-q4_k_m.gguf context_window: 8192 max_tokens: 2048 priority: 1 - name: api-gpt kind: api endpoint: https://api.example.com/v1/chat/completions api_key_ref: env:OPENAI_API_KEY model_name: gpt-4o-mini timeout: 120 priority: 2注意看api_key_ref这个字段，它引用的是环境变量名而不是明文密钥。我强烈建议你照着这个习惯来，因为把 API 密钥直接写进 YAML，意味着任何能读到配置文件的人都能拿走你的密钥，而且版本管理工具一提交就泄露出去了。用环境变量引用，密钥和配置分离，换机器部署也更安全。
priority字段决定故障转移顺序，数字越小优先级越高。上面这个配置里，主模型是local-7b，回退模型是api-gpt。一旦本地模型连续健康检查失败，请求会自动转到 API 模型，整个过程对调用方透明。
3.2 注册一个本地模型和一个 API 模型
配置写好了，接下来用指令把它们注册进去。注册命令的参数和配置字段是一一对应的：
openclaw model add --name local-7b \ --kind local \ --path ./models/qwen2.5-7b-instruct-q4_k_m.gguf \ --context-window 8192 \ --priority 1 openclaw model add --name api-gpt \ --kind api \ --endpoint https://api.example.com/v1/chat/completions \ --model-name gpt-4o-mini \ --api-key-ref env:OPENAI_API_KEY \ --timeout 120 \ --priority 2注册完先列一下确认都在：
openclaw model list输出会包含三列：模型名、类型（local/api）、健康状态（unknown/healthy/unhealthy）。注意，刚注册的模型健康状态是unknown，需要跑一次test才会更新。这一步很关键，别跳过，否则后面切换时可能因为健康检查缓存还是空白的而出现意外。
openclaw model test --name local-7b openclaw model test --name api-gpttest会真的往模型发一条极短的请求，比如让模型回复“ok”，并记录响应时间和是否成功。我习惯把两个模型的test结果都留档，尤其是 API 模型，因为在线模型时好时坏，网络抖动、服务商限流都会造成影响。
3.3 切换、回退和自动故障转移
注册和测试做完，切换就是一条指令的事：
openclaw model set --name local-7b openclaw model statusset背后做的是原子更新路由表：正在跑的请求继续在旧模型上跑完，新请求全部落到新模型。不需要重启，不需要优雅停机，这是我在生产环境里最看重的一点。model status会告诉你当前活跃模型是哪个、备用模型有哪些、最近一次健康检查结果是什么时间。
关于回退，我一开始以为自动故障转移是玄学，直到真的复现过一次。我把本地模型的路径改坏，然后故意不跑test，直接发请求，系统的表现是：前三次请求返回模型加载失败，随后自动把流量切到api-gpt，健康检查日志里记录了一条failover triggered的事件。如果你不希望自己的服务出现这三次失败，可以把健康检查的fail_threshold调成 1，但代价是网络抖动时更容易误触发切换。我通常保持默认的 3，毕竟误切比等待稍久更麻烦。
3.4 几个容易被忽略的调优参数
模型管理不是只管“哪个模型在服务”，参数调优同样重要。下面这几个参数是我在反复测试后确定的常用值，你可以作为起点按需调整：
| 参数 | 推荐值 | 说明 |
|---|---|---|
context_window | 8192 | 上下文窗口越大，显存占用越高，不是越大越好 |
max_tokens | 2048 | 单次回复的最大长度，摘要类任务 1024 足够 |
temperature | 0.7 | 默认值，写作用 0.9，抽取类任务建议降到 0.2 |
request_timeout | 120 | 本地模型推理慢，Timeout 太短会误报失败 |
concurrency | 4 | 过高的并发会让显存瞬间打满，小机器建议 2 |
其中最容易出问题的是request_timeout。本地模型在 CPU 机上跑大 prompt 时，生成几百字可能要一两分钟，如果 timeout 还停留在默认的 30 秒，健康检查就会把模型误判为 unhealthy，然后触发回退。看起来是“模型不稳定”，实际是超时设置不匹配，这类问题我前后排查了快半小时才定位到。
4. 把 OpenClaw 接到 Microsoft Teams 和 Obsidian 里
4.1 Teams 接入：从创建 Bot 到收到第一条回复
OpenClaw 接入 Microsoft Teams 的流程，本质上是把一个 Bot 应用注册到 Teams，然后把消息活动转发给 OpenClaw 的对外接口处理。具体步骤如下：
第一步，在 Azure 门户里创建一个 Bot 应用，拿到 Application ID 和 Client Secret。如果没有现成的 Azure 订阅，Teams 管理后台的“应用”入口也能创建自定义应用，两种方式拿到的凭据格式是相同的。
第二步，把凭据写进 OpenClaw 的配置，而不是直接放在命令行里。我在配置里加了一段：
teams: app_id: "你的AppID" app_secret_env: env:TEAMS_APP_SECRET public_url: "https://你的域名:8443/api/teams" allowed_channels: ["ai-ops"] trigger: "@OpenClaw" default_model: local-7b第三步，把对外端口开放到公网。Teams 的 Bot Framework 需要把消息投递到一个公网 HTTPS 地址，所以你必须有一个能被 Teams 访问到的端点。我在阿里云服务器上用的是云平台的安全组规则放行 8443 端口，再配上域名证书，让 Teams 能通过https://你的域名:8443/api/teams触达实例。注意，这一步不能用私有地址，否则 Teams 永远找不到你的 Bot。
第四步，启动服务和消息入口，在团队频道里创建一个叫ai-ops的频道，把 Bot 加进去，发一条@OpenClaw 测试。正常情况下，几秒后就能收到 Bot 的自动回复。
4.2 一个真实的团队协作场景
接入 Teams 之后，我实际用得最多的场景是周报辅助。每周五，我在团队频道里@OpenClaw，让它把这一个星期讨论串里的行动项整理成清单，然后按负责人分类。这里有个模型选择的问题：讨论串里经常混着内部项目细节，我倾向于用local-7b来处理，内容不出服务器；只有在需要更高质量归纳、且内容不敏感时，才手动切到api-gpt。
所以你会发现，模型管理和 Teams 是深度耦合的。我在配置里把default_model设成local-7b，目的就是默认让所有频道请求走本地模型，避免内部讨论内容被发送到外部 API。哪个频道用什么模型，也可以通过allowed_channels和频道级别的覆盖配置来做，这个粒度控制比我想象的周到。
4.3 Obsidian 集成：让模型真正能读你的笔记
Obsidian 是另一个我重度使用的工具，OpenClaw 和它搭配起来的效果，是让模型能检索并引用你自己的笔记内容。前提是笔记仓库里启用 Local REST API 插件，它会暴露一个本地 HTTP 接口，默认端口 27124，并在设置里生成一个 API Key。
OpenClaw 侧只需要配置仓库路径和接口信息：
obsidian: vault_path: /data/vault rest_api: "http://127.0.0.1:27124" api_key_env: env:OBSIDIAN_API_KEY scope_paths: - "Notes/私有笔记" - "Projects/进行中"这里有个明显的好处：笔记文件通常是很私密的，如果配置成走 API 模型，等于把笔记内容发给第三方服务。所以我这边的策略是，scope_paths内的所有检索请求默认路由到local-7b，只有像“查公开资料、整理论文摘要”这类不涉及私密笔记的任务，才允许走外部模型。这个路由规则写在一个简单的过滤器里，按请求内容的路径前缀做判断。
4.4 接入时的安全边界
和办公工具打通之后，安全边界比纯本地使用要紧得多。我自己总结了三条底线：第一，任何 API Key 都不写入明文的 YAML 或命令历史，全部走环境变量或密钥管理服务；第二，allowed_channels、scope_paths这类白名单必须主动维护，新增频道或笔记目录时先确认是否需要开放；第三，如果混合使用本地模型和 API 模型，要在文档里明确标注哪些数据允许出站，让团队所有人心里有数。
另外，Teams 交互对响应时间有要求。如果你用的模型推理很慢，Teams 端可能几秒后就不等回复了，表现出“Bot 没反应”。这时候别急着怀疑配置，先看推理耗时，再决定是换更快的模型，还是改成先快速返回一条“正在处理”的消息、稍后再同步结果。我在下一章的踩坑记录里会再提这个。
5. 阿里云免费试用服务器部署：能跑，但要想清楚定位
5.1 为什么我选免费试用而不是自家机器
我决定在阿里云免费试用服务器上部署 OpenClaw，有三个具体原因：家里的机器没法保证 24 小时在线，公司网络对公网端口限制又多；想给同事演示 Teams 接入，必须要一个公网 HTTPS 端点；还有一个很现实的原因，免费试用能让我在不花一分钱的情况下，把整个部署流程再从头跑一遍，验证文档里的步骤是否真的可靠。
如果你也有这三条里的任何一条，那么云上部署就是当前最合理的起点。但要提前说清楚，免费试用实例的规格通常很小，常见配置是 2 核 4 GB，没有 GPU。这意味着它不适合跑 13B 以上的本地模型，也不适合并发要求高的生产负载。它的定位是验证、演示和小流量实验，而不是生产环境。
5.2 创建实例和基础配置
申请免费试用实例的时候，我建议把系统选成 Ubuntu 22.04 LTS，这是社区里踩坑最少的版本。创建实例时有几个容易被忽略的细节：
- 安全组规则：至少放行 22（SSH）、8443（OpenClaw 管理端）和 443（HTTPS 对接 Teams）。如果只放行 22，你会发现部署完了但服务从外面访问不到。
- 公网 IP：免费试用通常分配一个固定的公网 IP，这个 IP 记得保存好，之后配置 Teams 公网地址和域名解析都要用到。
- 数据盘：如果实例附带数据盘，先挂载并格式化，把模型目录放到数据盘上，避免系统盘写满后实例直接不可用。
登录实例后，安装流程和第二章里一样，唯一区别是不需要装显卡驱动。CPU 模式下，OpenClaw 会自动检测不到 CUDA 并走 CPU 推理路径，install.sh会拉对应依赖。
5.3 在云上跑 OpenClaw 的两种模式
免费试用实例上，我实际验证了两种运行模式，各有各的适用场景：
| 模式 | 配置 | 表现 | 适合场景 |
|---|---|---|---|
| API 模型模式 | 注册一个在线 API 模型，不加载任何本地模型 | 响应快、稳定，CPU 占用极低 | 对外服务、Teams 演示、多团队协作 |
| CPU 本地模型模式 | 加载 3B 或 7B 量化模型到内存 | 生成速度大约 3 到 8 token/秒 | 验证本地模型链路、处理私密但不紧急的任务 |
我在实际测试中，2 核 4 GB 的实例跑 7B 量化模型，生成速度在 3 token/秒左右，回答一段 200 字的问题要等一分钟以上，体验只能说“能用但不快”。如果只是演示 Teams 接入，强烈建议直接使用 API 模型模式，把体验做顺，再慢慢研究本地模型。
5.4 免费试用的坑和到期迁移
免费试用最需要留心的是到期。到期后实例会被关机或释放，数据不会自动备份。我的处理习惯是：每周末把配置目录打一个包，模型文件因为体积大，只在本地留底，云端只存配置和小体积的向量库。
迁移流程其实不复杂，新机器装好之后，把备份的配置目录解压回去，再跑一遍openclaw doctor确认环境一致，最后openclaw model list看模型注册是否完整。我试过一次从到期实例迁到另一台机器，整个过程不超过二十分钟。关键是把配置当成资产来管理，别把它当成装完就忘的东西。
6. 实测过程中踩过的坑与排查思路
6.1 模型切换报 “model not found” 的完整排查
这个报错我遇到过好几次，每次都以为是版本 bug，最后发现基本是配置或权限问题。完整的排查链路是这样的：
- 先跑
openclaw model list，看目标模型名是否真的存在。有时候是记忆偏差，新版注册表里模型名多了一个后缀。 - 如果列表里有，检查当前运行用户是否有注册表目录的读取权限。我遇到过
model add是在 root 下执行的，而服务进程却以普通用户运行，结果服务端读不到注册表，直接报 not found。 - 用
openclaw doctor查看配置路径，确认服务实际加载的是不是你编辑的那份配置。同一台机器上可能存在多个配置副本，改错文件的情况不少见。 - 最后才考虑清理缓存：
openclaw model cache --clear，然后重新model test。
按这个顺序排查，绝大多数情况都能在十分钟内定位，别一上来就怀疑软件有问题。
6.2 本地模型加载到一半内存爆了
这是我第一次跑 13B 模型时经历的事故。机器有 16 GB 内存，我以为够用，结果模型加载到一半，整个进程被系统 OOM Killer 杀掉，连带着局域网里的其他服务都跟着闪断。后来查日志发现，13B 模型用 4 bit 量化，权重文件约 6.5 GB，但加载时还要建 KV Cache、临时缓冲区、推理工作区，峰值内存轻松超过 10 GB，再叠加系统本身占用，16 GB 根本不够。
解决办法是降级到 7B 模型，同时把context_window从 8192 降到 4096，concurrency从默认值降到 2。另外，启用内存映射（mmap）加载模型权重，也能显著降低内存压力，代价是启动变慢，但换来的是更低的常驻内存占用。如果你的内存只有 8 GB，我建议别碰 7B 以上的模型，老老实实用 3B 或更小。
6.3 Teams 收不到机器人回复
Teams 接入完成后的第一晚，我发了一条测试消息，结果 Bot 毫无反应。排查下来有三个层面：
首先是确认消息有没有到达 OpenClaw。看服务日志里有没有 Teams 消息活动的记录，如果没有，大概率是公网地址配置不对，或者安全组没放行对应端口。其次是看回复有没有发出去。Teams 对消息交互有时限要求，如果模型推理超过十几秒还没返回结果，Teams 端就会视作超时，表现为“Bot 没回复”。这一点在生产上非常致命，解决办法是让 OpenClaw 先立刻返回一条“我收到了，正在处理”的中间消息，等推理完成后再把结果同步回来。最后还要检查allowed_channels，如果频道不在白名单里，消息同样会被静默丢弃。
6.4 升级版本后配置不兼容怎么办
从旧版本升到 V2026.3.11 时，我第一次直接覆盖配置，结果模型注册表没被正确识别。后来才确认，新版把注册表从单文件改成了目录结构，迁移工具需要手动执行，而且会生成一份迁移前的备份。
现在我的升级流程固定为：先备份配置目录，再执行迁移，然后立刻跑model list和model test，最后看一眼健康检查日志。如果发现异常，直接回滚到上一个版本，把备份恢复回去就行。回滚这件事看起来很简单，但没有备份的前提下做回滚，往往比升级本身更折腾。这里再强调一次，生产环境里，版本固定比追求新功能重要得多，升级不是越多越好，而是越稳越好。
我个人的最后一个习惯，是把每台部署机的模型配置和切换记录写在一个简单的笔记文件里，哪个实例跑哪个模型、什么时候切过、因为什么原因切，都记一行。模型多了之后，这套“模型日记”比任何命令都可靠。希望这篇从安装到 Teams、Obsidian、云上部署再到踩坑排错的完整记录，能让你在管理多模型的路上少绕几个弯。
