OPENCLAW USER MANUAL

OpenClaw

使用手册

围绕 OpenClaw 的产品判断、系统结构、部署方式与调度逻辑展开的完整说明文档。

A practical guide to OpenClaw, covering system structure, deployment, model setup, and orchestration.

涵盖内容:赚钱案例 · 安装部署 · 大模型配置 · 踩坑经验 · 行业落地方案

Contact
Ivan: 0478586867
WeChat Contact QR
Class

目录

第一部分:核心判断与开篇01
核心数据一览01
前言:Openclaw是2026年最大的黑马02
第二部分:OpenClaw背景与为什么火03
AI Agent 时代的到来03
从0到278,932 Stars:史上最快增长04
创始人:Peter Steinberger05
Peter的完整故事:从一小时原型到改变世界06
命名大战:从OpenCloud到OpenClaw07
加入OpenAI:与Zuck和Sam的对话08
Peter的哲学:80%的App将会消失09
Skills > MCP:Peter的鲜明立场10
与ChatGPT的本质区别:顾问 vs 员工11
与Claude Code的对比:生活助手 vs 编程工具12
"养虾"文化:为什么有社交属性13
OpenClaw 面向哪些人群13
第三部分:安装、部署与详细配置14
部署方式选择指南14
Mac mini 部署(隐私优先,低功耗长期运行)15
关键配置文件逐行解析16
渠道接入详细配置17
30个高频报错排查手册18
第四部分:大模型选择与配置指南19
第十章:大模型市场全景(2026年3月)19
第十一章:各模型深度评测19
第十二章:智能模型路由配置20
第十三章:五大场景模型推荐方案21
第十四章:成本控制与优化技巧22
第十四章A:国外模型接入方式--OpenRouter 聚合 API23
第十四章B:国内模型接入方式--Coding Plan计划24
第一部分:核心判断与开篇

核心数据一览

先看结论。OpenClaw 不是一个慢热项目,而是典型的高势能引爆型产品。它踩中了 AI 从"会回答"转向"会执行"的时间点,同时用开源、自托管和多平台接入,迅速把抽象概念变成了可部署的个人 Agent 系统。

GitHub Stars
278,932
原文称其已登顶 GitHub,增长速度超越 React 等老牌项目。
ClawHub Skills
13,729 个
技能生态已形成规模,说明 OpenClaw 不只是单体工具,而是可扩展平台。
国内用户规模
10 万+
原文口径,强调其中文社区扩散速度和本土平台渗透能力。
最新稳定版
v2026.3.7
作为全文配置内容的版本锚点,相关示例均以此为准。

前言:Openclaw是2026年最大的黑马

OpenClaw的出现,在我看来不是偶然,而是完全必然。当模型能力、工具调用能力和多步任务稳定性同时跨过临界点,一个真正能替人执行任务的 Agent 框架出现,只是时间问题。Peter Steinberger 的周末项目,刚好踩中了这个节点。

这本电子书,和市面上已有的指南不同。多数指南是技术参考手册,适合技术性查阅。而这本书,是我从一个应用实践的视角去看待技术,结合社区的一手经验,为真正想用OpenClaw做事的人写的实践指南。

这本书的目标只有一个:读完之后,你能真正用 OpenClaw 做成一件有价值的事。

第二部分:OpenClaw背景与为什么火

AI Agent 时代的到来

2025 年,大语言模型发生了一次真正意义上的能力跃迁。模型不再只是更流畅地说话,而是开始具备使用工具、执行多步任务、与外部世界持续交互的能力。这种变化,让"聊天机器人"与"Agent"之间第一次出现了清晰边界。

第一,工具调用能力成熟

Anthropic、OpenAI 等模型在 Tool Use 上逐步进入实用阶段。模型不再只输出文本,而是能够判断何时调用 API、传入什么参数,并根据返回结果继续完成后续推理。这个能力决定了 AI 能否从"会回答问题"走向"会处理事情"。

第二,多步推理链条稳定

早期模型在链式任务里很容易迷路。做完 A,接 B,再到 C,经常会出现目标漂移、上下文混乱和幻觉放大。到了 2025 年,新一代模型在连续工具调用场景中的稳定性大幅提升,终于可以较可靠地完成"搜索信息、整理结果、输出报告、再发到指定渠道"这类复合任务。

OpenClaw 的意义,就在于它把这种能力工程化了。它不是再造一个聊天界面,而是把 AI 执行多步任务的能力,通过开源、自托管、多平台接入的方式,交到更多普通用户和团队手里。

从0到278,932 Stars:史上最快增长

OpenClaw 的火,不只是"很多人讨论",而是体现在一条极短时间内冲顶的增长曲线上。源文档给出的叙述重点,不是平滑扩张,而是连续爆点叠加之后的失控传播。

时间关键事件
2025 年 11 月Peter Steinberger 以"周末项目"发布 ClawdBot。项目最初是一套连接即时通讯平台的 AI 助手原型,龙虾形象和 Claw 命名从一开始就很鲜明。
2026 年 1 月中旬项目进入爆发式增长期。原文称其在 72 小时内获得 6 万 Stars,并出现单日增长 9,000 Stars 的高峰。
2026 年 1 月 27 日因与 Claude 名称相近,项目收到商标压力,被迫短暂改名。
2026 年 1 月 30 日最终更名为 OpenClaw。名称转向更明确的开源定位,同时保留龙虾主题。
2026 年 2 月初安全危机集中爆发,包括远程代码执行漏洞和 ClawHub 供应链攻击,项目被迫面对"高速增长 + 高风险暴露"的现实。
2026 年 2 月 14 日Peter 宣布加入 OpenAI。项目转交开源基金会运营,OpenAI 作为赞助方之一,但不控制项目方向。
2026 年 3 月 3 日原文称 OpenClaw Stars 超过 25 万,超越 React,成为 GitHub 全球第一软件项目。
2026 年 3 月 6 日至 8 日中文互联网和线下传播继续升温,项目完成从开发者社区热点到社会化话题的跨圈扩散。
增长速度的历史对比

因为它不是靠单一功能取胜,而是同时满足了几个条件:模型能力刚刚成熟、使用门槛被极大压低、传播载体是每个人已经在用的消息平台、再加上开源与社区二次创作,最终把一个"AI 助手框架"变成了可以迅速被模仿、部署和炫耀的社会化产品。

项目达到 25 万 Stars 用时
React10 年以上
Vue7 年以上
TensorFlow5 年以上
OpenClaw不到 4 个月

创始人:Peter Steinberger

Peter Steinberger 是一位奥地利开发者,在 iOS 和 macOS 开发圈长期具有较高知名度。OpenClaw 的重要性,很大一部分来自这个项目并不是由一个临时蹭热点的创业者做出来的,而是出自一个已经经历过完整产品、公司和退出周期的人。

"I'm a builder at heart... What I want is to change the world, not build a large company."

这句话是理解 Peter 的钥匙。他的驱动力不是再复制一次标准创业路线,而是重新回到"做出某个真正能改变世界的东西"这件事本身。源文档提到,在不到五个月的时间里,他个人就在项目上提交了 11,684 次 commit。这既说明投入强度,也解释了为什么 OpenClaw 在早期会表现出极强的个人风格。

从 PSPDFKit 到倦怠退休

在 OpenClaw 之前,Peter 已经完成过一次重量级创业。他用 13 年时间把 PSPDFKit 从一个 PDF 显示库做成运行在 10 亿台设备上的企业级产品,并最终完成出售。表面看,这是经典成功故事;但按他后来的回顾,这段经历留下的不是轻松,而是长期的人际冲突和彻底的精疲力竭。

退休后,他买了单程机票去马德里,试图补上生活中被工作挤压掉的部分。但很快他发现,彻底脱离创造并不带来自由,反而会带来空洞。没有挑战,没有期待,人的状态并不会自动变好。这个阶段很重要,因为它解释了 OpenClaw 为什么不是"商业计划",而更像一次强烈的个人反弹。

Peter的完整故事:从一小时原型到改变世界

源文档这一段最有价值的,不是传奇色彩,而是它给出了一个非常具体的原型诞生路径。真正改变世界的东西,最初往往并不复杂。

一小时原型的诞生

2025 年 11 月,那个旧想法重新回来。Peter 想要的不是另一个聊天机器人,而是一个真正能控制电脑、替他完成任务的个人助手。为了验证这个想法,他没有先设计宏大架构,而是用最短路径把链路接起来。

整个原型,原文称只花了一小时。随后又用了几个小时补上图片支持。第一版没有复杂框架,没有完整设计,甚至连名字都不重要。重点只有一个,它先活了起来。

马拉喀什的顿悟时刻

原型完成后不久,Peter 在摩洛哥马拉喀什旅行时做了一次测试。他给自己的 Bot 发去一条语音消息。这个 Bot 并没有预设语音识别功能,但它没有停在"我不支持"。相反,它自己识别文件头、尝试调用 FFmpeg、发现本地未安装后,转而用 curl 去调用 OpenAI Whisper API,再把转录结果发回。整个过程据称只用了约 9 秒。

这个瞬间的意义,不是功能有多复杂,而是系统开始表现出"自主补齐缺失环节"的倾向。也正是在这里,OpenClaw 从一个方便的脚本,变成了一个真正让人感到震动的 Agent 雏形。

全程:约9秒。

OpenClaw 的爆发,不只是因为模型更强了,也不是因为 Peter 恰好有名气。更核心的原因是,他把 Agent 的价值定义得很清楚:不是回答得更漂亮,而是能不能把任务真正做完。这个定义非常朴素,但足够锋利,也足够适合传播。

命名大战:从OpenCloud到OpenClaw

OpenClaw 的名字经历了一段堪称惊险的历史。

第一个名字:OpenCloud(原名)

最初项目叫 OpenCloud,强调「开放的云端能力」。但很快收到来自云服务商的商标压力。

第二个名字:Clade(含义:Claude 的爪子)

改名 Clade,取 Claw + Anthropic 字母,寓意与 Claude 的连接。数天后,收到 Anthropic 法务团队的邮件:「友善但紧迫,请改名。」

险些失败的第三个名字:Moltbot(Molt=龙虾蜕壳)

这是整个命名战中最惊心动魄的一幕。Peter 计划把账号名原子化地同时迁移到所有平台——GitHub、Twitter、NPM、Docker、域名,必须同时完成,否则会有人抢注。

结果,消息还是泄露了。加密社区(另一个 crypto 项目声称先用了某相关名称)提前盯上了:

Peter 当时在某个会议室里,「差点哭出来」,一度想直接删除整个项目。好在 Twitter 和 GitHub 的朋友紧急介入,帮助恢复了账号控制权。

最终名字:OpenClaw

Peter 直接联系 Anthropic,问:「OpenClaw 可以吗?」Anthropic 确认 OK(他们内部其实也有点喜欢这个名字)。

加入OpenAI:与Zuck和Sam的对话

OpenClaw 爆红之后,Peter 面前其实有三条路:继续自己做,成立公司融资,或者加入大厂。源文档给出的判断很明确,他不想再重复一次 13 年创业史,也不想把自己重新放回漫长的组织博弈里。最终他选择加入 OpenAI,看中的不是报价,而是"乐趣和影响力"。

与Sam Altman(OpenAI):

原文提到,Peter 与 Meta 和 OpenAI 都有过关键对话。Meta 的吸引力在资源,OpenAI 的吸引力在方向感。尤其是 Codex 路线,让他产生了更强的情感认同。对于一个把自己定义为 builder 的人来说,这种"我想跟谁一起把事情做大"的判断,往往比单纯的薪酬更重要。

不是为钱,而是为了乐趣和影响力。

这次加入最重要的后续安排,是项目并没有被 OpenAI 私有化。按源文档叙述,OpenClaw 被移交给开源基金会运营,OpenAI 只是赞助方之一,并不直接控制方向。这个安排很关键,它把"创始人个人职业选择"和"项目公共属性"分开处理,尽量压低社区对收编的焦虑。

Anthropic的反将:从起诉威胁到全行业拥抱

源文档对 Anthropic 的描述相当尖锐。它的核心意思只有一句:Anthropic 最先意识到 OpenClaw 的风险,却没有最先理解它的价值。法务动作很快,生态动作很慢。结果是,本来最该拥抱这一波 Agent 运动的公司,反而因为商标和安全顾虑,给了竞争对手足够的时间窗口。

这也是为什么原文会把这件事描述为一次典型的"大公司被自己的谨慎反将"。从行业角度看,OpenClaw 不是单独某个开源项目的胜负,而是一次关于平台心态的测试:当社区自发把你的模型能力外延化时,你是把它视作风险,还是视作杠杆。

Peter的哲学:80%的App将会消失

Peter 的判断并不温和。他不是在说"AI 会让软件更智能",而是在说,大量今天习以为常的软件形态,本身会被 Agent 吞掉。

这个文件从来没有公开过。

他的逻辑很直接。如果一个应用的核心只是记录、提醒、查询、填表或调度,那么这些动作都可能被 Agent 统一接管。用户不再需要记住几十个 App 的入口,而是只要把目标交给一个持续在线的助手。日历、邮件、任务管理、票务预订、简单 CRM,这类软件最先承压。

中期判断:Bot-to-Bot 经济会出现

源文档提到更激进的一层:未来不只是人使用 Agent,而是 Agent 代表人去和其他 Agent 交涉。你的 Bot 去联系餐厅 Bot、客服 Bot、平台 Bot,甚至雇佣线下执行者完成最后一公里。人类从大量数字流程里退场,变成定义目标、授权边界和做最终判断的人。

长期判断:通用智能未必最强,协作的专业智能更现实

Peter 并不迷信单一全能体。他更偏向另一种图景:像人类社会一样,AI 也会专业分工。有人擅长研究,有人擅长写作,有人擅长调用系统,有人擅长编程。真正强大的,不一定是一个什么都做的通用大脑,而是一群能协作的专业智能体。

这套哲学解释了 OpenClaw 为什么不是另一个聊天壳。它真正想做的,是把"会说话的模型"变成"持续在线、带边界、可积累、可分工"的执行系统。也正因为这个目标足够大,OpenClaw 才会同时吸引开发者、内容创作者、自动化玩家和研究型用户。

Skills > MCP:Peter的鲜明立场

在工具协议这件事上,Peter 的立场非常鲜明。源文档把它概括为一句话:OpenClaw 没有把 MCP 当成核心,而是走了 Skills + CLI 的路线。争论的重点,不是 MCP 能不能用,而是哪种方式更适合长期扩展的 Agent 系统。

MCP的问题,不在理念,而在运行成本
Skills的优势,在于按需加载和低摩擦扩展

OpenClaw 的 Skills 本质上是以 SKILL.md 为入口的工具说明系统。模型先读取简要描述,再决定要不要深入加载、更详细地看帮助文档,最后才实际调用工具。这个过程不像 MCP 那样要求一开始把所有工具暴露给模型,而是让模型像人类一样"先知道有这个东西,需要时再看说明书"。

这套机制与 CLI 天然适配。CLI 的优点不是古老,而是稳定、可组合、跨平台、可脚本化。只要一个工具在终端里能跑,OpenClaw 就能较自然地把它收编进 Agent 工作流。也正因此,它能够支撑 ClawHub 上数量庞大的技能生态,而不必每加一个技能就重启整个系统。

这不是宗教战争,而是产品路径选择

需要强调的是,Skills vs MCP 并不等于谁绝对先进。更准确地说,这是两种不同的产品取向。MCP 更像统一协议,希望把工具世界整理成标准接口。OpenClaw 的 Skills 则更像现实主义路线,优先解决"今天怎样把事做完"。对于一个强调自托管、多平台接入、快速扩展的系统来说,后者在当前阶段确实更有效。

与ChatGPT的本质区别:顾问 vs 员工

一句话总结:ChatGPT是顾问,OpenClaw是员工。

顾问的工作方式是"你问,他答"。员工的工作方式是"你交代任务,他去做,中间自己补足环节,最后回来汇报"。这不是能力高低之分,而是产品定位不同。ChatGPT 的长处是把复杂问题解释清楚,OpenClaw 的长处是把分散动作串起来。

维度ChatGPTOpenClaw
交互模式你问它答,被动响应你布置任务,它主动执行
运行方式网页或 App 内使用自托管,可 24/7 在线
入口主要是自有界面可接入 Telegram、WhatsApp、飞书、钉钉等多平台
扩展性受平台限制可通过 Skills 持续扩展
数据控制平台托管为主本地可控,边界更清晰
模型选择以 GPT 系列为主可接入 Claude、GPT、Gemini、DeepSeek、Ollama 等

所以,OpenClaw 不是 ChatGPT 的替代网页,而是另一类产品。它更接近"你自己的操作系统入口",或者说,一个在消息流中待命的数字执行层。

与Claude Code的对比:生活助手 vs 编程工具

很多人会问:"我已经有Claude Code了,还需要OpenClaw吗?"这个问题问错了。两者不是同一类产品。

维度OpenClawClaude Code
核心定位通用 AI 助手 / Life OS专业编程 Agent
主要环境自托管服务 + 消息平台终端 CLI / IDE 集成
主要对象消息、邮件、网页、日程、自动化流程代码库、文件系统、测试与调试
记忆机制多层记忆,长期积累会话上下文 + 指令文件
扩展方式ClawHub Skills,动态插件化以编程任务和规则文件为主
模型支持多模型仅 Claude 体系
强项长期在线、多平台联动代码理解、改写、重构、测试

最合理的实践不是二选一,而是分工。用 OpenClaw 管理消息、邮箱、日程、网页和轻量自动化,用 Claude Code 处理代码库、调试、重构和工程交付。二者组合,才更像 2026 年完整的 AI 工作流。

"养虾"文化:为什么有社交属性

中文社区把运行和维护OpenClaw实例称为"养虾",用户自称"养虾人"。这不是一个玩笑,而是它带有社交属性的一部分。

这层文化外壳非常重要。它把原本偏硬核的技术系统,转成了可以展示、可以讨论、甚至可以拟人化养成的东西。用户不只是配置一个工具,更像是在养一个有性格、会出错、会成长的数字生命体。

Moltbook:AI Agent的社交网络

源文档还提到 Moltbook 这类 Agent 社交空间。其意义不在于数据规模本身,而在于它提供了一个观察窗口:当大量 Agent 被赋予名字、人格、规则和任务之后,它们之间是否会形成某种社会化行为。即使这些实验仍很早期,它也说明 OpenClaw 的想象空间并不止于自动化。

OpenClaw 面向哪些人群

OpenClaw 的扩散速度快,部分原因就在于它不是只服务单一圈层。它既能让技术用户深挖,也能让非技术用户直接感受到"省时间"这件事。

人群主要动机典型玩法
开发者 / 技术人员完全掌控、可 hack、可自托管定制 SOUL.md、自己写 Skills、研究 Agent 架构
个人用户 / 效率控真正解放双手,管理数字生活接入消息平台,管理邮件、日历、提醒和网页操作
创业者 / 自由职业者把自动化能力包装为服务为客户搭建 AI 助手、销售自动化或内容工作流
企业用户把 Agent 接入内部协作平台客服、运营、知识库、数据分析和内部问答
研究者 / AI 爱好者观察 Agent 的边界与社会化行为设定人格、研究长期记忆、测试多 Agent 协作
内容创作者提高更新频率和分发效率选题整理、转写、摘要、矩阵化发布
真正的目标用户,不是最懂技术的人,而是最讨厌重复的人

如果用一句话概括 OpenClaw 的核心人群,那就是:手上有很多琐碎数字任务,希望把它们交给一个长期在线助手的人。会不会写代码当然有影响,但不是决定性门槛。真正决定使用强度的,是你是否有足够多值得自动化的日常流程。

这也是 OpenClaw 能跨圈层传播的原因。对开发者,它是可编排的 Agent 平台;对普通用户,它是会做事的私人助理;对企业,它是低成本试水 AI 自动化的入口。一个产品能同时在这三条线上成立,本身就是它成为黑马的重要原因。

第三部分:安装、部署与详细配置

部署方式选择指南

部署 OpenClaw,最容易踩的第一个坑,不是命令敲错,而是部署形态选错。很多人一上来就照着教程装,装完才发现:机器不常开、消息收不到、浏览器自动化跑不稳、手机节点根本连不上。OpenClaw 不是纯本地桌面工具,它更像一套持续在线的 Agent 基础设施,所以第一步应该是选部署方式。

部署方式选择指南
部署形态适合谁优点主要代价
本机临时运行只想快速试玩、验证模型与渠道是否可用的用户最快上手,不需要额外硬件电脑休眠即离线,不适合长期接管消息
Mac mini 常驻个人深度用户、内容创作者、小团队稳定、安静、低功耗,适合长期在线与浏览器自动化需要处理远程访问、登录态、系统睡眠与更新策略
Linux 主机 / NAS熟悉命令行、重视成本控制的技术用户可 24/7 运行,适合 Docker 与脚本化桌面浏览器、扫码登录、媒体能力配置更复杂
云服务器需要公网稳定访问、跨地域协作的团队外网可达性最好,便于远程节点接入安全责任更高,浏览器和消息平台风控更敏感
混合部署要求最高的进阶用户把网关、浏览器、节点、消息插件拆开部署,弹性最大配置最复杂,排查链路最长

如果你是个人用户

优先选 Mac mini 或一台长期不断电的家用主机。原因很简单:OpenClaw 的最佳体验往往依赖真实浏览器、长期登录态和稳定磁盘,不只是算力。

推荐长期在线兼顾图形能力

如果你是小团队

优先考虑"云服务器 + 本地浏览器节点"或"Mac mini + 反向代理"的组合。前者便于公网接入,后者更适合需要人工登录的平台。

团队协作可拆分部署安全边界清晰

选部署形态时,不要只看"能不能跑起来",要看"出问题时你能不能接得住"。OpenClaw 真正消耗时间的环节,在运行后的维护,而不是第一次安装。

Mac mini 部署(隐私优先,低功耗长期运行)

如果只推荐一种个人长期部署方案,Mac mini 仍然是最均衡的选择。它的优势不在于跑分,而在于图形环境稳定、功耗低、系统睡眠可控、浏览器兼容性好,适合把 OpenClaw 当成真正的日常助手来养。

硬件建议

M 系列芯片即可。16GB 内存起步更稳,512GB SSD 更适合缓存浏览器与会话数据。

系统要求

建议使用较新的 macOS 稳定版,避免开发者预览版。Node、Homebrew、浏览器与系统权限更容易保持兼容。

网络要求

固定家庭宽带或稳定企业网络即可。若要外网访问,优先用 Tailscale、Cloudflare Tunnel 或反向代理。

安装流程的正确顺序

顺序很重要。先装运行环境,再装 OpenClaw,再处理模型和渠道,最后才做自启动与远程访问。很多报错不是版本有问题,而是顺序不对,导致路径、权限和会话目录都乱了。

Mac mini 首次安装示例
# 1) 安装 Homebrew(如未安装)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2) 安装 Node.js LTS
brew install node
node -v
npm -v

# 3) 全局安装 OpenClaw
npm install -g openclaw

# 4) 初始化并检查版本
openclaw --version
openclaw help

# 5) 启动网关
openclaw gateway start
openclaw gateway status

Mac mini 常见误区:

第一,用远程桌面连上去后把机器锁屏或休眠,结果浏览器自动化全部失效。

第二,用个人日常账号直接长期跑服务,但没有关闭自动睡眠和自动重启后的登录策略。

第三,没有为终端、浏览器、自动化工具授予"完全磁盘访问""辅助功能""屏幕录制"等权限,导致截图、上传、剪贴板和浏览器控制表现异常。

Mac mini 需要补的系统设置

关键配置文件逐行解析

OpenClaw 的运行逻辑,不只是一个命令把所有事包圆。它更像"网关 + 配置 + 记忆 + 技能 + 渠道插件"的组合。理解这些文件后,后续的大部分报错才有抓手。

文件 / 目录作用建议做法
openclaw.json 或主配置文件声明网关、节点、插件、模型、日志等核心运行参数先从最小可运行配置开始,不要一开始把所有插件堆进去
AGENTS.md定义执行边界、通知规则、工作流和数据分级把它当作"系统宪法",不要写成杂乱备忘录
SOUL.md定义人格、语气、角色边界与写作风格适合放稳定偏好,不适合塞大量流程细节
TOOLS.md记录环境特有映射,例如设备名、目录路径、常用渠道 ID写具体,不写空话,避免把说明书内容重复抄一遍
memory/长期记忆、日记、状态文件需要备份,也需要定期清理无用积累
skills/ 或 ClawHub 安装目录技能说明与外部工具集成点生产环境中优先使用来源明确、版本可追踪的技能
一个可读性较高的最小配置思路
示意性配置片段
{
  "gateway": {
    "bind": "0.0.0.0:3000",
    "publicUrl": "https://your-domain.example.com"
  },
  "models": {
    "default": "openai/gpt-5.4",
    "fallback": "anthropic/claude-sonnet"
  },
  "plugins": {
    "telegram": {
      "enabled": true
    },
    "browser": {
      "enabled": true
    }
  },
  "logs": {
    "level": "info"
  }
}

上面是说明结构的示意性写法。具体字段名和层级应以你当前版本的官方配置模板为准,不建议照抄到生产环境。

配置时最容易忽略的三件事

渠道接入详细配置

对大多数用户来说,OpenClaw 的价值不是在终端里回一句"hello",而是它能不能出现在 Telegram、WhatsApp、Discord、飞书或企业微信里,真正承接消息、任务和提醒。渠道接入决定了你是"装了一个项目",还是"养了一只在线的虾"。

Telegram:最适合个人与跨境团队的起点

Telegram 的优点是 Bot API 成熟、回调机制清晰、跨平台稳定,中文社区教程也最多。缺点是某些地区网络条件和通知触达存在不确定性。

Telegram 接入检查清单
1. 通过 BotFather 创建机器人,拿到 Bot Token
2. 在 OpenClaw 中启用 telegram 插件
3. 配置 webhook 或轮询模式
4. 确认 gateway.publicUrl 能被 Telegram 访问
5. 给机器人发送 /start,观察日志是否收到 update
WhatsApp:体验强,但风控与接入方式更敏感

WhatsApp 往往更像"真实生活入口",因为联系人、家庭群、客户沟通都在那里。但它的代价也最明显:扫码、登录态、封号风险、桥接方式、网页版本变动,都会直接影响稳定性。若是生产环境,必须接受它比 Telegram 更难维护。

企业渠道:飞书、钉钉、Discord、Slack
渠道典型用途接入重点注意事项
飞书内部办公、知识问答、审批提醒事件订阅、机器人权限、企业内网可达性字段签名和权限范围配置不完整时,最容易出现"消息到了但发不回去"
钉钉运营通知、内部群机器人回调地址、加签、安全设置企业安全策略较严,跨网访问要提前验证
Discord开发者社区、线程化协作频道 ID、线程权限、Bot scopes适合技术团队,不适合完全非技术用户起步
Slack国际化团队工作流OAuth scopes、事件订阅、Socket Mode 或公网回调权限粒度细,首次配置容易漏 scope

渠道接入的本质,不是"能发消息就行",而是把身份、权限、回调、登录态和网络可达性同时打通。任何一个环节失真,用户看到的结果都是"机器人怎么又没反应"。

30个高频报错排查手册

OpenClaw 的报错表面很多,底层通常只有几类:进程没起来、配置没读到、渠道没打通、模型不可用、浏览器没权限、节点配对失败。不要见到报错就满网搜字符串,先给故障分层。

现象高概率原因第一步检查
命令可执行,但消息没有回应渠道插件未启用、Webhook 不通、Bot Token 错误先查网关日志,再查渠道平台的回调状态
网页能打开,节点却连不上publicUrl 错误、反代头缺失、Tailscale / NAT 问题从外部网络直接访问公开地址,确认不是只在内网可见
模型调用时报 401 / 403API Key 错误、供应商权限不足、模型名写错单独用最小请求验证密钥和模型是否真的可用
浏览器自动化突然失灵浏览器被系统回收、用户目录损坏、缺少图形权限手动打开浏览器,确认会话和页面是否正常
扫码接入后隔一段时间掉线平台风控、会话失效、机器休眠或网络切换看掉线时间是否与系统睡眠、重启、IP 变化重合
技能存在,但 Agent 不会用SKILL 描述不清、工具不可执行、权限不足先手动执行对应 CLI,再检查技能描述是否过度抽象
一个实用的排查顺序
  1. 第一层,进程层:OpenClaw 是否真的在运行,网关端口是否监听。
  2. 第二层,配置层:读取的是不是你刚改的那份配置,路径是否一致。
  3. 第三层,网络层:回调地址、反向代理、证书、内外网可达性是否正常。
  4. 第四层,插件层:渠道插件是否启用、令牌是否有效、平台侧是否报错。
  5. 第五层,模型层:基础文本请求能否成功,速率限制和余额是否异常。
  6. 第六层,行为层:不是系统坏了,而是规则文件把它限制住了,比如 AGENTS.md 明确禁止某类动作。
部署后建议保留的最小诊断命令
openclaw gateway status
openclaw gateway restart
openclaw help

# 配合日志查看时,重点关注:
# 1) 配置加载路径
# 2) 插件初始化是否成功
# 3) 外部回调是否到达
# 4) 模型调用返回码
# 5) 浏览器 / 节点连接状态
第四部分:大模型选择与配置指南

第十章:大模型市场全景(2026年3月)

进入 2026 年,OpenClaw 用户面对的已不是"有没有模型可用",而是"模型太多,应该怎么配"。同一套 Agent,如果默认模型、备用模型、搜索模型、长文模型、代码模型和本地模型没有分工,再强的能力也会被成本、延迟和不稳定吞掉。

第四部分的核心任务,是把杂乱的模型市场重新整理成可执行的配置方案。判断标准不只包括分数和榜单,更包括四个现实指标:第一,工具调用是否稳定;第二,长上下文是否真能用;第三,价格是否适合高频运行;第四,在中国网络环境和多渠道接入条件下,是否容易落地。

对个人用户

建议采用"双层模型栈":一个强模型负责复杂决策,一个便宜模型负责日常问答、摘要和低风险任务。这样最省钱,也最稳。

默认模型轻重分层先稳后强

对团队用户

建议采用"路由模型栈":按任务类型自动切换供应商,把高价值任务交给高质量模型,把大吞吐任务交给低成本模型。

路由优先控制预算避免单点故障

模型选型最怕一种思路:所有任务都上最贵的那个。这样看起来简单,实际会同时输掉成本、速度和可扩展性。

第十一章:各模型深度评测

今天的可用模型,大致可以分成六类:Anthropic Claude、OpenAI GPT、Google Gemini、DeepSeek、国产闭源模型,以及本地开源模型。它们的差异,不只是"谁更聪明",而是能力结构不同。有的擅长长文推理,有的擅长代码执行,有的成本低到适合批处理,有的则更适合隐私敏感场景。

阵营代表模型优势短板适合 OpenClaw 的位置
AnthropicClaude Sonnet、Claude Opus写作稳、工具调用自然、长文理解强价格偏高,区域可用性与配额需关注复杂任务主模型、长文整理、研究写作
OpenAIGPT-4.1 / GPT-5.x 系列、o 系列通用能力均衡,生态成熟,多模态支持广高阶模型成本不低,任务拆分不当时容易过度调用默认主模型、代码和工具编排核心
GoogleGemini 2.5 Pro / Flash长上下文强,文档与多模态读取出色某些复杂代理动作稳定性仍需版本验证长文检索、资料汇总、附件理解
DeepSeekDeepSeek-V3、DeepSeek-R1价格低,中文表现好,推理性价比高高压并发和复杂工具链场景下需观察稳定性低成本默认模型、中文分析、批量处理
国产闭源豆包、通义千问、文心、混元、Kimi中文生态友好,企业接入和本地合规更容易跨平台文档一致性、国际化工具生态参差不齐国内业务助手、企业知识库、合规场景
本地开源Qwen、Llama、Mistral、GLM 开源系可控、低边际成本、数据不出本地部署与调优门槛高,复杂 Agent 能力通常弱于顶级闭源隐私任务、本地兜底、离线环境
价格带怎么看,才不会被账单教育

可以把市场粗分成三档。第一档是高性能高价格模型,适合关键决策和复杂工作流,常见于 Claude 高阶型号、OpenAI 高阶型号、Gemini Pro 高阶版本。第二档是均衡型模型,适合做默认主力。第三档是低成本高吞吐模型,适合分类、摘要、意图识别、批量整理和兜底。

高性能档
适合 10% 核心任务
用于复杂写作、代码审查、多步工具决策,别拿它做所有日常闲聊。
均衡档
适合 60% 日常任务
默认模型应优先从这档选择,平衡质量、速度和成本。
低成本档
适合 30% 批量任务
适合摘要、改写、分类、RAG 预处理和基础客服。
本地档
适合隐私与兜底
不是为了追求最强,而是为了可控、可离线和边际成本接近零。

第十二章:智能模型路由配置

Claude:写作、研究、复杂指令跟随的强项依旧明显

如果你的 OpenClaw 任务偏长文整理、研究报告、邮件起草、复杂规则执行,Claude 通常仍是高质量选项。它的优势不在单点跑分,而在整体完成度,尤其是上下文保持、文字稳定性、长段落重写和复杂约束下的输出质量。

OpenAI:综合能力最均衡,适合做主干模型

OpenAI 系列模型的优势在于生态成熟,工具调用、结构化输出、多模态支持和开发资料最完整。对于需要"能写、能调工具、能读图、能接生态"的 OpenClaw 部署,OpenAI 往往是默认起点。

Gemini:长上下文和文档理解非常强

Gemini 的亮点是超长上下文和文档吸收能力。面对长 PDF、会议资料、资料包归纳、多附件分析时,它常常比只看短对话分数更有意义。若你的 Agent 常处理文档密集型任务,Gemini 值得放进主力池。

DeepSeek:中文性价比非常高

DeepSeek 的吸引力很直接,便宜,中文强,推理能力在同价位里有竞争力。对于日常助理、信息整理、内容重写、批处理任务,它往往能把单位成本压到很低。问题也同样直接,复杂代理链路里的稳定性,必须自己在生产环境压测。

国产闭源模型:适合国内企业与合规优先场景

豆包、通义千问、文心、混元、Kimi 等模型,在中文办公、企业文档、国内网络环境和本地商务支持上更友好。如果你的 OpenClaw 要接企业微信、飞书、钉钉、内部知识库,这一类模型往往比国际模型更容易落地。

本地模型:不是最强,但可能是最安心

只要场景涉及隐私、内网、离线、固定流程,或者你想把边际成本压到最低,本地模型就有价值。Qwen、Llama、Mistral、GLM 开源系配合 Ollama、vLLM 或 LM Studio,可以承担兜底问答、内部检索摘要、基础流程判断等任务。

模型类型综合质量工具调用稳定性长文本能力中文能力成本印象建议角色
Claude 高阶良好复杂写作、决策、深度研究
OpenAI 主力良好中高默认主模型、通用 Agent
Gemini Pro / Flash中高到高中高很高良好长文档、附件、多模态读取
DeepSeek 系中高中高批处理、中文主力、成本压缩
国产闭源主力中到中高中高很高国内办公、企业知识助手
本地开源 7B-70B中低到中视模型而定低边际隐私兜底、离线场景

这里给的是部署视角下的能力印象,不是学术基准测试排名。真正落地时,应以你的任务样本做 A/B 测试。

第十三章:五大场景模型推荐方案

最容易犯的错误,是把配置写成"有很多模型名的列表",但没有决策逻辑。真正有效的配置,不是堆供应商,而是明确谁是默认、谁是备用、谁负责便宜任务、谁负责长文档、谁负责本地兜底。

方案一:个人用户的双模型配置
示意性配置片段:默认强模型 + 低成本副模型
{
  "models": {
    "default": "anthropic/claude-sonnet",
    "fallback": "deepseek/deepseek-v3",
    "profiles": {
      "writing": "anthropic/claude-sonnet",
      "daily": "deepseek/deepseek-v3"
    }
  },
  "routing": {
    "preferCheapFor": ["summary", "classify", "rewrite"],
    "preferStrongFor": ["research", "tool-use", "longform"]
  }
}
方案二:团队用户的三层模型配置
示意性配置片段:主模型 + 文档模型 + 批处理模型
{
  "models": {
    "default": "openai/gpt-5.4",
    "fallback": "anthropic/claude-sonnet",
    "lowCost": "deepseek/deepseek-v3",
    "longContext": "google/gemini-2.5-pro",
    "local": "ollama/qwen3:14b"
  },
  "routing": {
    "rules": [
      { "match": "attachments|pdf|long-context", "use": "longContext" },
      { "match": "classification|batch|summary", "use": "lowCost" },
      { "match": "private|offline", "use": "local" },
      { "match": "default", "use": "default" }
    ]
  }
}
方案三:国内网络和合规优先配置
示意性配置片段:国产主力 + 国际备用 + 本地兜底
{
  "models": {
    "default": "qwen/qwen-max",
    "fallback": "deepseek/deepseek-v3",
    "backupInternational": "openai/gpt-5.4",
    "local": "ollama/qwen3:8b"
  },
  "policy": {
    "preferDomestic": true,
    "allowInternationalFor": ["coding", "deep-research"],
    "sensitiveTasksUseLocal": true
  }
}

以上示例用于说明思路。不同 OpenClaw 版本的字段名可能不同,实际生产配置请以当前模板和插件文档为准。

第十四章:成本控制与优化技巧

模型路由的价值,不在炫技,而在省钱和降风险。只要你的 Agent 每天处理几十到几百条请求,手动指定模型这件事就已经过时了。好的路由策略会让用户只管提任务,系统自己判断该用哪个模型。

按任务类型路由

写作、摘要、代码、搜索、附件理解分别走不同模型,这是最直接也最稳的方式。

按成本阈值路由

先用低成本模型尝试,置信度不足或任务失败时再升级到强模型。

按敏感级别路由

隐私数据、本地文件、内部文档优先走本地或私有云模型。

路由维度推荐做法原因
请求长度短请求走便宜模型,超长输入走长上下文模型减少大模型上下文浪费
工具复杂度多步工具调用直接上稳定主模型避免便宜模型在中途走偏
失败重试不要同模型盲目重试三次,第二次就切备用供应商减少供应商单点故障影响
敏感内容财务、人事、隐私文件优先本地或私有模型控制数据边界
批量任务拆分后交给低成本模型并发执行压缩单位任务成本
示意性路由逻辑
if task.has_private_files:
    model = "ollama/qwen3:14b"
elif task.contains_many_attachments or task.context_length > 120000:
    model = "google/gemini-2.5-pro"
elif task.requires_multi_tool_use or task.is_high_value:
    model = "openai/gpt-5.4"
elif task.type in ["summary", "classify", "rewrite", "tagging"]:
    model = "deepseek/deepseek-v3"
else:
    model = "anthropic/claude-sonnet"

路由设计的底线:

第一,不要让同一个任务在路由器和 Agent 提示词里互相打架。

第二,不要把所有失败都归因于模型,很多时候是工具权限、网络或上下文切分出了问题。

第三,路由规则要可观察。至少记录"这次为什么选了这个模型",否则后续无法优化。

第十四章A:国外模型接入方式--OpenRouter 聚合 API

场景一:个人全能助理

推荐组合:OpenAI 主模型 + DeepSeek 日常副模型

适用任务:聊天、日程整理、搜索总结、渠道回复、轻量自动化。

原因:综合能力稳,成本可控,适合作为第一套可长期运行的配置。

场景二:内容创作与研究写作

推荐组合:Claude 主模型 + Gemini 文档模型

适用任务:长文重写、报告、采访整理、论文辅助、资料归纳。

原因:前者负责质量,后者负责吞长文档,组合效率很高。

场景三:代码助手与技术运营

推荐组合:OpenAI 或 Claude 主模型 + 本地模型兜底

适用任务:代码解释、脚本生成、日志排错、仓库问答。

原因:顶级闭源模型负责复杂推理,本地模型承担低风险内部查询。

场景四:企业知识库与国内办公流

推荐组合:通义 / 豆包 / 千问主模型 + DeepSeek 低成本层

适用任务:飞书、钉钉、企业微信、SOP 问答、内部材料总结。

原因:中文表现与本地商务支持更好,合规与接入成本更低。

场景五:隐私优先与离线环境

推荐组合:Qwen / Llama 本地主模型 + 云端高阶模型作为人工触发补强

适用任务:私有文档、内网问答、离线批处理、敏感资料整理。

原因:平时本地跑,确实需要高质量时再手动升级,边界清楚。

最好的模型方案,不是排行榜第一,而是能连续三个月稳定运行、账单可接受、出问题时你知道怎么救的那一套。

第十四章B:国内模型接入方式--Coding Plan计划

很多团队不是被模型单价拖垮,而是被错误使用方式拖垮。比如,所有消息都走最强模型;每次请求都带上过长历史;失败后无脑重试;明明是摘要任务却用推理旗舰;低价值通知也调用完整 Agent 链路。成本爆炸,通常是系统设计问题,不是供应商问题。

五个最有效的优化动作
优化点错误做法推荐做法预期收益
默认模型全站固定使用最强模型按任务级别分层,设置默认与升级条件直接降低总账单
上下文管理每次都附带完整聊天历史摘要历史,只保留必要上下文减少 Token 浪费、降低延迟
工具调用任何请求都走全工具链先判断是否真的需要工具减少失败率和冗余步骤
长文处理整包原文直接丢给贵模型先切片、提纲化,再交高阶模型总结质量更稳,成本更低
本地模型完全不用本地模型把隐私和低价值任务转移到本地压缩云端调用量
预算友好型实践清单
1. 默认使用均衡模型
2. 检测到以下条件才升级:
   - 多步工具调用
   - 长文高质量改写
   - 高价值用户请求
   - 复杂代码/数据分析
3. 重复任务优先走缓存
4. 私密资料优先走本地模型
5. 每周复盘:
   - 各模型调用次数
   - 平均响应时间
   - 失败率
   - 单任务平均成本

如果只记一个原则,那就是:把"模型最强"改成"系统最优"。Agent 时代,决定上限的是模型,决定利润和可持续性的是调度。

本轮回调说明