1. 项目概述这不是“安装教程”而是一份给智能体新手的生存指南OpenClaw 这个名字最近在智能体开发圈里出现频率越来越高但很多人点开 GitHub 仓库第一眼看到requirements.txt里密密麻麻的依赖、docker-compose.yml里七八个服务、还有文档里动辄“需部署向量数据库LLM推理集群工作流调度中心”的描述直接关掉页面——不是不想学是怕一上来就花几百块买 GPU 实例、配环境配到怀疑人生、最后连个“Hello World”都没跑出来。我试过三次第一次用云服务器从零搭三天没跑通 RAG 检索链第二次买了某厂商的智能体平台年费套餐结果发现它把 OpenClaw 封装成黑盒连 prompt 模板都改不了第三次才真正摸清门道——OpenClaw 的核心设计哲学是“可拆卸式智能体架构”。它不强制你堆硬件也不绑架你用特定云服务它的最小可行单元MVP甚至不需要 GPU、不依赖外部 API、不启动 Docker只要一台能跑 Python 的旧笔记本20 分钟内就能让一个带记忆、能调用工具、会自主思考的智能体在本地活起来。这门“省钱第一课”说的就是这个 MVP 路径。它不教你怎么部署高并发生产环境而是帮你绕过所有前置成本陷阱直击 OpenClaw 最本质的能力层指令解析 → 工具路由 → 响应生成 → 状态留存。你不需要懂 LangChain不用研究 LlamaIndex 的 chunk 策略甚至可以完全跳过模型微调——因为 OpenClaw 默认支持ollama本地运行的轻量模型比如phi3:3.8b或qwen2:1.5b这些模型在 16GB 内存的 MacBook Air 上实测内存占用稳定在 3.2GB 以内CPU 温度峰值不超过 72℃。适合谁三类人立刻能用上刚学完 Python 基础想亲手造个“能查天气记待办读邮件”的个人助理但钱包比代码还干净的学生党做产品或运营的非技术岗需要快速验证一个智能体想法是否成立拒绝被工程师排期卡住的决策者已有业务系统比如内部 CRM 或 OA想给老系统加个“自然语言操作入口”但 IT 部门明确表示“不批新云预算”的落地执行者。关键不在“省多少钱”而在“省下第一个 24 小时”。这 24 小时是你决定继续深挖还是默默删掉仓库的分水岭。2. 核心设计逻辑拆解为什么“0 成本”不是营销话术而是架构使然OpenClaw 的“0 成本”不是靠阉割功能换来的妥协而是基于对当前智能体落地瓶颈的精准判断后做的三层反共识设计。我把它叫作“三不原则”不强耦合模型、不硬绑定基础设施、不预设交互形态。这三点直接决定了你能不能真正在没有一分钱投入的情况下跑通第一个端到端流程。2.1 不强耦合模型模型即插即用而非架构基石绝大多数智能体框架比如早期的 AutoGen、LangChain Agent把大模型当作不可替换的“心脏”所有逻辑围绕模型 API 展开你换模型就得重写提示词工程、重调 temperature、重测工具调用准确率。OpenClaw 反其道而行之它把模型抽象成一个标准接口ModelProvider只要实现generate(prompt: str) - str和stream_generate(prompt: str) - Iterator[str]这两个方法任何东西都能当模型用——包括你自己写的规则引擎、一个 Excel 公式、甚至一段正则表达式。提示官方默认集成的OllamaModelProvider之所以能实现“0 成本”是因为 Ollama 本身就是一个纯本地模型运行时。它不走网络请求不产生 token 费用不依赖厂商 API Key。你下载一个phi3:3.8b模型仅 2.1GBollama run phi3启动后OpenClaw 就能通过 HTTP localhost 调用它整个链路全程离线。更关键的是OpenClaw 的工具调用协议Tool Calling Protocol是模型无关的。它不依赖模型原生支持 function calling比如 GPT-4 的 JSON mode而是用自己实现的轻量级解析器先让模型输出一段结构化文本如TOOL: search_web QUERY: 2024 年最火的开源智能体框架再由 OpenClaw 的ToolRouter模块提取参数并分发。这意味着哪怕你用的是gemma:2b这种根本不支持 function calling 的小模型只要它能按约定格式输出文本OpenClaw 就能驱动它完成完整工具链。实测对比在同等硬件MacBook Pro M1, 16GB RAM上用phi3:3.8b运行一个带“查维基百科计算日期差生成 Markdown 报告”三工具的智能体单次响应平均耗时 4.7 秒显存占用为 0因为没用 GPU。而如果强行接入 OpenAI API光是网络延迟token 计费跨域鉴权就把“0 成本”和“实时性”两个目标全干掉了。2.2 不硬绑定基础设施状态存储与工具执行全部可降级很多框架一上来就要求你装 PostgreSQL、Redis、Elasticsearch理由是“智能体需要持久化记忆、需要向量检索、需要异步任务队列”。OpenClaw 的回答很干脆如果你不需要就别装。它把所有基础设施依赖都设计成“可选插件”且每个插件都自带降级方案。记忆Memory模块默认使用FileBasedMemory所有对话历史、工具调用记录、中间状态全存成 JSON 文件路径可自定义比如./memory/session_abc123.json。你删掉这个文件智能体就“失忆”你复制另一个文件过去它就“继承记忆”。没有数据库迁移、没有 schema 设计、没有连接池配置。工具Tool执行模块工具代码本身是纯 Python 函数OpenClaw 只负责解析调用指令、传参、捕获返回值。你写一个def get_weather(city: str) - str:它就能调你写一个def send_email(to: str, content: str) - bool:它也能调。工具的执行环境就是你的本地 Python 解释器不需要额外起服务、不需要注册到中心化工具市场。工作流Workflow引擎不依赖 Airflow 或 Prefect。OpenClaw 的 workflow 是用 YAML 定义的 DAG有向无环图但解析器极其简单只认steps、depends_on、timeout三个字段。一个三步工作流的 YAML 文件不到 20 行用 Python 的yaml.safe_load()直接读取连 schema 校验都省了。这种设计带来的直接好处是你第一天跑 demo用的是文件存储 同步工具调用 YAML 工作流第三十天要上生产再平滑切换到 Redis 异步 Celery PostgreSQL所有业务逻辑代码prompt、tool 函数、workflow 定义一行都不用改。成本是渐进式增加的不是起步就交“入场券”。2.3 不预设交互形态CLI 即界面无需前端开发很多智能体项目一上来就给你一个炫酷的 Web UI然后告诉你“先 npm install再 yarn dev最后打开 http://localhost:3000”。OpenClaw 的默认交互方式是命令行CLI。openclaw run --config config.yaml这条命令执行后你面对的就是一个纯文本交互终端输入自然语言它输出思考过程工具调用日志最终回复。这看似简陋实则极度务实。原因有三零构建成本不用配 Webpack、不用处理 CORS、不用解决 WebSocket 连接失败问题。CLI 是操作系统原生支持的只要 Python 能跑它就能交互。调试信息全量可见Web UI 为了用户体验会隐藏大量中间态比如模型原始输出、tool 参数解析过程、错误堆栈。CLI 下你可以用--verbose参数看到每一层的输入输出定位问题快得像看日志。无缝对接现有工作流你能把openclaw run命令嵌进 Shell 脚本、放进 Cron 定时任务、接进 Jenkins 流水线、甚至用subprocess.Popen在你的旧系统里调用它。它不是一个“独立应用”而是一个可编程的智能体 SDK。我自己就用这套 CLI 模式给公司内部的 Jira 系统加了个“自然语言创建工单”功能运维同事在终端里敲openclaw jira 帮我建个工单标题是‘升级监控告警阈值’描述是把 CPU 使用率告警从 90% 改成 85%优先级高OpenClaw 解析出意图、调用 Jira REST API 创建工单、返回工单号。整个过程没动 Jira 一行代码也没申请任何新权限——因为调用 API 的 token就存在本地 config.yaml 里。3. 实操全流程从空目录到第一个可交互智能体手把手拆解每一步现在我们进入最硬核的部分不跳过任何一个环节不假设任何前置知识从一个空文件夹开始带你跑通第一个 OpenClaw 智能体。全程使用 macOS / Linux 环境Windows 用户请用 WSL2不要用 CMD 或 PowerShell避免路径和权限问题。所有命令均可直接复制粘贴我会标注每一行的真实作用而不是只甩命令让你盲打。3.1 环境准备只装 3 个东西且全是免费开源你不需要 Python 最新版不需要 Conda不需要 Docker Desktop。只需要确认系统已安装Python 3.9macOS 自带 Python 3.9Linux 发行版apt install python3即可Gitxcode-select --installon Mac,apt install giton UbuntuOllama官网下载 dmg 或 deb 包或curl -fsSL https://ollama.com/install.sh | sh注意Ollama 是唯一必须安装的“外部依赖”但它不是 OpenClaw 的一部分而是你本地的模型运行时。它不联网、不上传数据、不收集日志所有模型文件都存在你本地~/.ollama/models/目录下完全可控。验证安装python3 --version # 应输出 3.9.x 或更高 git --version # 应输出 2.30 ollama --version # 应输出 0.1.30如果ollama --version报错说明 Ollama 服务没启动。macOS 上去 Launchpad 找 “Ollama” App 点开即可Linux 上执行systemctl --user start ollama。接下来创建项目目录并初始化mkdir openclaw-first cd openclaw-first git clone https://github.com/ai-forever/openclaw.git cd openclaw # 注意不要 pip installOpenClaw 的推荐方式是直接运行源码为什么不用pip install openclaw因为官方 PyPI 包是面向生产环境的精简版去掉了所有 demo 和本地开发依赖。而我们要跑的是最简 demo必须用源码里的examples/quickstart。3.2 运行第一个智能体5 分钟内看到“思考过程”OpenClaw 源码里有个精心设计的quickstart示例它只做一件事让你亲眼看到智能体如何“思考”。它不连任何外部 API不读任何文件所有逻辑都在内存里完成。进入示例目录cd examples/quickstart这里有两个核心文件config.yaml定义智能体的“人设”、可用工具、记忆配置tools.py定义两个极简工具get_time()返回当前时间calculate(expression)计算数学表达式打开config.yaml你会看到agent: name: QuickStartAgent description: 一个能告诉你时间、能帮你算数的智能体 model_provider: ollama # 关键指定用本地 Ollama model_name: phi3:3.8b # 指定模型名 memory: type: file # 用文件存储记忆 path: ./memory.json # 记忆文件路径 tools: - name: get_time description: 获取当前系统时间 module: tools.get_time - name: calculate description: 计算数学表达式如 22*3 module: tools.calculate现在执行最关键的一步拉取并运行模型。注意这一步是“0 成本”的物理基础——你下载的模型只存在于你本地硬盘不产生任何网络费用ollama pull phi3:3.8b这个命令会从 Ollama 的公共模型库下载phi3:3.8b约 2.1GB。如果你网络慢可以用更小的tinyllama:1.1b替代ollama pull tinyllama:1.1b它只有 600MB响应更快只是推理能力稍弱。等下载完成后启动智能体python3 -m openclaw.cli run --config config.yaml你会看到终端输出[INFO] Loading agent configuration from config.yaml [INFO] Initializing Ollama model provider with model: phi3:3.8b [INFO] Memory initialized: FileBasedMemory at ./memory.json [INFO] Tools loaded: [get_time, calculate] [INFO] Agent QuickStartAgent is ready. Type exit to quit. 现在在后输入现在几点几秒后你会看到类似这样的输出[THINKING] 用户问现在几点。我需要调用 get_time 工具获取当前时间。 [TOOL_CALL] get_time() → 2024-06-15 14:23:45 [THINKING] 工具返回了时间字符串我应该直接告诉用户。 [RESPONSE] 现在是 2024-06-15 14:23:45。再输入37 加 89 等于多少输出[THINKING] 用户问 37 加 89 的结果。这是一个数学计算我应该调用 calculate 工具。 [TOOL_CALL] calculate(3789) → 126 [THINKING] 工具返回了结果 126我应该用自然语言回复。 [RESPONSE] 37 加 89 等于 126。这就是你的第一个 OpenClaw 智能体。它没有 Web 界面没有登录页没有设置向导。但它清晰展示了智能体最核心的四步闭环理解用户意图 → 决策是否调用工具 → 执行工具并获取结果 → 综合信息生成自然语言回复。整个过程你没花一分钱没开一台云服务器甚至没注册一个账号。3.3 深度定制30 分钟内让它学会“查本地文件”“查时间”“算数学”只是热身。真正的价值在于你能用 10 行 Python 代码让它学会操作你电脑上的任何东西。下面我们给它加一个新工具读取当前目录下的 README.md 文件内容。在examples/quickstart/目录下新建文件my_tools.py# my_tools.py from pathlib import Path def read_readme() - str: 读取当前目录下的 README.md 文件内容最多返回前 500 字符 readme_path Path(.) / README.md if not readme_path.exists(): return 错误当前目录下没有 README.md 文件 try: content readme_path.read_text(encodingutf-8) return content[:500] (... if len(content) 500 else ) except Exception as e: return f读取文件时出错{str(e)}然后修改config.yaml在tools列表末尾添加- name: read_readme description: 读取当前目录下的 README.md 文件内容 module: my_tools.read_readme最后在examples/quickstart/目录下创建一个测试用的README.mdecho # 我的第一个 OpenClaw 项目 README.md echo 作者你的名字 README.md echo 创建时间$(date) README.md再次运行python3 -m openclaw.cli run --config config.yaml输入读一下 README.md 里写了什么你会看到[THINKING] 用户让我读 README.md 文件。我需要调用 read_readme 工具。 [TOOL_CALL] read_readme() → # 我的第一个 OpenClaw 项目\n作者你的名字\n创建时间Sat Jun 15 14:30:22 CST 2024 [THINKING] 工具返回了文件内容我应该总结并转述给用户。 [RESPONSE] README.md 文件内容是 # 我的第一个 OpenClaw 项目 作者你的名字 创建时间Sat Jun 15 14:30:22 CST 2024这个例子的价值在于它证明了 OpenClaw 的工具扩展是“零学习成本”的。你不需要懂 REST、不需要学 GraphQL、不需要配 OAuth。你只要会写一个 Python 函数能返回字符串或字典OpenClaw 就能把它变成智能体的一个“超能力”。下一步你可以把read_readme换成send_slack_message调 Slack Webhook、换成query_postgres连你公司的数据库、换成trigger_zapier触发 Zapier 自动化——所有这些都只需要改my_tools.py里的一个函数改config.yaml里的一行配置。3.4 进阶技巧让智能体“记住”你上次聊了什么前面的 demo 里每次重启智能体它都会“失忆”。现在我们用 OpenClaw 的文件记忆功能让它记住你。打开config.yaml找到memory部分确保它是这样memory: type: file path: ./memory.json然后在examples/quickstart/目录下手动创建一个初始记忆文件memory.json{ session_id: demo-session-001, history: [ { role: user, content: 你好, timestamp: 2024-06-15T14:00:00Z }, { role: assistant, content: 你好我是 QuickStartAgent我能帮你查时间、算数学。, timestamp: 2024-06-15T14:00:01Z } ] }现在再次运行智能体python3 -m openclaw.cli run --config config.yaml输入我们刚才聊过什么它会读取memory.json里的历史并回复[THINKING] 用户问我我们刚才聊过什么。我需要查看记忆中的对话历史。 [MEMORY_READ] 读取到 2 条历史消息用户说“你好”我回复“你好我是 QuickStartAgent...” [RESPONSE] 我们刚才聊了你说“你好”我介绍了自己。更妙的是OpenClaw 会在你每次对话结束后自动把新消息追加写入memory.json。你关掉终端再重开它依然记得。这就是“0 成本持久化”的真相它不依赖数据库就靠一个 JSON 文件用最朴素的f.write(json.dumps(data))实现。实操心得JSON 文件记忆不是玩具我在客户现场用它跑了 6 个月每天处理 200 条内部查询memory.json文件最大到 12MB用 Pythonjson.load()读取耗时始终低于 80ms。如果你担心文件过大OpenClaw 还支持memory的max_history_length参数设成 50它就只保留最近 50 轮对话自动裁剪旧记录。4. 常见问题与避坑指南那些没人告诉你的“第一课”陷阱跑通 demo 只是开始真正卡住新手的永远是那些文档里不会写、Stack Overflow 上搜不到、但又真实存在的“幽灵问题”。我把过去半年帮 37 个新手排查过的典型问题按发生频率排序附上根因分析和一招解决法。4.1 问题速查表高频报错与秒级解决方案报错信息截取关键段根本原因30 秒解决法为什么有效ConnectionError: HTTPConnectionPool(hostlocalhost, port11434): Max retries exceededOllama 服务没运行或端口被占ollama serve前台启动或systemctl --user restart ollama后台重启OpenClaw 默认连http://localhost:11434这是 Ollama 的固定 API 端口不是 OpenClaw 配的ModuleNotFoundError: No module named openclaw在错误目录下执行python3 -m openclaw.cli确保你在openclaw/源码根目录有pyproject.toml的那个执行命令python3 -m是按 Python 模块路径导入openclaw是源码里的包名不在根目录就找不到ValidationError: model_name is a required propertyconfig.yaml里model_provider: ollama但漏写了model_name在model_provider下一行严格缩进 2 格写model_name: phi3:3.8bYAML 对缩进极其敏感model_name必须和model_provider同级且缩进必须是空格不能是 TabPermissionError: [Errno 13] Permission denied: ./memory.jsonmemory.json被其他进程锁定比如你用 VS Code 打开了它关闭所有编辑器或rm ./memory.json删除后重试文件锁是操作系统级机制OpenClaw 用open(file, w)写入被锁就失败没别的办法ToolNotFoundError: Tool xxx not found in registryconfig.yaml里写的module: my_tools.xxx但my_tools.py文件不在PYTHONPATH路径下把my_tools.py放到examples/quickstart/目录和config.yaml同级或在命令前加PYTHONPATH. python3 -m ...OpenClaw 的 tool loader 用importlib.import_module(module_name)模块路径必须能被 Python 解释器 resolve4.2 那些“看起来正常其实已经错了”的隐形坑模型下载一半中断导致后续ollama run失败Ollama 的模型下载是分层的manifest、layer、config如果网络断了它不会自动重试而是留下一个损坏的 layer。表现是ollama list能看到模型但ollama run phi3报layer not found。解决法ollama rm phi3:3.8b彻底删除再ollama pull重下。别试图手动删~/.ollama/models/下的文件Ollama 有自己的数据库索引。CLI 输入中文后智能体回复乱码如我们刚才聊过什么？这不是 OpenClaw 的 bug是你的终端编码问题。macOS Terminal 默认 UTF-8但某些 SSH 客户端或老旧 Linux 发行版可能用ISO-8859-1。解决法在运行命令前先执行export PYTHONIOENCODINGutf-8再python3 -m openclaw.cli run...。一劳永逸把这行加到你的~/.zshrc。工具函数里用了print()结果 CLI 里看不到输出OpenClaw 的ToolRouter会捕获工具函数的stdout只返回函数的return值。print()的内容被吞掉了。解决法调试时把print()换成logging.info()或者直接return DEBUG: str(your_var)。正式上线时删掉所有调试 print。config.yaml里写了model_name: qwen2:1.5b但ollama list没显示Ollama 的模型名是区分大小写的且qwen2:1.5b是社区非官方模型需要手动ollama create。解决法先ollama pull qwen2:1.5b如果存在不存在就去 Ollama 模型库搜索qwen找到正确名称如qwen2:0.5b再改config.yaml。别猜去官网查。4.3 性能与体验优化让“0 成本”跑得比付费服务还稳启动慢默认ollama run会加载整个模型到内存。如果你只做 demo加--num_ctx 512参数ollama run phi3:3.8b --num_ctx 512上下文窗口从默认 2048 降到 512内存占用立减 40%启动快 3 倍。响应卡顿检查你的config.yaml里model_provider是否写成了openai拼写错误。OpenClaw 会静默 fallback 到ollama但会多一次无效的网络探测拖慢首响。用grep -r openai .全局搜一遍。想换模型但怕重配OpenClaw 支持.env文件。在examples/quickstart/下建.envOLLAMA_MODEL_NAMEphi3:3.8b OLLAMA_HOSThttp://localhost:11434然后config.yaml里直接写model_name: ${OLLAMA_MODEL_NAME}。以后换模型只改.env不用碰 YAML。团队协作时配置不一致把config.yaml里的敏感信息如 API Key、数据库密码全抽到.env再把config.yaml加进.gitignore。每个人本地维护自己的.envGit 只存通用逻辑。这是我给所有客户的标准交付物。5. 后续演进路径从“0 成本”到“可商用”一条平滑的升级曲线跑通第一个智能体只是起点。OpenClaw 的真正优势在于它为你规划了一条几乎无痛的升级路径每一步增加的成本都精确对应你业务增长的真实需求绝不会出现“为了支持 10 个用户被迫买 100 核云服务器”的荒谬局面。5.1 第二课把 CLI 智能体变成你电脑右下角的“随时待命”助手你现在用的是python3 -m openclaw.cli run每次都要开终端、输命令。下一步把它变成 macOS 的菜单栏小程序或 Windows 的系统托盘应用。macOS 方案用py2app打包。在examples/quickstart/下建setup.pyfrom setuptools import setup APP [run_agent.py] # 你写个简单 wrapperfrom openclaw.cli import run; run() DATA_FILES [config.yaml, memory.json] OPTIONS {argv_emulation: True} setup(appAPP, data_filesDATA_FILES, options{py2app: OPTIONS}, setup_requires[py2app])python3 setup.py py2app生成一个双击即用的.app。我把它拖进 Dock点击图标就弹出交互窗口比 Terminal 方便十倍。Windows 方案用pyinstaller --onefile --windowed run_agent.py生成一个无黑窗的.exe。这步成本0 元2 小时。效果你的智能体从“命令行玩具”变成了“个人数字助理”。5.2 第三课接入你的真实业务系统不改一行旧代码你公司有个老系统用 PHP 写的内部 Wiki地址是http://wiki.internal/search?q。你想让智能体能查 Wiki。写一个工具函数search_wiki(query: str) - str:里面用requests.get(fhttp://wiki.internal/search?q{query})把这个函数放进my_tools.pyconfig.yaml里加 tool 配置运行。全程你没动 Wiki 一行代码没申请任何 IT 权限没开新端口。Wiki 系统管理员甚至不知道这事发生了。这就是 OpenClaw 的“胶水层”价值它不取代旧系统而是给旧系统装上自然语言接口。我在一家制造业客户那里用这招把 15 年前的 SAP ERP 系统只提供 RFC 接口接入了智能体销售同事现在直接说“查一下客户 ABC 的最新订单”智能体就调 RFC 函数返回结构化数据再生成中文摘要。IT 部门只提供了 RFC 连接参数其余全是业务方自己搞定。5.3 第四课当用户量从 1 个变成 100 个如何平滑扩容第一个用户是你的老板第十个用户是部门同事第一百个用户是全公司。这时文件存储 memory 会变慢同步工具调用会阻塞。Memory 升级把memory.type: file改成redismemory.host: localhostmemory.port: 6379。pip install redisdocker run -d -p 6379:6379 redis。所有代码不变性能提升 10 倍。Tool 升级把calculate这种 CPU 密集型工具改成 Celery 异步任务。pip install celery redis加celery_worker.pyconfig.yaml里tool.async: true。用户发问智能体立即返回“正在计算”后台异步跑结果好了再推送。Model 升级当phi3:3.8b满足不了复杂推理时ollama pull qwen2:7b改config.yaml一行model_name: qwen2:7b。7B 模型在 RTX 4090 上推理速度仍达 18 tokens/s远超 GPT-3.5 Turbo 的 API 延迟。所有这些升级都不需要重构你的tools.py、config.yaml、workflow.yaml。你只是在同一个配置文件里改几个字段加几行依赖。成本是渐进的能力是叠加的。我个人在实际操作中发现90% 的智能体项目根本不需要走到第四课。它们停在第二课桌面助手或第三课业务系统胶水就已经解决了核心痛点产生了真实 ROI。OpenClaw 的伟大不在于它能跑多大的模型而在于它让你在花一分钱之前就看清了这条路到底值不值得走下去。这个“省钱第一课”的终点从来不是省钱本身。而是让你在键盘敲下第一个符号的那一刻就确信智能体真的可以属于你。