为 obs-agent 配置正向代理¶

本文说明如何让自部署 obs-agent 通过 HTTP 正向代理访问 Beak、LLM、AI Hub、远程 MCP 和 Agent release 服务。适用于主机不能直接访问公网，或所有公网请求必须经过企业代理审计的环境。

准备代理信息¶

准备代理地址和旁路列表：

export HTTP_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>'
export HTTPS_PROXY="$HTTP_PROXY"
export NO_PROXY='localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>'

当前版本支持：

无认证 HTTP 正向代理；
使用 URL 用户信息传递的 Basic Auth；
HTTP_PROXY、HTTPS_PROXY、NO_PROXY 及对应小写变量；
SSL_CERT_FILE 和 SSL_CERT_DIR 指定的企业 CA。

代理入口必须使用 http://。访问 HTTPS 或 WSS 目标时，Agent 会通过 HTTP 代理建立 CONNECT 隧道，再校验目标 TLS 证书。

同一变量的大写和小写形式同时存在时，值必须一致。安装器会自动补齐另一种大小写，并在 NO_PROXY 中保留以下本机地址：

localhost,127.0.0.1,::1

妥善保护代理凭据

代理 URL 可能包含用户名和密码。不要把完整代理 URL 写入工单、公开日志、聊天记录或截图。Linux 安装后的 /etc/obs-agent/agent.env 包含敏感配置，应保持仅管理员和 obs-agent 组可读。

在 Linux 主机安装时使用代理¶

先导出代理变量，再执行 Beak 安装页面提供的安装命令。使用 sudo 时，需要显式保留这些变量：

export HTTP_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>'
export HTTPS_PROXY="$HTTP_PROXY"
export NO_PROXY='localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>'

curl -fsSL https://static.guance.com/obs-agent/install.sh \
  -o /tmp/obs-agent-install.sh

sudo --preserve-env=HTTP_PROXY,http_proxy,HTTPS_PROXY,https_proxy,NO_PROXY,no_proxy,SSL_CERT_FILE,SSL_CERT_DIR \
  bash /tmp/obs-agent-install.sh <INSTALL-OPTIONS-FROM-BEAK>

第一条 curl 命令由当前 shell 执行，会读取已经导出的代理变量。安装脚本会把规范化后的代理设置写入：

/etc/obs-agent/agent.env

安装完成后重启并检查服务：

sudo systemctl restart obs-agent
systemctl status obs-agent
journalctl -u obs-agent -n 100

日志中出现以下信息，表示 Agent 已加载代理配置并成功连接 Beak：

obs-agent forward proxy configured
obs-agent websocket connected

启动日志中的代理地址会隐藏用户名和密码。

为现有 Linux 安装补充代理¶

先备份配置：

sudo cp /etc/obs-agent/agent.env /etc/obs-agent/agent.env.bak

编辑 /etc/obs-agent/agent.env，同时设置大小写变量：

HTTP_PROXY="http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>"
http_proxy="http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>"
HTTPS_PROXY="http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>"
https_proxy="http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>"
NO_PROXY="localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>"
no_proxy="localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>"

检查文件权限并重启 Agent：

sudo chown root:obs-agent /etc/obs-agent/agent.env
sudo chmod 0640 /etc/obs-agent/agent.env
sudo systemctl restart obs-agent

如果需要恢复原配置：

sudo cp /etc/obs-agent/agent.env.bak /etc/obs-agent/agent.env
sudo systemctl restart obs-agent

让自动升级继续使用代理¶

Linux 自动升级服务和手动 updater 都会读取 /etc/obs-agent/agent.env。完成上一节配置后，以下请求会继续使用同一代理：

检查 latest-version.json；
下载新版 install.sh；
下载 Agent 安装包和 checksum；
向 Beak 回报升级状态；
Owl CLI 更新所执行的 HTTP 请求。

检查自动更新定时器和最近日志：

systemctl status obs-agent-update-check.timer
systemctl list-timers obs-agent-update-check.timer
journalctl -u obs-agent-update-check.service -n 100

手动执行一次更新检查：

sudo systemctl start obs-agent-update-check.service
journalctl -u obs-agent-update-check.service -n 100

也可以直接运行 updater：

sudo /usr/local/bin/obs-agent-updater

代理不可达或认证失败时，升级会失败并保留当前版本，不会自动改为直连公网。

在 Docker 中使用代理¶

把代理变量写入专用 env 文件：

cat > obs-agent-proxy.env <<'EOF'
HTTP_PROXY=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
http_proxy=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
HTTPS_PROXY=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
https_proxy=http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>
NO_PROXY=localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>
no_proxy=localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>
EOF

chmod 0600 obs-agent-proxy.env

启动容器时同时加载 Agent 和代理配置：

docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --env-file ./obs-agent.env \
  --env-file ./obs-agent-proxy.env \
  -v obs-agent-work:/app \
  -v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
  "${OBS_AGENT_IMAGE}"

容器 entrypoint 会在请求 Beak 配置之前校验代理变量。检查启动日志：

docker logs obs-agent 2>&1 | tail -n 100

Docker 或 Compose 的完整安装步骤见 Agent 容器安装手册。

在 Kubernetes 或 Helm 中使用代理¶

代理 URL 包含凭据时，建议与 Agent API Key 一起保存在 Kubernetes 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>' \
  --from-literal=HTTP_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>' \
  --from-literal=HTTPS_PROXY='http://<PROXY-USER>:<PROXY-PASSWORD>@<PROXY-HOST>:<PROXY-PORT>'

在 Deployment 中从 Secret 注入代理，并单独设置旁路列表：

env:
  - name: HTTP_PROXY
    valueFrom:
      secretKeyRef:
        name: obs-agent-secret
        key: HTTP_PROXY
  - name: HTTPS_PROXY
    valueFrom:
      secretKeyRef:
        name: obs-agent-secret
        key: HTTPS_PROXY
  - name: NO_PROXY
    value: "localhost,127.0.0.1,::1,<INTERNAL-DOMAIN>"

Helm 部署需要确保 secret.keys 同时包含 HTTP_PROXY 和 HTTPS_PROXY。修改 Secret 或 values 后执行升级并等待 Pod 重建：

helm upgrade obs-agent obs-agent/obs-agent \
  --namespace obs-agent \
  --reuse-values \
  --set 'secret.keys={AGENT_API_KEY,AGENT_ID,HTTP_PROXY,HTTPS_PROXY}'

kubectl -n obs-agent rollout status deploy/obs-agent
kubectl -n obs-agent logs deploy/obs-agent --tail=100

完整安装步骤见 Agent 容器安装手册。

配置企业 CA¶

如果企业代理只建立 CONNECT 隧道，不重新签发目标证书，通常不需要额外 CA。

如果代理会检查 TLS 并使用企业 CA 重新签发证书，应先把企业 CA 安装到系统信任库，或设置：

export SSL_CERT_FILE='/etc/ssl/certs/<CORPORATE-CA-FILE>'

Linux 安装器会把显式设置的 SSL_CERT_FILE 或 SSL_CERT_DIR 写入 agent.env。容器环境需要把 CA 文件只读挂载到容器，并让变量指向容器内路径：

docker run -d \
  --name obs-agent \
  --env-file ./obs-agent.env \
  --env-file ./obs-agent-proxy.env \
  -e SSL_CERT_FILE=/etc/ssl/certs/corporate-ca.pem \
  -v /etc/obs-agent/corporate-ca.pem:/etc/ssl/certs/corporate-ca.pem:ro \
  "${OBS_AGENT_IMAGE}"

不要通过关闭 TLS 校验来绕过证书错误。

确认哪些请求会使用代理¶

请求类型	代理行为
Beak HTTP、WS、HTTPS、WSS	使用标准代理变量
LLM、Web Search、Send Email	使用标准代理变量
远程 HTTP MCP	使用标准代理变量
Linux Agent 自动升级	使用 `agent.env` 中的代理变量
Owl、stdio MCP、Skill 子进程	继承代理环境，是否使用取决于对应程序
数据库、自定义 TCP、UDP	不属于 HTTP 正向代理范围

如果必须禁止任意 Skill 或第三方程序直连公网，还需要在主机、VPC、安全组或 Kubernetes NetworkPolicy 中只允许访问代理地址。Agent 传播代理环境，但不提供网络层强制隔离。

排查代理连接问题¶

Agent 报代理配置冲突¶

检查大小写变量是否一致：

sudo grep -E '^(HTTP_PROXY|http_proxy|HTTPS_PROXY|https_proxy|NO_PROXY|no_proxy)=' \
  /etc/obs-agent/agent.env

修改后重启：

sudo systemctl restart obs-agent

返回 407 Proxy Authentication Required¶

确认代理用户名、密码和认证方式。当前版本只支持无认证代理和 Basic Auth，不支持 NTLM、Kerberos 或交互式登录。

如果密码包含 @、:、/、# 等 URL 特殊字符，需要先进行 URL 编码，再写入代理 URL。

HTTPS 请求提示证书错误¶

确认企业 CA 文件存在且 Agent 进程可读：

sudo test -r /etc/ssl/certs/<CORPORATE-CA-FILE>
sudo grep -E '^(SSL_CERT_FILE|SSL_CERT_DIR)=' /etc/obs-agent/agent.env

修正 CA 后重启 Agent 和自动升级检查：

sudo systemctl restart obs-agent
sudo systemctl start obs-agent-update-check.service

内网地址错误地经过代理¶

把内网域名、IP 或网段加入 NO_PROXY 和 no_proxy。不要使用 NO_PROXY=* 作为长期配置；该值会让所有目标直连并绕过代理。

Agent 可以连接但自动升级失败¶

检查更新服务加载的配置和日志：

sudo systemctl cat obs-agent-update-check.service
sudo journalctl -u obs-agent-update-check.service -n 100
sudo grep '^AGENT_UPDATE_BASE_URL=' /etc/obs-agent/agent.env

确认 AGENT_UPDATE_BASE_URL 的域名没有被错误加入 NO_PROXY，并确认代理允许下载 latest-version.json、install.sh、Agent 安装包和 checksum。