1. 项目概述为什么需要一个高效的指令手册如果你正在本地或服务器上折腾 OpenClaw也就是大家常说的“龙虾”大概率已经体验过它的强大和随之而来的复杂。这玩意儿本质上是一个 AI 智能体网关它像一个中央调度员帮你把 Ollama、各种大模型、以及像飞书、微信这样的外部应用连接起来让 AI 智能体Agent能真正“干活”。但问题来了它的配置项多如牛毛命令行参数、环境变量、配置文件层层嵌套新手很容易在docker-compose.yml、.env文件和五花八门的启动命令里迷失方向。我自己在部署和日常运维中最头疼的就是记不住那些关键命令。比如想临时换个模型试试效果或者查看某个技能Skill的运行日志又或者处理“智能体第二天就失忆”这种经典问题每次都得去翻文档或者查历史命令效率极低。网上的教程虽然多但往往只讲部署对于部署后如何高效管理、排查问题讲得比较零散。这就是我整理这份“常用指令手册”的初衷——它不是官方文档的复刻而是一个一线运维者从实战中沉淀下来的“速查清单”和“排坑指南”。无论你是刚用 Docker 把 OpenClaw 跑起来的新手还是已经在琢磨如何接入企业微信、优化响应速度的老鸟这份手册都能帮你节省大量翻找时间把精力聚焦在让 AI 智能体创造价值上。2. 核心架构与指令体系解析要玩转 OpenClaw 的指令首先得理解它的组件架构。它不是单个进程而是一组协同服务的集合。典型的 Docker 部署下你至少会接触到以下几个核心部分OpenClaw 主服务提供核心的 API 网关、智能体调度、会话管理等功能。这是指令操作的主要对象。数据库通常用 PostgreSQL 或 SQLite 存储会话、技能配置、用户数据等。很多“失忆”问题都源于此。消息队列如 Redis用于处理异步任务和事件驱动。模型服务通常是 Ollama也可以是 OpenAI API、智谱 AI 等。OpenClaw 通过配置的ollama_base_url和default_model与它们对话。技能服务一些复杂的 Skill 可能会以独立微服务的形式运行。因此OpenClaw 的指令可以大致分为三层容器生命周期管理、服务配置与状态查看、数据与运维操作。我们常用的命令基本都是围绕 Docker/Docker Compose 展开因为这是最主流的部署方式。2.1 容器生命周期管理指令这是最基础也最常用的部分。假设你的项目目录下有一个docker-compose.yml文件。启动与停止# 在后台启动所有服务-d 代表 detached mode docker-compose up -d # 启动并重新构建镜像修改了 Dockerfile 或依赖后 docker-compose up -d --build # 停止并移除所有容器、网络但保留卷和数据 docker-compose down # 停止服务但保留容器用于短暂暂停 docker-compose stop # 启动已停止的服务 docker-compose start注意docker-compose down不会删除 Docker 卷volume。你的数据库数据、配置文件如果挂载在卷里是安全的。但如果你用了匿名卷或想彻底清理需要加上-v参数docker-compose down -v这个操作会丢失所有持久化数据务必谨慎。查看状态与日志# 查看所有容器的运行状态 docker-compose ps # 查看 OpenClaw 主服务的实时日志-f 代表 follow docker-compose logs -f openclaw # 假设服务名在 compose 文件中定义为 openclaw # 查看所有服务的日志尾部最后100行 docker-compose logs --tail100 # 查看特定服务的日志并包含时间戳 docker-compose logs -f --timestamps openclaw日志是排错的第一现场。当你遇到 “openclaw llamap svr operator(): got exception: { “error”: { “code”: 400” 这类错误时第一时间就该用docker-compose logs openclaw查看详细错误堆栈通常能直接定位到是模型调用失败、配置错误还是网络问题。2.2 服务配置与状态查看指令服务跑起来后我们需要与之交互调整配置或查看内部状态。进入容器执行命令# 以交互模式进入 OpenClaw 容器的 bash 环境 docker-compose exec openclaw bash # 如果不支持 bash可以用 sh docker-compose exec openclaw sh # 不进入交互环境直接执行一个命令例如查看 Python 版本 docker-compose exec openclaw python --version进入容器内部非常有用比如你可以直接查看容器内的配置文件路径、检查依赖包版本或者运行一些 OpenClaw 提供的管理脚本。环境变量与配置检查OpenClaw 的配置大量依赖环境变量这些变量通常在.env文件或docker-compose.yml的environment部分定义。# 在宿主机上查看当前目录下的 .env 文件 cat .env # 在容器内查看所有环境变量 docker-compose exec openclaw env | grep -i “ollama” # 查找与 ollama 相关的环境变量一个常见的配置是OLLAMA_BASE_URL和DEFAULT_MODEL。确保OLLAMA_BASE_URL在容器内能访问到比如如果 Ollama 和 OpenClaw 在同一docker-compose网络中可以用服务名http://ollama:11434。DEFAULT_MODEL必须是 Ollama 中已拉取pull的模型名。重启单个服务修改了某个服务的环境变量或配置后无需重启整个栈可以单独重启。docker-compose restart openclaw2.3 数据与运维操作指令这部分指令关系到数据的持久化、备份和问题修复。数据库操作如果使用 PostgreSQL你可能需要连接数据库进行一些高级操作。# 进入数据库容器 docker-compose exec db bash # 假设数据库服务名为 db # 在数据库容器内连接 PostgreSQL psql -U openclaw -d openclaw_db # 用户名和数据库名根据你的配置调整 # 在 psql 中可以执行 SQL 语句例如查看会话表 SELECT * FROM sessions LIMIT 10;“智能体第二天就不知道昨天会话的内容了”这个问题九成原因在于会话session没有被正确持久化。你需要检查1. 数据库是否正常运行2. OpenClaw 的数据库连接配置是否正确3. 会话超时时间设置是否过短。通过直接查询数据库可以最快确认数据是否存在。备份与恢复数据卷# 备份名为 openclaw_db_data 的卷到宿主机当前目录 docker run --rm -v openclaw_db_data:/source -v $(pwd):/backup alpine tar czf /backup/db_backup_$(date %Y%m%d).tar.gz -C /source . # 恢复备份到数据卷谨慎操作会覆盖现有数据 docker run --rm -v openclaw_db_data:/target -v $(pwd):/backup alpine sh -c “rm -rf /target/* tar xzf /backup/db_backup_20231027.tar.gz -C /target”定期备份数据卷是好习惯尤其是在升级 OpenClaw 版本前。3. 高频问题与专用指令排坑实录光知道基础命令还不够实战中会遇到各种诡异问题。下面是我总结的几个高频场景及其对应的“药方”。3.1 模型连接失败openclaw llamap svr operator(): got exception这个错误信息{ “error”: { “code”: 400, “message”: … }是 OpenClaw 调用模型服务如 Ollama时返回的。排查思路如下检查 Ollama 服务状态# 如果 Ollama 也在 docker-compose 中 docker-compose logs ollama # 或者直接测试 Ollama API curl http://localhost:11434/api/tags # 宿主机访问 # 在 OpenClaw 容器内测试更准确 docker-compose exec openclaw curl http://ollama:11434/api/tags如果容器内无法访问说明 Docker 网络配置有问题。确保docker-compose.yml中 OpenClaw 和 Ollama 在同一个自定义网络下并且 OpenClaw 的环境变量OLLAMA_BASE_URL使用的是容器服务名如http://ollama:11434而不是localhost。检查模型是否存在# 进入 Ollama 容器查看已拉取模型 docker-compose exec ollama ollama list确保DEFAULT_MODEL环境变量里的模型名完全匹配ollama list列出的名字。大小写敏感。检查 OpenClaw 模型配置有时错误是因为 OpenClaw 的模型配置文件中对模型的参数如temperature,top_p设置超出了模型支持的范围。可以尝试在 OpenClaw 的管理界面或配置文件中换一个更简单的模型配置进行测试。3.2 技能安装与调试openclaw skill技能是 OpenClaw 的扩展能力。安装技能后出现问题很常见。# 假设技能通过 OpenClaw 的 CLI 或管理界面安装但失败了。 # 首先查看技能服务的独立日志如果技能以独立容器运行 docker-compose logs -f skill_weather # 假设技能容器名为 skill_weather # 其次查看 OpenClaw 主日志过滤技能相关错误 docker-compose logs openclaw | grep -i “skill” -A 5 -B 5 # 如果技能是 Python 包形式可以进入容器检查 docker-compose exec openclaw bash pip list | grep your-skill-name # 检查是否安装成功 find /app -name “*skill*” -type d # 查找技能目录技能安装失败除了网络问题经常是 Python 依赖冲突。一种解决思路是在自定义的 Dockerfile 里在安装 OpenClaw 核心包之后再单独安装技能包及其特定依赖。3.3 会话丢失与持久化配置这是最经典的“坑”。OpenClaw 的会话默认可能存储在内存或一个临时的 SQLite 数据库中。要确保持久化必须正确配置 PostgreSQL。确认数据库连接检查 OpenClaw 容器的环境变量确保DATABASE_URL类似postgresql://user:passworddb:5432/openclaw_db指向正确的数据库容器。检查数据库迁移OpenClaw 启动时应该自动运行数据库迁移migrations创建所需的表。查看启动日志docker-compose logs openclaw | grep -i “migrate” -A 2 -B 2如果没有迁移日志可能需要手动触发。这通常需要在项目源码中找到 Alembic 迁移脚本并执行但更规范的做法是确保你的 Docker 镜像或启动命令包含了迁移步骤。验证数据写入按照 2.3 节的方法连接数据库手动插入一条测试会话记录然后重启 OpenClaw 容器看记录是否还在。3.4 性能排查与监控指令当智能体响应变慢时需要一些命令来定位瓶颈。# 查看容器资源占用CPU、内存 docker stats # 查看 OpenClaw 容器的进程信息 docker-compose top openclaw # 如果怀疑是模型服务慢可以单独测试模型生成速度 # 在 Ollama 容器内直接运行一个生成测试注意这会消耗资源 docker-compose exec ollama ollama run llama3 “Hello, how are you?”如果发现 OpenClaw 容器内存持续增长可能是内存泄漏或会话数据积累过多。可以考虑调整会话清理策略或者为容器设置内存限制在docker-compose.yml中配置mem_limit。4. 进阶部署与配置管理实战对于生产环境或更复杂的场景仅仅docker-compose up是不够的。下面分享几个进阶的指令和配置技巧。4.1 多模型配置与管理OpenClaw 可以配置多个模型端点让不同的技能或用户组使用不同的模型。这通常通过在 OpenClaw 的配置文件可能是config.yaml或通过环境变量注入中定义多个模型配置来实现。但更动态的方式是利用 OpenClaw 的 API。不过在启动阶段我们可以通过环境变量预设一个默认模型。技巧使用.env文件管理多环境配置创建不同的环境文件如.env.prod,.env.test。# .env.prod OLLAMA_BASE_URLhttp://ollama-prod:11434 DEFAULT_MODELllama3:8b LOG_LEVELWARNING # .env.test OLLAMA_BASE_URLhttp://ollama-test:11434 DEFAULT_MODELgemma:2b LOG_LEVELDEBUG启动时指定环境文件docker-compose --env-file .env.prod up -d为不同技能指定模型这需要查阅 OpenClaw 的技能开发文档。通常在技能的config.json或元数据中可以指定其所需的模型能力或具体模型标识符。OpenClaw 的路由机制会根据这个标识符将请求转发到对应的模型端点。这部分的配置往往涉及更深的代码层面可能需要修改技能代码或 OpenClaw 的路由配置。4.2 与外部系统集成飞书/微信 Webhook 配置接入飞书或微信本质上是为 OpenClaw 配置一个 Webhook 接收器并在这两个平台的后台设置回调地址。确保 OpenClaw 公网可访问你需要一个域名或公网 IP并将 Docker 容器的端口如 8000映射出去或者通过 Nginx 反向代理。配置 OpenClaw 的 Webhook 端点这通常需要在 OpenClaw 的管理界面或配置文件中启用并配置相应的插件plugin或技能skill。例如安装openclaw-feishu或openclaw-wechat这类官方或社区提供的集成包。# 假设有命令行安装方式具体以集成包文档为准 docker-compose exec openclaw pip install openclaw-feishu # 安装后重启服务并配置环境变量 docker-compose restart openclaw需要配置的环境变量可能包括FEISHU_APP_ID,FEISHU_APP_SECRET,FEISHU_VERIFICATION_TOKEN等。在飞书/微信开放平台配置将 OpenClaw 的公网 URL如https://your-domain.com/feishu/webhook填写到对应平台的“事件订阅”或“消息接收”配置中并完成 Token 验证。关键排错指令# 查看 Webhook 相关的请求日志 docker-compose logs openclaw | grep -E “(feishu|wechat|webhook)” -i # 使用 curl 模拟飞书平台发送验证请求验证配置是否正确 curl -X POST https://your-domain.com/feishu/webhook \ -H “Content-Type: application/json” \ -d ‘{“type”: “url_verification”, “challenge”: “test123”}’集成失败时九成是网络或配置问题。确保公网地址能通且飞书/微信后台配置的 Token、密钥与 OpenClaw 环境变量完全一致。防火墙需放行 OpenClaw 服务端口。4.3 版本升级与数据迁移升级 OpenClaw 版本时最怕两件事服务起不来和数据丢了。安全升级指令流程# 1. 备份数据和配置文件 cp -r ./data ./data_backup_$(date %Y%m%d) cp .env .env_backup_$(date %Y%m%d) # 使用 2.3 节的方法备份数据卷更彻底 # 2. 拉取最新的镜像假设使用 latest tag生产环境建议用固定版本号 docker-compose pull # 3. 停止并移除旧容器 docker-compose down # 4. 使用新镜像启动 docker-compose up -d # 5. 密切观察日志看是否有数据库迁移报错 docker-compose logs -f openclaw如果启动失败最常见的错误是数据库表结构不兼容新版本需要迁移旧数据。这时需要回滚# 回滚到旧版本 docker-compose down docker-compose up -d --force-recreate # 使用旧的镜像如果本地还有缓存 # 或者修改 docker-compose.yml将 image tag 指回旧版本号再 up -d重要心得生产环境升级前一定要在测试环境用备份的数据完整走一遍流程。仔细阅读目标版本的 Release Notes看是否有破坏性变更Breaking Changes特别是数据库迁移说明。5. 日常维护与效能提升技巧最后分享几个让 OpenClaw 运行得更稳、更顺手的日常指令和习惯。日志轮转与清理OpenClaw 的日志如果不加管理会占满磁盘。# 在 docker-compose.yml 中为服务配置日志驱动和大小限制 # 示例 # services: # openclaw: # image: ... # logging: # driver: “json-file” # options: # max-size: “10m” # max-file: “3”配置后单个日志文件超过10M就会轮转最多保留3个历史文件。健康检查与自动重启在docker-compose.yml中配置健康检查确保服务挂掉后能自动恢复。services: openclaw: image: your-openclaw-image healthcheck: test: [“CMD”, “curl”, “-f”, “http://localhost:8080/health”] # 假设有健康检查端点 interval: 30s timeout: 10s retries: 3 start_period: 40s restart: unless-stopped一键清理无用资源长期开发测试会积累很多停止的容器、悬空镜像、无用网络。# 清理所有已停止的容器 docker container prune -f # 清理所有未被使用的镜像谨慎会删除所有未被容器引用的镜像 docker image prune -a -f # 清理所有未被使用的网络 docker network prune -f # 清理所有未被使用的卷最危险会删除数据务必先确认 docker volume prune -f建议将docker system df命令加入日常巡检查看 Docker 资源使用情况。利用 Docker Compose Override对于开发、测试、生产的不同配置不要复制多个docker-compose.yml。使用docker-compose.override.yml或指定多个配置文件。# 创建 docker-compose.prod.yml 用于生产特定配置 # 启动时合并使用 docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d这样能保持基础配置的纯净只在不同环境覆盖差异部分如环境变量、资源限制。说到底管理 OpenClaw 就像运维任何一个微服务集群核心思路是一样的状态可观测、变更可追溯、数据可恢复、问题可定位。这份指令手册里的命令就是实现这“四可”目标的工具。刚开始可能会觉得命令繁多但用多了就会形成肌肉记忆。最关键的还是理解每个命令背后的意图——你到底是想查看状态、修改配置、还是抢救数据想清楚了再翻看这份手册找到对应的命令效率自然就上来了。
