OpenHands Agent Canvas 开发环境如何锁定 agent-server 版本OH_AGENT_SERVER_LOCAL_PATH、GIT_REF 与 VERSION 的优先级【免费下载链接】OpenHands OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands在 OpenHands Agent Canvasagent-canvas里跑npm run dev时后端 agent-server 是通过uvx临时安装并启动的启动哪一份代码由环境变量决定本地 SDK checkout、某个 git 分支/commit、还是 PyPI 上的固定版本。本文说明这三个变量OH_AGENT_SERVER_LOCAL_PATH、OH_AGENT_SERVER_GIT_REF、OH_AGENT_SERVER_VERSION的优先级、各自的写法与前置要求以及启动后如何确认实际生效的是哪一个。适用对象是 Agent Canvas 仓库内的本地开发栈npm run dev/npm run dev:minimal/npm run dev:static以及已发布的agent-canvas命令npx openhands/agent-canvas。两者共用同一套 版本选择逻辑。版本选择的优先级docs/DEVELOPMENT.md 的 “Agent server version selection” 一节给出的规则是按最高优先级先命中先生效——OH_AGENT_SERVER_LOCAL_PATH指向本地software-agent-sdkcheckout 的绝对路径OH_AGENT_SERVER_GIT_REFgit commit SHA 或分支名优先级高于版本号OH_AGENT_SERVER_VERSION指定 PyPI 版本都不设置时使用默认的已发布版本。这条规则与 scripts/dev-safe.mjs 中buildAgentServerCommand()的实现一致函数依次检查LOCAL_PATH、GIT_REF、VERSION命中的第一个分支决定uvx参数AGENTS.md 和 .env.sample 也按同一顺序注释了这三个变量。如果同时设置了多个变量只有优先级最高的那个生效其余被忽略——不需要手动清空。三种锁定方式的写法与前置要求锁定到本地 SDK checkoutOH_AGENT_SERVER_LOCAL_PATHOH_AGENT_SERVER_LOCAL_PATH/abs/path/to/software-agent-sdk npm run dev该变量必须满足三个条件启动前就会校验见validateLocalAgentServerPath()scripts/dev-safe.mjs必须是绝对路径否则报OH_AGENT_SERVER_LOCAL_PATH must be an absolute path, got: ...目录必须存在否则报OH_AGENT_SERVER_LOCAL_PATH does not exist: ...checkout 内必须同时包含openhands-agent-server、openhands-sdk、openhands-tools、openhands-workspace四个 workspace 包缺任何一个都会报OH_AGENT_SERVER_LOCAL_PATH is missing expected workspace package 子目录名: ...。命中本地路径后启动命令等价于uvx --reinstall --from path/openhands-agent-server --with-editable path/openhands-sdk ...外加openhands-tools、openhands-workspace两个 editable 依赖和posthog6,7约束。也就是说openhands-agent-server每次启动都从本地源码重新安装其余三个包以 editable 方式安装所以改openhands-sdk/openhands-tools/openhands-workspace的源码后重启即可生效不需要手动重装。这是配合 SDK 二次开发最常用的模式。锁定到 git 分支或 commitOH_AGENT_SERVER_GIT_REF# 按分支 OH_AGENT_SERVER_GIT_REFmain npm run dev # 按 commit SHA OH_AGENT_SERVER_GIT_REFabc1234 npm run devGIT_REF可以是分支名或 commit SHA。四个 SDK 包全部从同一个 ref 安装保证包间接口一致。这里有一个代码里明确写出的坑scripts/dev-safe.mjs 中 git 分支的注释software-agent-sdk的某个分支可能带着和 PyPI 已发布版本相同的版本字符串例如都叫1.26.0此时uvx不加--reinstall会静默复用缓存的 PyPI wheel你要求的 git ref 根本没被使用。启动脚本已经自动带上--reinstall规避了这一点——如果你在其他环境里手写uvx命令引用 git ref需要自己加上。锁定到具体 PyPI 版本OH_AGENT_SERVER_VERSIONOH_AGENT_SERVER_VERSION1.18.0 npm run dev版本值会同时钉住openhands-agent-server、openhands-sdk、openhands-tools、openhands-workspace四个包--from openhands-agent-serverversion加三个--with openhands-xxxversion并额外附带两条约束agent-client-protocol0.11和posthog6,7。前一条约束在 config/defaults.json 中解释为临时上限openhands-sdk对agent-client-protocol没有设上界而 acp 0.11.0 调整了 ACPprompt()参数顺序会导致 SDK 的 ACP 客户端校验失败所以在修复版 SDK 发布前固定acp 0.11。默认版本两个文档说法不同以代码为准不设置任何变量时的默认值仓库内两处描述不完全一致docs/DEVELOPMENT.md 说“默认使用 PyPI 上最新发布的版本”config/defaults.json 的versions.agentServer固定为1.44.0AGENTS.md 也写明默认是“released PyPI version1.44.0”。实际代码行为是第二种buildAgentServerCommand()的默认分支使用--from openhands-agent-server${DEFAULT_AGENT_SERVER_VERSION}其中DEFAULT_AGENT_SERVER_VERSION直接读自config/defaults.json即精确钉在1.44.0而非“最新版”。可以理解为文档措辞滞后于代码实际默认行为是读 defaults.json 的固定值defaults.json顶部的注释也说明它是 npm 与 Docker 安装路径共用的版本单一事实来源。另外config/defaults.json 的compatibility.minimumAgentServer为1.28.0即 Agent Canvas 要求 agent-server 不低于 1.28.0。用OH_AGENT_SERVER_VERSION或OH_AGENT_SERVER_GIT_REF选择版本时选定的版本应满足这一下限。启动后如何确认实际生效的来源确认方式直接看启动日志。启动脚本会为每个服务打印来源agent-server 这一行形如来源标签由buildAgentServerCommand()的source字段生成agent-server: local (/abs/path/to/software-agent-sdk) # 命中 LOCAL_PATH agent-server: git (main) # 命中 GIT_REF agent-server: PyPI (1.18.0) # 命中 VERSION agent-server: PyPI (1.44.0, default) # 未设置任何变量这是 scripts/dev-safe.mjs 和 scripts/dev-with-automation.mjs 中实际打印的四种标签对照它就能判断你的变量是否生效如果期望local (...)却看到PyPI (..., default)说明变量没传进启动进程例如写在了不生效的 shell 里。对于已发布的agent-canvas命令还可以用--info查看默认栈配置npx openhands/agent-canvas --info该命令会输出当前包版本、默认栈版本agent-server / automation、兼容下限agent-server: 1.28.0、各服务端口并列出可用的覆盖变量OH_AGENT_SERVER_VERSION, OH_AGENT_SERVER_GIT_REF, OH_AGENT_SERVER_LOCAL_PATH见 bin/agent-canvas.mjs。--info展示的是默认配置不能替代上面的启动日志来判断本次运行实际用了哪个来源。启动本身还有一个健康检查waitForServer()会轮询127.0.0.1:18000直到返回 200最长 30 秒超时抛Timed out waiting for agent-server at ...。超时通常发生在uvx首次拉取对应版本依赖缓慢或版本不存在时。排查要点与限制LOCAL_PATH的三个校验错误非绝对路径 / 目录不存在 / 缺 workspace 包都在启动早期快速失败不需要等服务超时才暴露.env.sample 中三个变量按优先级从高到低排列注释与正文一致。OH_AGENT_SERVER_GIT_REF与OH_AGENT_SERVER_VERSION同时设置时git ref 赢同理前两个都设置时本地路径赢。没有“部分生效”的中间状态。git ref 路径依赖uvx从software-agent-sdk仓库拉取需要本机uvx可用且有对应仓库的访问权限uvx不在 PATH 时启动脚本会给出安装指引而不是静默失败。本地 checkout 模式下只有openhands-agent-server每次重新安装openhands-sdk、openhands-tools、openhands-workspace是 editable 安装——直接改这三个包的源码即可在重启后生效改动 agent-server 包本身则依赖每次启动的--reinstall。这些变量只影响 agent-server 的安装来源automation 后端的版本另有OH_AUTOMATION_VERSION/OH_AUTOMATION_GIT_REF控制不在本文范围内。完成验证的标准就一条启动日志中agent-server:一行的来源标签与你要锁定的来源一致local (...)/git (ref)/PyPI (version)且waitForServer在 30 秒内通过、前端可从http://localhost:8000/ingress 端口访问。【免费下载链接】OpenHands OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenHands Agent Canvas 开发环境如何锁定 agent-server 版本：OH_AGENT_SERVER_LOCAL_PATH、GIT_REF 与 VERSION 的优先级
OpenHands Agent Canvas 开发环境如何锁定 agent-server 版本OH_AGENT_SERVER_LOCAL_PATH、GIT_REF 与 VERSION 的优先级【免费下载链接】OpenHands OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands在 OpenHands Agent Canvasagent-canvas里跑npm run dev时后端 agent-server 是通过uvx临时安装并启动的启动哪一份代码由环境变量决定本地 SDK checkout、某个 git 分支/commit、还是 PyPI 上的固定版本。本文说明这三个变量OH_AGENT_SERVER_LOCAL_PATH、OH_AGENT_SERVER_GIT_REF、OH_AGENT_SERVER_VERSION的优先级、各自的写法与前置要求以及启动后如何确认实际生效的是哪一个。适用对象是 Agent Canvas 仓库内的本地开发栈npm run dev/npm run dev:minimal/npm run dev:static以及已发布的agent-canvas命令npx openhands/agent-canvas。两者共用同一套 版本选择逻辑。版本选择的优先级docs/DEVELOPMENT.md 的 “Agent server version selection” 一节给出的规则是按最高优先级先命中先生效——OH_AGENT_SERVER_LOCAL_PATH指向本地software-agent-sdkcheckout 的绝对路径OH_AGENT_SERVER_GIT_REFgit commit SHA 或分支名优先级高于版本号OH_AGENT_SERVER_VERSION指定 PyPI 版本都不设置时使用默认的已发布版本。这条规则与 scripts/dev-safe.mjs 中buildAgentServerCommand()的实现一致函数依次检查LOCAL_PATH、GIT_REF、VERSION命中的第一个分支决定uvx参数AGENTS.md 和 .env.sample 也按同一顺序注释了这三个变量。如果同时设置了多个变量只有优先级最高的那个生效其余被忽略——不需要手动清空。三种锁定方式的写法与前置要求锁定到本地 SDK checkoutOH_AGENT_SERVER_LOCAL_PATHOH_AGENT_SERVER_LOCAL_PATH/abs/path/to/software-agent-sdk npm run dev该变量必须满足三个条件启动前就会校验见validateLocalAgentServerPath()scripts/dev-safe.mjs必须是绝对路径否则报OH_AGENT_SERVER_LOCAL_PATH must be an absolute path, got: ...目录必须存在否则报OH_AGENT_SERVER_LOCAL_PATH does not exist: ...checkout 内必须同时包含openhands-agent-server、openhands-sdk、openhands-tools、openhands-workspace四个 workspace 包缺任何一个都会报OH_AGENT_SERVER_LOCAL_PATH is missing expected workspace package 子目录名: ...。命中本地路径后启动命令等价于uvx --reinstall --from path/openhands-agent-server --with-editable path/openhands-sdk ...外加openhands-tools、openhands-workspace两个 editable 依赖和posthog6,7约束。也就是说openhands-agent-server每次启动都从本地源码重新安装其余三个包以 editable 方式安装所以改openhands-sdk/openhands-tools/openhands-workspace的源码后重启即可生效不需要手动重装。这是配合 SDK 二次开发最常用的模式。锁定到 git 分支或 commitOH_AGENT_SERVER_GIT_REF# 按分支 OH_AGENT_SERVER_GIT_REFmain npm run dev # 按 commit SHA OH_AGENT_SERVER_GIT_REFabc1234 npm run devGIT_REF可以是分支名或 commit SHA。四个 SDK 包全部从同一个 ref 安装保证包间接口一致。这里有一个代码里明确写出的坑scripts/dev-safe.mjs 中 git 分支的注释software-agent-sdk的某个分支可能带着和 PyPI 已发布版本相同的版本字符串例如都叫1.26.0此时uvx不加--reinstall会静默复用缓存的 PyPI wheel你要求的 git ref 根本没被使用。启动脚本已经自动带上--reinstall规避了这一点——如果你在其他环境里手写uvx命令引用 git ref需要自己加上。锁定到具体 PyPI 版本OH_AGENT_SERVER_VERSIONOH_AGENT_SERVER_VERSION1.18.0 npm run dev版本值会同时钉住openhands-agent-server、openhands-sdk、openhands-tools、openhands-workspace四个包--from openhands-agent-serverversion加三个--with openhands-xxxversion并额外附带两条约束agent-client-protocol0.11和posthog6,7。前一条约束在 config/defaults.json 中解释为临时上限openhands-sdk对agent-client-protocol没有设上界而 acp 0.11.0 调整了 ACPprompt()参数顺序会导致 SDK 的 ACP 客户端校验失败所以在修复版 SDK 发布前固定acp 0.11。默认版本两个文档说法不同以代码为准不设置任何变量时的默认值仓库内两处描述不完全一致docs/DEVELOPMENT.md 说“默认使用 PyPI 上最新发布的版本”config/defaults.json 的versions.agentServer固定为1.44.0AGENTS.md 也写明默认是“released PyPI version1.44.0”。实际代码行为是第二种buildAgentServerCommand()的默认分支使用--from openhands-agent-server${DEFAULT_AGENT_SERVER_VERSION}其中DEFAULT_AGENT_SERVER_VERSION直接读自config/defaults.json即精确钉在1.44.0而非“最新版”。可以理解为文档措辞滞后于代码实际默认行为是读 defaults.json 的固定值defaults.json顶部的注释也说明它是 npm 与 Docker 安装路径共用的版本单一事实来源。另外config/defaults.json 的compatibility.minimumAgentServer为1.28.0即 Agent Canvas 要求 agent-server 不低于 1.28.0。用OH_AGENT_SERVER_VERSION或OH_AGENT_SERVER_GIT_REF选择版本时选定的版本应满足这一下限。启动后如何确认实际生效的来源确认方式直接看启动日志。启动脚本会为每个服务打印来源agent-server 这一行形如来源标签由buildAgentServerCommand()的source字段生成agent-server: local (/abs/path/to/software-agent-sdk) # 命中 LOCAL_PATH agent-server: git (main) # 命中 GIT_REF agent-server: PyPI (1.18.0) # 命中 VERSION agent-server: PyPI (1.44.0, default) # 未设置任何变量这是 scripts/dev-safe.mjs 和 scripts/dev-with-automation.mjs 中实际打印的四种标签对照它就能判断你的变量是否生效如果期望local (...)却看到PyPI (..., default)说明变量没传进启动进程例如写在了不生效的 shell 里。对于已发布的agent-canvas命令还可以用--info查看默认栈配置npx openhands/agent-canvas --info该命令会输出当前包版本、默认栈版本agent-server / automation、兼容下限agent-server: 1.28.0、各服务端口并列出可用的覆盖变量OH_AGENT_SERVER_VERSION, OH_AGENT_SERVER_GIT_REF, OH_AGENT_SERVER_LOCAL_PATH见 bin/agent-canvas.mjs。--info展示的是默认配置不能替代上面的启动日志来判断本次运行实际用了哪个来源。启动本身还有一个健康检查waitForServer()会轮询127.0.0.1:18000直到返回 200最长 30 秒超时抛Timed out waiting for agent-server at ...。超时通常发生在uvx首次拉取对应版本依赖缓慢或版本不存在时。排查要点与限制LOCAL_PATH的三个校验错误非绝对路径 / 目录不存在 / 缺 workspace 包都在启动早期快速失败不需要等服务超时才暴露.env.sample 中三个变量按优先级从高到低排列注释与正文一致。OH_AGENT_SERVER_GIT_REF与OH_AGENT_SERVER_VERSION同时设置时git ref 赢同理前两个都设置时本地路径赢。没有“部分生效”的中间状态。git ref 路径依赖uvx从software-agent-sdk仓库拉取需要本机uvx可用且有对应仓库的访问权限uvx不在 PATH 时启动脚本会给出安装指引而不是静默失败。本地 checkout 模式下只有openhands-agent-server每次重新安装openhands-sdk、openhands-tools、openhands-workspace是 editable 安装——直接改这三个包的源码即可在重启后生效改动 agent-server 包本身则依赖每次启动的--reinstall。这些变量只影响 agent-server 的安装来源automation 后端的版本另有OH_AUTOMATION_VERSION/OH_AUTOMATION_GIT_REF控制不在本文范围内。完成验证的标准就一条启动日志中agent-server:一行的来源标签与你要锁定的来源一致local (...)/git (ref)/PyPI (version)且waitForServer在 30 秒内通过、前端可从http://localhost:8000/ingress 端口访问。【免费下载链接】OpenHands OpenHands: AI-Driven Development项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考