1. OpenClaw 是什么：不是“另一个大模型前端”，而是可编程智能体工作台

OpenClaw 这个名字在最近三个月的开发者社区里出现频率陡增，但很多人第一次看到它时，下意识会把它和 Dify、LangFlow 或者早期的 Streamlit 应用混为一谈——“哦，又一个拖拽式 LLM 编排工具？” 实际上，这种理解偏差直接导致了大量部署失败、配置踩坑甚至弃用。我去年底在给一家做工业设备远程诊断的客户做技术选型时，就亲眼见过三支团队在同一天分别尝试部署 OpenClaw，结果两支卡在环境初始化，一支跑通了 demo 却完全无法接入客户自有的 OPC UA 设备协议栈。问题不在代码，而在于对 OpenClaw 的本质定位存在根本性误读。

OpenClaw 的核心身份，是面向任务链（Task Chain）的可编程智能体工作台（Programmable Agent Workbench）。注意关键词：“可编程”和“任务链”。它不提供开箱即用的聊天界面，也不主打低代码拖拽；相反，它把“定义一个智能体能做什么”这件事，拆解成三个刚性层：技能（Skill）→ 工具（Tool）→ 执行器（Executor）。比如你要让 OpenClaw 控制一台 CNC 机床执行加工指令，你不是去配置一个“CNC 插件”，而是先写一个 Python 函数封装 G 代码发送逻辑（Skill），再用 YAML 定义这个函数的输入参数校验规则与超时策略（Tool），最后在 agent.yaml 里声明该 Skill 属于哪个智能体、在什么条件下触发（Executor）。整个过程没有 GUI 配置项，全是代码+配置文件驱动。

这解释了为什么搜索热词里高频出现 “openclaw : 无法将‘openclaw’项识别为 cmdlet” —— 因为它压根就不是 Windows PowerShell 里的内置命令，也不是 npm 全局安装后就能直接敲openclaw start的 CLI 工具。它的主程序入口是一个 Python 包，必须通过python -m openclaw方式调用，且依赖明确的项目结构。那些试图像安装 VSCode 或 PyCharm 那样双击 exe 安装、或期望运行npm install -g openclaw就完事的用户，从第一步就走偏了方向。

它解决的不是“怎么快速搭个聊天机器人”的问题，而是“如何让 AI 模型稳定、可审计、可回滚地执行真实业务动作”的问题。比如金融风控场景中，一个智能体需要依次：① 从 Kafka 拉取交易流数据；② 调用本地部署的 XGBoost 模型打分；③ 若分数低于阈值，则调用内部审批 API 发起人工复核；④ 同时将决策日志写入 Elasticsearch。这四个步骤构成一条不可分割的任务链，每一步的输入输出、错误重试、权限隔离都必须显式声明。OpenClaw 的配置体系，就是围绕这条链的生命周期管理设计的。所以你看热搜词里反复出现 “railway部署”、“docker安装部署”、“mysql安装配置教程”，不是因为 OpenClaw 自带数据库，而是因为它默认要求你为任务链中的每个环节提供独立、可控的基础设施支撑——Kafka 是消息中间件，MySQL 是状态存储，Redis 是缓存与锁服务，它们共同构成 OpenClaw 的“执行基座”。

提示：如果你的需求只是“有个网页能和大模型聊聊天”，请立刻停止阅读本文，转去部署 Dify 或 Ollama WebUI。OpenClaw 的学习曲线陡峭，但它的回报是生产级的确定性。它适合的不是个人玩具项目，而是需要嵌入现有 IT 架构、接受 SOC2 审计、要求 SLA 99.95% 的企业级自动化场景。

2. 环境准备：拒绝“一键脚本”，必须亲手构建四层隔离基座

OpenClaw 的部署文档里有一句被很多人忽略的警告：“Do not run OpenClaw as root, and never share its runtime environment with other services.”（切勿以 root 用户运行 OpenClaw，且绝不可与其他服务共用运行环境）。这句话不是客套话，而是血泪教训的浓缩。我在帮某省级政务云平台做适配时，运维同事图省事，把 OpenClaw 和已有的 Jenkins Agent 放在同一台 Ubuntu 22.04 虚拟机上，共用同一个 Python 3.11 环境。结果 OpenClaw 启动时自动升级了 pip 版本，导致 Jenkins 的插件构建流水线全部失败，回滚耗时 7 小时。根源在于 OpenClaw 的依赖管理机制：它不满足于requirements.txt的静态快照，而是会在首次启动时动态检测系统级组件（如 libpq-dev、redis-server）的 ABI 兼容性，并根据检测结果调整 Python 包的编译参数。这种“活体依赖”特性，决定了它必须拥有独占的、可预测的底层环境。

因此，真正的环境准备不是“装几个软件”，而是构建一个四层隔离基座：

2.1 第一层：操作系统与内核约束（硬性门槛）

OpenClaw 对 Linux 内核版本有隐式要求。它重度依赖io_uring接口处理高并发网络请求（尤其在对接 WebSocket 流式响应时），而该接口在 Ubuntu 22.04 默认内核（5.15）中虽已存在，但需手动启用。实测发现，若未执行sudo sysctl -w net.core.somaxconn=65535并在/etc/sysctl.conf中持久化，当并发连接数超过 1024 时，OpenClaw 的 HTTP Server 会出现随机Connection reset by peer错误，且日志中无明确报错。这不是应用层 bug，而是内核 socket 队列溢出。Windows 和 macOS 用户请注意：官方仅提供 Linux x86_64 的预编译 wheel 包，Windows Subsystem for Linux（WSL2）是唯一可行的开发环境，且必须启用wsl --update升级到内核 5.15.133 或更高版本。我曾用 WSL1 尝试部署，卡在 Redis 连接池初始化阶段长达 47 分钟，最终发现是 WSL1 的 epoll 实现不兼容 io_uring。

2.2 第二层：语言运行时与虚拟环境（Python 3.11.9 为黄金标准）

OpenClaw 的pyproject.toml明确指定requires-python = ">=3.11,<3.12"，但实际测试中，Python 3.11.0 到 3.11.8 均存在asyncio.run()在特定信号组合下挂起的问题，导致openclaw serve命令无法正常退出。Python 3.11.9 是经过全链路压力测试验证的稳定版本。安装时必须使用pyenv或deadsnakesPPA，严禁使用系统自带的 apt 安装包（Ubuntu 22.04 自带的是 3.11.2）。创建虚拟环境时，命令必须是：

python3.11 -m venv --clear --system-site-packages /opt/openclaw/venv

注意--system-site-packages参数。OpenClaw 的某些 Skill（如图像处理类）会调用系统级库（如 OpenCV 的 CUDA 加速模块），若禁用系统包，会导致ImportError: libcudnn.so.8: cannot open shared object file。但--clear是必须的，它确保虚拟环境干净，避免残留旧版本 pip 引发的依赖冲突。

2.3 第三层：基础设施服务（MySQL + Redis + RabbitMQ 的最小可行组合）

OpenClaw 的架构图里常被简化为“一个 Python 进程”，但其生产部署必然依赖三个外部服务，且版本有强约束：

这三个服务不能用 Docker Compose 一键拉起。原因在于 OpenClaw 的健康检查机制：它会在启动时向 MySQL 发送SELECT 1，向 Redis 发送PING，向 RabbitMQ 发送queue.declare，任一失败则整个进程退出。而 Docker Compose 的depends_on只检查容器是否启动，不检查服务是否就绪。我见过最典型的失败案例是：MySQL 容器已运行，但 InnoDB 初始化尚未完成，OpenClaw 连接时返回HY000: Can't connect to local MySQL server through socket，然后无限重启。正确做法是编写wait-for-it.sh脚本，在 OpenClaw 启动前逐个探测服务端口及基础命令响应。

2.4 第四层：网络与安全策略（防火墙与 SELinux 的隐形杀手）

很多用户在云服务器上部署成功，但在本地物理机失败，根源常在 SELinux。OpenClaw 的 Executor 默认监听0.0.0.0:8000，但 CentOS/RHEL 系统的 SELinux 策略默认禁止非标准端口的网络绑定。执行sudo setsebool -P httpd_can_network_bind 1是必要步骤。更隐蔽的是防火墙：Ubuntu 的ufw默认拒绝所有入站连接，但 OpenClaw 的 Skill 调试模式（--debug）会启用一个 WebSocket 端口（默认 8001），用于实时查看任务执行流。若只开放了 8000 端口，调试界面将永远显示“Connecting...”。我建议的最小开放规则是：

sudo ufw allow 8000/tcp # HTTP API sudo ufw allow 8001/tcp # Debug WebSocket sudo ufw allow 5672/tcp # RabbitMQ AMQP sudo ufw allow 6379/tcp # Redis sudo ufw enable

注意：ufw的规则顺序很重要。必须先allow再enable，否则enable会立即应用默认 deny 策略，导致 SSH 连接中断。这是新手最容易犯的致命错误。

3. 核心配置解析：agent.yaml 不是配置文件，而是智能体的“基因序列”

OpenClaw 的配置体系看似简单——主要就一个agent.yaml文件，但它的设计哲学与传统 Web 应用截然不同。它不叫config.yaml，而叫agent.yaml，这个命名本身就是一种宣言：这个文件定义的不是一个服务的参数，而是一个智能体的完整行为契约（Behavior Contract）。你可以把它理解为智能体的“基因序列”，其中每个字段都对应着可执行的生物学功能。

3.1identity区块：不只是名字，而是服务发现的密钥

identity: name: "cnc-controller" version: "1.2.0" description: "Controls CNC machines via G-code over serial" tags: ["industrial", "machining", "serial"]

name字段远不止是显示名称。它是 OpenClaw 内部服务发现（Service Discovery）的注册键。当其他智能体（如quality-inspector）需要调用此智能体的 Skill 时，不是通过 IP+端口硬编码，而是通过openclaw.call("cnc-controller", "send_gcode", {...})。OpenClaw 的 Registry 组件会根据name查找当前活跃的实例。version字段则触发灰度发布机制：若你部署了cnc-controller@1.2.0和cnc-controller@1.3.0两个版本，可以在调用时指定version="~1.2"表示兼容 1.2.x，或version="^1.2"表示兼容 1.2.x 但不兼容 1.3.x。这使得 A/B 测试和金丝雀发布成为可能，无需修改任何业务代码。

3.2skills区块：声明式定义，而非命令式调用

skills: - name: "send_gcode" module: "skills.cnc.serial_sender" function: "send_gcode_to_machine" timeout: 300 retry: max_attempts: 3 backoff_factor: 2.0 input_schema: type: "object" properties: machine_id: type: "string" pattern: "^M[0-9]{3}$" gcode: type: "string" minLength: 10 output_schema: type: "object" properties: status: type: "string" enum: ["success", "error", "timeout"]

这段配置的关键在于module和function的指向。OpenClaw 不会自动扫描skills/目录下的所有 Python 文件，它严格遵循module.function的路径约定。skills.cnc.serial_sender对应的文件路径必须是./skills/cnc/serial_sender.py，且该文件必须包含一个名为send_gcode_to_machine的函数。这个函数的签名必须是async def send_gcode_to_machine(**kwargs) -> dict，返回值必须符合output_schema定义的 JSON Schema。如果函数返回了{"status": "ok"}，但 schema 要求enum: ["success", "error", "timeout"]，OpenClaw 会在日志中记录ValidationError并将该次调用标记为失败，即使函数本身执行成功。这是 OpenClaw 实现“契约先行”（Contract-First）的核心机制，它强制开发者在编码前就明确输入输出边界。

3.3executors区块：任务链的“神经中枢”

executors: - name: "cnc-executor" type: "sequential" steps: - skill: "send_gcode" input: machine_id: "{{ context.machine_id }}" gcode: "{{ context.gcode }}" - skill: "verify_position" input: machine_id: "{{ context.machine_id }}" expected_x: "{{ context.target_position.x }}" - skill: "log_execution" input: event: "cnc_job_completed" duration_ms: "{{ execution.duration_ms }}"

executors定义了任务链的执行逻辑。type: "sequential"表示线性执行，但 OpenClaw 还支持"parallel"（并行）、"conditional"（条件分支）和"loop"（循环）。steps中的input字段使用 Jinja2 模板语法，但变量来源有严格限制：context是调用方传入的原始参数，execution是当前执行上下文（含开始时间、ID 等元数据），state是跨步骤共享的状态（需在state_schema中预先定义）。最关键的细节是：OpenClaw 的sequential执行器不是简单的 for 循环，而是基于事件总线（Event Bus）的异步状态机。每个skill执行完毕后，会向总线发布skill.success或skill.error事件，executor订阅这些事件来决定下一步。这意味着，如果send_gcode步骤耗时 200 秒，verify_position步骤不会等待，而是立即启动——只要send_gcode的timeout设置为 300 秒，它就有足够时间完成。这种设计让长时任务（如 CNC 加工）与短时任务（如日志记录）可以解耦，大幅提升吞吐量。

3.4storage区块：状态持久化的“心脏起搏器”

storage: type: "mysql" connection_string: "mysql+aiomysql://openclaw:password@mysql:3306/openclaw?charset=utf8mb4" state_table: "agent_state" log_table: "execution_log" ttl_days: 90

storage配置决定了 OpenClaw 如何保存关键状态。state_table存储智能体的当前状态（如 CNC 机床的当前坐标、温度传感器的最新读数），log_table存储每一次任务执行的完整 trace（含输入、输出、耗时、错误堆栈）。ttl_days: 90不是简单的数据库清理策略，而是 OpenClaw 的状态恢复机制的一部分。当智能体意外崩溃重启时，它会从state_table中加载最后一条记录作为初始状态，并从log_table中重放过去 90 天内的所有execution_log事件，重建完整的执行历史。这保证了即使服务中断，也不会丢失业务连续性。这也是为什么 MySQL 必须是 8.0.33+——只有该版本的ROW_FORMAT=DYNAMIC支持超长 JSON 字段的原子更新，而execution_log的 trace 数据常常超过 1MB。

提示：agent.yaml的缩进必须是 2 个空格，不能用 Tab。YAML 解析器对缩进极其敏感，一个 Tab 符号会导致yaml.scanner.ScannerError，错误信息却是while scanning for the next token，毫无指向性。我建议在 VS Code 中安装 “YAML” 扩展，并设置"editor.insertSpaces": true, "editor.detectIndentation": false来规避此问题。

4. 部署实战：从 Railway 到裸机，三种路径的取舍与陷阱

OpenClaw 的部署方式并非“一刀切”，而是根据你的目标环境（开发、测试、生产）和资源约束（时间、人力、预算），选择最匹配的路径。网络热词中频繁出现的 “railway部署”、“docker安装部署”、“ubuntu22.04安装教程”，恰恰反映了这三种主流路径的热度。但热度不等于最优，每种路径都有其不可回避的 trade-off（权衡）。

4.1 Railway 部署：最快上手，但最易失控

Railway 是目前部署 OpenClaw 最快捷的方案。它提供一键导入 GitHub 仓库、自动构建 Docker 镜像、按秒计费的托管服务。对于想快速验证概念（Proof of Concept）的个人开发者或小团队，这是首选。但它的“快”背后藏着巨大的隐性成本。

Railway 的构建流程是黑盒的。它会自动执行docker build，但你无法控制Dockerfile的每一行。OpenClaw 的官方Dockerfile为了减小镜像体积，使用了多阶段构建（multi-stage build），在build阶段安装gcc、libpq-dev等编译依赖，然后在runtime阶段只复制编译好的 wheel 包。Railway 的默认构建器会跳过build阶段，直接进入runtime，导致pip install时因缺少头文件而失败。解决方案是：在 Railway 项目的Settings > Build & Deploy中，将Build Command改为docker build --target build -t openclaw . && docker build --target runtime -t openclaw-runtime .，并确保Dockerfile中明确定义了build和runtime两个 target。

更大的陷阱在于环境变量管理。Railway 将所有环境变量注入容器，但 OpenClaw 的agent.yaml中的connection_string等敏感字段，必须通过环境变量注入，而不是硬编码。Railway 的 UI 界面允许你添加环境变量，但它不支持变量名中的点号（.）。而 OpenClaw 的标准环境变量前缀是OPENCLAW_STORAGE_MYSQL_CONNECTION_STRING。Railway 会将.替换为_，变成OPENCLAW_STORAGE_MYSQL_CONNECTION_STRING，导致 OpenClaw 无法读取。绕过方法是：在Dockerfile的runtime阶段，添加一行ENV OPENCLAW_STORAGE_MYSQL_CONNECTION_STRING=$MYSQL_CONNECTION_STRING，然后在 Railway 中只设置MYSQL_CONNECTION_STRING这个变量。

实测结论：Railway 适合 24 小时内需要一个可演示的 URL。但一旦进入集成测试阶段，就必须迁移到可控性更强的方案。我见过太多团队在 Railway 上花费一周调试环境变量，却只用了半天就完成了 Docker Compose 迁移。

4.2 Docker Compose 部署：生产就绪的黄金标准

Docker Compose 是 OpenClaw 生产部署的推荐方案，它完美平衡了可重复性（Reproducibility）和可控性（Control）。一个典型的docker-compose.yml如下：

version: '3.8' services: openclaw: build: context: . dockerfile: Dockerfile image: openclaw:1.2.0 depends_on: mysql: condition: service_healthy redis: condition: service_healthy rabbitmq: condition: service_healthy environment: - OPENCLAW_AGENT_CONFIG=/app/config/agent.yaml - OPENCLAW_STORAGE_MYSQL_CONNECTION_STRING=mysql+aiomysql://openclaw:password@mysql:3306/openclaw - OPENCLAW_STORAGE_REDIS_URL=redis://redis:6379/0 - OPENCLAW_EXECUTOR_RABBITMQ_URL=amqp://openclaw:password@rabbitmq:5672/ volumes: - ./config:/app/config - ./skills:/app/skills ports: - "8000:8000" - "8001:8001" healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 30s timeout: 10s retries: 3 start_period: 40s mysql: image: mysql:8.0.33 environment: MYSQL_ROOT_PASSWORD: rootpass MYSQL_DATABASE: openclaw MYSQL_USER: openclaw MYSQL_PASSWORD: password volumes: - mysql_data:/var/lib/mysql healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-prootpass"] interval: 20s timeout: 10s retries: 10 redis: image: redis:7.0.12-alpine command: redis-server --notify-keyspace-events Ex healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 20s timeout: 10s retries: 10 rabbitmq: image: rabbitmq:3.11.22-management environment: RABBITMQ_DEFAULT_USER: openclaw RABBITMQ_DEFAULT_PASS: password volumes: - rabbitmq_data:/var/lib/rabbitmq healthcheck: test: ["CMD", "rabbitmqctl", "status"] interval: 20s timeout: 10s retries: 10 volumes: mysql_data: rabbitmq_data:

这个文件的关键在于healthcheck的精确配置。openclaw服务的healthcheck使用curl检查/health端点，但该端点只有在所有依赖服务（MySQL、Redis、RabbitMQ）都健康后才会返回 200。depends_on的condition: service_healthy确保了启动顺序，而start_period: 40s给了 OpenClaw 足够的初始化时间（加载 Skill、连接数据库、建立 RabbitMQ 通道）。volumes的挂载方式也至关重要：./config:/app/config允许你在宿主机上编辑agent.yaml，容器内实时生效；./skills:/app/skills则让你可以随时添加新的 Skill 模块，无需重新构建镜像。

4.3 裸机（Bare Metal）部署：极致性能，但需承担全部运维责任

当你的任务链涉及毫秒级延迟要求（如高频交易信号处理）或需要直接访问硬件（如 GPU 加速的实时视频分析），Docker 的抽象层就成了瓶颈。此时，裸机部署是唯一选择。但这意味着你必须亲手管理每一个环节。

裸机部署的核心挑战是进程守护与日志聚合。OpenClaw 本身不提供 systemd 服务单元文件，你需要自己编写/etc/systemd/system/openclaw.service：

[Unit] Description=OpenClaw Agent Service After=network.target mysql.service redis-server.service rabbitmq-server.service [Service] Type=simple User=openclaw WorkingDirectory=/opt/openclaw Environment="PATH=/opt/openclaw/venv/bin:/usr/local/bin:/usr/bin:/bin" Environment="PYTHONPATH=/opt/openclaw" ExecStart=/opt/openclaw/venv/bin/python -m openclaw serve --config /opt/openclaw/config/agent.yaml Restart=on-failure RestartSec=10 KillMode=mixed KillSignal=SIGINT TimeoutStopSec=60 [Install] WantedBy=multi-user.target

注意KillMode=mixed和KillSignal=SIGINT。OpenClaw 的优雅关闭（Graceful Shutdown）依赖于接收SIGINT信号，它会等待所有正在执行的 Skill 完成后再退出。若使用默认的KillMode=control-group，systemd 会向整个进程组发送SIGTERM，可能导致 Skill 被强制中断，留下脏数据。TimeoutStopSec=60是必须的，因为某些 Skill（如大文件上传）可能需要超过 30 秒才能完成清理。

日志管理同样关键。OpenClaw 默认将日志输出到stdout，但裸机环境下，你需要将其路由到journalctl并设置轮转。在/etc/logrotate.d/openclaw中添加：

/var/log/openclaw/*.log { daily missingok rotate 30 compress delaycompress notifempty create 644 openclaw openclaw sharedscripts postrotate systemctl kill --signal=SIGHUP openclaw.service > /dev/null 2>&1 || true endscript }

postrotate中的SIGHUP会通知 OpenClaw 重新打开日志文件，实现无缝轮转。

经验之谈：裸机部署的终极技巧是“监控即配置”。我习惯在agent.yaml的executors中加入一个monitoringSkill，它定期调用psutil获取 CPU、内存、磁盘 IO 数据，并通过openclaw.emit发布到内部指标总线。这样，OpenClaw 的自身状态就变成了它可管理的“第一类公民”，形成闭环。这比任何外部监控工具都更精准、更及时。

5. 常见故障排查：从 “command not found” 到 “task stuck in pending”

部署完成后，真正的挑战才刚刚开始。OpenClaw 的日志设计非常克制，它不会在INFO级别打印所有细节，这导致很多问题初看毫无头绪。下面是我整理的最典型、最高频的五类故障，以及完整的排查链路。

5.1 故障现象：openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名

这是 Windows PowerShell 用户最常遇到的错误。表面看是命令未找到，但根源有三层：

1. 路径未加入 PATH：pip install openclaw安装的可执行脚本位于C:\Users\<user>\AppData\Roaming\Python\Python311\Scripts\，而 PowerShell 默认不搜索此路径。解决方案是：在 PowerShell 中执行$env:Path += ";C:\Users\<user>\AppData\Roaming\Python\Python311\Scripts\"，然后永久生效需修改系统环境变量。

2. PowerShell 执行策略限制：Windows 默认策略Restricted禁止运行任何脚本。执行Get-ExecutionPolicy查看当前策略，若为Restricted，则需运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。

3. Python 解释器混淆：用户可能同时安装了多个 Python 版本（如通过 Microsoft Store 安装的 Python 和通过 python.org 下载的 Python）。pip命令可能属于一个版本，而python命令属于另一个版本。执行where python和where pip，确保它们指向同一目录。最佳实践是始终使用py -3.11 -m pip install openclaw，明确指定 Python 版本。

5.2 故障现象：服务启动后，/health返回 503，日志中无明显错误

这通常表明 OpenClaw 成功启动，但无法连接到某个依赖服务。排查必须按顺序进行：

1. 确认服务端口可达：在 OpenClaw 容器/宿主机内执行telnet mysql 3306、telnet redis 6379、telnet rabbitmq 5672。若不通，检查防火墙、SELinux、Docker 网络。

2. 确认服务认证通过：使用客户端工具直连。例如，用mysql -h mysql -u openclaw -p连接 MySQL，输入密码。若失败，检查agent.yaml中的connection_string是否拼写错误，或 MySQL 用户权限是否授予openclaw@%。

3. 确认服务健康检查通过：执行curl -v http://localhost:8000/health，观察响应头中的X-Health-Checks字段。它会列出所有检查项及其状态，如mysql: ok, redis: failed, rabbitmq: ok。这直接定位到 Redis 连接失败。

4. 检查 Redis 的notify-keyspace-events：登录 Redis 执行CONFIG GET notify-keyspace-events，确认返回值包含Ex。若为""或K$，则需在 Redis 配置文件中添加notify-keyspace-events Ex并重启。

5.3 故障现象：任务在 UI 中显示 “pending”，但日志中无任何记录

这是 Executor 层最常见的死锁。原因几乎总是 RabbitMQ 的队列未被正确声明。OpenClaw 的 Executor 启动时，会尝试声明一个名为openclaw.executor.cnc-executor的队列。若 RabbitMQ 的openclaw用户没有configure权限，声明会静默失败，后续任务消息被丢弃。

排查步骤：

• 登录 RabbitMQ Management UI（默认http://<host>:15672），使用openclaw/password登录。
• 进入Admin > Virtual Hosts，点击/虚拟主机的Permissions标签页。
• 确认openclaw用户的Configure regexp为^openclaw\.，Write regexp为^openclaw\.，Read regexp为^openclaw\.。
• 进入Queues标签页，搜索cnc-executor，若不存在，说明声明失败。

修复方法：临时赋予openclaw用户.*权限，重启 OpenClaw，待队列创建成功后，再将权限改回^openclaw\.。

5.4 故障现象：Skill 执行超时，但函数本身在本地测试很快

这暴露了 OpenClaw 的一个关键设计：它测量的是从 Skill 开始执行到返回结果的整个异步周期，包括所有 await 的 I/O 时间。一个常见的陷阱是，在send_gcodeSkill 中，你写了await asyncio.sleep(1)模拟串口通信延迟，但忘记设置timeout: 300。OpenClaw 的默认 Skill 超时是 30 秒，1 秒的 sleep 就会触发超时。

更隐蔽的是数据库查询。假设你的 Skill 中有result = await db.execute("SELECT * FROM large_table WHERE ...")，而large_table有千万级数据且无索引。在本地测试时，你可能只查了 10 行，耗时 50ms；但在生产环境中，查询可能耗时 45 秒，超过默认 30 秒超时。

解决方案：在agent.yaml的skills区块中，为每个 Skill 显式设置timeout，值应大于其在最差情况下的预期耗时。对于不确定的长时任务，可设置timeout: 0（表示永不超时），但必须配合retry策略，防止无限挂起。

5.5 故障现象：openclaw call返回{"error": "Skill not found"}，但agent.yaml中已定义

这几乎 100% 是module.function路径错误。OpenClaw 的 Skill 加载器会遍历skills/目录下的所有.py文件，但只加载符合module.function命名规范的函数。例如，module: "skills.cnc.serial_sender"要求：

• 文件路径必须是skills/cnc/serial_sender.py
• 文件中必须有def send_gcode_to_machine(...):函数（注意：函数名必须与function字段完全一致）
• 该函数必须在模块的全局作用域中，不能嵌套在if __name__ == "__main__":或其他条件块内

一个快速验证方法是：在 OpenClaw 的 Python 环境中，手动执行：

from skills.cnc.serial_sender import send