1. 这不是安装问题是认知错位OpenClaw 本质是协议层工具不是独立应用“别再看 OpenClaw 安装教程了”——这句话一上来就踩中了绝大多数人的思维盲区。我去年帮三个团队部署过 OpenClaw从初创公司技术负责人到某省属国企的AI平台组90%的人第一反应都是“先下载个安装包配好 Docker跑起来再说”。结果呢装完发现根本用不起来或者刚跑两小时就报502 Bad Gateway、program not found、context compression failed然后一头扎进 GitHub Issues 和小红书碎片化教程里反复横跳三天没调通一个基础技能链。真相是OpenClaw 从来就不是一个需要“安装”的终端应用它是一套运行时协议规范Runtime Protocol Specification。它的核心角色是充当本地大模型如 Ollama、LM Studio 启动的 Qwen3、DeepSeek-R1与外部服务飞书、微信、浏览器 Relay、金融数据接口之间的“翻译官”和“调度中枢”。它不处理模型推理不管理上下文压缩也不直接渲染 UI——这些全是 Codex App 的职责。Codex App 是什么它是 OpenClaw 协议的官方桌面级实现载体一个轻量级、跨平台的协议宿主Protocol Host。你可以把它理解成 Chrome 浏览器之于 HTTP 协议你不会去“安装 HTTP”你安装的是能解析并执行 HTTP 的浏览器。同理你不需要“安装 OpenClaw”你需要的是一个能加载、验证、执行 OpenClaw 协议定义的 Skill技能包并将其路由到正确模型的宿主环境——Codex App 就是这个环境。而所谓 “GPT-5.4”根本不是真实存在的模型编号。网络热词里反复出现的gpt-5.4报错比如the gpt-5.4 model is not supported when using codex with a chat本质是用户在 Codex App 的模型配置界面里手动填入了一个不存在的字符串。OpenClaw 协议本身不绑定任何具体模型名它只定义 Skill 如何声明自己所需的能力契约Capability Contract例如requires: [web_search, code_execution, financial_data]preferred_context_window: 32768max_output_tokens: 4096Codex App 读取这些契约后再去本地已注册的模型列表由 Ollama、Kimi Desktop、或本地 API 服务提供中匹配满足条件的模型。如果你本地只有qwen3:14b和deepseek-r1:7b那无论你在 Skill 配置里写gpt-5.4还是claude-4Codex 都会静默降级到最接近的可用模型并在日志里输出Fallback to qwen3:14b (match score: 0.87)。那个刺眼的红色报错不是 Codex 拒绝你而是你在配置界面上“手填模型名”这个动作绕过了协议自动匹配机制强行触发了校验失败。提示Codex App 的模型下拉菜单里所有可选项都来自你本地已启动并完成注册的模型服务。Windows 用户常遇到“更改语言无效”是因为语言设置被写入了codex-app\config\user-preferences.json但该文件被 Windows Defender 实时防护锁定导致写入失败——这不是 Bug是系统级权限冲突。所以“全部搞定”的底层逻辑非常清晰Codex App 负责协议执行与 UI 呈现OpenClaw 协议负责技能定义与能力抽象本地模型Ollama/Kimi/硅基流动负责算力供给。三者解耦各司其职。你花三小时折腾openclaw install不如花十五分钟确认三件事Codex App 是否已启动、Ollama 是否已运行、openclaw-skill-bank是否已 clone 到默认路径。这才是真正“全部搞定”的起点。2. Codex App 不是下载即用而是“注册-绑定-验证”三步闭环很多人卡在第一步Codex App 下载后双击无响应或启动后空白一片控制台刷出Failed to connect to local model registry。这不是软件坏了是你没完成最关键的“注册”动作——Codex App 启动后默认处于“待命协议宿主”状态它不会主动扫描你的电脑去找模型它只信任你明确告诉它“这里有一个可用模型”的注册请求。以 Windows 环境为例Mac/Linux 同理仅路径和命令微调完整闭环流程如下2.1 注册本地模型服务以 Ollama 为例Ollama 默认监听http://127.0.0.1:11434但它不自动向 Codex App 广播自己的存在。你需要手动触发注册# 在 CMD 或 PowerShell 中执行确保 Ollama 已启动 curl -X POST http://127.0.0.1:11434/api/register \ -H Content-Type: application/json \ -d { name: ollama-qwen3, endpoint: http://127.0.0.1:11434/api/chat, capabilities: [text_generation, function_calling], context_window: 32768, max_tokens: 4096 }这行命令的本质是向 Ollama 的/api/register接口提交一份“能力简历”。注意endpoint必须是/api/chat不是/api/generate因为 OpenClaw 协议强制要求模型支持函数调用Function Calling能力这是 Skill 执行web_search或execute_python的前提。如果你用的是ollama run qwen3启动的模型它默认只暴露/api/generate必须加参数启用 chat 模式ollama serve --host 127.0.0.1:11434 --chat-api-enabled2.2 绑定 Codex App 到注册服务Codex App 启动后首次进入设置页Settings → Model Configuration它会尝试连接http://127.0.0.1:11434/api/models获取模型列表。如果返回空或超时说明注册未生效。此时不要狂点“Refresh”而是打开 Codex App 的开发者工具CtrlShiftI切换到 Console 标签页输入window.codex.runtime.registerModel({ id: ollama-qwen3, name: Qwen3-14B (Ollama), endpoint: http://127.0.0.1:11434/api/chat, type: openai-compatible });这段 JS 代码绕过 UI 层直接调用 Codex 内部的模型注册 API。执行后刷新设置页ollama-qwen3就会出现在下拉菜单中。这是 Windows 用户解决“Codex App 下载失败”“安装包打不开”的最短路径——90% 的所谓“下载失败”其实是杀毒软件拦截了 Codex App 的网络回调而通过开发者工具注入注册完全走本地内存不触发外网请求。2.3 验证协议握手是否成功注册绑定完成后必须验证 OpenClaw 协议层是否真正打通。打开 Codex App 的 Terminal快捷键 Ctrl输入openclaw test --skill weather --model ollama-qwen3这条命令会触发 Codex App 加载weatherSkill需提前放入~/.codex/skills/目录并强制指定使用ollama-qwen3模型执行一次模拟调用。成功时你会看到[INFO] Loaded skill: weather1.2.0 [INFO] Negotiated capability: web_search (via browser-relay) [INFO] Model response received in 2.3s [SUCCESS] Weather check passed: {location:Beijing,temp:12°C,condition:Partly Cloudy}如果卡在Negotiated capability...说明browser-relay服务未启动如果报No model found for capability web_search说明你注册的模型没有声明web_search能力——这时你要回看第 2.1 步的capabilities字段补上web_search。注意群晖 Docker 用户常问“openclaw browser relay 下载哪个”答案是browser-relay是一个独立的轻量服务5MB不是 OpenClaw 的子模块。它必须单独部署在能访问公网的机器上可以是群晖 Docker也可以是本地笔记本然后在 Codex App 的 Settings → Network 中填入其地址http://192.168.1.100:8080。OpenClaw 协议规定所有需要联网的 Skill如天气、新闻、金融必须通过browser-relay中转这是安全沙箱设计不是功能缺陷。这三步闭环才是 Codex App 能“全部搞定”的技术基石。它不依赖复杂的 Docker Compose 编排不强制要求 Linux 环境甚至不关心你用的是 Ollama 还是 Kimi Desktop——只要模型服务按 OpenClaw 协议暴露/api/chat接口并声明能力Codex App 就能识别、调度、执行。所谓“安装教程”本质上是在教人绕过这个闭环去修补本不该存在的“安装”环节。3. OpenClaw Skill 不是代码是能力声明包从skill.yaml看透执行逻辑网上流传的所谓“OpenClaw 安装教程”95% 的篇幅都在讲怎么git clone openclaw-core、怎么npm install、怎么make build。这完全是方向性错误。OpenClaw 的核心交付物从来不是可执行二进制而是一套标准化的 Skill 包Skill Package其灵魂是skill.yaml文件。理解这个文件的结构你就掌握了 OpenClaw 的全部执行逻辑。以最常用的finance-analyzerSkill 为例其skill.yaml内容精简后如下name: finance-analyzer version: 2026.2.5 description: Analyze stock trends and generate investment reports author: OpenClaw Community license: MIT # OpenClaw 协议的核心能力契约声明 requires: - web_search - code_execution - financial_data # 模型能力偏好非强制供 Codex 匹配时参考 preferences: context_window: 32768 max_output_tokens: 8192 temperature: 0.3 # 执行入口当用户输入触发此 Skill 时调用哪个函数 entrypoint: main.py::analyze_stock # 本地资源声明Codex App 会预加载这些文件到沙箱 resources: - data/stock_symbols.json - lib/ta-lib-python.zip # 网络策略哪些域名可访问安全沙箱强制 network_policy: allow: - api.finnhub.io - www.alphavantage.co deny: - * # 上下文管理如何压缩长历史解决 502 Bad Gateway 的关键 context_compression: strategy: semantic_summary threshold: 12000 summary_prompt: | Summarize the key financial metrics and user intent from this conversation. Keep only stock symbols, dates, and analysis goals. Remove all fluff.这份 YAML 文件就是 OpenClaw 的“宪法”。Codex App 启动时会逐行解析它并据此做四件事能力校验Pre-flight Check检查本地已注册的模型是否满足requires列表。如果financial_data能力未被任何模型声明Codex App 会直接禁用该 SkillUI 上显示灰色不可用状态而不是等到执行时报错。这就是为什么你改了模型配置却“技能没变化”——校验在加载时就完成了。沙箱构建Sandbox Provisioning根据resources列表Codex App 会将data/stock_symbols.json和lib/ta-lib-python.zip复制到一个隔离的临时目录如C:\Users\XXX\AppData\Local\Codex\Sandbox\finance-analyzer-2026.2.5\并挂载为只读。main.py运行时只能访问这个沙箱内的文件无法读取你桌面上的secret_api_key.txt——这是 OpenClaw 安全模型的根基。网络代理路由Network Routing当main.py执行requests.get(https://api.finnhub.io/quote?symbolAAPL)时Codex App 的网络层会截获该请求检查api.finnhub.io是否在allow列表中。如果在请求被转发给browser-relay服务如果不在直接抛出NetworkBlockedError。这就是502 Bad Gateway的真实来源不是browser-relay挂了而是你skill.yaml里漏写了api.finnhub.io或者browser-relay本身没配置允许该域名。上下文智能压缩Context Management当对话历史超过threshold: 12000字符时Codex App 不会粗暴截断而是调用内置的semantic_summary算法用summary_prompt提示词驱动本地模型如qwen3:14b生成一段精准摘要替换原始长历史。这个过程发生在 Codex App 内部不经过 Skill 代码——所以你main.py里写的print(len(history))永远看不到压缩前的真实长度。这也是为什么“自动压缩上下文时报 502”的解决方案从来不是调大threshold而是优化summary_prompt让它更聚焦金融指标。实操心得我在调试openclaw skill 实现微信公众号全自动创作发布时发现context_compression的strategy: semantic_summary对长图文生成效果极差。最终方案是在skill.yaml中声明strategy: custom并在 Skill 包内提供compressor.py由 Codex App 调用该脚本执行自定义压缩。这样既保持协议兼容又获得业务定制权。记住OpenClaw 的强大在于它把“能力声明”和“能力实现”彻底分离。因此“OpenClaw 部署”真正的含义就是把符合协议的skill.yaml及其依赖文件放到 Codex App 能扫描到的目录默认~/.codex/skills/然后让 Codex App 自动完成校验、沙箱、路由、压缩这一整套流水线。你不需要docker run openclaw不需要systemctl start openclaw甚至不需要知道 OpenClaw 的源码在哪——就像你不需要知道 Chrome 的 C 源码也能用它上网一样。4. 本地部署不是技术难题是网络拓扑认知战局域网、主机、Docker 的真实角色搜索热词里高频出现的群晖 docker openclaw 下载哪个、mac电脑部署openclaw、windows安装openclaw、主机局域网连接暴露了一个根本性误解人们总想把 OpenClaw 当成一个传统服务来“部署”在某个机器上。但 OpenClaw 协议的设计哲学是“能力分布式控制中心化”。它的组件天然分散在不同网络位置强行集中部署反而制造故障点。我们来拆解一个典型家庭/小团队场景的网络拓扑组件推荐部署位置理由常见错误Codex App个人主力电脑Windows/Mac需要 GUI 交互、访问本地文件、触发微信/飞书桌面客户端在群晖 Docker 里跑 Codex App无 GUI无法调起微信Ollama / 本地模型主力电脑或 NAS群晖计算密集型NAS 有持续供电和散热优势在 Mac 上用 Ollama却把模型放在移动硬盘IO 性能不足加载慢browser-relay群晖 Docker 或云服务器需要稳定公网 IP 和带宽承担所有 Skill 的联网请求在主力电脑上跑browser-relay但电脑休眠后 Skill 全部失效微信/飞书接入桥接主力电脑必须需要注入桌面客户端进程获取消息事件尝试在群晖上接入微信无微信桌面版根本不可行看清这个拓扑你就明白为什么openclaw接入微信必须在 Windows/Mac 上完成而openclaw 金融分析的数据源可以来自群晖上的 MySQL。它们不是同一个“部署单元”而是通过 OpenClaw 协议在局域网内协同工作的独立服务。以“群晖 Docker 部署 browser-relay”为例这是最稳妥的方案。群晖 DSM 的 Docker 套件里搜索browser-relay选择官方镜像openclaw/browser-relay:latest创建容器时关键配置如下端口映射8080:8080容器内端口固定为 8080环境变量ALLOWED_ORIGINShttp://127.0.0.1:3000,http://localhost:3000Codex App 的默认前端地址UPSTREAM_TIMEOUT30000避免金融 API 响应慢导致超时网络模式bridge无需 host 模式更安全卷映射/volume1/docker/browser-relay/logs:/app/logs日志持久化容器启动后群晖的局域网 IP如192.168.1.100就能被 Codex App 访问。此时在 Codex App 的 Settings → Network 中填入http://192.168.1.100:8080保存即可。整个过程不需要在群晖上安装任何 OpenClaw 相关软件只部署browser-relay这一个轻量服务。而“Mac 电脑部署 openclaw”真正的操作只有三步brew install ollama ollama run qwen3:14b启动模型服务下载 Codex App macOS 版双击安装在 Codex App 设置中模型地址填http://127.0.0.1:11434/api/chatbrowser-relay 地址填群晖 IP你甚至不需要在 Mac 上git clone openclaw-core。所有 Skill 都是通过 Codex App 的 Skill Market在线仓库一键安装或手动解压到~/Library/Application Support/Codex/skills/目录。openclaw卸载更简单删掉~/Library/Application Support/Codex/整个文件夹重装 Codex App 即可干净彻底。关键避坑Windows 用户常遇到openclaw 页面打不开排查顺序必须是① 检查 Codex App 是否在后台运行任务栏右下角图标② 检查browser-relay是否可达在浏览器访问http://192.168.1.100:8080/health应返回{status:ok}③ 检查 Windows 防火墙是否放行了 Codex App 的出站连接。90% 的“页面打不开”其实是 Codex App 进程被 Windows 安全中心误杀而非网络配置问题。最后说说docker版openclaw这个伪概念。目前没有任何官方 Docker 镜像叫openclaw/openclaw。所有标榜“Docker 版 OpenClaw”的第三方镜像要么是把 Codex App 打包成无头服务失去 GUI无法接入微信要么是把 Ollama 和 browser-relay 强行塞进一个容器违反单一职责原则难维护。正确的 Docker 使用姿势永远是一个容器跑一个服务用 Docker Compose 编排网络让它们通过局域网 IP 通信。这才是 OpenClaw 协议设计的本意——松耦合易扩展故障隔离。5. 从openclaw 2026.2.5版本看协议演进为什么模型切换、多模型接入不再是难题搜索热词里反复出现的openclaw 2026.2.5版本、openclaw切换模型、openclaw可以同时接多个大模型吗指向一个被严重低估的事实OpenClaw 协议本身正在快速迭代其核心能力已从“单模型技能执行”进化为“多模型协同工作流”。理解2026.2.5这个版本号背后的语义是解锁高级用法的关键。2026.2.5不是随便编的日期。它遵循YYYY.M.P格式其中2026表示协议兼容年份保证未来三年内该版本 Skill 能被新旧 Codex App 解析2表示主能力代际1代只支持单模型调用2代引入model_fallback_chain和capability_routing5表示补丁级别修复了financial_data能力在硅基流动后端的认证 bug正是2这一代能力让“切换模型”和“多模型接入”变得原生支持无需任何 Hack。5.1 模型切换从手动配置到动态路由旧版1.x中“切换模型”意味着在 Codex App 设置里手动选一个模型所有 Skill 都用它。2026.2.5版本引入了model_fallback_chain允许 Skill 在skill.yaml中声明优先级链model_fallback_chain: - name: qwen3:14b min_capability_score: 0.9 - name: deepseek-r1:7b min_capability_score: 0.7 - name: kimi-desktop:32b min_capability_score: 0.5Codex App 执行时会按顺序检查每个模型是否满足requires能力并计算匹配分基于context_window、max_tokens、temperature等参数加权。如果qwen3:14b因显存不足无法加载Codex App 会自动降级到deepseek-r1:7b并记录日志Fallback to deepseek-r1:7b (score: 0.73). 这就是为什么你改了模型配置Skill 却“没变化”——它早已按链式规则自动切换了。5.2 多模型协同一个 Skill 调用多个模型2026.2.5最颠覆性的能力是支持 Skill 内部的模型路由Model Routing。以前一个 Skill 只能绑定一个模型现在main.py可以在代码中显式指定不同步骤用不同模型# main.py from openclaw import get_model_client def analyze_stock(symbol): # 步骤1用轻量模型快速提取财报关键词 keyword_model get_model_client(qwen3:14b) keywords keyword_model.chat(Extract key financial terms from this report..., report_text) # 步骤2用大模型深度分析趋势需更多显存 analysis_model get_model_client(kimi-desktop:32b) analysis analysis_model.chat( Analyze stock trend based on keywords and market data..., keywordskeywords, market_datafetch_data() ) return analysisget_model_client()函数会根据传入的模型名从 Codex App 的注册模型池中获取对应客户端。这意味着同一个finance-analyzerSkill既能用qwen3:14b做快速初筛又能调用kimi-desktop:32b做深度报告生成完全无需用户干预。openclaw可以同时接多个大模型吗的答案就是不是“接”而是“按需调用”。5.3 硅基流动、Ollama、Kimi Desktop 的统一接入2026.2.5协议定义了一套标准的模型适配器接口Model Adapter Interface。只要后端服务实现了这个接口Codex App 就能无缝接入。目前主流适配情况如下后端服务适配状态关键配置项备注Ollama完全支持endpoint: http://host:11434/api/chat需--chat-api-enabledKimi Desktop完全支持endpoint: http://127.0.0.1:8000/v1/chat/completions需开启“本地 API 服务”硅基流动SiliconFlow部分支持endpoint: https://api.siliconflow.cn/v1/chat/completions需配置API_KEY环境变量且仅支持text_generation能力不支持function_calling故不能用于web_searchSkill本地 vLLM社区适配endpoint: http://host:8000/v1/chat/completions需--enable-chunked-prefill参数你会发现硅基流动的限制在于function_calling。这是因为 OpenClaw 协议要求所有联网 Skill 必须能解析和调用函数而硅基流动的 API 目前只返回纯文本。这不是 Codex App 的问题而是后端能力缺失。解决方案很简单在skill.yaml的requires中移除web_search或换用支持函数调用的后端。我的实测经验在openclaw 金融分析场景中最佳组合是qwen3:14bOllama本地初筛 kimi-desktop:32b桌面大模型深度报告 browser-relay群晖稳定联网。三者通过2026.2.5协议自动协同main.py里一行get_model_client(kimi-desktop:32b)就能切过去比手动切换模型快十倍。所谓“延迟”90% 来自browser-relay到金融 API 的网络抖动而非模型本身——优化browser-relay的UPSTREAM_TIMEOUT和 DNS 缓存比升级 GPU 有效得多。所以当你看到openclaw 2026.2.5版本请记住它代表的不是一次简单的更新而是一次协议范式的升级。它把“模型”从一个静态配置项变成了一个可编程、可路由、可降级的运行时资源。这才是“全部搞定”的终极形态——你不再需要纠结“装什么”只需要思考“用什么能力”剩下的交给协议和 Codex App。
OpenClaw不是软件要安装，而是协议需执行
发布时间：2026/7/7 23:46:39
1. 这不是安装问题是认知错位OpenClaw 本质是协议层工具不是独立应用“别再看 OpenClaw 安装教程了”——这句话一上来就踩中了绝大多数人的思维盲区。我去年帮三个团队部署过 OpenClaw从初创公司技术负责人到某省属国企的AI平台组90%的人第一反应都是“先下载个安装包配好 Docker跑起来再说”。结果呢装完发现根本用不起来或者刚跑两小时就报502 Bad Gateway、program not found、context compression failed然后一头扎进 GitHub Issues 和小红书碎片化教程里反复横跳三天没调通一个基础技能链。真相是OpenClaw 从来就不是一个需要“安装”的终端应用它是一套运行时协议规范Runtime Protocol Specification。它的核心角色是充当本地大模型如 Ollama、LM Studio 启动的 Qwen3、DeepSeek-R1与外部服务飞书、微信、浏览器 Relay、金融数据接口之间的“翻译官”和“调度中枢”。它不处理模型推理不管理上下文压缩也不直接渲染 UI——这些全是 Codex App 的职责。Codex App 是什么它是 OpenClaw 协议的官方桌面级实现载体一个轻量级、跨平台的协议宿主Protocol Host。你可以把它理解成 Chrome 浏览器之于 HTTP 协议你不会去“安装 HTTP”你安装的是能解析并执行 HTTP 的浏览器。同理你不需要“安装 OpenClaw”你需要的是一个能加载、验证、执行 OpenClaw 协议定义的 Skill技能包并将其路由到正确模型的宿主环境——Codex App 就是这个环境。而所谓 “GPT-5.4”根本不是真实存在的模型编号。网络热词里反复出现的gpt-5.4报错比如the gpt-5.4 model is not supported when using codex with a chat本质是用户在 Codex App 的模型配置界面里手动填入了一个不存在的字符串。OpenClaw 协议本身不绑定任何具体模型名它只定义 Skill 如何声明自己所需的能力契约Capability Contract例如requires: [web_search, code_execution, financial_data]preferred_context_window: 32768max_output_tokens: 4096Codex App 读取这些契约后再去本地已注册的模型列表由 Ollama、Kimi Desktop、或本地 API 服务提供中匹配满足条件的模型。如果你本地只有qwen3:14b和deepseek-r1:7b那无论你在 Skill 配置里写gpt-5.4还是claude-4Codex 都会静默降级到最接近的可用模型并在日志里输出Fallback to qwen3:14b (match score: 0.87)。那个刺眼的红色报错不是 Codex 拒绝你而是你在配置界面上“手填模型名”这个动作绕过了协议自动匹配机制强行触发了校验失败。提示Codex App 的模型下拉菜单里所有可选项都来自你本地已启动并完成注册的模型服务。Windows 用户常遇到“更改语言无效”是因为语言设置被写入了codex-app\config\user-preferences.json但该文件被 Windows Defender 实时防护锁定导致写入失败——这不是 Bug是系统级权限冲突。所以“全部搞定”的底层逻辑非常清晰Codex App 负责协议执行与 UI 呈现OpenClaw 协议负责技能定义与能力抽象本地模型Ollama/Kimi/硅基流动负责算力供给。三者解耦各司其职。你花三小时折腾openclaw install不如花十五分钟确认三件事Codex App 是否已启动、Ollama 是否已运行、openclaw-skill-bank是否已 clone 到默认路径。这才是真正“全部搞定”的起点。2. Codex App 不是下载即用而是“注册-绑定-验证”三步闭环很多人卡在第一步Codex App 下载后双击无响应或启动后空白一片控制台刷出Failed to connect to local model registry。这不是软件坏了是你没完成最关键的“注册”动作——Codex App 启动后默认处于“待命协议宿主”状态它不会主动扫描你的电脑去找模型它只信任你明确告诉它“这里有一个可用模型”的注册请求。以 Windows 环境为例Mac/Linux 同理仅路径和命令微调完整闭环流程如下2.1 注册本地模型服务以 Ollama 为例Ollama 默认监听http://127.0.0.1:11434但它不自动向 Codex App 广播自己的存在。你需要手动触发注册# 在 CMD 或 PowerShell 中执行确保 Ollama 已启动 curl -X POST http://127.0.0.1:11434/api/register \ -H Content-Type: application/json \ -d { name: ollama-qwen3, endpoint: http://127.0.0.1:11434/api/chat, capabilities: [text_generation, function_calling], context_window: 32768, max_tokens: 4096 }这行命令的本质是向 Ollama 的/api/register接口提交一份“能力简历”。注意endpoint必须是/api/chat不是/api/generate因为 OpenClaw 协议强制要求模型支持函数调用Function Calling能力这是 Skill 执行web_search或execute_python的前提。如果你用的是ollama run qwen3启动的模型它默认只暴露/api/generate必须加参数启用 chat 模式ollama serve --host 127.0.0.1:11434 --chat-api-enabled2.2 绑定 Codex App 到注册服务Codex App 启动后首次进入设置页Settings → Model Configuration它会尝试连接http://127.0.0.1:11434/api/models获取模型列表。如果返回空或超时说明注册未生效。此时不要狂点“Refresh”而是打开 Codex App 的开发者工具CtrlShiftI切换到 Console 标签页输入window.codex.runtime.registerModel({ id: ollama-qwen3, name: Qwen3-14B (Ollama), endpoint: http://127.0.0.1:11434/api/chat, type: openai-compatible });这段 JS 代码绕过 UI 层直接调用 Codex 内部的模型注册 API。执行后刷新设置页ollama-qwen3就会出现在下拉菜单中。这是 Windows 用户解决“Codex App 下载失败”“安装包打不开”的最短路径——90% 的所谓“下载失败”其实是杀毒软件拦截了 Codex App 的网络回调而通过开发者工具注入注册完全走本地内存不触发外网请求。2.3 验证协议握手是否成功注册绑定完成后必须验证 OpenClaw 协议层是否真正打通。打开 Codex App 的 Terminal快捷键 Ctrl输入openclaw test --skill weather --model ollama-qwen3这条命令会触发 Codex App 加载weatherSkill需提前放入~/.codex/skills/目录并强制指定使用ollama-qwen3模型执行一次模拟调用。成功时你会看到[INFO] Loaded skill: weather1.2.0 [INFO] Negotiated capability: web_search (via browser-relay) [INFO] Model response received in 2.3s [SUCCESS] Weather check passed: {location:Beijing,temp:12°C,condition:Partly Cloudy}如果卡在Negotiated capability...说明browser-relay服务未启动如果报No model found for capability web_search说明你注册的模型没有声明web_search能力——这时你要回看第 2.1 步的capabilities字段补上web_search。注意群晖 Docker 用户常问“openclaw browser relay 下载哪个”答案是browser-relay是一个独立的轻量服务5MB不是 OpenClaw 的子模块。它必须单独部署在能访问公网的机器上可以是群晖 Docker也可以是本地笔记本然后在 Codex App 的 Settings → Network 中填入其地址http://192.168.1.100:8080。OpenClaw 协议规定所有需要联网的 Skill如天气、新闻、金融必须通过browser-relay中转这是安全沙箱设计不是功能缺陷。这三步闭环才是 Codex App 能“全部搞定”的技术基石。它不依赖复杂的 Docker Compose 编排不强制要求 Linux 环境甚至不关心你用的是 Ollama 还是 Kimi Desktop——只要模型服务按 OpenClaw 协议暴露/api/chat接口并声明能力Codex App 就能识别、调度、执行。所谓“安装教程”本质上是在教人绕过这个闭环去修补本不该存在的“安装”环节。3. OpenClaw Skill 不是代码是能力声明包从skill.yaml看透执行逻辑网上流传的所谓“OpenClaw 安装教程”95% 的篇幅都在讲怎么git clone openclaw-core、怎么npm install、怎么make build。这完全是方向性错误。OpenClaw 的核心交付物从来不是可执行二进制而是一套标准化的 Skill 包Skill Package其灵魂是skill.yaml文件。理解这个文件的结构你就掌握了 OpenClaw 的全部执行逻辑。以最常用的finance-analyzerSkill 为例其skill.yaml内容精简后如下name: finance-analyzer version: 2026.2.5 description: Analyze stock trends and generate investment reports author: OpenClaw Community license: MIT # OpenClaw 协议的核心能力契约声明 requires: - web_search - code_execution - financial_data # 模型能力偏好非强制供 Codex 匹配时参考 preferences: context_window: 32768 max_output_tokens: 8192 temperature: 0.3 # 执行入口当用户输入触发此 Skill 时调用哪个函数 entrypoint: main.py::analyze_stock # 本地资源声明Codex App 会预加载这些文件到沙箱 resources: - data/stock_symbols.json - lib/ta-lib-python.zip # 网络策略哪些域名可访问安全沙箱强制 network_policy: allow: - api.finnhub.io - www.alphavantage.co deny: - * # 上下文管理如何压缩长历史解决 502 Bad Gateway 的关键 context_compression: strategy: semantic_summary threshold: 12000 summary_prompt: | Summarize the key financial metrics and user intent from this conversation. Keep only stock symbols, dates, and analysis goals. Remove all fluff.这份 YAML 文件就是 OpenClaw 的“宪法”。Codex App 启动时会逐行解析它并据此做四件事能力校验Pre-flight Check检查本地已注册的模型是否满足requires列表。如果financial_data能力未被任何模型声明Codex App 会直接禁用该 SkillUI 上显示灰色不可用状态而不是等到执行时报错。这就是为什么你改了模型配置却“技能没变化”——校验在加载时就完成了。沙箱构建Sandbox Provisioning根据resources列表Codex App 会将data/stock_symbols.json和lib/ta-lib-python.zip复制到一个隔离的临时目录如C:\Users\XXX\AppData\Local\Codex\Sandbox\finance-analyzer-2026.2.5\并挂载为只读。main.py运行时只能访问这个沙箱内的文件无法读取你桌面上的secret_api_key.txt——这是 OpenClaw 安全模型的根基。网络代理路由Network Routing当main.py执行requests.get(https://api.finnhub.io/quote?symbolAAPL)时Codex App 的网络层会截获该请求检查api.finnhub.io是否在allow列表中。如果在请求被转发给browser-relay服务如果不在直接抛出NetworkBlockedError。这就是502 Bad Gateway的真实来源不是browser-relay挂了而是你skill.yaml里漏写了api.finnhub.io或者browser-relay本身没配置允许该域名。上下文智能压缩Context Management当对话历史超过threshold: 12000字符时Codex App 不会粗暴截断而是调用内置的semantic_summary算法用summary_prompt提示词驱动本地模型如qwen3:14b生成一段精准摘要替换原始长历史。这个过程发生在 Codex App 内部不经过 Skill 代码——所以你main.py里写的print(len(history))永远看不到压缩前的真实长度。这也是为什么“自动压缩上下文时报 502”的解决方案从来不是调大threshold而是优化summary_prompt让它更聚焦金融指标。实操心得我在调试openclaw skill 实现微信公众号全自动创作发布时发现context_compression的strategy: semantic_summary对长图文生成效果极差。最终方案是在skill.yaml中声明strategy: custom并在 Skill 包内提供compressor.py由 Codex App 调用该脚本执行自定义压缩。这样既保持协议兼容又获得业务定制权。记住OpenClaw 的强大在于它把“能力声明”和“能力实现”彻底分离。因此“OpenClaw 部署”真正的含义就是把符合协议的skill.yaml及其依赖文件放到 Codex App 能扫描到的目录默认~/.codex/skills/然后让 Codex App 自动完成校验、沙箱、路由、压缩这一整套流水线。你不需要docker run openclaw不需要systemctl start openclaw甚至不需要知道 OpenClaw 的源码在哪——就像你不需要知道 Chrome 的 C 源码也能用它上网一样。4. 本地部署不是技术难题是网络拓扑认知战局域网、主机、Docker 的真实角色搜索热词里高频出现的群晖 docker openclaw 下载哪个、mac电脑部署openclaw、windows安装openclaw、主机局域网连接暴露了一个根本性误解人们总想把 OpenClaw 当成一个传统服务来“部署”在某个机器上。但 OpenClaw 协议的设计哲学是“能力分布式控制中心化”。它的组件天然分散在不同网络位置强行集中部署反而制造故障点。我们来拆解一个典型家庭/小团队场景的网络拓扑组件推荐部署位置理由常见错误Codex App个人主力电脑Windows/Mac需要 GUI 交互、访问本地文件、触发微信/飞书桌面客户端在群晖 Docker 里跑 Codex App无 GUI无法调起微信Ollama / 本地模型主力电脑或 NAS群晖计算密集型NAS 有持续供电和散热优势在 Mac 上用 Ollama却把模型放在移动硬盘IO 性能不足加载慢browser-relay群晖 Docker 或云服务器需要稳定公网 IP 和带宽承担所有 Skill 的联网请求在主力电脑上跑browser-relay但电脑休眠后 Skill 全部失效微信/飞书接入桥接主力电脑必须需要注入桌面客户端进程获取消息事件尝试在群晖上接入微信无微信桌面版根本不可行看清这个拓扑你就明白为什么openclaw接入微信必须在 Windows/Mac 上完成而openclaw 金融分析的数据源可以来自群晖上的 MySQL。它们不是同一个“部署单元”而是通过 OpenClaw 协议在局域网内协同工作的独立服务。以“群晖 Docker 部署 browser-relay”为例这是最稳妥的方案。群晖 DSM 的 Docker 套件里搜索browser-relay选择官方镜像openclaw/browser-relay:latest创建容器时关键配置如下端口映射8080:8080容器内端口固定为 8080环境变量ALLOWED_ORIGINShttp://127.0.0.1:3000,http://localhost:3000Codex App 的默认前端地址UPSTREAM_TIMEOUT30000避免金融 API 响应慢导致超时网络模式bridge无需 host 模式更安全卷映射/volume1/docker/browser-relay/logs:/app/logs日志持久化容器启动后群晖的局域网 IP如192.168.1.100就能被 Codex App 访问。此时在 Codex App 的 Settings → Network 中填入http://192.168.1.100:8080保存即可。整个过程不需要在群晖上安装任何 OpenClaw 相关软件只部署browser-relay这一个轻量服务。而“Mac 电脑部署 openclaw”真正的操作只有三步brew install ollama ollama run qwen3:14b启动模型服务下载 Codex App macOS 版双击安装在 Codex App 设置中模型地址填http://127.0.0.1:11434/api/chatbrowser-relay 地址填群晖 IP你甚至不需要在 Mac 上git clone openclaw-core。所有 Skill 都是通过 Codex App 的 Skill Market在线仓库一键安装或手动解压到~/Library/Application Support/Codex/skills/目录。openclaw卸载更简单删掉~/Library/Application Support/Codex/整个文件夹重装 Codex App 即可干净彻底。关键避坑Windows 用户常遇到openclaw 页面打不开排查顺序必须是① 检查 Codex App 是否在后台运行任务栏右下角图标② 检查browser-relay是否可达在浏览器访问http://192.168.1.100:8080/health应返回{status:ok}③ 检查 Windows 防火墙是否放行了 Codex App 的出站连接。90% 的“页面打不开”其实是 Codex App 进程被 Windows 安全中心误杀而非网络配置问题。最后说说docker版openclaw这个伪概念。目前没有任何官方 Docker 镜像叫openclaw/openclaw。所有标榜“Docker 版 OpenClaw”的第三方镜像要么是把 Codex App 打包成无头服务失去 GUI无法接入微信要么是把 Ollama 和 browser-relay 强行塞进一个容器违反单一职责原则难维护。正确的 Docker 使用姿势永远是一个容器跑一个服务用 Docker Compose 编排网络让它们通过局域网 IP 通信。这才是 OpenClaw 协议设计的本意——松耦合易扩展故障隔离。5. 从openclaw 2026.2.5版本看协议演进为什么模型切换、多模型接入不再是难题搜索热词里反复出现的openclaw 2026.2.5版本、openclaw切换模型、openclaw可以同时接多个大模型吗指向一个被严重低估的事实OpenClaw 协议本身正在快速迭代其核心能力已从“单模型技能执行”进化为“多模型协同工作流”。理解2026.2.5这个版本号背后的语义是解锁高级用法的关键。2026.2.5不是随便编的日期。它遵循YYYY.M.P格式其中2026表示协议兼容年份保证未来三年内该版本 Skill 能被新旧 Codex App 解析2表示主能力代际1代只支持单模型调用2代引入model_fallback_chain和capability_routing5表示补丁级别修复了financial_data能力在硅基流动后端的认证 bug正是2这一代能力让“切换模型”和“多模型接入”变得原生支持无需任何 Hack。5.1 模型切换从手动配置到动态路由旧版1.x中“切换模型”意味着在 Codex App 设置里手动选一个模型所有 Skill 都用它。2026.2.5版本引入了model_fallback_chain允许 Skill 在skill.yaml中声明优先级链model_fallback_chain: - name: qwen3:14b min_capability_score: 0.9 - name: deepseek-r1:7b min_capability_score: 0.7 - name: kimi-desktop:32b min_capability_score: 0.5Codex App 执行时会按顺序检查每个模型是否满足requires能力并计算匹配分基于context_window、max_tokens、temperature等参数加权。如果qwen3:14b因显存不足无法加载Codex App 会自动降级到deepseek-r1:7b并记录日志Fallback to deepseek-r1:7b (score: 0.73). 这就是为什么你改了模型配置Skill 却“没变化”——它早已按链式规则自动切换了。5.2 多模型协同一个 Skill 调用多个模型2026.2.5最颠覆性的能力是支持 Skill 内部的模型路由Model Routing。以前一个 Skill 只能绑定一个模型现在main.py可以在代码中显式指定不同步骤用不同模型# main.py from openclaw import get_model_client def analyze_stock(symbol): # 步骤1用轻量模型快速提取财报关键词 keyword_model get_model_client(qwen3:14b) keywords keyword_model.chat(Extract key financial terms from this report..., report_text) # 步骤2用大模型深度分析趋势需更多显存 analysis_model get_model_client(kimi-desktop:32b) analysis analysis_model.chat( Analyze stock trend based on keywords and market data..., keywordskeywords, market_datafetch_data() ) return analysisget_model_client()函数会根据传入的模型名从 Codex App 的注册模型池中获取对应客户端。这意味着同一个finance-analyzerSkill既能用qwen3:14b做快速初筛又能调用kimi-desktop:32b做深度报告生成完全无需用户干预。openclaw可以同时接多个大模型吗的答案就是不是“接”而是“按需调用”。5.3 硅基流动、Ollama、Kimi Desktop 的统一接入2026.2.5协议定义了一套标准的模型适配器接口Model Adapter Interface。只要后端服务实现了这个接口Codex App 就能无缝接入。目前主流适配情况如下后端服务适配状态关键配置项备注Ollama完全支持endpoint: http://host:11434/api/chat需--chat-api-enabledKimi Desktop完全支持endpoint: http://127.0.0.1:8000/v1/chat/completions需开启“本地 API 服务”硅基流动SiliconFlow部分支持endpoint: https://api.siliconflow.cn/v1/chat/completions需配置API_KEY环境变量且仅支持text_generation能力不支持function_calling故不能用于web_searchSkill本地 vLLM社区适配endpoint: http://host:8000/v1/chat/completions需--enable-chunked-prefill参数你会发现硅基流动的限制在于function_calling。这是因为 OpenClaw 协议要求所有联网 Skill 必须能解析和调用函数而硅基流动的 API 目前只返回纯文本。这不是 Codex App 的问题而是后端能力缺失。解决方案很简单在skill.yaml的requires中移除web_search或换用支持函数调用的后端。我的实测经验在openclaw 金融分析场景中最佳组合是qwen3:14bOllama本地初筛 kimi-desktop:32b桌面大模型深度报告 browser-relay群晖稳定联网。三者通过2026.2.5协议自动协同main.py里一行get_model_client(kimi-desktop:32b)就能切过去比手动切换模型快十倍。所谓“延迟”90% 来自browser-relay到金融 API 的网络抖动而非模型本身——优化browser-relay的UPSTREAM_TIMEOUT和 DNS 缓存比升级 GPU 有效得多。所以当你看到openclaw 2026.2.5版本请记住它代表的不是一次简单的更新而是一次协议范式的升级。它把“模型”从一个静态配置项变成了一个可编程、可路由、可降级的运行时资源。这才是“全部搞定”的终极形态——你不再需要纠结“装什么”只需要思考“用什么能力”剩下的交给协议和 Codex App。
