一、说在前面
OpenClaw 作为开源 AI 助手框架的崛起,核心在于其 “多渠道接入 + 本地优先” 的架构设计,已成为办公自动化与智能交互的核心载体。当前业内主流的操控方案集中于即时通讯(IM)工具集成,形成了成熟的 “日常办公入口 + AI 自动化” 闭环:
这些方案虽解决了 “低门槛使用” 的需求,一方面受限于 IM 工具的功能边界与插件化设计;另一方面存在数据安全与隐私保护风险,加上使用的成本,正规企业还是不愿意选择;再者,以这种方式实现也难以满足个性化业务流程、系统集成等复杂需求。因此,通过自开发程序直接调用 OpenClaw API,达到指挥的目的,成为突破场景限制、实现深度定制化操控的关键路径。
二、技术实现方案
1. 现有 IM 工具操控 OpenClaw 的技术原理
微信、飞书等工具与 OpenClaw 的集成,本质上依赖 “网关 + 插件 + 认证” 的三层架构,核心实现逻辑如下:
统一网关(Gateway):作为通信枢纽,采用 WebSocket 长连接模式实现毫秒级消息同步,OpenClaw 支持 ProtocolGateway(远程 / 本地连接)、OpenAICompatGateway(HTTP 接口)等多种网关类型,负责指令与响应的转发;
平台适配插件:OpenClaw 内置微信、飞书等官方插件,封装了平台特有的 API 调用逻辑,例如飞书需通过企业应用的 App ID/Secret 授权,微信支持扫码授权或第三方解决方案对接;
安全认证机制:采用 Token 验证、事件订阅白名单等方式保障通信安全,如飞书需配置「im.message.receive_v1」事件订阅,微信则通过加密配置文件存储授权凭证。
这种实现方式的核心优势是 “零代码配置”,但灵活性不足,无法自定义指令格式、扩展响应处理逻辑。
2. API 实现程序操控 OpenClaw(Python 示例)
OpenClaw 提供了标准化 API 接口与 Python SDK,支持直接与本地或远程实例通信,实现指令发送、响应接收、会话管理等功能。本次提供另一个方案,不依赖与OpenClaw相关SDK,基于 WebSocket 通信开发客户端,用于与 OpenClaw 智能助手系统进行交互。该客户端通过 WebSocket 连接发送指令并接收回复,支持完整的对话流程和系统管理功能。主要实现以下功能
- WebSocket 连接和认证
- 发送聊天消息并获取回复
- 健康检查和系统状态查询
- 增量文本显示(避免重复打印)
- 事件驱动的消息处理
技术实现核心要点:
### 多线程设计
### 事件驱动架构
### 异步请求处理
(1)整体架构

(2)环境准备
•Python 3.10.91+,OpenClaw 本地实例(默认 WebSocket 网关地址:ws://127.0.0.1:18789/gateway)
•其他依赖

(3)核心实现代码
### 3.1 连接与认证
**连接流程:**
1. 初始化 WebSocket 连接到 `ws://127.0.0.1:18789/ws`
2. 发送第一阶段认证(仅 token)
3. 接收服务器 challenge
4. 发送第二阶段认证(token + password)
5. 接收 hello 事件,完成连接
# 第一阶段认证 - 仅 tokendef _on_open(self, ws): connect_msg = { "type": "req", "id": "connect-1", "method": "connect", "params": { "minProtocol": 3, "maxProtocol": 3, "client": { "id": "cli", "version": "1.0.0", "platform": "linux", "mode": "cli" }, "auth": { "token": self.token # 仅使用 token }, "role": "operator", "scopes": ["operator.admin", "operator.approvals", "operator.pairing"] } } self.ws.send(json.dumps(connect_msg))# 第二阶段认证 - token + passworddef _send_auth_connect(self): connect_msg = { "type": "req", "id": "connect-2", "method": "connect", "params": { "auth": { "token": self.token, # 再次使用 token "password": self.token # 密码也使用 token }, # 其他参数... } } self.ws.send(json.dumps(connect_msg))
### 3.2 消息发送与接收
**发送聊天消息:**
def send_chat(self, message: str, session_key: str = "agent:main:main", wait_for_response: bool = True, timeout: int = 120) -> Optional[Dict]: # 重置状态 self._current_response_text = "" self._current_run_id = None self._chat_responses.clear() self._last_printed_len.clear() # 发送聊天请求 result = self.send_request("chat.send", { "sessionKey": session_key, "message": message, "deliver": False, "idempotencyKey": str(uuid.uuid4()) # 唯一标识符 }, timeout=60) # 等待响应 if result and wait_for_response: run_id = result.get("runId") # 等待直到收到完成状态 start_time = time.time() while time.time() - start_time < timeout: if run_id in self._chat_responses: resp = self._chat_responses[run_id] if resp.get("state") in ["finished", "done", "error"]: result["response_text"] = resp.get("text", "") result["response_state"] = resp.get("state") break time.sleep(0.5) return result
### 3.3 事件处理
**消息处理机制:**
def _on_message(self, ws, message): try: data = json.loads(message) msg_type = data.get("type") if msg_type == "event": event = data.get("event") payload = data.get("payload", {}) if event == "connect.challenge": self._send_auth_connect() elif event == "hello": self.connected = True self.server_version = payload.get("server", {}).get("version") elif event == "agent": self._handle_agent_event(event, payload) elif event == "chat": self._handle_chat_event(event, payload) elif msg_type == "res": # 处理请求响应 req_id = data.get("id") ok = data.get("ok") if req_id in self.pending: if ok: self.pending[req_id]["result"] = data.get("payload", {}) self.pending[req_id]["ok"] = True else: self.pending[req_id]["ok"] = False self.pending[req_id]["error"] = data.get("error", {}) self.pending[req_id]["event"].set() except Exception as e: print(f"[OpenClaw] Error parsing message: {e}")
### 3.4 增量文本显示
**避免重复打印的核心实现:**
def _print_incremental(self, run_id: str, full_text: str): """只打印新增的文本部分""" last_len = self._last_printed_len.get(run_id, 0) if len(full_text) > last_len: new_text = full_text[last_len:] print(new_text, end="", flush=True) self._last_printed_len[run_id] = len(full_text)
文本更新检测:
elif stream in ("assistant", "text"): text = data.get("text", "") if text and len(text) > 0: # 检查是否是新的、更长的文本 current_text = self._chat_responses.get(run_id, {}).get("text", "") if len(text) > len(current_text): self._chat_responses[run_id]["text"] = text self._current_response_text = text # 增量打印 self._print_incremental(run_id, text)
## 3.5使用示例
**基本使用**

**健康检查**

程序运行的一个结果:
同时可以看到,OpenClaw端有日志显示有请求上来
而且在它的Dashboard页面也可以看到,确实是有提问三、程序实现操控 OpenClaw 的场景及意义
1. 场景与意义
个性化自动化工作流:适用于企业内部定制化业务场景,如对接 ERP 系统自动提取数据、结合本地数据库生成分析报告、触发跨系统任务调度等,突破 IM 工具的功能局限,采用本地私有化部署,数据流转全程可控,满足了企业对数据信息安全保护的诉求。
系统集成与二次开发:可将 OpenClaw 能力嵌入自有应用(如 CRM、OA 系统),实现 “AI 助手 + 业务系统” 深度融合,例如在客户管理系统中调用 OpenClaw 自动生成跟进话术;
批量任务与定时执行:通过 Python 脚本结合定时任务工具(如 cron、Airflow),实现批量数据处理、周期性报告生成、跨平台消息推送等自动化操作,提升工作效率;
四、最后
通过自开发程序调用 API 操控 OpenClaw,本质是将 AI 自动化能力从 “标准化工具” 升级为 “可定制化组件”,既保留了 OpenClaw 本地优先、多模型支持的核心优势,又突破了 IM 工具集成的场景限制。对于企业用户而言,这种方式能够深度适配业务流程,实现 “AI 能力 + 业务系统” 的无缝融合。
未来,随着 OpenClaw 生态的持续完善,API 操控将支持更多多模态交互、分布式部署场景,逐步优化性能与安全性,充分发挥自定义开发的灵活性优势,成为企业数字化转型中 “AI 自动化” 的核心实现路径之一。
感兴趣的同亲们,可以关注本公众号,并回复“openclaw” 领取《API调用OpenClaw源程序》实战干货,一起对程序进行优化改进。