OpenClaw Python：自托管个人 AI 助手网关

calendar 2026-03-10 · 4 min read · AI Claude

OpenClaw Python 是一个自托管的个人 AI 助手网关，它连接消息渠道与大型语言模型（LLM），让用户能够通过熟悉的聊天界面（Telegram、飞书、Discord 等）与 AI 助手进行交互。

简介

OpenClaw Python 是 TypeScript 版本 OpenClaw 的 Python 实现，核心定位是连接消息渠道与大型语言模型的统一网关。项目采用 Python 3.11+ 开发，使用 FastAPI + WebSocket + asyncio 作为核心框架。

核心特性

特性OpenClaw一般 ChatBot 框架
架构定位网关 + 运行时分离通常紧耦合
协议支持ACP（AI 通信协议）+ WebSocket多为私有协议
渠道覆盖20+ 消息渠道（含企业级）通常 3-5 个
工具生态文件、Shell、浏览器、子代理、定时任务多为简单函数调用
沙箱执行Docker 隔离通常无
模型切换运时动态切换 + 故障转移通常静态配置

能力矩阵

OpenClaw 能力全景

技术栈

  • 语言: Python 3.11+
  • 核心框架: FastAPI + WebSocket + asyncio
  • CLI 框架: Typer + Rich
  • 配置: Pydantic Settings + JSON5
  • 依赖管理: uv (Astral)

架构设计

OpenClaw 采用分层架构设计，实现 UI/渠道层与业务逻辑的完全分离。

OpenClaw 架构设计

核心数据流

OpenClaw 核心数据流

设计原则

  1. 分层与解耦: UI/渠道层与业务逻辑完全分离，同一 Agent 逻辑可同时服务多个渠道
  2. 事件驱动架构: 所有组件通过事件流通信，天然支持流式输出
  3. 依赖注入与自动装配: 工具通过依赖注入获取运行时上下文
  4. 运行时抽象: PiAgentRuntime 封装底层复杂性，提供统一的 run_turn() 接口

安装与配置

安装

使用 uv 进行依赖管理：

1# 克隆仓库
2git clone https://github.com/openxjarvis/openclaw-python.git
3cd openclaw-python
4
5# 安装依赖
6uv sync

配置文件

配置文件位于 ~/.openclaw/openclaw.json，支持 JSON5 格式（注释 + 尾随逗号）：

 1// ~/.openclaw/openclaw.json
 2{
 3  // 网关配置
 4  "gateway": {
 5    "mode": "local",
 6    "port": 18789,
 7    "bind": "127.0.0.1"
 8  },
 9
10  // LLM 配置
11  "llm": {
12    "provider": "gemini",
13    "model": "google/gemini-2.0-flash",
14    "apiKey": "${GEMINI_API_KEY}",
15    "fallbackModels": ["google/gemini-1.5-pro"]
16  },
17
18  // 渠道配置
19  "channels": {
20    "telegram": {
21      "enabled": true,
22      "botToken": "${TELEGRAM_BOT_TOKEN}",
23      "dmPolicy": "pairing"  // pairing | allowlist | open | disabled
24    },
25    "feishu": {
26      "enabled": true,
27      "appId": "${FEISHU_APP_ID}",
28      "appSecret": "${FEISHU_APP_SECRET}",
29      "useWebSocket": true
30    }
31  },
32
33  // 工具安全策略
34  "tools": {
35    "exec": {
36      "security": "allowlist",  // deny | allowlist | full
37      "safe_bins": ["python", "git", "node"],
38      "ask": "on-miss"  // never | on-miss | always
39    }
40  }
41}

配置特性

$include 指令：支持配置文件拆分和模块化：

1{
2  "channels": {"$include": "./channels.json"},
3  "llm": {"$include": ["./gemini.json", "./fallback.json"]}
4}

环境变量替换：使用 ${ENV_VAR} 语法引用环境变量。

启动服务

1# 启动 OpenClaw 服务
2uv run openclaw start
3
4# 指定端口
5uv run openclaw start --port 18789

核心子系统

Gateway 网关层

Gateway 是 OpenClaw 的中央协调器，负责：

  • 配置加载与验证（24 步初始化序列）
  • 渠道生命周期管理（启动/停止/健康检查）
  • 会话管理（创建/恢复/持久化）
  • 工具注册与策略执行
  • 定时任务调度（Cron）
  • 技能热加载

Agent 执行引擎

OpenClaw 使用 PiAgentRuntime 作为 Agent 运行时，基于 pi-mono-python 实现：

 1# openclaw/gateway/pi_runtime.py
 2class PiAgentRuntime:
 3    """
 4    Gateway 级运行时，基于 pi_coding_agent.AgentSession
 5
 6    维护 AgentSession 实例池，每个 session_id 对应一个实例
 7    提供兼容的 run_turn() 异步生成器接口
 8    """
 9
10    def __init__(
11        self,
12        model: str = "google/gemini-2.0-flash",
13        fallback_models: list[str] | None = None,
14        cwd: str | Path | None = None,
15        system_prompt: str | None = None,
16    ):
17        self.model_candidates: list[str] = [model] + list(fallback_models or [])
18        # 会话池: session_id → AgentSession
19        self._pool: dict[str, Any] = {}

工具系统

工具分为以下类别：

类别工具功能描述
文件系统read / write / edit / apply_patch文件读写、编辑、应用补丁
执行环境exec (bash) / processShell 命令执行、进程管理
Webweb_search / web_fetch网页搜索、内容抓取
浏览器browserCDP 浏览器控制
子代理subagents / sessions_spawn子 Agent 创建与管理
定时任务cronCron 表达式调度
记忆memory_search / memory_get向量记忆检索
媒体image / tts图像生成、语音合成

ACP 协议层

ACP (AI Communication Protocol) 是 OpenClaw 定义的 IDE 与 Agent 之间的通信协议，类比于 LSP 对于编程语言的意义。

核心特性：

  • 传输: NDJSON over stdin/stdout 或 WebSocket
  • 消息格式: JSON-RPC 2.0 风格
  • 会话管理: 支持多会话、会话恢复
  • 流式输出: 支持增量消息更新

安全与权限模型

OpenClaw 采用四层独立权限模型：

OpenClaw 四层权限模型

Docker 沙箱

 1async def create_sandbox_container(
 2    name: str,
 3    workspace_dir: Path,
 4    image: str = DEFAULT_SANDBOX_IMAGE,
 5) -> dict[str, Any]:
 6    """
 7    创建隔离的 Docker 容器用于代码执行
 8
 9    安全特性：
10    - 只读挂载工作空间
11    - 网络隔离（可选）
12    - 资源限制（CPU/内存）
13    - 非 root 用户运行
14    """

适用场景

个人 AI 助手

通过 Telegram/飞书与 AI 交互，实现日常任务自动化。

1uv run openclaw start

开发工作流自动化

代码审查、文件操作、Shell 执行，使用 read / write / edit / exec 工具。

多渠道客服系统

统一回复 Telegram、Discord、Slack 消息，支持多账户配置。

定时任务调度

自动报告生成、数据同步，使用 cron + subagents 工具。

IDE 集成

通过 ACP 协议集成到 Zed、VS Code，实现流式代码补全和辅助。

安全代码执行

使用 Docker 沙箱执行不可信代码，配置 sandbox.enabled = true。

总结

OpenClaw Python 是一个工程化程度很高的个人 AI 助手网关，它在以下方面表现出色：

  • 架构清晰: 分层设计让渠道、协议、引擎、工具各司其职
  • 协议先行: ACP 协议的设计让 IDE 集成成为可能
  • 安全周全: 四层权限 + Docker 沙箱的组合拳
  • 生态兼容: 与 TypeScript 版本共享协议和配置格式

项目代表了个人 AI 基础设施的发展趋势：不是简单的 ChatBot 封装，而是一个完整的、可扩展的、安全的 AI 运行时环境。

参考资源