Wegent 是一个开源、可自托管的 AI 工作区（AI workspace），用于编码、协作与自动化。它的任务执行层wegent-executor是一个用 Rust 编写的执行器：既支持Docker 沙箱隔离运行，也支持本地设备运行时直接跑在你的 Mac/Linux/Windows 上，并通过持久化的Codex app-server完成 AI 编码集成。本文带你快速看懂这三大核心机制的设计原理，无需深入代码也能理解它的架构脉络。

一、先认识 wegent-executor：一个二进制，两种形态

整个执行器由 Rust 编译为单一二进制wegent-executor（构建说明见 executor/BUILD.md）：

• Docker 模式：在容器内启动 HTTP 执行服务，由 Executor Manager 统一调度，天然获得容器级隔离；
• 本地模式：作为桌面应用（Wework）的 sidecar 运行，通过 Socket.IO 与 Backend 通信，无需 Docker 环境。

两种模式共用同一套任务执行核心（Agent 引擎、协议层、事件流），因此云端沙箱与本地设备在能力上保持对齐。

二、Docker 模式：容器 + bubblewrap 的沙箱隔离

在 docker/executor/Dockerfile 中可以看到生产环境的隔离设计：

• 容器隔离：Rust 二进制被复制到镜像的/app/executor稳定路径，配合EXECUTOR_MODE=docker、端口10001运行，每个任务运行在独立容器中；
• 进程级沙箱：镜像中额外安装了bubblewrap，这是 Codex 在 Linux 上的沙箱 helper，让 AI 生成的 shell 命令、文件改动被限制在沙箱边界内；
• 能力预装：Claude Code、OpenAI Codex CLI、浏览器自动化（Playwright/Chromium）、文档生成依赖（LibreOffice、pandoc 等）都在镜像层固化，保证任务环境可复现。

容器之外还有一个 Python 写的Executor Manager（见 executor_manager/services/sandbox/），负责沙箱的创建、调度（scheduler.py）、健康检查（health_checker.py）、Skills 同步（skill_sync.py）与运行时绑定（runtime_binding.py），并维护sandboxes/{id}/heartbeat这类心跳链路（对应执行器侧 executor/src/heartbeat.rs）。

💡 一句话总结：Docker 管"环境边界"，bubblewrap 管"进程边界"，两层防线保护宿主机。

三、本地模式：你的电脑就是执行沙箱

本地模式的核心文档是 executor/docs/LOCAL_MODE.md。它在用户目录下建立独立主目录，实现"逻辑隔离"：

~/.wegent-executor/ ├── workspace/ # 代码仓库克隆位置（{task_id}/{repo_name}） ├── logs/ # 轮转日志 └── cache/skills/# Skills 缓存

关键组件（均在 executor/src/local/ 下）：

连接配置优先级为：环境变量 >~/.wegent-executor/device-config.json> 默认值。当 Wework 桌面端启动执行器并设置WEGENT_APP_IPC_DEVICE_ID时，本地控制面走 stdio IPC；而独立启动的本地执行器则沿用 Socket.IO 远端链路，两条链路可并存。

值得一提的是，这条本地设备链路是从 Python 版迁移到 Rust 的，executor/docs/LOCAL_DEVICE_PYTHON_MIGRATION_TESTS.md 逐条列出了迁移状态与测试覆盖，包括设备身份持久化、能力同步、终端会话（PTY）、取消任务等全部行为——这是 Rust 执行器"本地即生产级"的证据。

开发者的日常循环由 executor/local.sh 一条命令搞定：./local.sh all完成构建、停止、启动，./local.sh logs查看日志。

四、Codex 集成：持久化 app-server + JSON-RPC + 权限画像

Codex 集成是执行器中最精巧的部分，实现集中在 executor/src/agents/codex.rs。它不是"每次任务起一个 CLI 进程"，而是维护一个持久化的codex app-server进程，通过 stdio 上的 JSON-RPC（见 executor/src/agents/codex/json_rpc.rs）进行对话：

• 进程复用与自愈：app-server 按"二进制 + 专属 Home"维度共享；运行时代理变更、轮次卡死（默认 180 秒无进展）时会自动重启；Executor 关闭时会终止所有派生的 Agent 进程；
• 三级权限画像：任务请求中可指定:read-only（只读）、:workspace（工作区内可写）、:danger-full-access（完全访问），默认策略由 Backend 下发，AI 的能力边界因此是可审计、可配置的；
• 命名 Agent Home：executor/src/agents/instance_home.rs 为不同 Bot 分配独立的 Agent Home 目录，会话、Skills、插件状态互不干扰，并带文件锁防止并发写入；
• Skills 部署：executor/src/agents/runtime_capabilities.rs 负责从 Backend 拉取受管 Skills 包，先解包到暂存目录再原子替换，支持 ETag 增量同步。

五、凭证安全：本地模型代理

Codex 进程本身不接触任何模型供应商密钥。executor/src/server/local_model_proxy/ 在本地起了一个模型代理：Codex 只请求127.0.0.1上的固定路由，由代理负责注入凭证、附加自定义 Header、走出站代理、归一化 Responses 流，并把 Chat Completions 供应商翻译成对应协议。附带限流重试（1s/5s/10s/30s/60s 退避）与图片预算控制。

这意味着：即使某个 Skill 行为异常，它拿到的也只是本地回环地址，真实 API Key 始终留在执行器内存中。

六、上手路径：从零跑通本地执行器

1. 克隆仓库后进入executor目录执行cargo build --release --locked，产物在target/release/wegent-executor；
2. 设置连接信息后直接运行：

WEGENT_BACKEND_URL=http://localhost:8000 \ WEGENT_AUTH_TOKEN=your-auth-token \ ./dist/wegent-executor

3. 或者用一键脚本./local.sh all完成构建与后台启动；
4. 观察~/.wegent-executor/logs/executor.log确认设备已注册、心跳正常；
5. 生产部署则使用 Docker：docker build -f docker/executor/Dockerfile -t executor:latest .，交给 Executor Manager 统一编排。

七、小结

Wegent 的 Rust 执行器用一套代码同时解决了三个难题：

核心关键词回顾：Wegent Rust 执行器、沙箱隔离、本地设备运行时、Codex 集成、wegent-executor。如果你想进一步研究，建议从 executor/docs/LOCAL_MODE.md 的架构图与 executor/tests/ 下上百个 contract 测试入手——它们比任何文档都更准确地描述了这个执行器的行为契约。