OpenClaw 是近期在 AI Agent 工程实践里经常被讨论的一个可本地部署的智能体运行时。它把模型接入、技能扩展、消息渠道和运行时管理整合到一起让开发者可以像搭积木一样搭建自己的 AI 助手。团队在推进 AI 前沿构建时选择 OpenClaw核心原因是开放模型可以切换技能可以自己写渠道可以接微信和飞书并且支持 Docker 本地部署。这篇实践记录会围绕一次完整落地流程展开内容包括环境准备、Docker 部署、模型接入、Skill 编写、IM 渠道接入和典型报错排查。读完后你可以独立复现一个可对话、可扩展工具、可接入 IM 的本地 Agent。1. 先理解 OpenClaw 在 AI Agent 构建中的定位1.1 OpenClaw 解决的是什么问题AI Agent 和普通聊天机器人的最大区别是 Agent 需要“执行动作”而不只是“生成文本”。大模型本身只能根据提示词和上下文输出内容无法直接读取数据库、调用接口、发送消息。要让模型完成这些事必须有一条链路把模型输出解析成工具调用把工具执行结果回传给模型再让模型根据结果继续推理。OpenClaw 把这条链路封装成了可运行的 Agent 运行时。它提供会话管理、工具调用、记忆持久化、模型切换、IM 渠道接入等能力。你可以把它理解成一个“Agent 操作系统”不是某一个具体聊天应用而是一套可以用来构建各种 Agent 应用的底座。1.2 为什么团队会强调本地部署团队在 AI 前沿构建中强调 OpenClaw不是因为它的默认配置有多强而是因为它的架构允许团队把 Agent 变成一个可以持续迭代的工程系统而不是一段演示代码。本地部署带来的直接收益有三点数据不离开本机。用户消息、知识库内容、工具调用记录可以控制在本地适合企业内部场景和隐私敏感场景。模型可替换。没有绑定单一厂商可以随时切换云端模型、NVIDIA NIM 服务或本地模型。调试成本低。可以直接看日志、改配置、重启容器不需要等待云端发布流程。这一点在接入模型时尤其重要。一个只在演示环境跑通的 Agent 并不难难的是在生产环境里能换模型、能排错、能扩展技能这些都需要部署能力可控。1.3 核心能力边界与架构分层OpenClaw 的能力可以大致分成四层能力层作用典型场景模型层管理不同模型的接入、切换和调用OpenAI、NVIDIA NIM、Ollama 本地模型运行时负责 Agent 会话、工具调用、记忆和状态管理多轮对话、工具调度、上下文维护技能层把外部 API 或固定流程封装成 Agent 可调用的工具查天气、查库存、写周报、调用业务接口渠道层将 Agent 对接到不同消息入口微信、飞书、Control UI 网页在实际使用中模型层和渠道层最容易让新手产生误解。模型层不是“选一个大模型”就结束了还要确认base_url、model、api_key是否匹配。渠道层也不只是“发消息”还要处理消息格式转换、回调地址、鉴权和超时。2. 环境准备Docker、Node.js 与部署前检查2.1 部署前需要准备什么OpenClaw 的常见部署方式有两种使用 Docker 本地部署或者直接安装 Node.js 版本。无论哪一种都需要先确认以下几个方面Docker 或 Podman 等容器运行时。Node.js 运行时。如果只使用 Docker 部署Node.js 不是必须的但二次开发、安装部分插件、排查node runtime not found报错时需要本地 Node.js。足够的内存和磁盘空间。模型推理和 Agent 状态管理都会占用资源。一个可用的模型 API Key或可访问的本地模型服务。硬件门槛取决于使用场景。这里给出一个常见项目的起步参考场景硬件建议依赖Mac mini 本地试水16G 内存以上256G 磁盘Docker DesktopWindows 开发环境16G 内存SSDDocker Desktop / Node.js LTS生产级 Linux 服务器32G 内存SSD稳定网络Docker Engine、日志与监控组件说明这里的依赖版本以实际安装时为准不要在落地前直接照抄教程里的固定版本号要先确认 Docker 镜像和 OpenClaw 当前版本的兼容关系。2.2 Mac mini 使用 Docker 本地部署的基础方案Mac mini 做本地 Agent 测试是比较常见的选择。原因是功耗低、常驻运行成本低并且可以通宵跑任务。使用 Docker 部署时核心步骤是把数据目录挂载到宿主机把 Control UI 端口映射出来。docker pull openclaw/openclaw:latest mkdir -p ~/.openclaw docker run -d --name openclaw \ -p 3000:3000 \ -v ~/.openclaw:/root/.openclaw \ -e OPENCLAW_MODEL_PROVIDERopenai \ -e OPENCLAW_MODELdeepseek-chat \ --restart unless-stopped \ openclaw/openclaw:latest这段命令里-p 3000:3000把容器内的 3000 端口映射到本机-v ~/.openclaw:/root/.openclaw把配置和数据目录持久化到宿主机--restart unless-stopped让容器在机器重启后自动拉起。OPENCLAW_MODEL_PROVIDER和OPENCLAW_MODEL只是示例实际环境要根据你自己的模型服务调整。启动后用docker ps确认容器状态再用curl http://localhost:3000检查 Control UI 是否返回 HTTP 响应。2.3 Windows 部署时的运行时问题Windows 用户直接安装时常遇到oneclaw node runtime not found。虽然项目名是 OpenClaw但部分安装器或脚本里的报错文本可能写成了 oneclaw。报错本质是安装器在系统里找不到 Node.js 运行时。处理方式node -v npm -v where node如果node -v有输出说明系统里已经安装了 Node.js问题通常出在 PATH 环境变量没有刷新或者安装器读取不到当前终端的 PATH。建议安装 Node.js LTS 版本后重新打开终端再执行安装命令。如果仍然报错最简单的方式是放弃直接安装改用 Docker 部署避免在系统依赖上浪费时间。2.4 配置文件的基本结构无论使用 Docker 还是直接安装OpenClaw 都会在用户目录下生成一个数据目录。常见结构大致如下~/.openclaw/ ├── config.json ├── skills/ ├── memory/ ├── logs/ └── credentials.jsonconfig.json保存模型 provider 和 Agent 行为配置skills目录放自定义技能memory目录用于记忆持久化logs目录保存日志。不同版本的目录命名可能有差异但整体思路是统一的配置、技能、记忆、日志分离。这里要注意不要在容器运行的时候手动修改宿主机挂载目录里的配置文件否则可能出现配置被容器覆盖或写入冲突。推荐修改配置后重启容器让配置重新加载。3. 用最小案例完成 OpenClaw 初始化3.1 拉取镜像并启动如果你是第一次部署建议先把容器跑起来再看 Control UI 是否正常启动。不要跳过日志检查很多初始化失败只有日志里能看到。docker ps docker logs -f openclaw日志中如果出现服务启动成功的提示再访问http://localhost:3000。出现Control UI did not start时先看端口映射和启动日志再检查数据目录权限不要急着重装。3.2 首次初始化流程首次打开 Control UI 时通常需要完成三件事填写模型 API Key或选择已经配置好的 provider。选择默认模型。创建 Agent 名称和系统提示词。这里的核心是OpenClaw 本身不生产模型能力所有对话推理都需要模型服务支持。模型凭据配置错误会让后续所有对话全部失败。所以初始化时第一步配置模型第二步验证对话第三步再考虑加技能和接渠道。3.3 验证第一个对话在 Control UI 中发送第一条消息例如“你好请介绍你的能力和技能”。如果模型配置正确会收到正常回复。如果直接报agent failed before reply或the agent run failed before producing a reply优先检查三点模型名称是否被 provider 支持。API Key 是否有权限调用该模型。base_url 是否可达。这些检查可以使用 curl 直接调用模型接口验证而不是只看 OpenClaw 的日志。3.4 初始化时的关键配置项配置项说明检查要点model_provider模型服务商是否与 base_url 匹配model模型名称名称是否与 provider 文档一致api_keyAPI 密钥是否有权限调用目标模型base_url模型服务地址是否可访问、是否包含 /v1 路径只要这四个字段对应正确大多数对话初始化问题都能解决。最容易踩的坑是模型名称写错或者把 base_url 少了/v1后缀。4. 多模型接入与切换4.1 模型层抽象一个 Agent 要支持多模型需要把 provider、base_url、model、api_key 分开管理。OpenClaw 的模型配置通常也是这套结构。常见需求有两种日常对话用云端模型复杂任务用本地模型。从 OpenAI 兼容接口切换到 NVIDIA NIM或者切换到 DeepSeek 等国内模型服务。多模型接入的收益是明显的可以按成本、隐私、推理速度、任务复杂度选择不同模型。但代价是配置项变多模型切换时的错误排查链路会变长。4.2 接入 NVIDIA NIM“openclaw 配置 nvidia nim”是一个高频需求。NVIDIA NIM 提供 OpenAI 兼容的推理服务配置方式与接入 OpenAI 兼容接口相似{ model_provider: nvidia_nim, model: meta/llama-3.3-70b-instruct, base_url: https://integrate.api.nvidia.com/v1, api_key: 替换为你的密钥 }这里最需要注意的是模型名称。NVIDIA NIM 的模型名称通常带命名空间例如meta/llama-3.3-70b-instruct。模型名称写错时服务端可能返回 404 或model not found。base_url 尾部的/v1也容易丢丢失后 OpenClaw 可能会发出带错误路径的请求。4.3 本地模型接入如果希望请求不离开局域网可以使用 Ollama 或其他本地推理服务。假设本地 Ollama 地址是http://localhost:11434配置示例{ model_provider: openai_compatible, model: qwen2.5:7b, base_url: http://localhost:11434/v1, api_key: ollama }如果 OpenClaw 运行在 Docker 容器里localhost指向容器内部而不是宿主机。此时需要把地址改成http://host.docker.internal:11434/v1Mac 和 Windows 的 Docker Desktop 都支持这个特殊主机名。Linux 上则可以使用http://172.17.0.1:11434/v1具体取决于 Docker 网络配置。4.4 多模型切换的正确操作配置多个 provider 后切换模型是高频操作。常见做法是在 Control UI 的模型配置里新增多个模型再在会话中选择当前模型。切换时注意以下几点保存配置后确认 OpenClaw 已经重新加载配置。切换模型后最好新开一个会话避免旧会话中的工具调用状态干扰新模型。如果 UI 上的模型列表没有刷新重启容器或重新加载配置。“我 OpenClaw 的切换模型”这种表达背后通常是对应两个问题一个是不知道在哪里切换另一个是切换后报错。前者看 UI 的 model 选择位置后者参考下一节的排查方法。4.5 切换模型后报 agent failed before reply这个报错非常通用需要分层排查排查层检查项验证方式模型层模型名、API Key、base_url用 curl 直接调用模型接口运行时层会话状态、上下文是否异常查看 OpenClaw 日志技能层自定义 Skill 是否抛错禁用 Skill 后重试渠道层IM 回调是否超时或鉴权失败查看渠道适配器日志切换模型后出现的agent failed before reply多半是模型不支持当前会话里已经存在的工具调用格式或者模型上下文窗口较小导致输出被截断。判断方法很简单把同一请求切回原模型如果恢复说明问题在模型差异如果仍然失败则问题在运行时或连接器。5. 如何编写 Skill 并接入外部 API5.1 Skill 机制到底做了什么Skill 是 OpenClaw 中把“一个能力”封装成 Agent 可调用工具的单元。模型通过工具调用协议决定是否调用某个 SkillSkill 执行完后把结果返回给模型。你可以把 Skill 理解成 Agent 的“手”和“脚”。这样做的好处是模型不需要知道 API 内部细节。新能力只需要新增一个 Skill不用修改 Agent 主流程。Skill 可以被多个场景复用。一个常见的误区是把 Skill 当成“提示词模板”。实际上 Skill 需要可执行代码和明确的输入输出结构否则模型无法稳定调用。5.2 Skill 目录结构与最小示例典型 Skill 目录结构如下skills/ └── weather/ ├── SKILL.md └── run.pySKILL.md负责描述技能用途、参数和调用方式run.py负责执行逻辑。最小SKILL.md示例# 查天气 通过城市名查询实时天气。 参数 - city: 字符串城市名例如北京这里的关键是参数描述要足够清晰模型才知道如何生成调用参数。如果参数描述模糊模型可能会传错参数名或参数类型。5.3 让 Skill 调用外部 HTTP API以查询天气为例run.py可以写成这样import json import urllib.request def run(city: str): url fhttps://api.example.com/weather?city{city} try: with urllib.request.urlopen(url, timeout10) as resp: data json.load(resp) except Exception as exc: return json.dumps({error: str(exc)}) return json.dumps({city: city, weather: data.get(weather)})代码里做了两件重要的事设置超时、把异常转成 JSON 返回。如果不设置超时模型调用 Skill 时可能长时间卡住如果不捕获异常Skill 抛错会让整个 Agent 运行失败。Skill 返回给模型的是一段字符串所以返回结构越清晰模型越容易理解。推荐统一使用 JSON 文本字段名直观。5.4 编写 Skill 时的规范与常见坑参数必须声明清楚。模型根据SKILL.md生成参数描述越准确调用越稳定。不要在原函数里打印大量调试信息。打印内容会混入返回结果影响模型判断。外部 API 的 Key 不要硬编码在 Skill 文件里要放到配置或环境变量。网络请求必须设置超时。失败时返回明确错误信息而不是空字符串。一个常见坑是把 Skill 当成普通 Python 文件随意导入第三方库但部署环境没有安装这些依赖。在本地开发环境能跑进入 Docker 容器就报 ModuleNotFoundError。解决方式是在 Skill 部署说明里写明依赖或者在 Dockerfile 里提前安装。6. 接入飞书、微信等 IM 渠道6.1 为什么要把 Agent 接入 IM把 OpenClaw 接到飞书、微信是为了让 Agent 出现在用户日常沟通的地方而不是只在网页里使用。IM 渠道的价值非常直接用户在聊天框里就能完成任务不需要打开独立系统也不需要学习新的操作界面。对接 IM 之后日常使用就变成了“给 Agent 发一条消息Agent 自动回复并执行动作”。这也让收集需求、记录工单、查询信息等操作变得更自然。6.2 飞书接入流程接入飞书通常需要以下几个步骤在飞书开放平台创建企业自建应用。开启应用机器人能力。获取 App ID 和 App Secret。配置事件订阅把消息事件地址指向 OpenClaw 的回调接口。配置示例{ channel: feishu, app_id: cli_xxx, app_secret: 替换为密钥, event_callback_url: https://你的公网域名/openclaw/webhook/feishu }这里最容易出问题的是回调地址。本地调试时没有公网域名飞书服务端无法访问你的回调接口需要使用内网穿透工具把本地端口暴露到公网。生产环境则必须使用 HTTPS 域名并配置好证书。回调地址配置正确后可以打开飞书应用给机器人发一条消息验证是否能收到回复。6.3 微信接入的边界与合规提醒微信个人号接入存在账号风险。个人号自动回复、自动发消息的行为可能触发限制不建议在个人号上做自动化。如果业务确实需要可以优先选择企业微信或微信官方开放能力从源头上避免账号异常。接入微信的方案有多种但无论选择哪种都要先确认两个问题渠道是否合规账号是否允许机器人行为。团队项目中账号安全优先级高于功能便利性这一点要提前和技术负责人对齐。6.4 从 IM 消息到 Agent 回复的流转链路IM 消息进入 OpenClaw 后会经过一条固定链路飞书/微信消息 - 渠道适配器 - Agent 会话管理 - 模型推理 Skill 调用 - 生成回复 - 渠道适配器 - 发回 IM这条链路说明核心业务逻辑在 Agent 层渠道层只负责消息格式转换。新增一个新渠道时不应该修改模型和 Skill 逻辑只需要新增渠道适配器。排查 IM 消息问题时要先确认消息到底卡在哪一层。飞书回调没到 OpenClaw是渠道层问题消息到了但 Agent 没回复是运行时或模型层问题。7. 常见问题排查清单7.1 Control UI did not start现象容器启动后访问 3000 端口没有界面或者一直转圈。可能原因端口映射失败。容器启动过程中出现异常。挂载目录权限不足OpenClaw 无法写入配置。模型配置错误导致服务启动后初始化失败。检查顺序docker ps docker logs openclaw --tail 100 curl http://localhost:3000如果日志显示端口被占用修改宿主端口映射如果日志显示没有权限写入目录检查宿主机目录权限。这里要注意不要急着删除容器里已经写好的配置先备份再重装。7.2 Windows 安装时提示 oneclaw node runtime not found现象安装过程中直接退出报错信息包含node runtime not found。可能原因Node.js 没有安装。Node.js 已经安装但 PATH 环境变量未刷新。安装器读取不到当前终端的 PATH。处理方式node -v npm -v where node如果node -v没有输出安装 Node.js LTS 版本后重启终端。如果已经安装重新打开终端后再执行安装。如果仍报错直接把 Node.js 安装目录加入 PATH或者改用 Docker 部署。7.3 the agent run failed before producing a reply现象发送消息后Agent 没有回复日志或 UI 中出现the agent run failed before producing a reply。可能原因模型名称写错。API Key 无效或没有权限。base_url 不可达。模型不支持工具调用格式。自定义 Skill 抛出了未捕获异常。上下文过长超出模型上下文窗口。排查顺序先用 curl 直接调用模型接口确认模型层正常。查看 OpenClaw 日志确认异常发生在哪个模块。禁用自定义 Skill再跑一次对话。如果切换模型后出现切回原模型对比。问题现象常见原因检查方式处理建议切换模型后报错新模型不支持工具调用查看模型文档换支持工具调用的模型停用 Skill 后恢复Skill 抛错查看 Skill 日志捕获异常并返回错误信息所有模型都失败base_url 或网络问题curl 访问模型接口修复网络或地址7.4 多模型配置不生效现象切换模型后实际请求仍然走旧模型。可能原因配置缓存未刷新。在错误的配置环境里修改了模型参数。容器没有重启配置没有重新加载。处理方式保存配置后重启容器在日志中确认加载的 provider 和 model。重启后仍然不生效说明修改的位置不对不要反复点击保存先确认配置文件的路径和加载顺序。7.5 排查顺序建议现场排查问题时优先按这个顺序推进输入是否正确。检查消息是否真的发到了 OpenClaw。文件路径和命名是否正确。配置文件、Skill 目录是否放对位置。依赖版本是否匹配。Node.js、Docker 镜像、模型名称是否与当前版本兼容。配置是否生效。重启容器后观察日志。权限、端口、网络、环境变量是否正确。日志中是否有明确异常。工具或框架本身是否存在版本限制。不要一上来就卸载重装。大部分 OpenClaw 报错都不是程序损坏而是配置、路径或网络问题。8. 最佳实践与下一步扩展方向8.1 生产环境部署建议从本地测试环境切换到生产环境前需要补齐以下能力配置外置化。api_key、app_secret等敏感信息不要写死在config.json里改用环境变量或密钥管理服务。日志和监控。日志要能按会话 ID 检索监控要覆盖模型调用成功率、延迟和错误率。权限控制。只给容器最小权限数据目录和配置文件权限要收紧。异常处理。所有 Skill 都要捕获异常并返回明确错误不能让未处理异常中断 Agent。回滚方案。多个模型配置要形成可切换的备份避免单点故障。8.2 团队二次开发时的代码组织如果团队要在 OpenClaw 基础上做二次开发建议按模块拆分代码packages/ ├── core/ # Agent 核心逻辑 ├── skills/ # 业务技能 ├── channels/ # IM 渠道适配 └── models/ # 模型 provider 配置不要在 Skill 里写业务数据库访问逻辑。Skill 更适合做薄适配层把外部 API 包装成模型可理解的工具。复杂的业务逻辑应该放到独立服务里由 Skill 通过 HTTP 调用。这样做的好处是模型升级、渠道更换、Skill 扩展可以互不影响。团队里有人改 Skill 时不需要动核心逻辑冲突风险也会降低。8.3 从单机 Agent 到多 Agent 架构当一个 Skill 的逻辑变复杂后可以考虑把特定任务拆成独立服务由 OpenClaw 通过 HTTP 调用。比如把“生成周报”拆成一个独立服务OpenClaw 只负责编排先查数据再调用周报服务然后返回结果给用户。这样的架构下Agent 只做编排业务逻辑由微服务负责。容量扩展、权限控制、故障隔离都可以独立处理。这是从单机 Agent 走向生产级 Agent 平台的自然演进方向。8.4 发布前检查清单每次部署或发布前逐项确认模型 provider、model、base_url、api_key 是否匹配。Control UI 能否打开日志中是否无异常报错。至少完成一次正常对话。至少完成一次 Skill 调用。IM 回调地址是否可访问能否收到消息。容器重启后配置和数据是否保留。生产环境是否有日志、监控、权限、回滚方案。敏感信息是否已经外置没有硬编码在配置中。OpenClaw 这类工具代表的不是某个固定答案而是一条可以继续扩展的 Agent 工程路径。真正的价值来自团队能控制部署、模型和工具而不是只能使用一个黑盒网页。对新手来说最有价值的练习是先完成本地部署再写一个真正会调用外部 API 的 Skill最后接一个真实 IM 渠道。把这条链路走通后再切换到其他 Agent 框架也会很快上手。
