1. 为什么要在 Docker compose 里把 Hermes webUI 和 vscode 拼在一起如果你正在折腾 Hermes webUI 本地开发环境大概率会遇到一个很别扭的问题webUI 跑在容器里vscodecode-server也跑在容器里但模型请求的 endpoint 却各写各的一个指向127.0.0.1:8000另一个指向别的地址最后调试的时候根本分不清请求到底从哪发出去、有没有走通。这篇就围绕 Docker compose 编排 Hermes webUI 与 vscode 的本地开发环境重点解决模型 endpoint 统一指向的问题给出可复制的 compose 文件、环境变量和统一 Key 配置并附上启动后验证 webUI 与 vscode 内请求是否走通的检查步骤。先说清楚这套东西是什么、能做什么、适合谁。Hermes webUI 是一个带管理面板的 Web 界面它内部会拉起一个 gateway 进程来代理模型请求code-server 是把 vscode 搬到浏览器里的服务配合 Continue 插件就能在网页版 vscode 里做代码补全和对话。把这两个塞进同一个容器、用同一个 compose 管理好处是环境变量只维护一份模型 endpoint 改一处就全生效。适合的人群是想在自己服务器或开发机上搭一套私有 AI 编码环境、又不想每个组件单独配一遍 Key 和地址的开发者。我试过把 endpoint 分散配置结果排查一个 401 花了大半天后来统一到一处才清爽。这套方案的核心矛盾在于Hermes webUI 的 gateway 和 code-server 里的 Continue 插件是两个完全独立的请求发起方。gateway 读的是config.yaml里的custom_providersContinue 读的是它自己的config.json。如果两边都写死各自的 endpoint一旦要换服务商就得改两处还容易漏。所以正确做法是让它们都指向同一个 OpenAI 兼容入口Key 也用同一个这样无论从 webUI 发起的对话还是从 vscode 里发起的补全走的都是同一条链路验证的时候只需要看一个地方。下面我会按「原问题与场景 → TaoToken 前置 → 可复制配置 → 验证请求 → 常见错排查 → CTA」的顺序展开。其中配置部分会给出完整的docker-compose.yaml、config.yaml和 Continue 的config.json你可以直接抄。验证部分会给 curl 命令和日志观察点确保请求真的发出去了。排障部分会对照 401、local proxy failed、reading choices 这几个真实报错来讲。需要提前说明的是本文不涉及任何网络加速工具所有镜像和依赖都走公开可访问的源。如果你在拉取基础镜像时遇到困难可以换用文中提到的镜像站这是常规的容器镜像分发优化和网络访问方式无关。2. TaoToken 前置统一 Key 与 Base URL 的准备在动手写 compose 之前先把模型接入这一层理清楚。这套环境里有两个地方要发模型请求Hermes webUI 的 gateway以及 code-server 里 Continue 插件。如果它们各自去连不同的服务商Key 管理会很乱。所以这里统一用 TaoToken 作为 OpenAI 兼容入口一个 Key、一个 Base URL两边共用。TaoToken 在这里扮演的角色是「统一的模型请求入口」。它对外暴露 OpenAI 兼容的/v1/chat/completions接口也就是说任何支持自定义 OpenAI endpoint 的客户端只要把 Base URL 改成 TaoToken 的地址、把 API Key 换成 TaoToken 的 Key就能直接调通。对 Hermes webUI 来说它读config.yaml里的custom_providers我们把base_url指向 TaoToken 即可对 Continue 来说它读config.json里的apiBase同样指向 TaoToken。这样两边的模型来源就是同一个切换模型或换 Key 时只改一处。你需要准备的东西有三样TaoToken 的 API Key、Base URL、以及你要用的 Model ID。Base URL 是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容根路径使用。API Key 在控制台的 API Keys 页面创建创建后复制出来形如sk-开头的一串。Model ID 取决于你要用哪个模型比如对话类可以用MiniMax-M2.5视觉辅助可以用Nemotron-3-Nano-Omni具体以你账号下可用的模型列表为准。这里有个容易踩的坑很多人会把 Base URL 写成https://taotoken.net/api/v1然后在客户端里又拼一次/v1结果变成/api/v1/v1/chat/completions直接 404。正确做法是 Base URL 只写到/api客户端自己会补/v1/chat/completions。Hermes 的config.yaml里base_url字段要写成https://taotoken.net/api/v1因为它的字段语义是「包含 v1 的完整前缀」而 Continue 的apiBase字段通常写https://taotoken.net/api/v1也可以但要看插件版本有的版本要求写到/api。这个差异我在第 5 节排障里会详细对照。创建 Key 的入口在控制台地址是https://taotoken.net/console进去后找 API Keys 菜单。如果你还没账号先注册再创建。Key 创建后只显示一次记得立刻复制保存。如果你打算长期跑这套环境建议单独建一个 Key 专门给容器用方便后续轮换和审计。另外如果你后续想把这套环境用于更重的编码任务或 Agent 场景可以了解下 Coding Plan它面向长期编码和自动化场景和本文这种本地开发环境是互补的。但本文的重点还是把 compose 跑起来、把 endpoint 指对所以先把基础打通再说。准备好 Key 和 Base URL 后我们就可以进入配置环节了。下面给出的所有配置文件里凡是出现sk-xxxx的地方都替换成你自己的 Key凡是出现https://taotoken.net/api/v1的地方保持原样即可。3. 可复制配置compose、config.yaml 与 Continue settings这一节是全文的核心给出可以直接复制的配置文件。我按「目录结构 → docker-compose.yaml → config.yaml → Continue config.json」的顺序来每一步都说明字段含义你照着改 Key 就能用。先看目录结构。假设你的项目根目录叫hermes-dev里面长这样hermes-dev/ ├── docker-compose.yaml ├── Dockerfile-hermes ├── my-scripts/ │ ├── start.sh │ └── server.js ├── code-server/ │ ├── code-server.tar.gz │ └── continue.continue-1.3.38.vsix ├── hermes_data/ │ ├── config.yaml │ └── hermes-web-ui/ └── app/ └── .venv/my-scripts里放启动脚本code-server里放离线安装包和插件hermes_data是持久化目录config.yaml就放在这里。这个结构和后面 compose 里的 volume 挂载是一一对应的路径别写错。接下来是docker-compose.yaml。这是编排的核心我把它写成单服务多进程的形式因为 Hermes webUI 和 code-server 在同一个容器里由server.js统一调度services: hermes-webui: image: hermes-codeserver:V0.6.7.1 container_name: hermes-webui ports: - 6060:6060 environment: - PORT6060 - HERMES_ALLOW_ROOT_GATEWAY1 - HERMES_WEB_UI_MANAGED_GATEWAY1 - HERMES_DASHBOARD0 - GATEWAY_ALLOW_ALL_USERStrue - GATEWAY_HOST127.0.0.1 - GATEWAY_PORT18790 - HERMES_WEB_PORT8648 - PATH/opt/hermes/.venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin - npm_config_registryhttps://registry.npmmirror.com/ volumes: - ./hermes_data:/home/agent/.hermes - ./hermes_data/config.yaml:/home/agent/.hermes/config.yaml - ./hermes_data/hermes-web-ui:/home/agent/.hermes-web-ui - ./app/.venv:/app/.venv - ./uv.toml:/home/agent/.config/uv/uv.toml restart: unless-stopped stdin_open: true tty: true这里几个环境变量值得说明。PORT6060是管理面板和 webUI 对外的统一端口server.js会根据路径把请求路由到不同后端。HERMES_WEB_UI_MANAGED_GATEWAY1表示由 webUI 自己管理 gateway 进程这样 gateway 会随容器启动而拉起。GATEWAY_HOST和GATEWAY_PORT是 gateway 内部监听的地址保持默认即可。HERMES_WEB_PORT8648是 webUI 前端实际监听的端口由server.js反向代理出去。然后是hermes_data/config.yaml这是模型 endpoint 的关键配置model: default: MiniMax-M2.5 provider: custom:taotoken auxiliary: vision: provider: custom base_url: https://taotoken.net/api/v1 api_key: sk-xxxx model: Nemotron-3-Nano-Omni custom_providers: - name: taotoken base_url: https://taotoken.net/api/v1 api_key: sk-xxxx model: MiniMax-M2.5 models: MiniMax-M2.5: context_length: 196608 - name: taotoken-vision base_url: https://taotoken.net/api/v1 api_key: sk-xxxx model: Nemotron-3-Nano-Omni models: Nemotron-3-Nano-Omni: context_length: 65536注意base_url这里写的是https://taotoken.net/api/v1因为 Hermes 的字段语义要求包含/v1。api_key两处都填同一个 TaoToken Key。provider: custom:taotoken表示默认走custom_providers里 name 为taotoken的那一项。context_length按模型实际能力填这里给的是示例值。再来看 code-server 里 Continue 插件的配置。Continue 的配置文件通常在~/.continue/config.json在容器里对应/home/node/.vscode-server/下的用户目录。内容如下{ models: [ { title: TaoToken MiniMax, provider: openai, model: MiniMax-M2.5, apiBase: https://taotoken.net/api/v1, apiKey: sk-xxxx } ], tabAutocompleteModel: { title: TaoToken Autocomplete, provider: openai, model: MiniMax-M2.5, apiBase: https://taotoken.net/api/v1, apiKey: sk-xxxx } }这里provider填openai因为 TaoToken 是 OpenAI 兼容接口。apiBase写https://taotoken.net/api/v1apiKey填同一个 Key。tabAutocompleteModel是代码补全用的模型可以和对话模型相同也可以换成更轻量的。三件套 Base URL、Key、Model ID 在这里都齐了缺一不可。最后是uv.toml用于 Python 依赖的镜像源加速[pip] index-url https://pypi.tuna.tsinghua.edu.cn/simple这个文件挂载到/home/agent/.config/uv/uv.toml作用是让容器内 pip 安装走国内源加快构建速度。它不是模型配置的一部分但构建镜像时会用到。配置写完后启动命令是docker compose up -d docker compose logs -f hermes-webui日志里看到服务管理已启动和管理面板: http://0.0.0.0:6060/manager就说明起来了。接下来进入验证环节。4. 验证请求确认 webUI 与 vscode 都走通 TaoToken配置写完不代表请求真的发出去了必须验证。这一节给两套验证方法一套针对 Hermes webUI 的 gateway一套针对 code-server 里的 Continue。两套都过了才算 endpoint 真正指对。先验证 Hermes webUI。启动容器后打开浏览器访问http://你的服务器IP:6060/这是 webUI 前端页面。在对话框里发一条消息比如「你好请回复 ok」。如果配置正确你会看到模型正常回复。如果报错页面或日志里会有提示。更可靠的验证方式是直接看 gateway 日志执行docker compose logs -f hermes-webui | grep -i gateway正常请求会看到类似POST /v1/chat/completions 200的记录。如果看到 401说明 Key 不对如果看到连接超时说明 Base URL 不通。再验证 code-server 里的 Continue。访问http://你的服务器IP:6060/manager在管理面板里点「启动 code-server」设置一个密码比如123456。然后访问http://你的服务器IP:6060/会进入 code-server 界面注意这里路径路由由server.js处理管理面板在/managercode-server 在根路径。登录后打开 Continue 插件面板发一条对话请求。如果配置正确会正常返回。更底层的验证是直接在容器内用 curl 打 TaoToken 接口确认网络和 Key 都没问题docker exec -it hermes-webui curl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-xxxx \ -H Content-Type: application/json \ -d {model:MiniMax-M2.5,messages:[{role:user,content:ping}]}如果返回 JSON 里有choices字段说明 Key 和 Base URL 都对。这一步能排除掉容器网络问题把问题范围缩小到客户端配置。还有一个观察点Hermes webUI 的 gateway 会把请求转发到config.yaml里配置的base_url。你可以在容器里看 gateway 的详细日志确认它实际请求的地址。如果日志里显示的地址不是https://taotoken.net/api/v1说明config.yaml没被正确加载检查 volume 挂载路径是否和容器内路径一致。对于 Continue它的请求日志可以在 code-server 的输出面板里看到。如果 Continue 报reading choices错误通常是返回体结构不对多半是 Base URL 多写或少写了/v1。这个在第 5 节详细讲。验证通过后你就有了一套 webUI 和 vscode 共用同一个 TaoToken endpoint 的环境。无论从哪个入口发请求走的都是同一条链路排查问题时只需要看一个地方。5. 本篇常见错排查401、local proxy failed、reading choices这一节对照几个真实报错来讲都是我在搭这套环境时踩过的。每个报错给出原因和解决方式你遇到时可以直接对号入座。第一个是 401 Unauthorized。这个最直接就是 Key 不对或没带上。检查三处config.yaml里的api_key、Continueconfig.json里的apiKey、以及你 curl 测试时用的 Key是否都是同一个有效的 TaoToken Key。常见错误是复制 Key 时带了空格或者 Key 已经过期/被删除。另外注意config.yaml里有两处api_keyauxiliary.vision和custom_providers别只改了一处。解决方式是把 Key 重新复制一遍确保没有多余字符然后重启容器docker compose down docker compose up -d第二个是local proxy failed。这个报错通常出现在 gateway 尝试连接base_url时。原因可能是 Base URL 写错比如写成了http://127.0.0.1:8000/v1这种本地地址但容器里根本没有这个服务。本文场景下应该指向https://taotoken.net/api/v1。另一个原因是容器内 DNS 解析不了外网检查容器是否能访问外网docker exec -it hermes-webui curl -I https://taotoken.net/api/v1如果这条命令超时说明容器网络有问题检查宿主机的网络配置和 Docker 的 DNS 设置。如果返回 401 或 404说明网络通问题在 Key 或路径。第三个是reading choices相关错误完整报错可能是error reading choices: unexpected end of JSON input或cannot read property choices of undefined。这个错误的本质是客户端期望返回 OpenAI 格式的 JSON但实际拿到的不是。最常见原因是 Base URL 路径不对。比如 Continue 的apiBase写成了https://taotoken.net/api它自己拼/v1/chat/completions变成https://taotoken.net/api/v1/chat/completions这是对的但如果apiBase写成https://taotoken.net/api/v1它可能又拼一次/v1变成/api/v1/v1/chat/completions返回 404 的 HTML解析 JSON 就失败。解决方式是确认 Continue 版本的路径拼接规则通常apiBase写到/api即可让插件自己补/v1。而 Hermes 的config.yaml里base_url要写到/api/v1因为它的字段语义不同。这个差异是很多人卡住的地方。第四个是exec format error这个在 arm64 环境常见。如果你在 x86 宿主机上跑 arm64 镜像容器启动时调用 ARM 版 bash 会报格式错误。解决方式是安装 qemu 支持apt update apt install -y qemu-user-static binfmt-support update-binfmts --enable qemu-aarch64 systemctl restart binfmt-support然后重新docker compose down docker compose up -d。这个报错和模型配置无关是架构兼容问题。第五个是 OAuth 相关报错。如果你在 Continue 里看到 OAuth 登录提示说明它没走自定义 endpoint而是尝试用官方登录。检查config.json里provider是否写成了openai以及apiBase和apiKey是否都填了。只要这两个字段齐全Continue 就不会走 OAuth。排查时有个通用技巧先在容器内用 curl 直接打 TaoToken确认 Key 和网络没问题再看客户端配置的 Base URL 路径拼接最后看日志里实际请求的 URL。按这个顺序大部分问题都能定位。6. 把 endpoint 统一到 TaoToken 后的日常维护环境跑起来之后日常维护其实很简单因为 endpoint 和 Key 都收敛到了一处。你要换模型只改config.yaml里的model字段和 Continue 的model字段你要换 Key改config.yaml两处api_key和 Continue 的apiKey然后重启容器。不用再满世界找哪个配置文件里还藏着一个旧地址。如果你后续想把这套环境用于更长期的编码任务可以了解 Coding Plan它面向持续编码和 Agent 场景和本地开发环境配合使用。想快速验证某个模型是否可用可以直接在模型对话页面试。需要管理 Key 或查看用量去控制台。接入文档里有更详细的参数说明遇到字段不确定时可以查。最后留一个实用技巧把config.yaml和 Continue 的config.json都纳入版本管理但 Key 用环境变量注入不要硬编码进仓库。你可以在 compose 里用${TAOTOKEN_API_KEY}引用宿主机环境变量这样配置文件可以安全提交Key 单独管理。这个做法在多环境部署时特别省事。
