openclaw-webchat-adapter 0.0.2__tar.gz

openclaw_webchat_adapter-0.0.2/.env

@@ -0,0 +1,8 @@
+OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789
+OPENCLAW_GATEWAY_TOKEN=hhadage
+OPENCLAW_SESSION_KEY=agent:main:main
+
+#OPENCLAW_PROTOCOL_VERSION=3
+#OPENCLAW_CLIENT_ID=webchat-ui
+#OPENCLAW_CLIENT_MODE=webchat
+#OPENCLAW_CLIENT_PLATFORM=browser

openclaw_webchat_adapter-0.0.2/.env.example

@@ -0,0 +1,91 @@
+###############################################################################
+# [必须/可选]：必须
+# [配置效果]：配置 OpenClaw Gateway 的 WebSocket 连接地址；修改后会连接到不同的网关实例。
+# [格式/默认值]：字符串；示例 ws://127.0.0.1:18789；默认值 ws://127.0.0.1:18789
+###############################################################################
+OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789
+
+###############################################################################
+# [必须/可选]：可选（与 OPENCLAW_GATEWAY_PASSWORD 二选一，或两者同时提供）
+# [配置效果]：使用 token 方式通过网关鉴权；提供后将在 connect.auth.token 中发送。
+# [格式/默认值]：字符串；示例 sk-xxxx；默认值为空
+###############################################################################
+OPENCLAW_GATEWAY_TOKEN=
+
+###############################################################################
+# [必须/可选]：可选（与 OPENCLAW_GATEWAY_TOKEN 二选一，或两者同时提供）
+# [配置效果]：使用 password 方式通过网关鉴权；提供后将在 connect.auth.password 中发送。
+# [格式/默认值]：字符串；示例 my-password；默认值为空
+###############################################################################
+OPENCLAW_GATEWAY_PASSWORD=
+
+###############################################################################
+# [必须/可选]：必须
+# [配置效果]：chat.send 使用的 sessionKey；不同 sessionKey 会影响会话上下文/聊天记录隔离。
+# [格式/默认值]：字符串；示例 agent:main:main；默认值 agent:main:main
+###############################################################################
+OPENCLAW_SESSION_KEY=agent:main:main
+
+###############################################################################
+# [必须/可选]：可选
+# [配置效果]：用于 connect 握手时声明协议版本；一般无需修改。
+# [格式/默认值]：整数；示例 3；默认值 3
+###############################################################################
+OPENCLAW_PROTOCOL_VERSION=3
+
+###############################################################################
+# [必须/可选]：可选
+# [配置效果]：connect.client.id；用于标识客户端来源（便于网关侧统计/审计）。
+# [格式/默认值]：字符串；示例 webchat-ui；默认值 webchat-ui
+###############################################################################
+OPENCLAW_CLIENT_ID=webchat-ui
+
+###############################################################################
+# [必须/可选]：可选
+# [配置效果]：connect.client.mode；用于标识客户端模式（例如 webchat）。
+# [格式/默认值]：字符串；示例 webchat；默认值 webchat
+###############################################################################
+OPENCLAW_CLIENT_MODE=webchat
+
+###############################################################################
+# [必须/可选]：可选
+# [配置效果]：connect.client.displayName；用于在网关侧展示/日志中识别客户端。
+# [格式/默认值]：字符串；示例 py-adapter；默认值 py-adapter
+###############################################################################
+OPENCLAW_CLIENT_DISPLAY_NAME=py-adapter
+
+###############################################################################
+# [必须/可选]：可选
+# [配置效果]：connect.client.version；用于在网关侧展示客户端版本信息。
+# [格式/默认值]：字符串；示例 dev；默认值 dev
+###############################################################################
+OPENCLAW_CLIENT_VERSION=dev
+
+###############################################################################
+# [必须/可选]：可选
+# [配置效果]：connect.client.platform；用于在网关侧识别平台（browser/server 等）。
+# [格式/默认值]：字符串；示例 browser；默认值 browser
+###############################################################################
+OPENCLAW_CLIENT_PLATFORM=browser
+
+###############################################################################
+# [必须/可选]：可选
+# [配置效果]：connect.client.instanceId；用于区分同一客户端的不同实例；为空时会自动生成。
+# [格式/默认值]：字符串；示例 py-<uuid>；默认值为空（自动生成）
+###############################################################################
+OPENCLAW_CLIENT_INSTANCE_ID=
+
+###############################################################################
+# [必须/可选]：可选
+# [配置效果]：connect.role；用于声明连接角色（取决于网关侧策略）。
+# [格式/默认值]：字符串；示例 operator；默认值 operator
+###############################################################################
+OPENCLAW_CONNECT_ROLE=operator
+
+###############################################################################
+# [必须/可选]：可选
+# [配置效果]：connect.scopes；声明请求权限范围（逗号分隔），取决于网关侧策略。
+# [格式/默认值]：字符串（CSV）；示例 operator.admin,operator.read；默认值 operator.admin
+###############################################################################
+OPENCLAW_CONNECT_SCOPES=operator.admin
+

openclaw_webchat_adapter-0.0.2/.gitignore

@@ -0,0 +1,31 @@
+### IntelliJ IDEA ###
+out/
+!**/src/main/**/out/
+!**/src/test/**/out/
+
+### Eclipse ###
+.xml
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+bin/
+.idea
+!**/src/main/**/bin/
+!**/src/test/**/bin/
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store

openclaw_webchat_adapter-0.0.2/ADAPTER_DESIGN_REPORT.md

@@ -0,0 +1,98 @@
+# OpenClaw Gateway Python 适配器（结构化版）设计文档
+
+### 让你的项目更加简单的嵌入openclaw
+
+## 修改摘要
+- 将原先单文件的 WebSocket 适配器拆分为可复用的包：配置加载、.env 解析、协议适配、异常定义、CLI 入口分离。
+- 新增统一配置入口 `AdapterSettings.from_env()`：从 `.env` 或系统环境变量读取 `token/password` 用于网关鉴权。
+- 对外提供核心流式接口 `OpenClawGatewayWsAdapter.stream_chat(user_request)`：按 runId 订阅 chat 事件并增量输出。
+- 增加可注入 `ws_factory` 以便单元测试模拟网关收发，降低耦合。
+
+## 代码结构与职责划分
+- `openclaw_webchat_adapter/env.py`
+  - 负责解析/加载 `.env`，不引入第三方 dotenv 依赖。
+- `openclaw_webchat_adapter/config.py`
+  - 定义 `AdapterSettings`，统一读取并校验环境变量（含鉴权字段存在性校验）。
+- `openclaw_webchat_adapter/exceptions.py`
+  - 定义适配器对外抛出的异常类型，便于上层调用方精确捕获与处理。
+- `openclaw_webchat_adapter/ws_adapter.py`
+  - 协议适配核心：握手（connect.challenge -> connect -> hello-ok）、RPC request/response pending 映射、chat 事件路由与增量拼接输出。
+- `openclaw_webchat_adapter/__main__.py`
+  - 提供最小 CLI：用于快速验证连通性与流式输出效果。
+
+## 关键设计点
+### 1) 配置与鉴权
+- 配置读取策略：
+  - 优先从 `.env` 加载（若存在），再从 `os.environ` 获取最终值。
+  - 默认不覆盖既有 `os.environ`（可通过 `dotenv_override=True` 允许覆盖）。
+- 鉴权策略：
+  - 强制要求至少配置 `OPENCLAW_GATEWAY_TOKEN` 或 `OPENCLAW_GATEWAY_PASSWORD` 其一。
+  - 适配器在 `connect` 请求中仅在配置存在时才发送 `auth.token/auth.password` 字段，避免发送空字段。
+
+### 2) 协议适配与流式输出
+- 握手：
+  - WebSocket 建连后可能先收到 `connect.challenge`，也可能不保证顺序；适配器同时提供事件触发和定时兜底，确保 connect 能发送。
+  - 收到 `res.payload.type == "hello-ok"` 视为握手成功。
+- RPC：
+  - `req.id` 为一次请求的唯一标识；适配器用 `pending` 映射将 `res.id` 回投到对应等待队列。
+- chat 流：
+  - `chat.send` 使用 `idempotencyKey` 作为 `runId`（一次请求一次 run）。
+  - 服务端 `event=chat` 按 `payload.runId` 路由到对应队列。
+  - 对 `delta/final` 采用“前缀差分”输出新增文本，避免重复输出累计内容。
+
+### 3) 可测试性与解耦
+- `ws_factory` 注入点：
+  - 默认使用 `websocket-client` 的 `WebSocketApp`。
+  - 测试中用 FakeWebSocketApp 模拟握手、RPC、chat 事件，避免依赖真实网关。
+
+## 环境变量配置指南
+请复制 `.env.example` 为 `.env` 并填写。每个变量的含义与影响已在 `.env.example` 中以注释块完整说明：
+- 网关连接：
+  - `OPENCLAW_GATEWAY_URL`
+- 鉴权（二选一或同时提供）：
+  - `OPENCLAW_GATEWAY_TOKEN`
+  - `OPENCLAW_GATEWAY_PASSWORD`
+- 会话：
+  - `OPENCLAW_SESSION_KEY`
+- 可选握手参数：
+  - `OPENCLAW_PROTOCOL_VERSION`
+  - `OPENCLAW_CLIENT_ID`
+  - `OPENCLAW_CLIENT_MODE`
+  - `OPENCLAW_CLIENT_DISPLAY_NAME`
+  - `OPENCLAW_CLIENT_VERSION`
+  - `OPENCLAW_CLIENT_PLATFORM`
+  - `OPENCLAW_CLIENT_INSTANCE_ID`
+  - `OPENCLAW_CONNECT_ROLE`
+  - `OPENCLAW_CONNECT_SCOPES`
+
+## 使用方式
+### 依赖安装（必须）
+```bash
+pip install -r requirements.txt
+```
+
+### 方式 A：代码调用（推荐集成）
+```python
+from openclaw_webchat_adapter import AdapterSettings, OpenClawGatewayWsAdapter
+
+settings = AdapterSettings.from_env(dotenv_path=".env")
+adapter = OpenClawGatewayWsAdapter(settings=settings)
+
+adapter.start()
+adapter.ensure_session("main")
+
+for chunk in adapter.stream_chat("你好"):
+    print(chunk, end="", flush=True)
+
+adapter.stop()
+```
+
+### 方式 B：命令行快速验证
+```bash
+python -m openclaw_webchat_adapter --once "你好"
+```
+
+## 安全性说明
+- 本实现不打印/不记录 token/password；上层如需日志，建议对敏感字段脱敏后再输出。
+- `stream_chat` 对输入做类型与空字符串校验，避免异常协议请求。
+

openclaw_webchat_adapter-0.0.2/DESIGN_REPORT.md

@@ -0,0 +1,56 @@
+# OpenClaw Gateway Adapter 设计文档（本次变更）
+
+## 修改摘要
+- 修复 `OpenClawGatewayWsAdapter.create_connected()` 的类方法绑定，并新增 `create_connected_from_env()`：支持无参从 `.env`/环境变量读取并连接，也支持显式覆盖 `OPENCLAW_GATEWAY_URL/token/password`。
+- 将 `openclaw_webchat_adapter` 包内的模块/类/函数 Docstring 统一翻译为中文，提升可读性与团队协作效率（不改变任何运行逻辑）。
+- 新增 `env.py` 的解析与加载单元测试，覆盖引号处理、注释/空行跳过、override 行为等核心路径。
+- 将 CLI 的“连接/握手/会话准备”逻辑迁移到 `ws_adapter.create_connected()`，CLI 仅负责读取输入并调用聊天接口。
+- 适配器在“连接就绪/会话就绪”时输出 INFO 日志，便于启动排障与联调。
+- 新增 `TEST_REPORT.md` 作为本次交付的测试报告。
+
+## 架构设计思路
+该适配器以“配置加载 + 协议适配 + 异常分层”的方式拆分职责，降低耦合并便于测试：
+- `openclaw_webchat_adapter/env.py`
+  - 负责 `.env` 文本解析与写入 `os.environ`，不引入第三方依赖。
+- `openclaw_webchat_adapter/config.py`
+  - 负责从环境变量/`.env` 读取配置并做基本合法性校验，最终构造 `AdapterSettings`。
+- `openclaw_webchat_adapter/ws_adapter.py`
+  - 负责 WebSocket 连接、握手、RPC request/response 的 pending 映射、chat 事件路由与增量输出；并提供 `create_connected()` 封装一键启动流程。
+- `openclaw_webchat_adapter/exceptions.py`
+  - 对外暴露类型化异常，便于上层做精确捕获与处理分支。
+- `openclaw_webchat_adapter/__main__.py`
+  - 提供最小 CLI 入口，方便验证连通性与进行一次性请求；连接与会话准备由 `ws_adapter.create_connected()` 承担。
+
+## 环境变量详细配置指南
+建议复制 `.env.example` 为 `.env`，并按注释块填写。代码侧读取入口为 `AdapterSettings.from_env()`，主要变量如下：
+
+### 必填（代码会校验非空）
+- `OPENCLAW_GATEWAY_URL`
+  - 网关 WebSocket 地址，例如：`ws://127.0.0.1:18789`
+- `OPENCLAW_SESSION_KEY`
+  - chat 请求使用的会话 key，例如：`agent:main:main`
+
+### 选填（是否必需由网关端策略决定）
+- `OPENCLAW_GATEWAY_TOKEN`
+  - token 鉴权凭据（若提供则在 connect 时携带）。
+- `OPENCLAW_GATEWAY_PASSWORD`
+  - password 鉴权凭据（若提供则在 connect 时携带）。
+
+### 选填（握手与客户端信息）
+- `OPENCLAW_PROTOCOL_VERSION`
+- `OPENCLAW_CLIENT_ID`
+- `OPENCLAW_CLIENT_MODE`
+- `OPENCLAW_CLIENT_DISPLAY_NAME`
+- `OPENCLAW_CLIENT_VERSION`
+- `OPENCLAW_CLIENT_PLATFORM`
+- `OPENCLAW_CLIENT_INSTANCE_ID`
+- `OPENCLAW_CONNECT_ROLE`
+- `OPENCLAW_CONNECT_SCOPES`
+
+说明：
+- 变量的 `[必须/可选]`、`[配置效果]`、`[格式/默认值]` 以 `.env.example` 为准；该文件是配置说明的单一可信来源。
+- `.env` 加载策略：默认不覆盖已存在的 `os.environ` 同名值；如需覆盖可在代码调用 `dotenv_override=True`。
+
+## 安全性说明
+- 适配器不输出 `token/password` 等敏感字段；上层若需要日志，请自行脱敏后再记录。
+- `.env` 解析逻辑仅处理 `KEY=VALUE` 形式，并会忽略注释/空行/非法行，降低误解析风险。

openclaw_webchat_adapter-0.0.2/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) [2026] [hadage]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

openclaw_webchat_adapter-0.0.2/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: openclaw_webchat_adapter
+Version: 0.0.2
+Summary: 让你的项目更加简单的嵌入openclaw
+Project-URL: Homepage, https://github.com/tangdeyx2333-beep/openclaw-websocket-adapter
+Project-URL: Issues, https://github.com/tangdeyx2333-beep/openclaw-websocket-adapter/issues
+Author-email: hadage <tangdeyx2333@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# OpenClaw Gateway Python 适配器（WebChat 协议）
+
+让你的项目更加简单的嵌入openclaw
+
+这是一个可复用的 Python 包：基于 OpenClaw Gateway 的 WebSocket 协议完成握手与 RPC 调用，并提供开箱即用的流式聊天接口（chat.send + event=chat）。
+
+## 如何工作（简版）
+
+```text
+调用接口（你的 Python 代码 / CLI）
+    │
+    ▼
+伪造的 WebChat 终端（本适配器模拟的 Web 客户端）
+    │  ws://127.0.0.1:18789（WebChat 协议：connect / sessions.patch / chat.send）
+    ▼
+OpenClaw Gateway
+```
+
+## 特性
+- 一键连接：`OpenClawGatewayWsAdapter.create_connected()` 自动握手并准备会话
+- 配置统一：`AdapterSettings.from_env()` 从 `.env` / 环境变量读取参数
+- 流式输出：`stream_chat()` 增量产出 assistant 文本片段
+- CLI 入口：支持一次性请求与交互式 REPL，并输出连接就绪日志
+- 可测试：可注入 `ws_factory`，便于在单元测试中模拟网关收发
+
+## 快速开始
+
+### 1) 安装依赖
+```bash
+py -m pip install --index-url https://test.pypi.org/simple/ --no-deps openclaw-webchat-adapter 
+```
+
+### 2) 配置环境变量
+复制 `.env.example` 为 `.env` 并按注释块填写（每个变量的含义与影响以 `.env.example` 为准）。
+
+最少需要：
+- `OPENCLAW_GATEWAY_URL`
+- `OPENCLAW_SESSION_KEY`
+
+鉴权（按你的网关策略选择其一或同时提供）：
+- `OPENCLAW_GATEWAY_TOKEN`
+- `OPENCLAW_GATEWAY_PASSWORD`
+
+### 3) 使用示例（推荐：代码调用）
+
+```python
+"""为 OpenClaw Gateway 适配器提供一个最小可用的命令行入口。"""
+
+from openclaw_webchat_adapter.ws_adapter import OpenClawChatWsAdapter as adapter
+
+def main() -> int:
+    """基于 .env 配置启动交互式 REPL 或执行一次性请求。"""
+    connect = adapter.create_connected_from_env()
+    # 进入交互式 REPL
+    try:
+        while True:
+            line = input("> ").strip()
+            if not line:
+                continue
+            if line.lower() in ("/exit", "/quit"):
+                break
+            for chunk in connect.stream_chat(line):
+                print(chunk, end="", flush=True)
+            print("")
+    finally:
+        connect.stop()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+```
+
+退出交互式聊天：
+- 输入 `/exit` 或 `/quit`
+
+## 安全建议
+- 不要在日志中输出 `token/password` 等敏感信息（本适配器不会主动打印这些字段）。
+- 如需远程访问网关，建议通过安全通道（例如内网/VPN/反向代理）并启用鉴权。
+
+## 文档
+- 结构化设计文档：[ADAPTER_DESIGN_REPORT.md](file:///f:/aaa_desktop_file/python-study/openclaw_webchat_adapter/ADAPTER_DESIGN_REPORT.md)
+- 本仓库设计变更说明：[DESIGN_REPORT.md](file:///f:/aaa_desktop_file/python-study/openclaw_webchat_adapter/DESIGN_REPORT.md)
+- 本仓库测试报告：[TEST_REPORT.md](file:///f:/aaa_desktop_file/python-study/openclaw_webchat_adapter/TEST_REPORT.md)
+- 协议与握手细节参考：[README_3.md](file:///f:/aaa_desktop_file/python-study/openclaw_webchat_adapter/README_3.md)

openclaw_webchat_adapter-0.0.2/README.md

@@ -0,0 +1,87 @@
+# OpenClaw Gateway Python 适配器（WebChat 协议）
+
+让你的项目更加简单的嵌入openclaw
+
+这是一个可复用的 Python 包：基于 OpenClaw Gateway 的 WebSocket 协议完成握手与 RPC 调用，并提供开箱即用的流式聊天接口（chat.send + event=chat）。
+
+## 如何工作（简版）
+
+```text
+调用接口（你的 Python 代码 / CLI）
+    │
+    ▼
+伪造的 WebChat 终端（本适配器模拟的 Web 客户端）
+    │  ws://127.0.0.1:18789（WebChat 协议：connect / sessions.patch / chat.send）
+    ▼
+OpenClaw Gateway
+```
+
+## 特性
+- 一键连接：`OpenClawGatewayWsAdapter.create_connected()` 自动握手并准备会话
+- 配置统一：`AdapterSettings.from_env()` 从 `.env` / 环境变量读取参数
+- 流式输出：`stream_chat()` 增量产出 assistant 文本片段
+- CLI 入口：支持一次性请求与交互式 REPL，并输出连接就绪日志
+- 可测试：可注入 `ws_factory`，便于在单元测试中模拟网关收发
+
+## 快速开始
+
+### 1) 安装依赖
+```bash
+py -m pip install --index-url https://test.pypi.org/simple/ --no-deps openclaw-webchat-adapter 
+```
+
+### 2) 配置环境变量
+复制 `.env.example` 为 `.env` 并按注释块填写（每个变量的含义与影响以 `.env.example` 为准）。
+
+最少需要：
+- `OPENCLAW_GATEWAY_URL`
+- `OPENCLAW_SESSION_KEY`
+
+鉴权（按你的网关策略选择其一或同时提供）：
+- `OPENCLAW_GATEWAY_TOKEN`
+- `OPENCLAW_GATEWAY_PASSWORD`
+
+### 3) 使用示例（推荐：代码调用）
+
+```python
+"""为 OpenClaw Gateway 适配器提供一个最小可用的命令行入口。"""
+
+from openclaw_webchat_adapter.ws_adapter import OpenClawChatWsAdapter as adapter
+
+def main() -> int:
+    """基于 .env 配置启动交互式 REPL 或执行一次性请求。"""
+    connect = adapter.create_connected_from_env()
+    # 进入交互式 REPL
+    try:
+        while True:
+            line = input("> ").strip()
+            if not line:
+                continue
+            if line.lower() in ("/exit", "/quit"):
+                break
+            for chunk in connect.stream_chat(line):
+                print(chunk, end="", flush=True)
+            print("")
+    finally:
+        connect.stop()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+```
+
+退出交互式聊天：
+- 输入 `/exit` 或 `/quit`
+
+## 安全建议
+- 不要在日志中输出 `token/password` 等敏感信息（本适配器不会主动打印这些字段）。
+- 如需远程访问网关，建议通过安全通道（例如内网/VPN/反向代理）并启用鉴权。
+
+## 文档
+- 结构化设计文档：[ADAPTER_DESIGN_REPORT.md](file:///f:/aaa_desktop_file/python-study/openclaw_webchat_adapter/ADAPTER_DESIGN_REPORT.md)
+- 本仓库设计变更说明：[DESIGN_REPORT.md](file:///f:/aaa_desktop_file/python-study/openclaw_webchat_adapter/DESIGN_REPORT.md)
+- 本仓库测试报告：[TEST_REPORT.md](file:///f:/aaa_desktop_file/python-study/openclaw_webchat_adapter/TEST_REPORT.md)
+- 协议与握手细节参考：[README_3.md](file:///f:/aaa_desktop_file/python-study/openclaw_webchat_adapter/README_3.md)