我的猫最近开始乱尿我带着它跑了一趟医院医生第一句话就是有连续的健康记录吗我翻了相册、聊天记录和几个浮窗备注根本凑不出一条完整时间线。回家之后我决定做一件事——用 OpenClaw 搭一套本地宠物日记把这只猫的体重、喂食、疫苗、行为和照片全部存进自己的硬盘。这篇先讲本地搭建从零把 OpenClaw 跑起来。我试过不少宠物App但不是要开订阅就是不得不把照片传到别人服务器上好不容易找到一个能离线用的字段又锁得死死的连“罐头品牌”这种自定义项都加不进去。OpenClaw 最吸引我的地方是它把日记当成一份可以自己掌控的结构化数据猫档案是一张表每一条日记是一行记录照片原图留在本地所有摘要和索引都在本机生成。想改字段就改表结构想导出就导出不跟任何云盘绑定。这篇内容适合两种人一种是只想认真记录毛孩子日常、又格外在意数据隐私的养宠人另一种是像我一样想拿真实需求练手本地服务搭建的开发者。如果你完全不想碰命令行你依然能读完前两部分把能做什么、怎么规划搞清楚后面再找懂行的朋友照着操作。1. 为什么我会选择本地搭建OpenClaw宠物日记1.1 云端App解决不了的三个问题在评估 OpenClaw 之前我认真列过自己的需求要记多种事件、要能传原图、要支持多只宠物、要能本地备份、不要强制联网。把市面上的宠物App看了一圈三个老问题始终在。第一个是数据主权。几乎所有号称免费的应用都把数据存在厂商的云上。如果哪一天服务停掉或者账号被限制几年积累的记录可能连导出的机会都没有。第二个是字段不可定制。有的App只能记“喂食”“铲屎”“遛弯”我想额外记“驱虫药批号”“猫粮批次”就非常别扭。自己搭建意味着数据结构和页面都能改。第三个是订阅费用。很多应用把多宠物同步、数据导出、照片云端原图都划到高级功能里一个月几十块一年下来足够买个移动硬盘。这三点合在一起指向同一个结论与其在一个封闭产品里凑合不如把日记放在自己手里。1.2 OpenClaw 的本地优先设计OpenClaw 的核心理念是 local-first所有数据先写进本地存储再考虑要不要同步。它不是简单把一篇篇日记拼成一个时间线而是以宠物档案为主体组织信息每只宠物有独立的档案日记通过 pet_id 关联回档案图片作为一个独立资源存储日记里只保留引用。这样设计的好处体现在导出和统计你可以随时列出某只猫一年内的体重记录也可以把某一天的图片和文字打包成一个文件夹结构依然是清楚的。服务由三块组成核心服务负责认证、档案和日记的增删改查存储模块管理数据库文件与图片目录智能模块是可选的默认不启用用来做自动标签、体重趋势摘要。本地搭建的第一步就是把这三块跑在同一台电脑上。1.3 适合什么人、不适合什么人适合的场景家里有一只或几只宠物希望把疫苗、体重、喂食、行为串成一条可靠的时间线对数据敏感不想把照片发给第三方愿意花半小时做一次性的安装配置。不适合的场景完全不想接触配置文件只要打开App就能用或者需要多人多地同时编辑并且不关心数据放哪里。这些情况用商业产品更省心。如果你的需求介于两者之间也可以先按这篇内容把本地版搭起来局域网内手机浏览器直接访问家里一个人负责记录数据始终在自己的网络里。2. 搭建前必须想清楚的整体设计2.1 数据流与模块划分我自己画过一张极简数据流你可以先把它记在脑子里用户在网页或手机浏览器里填一条记录上传照片后端把图片写到图片目录把结构化内容写进数据库读取时后端从数据库查记录、从图片目录读文件组合成完整日记返回给页面如果启用了智能模块会额外把文本摘要和标签回写到记录里。这张图虽然简单但能解释很多后面的配置项数据库路径决定历史数据放哪图片目录决定原图放哪host 和端口决定局域网内怎么访问AI 模块的地址决定摘要能力从哪里来。也就是说本地搭建的绝大部分工作其实是在把这些“决定”填进配置文件。2.2 技术选型为什么不需要重型组件做技术选型时最需要顶住诱惑。第一个诱惑是看到别人用容器编排就觉得很高端想上多个组件。单用户、单机的宠物日记最需要的是低维护不是高并发。我用的是本地嵌入式的数据库数据就是一个文件备份时复制走即可图片目录就是普通文件夹后端服务是一个独立进程默认监听一个端口。这个组合足够覆盖几万条日记而且没有中间件要养。第二个诱惑是过早引入外部依赖。比如为了让手机也能访问直接把服务暴露到公网或者接一堆统计SDK都会带来安全和维护成本。OpenClaw 在本地搭建阶段刻意保持零外部依赖只有当你确实需要云端同步时才在后续阶段加入同步组件。2.3 用容器还是直接在系统里跑我最终选择了直接在系统里运行没有用容器。理由很简单本机调试时虚拟环境已经提供了依赖隔离热重载和日志查看都比容器里简单图片目录、数据库文件直接放在用户目录下不用处理容器内外路径映射。缺点也有就是换电脑时需要手动迁移数据和依赖。如果你对容器比较熟悉也可以把 OpenClaw 打成镜像把数据和图片目录挂载到宿主机。两种方式的数据格式是一样的后续可以随时切换。这篇内容按非容器方式写因为受众面更广报错也更容易定位。3. 本地环境准备3.1 安装基础运行时搭建前先确认电脑里有三样东西Python 运行时、版本控制工具、一个能跑命令行的终端。Python 建议选择 3.10 或更新版本因为新版本对类型注解的支持更好也避免后续依赖装不上。终端在常用系统上都有桌面系统直接打开Windows 可以使用系统自带的终端。打开终端后先验证环境python --version git --version如果提示找不到 python可能需要用 python3 命令或者安装对应运行时。这一步很重要后面所有操作都基于它。虚拟环境、依赖安装、启动服务全都依赖这个终端环境正确。3.2 拉取 OpenClaw 源码并创建虚拟环境我习惯把项目放在一个专门的目录下方便以后统一管理。命令如下mkdir -p ~/projects cd ~/projects git clone https://example.com/openclaw/openclaw.git cd openclaw python -m venv .venv创建虚拟环境是为了不污染系统Python依赖。后面所有操作都要在这个虚拟环境里执行。激活方式桌面系统上是 source .venv/bin/activateWindows 下是 .venv\Scripts\activate。激活成功后命令行前缀会出现(.venv)看到它再继续下一步。小技巧把激活命令写进终端历史的开头如果每次新开终端都忘记激活后面命令容易装到全局甚至出现“模块找不到”的怪问题。3.3 安装依赖进入项目目录且虚拟环境已激活后执行包管理命令安装依赖pip install -r requirements.txt第一次安装可能需要几分钟耐心等待即可。如果遇到网络超时可以把包索引切到本地网络更快的镜像源核心思路是修改包管理工具的 index-url。装完之后验证核心服务是否能被导入python -c from openclaw.core import app; print(ok)如果输出 ok说明依赖安装完整可以进入下一步。这个验证命令不要跳过它能快速区分是环境问题还是配置问题。3.4 不同系统上的路径与权限差异在服务器上操作时不要直接使用管理员身份跑服务而是创建一个普通用户数据库和图片目录放在这个用户的主目录下。Windows 上要注意目录路径不要带空格和中文避免某些底层库解析路径出错。macOS 上如果系统有安全策略拦截第一次运行需要到系统设置的隐私与安全里允许。这些都是小事但卡住的概率不低。我自己的习惯是先跑一遍文档里的验证命令再进入配置阶段。环境准备阶段多花 5 分钟后面能少踩很多坑。4. 核心配置与数据库初始化4.1 配置文件逐项解读OpenClaw 在项目目录里提供了默认配置模板 config.example.yaml我们需要复制一份为 config.yaml 再编辑。用文本编辑器打开后最关心的几个字段如下server: host: 0.0.0.0 port: 8080 storage: data_dir: ./data db_name: pets.db image_dir: ./data/images ai: enabled: false endpoint: http://127.0.0.1:8000 auth: session_days: 30逐个说host 为 0.0.0.0 表示监听所有网卡这样手机能通过局域网 IP 访问如果不想被局域网访问可以改成 127.0.0.1。port 是一个未占用的端口我习惯用 8080也可以用 8000、8800 这类高位端口。data_dir 是数据和图片的根目录db_name 是数据库文件名。ai.enabled 默认关掉endpoint 是未来要接入的本地推理服务地址这一步不需要你就保持默认。还有一个容易忽略的 auth.session_days它控制登录状态保持多少天。自己用可以设长一点比如30天省得天天登录。4.2 初始化数据库配置文件保存好之后开始初始化数据目录和数据库。执行python -m openclaw init这个命令会读取 config.yaml创建 data 目录、图片目录、数据库文件并把内置的表结构写好包括宠物档案表、日记表、图片表、用户表。命令设计成幂等的重复执行不会清空已有数据可以放心。看日志看到类似 database initialized successfully 的提示说明初始化成功了。如果报错先检查 data_dir 的父目录是否有写权限。某些系统下项目目录安装在受保护位置需要把 config.yaml 里的 data_dir 改成完全独立的路径比如当前用户目录下的 openclaw-data。4.3 创建管理员账号数据库建好后需要创建登录和管理用的账号python -m openclaw create-user admin执行后按提示输入密码。这里有两个建议一是密码不要太简单因为局域网内其他人也可能扫到服务二是记住这个账号名后面所有管理操作都用它。创建成功后会提示 session_secret 是否已生成。这个密钥用于签名登录态如果 config.yaml 里没有初始化时会自动生成。不要把这个文件提交到代码仓库以免泄露后别人能伪造登录状态。我在实际中见过有人把默认密钥直接留在配置里带到生产非常不建议。5. 启动服务与接口自测5.1 启动后端服务初始化完成后运行python -m openclaw run如果一切正常日志会显示监听地址比如 http://0.0.0.0:8080。此时已经可以打开浏览器访问了但我建议先做两件自测确认服务真的正常。第一件事是看日志有没有异常堆栈尤其是数据库连接和图片目录权限相关的告警。第二件事是保持终端在当前状态另开一个终端对健康检查接口发请求。5.2 用接口验证核心功能健康检查接口通常是这样curl http://127.0.0.1:8080/api/health正常会返回 JSON 数据内容包含服务状态和版本号。看到这个响应说明核心服务可以拿到请求并返回结果。再进一步可以试一个需要登录的接口把登录步骤合并成一条命令先用账号密码换取登录令牌再请求宠物列表具体接口路径以项目文档为准。我建议把这一步当作每次改完配置后的固定流程检查健康接口、登录、查列表。三件事都通了说明配置、认证、数据库这条主线是通的剩下就是页面上的操作。5.3 局域网内手机访问电脑上的 127.0.0.1 只有本机能访问。想用手机记录需要满足两个条件电脑和手机在同一个局域网电脑的防火墙允许 8080 端口进入。查看电脑的局域网 IP桌面系统可以用 ip addr 或 ipconfig 之类命令。拿到 IP 后手机浏览器直接访问 http://电脑IP:8080登录刚才创建的账号。如果手机打不开优先检查防火墙和监听地址。尤其要确认 server.host 是 0.0.0.0而不是 127.0.0.1。很多“手机访问不了”的问题最后都出在这两点上。5.4 调试模式与日志等级如果后续想改代码或排查问题可以在 config.yaml 里把日志等级调成 debug并打开调试开关。调试模式下每次请求都会打印更详细的参数和耗时页面报错也会展示具体堆栈。这里要注意调试模式会暴露内部信息仅限本机调试使用临时开完记得关掉。本地搭建阶段日志是你最好的朋友。遇到页面白屏、上传失败先去终端看最新几行日志大多数问题都会直接告诉你是哪个文件、哪行代码出了错。6. Web界面与首次宠物记录6.1 界面功能一览整个 Web 界面以“今日时间线”为主入口登录后第一屏能看到最近日记卡片按时间倒序排列。顶栏有宠物档案入口、新建记录按钮、图片库入口。侧边导航会列出已建档的宠物方便筛选。这里的设计思路和普通社交App不同日记不是以列表为核心而是以宠物为核心。你先选择要记录的猫或狗再选择事件类型填内容日期默认当前时间也可以回填到过去比如补录昨天的体重。图片库独立于日记每张图片会记录上传时间和关联的宠物。图片原图保存在图片目录页面显示的是缩略图后面就算缩略图被误删原图还在。6.2 第一步建立宠物档案在页面上找到“宠物档案”点新建填写名字、物种、品种、生日、绝育状态、过敏史和基础体重。字段不需要一次填全很多项目可以在之后的编辑里补。保存后系统会自动为这只宠物分配一个唯一ID这个ID会出现在数据库的宠物表里前端也能看到。我个人建议把每只宠物的唯一ID记在手机备忘里后面调用接口或做数据整理时用得上。这几步做完第一只宠物已经建档完成。如果家里有多只猫狗可以按照同样方式继续建档之后每条日记都可以关联到对应宠物。6.3 记录第一条日常日记回到新建记录页面选择宠物、时间、事件类型。默认事件类型有喂食、体重、疫苗、行为、就医也支持自定义标签。我通常会记两类一是体重和食量用来观察食欲变化二是行为异常比如乱尿、躲藏、嗜睡这些在兽医问诊时特别有用。上传图片时可以把手机相册里拍的照片传上去。上传成功后页面会先显示缩略图点开能看到原图。所有图片的 EXIF 信息会被读取作为拍摄时间的辅助字段但不会覆盖你手动选择的记录时间。点击保存第一条日记就写进数据库了。这时可以在时间线上看到它也可以通过筛选条件只看某只宠物某段时间的日记。关于自动摘要只有后续启用智能模块后保存时才会自动生成内容摘要这一步先不做。7. 常见问题与排查笔记7.1 端口占用导致服务起不来启动 OpenClaw 时如果日志报 address already in use说明端口被别的进程占了。最简单的办法是换一个端口在 config.yaml 里把 port 改成 8081 再启动。如果想保留端口需要找出占用进程并处理。不同系统的命令不太一样但思路一致先查监听端口的进程再决定结束它还是换端口。这个场景最容易发生在 8080/8000 这类常见端口上。如果你同时跑过其他开发服务建议直接选一个冷门端口比如 8899省得每次排查。7.2 中文内容出现乱码页面和数据库里的中文乱码多数和三个地方有关文件编码、数据库连接编码、浏览器自动识别编码。OpenClaw 默认的项目文件都是 UTF-8 编码如果你用系统旧版记事本编辑 config.yaml保存时可能被存成旧编码导致配置里的中文注释和服务解析不一致。处理方法是用支持 UTF-8 的编辑器重新保存配置文件确认数据库连接串或配置里指定了 utf8mb4 这类字符集浏览器访问时强制 UTF-8。别用旧版记事本改配置这是我在 Windows 环境里踩过最典型的坑。7.3 图片上传失败图片上传失败常见原因有三类目录权限、文件大小限制、磁盘空间不足。先看日志有没有 Permission denied如果有把 image_dir 目录的写权限给到运行服务的用户。再看请求是否返回 payload too large说明单张图片超过了默认限制需要在配置里提高 max_upload_size。最后查看磁盘剩余空间一眼就能看出来。另外不要在图片目录里手动放同名文件。OpenClaw 会用时间戳加随机串生成文件名手动重名会导致读取到错误内容。7.4 虚拟环境失效或命令找不到新开终端后直接运行 python -m openclaw如果提示找不到模块多半是因为没有激活虚拟环境或者激活后目录不对。先执行激活命令再确认当前目录在项目根目录之后再运行服务。还有一种情况系统里有多个 Python 版本python 指向旧版本而依赖安装在新版本虚拟环境里。可以用 python3 -m venv .venv 重建或者让 python 指向新版本再激活。7.5 服务运行一段时间后数据库锁死本地嵌入式数据库偶尔会出现 database is locked 的报错大多是多个进程同时访问同一个数据库文件导致的。比如你已经启动了一个服务又手动跑了一条初始化命令。解决办法很简单保证同时只有一个 OpenClaw 服务进程在运行。如果确实需要临时查数据用只读方式打开不要在生产目录上用图形化工具直接编辑数据库。我自己曾经一边开着服务一边用数据库工具改字段结果整个服务卡了半分钟只能重启。8. 后续建议备份、扩展与多设备8.1 定时备份是最好的安全网本地日记再安全硬盘坏了照样清零。我建议搭建当天就把备份方案做了而不是等写了一个月再说。OpenClaw 的数据全部集中在 data 目录数据库文件和图片目录都在里面备份只需要复制这个目录。在桌面系统上可以用系统自带的定时任务每天凌晨把 data 目录打包复制到一个外部存储或另一块硬盘。压缩命令可简单可复杂核心是保留最近若干天版本避免一次误操作把备份也覆盖掉。这里有一个很多人忽略的要点如果数据库正在被服务占用直接复制文件可能导致备份文件处于不一致状态。稳妥的做法是先在服务里用导出接口生成数据快照再复制数据目录或者停服务再复制。频率高且不想停机的话可以后续利用文件系统快照但本地搭建没必要一上来就做得太重。8.2 后续接入自动摘要和智能提醒本地搭建完成只是第一步。我计划在系列后续里做两件事一是接入本地推理服务让 OpenClaw 在保存日记时自动提取关键词、生成体重走势摘要二是针对疫苗到期、驱虫周期做提醒。这两项在本地搭建阶段都预留了接口只要把 config.yaml 里的 ai.enabled 打开再填上推理服务的地址就行。这样做的好处是整个智能分析过程都在内网完成宠物照片和健康记录不会为了一个摘要功能上传到外部。对在意隐私的人来说这个方向是值得投资的。8.3 多设备同步的最简方案如果不满足于只在电脑上访问想实现手机和电脑都能随时记录最轻量的做法是保持服务运行在电脑上手机通过局域网 IP 访问同一个 Web 页面。这个方案零配置但离开家就没法用。想在外网也访问本地方案传统思路是内网穿透、反向代理、动态域名这些组合但这会引入安全风险也不是必须的。我更推荐在笔记里记一句话本地是数据源云端只做加密备份不要直接把服务暴露到公网。对外出时临时记录可以用后续要讲的移动端离线模式回家后自动同步。这个部分比较复杂我会放在系列后续展开。最后分享一个搭建 OpenClaw 时的小习惯我会在电脑里建一个纯文本文件把第一只宠物的ID、配置文件的备份位置、备份任务的名字写在一起。别看它简陋每次换电脑、排查问题我都靠这份笔记快速找回现场。搭建本身不难难的是让这套系统愿意持续记录下去——建议你从今天为毛孩子补一条体重开始。