跳转至

Agent 容器安装手册

本文说明如何在 Docker 和 Kubernetes 中安装 obs-agent。如果您要安装到 Kubernetes,优先使用 Helm。

本文示例使用 v0.19.0。使用新版镜像前,管理员须先完成 Beak CDN 配置升级,并确认安装配置 v2 下发目标品牌的 CDN 地址。

容器启动时会使用 BEAK_WS_URL、AGENT_ID 和 AGENT_API_KEY 从 Beak 获取运行配置,然后启动 agent。

容器安装只通过环境变量配置,不读取或生成 config.toml。请按下文设置 Docker、Compose 或 Kubernetes 环境变量。Docker 的 --env-file 参数仍可用于注入环境变量;不要向 Agent 传入 --config 或 --env-file 文件参数。

需要搜索私有代码仓库时,参阅git-rg 使用与仓库凭证配置。

持久化存储是运行前置条件。 /app 中保存运行中 session/task 的 JSONL 历史及相关数据,另外两个目录保存 profile 和 Owl 数据。Docker、Kubernetes YAML 和 Helm 部署都必须为 /app、/var/lib/obs-agent/profile-cache、/app/.owl 提供持久化存储。Owl 卷独立嵌套挂载到 /app/.owl。否则容器、Pod 重建或升级后,运行中的 session/task 可能因历史数据丢失而无法继续。

如果容器所在节点不能直连 Beak、LLM 或其他公网服务,请先阅读为 obs-agent 配置正向代理。

执行权限与容器安全配置

Agent 启动和工具执行不要求 Linux user namespace,也不安装额外的工具 seccomp 过滤器。Docker 使用运行时默认 seccomp;Kubernetes YAML 和 Helm 使用 RuntimeDefault。旧部署如曾显式设置 seccomp=unconfined 或 Unconfined,升级时应重新创建容器或更新工作负载安全配置;Helm 使用 --reuse-values 时显式覆盖 securityContext.seccompProfile.type=RuntimeDefault。

容器默认以非 root 用户运行、移除全部 capabilities 并禁止提权,不需要 --privileged 或 SYS_ADMIN。这些容器设置仍然约束工具,完全访问模式不会授予 root 或宿主机权限。需要 sudo 的系统操作仅能在部署已授予相应 OS 权限且允许提权的环境执行;标准容器配置不提供这项权限。

应用审批控制工具调用是否执行,文件访问和 sudo 能力由操作系统授权控制。通用 Bash、Python、exec、Owl 和本地 stdio MCP 不提供进程沙箱;有足够 OS 权限的程序可以读写配置,配置工具的字段和角色校验不能视为通用 shell 不可绕过的权限隔离。

Skill 依赖与在线更新

v0.15.0、v0.15.1 的容器镜像缺少 Skill 依赖准备器,即使 git-rg 命令已经存在,带依赖声明的技能也可能无法启用。请升级到 v0.15.2 或更新镜像。

修复后的镜像提供 Skill 依赖检查器,并通过 AGENT_SKILL_DEP_INSTALLER 配置为默认准备器。收到技能更新通知或周期同步发现新技能后,Agent 会先检查镜像中的必需命令、Debian 软件包和 Python 包及其版本;检查通过才启用技能,无需重启容器。没有依赖声明的技能直接进入发布流程。

容器运行期间不会通过此检查器执行 apt、pip 或 sudo 安装。缺少依赖或版本不满足时,该技能不可用,不回退旧版技能;其他已就绪技能仍可使用。日志记录缺失项并提示更新镜像。请在镜像中补齐依赖后重新部署,沿用原来的三个持久卷。主机安装仍使用自己的依赖安装器,可以在已有操作系统授权范围内在线准备新技能的依赖。

Agent 先连接,再逐项准备技能;依赖检查期间可以继续聊天。正常同步默认约每十分钟执行一次;准备或状态上报失败后 30 秒重试,成功后恢复正常间隔。配置的同步间隔更短时,重试沿用该间隔。状态上报失败不会撤销本机已准备好的技能,也不会因为补报而重复安装。

仅在旧容器中设置 AGENT_SKILL_DEP_INSTALLER 不能补齐镜像缺失的检查器;需要使用包含该组件的新镜像重新创建容器或更新工作负载。

准备连接信息

从 Beak 控制台或安装页面复制这三个值。Docker 和 Kubernetes YAML 安装会使用全部三个值;从品牌 Helm 仓库安装时,Chart 已包含默认 Beak 地址,只会使用 AGENT_ID 和 AGENT_API_KEY,除非您需要覆盖 Beak 地址:

export BEAK_WS_URL='https://agent-api.guance.com'
export AGENT_ID='replace-with-agent-uuid'
export AGENT_API_KEY='replace-with-agent-api-key'

准备镜像地址:

export OBS_AGENT_IMAGE='pubrepo.guance.com/guance/obs-agent:v0.19.0'

用 Docker 安装

Docker 部署必须创建并重复挂载下面命令中的三个命名卷。升级或重启时应沿用相同的卷名;不要把这些挂载替换为容器临时目录。也可以使用由运维系统管理的 bind mount,但其生命周期必须独立于容器。

创建 env 文件:

cat > obs-agent.env <<EOF
BEAK_WS_URL=${BEAK_WS_URL}
AGENT_ID=${AGENT_ID}
AGENT_API_KEY=${AGENT_API_KEY}
EOF

使用自定义 OpenAI-compatible 模型,同时保留 AIHub 的 Web Search 和 Mail 时, 由 Beak 之外的部署系统追加以下配置:

cat >> obs-agent.env <<EOF
LLM_BASE_URL=https://user-llm.example.com/v1
LLM_API_KEY=replace-with-user-llm-api-key
LLM_MODEL=custom-model
EOF

模型请求使用 LLM_API_KEY;Web Search 和 Mail 使用 AGENT_API_KEY。 容器启动时从 Beak 分别获取模型、搜索和邮件地址;每项优先使用 Connector 的非空部署 配置,否则使用 Beak 对应的 SaaS 默认值。本地非空配置覆盖对应的平台默认值,因此只替换 模型时无需重复配置搜索和邮件地址。需要接入其他搜索或邮件服务时,再分别设置 AGENT_WEB_SEARCH_BASE_URL 或 AGENT_SEND_EMAIL_BASE_URL,不会用模型地址补齐工具地址。

使用新容器镜像前,应先升级 Beak 并配置三项服务默认地址;即使使用同一服务地址,也需要 分别配置。Beak 返回的服务地址缺失或非法时,容器会在启动 Agent 前失败,本地工具地址 不能代替服务端必需的配置。需要禁用工具时,设置 AGENT_WEB_SEARCH_ENABLED=false 或 AGENT_SEND_EMAIL_ENABLED=false,不要通过省略地址来禁用。

容器环境中的非空值优先于 Beak 默认值。远端 install-config 只按固定 allowlist 作为字面 数据解析,不会被 source 或执行。未知字段(包括重复出现的未知字段)会被静默忽略, 不会导出到环境变量;身份字段冲突、已知字段重复、格式错误以及 endpoint 与 credential 来源不完整仍会让容器在启动 Agent 前失败,错误不会打印 secret。

此行为从 v0.14.1 镜像开始提供。旧镜像若因 unsupported Beak install config field 启动失败,请在 v0.14.1 发布后升级到该版本或更新的发布镜像,并重新创建 Docker 容器或更新 Kubernetes 工作负载,保留原有身份配置和数据卷。仅重启旧镜像无法获得未知字段容错能力;更换镜像 不要求旧 Agent 先成功启动。

启动容器:

docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --user 10001:10001 \
  --cap-drop ALL \
  --security-opt no-new-privileges=true \
  --env-file ./obs-agent.env \
  -v obs-agent-work:/app \
  -v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
  -v obs-agent-owl:/app/.owl \
  "${OBS_AGENT_IMAGE}"

检查状态:

docker ps --filter name=obs-agent
docker logs -f obs-agent

日志中看到以下内容表示启动成功:

obs-agent profile request loaded
obs-agent websocket connected

升级镜像:

OBS_AGENT_IMAGE="${OBS_AGENT_IMAGE%:*}:v0.19.0"
docker pull "${OBS_AGENT_IMAGE}"
docker rm -f obs-agent
docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --user 10001:10001 \
  --cap-drop ALL \
  --security-opt no-new-privileges=true \
  --env-file ./obs-agent.env \
  -v obs-agent-work:/app \
  -v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
  -v obs-agent-owl:/app/.owl \
  "${OBS_AGENT_IMAGE}"

清理 Docker 安装:

下面的 docker volume rm 会永久删除 session/task 历史及相关数据。仅在确认不再需要恢复或继续任何任务时执行。

docker rm -f obs-agent
docker volume rm obs-agent-work obs-agent-profile-cache obs-agent-owl

Browser 配置

只需标准 Agent 镜像,镜像已有所需共享库和中文字体。Browser 默认开启:AGENT_BROWSER_ENABLED 未设置或为空时均按 true 处理,容器启动时自动安装或复用 Browser 程序,无需额外配置。

不需要 Browser 时,在 Docker 的 obs-agent.env 中设置:

AGENT_BROWSER_ENABLED=false

然后用相同镜像和原有三个持久卷重新创建容器。仅 docker restart 不会读取修改后的 env 文件。Kubernetes YAML 可增加同名环境变量;Helm 可在 values 中设置:

config:
  AGENT_BROWSER_ENABLED: "false"

首次启动需要访问镜像指定的 Agent 下载地址,以及 Chrome for Testing(AMD64)或 Debian Chromium 包下载地址(ARM64;旧包可从 Debian Snapshot 获取)。入口以非 root 用户校验并安装固定版本的 agent-browser 和浏览器程序;下载可能需要等待。程序缓存在 /var/lib/obs-agent/profile-cache/browser-runtime,重启、重建或回滚时复用与镜像匹配且校验完整的缓存,完整缓存可离线复用;首次安装或缓存损坏时仍需联网。不要删除原有 profile-cache 持久卷。

下载或浏览器健康检查失败时,日志会说明 Browser 不可用,普通 Agent 仍可启动。Browser 的沙箱检查不会自动关闭;如节点限制 Chromium 所需的 user namespace,应由部署管理员检查节点策略,不要为此直接授予容器特权。

显式设置 AGENT_BROWSER_ENABLED=false 时不下载,也不提供 Browser 工具,即使下载缓存还在;旧部署中显式设置的 false 仍然有效,重新启用时改为 true 并重新创建容器或更新工作负载。缓存仅保存程序,不保存网页 Cookie、登录态或会话授权;这项启动开关不改变现有 Browser 会话的审批规则。原生安装方式保持不变。

用 Kubernetes YAML 安装

如果您不使用 Helm,可以直接使用发布到 OSS 的基础 manifest。

基础 manifest 会创建并挂载三个 PVC(20 GiB、5 GiB、5 GiB)。安装前,集群必须配置默认 StorageClass 以动态供应 PV,或预先准备可供这三个 PVC 绑定的 PV。PVC 未绑定时,Pod 会保持 Pending;不要改用 emptyDir 绕过该要求,否则 Pod 重建或升级会丢失运行中 session/task 的 JSONL 历史及相关数据。

下载 manifest:

curl -fsSL https://static.guance.com/obs-agent/obs-agent.yml -o obs-agent.yml

下载指定版本的 manifest:

curl -fsSL https://static.guance.com/obs-agent/obs-agent-v0.19.0.yml -o obs-agent.yml

创建 namespace:

kubectl create namespace obs-agent

manifest 使用环境变量保存 Beak 地址和 agent 凭据。确认本机已安装 envsubst,安装时只展开这三个变量,避免 URL 或凭据中的 /、& 等字符被替换命令解释:

envsubst '${BEAK_WS_URL} ${AGENT_ID} ${AGENT_API_KEY}' \
  < obs-agent.yml \
  | kubectl -n obs-agent apply -f -

obs-agent.yml 已经包含一个 Kubernetes Secret。上述 envsubst 命令会把当前环境中的凭据写入下面两个字段:

apiVersion: v1
kind: Secret
metadata:
  name: obs-agent-secret
type: Opaque
stringData:
  AGENT_API_KEY: "${AGENT_API_KEY}"
  AGENT_ID: "${AGENT_ID}"

检查状态:

kubectl -n obs-agent get pods
kubectl -n obs-agent get deploy
kubectl -n obs-agent logs -f deploy/obs-agent

升级时重新下载新版 obs-agent.yml,保留当前 BEAK_WS_URL、AGENT_ID、AGENT_API_KEY,再执行:

envsubst '${BEAK_WS_URL} ${AGENT_ID} ${AGENT_API_KEY}' \
  < obs-agent.yml \
  | kubectl -n obs-agent apply -f -

升级时必须保留并复用原有 PVC。删除 PVC 或 namespace 可能连同底层 PV 数据一起删除,具体取决于 StorageClass 的回收策略。

清理 YAML 安装:

下面的命令会删除 manifest 创建的 PVC,底层 PV 数据是否保留取决于 StorageClass 的回收策略。仅在确认不再需要恢复或继续任何任务时执行。

kubectl -n obs-agent delete -f obs-agent.yml
kubectl delete namespace obs-agent

用 Kubernetes Helm 安装

Helm chart 默认创建并挂载三个 PVC(20 GiB、5 GiB、5 GiB)。安装前,集群必须配置默认 StorageClass 以动态供应 PV,或分别在 persistence.work.existingClaim、persistence.profileCache.existingClaim、persistence.owl.existingClaim 中指定三个已绑定的 PVC。不要禁用这些持久化项,否则 Pod 重建或升级会丢失运行中 session/task 的 JSONL 历史及相关数据。

设置 Helm 仓库地址,然后添加仓库:

Helm 仓库地址与容器镜像仓库地址不同。不要把后续 image.repository 使用的镜像路径作为 helm repo add 的仓库地址。

export OBS_AGENT_HELM_REPO_URL='https://pubrepo.guance.com/chartrepo/obs-agent'
helm repo add obs-agent "${OBS_AGENT_HELM_REPO_URL}"
helm repo update obs-agent
helm search repo obs-agent

创建 namespace:

kubectl create namespace obs-agent

创建 agent secret:

kubectl -n obs-agent create secret generic obs-agent-secret \
  --from-literal=AGENT_ID="${AGENT_ID}" \
  --from-literal=AGENT_API_KEY="${AGENT_API_KEY}"

品牌 Helm Chart 已包含当前品牌的默认 Beak 地址,正常安装时不需要手动设置 config.BEAK_WS_URL。

Chart 默认设置 automountServiceAccountToken: false。当前 Agent 功能无需 Kubernetes API 凭据;ConfigMap、Secret 和 PVC 挂载不依赖该 token。需要 Agent 访问 Kubernetes API 时,在安装或升级命令中追加 --set automountServiceAccountToken=true,并为所用 ServiceAccount 配置所需 RBAC 权限。

安装:

helm upgrade --install obs-agent obs-agent/obs-agent \
  --namespace obs-agent \
  --set image.repository=pubrepo.guance.com/guance/obs-agent \
  --set image.tag=v0.19.0 \
  --set secret.existingSecret=obs-agent-secret

只有使用自定义 Beak 地址、安装未包含品牌默认地址的旧版 Chart,或直接从仓库源码 docs/examples/helm/obs-agent 安装时,才需要在安装命令中追加 --set-string config.BEAK_WS_URL="${BEAK_WS_URL}"。

检查状态:

kubectl -n obs-agent get pods
kubectl -n obs-agent get deploy -l app.kubernetes.io/instance=obs-agent
kubectl -n obs-agent logs -f deploy/obs-agent

如果 Deployment 名不是 obs-agent,用上面的 kubectl get deploy 输出中的实际名称查看日志。

升级:

helm upgrade obs-agent obs-agent/obs-agent \
  --namespace obs-agent \
  --reuse-values \
  --set image.tag=v0.19.0 \
  --set securityContext.seccompProfile.type=RuntimeDefault

如果旧 release 的 values 中已经保存了错误或未解析的 Beak 地址,--reuse-values 会继续复用该值。首次升级到修复后的 Chart 时,请额外传入 --set-string config.BEAK_WS_URL="${BEAK_WS_URL}" 修正它;后续升级可以继续复用。

清理 Helm 安装:

helm uninstall 会删除 chart 创建的 PVC,kubectl delete namespace 也会删除该 namespace 中的 PVC。底层 PV 数据是否保留取决于 StorageClass 的回收策略;仅在确认不再需要恢复或继续任何任务时执行。

helm uninstall obs-agent -n obs-agent
kubectl delete namespace obs-agent

查看可用环境变量

所有安装方式都需要 AGENT_ID 和 AGENT_API_KEY。Docker 和 Kubernetes YAML 安装还需要 BEAK_WS_URL;品牌 Helm Chart 已提供默认值,仅在自定义地址或兼容旧 Chart 时需要覆盖。下面的其他变量用于排查问题或覆盖默认配置;没有明确需求时不用设置。

环境变量 是否需要手动配置 说明
BEAK_WS_URL Docker/YAML:是;品牌 Helm:否 Beak config API 地址,例如 https://agent-api.guance.com。品牌 Helm Chart 已内置默认地址,可通过 config.BEAK_WS_URL 覆盖。
AGENT_ID 是 Agent 实例 ID。每个运行实例必须唯一。
AGENT_API_KEY 是 Agent 访问 Beak config API 和 WebSocket 的凭据。
BEAK_ENDPOINT 否 容器入口读取 Beak config API 时的备用地址;未设置时使用 BEAK_WS_URL。
HTTP_PROXY / http_proxy 否 HTTP 和 WS 请求使用的 HTTP 正向代理。大小写变量同时存在时值必须一致。
HTTPS_PROXY / https_proxy 否 HTTPS 和 WSS 请求使用的代理;代理入口仍使用 http://。
NO_PROXY / no_proxy 否 不经过代理的主机、域名、IP 或网段。建议至少包含 localhost,127.0.0.1,::1。
SSL_CERT_FILE / SSL_CERT_DIR 否 企业代理重新签发 TLS 证书时使用的 CA 文件或目录。
AGENT_NAME 否 Agent 显示名称。未手动配置时由 Beak config API 下发。
AGENT_WORKDIR 否 Agent 工作目录。容器默认 /app。
AGENT_PROFILE_CACHE_DIR 否 Profile 缓存目录。容器默认 /var/lib/obs-agent/profile-cache。
AGENT_BROWSER_ENABLED 否 默认 true(未设置或为空均开启);启动前按需安装或复用 Browser 程序,健康检查通过后提供工具。显式 false 时不下载、不启用;修改后重新创建容器或更新工作负载。
AGENT_LOCAL_TIMEZONE 否 Agent 本地时区。容器默认 Asia/Shanghai。
AGENT_HTTP_ALLOWED_DOMAINS 否 限制 HTTP 工具可访问的域名,逗号分隔。
AGENT_UPDATE_ENABLED 否 容器化部署固定关闭自更新。升级通过镜像或 manifest 完成。
AGENT_UPDATE_HELPER_PATH 否 自更新 helper 路径;容器化部署通常不使用。
AGENT_UPDATE_BASE_URL 否 自更新 release 地址;容器化部署通常不使用。
AGENT_UPDATE_CHECK_INTERVAL_SECONDS 否 自更新检查间隔;默认 300。
AGENT_UPDATE_STATE_PATH 否 自更新状态文件路径。
AGENT_UPDATE_HISTORY_PATH 否 自更新历史文件路径。
AGENT_INSTALL_MODE 否 安装模式标记,通常由安装脚本写入。
AGENT_SELF_HOST_STATE_PATH 否 宿主机安装状态文件路径;容器化部署通常不使用。
AGENT_SKILL_DEP_INSTALLER 否 Skill 依赖安装器路径;通常由安装脚本或镜像提供。
AGENT_SKILL_DEP_STATE_PATH 否 Skill 依赖状态文件路径。
AGENT_SKILL_DEP_HISTORY_PATH 否 Skill 依赖历史文件路径。
LLM_BASE_URL 否 OpenAI-compatible 模型地址,可由 Beak 之外的部署系统注入。
LLM_API_KEY 否 模型 API key,仅发送到 LLM_BASE_URL。
LLM_MODEL 否 模型名称;自定义模型应显式配置。
LLM_TEMPERATURE 否 LLM temperature,默认 0.2。
LLM_MAX_TOKENS 否 LLM 最大输出 token,默认 0 表示使用模型默认值。
AGENT_SEND_EMAIL_ENABLED 否 是否启用 Send Email 工具,默认 true。
AGENT_SEND_EMAIL_BASE_URL 否 Send Email API 地址;本地未设置时使用 Beak 下发的独立邮件地址。
LOG_LEVEL 否 日志级别。容器默认 info。
LOG_FORMAT 否 日志格式。容器默认 text。
LOG_PATH 否 日志输出位置。容器默认 stdout。
AGENT_DIAGNOSTIC_LOG_PATH 否 Bug report 使用的受限轮转日志副本。容器默认 /var/lib/obs-agent/profile-cache/diagnostics/agent.log,复用 profile-cache 持久卷;不可写时回退到 4 MiB 内存尾部。
LOG_RELATIVE_PATH 否 日志路径是否按工作目录解析,默认 true。
LOG_MAX_SIZE_MB 否 单个日志文件最大大小,默认 32。
LOG_MAX_BACKUPS 否 日志备份文件数量,默认 5。
OTEL_EXPORTER_OTLP_PROTOCOL 否 OTEL 导出协议。容器默认 http/protobuf。
OTEL_EXPORTER_OTLP_ENDPOINT 否 OTEL 采集端地址。需要链路上报时由 Beak config API 下发或手动覆盖。
OTEL_EXPORTER_OTLP_HEADERS 否 OTEL 请求头。需要链路上报时由 Beak config API 下发或手动覆盖。
OTEL_LOGS_ENABLED 否 历史变量,当前 Agent 忽略。metrics、logs、traces 的启停统一由 Beak runtime-config API 控制。
AGENT_MAX_RUN_DURATION 否 单轮软时间预算,默认 2h;当前模型请求或工具结束后停止新工作并尝试一次总结。审批等待计入预算;0s 关闭。
AGENT_MAX_LLM_MESSAGES 否 可选的单次 provider 请求消息保护上限,默认 0(关闭)。
AGENT_MAX_LLM_MESSAGE_CHARS 否 单条 LLM 消息最大字符数,默认 512000。
AGENT_MAX_SYSTEM_PROMPT_CHARS 否 System prompt 最大字符数,默认 512000。
AGENT_QUERY_SESSION_CHAT_HISTORY_LIMIT 否 查询会话历史条数,默认 20。
AGENT_CONTEXT_BUDGET_TOKENS 否 上下文 token 预算,默认 262144。
AGENT_CONTEXT_BUDGET_CHARS 否 上下文字符预算,默认 262144。
AGENT_REASONING_DISPLAY_MODE 否 推理内容显示模式,支持 hidden 或 raw,默认 raw,展示模型返回的 thinking;设置 hidden 可隐藏。升级保留显式配置,模型没有返回 thinking 时正常展示正文。
AGENT_PROFILE_SYNC_DISABLE 否 是否关闭启动、周期和推送触发的远端 Profile 同步;设为 true 时使用本地缓存,默认 false。
AGENT_PROFILE_SYNC_INTERVAL 否 Profile 完整同步的周期兜底间隔,默认 10m;失败后 30 秒重试,配置周期更短时沿用该周期;保存该 Agent 的 Profile、Skill 或 MCP 绑定时也会立即触发定向同步。
AGENT_DEFAULT_APPROVAL_TTL_SECONDS 否 已废弃;为兼容旧配置仍接受,但会忽略并在启动时告警一次。
AGENT_WEB_SEARCH_ENABLED 否 是否启用 Web Search 工具,默认 true。
AGENT_PRE_SEARCH_ENABLED 否 是否要求 Agent 在执行复杂任务前先核对可用工具、证据和执行路径,默认 true。设为 false 时,主 Agent 与子 Agent 同时关闭此要求。
AGENT_WEB_SEARCH_BASE_URL 否 Web Search API 地址;本地未设置时使用 Beak 下发的独立搜索地址。
AGENT_WEB_SEARCH_DEFAULT_LIMIT 否 Web Search 默认结果数,默认 5。
AGENT_WEB_SEARCH_MAX_LIMIT 否 Web Search 最大结果数,默认 10。
AGENT_WEB_SEARCH_MAX_CONTENT_CHARS 否 单条搜索内容最大字符数,默认 3000。
AGENT_WEB_SEARCH_MAX_CONTEXT_CHARS 否 搜索上下文最大字符数,默认 12000。
AGENT_WEB_SEARCH_DEFAULT_MODE 否 Web Search 默认模式,默认 auto。
AGENT_WEB_SEARCH_TIMEOUT 否 Web Search 超时时间,默认 30s。
AGENT_MESSAGE_ENCRYPTION_ENABLED 否 是否启用消息加密,默认 true。
AGENT_MESSAGE_HPKE_KEY_ID 否 HPKE key ID。
AGENT_MESSAGE_HPKE_PRIVATE_KEY 否 HPKE 私钥内容。
AGENT_MESSAGE_HPKE_KEY_PATH 否 HPKE 私钥文件路径。
AGENT_MESSAGE_HPKE_ROTATION_INTERVAL 否 HPKE key 轮换间隔,默认 0 表示不自动轮换。
OWL_BASE_URL 否 Owl 依赖下载地址。通常由镜像内置或 Beak config API 下发。
OWL_INSTALL_URL 否 Owl 安装脚本地址。通常由 Beak config API 下发。
OWL_REGISTRY_ENDPOINT 否 Owl registry 地址。通常由 Beak config API 下发;Agent 正常启动时写入 $OWL_DIR/config.yaml。
OWL_TOKEN 否 Owl registry 访问 token。通常由 Beak config API 下发;Agent 启动时写入 Owl 配置的 auth.api-key,不会加入工具 ENV 白名单。
OWL_DIR 否 Owl 工作目录。容器默认 ${AGENT_WORKDIR}/.owl,即 /app/.owl;obs-agent 将其作为 read_file、list_dir 的共享只读根。旧部署显式配置的其他路径仍受支持。
AGENT_IMAGE_PRINT_VERSIONS 否 容器启动时是否打印 obs-agent 和 owl 版本,默认 false。

注意事项

  • 容器正常启动时,Agent 将有效的 OWL_REGISTRY_ENDPOINT 和 OWL_TOKEN 一次性写入 $OWL_DIR/config.yaml,完成后才启动工具服务。无需新增命令行参数,-h、--version 等信息查询不会写入配置。默认路径是 /app/.owl/config.yaml,文件权限为 0600,采用原子写入。请挂载可写的 Owl 目录;单独挂载只读配置文件不适用于此模式。
  • 根 config.yaml 由容器启动流程完整管理,包含 registry.endpoint 与 auth.api-key;重启会替换整个文件,自定义字段不会保留,cache/data 保留。升级前请备份原配置。两个启动输入均为空时不写文件;只提供一个输入会阻止启动。非空本地覆盖和自定义 registry 必须配套本地 token 的规则保持不变;宿主机仍保留原有配置值优先的初始化规则。
  • 若持久卷的 state.yaml 选择了命名 profile,或设置了非 default 的 OWL_PROFILE,Agent 会报错且不修改配置。请先在维护环境用相同 OWL_DIR 执行 owl switch default 并清除 OWL_PROFILE,再启动容器;Agent 不会自动切换或改写命名 profile。state.yaml 无效、写入或替换失败时也会阻止启动,原配置保持不变。
  • Docker 和 Helm 不能复用同一个 AGENT_ID 同时在线。每个运行实例需要独立 agent。
  • 仅替换镜像升级的旧部署如果仍把 Owl 卷挂载到 /var/lib/obs-agent/work/.owl,entrypoint 会在未显式设置 OWL_DIR 时检测并继续使用该目录;更新到新 Compose、Kubernetes 或 Helm 模板后则使用 /app/.owl。迁移期间不要同时挂载两个 Owl 卷。
  • obs-agent.yml 会创建独立 ServiceAccount,并关闭 Kubernetes service account token 自动挂载。
  • 容器内不会运行宿主机安装脚本,也不依赖 systemd。
  • 容器化部署不启用本地自更新;升级通过替换镜像 tag 或 digest 完成。
  • 生产环境建议使用镜像 digest 固定版本。

文档评价

文档内容是否对您有帮助?