1. 为什么要在 1Panel 上部署 Hermes AgentHermes Agent 是一个开源的 AI 智能体框架它能让你在服务器上跑一个带 Web UI 的对话与任务执行入口支持多轮会话、技能扩展、定时任务和日志追踪。适合谁适合手里已经有一台 Linux 服务器、装了 1Panel 面板、想快速拥有一个可对话可扩展的智能体、又不想手动折腾一堆依赖的开发者。它的核心价值在于把「模型接入」和「智能体运行」拆开模型走统一 API 通道智能体本身只管调度和展示。我这次部署的目标很明确在 1Panel 里从零把 Hermes Agent 跑起来Web UI 能打开模型能对话API 能连通。整个过程分两条线一条是 1Panel 侧的应用创建与端口放行另一条是模型侧的 Key 与接口地址配置。两条线都通了Web UI 首页的状态才会从异常变成正常。需要提前说明的是模型服务这里我用的是 TaoToken 的统一 Key/API 通道。它的作用是给你一个兼容常见接口格式的入口你不需要为每个模型单独记一套地址和鉴权方式换模型时改配置里的模型名就行。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。下面所有配置都围绕这个通道展开。环境要求不复杂1Panel 已正常搭建系统是 Ubuntu / Debian / CentOS 主流发行版内存建议 2G 以上服务器能访问外网。这三点满足了后面基本就是填空。2. 前置准备TaoToken Key 与 1Panel 环境确认2.1 拿到统一 Key 和 API 地址第一步是准备模型侧的凭证。打开 TaoToken 控制台创建一个 API Key。这个 Key 就是你后面填进 Hermes Agent 配置里的凭证。创建入口在控制台的 API Keys 页面地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后记下两个东西一个是 Key 本身形如一串字符另一个是 API 基址统一用 https://taotoken.net/api 。注意这个基址后面拼接路径时不要多加斜杠很多接入失败就是斜杠重复导致的。如果你不确定该用哪个模型名可以先去模型对话页面试一下地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。在那边发一条消息确认 Key 有效、模型能返回内容再回到 1Panel 里配置能省掉很多来回排查的时间。2.2 确认 1Panel 版本与 AI 菜单登录 1Panel 面板确认左侧菜单里有「AI」这一项。不同版本的 1Panel 菜单命名略有差异有的叫「AI」有的在「应用商店」里以应用形式出现。如果你的面板没有 AI 菜单优先升级 1Panel 到较新版本或者直接在应用商店搜索 Hermes Agent。同时确认服务器的防火墙状态。1Panel 自带的防火墙和安全组是两层面板里放行了不代表云厂商安全组也放行了。Web UI 需要一个端口比如 8080这个端口要在两处都放行否则你会遇到「容器起来了但浏览器打不开」的经典问题。提示端口选择上避开 80、443、1Panel 自身占用的端口。用 8080、8090 这类高位端口更省心。3. 在 1Panel 中创建 Hermes Agent 应用3.1 创建模型账号进入 1Panel 的 AI 菜单选择「模型」点击「创建模型账号」。这里要填的是模型供应商和 API Key。供应商类型选择兼容 OpenAI 接口格式的选项因为 TaoToken 的 API 是兼容这种格式的。填写时注意三个字段字段填写内容说明供应商类型OpenAI 兼容 / 自定义取决于面板选项命名API 地址https://taotoken.net/api不要带尾部斜杠API Key你的 TaoToken Key从控制台复制填完保存。如果面板有「测试连接」按钮点一下返回成功就说明模型账号这条线通了。如果报 401检查 Key 是否复制完整如果报连接超时检查服务器出网是否正常。3.2 创建 Hermes Agent 智能体回到 AI 菜单选择「智能体」点击「创建智能体」。智能体类型选 Hermes Agent。这一步需要填几个关键参数Web UI 端口填你规划好的端口比如 8080模型选择上一步创建的模型账号名称随便起比如 hermes-prod点击确认后1Panel 会拉取镜像并启动容器。首次拉取镜像可能需要一两分钟取决于网络速度。创建完成后智能体列表里会出现 Hermes Agent 的条目旁边有「对话」「配置」「Web UI」几个按钮。3.3 放行端口这一步最容易被跳过。在 1Panel 的「防火墙」里添加一条规则放行你设置的 Web UI 端口协议 TCP。然后去云厂商控制台的安全组同样放行这个端口。两处都做完浏览器才能访问。如果你用的是 1Panel 的反向代理也可以不直接暴露端口而是通过域名代理到容器端口。这种方式更安全但配置稍多本文先用直连端口的方式跑通之后再考虑加代理。4. 可复制的配置骨架环境变量与 config.toml4.1 环境变量Hermes Agent 的容器启动时会读取一组环境变量。在 1Panel 的智能体配置里找到「环境变量」或「设置」区域填入以下内容。这些变量决定了它连哪个模型、用哪个 Key。# 模型服务基址统一走 TaoToken OPENAI_BASE_URLhttps://taotoken.net/api # 你的 TaoToken Key OPENAI_API_KEYsk-你的Key # 默认使用的模型名按你实际可用的填 DEFAULT_MODELgpt-4o-mini # Web UI 监听端口 WEBUI_PORT8080 # 时区避免日志时间错乱 TZAsia/Shanghai模型名这一项要填你账号下确实可用的。不确定的话去模型对话页面确认一下地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。填一个不存在的模型名Web UI 能打开但一发消息就报错这是很常见的坑。4.2 config.toml 骨架Hermes Agent 的核心配置在 config.toml 里。在 1Panel 的智能体配置页面找到「配置文件」或「设置」里的配置查看入口把下面这段骨架贴进去按需改。[server] host 0.0.0.0 port 8080 [model] provider openai base_url https://taotoken.net/api api_key sk-你的Key model gpt-4o-mini timeout 60 [agent] name hermes max_history 20 enable_skills true [log] level info path /app/logs [timezone] name Asia/Shanghai几个参数说明一下。base_url和api_key必须和前面环境变量一致否则会出现「环境变量生效了但配置文件覆盖了」的情况。timeout设 60 秒比较稳妥模型响应慢的时候不至于直接断。max_history控制上下文轮数设太大 token 消耗快设太小对话容易失忆20 是个折中值。注意config.toml 里的 api_key 如果和环境变量冲突以配置文件为准。改完配置记得重启容器不然不生效。5. 启动后验证Web UI 与 API 连通性5.1 打开 Web UI 看状态页容器启动后浏览器访问http://你的服务器IP:8080。能打开就说明 Web UI 这条线通了。首页是状态页能看到 Agent 的运行状态、当前模型、版本信息。右上角可以切换主题配色和语言中文界面在这里切。状态页如果显示模型未连接或异常先别急着改配置去日志页面看具体报错。日志会明确告诉你是不鉴权失败还是模型名不存在。5.2 发一条消息验证模型点「会话」页面新建对话在输入框发一句「你好」。输入框上方会显示当前对接的模型名。如果模型正常返回说明整条链路通了Web UI → Agent → TaoToken API → 模型 → 返回。如果返回报错按错误码排查401Key 不对或没带上检查 config.toml 和环境变量404模型名不存在去模型对话页面确认可用模型超时服务器出网慢或 timeout 设太短调大 timeout5.3 用 curl 验证 API 连通性除了 Web UI也可以直接在服务器上用 curl 验证 API 通道排除 Web UI 本身的干扰。curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回里有choices字段和内容就说明 API 通道没问题。这一步能帮你快速区分是「模型侧问题」还是「Hermes Agent 配置问题」。如果 curl 通但 Web UI 不通问题一定在 Agent 配置里。5.4 看分析页和日志页Web UI 的「分析」页面能看到 token 消耗量这个数据对控制成本很有用。「日志」页面能看到 Agent 运行的详细日志排查问题时优先看这里。「定时任务」页面可以设置周期性任务比如定时让 Agent 执行某个技能。「技能」页面可以搜索安装需要的技能也可以查看已安装的技能列表。6. 本篇常见错误排查6.1 容器起来了但浏览器打不开九成是端口没放行。检查两处1Panel 防火墙规则、云厂商安全组。另外确认访问的是http://而不是https://直连端口一般没有证书用 https 会握手失败。6.2 Web UI 能开但发消息报错先看日志页面的具体错误。如果是鉴权类错误检查 Key 是否有多余空格复制时容易带上换行。如果是模型类错误去模型对话页面确认模型名。还有一种情况是 base_url 写成了https://taotoken.net/api/尾部多了斜杠拼接后变成双斜杠部分服务会拒绝。6.3 配置改了不生效Hermes Agent 的配置优先级是config.toml 环境变量。如果你在环境变量里改了 Key但 config.toml 里还是旧的那以 config.toml 为准。改完配置必须重启容器1Panel 智能体页面有重启按钮。6.4 对话上下文丢失检查max_history设置。设得太小比如 5多轮对话很快就丢上下文。设得太大token 消耗快。20 到 30 之间比较平衡。另外确认会话页面是否真的在同一个会话里新建对话会清空上下文。6.5 日志时间不对时区没设对。环境变量TZAsia/Shanghai和 config.toml 里的[timezone]都要设。只设一处可能不生效两处都设最稳。7. 后续接入与长期使用建议Web UI 跑通之后如果你要长期用 Hermes Agent 做编码或 Agent 类任务建议关注 Coding Plan 这条线地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。它更适合持续性的编码场景和单次对话的计费方式不同。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有接口格式和参数说明遇到字段不确定的时候查这里最快。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以管理 Key 和查看用量。如果你用的是 Claude Code 这类工具Anthropic 兼容通道的说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配置思路和本文一致只是接口路径不同。最后说一个实操经验Hermes Agent 的配置页面支持直接编辑 JSON 格式的配置点「yaml」按钮可以切换查看。改复杂配置时先在 JSON 视图里改好再保存比在表单里一项项点更不容易漏。改完记得回状态页确认 Agent 状态正常再去会话页发消息验证。整个链路里模型侧用 curl 验证、Agent 侧用日志验证两个动作能覆盖绝大多数问题。