1. 项目概述从OpenClaw的账单之痛到CheapClaw的诞生如果你和我一样曾经看着OpenClaw的API调用账单心头会不自觉地一紧——那种感觉就像看着水龙头没关紧水表在飞速旋转。OpenClaw确实强大它构建了一个多智能体协作的框架让不同的AI模型Bot能够像一支训练有素的团队一样工作一个负责规划强模型一个负责执行弱模型。但问题也随之而来当执行过程中出现意外偏离了最初的规划时那个负责执行的“弱模型”往往就懵了因为它有限的上下文窗口里塞满了历史对话却缺乏应对新情况的“临场应变”能力。结果就是任务卡壳你不得不重新调用昂贵的“强模型”来收拾残局成本就在这一次次的“救火”中悄然攀升。CheapClaw正是为了解决这个痛点而生的。它不是一个试图用最少代码复刻OpenClaw全部功能的项目其核心目标非常明确在保留OpenClaw大部分核心功能的前提下通过一种更聪明的模型调度策略显著降低处理复杂、长流程任务时的成本。简单来说它让“强模型”和“弱模型”的协作不再是简单的“计划-执行”两段式而是变成了一个可以动态调整、定期刷新的循环。想象一下你有一个需要阅读500份PDF并汇总成表格的巨型任务。传统的OpenClaw模式可能让强模型如GPT-4制定一个宏伟的50步计划然后交给弱模型如GPT-3.5去一步步执行。走到第15步时如果遇到一份格式怪异的PDF弱模型可能就卡住了因为它只记得最初的计划却无法基于当前困境重新思考。CheapClaw的做法是每执行10步或20步就主动“剪断”之前的对话历史让强模型基于最新的任务进展重新评估并输出一个更新的、更聚焦的短期计划再交给弱模型继续。这样弱模型始终在一个清爽、简短的上下文窗口里工作而强模型的介入也变得更有节奏、更具性价比。所以CheapClaw的定位非常清晰对于简单的“你好”对话它的工作流可能显得有点“重”但对于真正复杂、耗时的任务它就是你控制成本、提升效率的利器。它基于infiagentSDK构建继承了其多智能体编排的能力并在此基础上增加了对成本敏感场景的深度优化。2. 核心架构与设计思路拆解要理解CheapClaw如何省钱我们必须深入其核心设计理念。这不仅仅是换用更便宜的模型那么简单而是一套关于“上下文管理”和“任务分解”的系统工程。2.1 混合执行引擎强模型与弱模型的共舞OpenClaw的“强模型规划弱模型执行”模式本身是个好主意但它假设执行路径是线性的、可预测的。现实任务往往充满变数。CheapClaw的关键创新在于引入了阶段性思考和历史截断机制。为什么是“阶段性”而不是“持续监控”持续让强模型监控每一步执行成本太高违背了省钱的初衷。阶段性思考是在成本与效果之间寻找平衡点。例如设置每20步为一个阶段。弱模型执行完20步后系统会将这20步的关键结果摘要而非全部原始对话连同最新的任务目标一并提交给强模型。强模型据此重新分析现状可能发现原计划的后半部分已经不合时宜于是生成一个新的、更简短的21-40步计划。这个过程我称之为“计划刷新”。历史截断的技术实现与收益infiagentSDK提供了底层支持允许在Agent循环中直接操作对话历史。CheapClaw利用这一点在阶段切换时将旧的、冗长的对话历史从弱模型的上下文中彻底移除只保留最精华的任务状态描述和新的阶段计划。注意这里的“截断”不是删除日志而是不让这些历史信息占用模型宝贵的Token限额。完整的交互日志依然保存在系统内存或数据库中以供追溯但不会作为上下文输入给模型。这么做的直接收益是双重的降低成本弱模型通常是按Token计费的每次处理的上下文长度大幅缩短直接减少了Token消耗。提升稳定性弱模型摆脱了历史包袱更能专注于当前阶段的指令减少了因上下文过长导致的注意力分散或理解偏差。2.2 分层记忆系统让专业的人管专业的事一个常见的多智能体系统陷阱是“记忆污染”。比如一个正在帮你写代码的Agent不应该被之前讨论晚餐食谱的对话所干扰。CheapClaw采用了清晰的分层记忆设计监督层记忆位于每个Bot的顶层只关心与用户交互相关的记忆。例如用户偏好、长期任务目标、用户身份信息等。这部分记忆是持久且高层次的。任务层记忆当监督层将一个复杂任务如“写研究报告”下发给一个特定的Agent系统如“学术写作Agent系统”时该系统会创建自己独立的任务记忆。这个记忆只包含与该任务相关的所有子步骤、中间产物、参考资料等。执行层记忆在Agent系统内部不同的子Agent如“资料搜集Agent”、“大纲生成Agent”、“润色Agent”又有自己更临时的、专注于当前操作步骤的记忆。这种分层结构确保了记忆的隔离性和专业性。写报告的Agent不会读到处理邮件的Agent产生的杂乱信息每个“工作线程”都能在干净的环境下高效运行。2.3 技能与自定义Agent系统的扩展性CheapClaw不仅是一个运行器更是一个平台。技能你可以为Bot定义可复用的“技能”比如“总结网页内容”、“翻译文本”、“生成图表描述”。这些技能可以被多阶段、有条件地触发和组合。自定义Agent系统这是CheapClaw真正强大的地方。如果你在某个垂直领域如法律文书分析、学术论文检索、社交媒体监控有特定需求你可以基于infiagent的规范构建一整套专属的Agent工作流然后打包成ZIP文件“安装”到特定的Bot上。这意味着你的CheapClaw实例可以从一个通用助手进化成一个拥有专业团队的“数字员工中心”。实操心得在构建自定义Agent系统时务必警惕一个“坑”避免引入human_in_loop这类需要人工交互的工具。如果你的目标是自动化后台任务这类工具会导致整个流程挂起等待永远不会到来的人工输入从而使得“后台执行”变得不可能。在集成第三方Agent系统前一定要检查其工具列表。3. 从零开始部署与深度配置指南理论讲完我们进入实战。假设你有一台云服务器或本地开发机我们将完成一次完整的CheapClaw部署和配置。3.1 环境准备与安装CheapClaw是一个Python项目安装本身很简单但依赖项需要特别注意。步骤一安装CheapClaw首选从PyPI安装这是最干净的方式。pip install -U cheapclaw如果你想从源码安装以便于调试或贡献git clone https://github.com/polyuiislab/CheapClaw.git cd CheapClaw pip install -U -e .步骤二处理关键依赖——浏览器运行时这是新手最容易踩坑的地方。CheapClaw依赖的infiagent其内部工具如crawl4ai用于网页抓取需要真实的浏览器环境Chromium来渲染页面。因此在首次部署的机器上必须执行python -m playwright install --with-deps chromium这条命令会下载Chromium浏览器及其所有系统依赖如字体库、共享库等。如果你在本地桌面环境也可以尝试运行crawl4ai-setup但它本质上也是调用Playwright。步骤三验证安装安装完成后强烈建议运行crawl4ai-doctor这个命令会检查所有必要的组件浏览器、驱动、库是否就位。如果看到“All checks passed”之类的信息说明环境OK。如果跳过这一步后续任何涉及网页访问、自动化操作的任务都会失败并报出关于“找不到浏览器”或“无法启动”的晦涩错误。3.2 初始化配置与核心概念解析安装完成后不要急着启动。我们先理解它的文件结构和配置逻辑。初始化与交互式配置运行以下命令来生成配置文件并进行交互式设置cheapclaw init cheapclaw config --interactiveinit命令会在默认路径~/cheapclaw/下创建核心配置文件fleet.manifest.json。config --interactive则会引导你填写最重要的部分。关键配置项详解交互式配置中最核心的是LLM大语言模型设置。即使你只有一个API密钥和一个服务地址也足够了。llm.base_url: 你的LLM API服务地址。例如如果你使用OpenAI兼容的API服务可能是https://api.openai.com/v1如果是本地部署的Ollama则是http://localhost:11434/v1。llm.api_key: 对应的API密钥。llm.model:这是最容易填错的一项。这里的格式规则是API格式前缀/模型名称。为什么需要前缀因为不同的服务提供商如OpenRouter、Together AI可能支持多种API协议如OpenAI格式、Anthropic格式。前缀告诉CheapClaw底层SDK应该使用哪种通信格式来调用这个模型。如何填写参考你的服务商文档。例如在OpenRouter上使用GPT-4o且选择OpenAI格式调用则填openai/gpt-4o使用本地Ollama的llama3.2模型Ollama默认提供OpenAI兼容接口则填openai/llama3.2使用Google Gemini API则填gemini/gemini-1.5-flash(假设服务商将前缀映射为gemini)默认示例CheapClaw给的例子是gemini-3-flash这可能是一个简写或特定配置。最保险的方法是查阅infiagent项目关于模型配置的文档或者直接使用openai/前缀搭配你熟悉的模型名进行尝试。配置完成后所有Bot默认都会使用这个共享的llm_config.yaml。但你也可以在Bot级别或Agent系统级别覆盖这个配置实现混合调度——比如让“思考模型”用强一点的GPT-4让“执行模型”用便宜的Claude Haiku。3.3 启动、验证与Dashboard使用首次启动与验证路径我强烈推荐按以下安全路径进行避免多线作战创建本地测试Bot首先我们只创建一个localweb类型的Bot。这个Bot不需要任何第三方凭证纯粹用于本地功能验证。cheapclaw add-bot交互过程中选择localweb作为频道类型并给它起个ID比如my_test_bot。启动服务cheapclaw up这个命令会启动CheapClaw的后台服务以及Web控制台。访问Dashboard打开浏览器访问http://127.0.0.1:8787/dashboard。你应该能看到Dashboard界面并看到你刚创建的my_test_bot处于“未启动”或“已停止”状态。启动Bot并测试在Dashboard上找到你的Bot点击“启动”。然后在Dashboard的“本地聊天”区域选择这个Bot发送一句“你好”。如果一切正常你应该能收到回复。注意第一次回复可能会比较慢因为系统需要加载模型、初始化Agent。后续交互会快很多。Dashboard详解Dashboard是CheapClaw的指挥中心功能非常直观Bot列表与状态管理查看所有Bot的ID、名称、频道类型、运行状态运行中、已停止、错误并可以一键启动、停止、重启。舰队配置编辑可以直接在网页上修改fleet.manifest.json无需手动找文件。本地网页聊天最直接的测试工具可以同时拉多个localwebBot进一个群聊通过bot_id来指定由哪个Bot响应。对话历史查看回顾与每个Bot的完整对话记录。运行时状态管理比命令行更直观地管理一些运行时的细节。将Dashboard暴露给局域网如果你想在服务器上部署并通过手机或同一网络下的其他电脑访问Dashboard需要在启动时指定主机和端口cheapclaw up --web-host 0.0.0.0 --web-port 8787然后你就可以通过http://你的服务器IP:8787/dashboard来访问了。请确保服务器的防火墙开放了8787端口。4. 连接外部通信渠道Telegram与飞书实战一旦确认本地Web聊天工作正常就可以连接真正的消息平台了。这里以Telegram和飞书为例讲解连接过程中的关键点和避坑指南。4.1 连接Telegram Bot前期准备在Telegram上找到BotFather创建一个新的Bot获取bot_token一串类似123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ的字符。可选获取allowed_chats。如果你希望Bot只响应特定群组或用户的消息需要先向Bot发送一条消息然后访问https://api.telegram.org/bot你的bot_token/getUpdates来获取聊天ID。配置与启动你可以通过Dashboard的“添加Bot”功能或者在命令行运行cheapclaw add-bot选择telegram频道类型。telegram.bot_token: 填入从BotFather获取的token。telegram.allowed_chats: 可选填入你允许的聊天ID多个ID用逗号分隔。如果不填则Bot会响应所有它能收到的消息。启动Botcheapclaw start-bot --bot-id your_telegram_bot_id --prepare-first--prepare-first参数会在启动前确保Bot的运行时环境如模型加载、配置读取已准备就绪。常见问题排查错误404 getUpdates这几乎总是意味着bot_token填写错误。请仔细检查确保没有多余的空格或换行。Token的格式是数字:字母数字组合。Bot无响应首先在Dashboard上确认该Bot的状态是“运行中”。然后在Telegram中确保你已经/start了这个Bot。最后检查服务器网络是否能正常访问Telegram的API某些网络环境可能需要配置。消息重复响应这可能是由于Webhook和长轮询Polling模式冲突。CheapClaw默认使用Polling模式。如果你之前用其他框架以Webhook模式配置过同一个Bot需要先在BotFather处/setwebhook一个空的URL来清除Webhook。4.2 连接飞书FeishuBot飞书的配置稍微复杂一点因为它涉及企业自建应用。前期准备登录 飞书开放平台 创建一家企业如果还没有。在开发者后台创建“企业自建应用”。在应用详情页找到“凭证与基础信息”获取app_id和app_secret。在“事件订阅”中启用并配置“接收消息v2.0”权限。CheapClaw使用长连接模式通常不需要配置请求地址URL但需要确保应用有相应的消息接收权限。在“权限管理”中为应用添加im:message接收与发送单聊、群组消息等必要的权限范围并发布版本、等待审核通过通常自用应用审核很快。配置与启动在添加Bot时选择feishu频道类型。feishu.app_id: 填入你的应用ID。feishu.app_secret: 填入你的应用密钥。启动命令与Telegram类似。网络与代理问题如果你的服务器环境需要通过代理访问外网而飞书服务器在国内可能会遇到连接问题。你需要确保CheapClaw进程能正确读取并使用你设定的代理配置。这通常需要在系统环境变量或CheapClaw的配置文件中进行设置而不是想当然地认为“服务器有代理就行”。实操心得一个快速的测试方法是在运行CheapClaw的服务器上用curl命令尝试访问一个国内网站如www.baidu.com和一个国外网站看看代理是否生效。如果CheapClaw连接飞书失败可以尝试暂时关闭代理或配置直连规则进行测试。5. 高级功能自定义Agent系统的集成与管理CheapClaw的基础功能已经很强大了但它的上限在于你可以为其“安装”专业的大脑——自定义Agent系统。5.1 什么是自定义Agent系统你可以把它理解为一个“技能包”或“专家团队”的完整工作流定义。它不仅仅是一两个工具而是一套包含多个Agent角色、工具集、内部协调逻辑的完整程序。例如一个“学术论文助手”系统可能包含文献检索Agent、摘要生成Agent、参考文献格式化Agent和论文结构建议Agent它们按照一定规则协作。5.2 如何安装假设你已经按照infiagent的规范开发并打包好了一个Agent系统一个ZIP文件。安装到单个Bot私有化cheapclaw bot-agent-system add /path/to/your_agent_system.zip --bot-id my_special_bot --reload-after--bot-id: 指定安装到哪个Bot。这个系统将只对该Bot可见和可用。--reload-after: 安装完成后立即重启该Bot使新系统生效。这是一个非常方便的参数。安装到全局共享资产cheapclaw bot-agent-system add /path/to/your_agent_system.zip --global这样安装后所有Bot都可以在它们的配置中选择使用这个系统。适用于通用型的Agent系统。5.3 安装后的管理与可见性系统可见性CheapClaw的Dashboard和Bot只会显示当前已加载到其运行时环境中的Agent系统。infiagentSDK内置了一些基础系统但CheapClaw不会自动注入它们。你必须通过prepare流程或安装命令显式地将系统“准备”到Bot的运行时目录下它才会出现。持久化通过CLI安装的系统会被复制到Bot的运行时目录如~/cheapclaw/runtime/my_bot/agent_systems/下。后续执行cheapclaw prepare或cheapclaw reload-bot --prepare-first时这些已安装的系统会被保留不会被覆盖。如何选择使用在Dashboard上编辑Bot的配置或者在fleet.manifest.json中为该Bot指定agent_systems列表将你安装的系统ID添加进去。当用户向该Bot发起一个复杂任务时监督层就会根据任务类型调度对应的Agent系统来执行。6. 运维、监控与故障排查实录将CheapClaw用于实际工作后日常的运维和问题排查是必不可少的环节。6.1 常用运维命令速查除了前面提到的这里整理一个更全面的清单命令功能描述常用场景cheapclaw status查看所有Bot和Web服务的整体状态快速健康检查cheapclaw status --bot-id bot_1查看指定Bot的详细状态模型、系统加载等深度检查某个Botcheapclaw logs --bot-id bot_1查看指定Bot的最新日志默认尾部实时调试查看错误输出cheapclaw logs --bot-id bot_1 --lines 100查看指定Bot的最后100行日志查看近期历史cheapclaw stop停止所有CheapClaw服务后台进程和Bot安全关闭准备维护cheapclaw restart重启所有服务应用配置变更后cheapclaw web-status仅查看Dashboard Web服务的状态排查网页无法访问问题6.2 典型问题排查流程当遇到问题尤其是外部频道Telegram/Feishu无响应时请遵循以下“回归测试”流程由内向外定位问题第一步检查核心服务运行cheapclaw status确保所有服务进程都在运行。访问http://127.0.0.1:8787/dashboard看Dashboard是否能正常打开。如果打不开问题出在Web服务或端口冲突。第二步验证LLM配置在Dashboard上使用localwebBot发送一条简单消息如“ping”。如果localwebBot也无响应或报错问题极大概率出在LLM配置上。检查~/cheapclaw/runtime/config/llm_config.yaml中的base_url、api_key和model格式是否正确。可以尝试用curl命令直接调用你的LLM API验证连通性。第三步检查特定Bot的运行时如果localweb正常但某个Telegram Bot不正常。运行cheapclaw logs --bot-id your_telegram_bot。查看日志末尾是否有明显的错误信息如“Invalid token”、“Connection refused”、“Timeout”。根据错误信息针对性解决如修正Token、检查网络代理。第四步检查频道凭证与权限Telegram确认Bot是否被用户/start。确认allowed_chats是否设置错误导致消息被过滤。飞书确认应用已通过审核且已发布新版本。在开放平台检查应用的“权限管理”确保已添加并生效了消息接收发送权限。检查app_id和app_secret是否对应。第五步网络与防火墙确认运行CheapClaw的服务器可以访问目标频道APITelegram API、飞书服务器。如果使用代理确认CheapClaw进程的代理环境变量如HTTP_PROXY,HTTPS_PROXY已正确设置。6.3 配置文件与目录结构维护理解运行时目录结构有助于手动排查和备份~/cheapclaw/ ├── fleet.manifest.json # 舰队主配置定义所有Bot ├── runtime/ # 运行时目录每个Bot独立子目录 │ ├── config/ │ │ └── llm_config.yaml # 共享的LLM配置 │ ├── bot_telegram_1/ # 一个Bot的独立运行时 │ │ ├── cheapclaw/ │ │ │ ├── config/ │ │ │ │ └── app_config.json # 该Bot的应用配置如watchdog间隔 │ │ │ └── system-add.md # 该Bot的附加系统指令和记忆 │ │ └── agent_systems/ # 安装到此Bot的自定义Agent系统 │ └── bot_localweb_1/ └── ...重要注意事项修改配置前先停止服务在手动编辑fleet.manifest.json或任何runtime/下的文件前务必先运行cheapclaw stop。否则运行中的进程可能不会读取你的更改甚至可能因文件被修改而出现错误。system-add.md是安全的你可以放心在这个文件中添加你自己的提示词或角色设定。CheapClaw只会更新文件中它自己管理的保留区块通常有特定标记不会覆盖你写在其他区域的内容。你可以利用这个文件为Bot注入长期记忆或特定领域的知识。Watchdog间隔默认的watchdog_interval_sec是86400秒24小时这意味着它每天才检查一次系统健康。对于生产环境如果你需要更及时地重启崩溃的进程可以到对应Bot的app_config.json里调小这个值比如设为36001小时。但要注意过于频繁的检查也可能产生不必要的开销。7. 性能调优与成本控制实践部署稳定后我们最终要回归初心如何让CheapClaw更“Cheap”这里分享一些实战中的调优经验。7.1 模型策略混合配置这是省钱的核心。你不需要所有环节都用最好的模型。思考模型 vs. 执行模型在Agent系统的最底层配置中你可以为不同的子Agent指定不同的模型。通常“规划者”、“决策者”这类角色需要更强的推理能力可以配置为gpt-4o或claude-3-5-sonnet。而“执行者”、“代码编写者”、“文本总结者”这类角色可以配置为gpt-3.5-turbo、claude-3-haiku或gemini-1.5-flash这类性价比更高的模型。图像阅读与压缩模型如果任务涉及图片理解你可以专门为“图像阅读”功能配置一个模型如gpt-4o-mini或claude-3-haiku的视觉版。对于“文本压缩”或“摘要生成”步骤可以指定一个更小、更快的模型。这些都在Agent系统的YAML配置文件中进行定义。本地模型集成对于某些对延迟要求不高、但希望零API成本的任务可以考虑集成本地模型如通过Ollama部署的llama3.2、qwen2.5。将一些简单的文本处理、格式转换任务交给本地模型执行能极大降低云API调用费用。只需在llm_config.yaml中为本地模型配置一个条目并将其base_url指向你的Ollama服务地址即可。7.2 上下文与阶段长度优化CheapClaw的“历史截断”机制是省Token的关键但截断的“步长”需要根据任务类型调整。对于流程稳定、偏差小的任务比如“按固定模板处理100份简历”可以将阶段步长设置得大一些比如50步甚至100步。因为任务模式固定弱模型不太容易偏离轨道减少强模型的介入频率可以节省成本。对于探索性强、易发散的任务比如“研究某个新兴技术并撰写报告”阶段步长应该设小比如10步或15步。这样强模型可以更频繁地“纠偏”和“重新聚焦”防止弱模型在错误的方向上浪费大量Token。调整方法这个参数通常在自定义Agent系统的配置文件中定义或者作为Bot的全局参数。你需要理解你集成的Agent系统的工作流程找到控制“规划周期”或“反思间隔”的配置项。7.3 监控与账单分析省钱不能靠感觉要靠数据。利用日志粗略估算CheapClaw和底层infiagent的日志通常会输出每次调用模型的名称和Token使用情况输入/输出。你可以编写简单的脚本定期分析日志文件统计不同模型的调用次数和Token消耗形成趋势图。服务商账单明细定期查看你的OpenAI、Anthropic、Google AI等平台的账单详情。对比使用CheapClaw前后在处理同类复杂任务时总费用和“强模型”调用费用的变化。理想情况下总费用应下降且强模型费用占比应降低。效果评估省钱不能以牺牲质量为代价。定期抽样检查CheapClaw处理的任务结果与直接用强模型处理的结果进行对比确保在成本下降的同时任务完成的质量没有不可接受的下降。这通常需要一个主观的质量评估标准。我个人在将一个每周运行的竞品分析报告任务迁移到CheapClaw后通过将执行模型从GPT-4换为GPT-3.5-Turbo并设置每15步进行一次计划刷新使得该任务的月度API成本降低了约65%而报告质量经过团队评审认为关键信息提取和结论部分并无显著差异仅在部分语言的丰富性上略有下降这在可接受范围内。这个实践让我确信对于结构化的长文本处理任务CheapClaw的混合执行策略具有巨大的成本优势。