OpenClaw + Ollama 开发者分享文档

OpenClaw + Ollama 开发者分享文档

文档结构

1. 分享会定位

1.1 分享主题

OpenClaw + Ollama 开发者实践：从 AI Agent 架构到本地模型辅助开发

1.2 听众与分享目标

听众画像：前端 / 全栈开发者，已有 Cursor 或 Copilot 使用经验，想了解 Agent 架构、本地模型和可自部署助手。

本次分享主要解决八个问题：

1. AI Agent 是什么，和「单次问答 / 补全」有什么本质区别。
2. OpenClaw 的架构是什么，开发者能扩展哪些能力（Skills、Tools、MCP、模型路由）。
3. OpenClaw 怎么安装、初始化，怎么配默认模型、理解 Memory。
4. Cursor 已能 plan + execute 的前提下，OpenClaw 还剩哪些独特价值。
5. 两者边界在哪里——运行形态、扩展方式、部署位置（详见第 5 章）。
6. Ollama 是什么，本地跑模型的硬件门槛和选型建议。
7. Ollama 如何一键接入OpenClaw（原生集成，无需 OpenAI 兼容配置）。
8. 本地 Ollama 与云端 API 在开发场景下的取舍。

1.3 分享建议时长

建议总时长：60 到 75 分钟。

2. AI Agent 是什么

2.1 一句话介绍

AI Agent 是「能围绕目标自主完成任务的 AI 系统」：理解目标 → 规划步骤 → 调用工具 → 观察结果 → 迭代，而不只是生成一段文字。

前提：Cursor 的 Agent / Plan 模式在 IDE 内已能完成这条链路。OpenClaw 与 Cursor 的差异不在「会不会 plan + execute」，而在运行形态——详见第 5 章，此处只讲 Agent 本身。

2.2 典型工作流程

用户提出目标 → 理解目标 → 拆解任务 → 调用模型和工具 → 执行动作 → 观察结果 → 返回或继续执行

示例：「头像上传返回 413，帮我排查并给修复方案」——Agent 会读UploadAvatar.vue、grep upload 配置、对比接口 size limit、产出 patch；而不是只解释 HTTP 413 含义。

2.3 组成部分与协作示例

以「用户列表白屏，TypeError: undefined」为例：

Prompt 加载调试规则 → Memory 补充 Vue3+Pinia 约定 → LLM+Planning 定计划 → Tools 读 UserList.vue、grep user.profile → Feedback 单测仍红、补判空 → Permission 禁止触达 .env → 输出根因 + 补丁

2.4 价值与风险（开发者视角）

价值：多步骤自动化、接入工程工具、Skill 沉淀团队规范、配合 Ollama 本地部署。

风险：权限越界、错误执行、敏感数据泄露、结果不可控、缺少审计日志。

原则：默认只读 → 写操作须确认 → 最小权限 → 保留 tool call 日志。

3. OpenClaw 是什么

3.1 一句话介绍

OpenClaw 是开源 AI Agent 运行时，提供模型路由、工具调用、Skills 扩展、Memory 与权限沙箱，把 AI 接到 CLI、消息 Bot 或团队工作流——不是 ChatGPT 套壳。

模型路由：在多个 Provider / 模型间按规则调度（主模型、fallback、按通道切换）。例如日常走 Ollama 7B，复杂任务切云端，主模型 429 时自动降级。

3.2 架构（三层）

入口层：CLI、消息 Bot、工作空间 能力层：模型路由、Tools、Skills/MCP、Memory、权限沙箱 扩展层：自定义 Skill、脚本、内部 API、Ollama / 云端模型

3.3 核心特征

• 开源可 fork：学习 Agent Runtime、Tool 注册、Skill 加载。
• 工具调用：读文件、跑 shell、调 HTTP。
• Skills 可扩展：联调 checklist、CR 模板等可复用。
• 模型可替换：Ollama 本地 ↔ 云端 API，同一套 Agent 配置。
• 可自部署：代码与推理可不出内网。

3.4 适用场景

4. OpenClaw 安装和使用

4.1 安装前准备

• Node.js 24（最低 22.16+）、npm/pnpm/bun、Git（源码时）
• 模型：Ollama 或云端 API Key
• Windows 建议 WSL2；命令以 OpenClaw 官方文档 为准

4.2 WSL2（Windows 用户）

wsl--install# 管理员 PowerShell，重启后 wsl -l -v 确认版本为 2

4.3 安装

npminstall-gopenclaw@latest openclaw--version

源码：git clone https://github.com/openclaw/openclaw.git

4.4 初始化

openclaw onboard# 交互引导openclaw onboard --install-daemon# 安装后台守护进程

provider 列表选Ollama可一键接入本地模型（自动发现、auto-pull）；云端 API 则选对应 provider 填 Key。还会配置工作区、入口、技能、权限范围。

4.5 升级与卸载

npminstall-gopenclaw@latest# 升级npmuninstall-gopenclaw# 卸载（先停 daemon）

4.6 开发者路径

安装 → onboard → 配置模型 → CLI 发任务 → 观察 tool call → 扩展 Skill

三个 checkpoint：①openclaw --version② 模型连通 ③ 完成一个只读任务（如 CR 清单）。

习惯建议：描述带上技术栈和输出格式；改代码前先只要方案；本地试验优先 Ollama。

4.7 配置文件概览

OpenClaw 的配置集中在JSON5文件（默认路径）：

~/.openclaw/openclaw.json # 主配置（模型、通道、技能、Memory 等） ~/.openclaw/workspace/ # Agent 工作区（Memory 文件、知识文档等）

三种修改方式（推荐优先用 CLI / 向导，避免手写出错）：

Control UI 默认地址：http://127.0.0.1:18789（端口以gateway.controlUi.port为准）。

常用配置片段示例（Ollama 本地 + 降级链）：

{ agents: { defaults: { workspace: "~/.openclaw/workspace", model: { primary: "ollama/qwen2.5-coder:7b", fallbacks: ["anthropic/claude-sonnet-4-6"], // 主模型失败时尝试 }, models: { "ollama/qwen2.5-coder:7b": { alias: "local" }, "anthropic/claude-sonnet-4-6": { alias: "cloud" }, }, }, }, }

模型引用格式：provider/model（如ollama/qwen2.5-coder:7b）。改agents.defaults.model后通常需重启 gateway；Memory 相关字段部分支持热更新。

配置变更后建议：

openclaw doctor# 检查配置是否合法openclaw doctor--fix# 升级后修复过时字段openclaw config get agents.defaults.model.primary# 确认生效值

4.8 模型：设置默认与切换

模型选择优先级（简化）

当前会话 /model 选择 → agents.defaults.model.primary → fallbacks 链 → Provider 内 auth 轮换

设置默认模型

CLI（改全局默认，写入 openclaw.json）：

openclaw models list# 看已配置/可用模型openclaw models list--providerollama# 只看 Ollamaopenclaw models status# 当前 primary、fallbacks、鉴权状态openclaw models status--probe# 探测各 Provider 是否连通openclaw modelssetollama/qwen2.5-coder:7b# 设默认模型openclaw models fallbacksaddanthropic/claude-sonnet-4-6 openclaw models aliasesaddlocalollama/qwen2.5-coder:7b

配置文件：

openclaw configsetagents.defaults.model.primary'"ollama/qwen2.5-coder:7b"'--strict-json

Control UI：openclaw dashboard→ Config →agents.defaults.model→ 设置primary/fallbacks。

会话内临时切换（不改全局默认）

在 CLI TUI、Telegram、Discord 等对话里：

/model # 弹出编号选择器 /model list # 列出可选模型 /model 2 # 选第 2 个 /model ollama/qwen2.5-coder:7b /model status # 看当前会话用的模型与鉴权

• /model只影响当前会话；新会话仍用agents.defaults.model.primary。
• 用户用/model指定的模型若不可用，会直接报错，不会静默 fallback（与全局默认行为不同）。

交互式分段配置

openclaw configure--sectionmodel# 只跑模型相关向导openclaw configure--sectionchannels# 只配消息通道

4.9 记忆（Memory）原理

Memory ≠ 聊天记录缓存，也 ≠ RAG 知识库（Knowledge Skill 是另一条线）。Memory 是Agent 主动写入工作区的 Markdown 笔记，下次对话再检索注入。

核心原理

模型本身无持久记忆 → OpenClaw 把「值得记住的」写到磁盘 Markdown → 新会话 bootstrap 加载摘要 → memory_search 语义检索历史笔记 → 注入 prompt

Agent 只「记得」写进文件的内容，没有隐藏状态。

文件结构（默认在 workspace 内）

怎么写入：直接告诉 Agent——「记住我偏好 TypeScript」「记住这个项目用 Vue3+Pinia」——它会写到合适文件。Compaction（上下文压缩）前还会自动memory flush，把对话里尚未落盘的重要信息写入memory/*.md。

Memory 工具（Agent 运行时调用）

CLI 等价操作：

openclaw memory status openclaw memory search"联调 头像上传"openclaw memory index--force# 重建索引

检索（Embedding）配置

默认用云端 embedding；本地/Ollama 场景可在openclaw.json配置：

{ agents: { defaults: { memorySearch: { provider: "ollama", // 或 local、openai、gemini 等 model: "qwen3-embedding:0.6b", enabled: true, }, }, }, }

配合 Ollama 全离线时，对话模型和embedding 模型可分别指定（例如 7B coder 对话 + 小 embedding 模型检索）。

Memory vs 其他概念

进阶： bundledmemory-wiki插件可把 Memory 整理成带溯源的 wiki；Honcho、LanceDB 等为可选后端插件。

4.10 常用命令速查

# ── 生命周期 ──openclaw onboard --install-daemon openclaw configure openclaw dashboard# 打开 Control UIopenclaw doctor--fix# ── Gateway ──openclaw gateway status|restart openclaw agent--message"你好"# 直接跑一轮 Agent# ── 配置 ──openclaw config get agents.defaults.model.primary openclaw configsetgateway.bind'"loopback"'--strict-json# ── 模型 ──openclaw modelssetollama/qwen2.5-coder:7b openclaw models fallbacks list# ── Memory ──openclaw memory status openclaw memory search"部署 checklist"# ── 通道（Bot） ──openclaw channels list openclaw channelsadd--channeltelegram openclaw configure--sectionchannels

对话内常用 slash 命令：/model、/model status、/reset（清会话）、/context list（看注入上下文大小）。

5. OpenClaw 和 Cursor 对比

全文唯一展开 Cursor 对比的章节。其他章节仅引用结论。

5.1 一句话

Cursor= IDE 内 Agent，plan + execute 代码任务，日常编码首选。

OpenClaw= IDE外的开源 Agent 运行时——Bot、CI、Ollama 离线、可 fork。

5.2 对比表

5.3 选型决策

组合用法：

Cursor — 日常编码（plan + execute） OpenClaw — IDE 外 Bot / CI / Skill 基础设施 Ollama — 本地模型，配合 OpenClaw 离线跑 云端 API — 复杂推理，Cursor 或 OpenClaw 均可接

编码用 Cursor 就够了；要把 Agent 部署到 IDE 之外，再看 OpenClaw。

6. 差异化场景与 Agent 能力示例

6.1 OpenClaw 真正差异化的场景

Skill 示例：

# frontend-pr-checklist 当用户说「PR 检查」→ 询问 Vue/React → 输出 a11y/性能/类型 checklist 表格

新人在 Slack @Bot 即可得到团队统一输出——IDE 产品难以直接提供这种部署形态。

6.2 Agent 能力示例（Cursor 同样擅长）

以下示例用于理解 Agent 能力模型。Cursor Agent 在 IDE 内已能 plan + execute，不必为此专门装 OpenClaw。

分享建议：6.2 可快速带过；重点演示 6.1 的 IDE 外场景。

7. Ollama 是什么

Ollama 是在本机下载、运行开源大模型的工具，默认服务地址http://127.0.0.1:11434。

价值：不依赖云端 API，适合学习、演示、隐私敏感和内网开发。

7.1 核心能力

• 本地推理，数据默认不出本机
• ollama pull / run / list管理模型
• 原生 API/api/chat——OpenClaw 直接集成，支持 streaming + tool calling
• 推荐代码模型：qwen2.5-coder:7b

7.2 硬件要求（简表）

• 磁盘预留 20～50GB；有 NVIDIA GPU 明显加速
• 分享演示：16GB 内存 + 7B 模型即可

8. Ollama 安装与使用

# 安装（macOS/Linux）curl-fsSLhttps://ollama.com/install.sh|sh# Windows： https://ollama.com 下载安装包ollama--versioncurlhttp://127.0.0.1:11434/api/tags# 确认服务在跑ollama pull qwen2.5-coder:7b ollama run qwen2.5-coder:7b ollama list

/v1OpenAI 兼容接口供其他第三方工具使用；OpenClaw 不走此路径（见 §9.3）。

9. Ollama 接入 OpenClaw

OpenClaw原生支持Ollama，无需手动填 OpenAI Compatible //v1/ 假 API Key。

9.1 一键接入

方式 A（推荐）：

openclaw onboard# → 选 Ollama → Local only → 选模型（自动发现、auto-pull）openclaw models list--providerollama# 验证

方式 B（Ollama 0.17+）：

ollama launch openclaw--modelqwen2.5-coder:7b

方式 C（CI / 非交互）：

openclaw onboard --non-interactive\--auth-choice ollama\--custom-model-id"qwen2.5-coder:7b"\--accept-risk

9.2 接入前检查

ollama--version&&ollama listcurlhttp://127.0.0.1:11434/api/tags

9.3 为何不用 OpenAI Compatible/v1

9.4 好处与限制

好处：零 API 成本、数据不出网、tool calling 稳定、auto-pull 省心。

限制：7B 能力弱于顶级云端模型；速度受硬件影响；复杂推理可能不稳定。

10. Ollama 与云端 API 对比

日常编码 → Cursor Agent IDE 外 / 离线 / Bot → OpenClaw + Ollama 复杂方案 / 高 SLA → 云端 API

11. 分享演示设计

注意：提前装好、拉好 7B 模型；每个 demo 3～5 分钟；准备截图 fallback；勿展示真实 Key。

12. 分享开场白

大家好，今天聊OpenClaw + Ollama。

先对齐：Cursor Agent 在 IDE 里已经能 plan + execute——这很好，日常编码继续用它。

OpenClaw 讲四件事：Agent 架构、IDE 之外（CLI/Bot/CI）、本地模型（Ollama）、配置与 Memory（默认模型、持久记忆）。

分享结束后请思考：什么情况下才值得上 OpenClaw？默认模型和 Memory 怎么配？Bot/Skill 权限怎么控？

13. Q&A 与一页总结

常见问题

Q：OpenClaw 能替代 Cursor 吗？
不能也不必要。Cursor 做 IDE 内编码；OpenClaw 做 Bot、CI、内网、Ollama 离线。

Q：已有 Cursor，还需要 OpenClaw 吗？
日常写代码 ❌；代码不出网 / 做 Bot / CI 分析 / 学 Runtime ✅。

Q：Ollama 怎么接 OpenClaw？
openclaw onboard选 Ollama，或ollama launch openclaw --model <名>。不需要 OpenAI Compatible。

Q：Ollama vs 云端？
试验、隐私、离线 → Ollama；复杂推理、高 SLA → 云端。

Q：默认模型怎么设？
全局：openclaw models set ollama/qwen2.5-coder:7b或 Control UI Config。会话内：/model ollama/qwen2.5-coder:7b（仅当前会话）。

Q：Memory 是什么？
Agent 把偏好/结论写入 workspace 的MEMORY.md和memory/YYYY-MM-DD.md，通过memory_search检索；不是聊天自动缓存。说「记住 xxx」即可写入。

Q：试用第一步？
前提：编码已有 Cursor。若有 IDE 外需求 → 安装 OpenClaw → onboard 选 Ollama → 试 Skill/Bot。

一页总结

IDE 内编码 → Cursor Agent IDE 外 / 离线 → OpenClaw + Ollama 学 Agent 架构 → OpenClaw 源码

Cursor 把 Agent 做进了 IDE；OpenClaw 让你把 Agent部署到 IDE 之外——互补，非替代。

14. 分享结尾

• Cursor继续担任 IDE 内编码首选。
• OpenClaw适合 Agent 架构学习、IDE 外部署、Ollama 离线、fork Runtime。
• 务实路径：编码 → Cursor；IDE 外基础设施 → OpenClaw + Ollama。