在本地设备上执行AI任务
本地设备支持允许您使用个人电脑(Mac、Linux 或 Windows)作为任务执行器,让 AI 任务直接在本地机器上运行。
📋 目录
🎯 概述
什么是本地设备支持?
本地设备支持允许您的个人电脑作为 Wegent 的任务执行器。任务不再在云端基础设施上运行,而是直接在您的本地机器上执行,并提供实时流式反馈。
核心价值
| 优势 | 描述 |
|---|---|
| 更低延迟 | 本地直接执行,无需网络传输延迟 |
| 数据隐私 | 您的代码和数据永远不会离开本地机器 |
| 环境控制 | 使用本地安装的工具、依赖和配置 |
| 成本节约 | 减少云端执行资源消耗 |
| 自定义设置 | 访问本地凭证、自定义工具和专业软件 |
📲 设备注册
前置条件
在注册本地设备之前,请确保您具备:
- 有效凭证的 Wegent 账号
- 在您的机器上安装了 Wegent Executor
- 能够连接到 Wegent 后端的网络
- 已配置 Claude Code SDK(用于 ClaudeCode shell 类型)
安装 Wegent Executor
一键安装(推荐)
macOS / Linux:
curl -fsSL https://github.com/wecode-ai/Wegent/releases/latest/download/local_executor_install.sh | bash
Windows (PowerShell):
irm https://github.com/wecode-ai/Wegent/releases/latest/download/local_executor_install.ps1 | iex
安装脚本将会:
- 检查并安装 Node.js 18+(Claude Code 运行所需)
- 安装或升级 Claude Code SDK
- 下载适合您平台的二进制文件
- 将二进制文件添加到系统 PATH
Linux AMD64 Claude CLI 要求
Rust executor 二进制不会内置 Claude CLI。运行环境中必须存在可执行的 claude 命令,并满足 Wegent 要求的 Claude Code 最低版本。安装脚本和设备镜像会在 executor 二进制之外单独安装或升级 Claude Code。
使用个人 Codex CLI 配置
默认情况下,executor 会使用 Wegent 下发的 Claude/Codex 模型和 provider 配置。需要使用个人 Codex 登录信息时,在 Wework 的【设置】->【个人】中从设备导入或上传 ~/.codex/auth.json,再启用“个人配置”。设备心跳发现本机缺少 Codex auth 文件时,会在后台同步该认证;如果设备上已存在 ~/.codex/auth.json,不会覆盖。使用 Codex 的 GPT 模型会通过该认证账户访问 Codex。
如果访问 Codex 需要代理,可以先在 Wework 的【设置】->【个人】->【代理】中保存个人代理地址,再回到【Codex 认证】中启用“Codex 代理”。Wegent 会在执行 Codex 时注入 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 以及对应的小写环境变量。已有 NO_PROXY 或 no_proxy 时会沿用现有值;未配置时默认绕过 localhost、127.0.0.1、::1 和 host.docker.internal。
Wegent 会根据用户设置在执行请求中显式标记 Codex 是否使用个人配置,不再通过 WEGENT_LOCAL_CLI_CONFIG_RUNTIMES 环境变量判断。
统一管理本地 Skills
如果同一台本地设备同时使用 Claude Code 和 Codex,可以在 Wework 的【设置】->【编码】->【技能】中启用统一管理。Wegent 会在所选在线 Claude Code 设备上创建 ~/.agents/skills,把 ~/.codex/skills 和 ~/.claude/skills 中已有的技能移动到该目录,并把两个旧目录改成指向 ~/.agents/skills 的软链接。
该操作可以重复执行。重名技能不会被覆盖;系统会为后迁移的目录追加来源后缀,并在页面展示迁移数量。启用后,输入框里的本地 Skill 自动补全会把 ~/.agents/skills 中的技能视为 Claude 和 Codex 都可用。
构建设备镜像
仓库提供 docker/device/Dockerfile 用于构建云设备或本地设备基础镜像。该镜像会安装 code-server、weiboplat.wecoder-agent 扩展、Claude Code CLI、Node.js 22、Python、Git,并把 executor/dist/wegent-executor 放到 /app/executor 和 ~/.wecode/wegent-executor/bin/wegent-executor。
镜像内默认用户为 wegent,默认密码为 wegent。该账号用于容器内 code-server 和终端 shell 场景;生产部署时建议通过运行时配置、访问控制或上游平台认证限制访问范围。
构建前请先准备与目标平台匹配的 Linux executor 二进制,并确认基础镜像也支持同一平台。例如构建 Linux AMD64 镜像时,executor/dist/wegent-executor 必须是 Linux x86-64 ELF 文件,不能使用 macOS 的 Mach-O 二进制;构建 Linux ARM64 镜像时,基础 Ubuntu 镜像的 rootfs 也必须是 arm64。
WECODE_CLI_CC_TOKEN=xxx \
WECODE_CLI_CC_INSTALL_URL=xxx \
docker buildx build --platform linux/amd64 \
-f docker/device/Dockerfile \
-t wegent-device:linux-amd64 \
--secret id=wecode_cli_cc_token,env=WECODE_CLI_CC_TOKEN \
--secret id=wecode_cli_cc_install_url,env=WECODE_CLI_CC_INSTALL_URL \
--load .
executor 二进制不包含 Claude Code,因此通过 npm、基础镜像或其他方式安装 Claude Code 的镜像可以直接复用 executor/dist/wegent-executor。
运行设备镜像时通过环境变量传入 executor 连接信息,不要把 token 写入镜像:
docker run -d --platform linux/amd64 \
--name wegent-device \
-p 17888:17888 \
-e CODE_SERVER_PASSWORD=wegent \
-e WEGENT_BACKEND_URL=http://host.docker.internal:8000 \
-e WEGENT_AUTH_TOKEN="$WEGENT_AUTH_TOKEN" \
-e DEVICE_PUBLIC_BASE_URL=http://localhost:17888 \
wegent-device:linux-amd64
WEGENT_BACKEND_URL 必须是容器内可以访问到的 Backend 地址。如果 Backend 运行在同一台 macOS 或 Windows 宿主机上,通常使用 http://host.docker.internal:8000;生成的远程 Docker 命令会在需要时自动加入 --add-host host.docker.internal:host-gateway 以兼容 Linux Docker。DEVICE_PUBLIC_BASE_URL 是浏览器访问容器 session gateway 的地址,本机运行通常使用 http://localhost:17888。
添加远程 Docker 设备
远程 Docker 设备适合把一台自管服务器或容器主机接入 Wegent。它和云设备一样通过设备 WebSocket 协议接收任务,并支持终端与 code-server 会话;区别是容器生命周期由用户自己管理,Wegent 不会自动创建、重启或销毁这台 Docker 容器。
每个用户最多只能创建一台云设备。如果已经存在云设备,添加设备弹窗会禁用云设备创建入口,但仍可继续生成远程 Docker 设备命令。
在 Wework 中进入 设置 -> 连接,点击 添加设备,选择 远程 Docker 设备 并生成启动命令。Wegent 会先创建一条 remote 类型的 Device 记录,并根据 Backend 当前环境自动生成镜像地址、WEGENT_BACKEND_URL 和一把新的 remote device API Key,再把设备 ID 等参数放入返回的 docker run 命令中。复制命令到目标机器执行后,容器会注册为远程设备并显示在 远程设备 分组。
生成的命令会包含类似参数:
docker run -d \
--name wegent-remote-device \
--restart unless-stopped \
-e DEVICE_TYPE=remote \
-e EXECUTOR_MODE=local \
-e DEVICE_ID=<generated-device-id> \
-e DEVICE_NAME=<generated-device-name> \
-e WEGENT_BACKEND_URL=https://backend.example.com \
-e WEGENT_AUTH_TOKEN=<generated-api-key> \
-e DEVICE_PUBLIC_BASE_URL=http://localhost:17888 \
-p 17888:17888 \
-v wegent-remote-device-home:/home/wegent/.wecode/wegent-executor \
ghcr.io/wecode-ai/wegent-device:latest
生成接口会使用后端当前环境地址生成 WEGENT_BACKEND_URL,优先级为 REMOTE_DEVICE_BACKEND_URL、BACKEND_INTERNAL_URL、当前请求 Host。WEGENT_AUTH_TOKEN 每次生成命令时都会新建一把 remote device API Key,只出现在生成命令中,不会写入 Device CRD 的 remoteConfig。DEVICE_PUBLIC_BASE_URL 会根据当前前端访问域名推导,用于浏览器访问设备 session gateway。
默认镜像由 Backend 环境变量 REMOTE_DEVICE_DOCKER_IMAGE 控制,未配置时使用 ghcr.io/wecode-ai/wegent-device:latest。如果目标部署需要使用内部镜像仓库,请部署方在 Backend 启动环境中设置 REMOTE_DEVICE_DOCKER_IMAGE=<your-registry>/<your-image>:<tag>,用户侧不需要手动填写镜像地址。
设备镜像默认只启动 wegent-executor 和 code-server session gateway。Wework 项目终端通过 Backend 和 Executor 之间已有的 Socket.IO 连接中转,不要求设备有公网地址;云设备和远程 Docker 设备的 IDE/code-server 通过 DEVICE_PUBLIC_BASE_URL 对应的 session gateway 访问,因此该地址必须能从用户浏览器访问。公开版 Wework 不提供云桌面;部分产品发行版可以通过可选扩展增加该能力。
POST /api/projects/{project_id}/terminal:在项目路径中启动可写 PTY,返回transport=socketio的终端会话 ID;浏览器通过 Backend/terminalSocket.IO namespace 连接。POST /api/projects/{project_id}/code-server:返回带短期 token 的 code-server 访问 URL。设备镜像内的 code-server 使用固定密码运行,session gateway 会在服务端自动登录,浏览器不会看到 code-server 登录页或固定密码。POST /api/devices/{device_id}/code-server:打开指定设备上的 code-server。请求 body 可选传入path;传入时打开该远程项目目录,不传时使用设置页的默认工作目录。Executor 只接受默认 workspace、WEGENT_WORKSPACE_ROOTS配置目录和已保存的 Codex 项目根目录,越界路径会被拒绝。
Terminal 会话适用于本地设备、云设备和远程 Docker 设备:Backend 记录 session_id、用户、设备和 executor socket 绑定关系,前端使用登录 JWT 连接 /terminal namespace。浏览器加入会话 room 后,Backend 会通过 /local-executor namespace 发送带 ACK 的 terminal:attach;Executor 收到 attach 后才读取 PTY 中暂存的首屏输出,并通过 terminal:output 和 terminal:exit 回传,避免初始 Shell 提示符在浏览器订阅前丢失。Backend 还会把输入、resize、关闭事件转发给设备,设备上的 Executor 直接管理 PTY。code-server 是容器内持久进程,云设备和远程 Docker 设备通过 gateway 按项目路径打开目录;本地设备不支持 code-server 项目会话。
如果项目配置了 workspace.localPath、workspace.devicePath 或 workspace.checkoutPath,Wework 会在确认项目时通过设备命令创建该目录,并在启动 terminal 或 code-server 前再次确保目录存在;目录创建失败时项目不会静默进入不可用状态。localPath 用于本机 local executor,devicePath 用于绑定到具体 cloud 或 remote 设备的沙箱目录。若请求携带任务 ID 且该任务记录了执行工作区路径(例如 Git 新工作树),terminal 或 code-server 会直接在任务工作区路径中启动,不会回退到项目目录。
非项目会话工作区
Wework 入口的新对话在未选择项目(project_id=0)且绑定到在线设备时,Executor 会默认使用独立 Chats 工作区。如需关闭,可在设备运行环境中设置 WEGENT_EXECUTOR_STANDALONE_CHATS_ENABLED=false。Frontend 设备对话保留旧行为,仍使用任务临时工作区。
首轮任务会在 Chats 工作区树中创建目录,目录名根据日期和用户请求生成。默认根目录为 ~/.wecode/wegent-executor/workspace/chats。如需自定义位置,可在设备运行环境中设置 WEGENT_EXECUTOR_CHATS_DIR。Backend 会把最终路径写入任务元数据标签 standaloneChatWorkspacePath,后续继续该会话或打开历史会话时会复用同一目录。
项目会话不使用 Chats 工作区路径;项目会话默认使用项目配置中的 workspace.localPath、workspace.devicePath 或 workspace.checkoutPath。其中 workspace.devicePath 必须绑定到项目选择的 cloud 或 remote 设备。如果当前任务使用 Git 新工作树,项目工具会使用任务记录的工作树路径。
安装指定版本
macOS / Linux:
curl -fsSL https://github.com/wecode-ai/Wegent/releases/download/v1.0.0/local_executor_install.sh | bash -s -- --version v1.0.0
Windows (PowerShell):
$env:WEGENT_VERSION='v1.0.0'; irm https://github.com/wecode-ai/Wegent/releases/latest/download/local_executor_install.ps1 | iex
手动安装(开发环境)
- 克隆或下载 Wegent 仓库
- 安装依赖:
cd executor
pip install -e .
启动 Executor
以本地设备模式运行 executor:
# 使用环境变量或 ~/.wegent-executor/device-config.json 中的配置启动
wegent-executor
# 或用环境变量临时覆盖配置文件中的连接信息
export WEGENT_AUTH_TOKEN=your_jwt_token
export WEGENT_BACKEND_URL=https://your-wegent-instance.com
wegent-executor
安装脚本和首次启动会创建 ~/.wegent-executor/device-config.json。配置优先级是环境变量、device config、默认值;未设置 WEGENT_EXECUTOR_HOME 时默认使用 ~/.wegent-executor。executor 启动时始终提供 HTTP server;非 docker 模式还会通过当前进程的 stdin/stdout 提供本地 JSONL IPC,并在设置 WEGENT_BACKEND_URL 或配置文件中的 connection.backend_url 后连接 Backend。Wework App 只与自己直接启动的 executor 子进程通信,不会发现或附着 App 外手动启动的 executor;完整退出 App 时也只回收自己管理的子进程。stdout 只承载协议帧,诊断信息写入 stderr 和 ~/.wegent-executor/logs/executor.log。
Claude Code 执行超时
本地 executor 启动 Claude Code 子进程时,默认最长等待 24 小时。长时间代码生成、依赖安装或文件处理任务可以在这个时间内继续运行。若需要为特定环境调整该限制,可在启动 executor 前设置 WEGENT_CLAUDE_CODE_PROCESS_TIMEOUT_SECONDS。该配置只影响 Claude Code 子进程,不影响 native Codex app-server;Codex RPC 超时由 WEGENT_CODEX_RPC_TIMEOUT_SECONDS 控制。
export WEGENT_CLAUDE_CODE_PROCESS_TIMEOUT_SECONDS=172800
wegent-executor
获取 JWT Token
- 登录 Wegent Web 界面
- 进入 设置 → API Token
- 点击 生成 创建新 token
- 复制 token 用于启动 executor
注意:Token 有效期为 7 天,过期后需要重新生成。
🖥 使用本地设备
选择设备
在聊天界面中,您会看到设备选择器下拉菜单:
- 点击聊天输入框附近的 设备选择器 图标
- 查看可用设备及其状态:
- 🟢 在线:设备已连接且就绪
- 🔴 离线:设备未连接
- 🟡 繁忙:设备已达最大容量
- 选择您想使用的设备
- 像往常一样发送消息
设备状态指示
| 状态 | 图标 | 描述 |
|---|---|---|
| 在线 | 🟢 | 设备已连接,有可用槽位 |
| 离线 | 🔴 | 设备未连接 |
| 繁忙 | 🟡 | 所有 5 个并发槽位均被占用 |
| 默认 | ⭐ | 您的新任务默认设备 |
并发任务槽位
每个设备支持最多 5 个并发任务:
- 查看槽位使用情况:"2/5 槽位使用中"
- 所有槽位被占用时设备显示"繁忙"
- 如果选择繁忙设备,任务会排队等待
云端与本地切换
您可以动态选择执行位置:
| 选择 | 行为 |
|---|---|
| 云端(默认) | 任务在 Wegent 云端基础设施上执行 |
| 本地设备 | 任务在您选择的本地机器上执行 |
只需在发送每条消息之前更改设备选择即可。
项目中使用本地设备
创建项目时可以选择在线或繁忙的 ClaudeCode 本地设备。项目创建后,AI 任务会在该本地设备上执行,并使用项目配置中的本地路径或检出路径。
本地设备不支持项目工具栏中的云端连接能力:
| 功能 | 本地设备支持 |
|---|---|
| 终端 | 不支持 |
| IDE/code-server | 不支持 |
| 云桌面 | 不支持 |
| CPU/MEM/磁盘监控 | 不支持 |
如果项目绑定本地设备,工作区工具栏会隐藏终端、IDE 和桌面入口,并显示本地设备能力限制提示。需要这些连接和监控能力时,请选择云设备创建项目。
设置默认设备
- 在选择器中打开设备列表
- 点击您首选设备旁边的 星号图标
- 该设备将在新对话中被预先选中
⚙️ 设备管理
查看已注册设备
通过以下方式访问您的设备:
- 设备选择器:聊天界面中快速访问
- 设置页:进入 设置 → 连接 查看可连接设备
- API:
GET /devices用于程序化访问
管理连接页设备
设置 → 连接 页面会列出当前账号可连接的 ClaudeCode 设备,包括云设备和本地设备。页面仅展示 bind_shell=claudecode 的设备,并按云设备、本地设备分组。
云设备会显示在线状态、executor 版本、CPU、内存和磁盘使用率。当没有云设备时,点击 添加 可以创建一台新的云设备。创建请求返回后,页面会保留“云设备创建中”的提示;初始化通常需要 2-3 分钟,设备上线后会自动出现在列表中。Wework 前端可通过 VITE_CLOUD_DEVICE_SCALING_WIKI_URL 配置资源说明卡中的扩容 Wiki 链接,用于引导用户在 CPU、MEM 或磁盘持续超过 80% 时申请扩容或清理工作区缓存。
本地设备会显示设备名称、在线状态和 executor 版本,但不会展示 CPU、MEM、磁盘监控数据和资源监控说明,也不会展示终端、IDE、云桌面、重启或删除云资源等云设备专属操作。离线本地设备会显示删除入口,用于移除该设备的注册记录;如果设备重新连接,它会自动重新注册。
在线云设备和远程 Docker 设备支持直接打开交互式会话:
| 操作 | 后端接口 | 说明 |
|---|---|---|
| 终端 | POST /api/devices/{device_id}/terminal | 在默认工作目录 /home/ubuntu/.wegent-executor/workspace 启动 PTY;请求 body 可传 path 指定工作目录,并通过 Backend Socket.IO 中转 |
| IDE | POST /api/devices/{device_id}/code-server | 打开 code-server 会话;请求 body 可传 path 指定允许范围内的远程项目目录,不传时使用默认工作目录 |
终端会话不暴露设备端口;IDE 返回的访问地址带有短期 session token,并通过设备侧 session gateway 暴露。设备离线时,终端和 IDE 按钮不可用。
更多菜单提供低频管理操作:
| 操作 | 说明 |
|---|---|
| 重命名 | 点击设备名称或编辑图标,保存后会刷新列表 |
| 重启设备 | 需要二次确认;设备会短暂离线,进行中的连接可能中断 |
| 删除设备 | 需要二次确认;云资源会被释放 |
系统管理设备监控
管理员可在 系统管理 → 设备监控 查看所有用户的设备。该页面支持按状态、设备类型、Shell 类型、版本和关键词筛选设备,并提供单设备升级、云设备重启等操作。
页面顶部提供两个批量操作:
| 操作 | 作用范围 | 说明 |
|---|---|---|
| 升级全部本地设备 | 在线、bindShell=claudecode、executor 版本满足自动升级要求的本地设备 | 向符合条件的设备发送升级命令;离线、版本过低或正在运行任务的设备会跳过 |
| 重启全部云设备 | 所有云设备 | 通过部署侧云设备重启实现批量触发;没有配置重启实现时会返回未配置结果 |
批量操作提交后,接口会立即返回批次 ID,页面会轮询批次状态,避免长时间占用 HTTP 请求。批次完成后,页面会刷新设备列表和统计数据;状态结果包含总数、已触发数量、失败数量、跳过数量和逐设备错误信息,便于管理员判断是否需要按单台设备继续处理。
设备信息
每个设备显示:
| 字段 | 描述 |
|---|---|
| 名称 | 设备主机名(如 "Darwin - MacBook-Pro.local") |
| 状态 | 在线/离线指示器 |
| 版本 | executor 版本(如适用) |
| 资源使用率 | CPU、内存、磁盘使用率(仅云设备) |
| 槽位 | 并发任务容量(X/5) |
| 默认 | 如果设为默认则显示星号 |
管理设备
| 操作 | 方法 |
|---|---|
| 设为默认 | 点击星号图标 |
| 取消默认 | 再次点击当前默认设备的星号 |
| 删除设备 | 点击删除图标 |
注意:本地设备的删除只是移除注册记录。如果设备重新连接,它会自动重新注册。云设备在连接设置页删除时会释放对应云资源。
离线设备处理
当设备离线时:
- 系统会先等待一个很短的重连确认窗口,避免瞬时网络抖动误判为离线
- 如果设备未在确认窗口内恢复,运行中的任务会自动标记为 失败
- 错误消息指示设备断开连接
- 任务槽位会在确认设备离线后释放
- 设备在选择器中显示为灰色
❓ 常见问题
连接问题
设备无法连接
可能原因:
- JWT token 无效或已过期
- 网络连接问题
- 后端 URL 配置错误
解决方案:
- 从 Wegent UI 生成新的 JWT token
- 检查到 Wegent 后端的网络连接
- 验证
~/.wegent-executor/device-config.json或WEGENT_BACKEND_URL环境变量
设备连接后立即显示离线
可能原因:
- Token 验证失败
- 防火墙阻止 WebSocket
- 后端服务问题
解决方案:
- 检查 token 有效性和权限
- 确保允许 WebSocket 连接
- 检查 Wegent 后端日志中的错误
任务执行问题
任务立即失败
可能原因:
- Claude Code SDK 未安装
- 本地机器缺少依赖
- 权限不足
解决方案:
- 安装并配置 Claude Code SDK
- 安装所需依赖
- 检查文件系统权限
任务挂起无进展
可能原因:
- Claude Code SDK 卡住
- 执行期间网络中断
- 本地机器资源耗尽
解决方案:
- 重启 executor
- 检查网络连接
- 监控本地资源使用(CPU、内存)
设备管理问题
多个设备显示相同名称
这是正常的,如果您有多台主机名相似的机器。每个设备有基于硬件的唯一 ID。
无法删除设备
如果设备在删除后不断重新出现,说明 executor 仍在运行并重新注册。请先停止 executor,然后再删除。
💡 最佳实践
何时使用本地设备
| 使用场景 | 建议 |
|---|---|
| 敏感代码库 | ✅ 本地设备 |
| 快速迭代 | ✅ 本地设备 |
| 自定义工具需求 | ✅ 本地设备 |
| 批量处理 | 云端(更大容量) |
| 团队协作 | 云端(共享访问) |
| 移动/远程访问 | 云端(无需本地设置) |
多设备设置
如果您有多台机器:
- 分别注册每台设备
- 使用描述性主机名便于识别
- 将主要工作站设为默认
- 设备离线时使用云端作为后备
资源管理
- 任务执行期间监控本地资源使用
- 关闭不必要的应用程序以获得更好性能
- 考虑使用 SSD 存储以加快文件操作
- 确保有足够的 RAM 供 Claude Code SDK 使用
🔗 相关资源
文档
技术参考
- 本地设备架构 - 技术架构详解
💬 获取帮助
需要帮助?
- 📖 查看 常见问题
- 🐛 提交 GitHub Issue
- 💬 加入社区讨论
在本地机器上执行 AI 任务,完全掌控! 🚀