# local_gpu_ocgateway

**Repository Path**: dougio/openclaw-gateway

## Basic Information

- **Project Name**: local_gpu_ocgateway
- **Description**: 一个可以调用本地GPU的openclaw gateway
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-18
- **Last Updated**: 2026-02-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenClaw Gateway

OpenClaw Gateway 是一个本地AI网关，用于在中国大陆网络环境下通过LM Studio调用本地大模型。

## 快速开始

### 1. 环境准备
- 安装 Python 3.8+
- 安装 LM Studio 并启动（监听 1234 端口）
- 克隆本仓库

### 2. 安装依赖
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

pip install -r requirements.txt
```

### 3. 启动服务
```bash
# 基础模式（仅本地）
python -m gateway

# 启用云端混合计算（带Gateway Token）
python -m gateway --enable-cloud --cloud-url ws://your-openclaw-cloud.com --gateway-token your-token-here

# 自定义端口
python -m gateway --port 19000
```

### 4. 使用客户端
```bash
# 直接模式
python client/local_client.py --prompt "写一个Python排序函数"

# 交互模式  
python client/local_client.py
```

## 云端混合计算支持 🌥️

项目现在支持**本地+云端混合计算架构**，可以显著提升小模型的代码生成质量：

### 配置方式（无需配置文件）

#### 方式1：命令行参数（推荐）
```bash
# 带Gateway Token的完整示例
python -m gateway --enable-cloud --cloud-url ws://your-openclaw-cloud.com --gateway-token your-secret-token

# 如果你的token包含特殊字符，用引号包围
python -m gateway --enable-cloud --cloud-url ws://your-openclaw-cloud.com --gateway-token "your-token-with-special-chars!"
```

#### 方式2：环境变量
```bash
# Windows
set OPENCLAW_CLOUD_ENABLED=true
set OPENCLAW_CLOUD_URL=ws://your-openclaw-cloud.com
set OPENCLAW_GATEWAY_TOKEN=your-secret-token
python -m gateway

# Linux/Mac
export OPENCLAW_CLOUD_ENABLED=true
export OPENCLAW_CLOUD_URL=ws://your-openclaw-cloud.com
export OPENCLAW_GATEWAY_TOKEN=your-secret-token
python -m gateway
```

### 认证支持
- **无认证**：完全兼容之前的无key模式
- **API Key**：通过 `--api-key` 或 `OPENCLAW_API_KEY` 环境变量
- **Gateway Token**：通过 `--gateway-token` 或 `OPENCLAW_GATEWAY_TOKEN` 环境变量
- **自动检测**：系统会自动将认证信息添加到WebSocket连接URL的查询参数中

### 混合计算工作模式
- **提示词优化**：云端大模型优化你的提示词，然后本地小模型执行
- **智能兜底**：本地处理失败时自动切换到云端处理
- **零配置兼容**：支持无认证、API Key、Gateway Token等多种认证方式

### 工作流程
```
用户请求 
    ↓
本地Gateway (18789)
    ↓
[智能路由判断]
├── 简单任务 → 本地LM Studio (1234) → 返回结果
└── 复杂任务 → 云端OpenClaw → 
    ├── 优化提示词 → 本地LM Studio → 返回结果
    └── 或直接云端生成 → 返回结果
```

## VS Code 集成 🚀

项目已配置完整的 VS Code 开发环境集成，提供一键式操作体验：

### 快捷键
- **Ctrl+Shift+G**: 启动 OpenClaw Gateway 服务
- **Ctrl+Shift+C**: 启动本地客户端（交互模式）
- **Ctrl+Shift+T**: 运行集成测试

### 任务面板
通过 `Terminal -> Run Task` 可以访问以下任务：
- 启动 OpenClaw Gateway
- 启动本地客户端（交互模式）
- 运行Step 1.1测试（验证网关基础功能）
- 运行Step 1.2测试（验证客户端功能）
- 运行集成测试

### 工作区设置
- 自动激活虚拟环境
- 智能文件排除（__pycache__, .pyc, 日志文件等）
- 优化的搜索体验

## 功能特性

- ✅ **完全本地运行**：不依赖外部网络，数据不出境
- ✅ **零API费用**：利用本地GPU资源，无调用成本
- ✅ **标准兼容**：提供标准OpenClaw WebSocket接口
- ✅ **开发友好**：VS Code深度集成，一键启动/测试
- ✅ **简单易用**：命令行和交互模式双支持
- 🌥️ **混合计算**：本地+云端协同，提升小模型效果
- 🔧 **零配置**：无需管理配置文件，多设备轻松同步
- 🔒 **灵活认证**：支持无认证、API Key、Gateway Token等多种方式

## 支持的命令

- `ping`: 健康检查
- `status`: 获取网关状态
- `models`: 列出可用模型
- `chat`: 执行聊天完成请求（代码生成）

## 故障排除

如果遇到连接问题：
1. 确保 LM Studio 正在运行并监听 1234 端口
2. 确保没有其他进程占用 18789 端口
3. 使用 VS Code 任务面板启动服务（推荐）
4. 查看 `gateway.log` 文件获取详细日志
5. **认证问题**：确保 Gateway Token 正确，且URL格式为 `ws://` 或 `wss://`

## 贡献

欢迎提交 Issue 和 Pull Request！

# OpenClaw Gateway - 个人AI工具增强版本

这个仓库包含了一个增强版的 OpenClaw Gateway，专为个人开发者设计，支持**本地GPU + 境内云服务器**的混合架构，最大化利用本地算力降低成本，同时保证服务的稳定性和便携性。

## 🎯 核心特性

- **本地GPU优先**：80%常规任务（如代码生成）在本地GPU执行，大幅降低API费用
- **云端协调器**：通过境内云服务器提供配置管理和故障容错
- **便携部署**：一键安装，无需复杂配置，支持多设备快速切换
- **国内网络友好**：完全适配中国大陆网络环境，不依赖境外服务
- **智能路由**：自动选择最优执行位置（本地/云端）
- **故障自动切换**：本地不可用时无缝切换到云端备用

## 🏗️ 项目架构

```
openclaw-gateway/
├── client/              # 智能客户端（终端设备）
├── gateway/             # 本地网关（连接LM Studio）
├── coordinator/         # 云端协调器（境内服务器）
├── shared/              # 共享组件和工具
├── docs/                # 技术文档
├── tests/               # 测试代码
├── examples/            # 使用示例
├── PRD.md               # 产品需求文档
├── design.md            # 概要设计文档  
├── todo.md              # 开发任务列表
└── README.md            # 项目说明
```

## 🚀 快速开始

### 1. 克隆仓库
```bash
git clone https://gitee.com/dougio/openclaw-gateway.git
cd openclaw-gateway
git checkout develop
```

### 2. 创建 Python 虚拟环境
```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows (PowerShell):
.\venv\Scripts\Activate.ps1
# Linux/macOS (WSL2):
source venv/bin/activate
```

### 3. 安装依赖
```bash
pip install -r requirements.txt
```

### 4. 配置和运行

#### 选项A: 仅使用本地网关（基础模式）
```bash
# 启动 LM Studio 并监听 1234 端口
# 运行本地网关
python -m gateway
```

#### 选项B: 完整混合架构（推荐）
```bash
# 1. 部署云端协调器到境内服务器
python -m coordinator

# 2. 在终端设备运行智能客户端
python -m client
```

## 📋 功能特性

### 客户端功能
- **自动配置发现**：启动时从云端获取最新配置
- **环境检测**：自动检测本地GPU和LM Studio状态
- **混合执行**：智能选择本地或云端执行任务
- **离线工作**：网络中断时使用缓存继续工作

### 本地网关功能
- **WebSocket API**：标准的 OpenClaw WebSocket 接口 (18789端口)
- **LM Studio集成**：连接 localhost:1234 的 LM Studio
- **聊天完成功能**：支持基于聊天的 AI 交互
- **模型管理**：列出和管理可用的本地模型

### 云端协调器功能
- **配置管理**：统一管理所有客户端配置
- **状态监控**：监控客户端在线状态和能力
- **智能路由**：根据任务类型决定执行位置
- **故障容错**：本地不可用时提供备用API服务

## 🔧 支持的命令

Gateway 支持以下 WebSocket 命令：

- `ping`：测试连接
- `status`：获取网关状态和配置  
- `chat`：向 LM Studio 发送聊天完成请求
- `models`：列出 LM Studio 中可用的模型

## 🌐 配置说明

### 默认配置
- **本地网关端口**：18789
- **LM Studio URL**：`http://localhost:1234/v1`
- **云端协调器**：需要部署到境内云服务器

### 自定义配置
创建 `config.yaml` 文件来自定义配置：

```
# 客户端配置
client:
  coordinator_url: "https://your-china-server.com:8080"
  local_gateway_port: 18789
  
# 网关配置  
gateway:
  port: 18789
  lmstudio_url: "http://localhost:1234/v1"
  lmstudio_api_key: "lm-studio"

# 协调器配置
coordinator:
  port: 8080
  enable_https: true
```

## 📚 文档资源

- **[PRD.md](PRD.md)** - 产品需求文档
- **[design.md](design.md)** - 概要设计文档  
- **[todo.md](todo.md)** - 开发任务列表
- **[examples/](examples/)** - 使用示例

## 💡 使用场景

### 日常开发
- 在笔记本上编写代码时，AI辅助编程任务自动在本地GPU执行
- 节省80%以上的API费用，响应速度更快

### 多设备切换  
- 换到新电脑后，只需运行客户端即可自动配置
- 无需手动设置LM Studio和网关

### 网络受限环境
- 完全在国内网络环境下工作
- 不依赖GitHub、Google等境外服务

## 🛠️ 开发说明

这是 `develop` 分支，包含完整的混合架构实现。

### 目录说明
- **client/**: 智能客户端，运行在终端设备上
- **gateway/**: 本地网关，连接LM Studio  
- **coordinator/**: 云端协调器，部署在境内服务器
- **shared/**: 共享的工具函数和数据模型
- **docs/**: 详细的技术文档
- **tests/**: 单元测试和集成测试
- **examples/**: 各种使用场景的示例代码

### 技术栈
- **Python 3.8+**
- **websockets**: WebSocket通信
- **aiohttp**: 异步HTTP客户端
- **pyyaml**: 配置文件解析

## 📈 成本效益

| 方案 | 月成本 | 年成本 | 特点 |
|------|--------|--------|------|
| 纯云端API | ￥150-300 | ￥1800-3600 | 简单但昂贵 |
| 本地GPU方案 | ￥30-60 | ￥360-720 | 经济高效 |
| 混合架构 | ￥100-150 | ￥1200-1800 | 最佳平衡 |

**ROI周期**: 1-3个月回本，长期节省80%以上成本。