Eigent 如何把 standalone brain 后端配置为 RemoteHands 远程集群资源模式【免费下载链接】eigentEigent: The Open Source Cowork Desktop - Local and Free Alternative to Claude Cowork and Codex项目地址: https://gitcode.com/GitHub_Trending/ei/eigentEigent 的 brain 后端既可以随 Electron 客户端运行也可以作为 standalone 后端独立启动uv run python main.py或 uvicorn 方式见 backend/README.md。默认情况下brain 的能力集terminal、browser、filesystem、MCP由本地部署环境自动探测决定当你的浏览器、终端等资源不再跑在 brain 本机而是由远端的资源池服务提供时就需要把 brain 切换为RemoteHands远程集群资源模式brain 本身不再持有执行能力而是按路由把acquire/release请求转发给配置的集群端点由集群返回可连接的资源端点。适用前提你已能按 backend/README.md 的方式启动 standalone brain你已经有一个或若干实现 acquire/release/health 接口的 HTTP 集群服务且 brain 所在机器可以通过base_url访问到它配置文件格式为 TOMLPython 3.11 自带的tomllib负责解析见 backend/app/hands/cluster_config.py。用环境变量开启 RemoteHands 模式brain 启动时通过init_environment_hands()初始化能力集。当环境变量EIGENT_HANDS_MODEremote或EIGENT_HANDS_REMOTE为真值时backend/app/router_layer/hands_resolver.py 中的init_environment_hands()会构造RemoteHands实例而不是走本地能力探测。RemoteHands的能力清单固定为terminal 可用、browser 可用、filesystem 仅限 workspace 目录、MCP 全开、deployment 标记为remote_cluster见 backend/app/hands/remote_hands.py。README 给出的最小配置方式是复制示例集群配置文件并导出两个变量cp backend/config/hands_clusters.example.toml ~/.eigent/hands_clusters.toml export EIGENT_HANDS_MODEremote export EIGENT_HANDS_CLUSTER_CONFIG_FILE~/.eigent/hands_clusters.toml随后按 README 中任意一种方式启动例如uv run python main.py。相关 standalone 环境变量如下摘自 backend/README.mdVariableDefaultDescriptionEIGENT_BRAIN_PORT5001Listening portEIGENT_BRAIN_HOST0.0.0.0Listening addressEIGENT_WORKSPACE~/.eigent/workspaceWorking directoryEIGENT_HANDS_MODE-Set toremoteto enableRemoteHands(remote cluster resource mode)EIGENT_HANDS_CLUSTER_CONFIG_FILE-Path toRemoteHandsconfig file (TOML);recommended远程模式下EIGENT_WORKSPACE决定RemoteHands的 workspace 根目录会话工作目录为workspace_root/session_id。注意 filesystem 能力是workspace_onlycan_access_filesystem()只放行能解析到 workspace 根目录之内的路径指向集群之外的路径会被拒绝。集群配置文件的结构示例文件 backend/config/hands_clusters.example.toml 展示了完整结构[defaults] timeout_seconds 10 verify_tls true acquire_path /acquire release_path /release health_path /health # auth_token_env EIGENT_HANDS_CLUSTER_AUTH_TOKEN [routes] browser browser_pool terminal terminal_pool model model_pool default gateway [clusters.gateway] base_url http://hands-gateway:8080 [clusters.browser_pool] base_url http://browser-cluster:8080 # auth_token_env EIGENT_BROWSER_CLUSTER_TOKEN [clusters.terminal_pool] base_url http://terminal-cluster:8080 [clusters.model_pool] base_url http://model-cluster:8080解析规则以 backend/app/hands/cluster_config.py 为准关键行为包括[defaults]提供各集群未显式指定时的取值timeout_seconds数值必须大于 0代码默认 10.0、verify_tls默认 true、acquire_path/release_path/health_path默认/acquire、/release、/health不以/开头的值会自动补前缀。每个[clusters.name]必须有base_url兼容旧字段名api否则抛HandsClusterConfigError。认证按优先级解析本集群的auth_token→ 本集群的auth_token_env指向一个环境变量名运行时读取其值→ defaults 的auth_token→ defaults 的auth_token_env都没有则不带认证头。示例文件中把auth_token_env写成注释即默认不启用 token。[routes]把资源路由键映射到集群名路由目标必须已定义否则报route route references unknown cluster cluster。路由键*或fallback会被归一化为default。不写[routes]时只有一个集群则自动作为default路由多个集群则每个集群名各自成为一条路由。运行时组装见 backend/app/router_layer/hands_resolver.py_build_cluster_from_routing()中若只有一条default路由则直接使用对应集群客户端否则包装为RoutedHandsCluster由它按资源类型选择集群。单元测试 backend/tests/app/hands/test_cluster_config.py 覆盖了以上规则多路由加环境变量 token、单集群无 routes 自动 default、fallback路由归一化、路由指向未知集群时报错、配置文件不存在时报错。集群端点需要实现的接口契约brain 侧对集群的调用全部通过HttpHandsClusterbackend/app/hands/http_hands_cluster.py你的集群服务至少要实现三个端点路径由配置中的acquire_path/release_path/health_path拼接在base_url之后POST {acquire_path}请求体包含type、resource_type、session_id、tenant_id以及透传的额外参数。响应必须是 JSON且能从中取到资源端点字段——代码依次取endpoint、cdp_url、url支持{data: {...}}或{result: {...}}包一层再解包。取不到端点时 brain 侧抛RuntimeError(Hands cluster acquire response missing endpoint)。POST {release_path}请求体为{session_id: ...}。返回 404 会被记录为 warning 后正常返回幂等释放其他错误状态码会向上抛出。GET {health_path}返回 JSON用于健康检查。请求头默认带Accept: application/json配置了 token 时附加Authorization: Bearer token。每次调用都受timeout_seconds约束verify_tls控制 HTTPS 证书校验。资源获取在RemoteHands.acquire_resource()中同步桥接到集群的异步 API要求不在运行中的事件循环内被调用若release_resource()在事件循环内被调用release 会转为 best-effort 的create_task调度。启动验证日志与 /health?detailtrue两处可以确认 RemoteHands 是否真的生效启动日志。backend/main.py在启动时调用init_environment_hands()并记录EnvironmentHands initialized: mode...RemoteHands.mode返回full。同时 backend/app/router_layer/hands_resolver.py 会打印Initializing RemoteHands from env switch含 mode 与 remote_enabled以及Loaded hands cluster config file含 config_file 与路由列表或Configured HttpHandsCluster含 cluster_api、各路径、timeout、verify_tls、has_auth_token。HTTP 检查。backend/app/controller/health_controller.py 的GET /health支持?detailtrue返回当前 Hands 的get_capability_manifest()并附加browser_cdp_reachable字段。RemoteHands 生效时capabilities 应为{ mode: full, terminal: true, browser: true, filesystem: workspace_only, mcp: all, mcp_allowlist: [], deployment: remote_cluster, workspace_root: /HOME/.eigent/workspace, browser_cdp_reachable: false }其中workspace_root取决于EIGENT_WORKSPACE环境变量browser_cdp_reachable取决于EIGENT_CDP_URL或本机 9222 端口的 CDP 探测结果远程模式下它通常不是判断集群是否就绪的依据——集群自身的健康检查走的是各集群的health_path。配置错误的行为与限制配置文件缺失、路径不是文件、TOML 非法或路由指向未知集群时load_hands_cluster_config抛HandsClusterConfigError_build_remote_cluster()捕获后记录 warningFailed to load hands cluster config file ...并继续以clusterNone创建RemoteHands。此时 brain 仍按 remote 模式运行但浏览器资源获取会退化为本地回退端点日志给出RemoteHands enabled but EIGENT_HANDS_CLUSTER_CONFIG_FILE is missing/invalid; browser resource acquisition will fallback to localhost endpointacquire_resource(browser)直接返回http://localhost:9222port参数可调非 browser 类型在未配置集群时抛ValueError。也就是说看到该 warning 后若任务仍要访问远端浏览器池应修正 TOML 或EIGENT_HANDS_CLUSTER_CONFIG_FILE指向的文件后重启。filesystem 能力固定为workspace_onlyMCP 固定为all且 allowlist 为空这些不随 TOML 变化TOML 只决定路由到哪个集群。除环境变量外backend/app/router_layer/hands_resolver.py 的get_hands_for_channel()还支持通过hands_override参数full/sandbox/remote强制选择 Hands 实现README 中记为调试用途X-Hands-Override排障时可用它确认问题出在环境开关还是集群配置上。release返回 404 被视为正常资源已不在集群侧不应当作故障处理。完成以上步骤后standalone brain 即完成向远程集群资源模式的切换启动日志、/health?detailtrue的deployment: remote_cluster清单以及集群侧收到的/acquire请求共同构成核对依据。【免费下载链接】eigentEigent: The Open Source Cowork Desktop - Local and Free Alternative to Claude Cowork and Codex项目地址: https://gitcode.com/GitHub_Trending/ei/eigent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考