Hermes WebUI 扩展的 loopback sidecar 怎么配置 proxy_auth token 认证【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webuiHermes WebUI 的扩展可以为 manifest 声明一个本地 loopback sidecar例如监听http://127.0.0.1:17787的桌面伴侣进程并通过固定的每扩展代理路径让浏览器访问它。问题在于sidecar 绑定的 loopback 端口对任何本地进程都可达而 WebUI 代理在转发前会剥掉所有入站凭据Cookie、Authorization、CSRF、x-hermes-*头sidecar 自身无法区分一个请求是走代理转发的还是被本地其他进程直连发起的。proxy_auth: token-v1就是用来堵住这个缺口的WebUI 为每个扩展生成一个令牌sidecar 用它来识别合法的代理请求。本文基于 docs/EXTENSIONS.md 给出完整的声明、启动、验证与排查步骤。前置条件你已经在扩展 manifest 中声明了 loopback sidecar且 sidecar 进程本身在本机运行。必须启用 WebUI 认证。WebUI 认证默认是关闭的在认证关闭时token-v1会 fail closed——代理同意consent和代理解析会返回403直到认证被配置。原因是未认证的调用方也能让 core 注入令牌把它当作转发预言机forwarding oracle使用。扩展以完整的 WebUI 会话权限运行只启用你自行编写或完全信任的扩展。第一步在 manifest 中声明 sidecar 与 proxy_auth扩展条目可以声明一个 loopback sidecar用于诊断和可选的代理。在 manifest例如extensions.json中加入sidecar字段并在其中设置proxy_auth: proxy_auth 取值为token-v1{ extensions: [ { id: desktop-companion, name: Desktop Companion, scripts: [companion-adapter.js], stylesheets: [companion-adapter.css], sidecar: { type: loopback, origin: http://127.0.0.1:17787, health_path: /health, proxy_auth: token-v1 } } ] }各字段的文档约束type只支持loopbackorigin必须是127.0.0.1、localhost或[::1]上的http/httpsorigin且不能包含用户名、密码、路径、查询串或 fragmenthealth_path可省略省略时诊断使用/health存在时必须以/开头且不含 scheme、host、查询串、fragment、引号、控制字符、反斜杠、空段、空白或路径穿越。声明非法时 sidecar 会被跳过并给出稳定的告警码如sidecar_origin_rejected、sidecar_type_unsupported、sidecar_health_path_rejected、sidecar_invalid而不是被探测。proxy_auth的取值规则token-v1启用令牌认证文档建议任何会修改状态的 sidecar 都用它省略或显式写legacylegacy 模式无令牌、行为不变只适合只读、无敏感信息的 sidecar其他任何值fail closed该 sidecar 声明直接被拒绝。第二步配置 WebUI 认证并启动token-v1依赖 WebUI 认证存在。按 docs/remote-access.md 与 README.md 的方式通过HERMES_WEBUI_PASSWORD环境变量开启认证下文命令中的your-secret是占位符替换为你自己设置的密码再指定期望的扩展目录与 manifest 启动 start.shHERMES_WEBUI_PASSWORDyour-secret \ HERMES_WEBUI_EXTENSION_DIR~/.hermes/webui-extension-bundle \ HERMES_WEBUI_EXTENSION_MANIFESTextensions.json \ ./start.sh若启动后在Settings → Extensions面板中看到local_unprotected状态提示说明 WebUI 认证还没有配置好此时不应授予代理同意——面板就是靠这个状态提示运营者先启用认证。第三步sidecar 侧的令牌校验约定配置token-v1后WebUI 会为扩展在STATE_DIR/sidecar-auth/id.token生成一个专属密钥文件权限0600id即 manifest 中的扩展 id并在每个经代理转发的请求上注入X-Hermes-Sidecar-Token头。sidecar 侧必须做相应校验按以下顺序解析令牌文件HERMES_EXT_SIDECAR_TOKEN_FILE→$HERMES_WEBUI_STATE_DIR/sidecar-auth/id.token→$HERMES_HOME/webui/sidecar-auth/id.token→ 平台默认路径~/.hermes/webui/…Windows 上为%LOCALAPPDATA%\hermes\webui\…除/health外的每个路由都要校验X-Hermes-Sidecar-Token头令牌缺失或不匹配时返回401令牌文件不存在或不可读时返回503。文档明确要求不要自己手写这套逻辑扩展库仓库hermes-webui/hermes-webui-extensions中的官方脚手架examples/见该仓库的docs/SIDECAR_CONTRACT.md已经实现了上述全部行为直接基于它写 sidecar。第四步授予代理同意并走固定代理路径sidecar 声明本身不改变资产注入行为也不会自动打开代理。要启用代理运营者需要在Settings → Extensions中显式批准对应的持久化接口是POST /api/extensions/sidecar-proxy-consent。同意后WebUI 只会把该扩展的请求通过固定的每扩展 sidecar 路径代理出去/api/extensions/extension-id/sidecar/relative-path其中extension-id替换为 manifest 里的扩展 idrelative-path替换为 sidecar 上的相对路径。转发时 WebUI 会剥掉Cookie、Authorization和 CSRF 头sidecar 响应中的Set-Cookie头在返回浏览器前也会被剥掉。WebUI 不会为扩展创建任意后端路由代理面始终限定在这条固定路径上。验证配置是否生效文档提供了两条验证路径诊断端点已认证的管理员可以调用只读端点GET /api/extensions/status检查返回中的manifest.sidecar_countmanifest 里被接受的启用 loopback sidecar 数与counts.sidecars最终清洗后的 sidecar 列表条数。如果你的 sidecar 声明被拒这里会出现sidecar_origin_rejected、sidecar_invalid等告警码——注意端点不会返回被拒绝的原始 origin、health 路径或环境变量值。Settings → Extensions 的 sidecar monitor 卡片浏览器直接探测声明的health_url。判断标准HTTP 成功响应显示为 healthy非 OK 的 HTTP 响应显示为 unhealthyCORS/网络/超时显示为 unreachable 或 blocked。如果 sidecar 健康响应包含可选的顶层runtime对象面板会渲染其中允许列表内的标量字段如sidecar、native_host、bridge、last_seen_at、webui_origin。已知限制与 fail-closed 行为令牌只防其他 UID 的本地调用方和沙箱化本地调用方不能防任意同 UID 代码——同 UID 代码可以直接读令牌文件、读 WebUI 的签名密钥或绕过 sidecar 直接运行其工具。认证关闭时local_unprotected状态consent 与代理解析对token-v1一律返回403与 sidecar origin 是否 loopback 无关。loopback origin 已在 WebUI 强制的 CSPconnect-src中http://127.0.0.1:*、http://localhost:*、http://ipc.localhost、ws://127.0.0.1:*、ws://localhost:*浏览器直连 sidecar 不需要额外配置只有非 loopback 的可信 origin 才需要启动前用HERMES_WEBUI_CSP_CONNECT_EXTRA追加精确 origin。下一步如果你需要发布这个扩展供他人一键安装按文档说明向扩展库仓库hermes-webui/hermes-webui-extensions提交 PR遵循其docs/extension-entry.md约定与 CI 校验。【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hermes WebUI 扩展的 loopback sidecar 怎么配置 proxy_auth token 认证
Hermes WebUI 扩展的 loopback sidecar 怎么配置 proxy_auth token 认证【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webuiHermes WebUI 的扩展可以为 manifest 声明一个本地 loopback sidecar例如监听http://127.0.0.1:17787的桌面伴侣进程并通过固定的每扩展代理路径让浏览器访问它。问题在于sidecar 绑定的 loopback 端口对任何本地进程都可达而 WebUI 代理在转发前会剥掉所有入站凭据Cookie、Authorization、CSRF、x-hermes-*头sidecar 自身无法区分一个请求是走代理转发的还是被本地其他进程直连发起的。proxy_auth: token-v1就是用来堵住这个缺口的WebUI 为每个扩展生成一个令牌sidecar 用它来识别合法的代理请求。本文基于 docs/EXTENSIONS.md 给出完整的声明、启动、验证与排查步骤。前置条件你已经在扩展 manifest 中声明了 loopback sidecar且 sidecar 进程本身在本机运行。必须启用 WebUI 认证。WebUI 认证默认是关闭的在认证关闭时token-v1会 fail closed——代理同意consent和代理解析会返回403直到认证被配置。原因是未认证的调用方也能让 core 注入令牌把它当作转发预言机forwarding oracle使用。扩展以完整的 WebUI 会话权限运行只启用你自行编写或完全信任的扩展。第一步在 manifest 中声明 sidecar 与 proxy_auth扩展条目可以声明一个 loopback sidecar用于诊断和可选的代理。在 manifest例如extensions.json中加入sidecar字段并在其中设置proxy_auth: proxy_auth 取值为token-v1{ extensions: [ { id: desktop-companion, name: Desktop Companion, scripts: [companion-adapter.js], stylesheets: [companion-adapter.css], sidecar: { type: loopback, origin: http://127.0.0.1:17787, health_path: /health, proxy_auth: token-v1 } } ] }各字段的文档约束type只支持loopbackorigin必须是127.0.0.1、localhost或[::1]上的http/httpsorigin且不能包含用户名、密码、路径、查询串或 fragmenthealth_path可省略省略时诊断使用/health存在时必须以/开头且不含 scheme、host、查询串、fragment、引号、控制字符、反斜杠、空段、空白或路径穿越。声明非法时 sidecar 会被跳过并给出稳定的告警码如sidecar_origin_rejected、sidecar_type_unsupported、sidecar_health_path_rejected、sidecar_invalid而不是被探测。proxy_auth的取值规则token-v1启用令牌认证文档建议任何会修改状态的 sidecar 都用它省略或显式写legacylegacy 模式无令牌、行为不变只适合只读、无敏感信息的 sidecar其他任何值fail closed该 sidecar 声明直接被拒绝。第二步配置 WebUI 认证并启动token-v1依赖 WebUI 认证存在。按 docs/remote-access.md 与 README.md 的方式通过HERMES_WEBUI_PASSWORD环境变量开启认证下文命令中的your-secret是占位符替换为你自己设置的密码再指定期望的扩展目录与 manifest 启动 start.shHERMES_WEBUI_PASSWORDyour-secret \ HERMES_WEBUI_EXTENSION_DIR~/.hermes/webui-extension-bundle \ HERMES_WEBUI_EXTENSION_MANIFESTextensions.json \ ./start.sh若启动后在Settings → Extensions面板中看到local_unprotected状态提示说明 WebUI 认证还没有配置好此时不应授予代理同意——面板就是靠这个状态提示运营者先启用认证。第三步sidecar 侧的令牌校验约定配置token-v1后WebUI 会为扩展在STATE_DIR/sidecar-auth/id.token生成一个专属密钥文件权限0600id即 manifest 中的扩展 id并在每个经代理转发的请求上注入X-Hermes-Sidecar-Token头。sidecar 侧必须做相应校验按以下顺序解析令牌文件HERMES_EXT_SIDECAR_TOKEN_FILE→$HERMES_WEBUI_STATE_DIR/sidecar-auth/id.token→$HERMES_HOME/webui/sidecar-auth/id.token→ 平台默认路径~/.hermes/webui/…Windows 上为%LOCALAPPDATA%\hermes\webui\…除/health外的每个路由都要校验X-Hermes-Sidecar-Token头令牌缺失或不匹配时返回401令牌文件不存在或不可读时返回503。文档明确要求不要自己手写这套逻辑扩展库仓库hermes-webui/hermes-webui-extensions中的官方脚手架examples/见该仓库的docs/SIDECAR_CONTRACT.md已经实现了上述全部行为直接基于它写 sidecar。第四步授予代理同意并走固定代理路径sidecar 声明本身不改变资产注入行为也不会自动打开代理。要启用代理运营者需要在Settings → Extensions中显式批准对应的持久化接口是POST /api/extensions/sidecar-proxy-consent。同意后WebUI 只会把该扩展的请求通过固定的每扩展 sidecar 路径代理出去/api/extensions/extension-id/sidecar/relative-path其中extension-id替换为 manifest 里的扩展 idrelative-path替换为 sidecar 上的相对路径。转发时 WebUI 会剥掉Cookie、Authorization和 CSRF 头sidecar 响应中的Set-Cookie头在返回浏览器前也会被剥掉。WebUI 不会为扩展创建任意后端路由代理面始终限定在这条固定路径上。验证配置是否生效文档提供了两条验证路径诊断端点已认证的管理员可以调用只读端点GET /api/extensions/status检查返回中的manifest.sidecar_countmanifest 里被接受的启用 loopback sidecar 数与counts.sidecars最终清洗后的 sidecar 列表条数。如果你的 sidecar 声明被拒这里会出现sidecar_origin_rejected、sidecar_invalid等告警码——注意端点不会返回被拒绝的原始 origin、health 路径或环境变量值。Settings → Extensions 的 sidecar monitor 卡片浏览器直接探测声明的health_url。判断标准HTTP 成功响应显示为 healthy非 OK 的 HTTP 响应显示为 unhealthyCORS/网络/超时显示为 unreachable 或 blocked。如果 sidecar 健康响应包含可选的顶层runtime对象面板会渲染其中允许列表内的标量字段如sidecar、native_host、bridge、last_seen_at、webui_origin。已知限制与 fail-closed 行为令牌只防其他 UID 的本地调用方和沙箱化本地调用方不能防任意同 UID 代码——同 UID 代码可以直接读令牌文件、读 WebUI 的签名密钥或绕过 sidecar 直接运行其工具。认证关闭时local_unprotected状态consent 与代理解析对token-v1一律返回403与 sidecar origin 是否 loopback 无关。loopback origin 已在 WebUI 强制的 CSPconnect-src中http://127.0.0.1:*、http://localhost:*、http://ipc.localhost、ws://127.0.0.1:*、ws://localhost:*浏览器直连 sidecar 不需要额外配置只有非 loopback 的可信 origin 才需要启动前用HERMES_WEBUI_CSP_CONNECT_EXTRA追加精确 origin。下一步如果你需要发布这个扩展供他人一键安装按文档说明向扩展库仓库hermes-webui/hermes-webui-extensions提交 PR遵循其docs/extension-entry.md约定与 CI 校验。【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考