OpenClaw Python 技术深度解析

项目地址: https://github.com/openxjarvis/openclaw-python^[1]版本: 0.8.2 · Python 3.11+ · MIT License

1. 引言

1.1 项目定义

OpenClaw Python 是一个自托管的个人 AI 助手，它是 TypeScript 版本 OpenClaw^[2] 的 Python 实现。项目核心定位是连接消息渠道与大型语言模型（LLM）的统一网关，让用户能够通过熟悉的聊天界面（Telegram、飞书、Discord 等）与 AI 助手进行交互。

与同类工具相比，OpenClaw 的独特之处在于：

1.2 核心能力矩阵

┌─────────────────────────────────────────────────────────────┐│                    OpenClaw 能力全景                         │├─────────────────────────────────────────────────────────────┤│  消息渠道层    │ Telegram · 飞书(Lark) · Discord · Slack ·   ││               │ WhatsApp · Signal · IRC · Matrix · Teams    │├─────────────────────────────────────────────────────────────┤│  LLM 提供商   │ Gemini · Claude · GPT · DeepSeek · Grok ·   ││               │ Ollama(本地) · AWS Bedrock                   │├─────────────────────────────────────────────────────────────┤│  工具系统     │ read/write/edit · bash · browser · web_search││               │ subagents · cron · memory · image · tts      │├─────────────────────────────────────────────────────────────┤│  扩展机制     │ Skills(技能) · Extensions(插件) · Sandbox    │├─────────────────────────────────────────────────────────────┤│  协议层       │ ACP (AI Communication Protocol) · WebSocket  │└─────────────────────────────────────────────────────────────┘

1.3 技术栈概览

• 语言: Python 3.11+
• 核心框架: FastAPI + WebSocket + asyncio
• CLI 框架: Typer + Rich
• 配置: Pydantic Settings + JSON5
• 依赖管理: uv (Astral)
• 核心依赖库: 
• pi-agent / pi-ai / pi-coding-agent / pi-tui (来自 pi-mono-python)

2. 架构全景：分层设计与数据流

2.1 高层架构图

┌─────────────────────────────────────────────────────────────────────────────┐│                              客户端层 (Clients)                               ││  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    ││  │   Telegram   │  │    飞书       │  │   Discord    │  │   Web UI     │    ││  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘    │└─────────┼─────────────────┼─────────────────┼─────────────────┼────────────┘          │                 │                 │                 │          └─────────────────┴────────┬────────┴─────────────────┘                                     ▼┌─────────────────────────────────────────────────────────────────────────────┐│                           渠道适配层 (Channels)                               ││  ChannelManager ──► ChannelAdapter ──► ConnectionManager (WebSocket/HTTP)   │└─────────────────────────────────────────────────────────────────────────────┘                                     │                                     ▼┌─────────────────────────────────────────────────────────────────────────────┐│                            网关层 (Gateway)                                   ││  ┌───────────────────────────────────────────────────────────────────────┐  ││  │  GatewayBootstrap (40步初始化序列)                                      │  ││  │  ├── Config Loader (JSON5 + $include + ${ENV})                        │  ││  │  ├── PiAgentRuntime (pi-mono-python 驱动)                             │  ││  │  ├── ChannelManager (渠道生命周期管理)                                 │  ││  │  ├── SessionManager (会话状态管理)                                     │  ││  │  ├── ToolRegistry (工具注册与策略)                                     │  ││  │  ├── CronService (定时任务调度)                                        │  ││  │  └── SkillLoader (技能热加载)                                          │  ││  └───────────────────────────────────────────────────────────────────────┘  │└─────────────────────────────────────────────────────────────────────────────┘                                     │                                     ▼┌─────────────────────────────────────────────────────────────────────────────┐│                         Agent 执行引擎 (Agent Runtime)                         ││  ┌───────────────────────────────────────────────────────────────────────┐  ││  │  AgentLoop (核心执行循环)                                               │  ││  │  ├── LLM Provider (Gemini/OpenAI/Claude/Ollama)                       │  ││  │  ├── Tool Execution (工具调用与执行)                                   │  ││  │  ├── Event Streaming (事件流输出)                                      │  ││  │  ├── Context Management (上下文窗口管理)                               │  ││  │  ├── Failover Chain (模型故障转移)                                     │  ││  │  └── Auth Rotation (API Key 轮换)                                      │  ││  └───────────────────────────────────────────────────────────────────────┘  │└─────────────────────────────────────────────────────────────────────────────┘                                     │                                     ▼┌─────────────────────────────────────────────────────────────────────────────┐│                            工具层 (Tools)                                     ││  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐         ││  │   File   │ │   Bash   │ │ Browser  │ │ Subagent │ │   Cron   │         ││  │  (FS)    │ │ (Shell)  │ │  (CDP)   │ │ (Spawn)  │ │(Schedule)│         ││  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘         │└─────────────────────────────────────────────────────────────────────────────┘

2.2 核心数据流

用户消息 → ChannelAdapter → Gateway → SessionManager → PiAgentRuntime                                                              │                                                              ▼                                                    ┌──────────────────┐                                                    │   AgentSession   │                                                    │  (pi-mono-python) │                                                    └────────┬─────────┘                                                             │                    ┌────────────────────────────────────────┼────────────────────────────────────────┐                    │                                        │                                        │                    ▼                                        ▼                                        ▼            ┌───────────────┐                      ┌───────────────┐                      ┌───────────────┐            │  LLM Provider │                      │  Tool Calls   │                      │   Events      │            │  (Streaming)  │◄────────────────────►│  (Execution)  │                      │  (Streaming)  │            └───────────────┘                      └───────────────┘                      └───────┬───────┘                    │                                        │                                    │                    │                                        ▼                                    ▼                    │                               ┌───────────────┐                      ┌───────────────┐                    │                               │  ToolResult   │─────────────────────►│   Channel     │                    │                               │  (Callback)   │                      │   Output      │                    │                               └───────────────┘                      └───────────────┘                    │                    ▼            ┌───────────────┐            │  LLMResponse  │            │  (Text Delta) │            └───────┬───────┘                    │                    ▼            ┌───────────────┐            │   Channel     │            │   Response    │            └───────────────┘

2.3 核心设计思想

1. 分层与解耦

• UI/渠道层与业务逻辑完全分离，同一 Agent 逻辑可同时服务 Telegram、飞书、Web UI
• 协议层（ACP）与实现层解耦，支持 IDE 集成

2. 事件驱动架构

• 所有组件通过事件流通信，天然支持流式输出
• 支持中断（Steering）和后续消息（Follow-up）

3. 依赖注入与自动装配

• 工具通过依赖注入获取运行时上下文
• 技能（Skills）支持热加载和自动发现

4. 运行时抽象

• PiAgentRuntime 封装 pi-mono-python 的复杂性
• 提供统一的 run_turn() 接口，底层可切换不同 LLM Provider

3. 核心子系统深度解析

3.1 Gateway 网关层

3.1.1 职责定位

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

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

3.1.2 初始化流程（GatewayBootstrap）

# openclaw/gateway/bootstrap.pyclassGatewayBootstrap:"""    完整的 24 步初始化序列，匹配 TypeScript gateway/server.impl.ts    """asyncdefbootstrap(self, config_path: Path | None = None, ...) -> dict[str, Any]:# Step 0: 获取 Gateway PID 锁（防止多实例冲突）self._gateway_lock = acquire_gateway_lock(...)# Step 1: 设置环境变量self._set_env_vars()# Step 2: 加载配置self.config = load_config(config_path)# Step 3: 迁移旧配置self._migrate_legacy_config()# Step 4+: 初始化子代理注册表、默认 Agent、工作空间#          加载 Gateway 插件、创建运行时环境#          构建 Cron 服务、创建渠道管理器#          启动发现服务、注册技能变更监听器#          ...（共 24 步）

3.1.3 关键代码：GatewayBootstrap 启动入口

# openclaw/cli/main.py@app.command()defstart(port: int = 18789, ...):"""Start OpenClaw server with all features"""from ..gateway.bootstrap import GatewayBootstrapasyncdefstart_gateway():        bootstrap = GatewayBootstrap()        results = await bootstrap.bootstrap(force=force)# 保持运行直到收到终止信号        shutdown_event = asyncio.Event()        signal.signal(signal.SIGINT, lambda s, f: shutdown_event.set())await shutdown_event.wait()await bootstrap.shutdown()    asyncio.run(start_gateway())

3.2 Agent 执行引擎

3.2.1 架构演进

OpenClaw Python 经历了两代 Agent 运行时：

3.2.2 PiAgentRuntime 核心实现

# openclaw/gateway/pi_runtime.pyclassPiAgentRuntime:"""    Gateway 级运行时，基于 pi_coding_agent.AgentSession    维护 pi_coding_agent.AgentSession 实例池，每个 openclaw session_id 对应一个实例    提供兼容旧 MultiProviderRuntime 的 run_turn() 异步生成器接口    """def__init__(        self,        model: str = "google/gemini-2.0-flash",        fallback_models: list[str] | None = None,        cwd: str | Path | None = None,        system_prompt: str | None = None,        config: Any = None,        hook_runner: Any | None = None,):self.model_str = modelself.model_candidates: list[str] = [model] + list(fallback_models or [])self.cwd = str(cwd) if cwd elseNoneself.system_prompt = system_promptself._config = configself._hook_runner = hook_runner# 会话池: openclaw session_id → pi_coding_agent.AgentSessionself._pool: dict[str, Any] = {}self._event_listeners: list[Callable] = []# 认证轮换管理self._profile_store: Any | None = Noneself._rotation_manager: Any | None = None

3.2.3 AgentLoop：核心执行循环

# openclaw/agents/agent_loop.py@dataclassclassAgentOptions:"""Agent 执行配置选项"""    stream_fn: Callable[..., AsyncIterator[Any]] | None = None    session_id: str | None = None    get_api_key: Callable[[str], Awaitable[str | None]] | None = None    thinking_budgets: dict[str, int] | None = None# 关键：transform_context 在 convert_to_llm 之前执行    transform_context: Callable[[list[AgentMessage]], Awaitable[list[AgentMessage]]] | None = None    steering_mode: Literal["all", "one-at-a-time"] = "one-at-a-time"    follow_up_mode: Literal["all", "one-at-a-time"] = "one-at-a-time"    max_turns: int = MAX_OUTER_TURNS  # 默认 20classAgentLoop:"""    核心 Agent 执行循环，匹配 pi-mono 的 agent-loop.ts    功能：    - 流式 LLM 响应    - 工具调用提取与执行    - 支持中断（Steering）    - 事件发射    """asyncdefrun(        self,        messages: list[AgentMessage],        options: AgentOptions | None = None,) -> AsyncIterator[AgentEvent]:"""执行 Agent 循环，产生事件流"""# 1. 应用上下文转换（如上下文压缩）if opts.transform_context:            messages = await opts.transform_context(messages)# 2. 转换为 LLM 消息格式        llm_messages = (opts.convert_to_llm or default_convert_to_llm)(messages)# 3. 流式调用 LLMasyncfor response inself.provider.stream(llm_messages, tools=...):# 4. 处理响应，可能是文本增量或工具调用if response.type == "text_delta":yield TextDeltaEvent(delta=response.content)elif response.type == "tool_call":# 5. 执行工具yield ToolCallStartEvent(...)                result = awaitself._execute_tool(tool_call)yield ToolExecutionEndEvent(result=result)

3.2.4 消息转换管道

# openclaw/agents/agent_loop.pydefdefault_convert_to_llm(messages: list[AgentMessage]) -> list[LLMMessage]:"""    默认消息转换：AgentMessage → LLMMessage    - 过滤掉 custom 消息（内部使用）    - 保留 tool_calls 和 tool_call_id    """    llm_messages: list[LLMMessage] = []for msg in messages:if msg.custom:  # 跳过内部消息continue        llm_msg = LLMMessage(            role=msg.role,            content=msg.content,            images=msg.images        )if msg.tool_calls:            llm_msg.tool_calls = msg.tool_callsif msg.tool_call_id:            llm_msg.tool_call_id = msg.tool_call_id        llm_messages.append(llm_msg)return llm_messages

3.3 工具系统（Tools）

3.3.1 工具接口设计

# openclaw/agents/tools/base.pyclassAgentToolBase(ABC, Generic[TParams, TDetails]):"""    Agent 工具基类，匹配 Pi Agent 接口    工具必须实现：    - name: 工具标识符（LLM 使用）    - label: 人类可读名称（UI 使用）    - description: 工具描述（LLM 使用）    - parameters: JSON Schema 参数定义    - execute: 异步执行（支持流式更新）    """    @property    @abstractmethoddefname(self) -> str: ...    @property    @abstractmethoddeflabel(self) -> str: ...    @property    @abstractmethoddefdescription(self) -> str: ...    @property    @abstractmethoddefparameters(self) -> dict[str, Any]: ...    @abstractmethodasyncdefexecute(        self,        tool_call_id: str,        params: TParams,        signal: asyncio.Event | None = None,        on_update: Callable[[AgentToolResult], None] | None = None,) -> AgentToolResult[TDetails]:"""        执行工具        Args:            tool_call_id: 工具调用唯一 ID            params: 解析后的参数            signal: 取消信号            on_update: 流式更新回调        """        ...

3.3.2 工具分类与示例

3.3.3 工具策略与权限

# openclaw/agents/tool_policy.py# 工具别名映射TOOL_NAME_ALIASES: dict[str, str] = {"bash": "exec","apply-patch": "apply_patch",}# 工具组定义TOOL_GROUPS: dict[str, list[str]] = {"group:fs": ["read", "write", "edit", "apply_patch"],"group:runtime": ["exec", "process"],"group:web": ["web_search", "web_fetch"],"group:sessions": ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn"],# ...}# 工具配置文件（预定义权限集）TOOL_PROFILES: dict[str, dict[str, list[str]]] = {"minimal": {"allow": ["session_status"],    },"coding": {"allow": ["group:fs", "group:runtime", "group:sessions", "group:memory", "image"],    },"messaging": {"allow": ["group:messaging", "sessions_list", "sessions_history", "sessions_send"],    },"full": {},  # 允许所有}# 子代理工具黑名单SUBAGENT_TOOL_DENY_ALWAYS = ["gateway",        # 系统管理 - 子代理使用危险"agents_list",    # 系统管理"cron",           # 调度 - 主代理协调"memory_search",  # 记忆 - 通过 spawn prompt 传递]

3.4 渠道适配层（Channels）

3.4.1 渠道抽象模型

# openclaw/channels/base.pyclassChannelMeta(BaseModel):"""渠道元数据"""id: str    label: str    description: str | None = None    docs_path: str | None = None    icon_url: str | None = NoneclassChannelCapabilities(BaseModel):"""渠道能力声明"""    chat_types: list[str] = ["direct", "group"]    supports_media: bool = False    supports_reactions: bool = False    supports_threads: bool = False    block_streaming: bool = False# 是否分块发送（非流式）    native_commands: bool = False# 是否支持原生命令    supports_edit: bool = False# 是否支持编辑已发送消息    text_chunk_limit: int | None = None# 单条消息最大字符数classInboundMessage(BaseModel):"""标准化入站消息"""    channel_id: str    message_id: str    sender_id: str    sender_name: str    chat_id: str    chat_type: str# "direct", "group", "channel"    content: str    attachments: list[ChatAttachment] = []

3.4.2 渠道生命周期管理

# ChannelManager 负责所有渠道账户的生命周期classChannelManager:"""    渠道生命周期管理器    职责：    - 根据配置启动/停止渠道账户    - 监控连接健康状态    - 处理重连逻辑    """asyncdefstart_account(self, channel_id: str, account_id: str):"""启动指定渠道的指定账户"""        adapter = self._get_adapter(channel_id)        account = adapter.resolve_account(self.config, account_id)# 创建账户状态快照        status = ChannelAccountSnapshot(            account_id=account_id,            enabled=True,            configured=True,            running=True,        )# 启动账户（阻塞直到停止）await adapter.start_account(            cfg=self.config,            account_id=account_id,            account=account,            get_status=lambda: status,            set_status=lambda s: self._update_status(channel_id, account_id, s),        )

3.5 ACP 协议层

3.5.1 ACP 协议定位

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

核心特性：

• 传输: NDJSON over stdin/stdout 或 WebSocket
• 消息格式: JSON-RPC 2.0 风格
• 会话管理: 支持多会话、会话恢复
• 流式输出: 支持增量消息更新
• 工具调用: 标准化的工具调用序列

3.5.2 ACP 服务器实现

# openclaw/acp/server.pyasyncdefserve_acp_gateway(opts: AcpServerOptions | None = None) -> None:"""    启动 ACP 网关服务器    流程：    1. 连接到 OpenClaw Gateway (WebSocket)    2. 等待 Gateway 握手 (hello ok)    3. 从 stdin 读取 NDJSON 请求，分发到 AcpGatewayAgent    4. 将 NDJSON 响应/流式会话更新写入 stdout    """from openclaw.gateway.client import GatewayClient    gateway = GatewayClient(        url=gateway_url,        token=token,        password=password,        client_name="acp",        on_event=on_event,        on_hello_ok=on_hello_ok,        on_connect_error=on_connect_error,        on_close=on_close,    )# 读取 stdin 请求循环whilenot stopped:        line = await _read_stdin_lines()        request = json.loads(line)# 分发到对应方法        method = _METHOD_MAP.get(request["method"])if method and agent:            result = awaitgetattr(agent, method)(request.get("params", {}))await connection._write_response(request["id"], result=result)

3.5.3 ACP 会话管理

# openclaw/acp/types.py@dataclassclassAcpSession:"""ACP 会话状态"""    session_id: str# OpenClaw 会话 ID    session_key: str# 用户可见的会话标识    cwd: str# 当前工作目录    created_at: int# 创建时间戳（epoch ms）    abort_controller: Any = None# 取消令牌    active_run_id: str | None = None# 当前运行 ID@dataclassclassAcpServerOptions:"""ACP 服务器配置"""    gateway_url: str | None = None    gateway_token: str | None = None    gateway_password: str | None = None    default_session_key: str | None = None    default_session_label: str | None = None    require_existing_session: bool = False    reset_session: bool = False    prefix_cwd: bool = True    verbose: bool = False

4. 配置系统与运行时

4.1 配置加载机制

OpenClaw 使用分层配置系统：

配置来源（优先级从低到高）：1. 默认值 (defaults.py)2. 配置文件 (~/.openclaw/openclaw.json)3. 环境变量 (${ENV_VAR} 替换)4. 命令行参数

4.1.1 JSON5 配置支持

# openclaw/config/loader.pydef_parse_json5(text: str) -> Any:"""    解析 JSON5 文本（支持注释 + 尾随逗号）    使用字符串感知的注释剥离器，确保 URL 如 "http://127.0.0.1:11434" 不会被破坏    """try:import json5return json5.loads(text)except ImportError:pass# 字符串感知的注释剥离 + 尾随逗号移除    text = _strip_json5_comments(text)    text = re.sub(r",\s*([\]}])", r"\1", text)return json.loads(text)

4.1.2 $include 指令

def_resolve_includes(obj: Any, base_dir: Path, depth: int = 0) -> Any:"""    递归解析 {"$include": "./path.json"} 指令    示例配置：    {        "channels": {"$include": "./channels.json"},        "llm": {"$include": ["./gemini.json", "./fallback.json"]}    }    """ifisinstance(obj, dict) and"$include"in obj:        include_value = obj["$include"]        include_list = include_value ifisinstance(include_value, list) else [include_value]        merged: dict[str, Any] = {}for item in include_list:            include_path = (base_dir / str(item)).resolve()            raw = include_path.read_text(encoding="utf-8")            included = _parse_json5(raw)            resolved = _resolve_includes(included, include_path.parent, depth + 1)ifisinstance(resolved, dict):                merged = _deep_merge(merged, resolved)# 合并本地配置（$include 之外的键）        local = {k: v for k, v in obj.items() if k != "$include"}return _deep_merge(merged, local)

4.2 配置示例

// ~/.openclaw/openclaw.json{  // 网关配置  "gateway": {    "mode": "local",    "port": 18789,    "bind": "127.0.0.1"  },  // LLM 配置  "llm": {    "provider": "gemini",    "model": "google/gemini-2.0-flash",    "apiKey": "${GEMINI_API_KEY}",    "fallbackModels": ["google/gemini-1.5-pro"]  },  // 渠道配置  "channels": {    "telegram": {      "enabled": true,      "botToken": "${TELEGRAM_BOT_TOKEN}",      "dmPolicy": "pairing"  // pairing | allowlist | open | disabled    },    "feishu": {      "enabled": true,      "appId": "${FEISHU_APP_ID}",      "appSecret": "${FEISHU_APP_SECRET}",      "useWebSocket": true    }  },  // 工具安全策略  "tools": {    "exec": {      "security": "allowlist",  // deny | allowlist | full      "safe_bins": ["python", "git", "node"],      "ask": "on-miss"  // never | on-miss | always    }  }}

5. 安全与权限模型

5.1 多层权限体系

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

┌─────────────────────────────────────────────────────────────┐│  Layer 1: 渠道访问控制 (Channel Access)                       ││  ─────────────────────────────────────                      ││  控制谁可以与 Bot 交互                                        ││  • pairing: 新用户需通过 CLI 审批                            ││  • allowlist: 仅预批准用户                                   ││  • open: 任何人（慎用）                                       ││  • disabled: 禁用私聊                                         │├─────────────────────────────────────────────────────────────┤│  Layer 2: 命令执行安全 (Bash Execution)                       ││  ─────────────────────────────────────                      ││  控制 Agent 可执行的 Shell 命令                               ││  • deny: 禁止所有命令                                         ││  • allowlist: 仅允许 safe_bins 列表中的命令                   ││  • full: 允许任何命令（信任环境）                             │├─────────────────────────────────────────────────────────────┤│  Layer 3: 工具策略 (Tool Policies)                            ││  ─────────────────────────────────────                      ││  细粒度的工具权限控制                                          ││  • 白名单/黑名单                                              ││  • 速率限制                                                   ││  • 子代理特殊限制                                             │├─────────────────────────────────────────────────────────────┤│  Layer 4: 沙箱隔离 (Sandbox)                                  ││  ─────────────────────────────────────                      ││  Docker 容器隔离执行                                          ││  • 文件系统隔离                                               ││  • 网络隔离                                                   ││  • 资源限制                                                   │└─────────────────────────────────────────────────────────────┘

5.2 工具策略实现

# openclaw/agents/tools/policies.pyclassPolicyDecision(str, Enum):"""策略决策结果"""    ALLOW = "allow"    DENY = "deny"    REQUIRE_APPROVAL = "require_approval"classToolPolicy(ABC):"""工具执行策略基类"""defevaluate(        self,         tool_name: str,         arguments: dict[str, Any],         context: dict[str, Any]) -> PolicyDecision:raise NotImplementedErrorclassWhitelistPolicy(ToolPolicy):"""白名单策略：仅允许指定工具"""def__init__(self, allowed_tools: list[str]):self.allowed_tools = set(allowed_tools)defevaluate(self, tool_name: str, arguments: dict, context: dict) -> PolicyDecision:return PolicyDecision.ALLOW if tool_name inself.allowed_tools else PolicyDecision.DENYclassRateLimitPolicy(ToolPolicy):"""速率限制策略"""def__init__(self, max_calls: int, window_seconds: int = 60):self.max_calls = max_callsself.window_seconds = window_secondsself._call_history: dict[str, list[datetime]] = {}defevaluate(self, tool_name: str, arguments: dict, context: dict) -> PolicyDecision:        key = tool_name        now = datetime.now(UTC)# 清理过期记录        cutoff = now - timedelta(seconds=self.window_seconds)self._call_history[key] = [ts for ts inself._call_history.get(key, []) if ts > cutoff]# 检查限制iflen(self._call_history[key]) >= self.max_calls:return PolicyDecision.DENYself._call_history[key].append(now)return PolicyDecision.ALLOW

5.3 Docker 沙箱

# openclaw/agents/sandbox/docker.pyasyncdefcreate_sandbox_container(    name: str,    workspace_dir: Path,    image: str = DEFAULT_SANDBOX_IMAGE,) -> dict[str, Any]:"""    创建隔离的 Docker 容器用于代码执行    安全特性：    - 只读挂载工作空间    - 网络隔离（可选）    - 资源限制（CPU/内存）    - 非 root 用户运行    """    args = ["run", "-d", "--rm","--name", name,"--label", "openclaw.sandbox=true","-v", f"{workspace_dir}:{SANDBOX_AGENT_WORKSPACE_MOUNT}:ro","--network", "none",  # 默认禁用网络"--memory", "512m","--cpus", "1.0","--user", "1000:1000",  # 非 root        image,"sleep", "infinity"    ]returnawait exec_docker(args)

6. 核心设计理念总结

6.1 设计原则

6.2 与 TypeScript 版本的差异

7. 适用场景与限制

7.1 最适合的场景

1. 个人 AI 助手

• 通过 Telegram/飞书与 AI 交互
• 命令: uv run openclaw start

2. 开发工作流自动化

• 代码审查、文件操作、Shell 执行
• 工具: read / write / edit / exec

3. 多渠道客服系统

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

4. 定时任务调度

• 自动报告生成、数据同步
• 工具: cron + subagents

5. IDE 集成

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

6. 安全代码执行

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

8. 结语

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

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

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

资源链接

• 主仓库: https://github.com/openxjarvis/openclaw-python^[3]
• 依赖仓库: https://github.com/openxjarvis/pi-mono-python^[4]
• 原版 TypeScript: https://github.com/badlogic/pi-mono^[5]
• 使用指南: GUIDE.md^[6] / GUIDE_CN.md^[7]

引用链接