跳转至

obs-agent 容器安装手册

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

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

准备连接信息

从 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.4.0'

用 Docker 安装

创建 env 文件：

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

启动容器：

docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --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:/var/lib/obs-agent/work/.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.4.0"
docker pull "${OBS_AGENT_IMAGE}"
docker rm -f obs-agent
docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --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:/var/lib/obs-agent/work/.owl \
  "${OBS_AGENT_IMAGE}"

清理 Docker 安装：

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

用 Kubernetes YAML 安装

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

下载 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.4.0.yml -o obs-agent.yml

创建 namespace：

kubectl create namespace obs-agent

把 manifest 中的占位值替换成当前 agent 的信息：

sed -i.bak \
  -e "s#replace-with-beak-ws-url#${BEAK_WS_URL}#g" \
  -e "s#replace-with-agent-uuid#${AGENT_ID}#g" \
  -e "s#replace-with-agent-api-key#${AGENT_API_KEY}#g" \
  obs-agent.yml

obs-agent.yml 已经包含一个 Kubernetes Secret。也可以直接编辑下面这一段：

apiVersion: v1
kind: Secret
metadata:
  name: obs-agent-secret
type: Opaque
stringData:
  AGENT_API_KEY: "replace-with-agent-api-key"
  AGENT_ID: "replace-with-agent-uuid"

安装：

kubectl -n obs-agent apply -f obs-agent.yml

检查状态：

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，再执行：

kubectl -n obs-agent apply -f obs-agent.yml

清理 YAML 安装：

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

用 Kubernetes Helm 安装

设置 Helm 仓库地址，然后添加仓库：

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 upgrade --install obs-agent obs-agent/obs-agent \
  --namespace obs-agent \

  --set image.repository=pubrepo.guance.com/guance/obs-agent \

  --set image.tag=v0.4.0 \
  --set-string config.BEAK_WS_URL="${BEAK_WS_URL}" \
  --set secret.existingSecret=obs-agent-secret

检查状态：

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.4.0

清理 Helm 安装：

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

查看可用环境变量

安装步骤只需要 BEAK_WS_URL、AGENT_ID 和 AGENT_API_KEY。下面的变量用于排查问题或覆盖默认配置；没有明确需求时不用设置。

环境变量 是否需要手动配置 说明
BEAK_WS_URL 是 Beak config API 地址，例如 https://agent-api.guance.com。
BEAK_ENDPOINT 否 容器入口读取 Beak config API 时的备用地址；未设置时使用 BEAK_WS_URL。
AGENT_ID 是 Agent 实例 ID。每个运行实例必须唯一。
AGENT_API_KEY 是 Agent 访问 Beak config API 和 WebSocket 的凭据。
AGENT_NAME 否 Agent 显示名称。未手动配置时由 Beak config API 下发。
AGENT_WORKDIR 否 Agent 工作目录。容器默认 /app。
AGENT_PROFILE_CACHE_DIR 否 Profile 缓存目录。容器默认 /var/lib/obs-agent/profile-cache。
AGENT_PERMISSION_MODE 否 工具权限模式。容器默认 standard。
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_SELF_HOST_HISTORY_PATH 否 宿主机安装历史文件路径；容器化部署通常不使用。
AGENT_SKILL_DEP_INSTALLER 否 Skill 依赖安装器路径；通常由安装脚本或镜像提供。
AGENT_SKILL_DEP_STATE_PATH 否 Skill 依赖状态文件路径。
AGENT_SKILL_DEP_HISTORY_PATH 否 Skill 依赖历史文件路径。
LLM_BASE_URL 否 由 Beak config API 下发。
LLM_API_KEY 否 由 Beak config API 下发，默认使用 AGENT_API_KEY。
LLM_MODEL 否 不需要手动配置。未配置时 agent 使用默认模型。
LLM_TEMPERATURE 否 LLM temperature，默认 0.2。
LLM_MAX_TOKENS 否 LLM 最大输出 token，默认 0 表示使用模型默认值。
AI_HUB_BASE_URL 否 AI Hub 地址；未配置时使用 LLM_BASE_URL。
LOG_LEVEL 否 日志级别。容器默认 info。
LOG_FORMAT 否 日志格式。容器默认 text。
LOG_PATH 否 日志输出位置。容器默认 stdout。
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 否 是否导出 OTEL logs；默认随 OTEL_EXPORTER_OTLP_ENDPOINT 是否配置而启用。
AGENT_MAX_TOOL_CALL_ITERATIONS 否 单次任务最大工具调用轮数，默认 128。
AGENT_MAX_LLM_MESSAGES 否 LLM 上下文最大消息数，默认 256。
AGENT_MAX_LLM_MESSAGE_CHARS 否 单条 LLM 消息最大字符数，默认 512000。
AGENT_MAX_SYSTEM_PROMPT_CHARS 否 System prompt 最大字符数，默认 512000。
AGENT_RECENT_CHAT_HISTORY_MESSAGES 否 最近聊天历史消息数，默认 20。
AGENT_QUERY_SESSION_CHAT_HISTORY_LIMIT 否 查询会话历史条数，默认 20。
AGENT_CONTEXT_BUDGET_TOKENS 否 上下文 token 预算，默认 262144。
AGENT_CONTEXT_BUDGET_CHARS 否 上下文字符预算，默认 262144。
AGENT_CONTEXT_COMPACT_THRESHOLD 否 上下文压缩阈值，默认 0.6。
AGENT_TOOL_LOOP_RECENT_INTERACTIONS 否 工具循环检测窗口，默认 4。
AGENT_TOOL_SAME_ERROR_LIMIT 否 相同工具错误上限，默认 20。
AGENT_TOOL_TOTAL_FAILED_LIMIT 否 工具总失败上限，默认 50。
AGENT_TOOL_SAME_ACTION_LIMIT 否 相同工具动作上限，默认 3。
AGENT_TOOL_MALFORMED_ARGUMENTS_LIMIT 否 工具参数格式错误上限，默认 2。
AGENT_REASONING_DISPLAY_MODE 否 推理内容显示模式，支持 hidden 或 raw，默认 hidden。
AGENT_PROFILE_SYNC_DISABLE 否 是否关闭 profile 同步，默认 false。
AGENT_PROFILE_SYNC_INTERVAL 否 Profile 同步间隔，默认 5m。
AGENT_DEFAULT_APPROVAL_TTL_SECONDS 否 默认审批有效期，默认 300 秒。
AGENT_WEB_SEARCH_ENABLED 否 是否启用 Web Search 工具，默认 true。
AGENT_WEB_SEARCH_BASE_URL 否 Web Search 服务地址；启用 Web Search 时需要。
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 下发。
OWL_TOKEN 否 Owl registry 访问 token。通常由 Beak config API 下发。
OWL_DIR 否 Owl 工作目录。容器默认 /var/lib/obs-agent/work/.owl。
AGENT_IMAGE_PRINT_VERSIONS 否 容器启动时是否打印 obs-agent 和 owl 版本，默认 false。

注意事项

  • Docker 和 Helm 不能复用同一个 AGENT_ID 同时在线。每个运行实例需要独立 agent。
  • obs-agent.yml 会创建独立 ServiceAccount，并关闭 Kubernetes service account token 自动挂载。
  • 容器内不会运行宿主机安装脚本，也不依赖 systemd。
  • 容器化部署不启用本地自更新；升级通过替换镜像 tag 或 digest 完成。
  • 生产环境建议使用镜像 digest 固定版本。

文档评价

文档内容是否对您有帮助？ ×