에이전트 컨테이너 설치 매뉴얼¶
이 문서는 Docker 및 Kubernetes로 obs-agent를 설치하는 방법을 설명합니다. Kubernetes에 설치하는 경우 Helm 사용을 권장합니다.
이 예제는 v0.19.0을 사용합니다. 새 이미지를 사용하기 전에 관리자는 Beak CDN 설정 업그레이드를 완료하고 설치 설정 v2가 해당 브랜드의 CDN을 제공하는지 확인해야 합니다.
컨테이너가 시작되면 BEAK_WS_URL, AGENT_ID, AGENT_API_KEY를 사용하여 Beak에서 런타임 구성을 로드한 다음 에이전트를 시작합니다.
컨테이너 설치는 환경 변수만을 사용합니다. config.toml를 읽거나 생성하지 않습니다. 아래의 Docker, Compose 또는 Kubernetes 환경 설정을 사용하세요. Docker는 여전히 환경 변수를 삽입하기 위해 --env-file를 사용할 수 있습니다. --config나 --env-file 파일 인자를 Agent에 전달하지 마세요.
개인 코드 저장소를 검색하려면 git-rg 사용 및 저장소 자격 증명 설정를 참조하십시오.
영구 스토리지는 런타임 필수 요건입니다.
/app은 활성 세션/작업 JSONL 기록 및 관련 데이터를 저장하며, 나머지 두 디렉터리는 프로필 및 Owl 데이터를 저장합니다. Docker, Kubernetes YAML, Helm 배포는/app,/var/lib/obs-agent/profile-cache,/app/.owl에 대해 영구 스토리지를 제공해야 합니다. Owl 볼륨은/app/.owl에 별도로 마운트하십시오. 그렇지 않으면 컨테이너 또는 Pod 재빌드나 업그레이드 후 활성 세션/작업을 이어갈 수 없게 될 수 있습니다.
컨테이너 노드가 Beak, LLM 또는 기타 공용 서비스에 직접 접근할 수 없는 경우 먼저 obs-agent 정방향 프록시 구성을 참고하십시오.
실행 권한과 컨테이너 보안¶
Agent 시작과 도구 실행에는 더 이상 Linux 사용자 네임스페이스가 필요하지 않으며 추가 도구 seccomp 필터도 설치하지 않습니다. Docker는 런타임 기본 seccomp 프로파일을 사용하고 Kubernetes YAML과 Helm은 RuntimeDefault를 사용합니다. 이전 배포에서 seccomp=unconfined 또는 Unconfined를 명시적으로 설정했다면 컨테이너를 다시 생성하거나 워크로드 보안 설정을 업데이트하세요. Helm --reuse-values를 사용할 때는 securityContext.seccompProfile.type=RuntimeDefault를 명시적으로 재정의하세요.
컨테이너는 root가 아닌 사용자로 실행되며 모든 capability를 제거하고 권한 상승을 방지합니다. --privileged와 SYS_ADMIN은 필요하지 않습니다. 이 설정은 도구에도 적용됩니다. Full Access가 root 또는 호스트 권한을 부여하지는 않습니다. sudo가 필요한 작업은 배포 환경에서 필요한 OS 권한과 권한 상승을 이미 허용한 경우에만 실행할 수 있습니다. 표준 컨테이너 설정은 이 권한을 부여하지 않습니다.
애플리케이션 승인은 도구 호출이 실행되는지 여부를 결정합니다. 운영 체제 권한 부여는 파일 액세스와 sudo를 제어합니다. 범용 Bash, Python, exec, Owl, 그리고 로컬 stdio MCP는 프로세스 샌드박스를 제공하지 않습니다. 충분한 OS 권한을 가진 프로그램은 설정 파일을 읽거나 쓸 수 있으므로, 설정 도구 필드와 역할 확인은 범용 셸이 우회할 수 없는 격리 구역이 아닙니다.
Skill 의 종속성 및 온라인 업데이트¶
v0.15.0 및 v0.15.1 컨테이너 이미지는 Skill 의존성 준비자를 포함하고 있지 않습니다. 의존성 선언이 포함된 Skill도 git-rg 명령어가 설치되어 있더라도 사용할 수 없습니다. v0.15.2 또는 더 새로운 이미지로 업그레이드해야 합니다.
이 이미지에는 Skill 의 종속성 확인 기능이 포함되어 있으며, AGENT_SKILL_DEP_INSTALLER를 통해 이 기능을 기본 설정으로 지정합니다. Agent가 Skill 업데이트 알림을 받거나 주기적인 동기화 과정에서 새로운 Skill를 발견할 경우, 해당 이미지 내의 필요한 명령어, 데비안 패키지, 파이썬 패키지 및 그 버전을 확인한 후에야 Skill를 사용할 수 있게 됩니다. 종속성이 충족된 경우 컨테이너를 재시작할 필요가 없습니다. 종속성 선언이 없는 Skills는 바로 출시됩니다.
이 체크는 실행 중인 컨테이너 내에서 apt, pip, sudo를 사용한 설치 작업을 실행하지 않습니다. 종속성이 누락되거나 버전이 적합하지 않다면, 해당 Skill는 사용할 수 없으며, 이전 버전으로 전환되지 않습니다. 다른 준비된 Skills는 여전히 사용할 수 있습니다. 로그에는 누락된 항목이 표시되며, 이미지 업데이트를 요청합니다. 종속성을 이미지에 추가하고, 동일한 세 개의 영구 볼륨을 사용하여 다시 배포합니다. 호스트 설치는 자체 종속성 설치 프로그램을 유지하며, 기존 OS 권한 내에서 새로운 Skill 종속성을 준비할 수 있습니다.
Agent는 연결한 후 Skills를 하나씩 준비합니다. 의존성 검사 중에도 채팅은 사용할 수 있습니다. 기본 동기화 간격은 약 10분입니다. 준비나 상태 보고에 실패하면 30초 후 재시도하며 성공하면 기본 간격으로 돌아갑니다. 더 짧게 설정한 간격은 재시도에도 적용됩니다. 상태 보고에 실패해도 로컬에 준비된 Skill을 제거하거나 다시 보고할 때 재설치하지 않습니다.
AGENT_SKILL_DEP_INSTALLER를 오래된 컨테이너에 설정해도 부족한 체커가 추가되지 않습니다. 컨테이너를 다시 생성하거나, 그 체커가 포함된 이미지로 워크로드를 업데이트해야 합니다.
연결 정보 준비¶
이 값들은 Beak 콘솔 또는 설치 페이지에서 가져올 수 있습니다. Docker와 Kubernetes, YAML 설치 환경에서는 세 값 모두를 사용합니다. 브랜드 Helm 차트에는 이미 기본적인 Beak 주소가 포함되어 있으며, 해당 주소를 변경할 필요가 없는 경우에는 AGENT_ID와 AGENT_API_KEY만을 사용합니다.
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'
이미지 주소를 준비하십시오:
Docker로 설치¶
Docker 배포는 아래에 표시된 세 개의 명명된 볼륨을 생성하고 다시 마운트해야 합니다. 업그레이드 및 재시작 시 동일한 볼륨 이름을 재사용하십시오. 컨테이너 임시 디렉터리로 대체하지 마십시오. 컨테이너와 독립적으로 관리되는 바인드 마운트도 지원됩니다.
env 파일을 생성하십시오:
cat > obs-agent.env <<EOF
BEAK_WS_URL=${BEAK_WS_URL}
AGENT_ID=${AGENT_ID}
AGENT_API_KEY=${AGENT_API_KEY}
EOF
AIHub의 Web Search와 Mail을 유지하면서 사용자 정의 OpenAI 호환 모델을 사용하려면 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를 업그레이드하고, 세 가지 서비스 설정을 명시적으로 구성해야 합니다. 비록 URL이 동일하더라도 말입니다. Beak에서 반환된 끝점이 없거나 유효하지 않으면, 컨테이너가 Agent를 시작하기 전에 실패하게 됩니다. 로컬 도구의 끝점은 필요한 서버 설정을 대체하지 않습니다. 도구를 비활성화하려면, 그 도구의 끝점을 생략하지 말고 AGENT_WEB_SEARCH_ENABLED=false나 AGENT_SEND_EMAIL_ENABLED=false를 설정해야 합니다.
비어 있지 않은 컨테이너 환경 값이 Beak 기본값보다 우선합니다. 원격 설치 설정은 고정된 허용 목록에 따라 리터럴 데이터로 파싱하며 셸에 불러오거나 실행하지 않습니다. 반복된 알 수 없는 필드를 포함하여 알 수 없는 필드는 조용히 무시하고 내보내지 않습니다. 충돌하는 식별 필드, 중복된 알려진 필드, 잘못된 응답 및 불완전한 엔드포인트/자격 증명 소스는 비밀 정보를 출력하지 않고 Agent 시작 전에 컨테이너를 중단합니다.
이 동작은 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}"
상태를 확인하십시오:
다음 로그 라인은 시작이 성공했음을 나타냅니다:
이미지를 업그레이드하십시오:
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 명령은 세션/작업 기록 및 관련 데이터를 영구적으로 삭제합니다. 복원하거나 이어갈 작업이 없음을 확인한 후에만 실행하십시오.
Browser 설정¶
표준 Agent 이미지를 사용하세요. 필요한 공유 라이브러리와 중국어 글꼴이 포함되어 있습니다. Browser는 기본적으로 활성화됩니다. AGENT_BROWSER_ENABLED가 설정되지 않았거나 비어 있으면 true를 의미합니다. 컨테이너 시작 과정에서 추가 설정 없이 Browser 프로그램을 설치하거나 재사용합니다.
Browser 기능을 비활성화하려면 Docker 또는 obs-agent.env 파일에 다음과 같은 설정을 해야 합니다:
동일한 이미지와 세 개의 기존 영구 볼륨을 사용하여 컨테이너를 다시 생성합니다. docker restart만으로는 변경된 환경 파일을 읽을 수 없습니다. 동일한 환경 변수를 Kubernetes, YAML에 추가하거나 Helm 값에 설정해야 합니다.
첫 번째 시작 과정에서는 이미지의 Agent 다운로드 주소와 테스트를 위한 Chrome(AMD64) 또는 데비안 크로미오 패키지 다운로드가 필요합니다(ARM64; 구 패키지는 데비안 스냅샷에서 가져올 수 있습니다). 엔트리포인트는 agent-browser 및 브라우저의 고정된 버전을 루트 사용자가 아닌 상태에서 확인하고 설치합니다. 다운로드 과정에는 시간이 걸릴 수 있습니다. 프로그램들은 /var/lib/obs-agent/profile-cache/browser-runtime에 캐싱됩니다. 재시작, 재구성, 롤백 과정에서는 이미지와 일치하는 완전히 검증된 캐시가 사용됩니다. 완전한 캐시는 오프라인 상태에서도 작동합니다; 첫 번째 설치 또는 손상된 캐시는 네트워크 접근이 필요합니다. 기존의 프로필 캐시 볼륨은 그대로 유지됩니다.
다운로드 또는 상태 검사에 실패하면 Browser를 사용할 수 없다는 진단을 표시하지만 일반 Agent는 계속 시작할 수 있습니다. 샌드박스 검사를 자동으로 비활성화하지 않습니다. 노드에서 Chromium 사용자 네임스페이스를 제한하면 컨테이너 권한을 직접 부여하지 말고 관리자에게 노드 정책 확인을 요청하세요.
명시적인 AGENT_BROWSER_ENABLED=false를 설정하면 캐시가 존재하더라도 다운로드 및 Browser 도구 사용이 제한됩니다. 명시적인 false를 사용하는 기존 배포 환경에서는 해당 설정이 유지됩니다. 이 설정을 true로 변경하고 컨테이너를 다시 생성하거나 워크로드를 업데이트하여 Browser 기능을 다시 활성화시킬 수 있습니다. 캐시는 웹사이트 쿠키, 로그인 상태, 세션 승인 정보 등을 포함하지 않습니다. 이 시작 스위치는 Browser 세션 승인 규칙을 변경하지 않습니다. 네이티브 설치 방식은 변하지 않습니다.
Kubernetes YAML로 설치¶
Helm을 사용하지 않는 경우 OSS에 게시된 기본 매니페스트를 직접 사용할 수 있습니다.
기본 매니페스트는 세 개의 PVC(20 GiB, 5 GiB, 5 GiB)를 생성하고 마운트합니다. 설치 전에 클러스터에 동적 프로비저닝을 위한 기본 StorageClass가 있거나 PVC가 바인딩할 수 있는 사전 생성된 PV가 있어야 합니다. PVC가 바인딩되지 않은 동안 Pod는 Pending 상태로 유지됩니다. 이를 emptyDir로 대체하지 마십시오. Pod 재빌드나 업그레이드 시 활성 세션/작업 JSONL 기록 및 관련 데이터가 손실되기 때문입니다.
매니페스트를 다운로드하십시오:
특정 버전의 매니페스트를 다운로드하십시오:
네임스페이스를 생성하십시오:
매니펫은 환경 변수에 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 또는 네임스페이스를 삭제하면 StorageClass 회수 정책에 따라 기저 PV 데이터도 삭제될 수 있습니다.
YAML 설치를 제거하십시오:
아래 명령은 매니페스트가 생성한 PVC를 삭제합니다. 기저 PV 데이터가 보존되는지 여부는 StorageClass 회수 정책에 따라 다릅니다. 복원하거나 이어갈 작업이 없음을 확인한 후에만 실행하십시오.
Kubernetes Helm으로 설치¶
Helm 차트는 기본적으로 세 개의 PVC(20 GiB, 5 GiB, 5 GiB)를 생성하고 마운트합니다. 설치 전에 기본 StorageClass를 구성하거나 persistence.work.existingClaim, persistence.profileCache.existingClaim, persistence.owl.existingClaim을 통해 바인딩된 세 개의 PVC를 지정하십시오. 이러한 영속성 항목을 비활성화하지 마십시오. Pod 재빌드나 업그레이드 시 활성 세션/작업 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
네임스페이스를 생성하십시오:
에이전트 시크릿을 생성하십시오:
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 차트에는 현재 브랜드에 대한 기본적인 Beak 주소가 포함되어 있으므로, 일반적인 설치에서는 config.BEAK_WS_URL를 수동으로 설정할 필요가 없습니다.
이 차트는 기본적으로 automountServiceAccountToken: false를 설정합니다. 현재의 Agent 기능들은 Kubernetes, API 자격 증명이 필요하지 않습니다. ConfigMap, Secret, PVC 마운트는 이 토큰에 의존하지 않습니다. 만약 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
--set-string config.BEAK_WS_URL="${BEAK_WS_URL}"를 추가할 수 있는 경우는, 사용자 정의 Beak 주소를 사용할 때, 브랜드가 없는 기존의 Chart를 업그레이드할 때, 또는 docs/examples/helm/obs-agent에서 리포지터리 소스로부터 Chart를 직접 설치할 때뿐입니다.
상태를 확인하십시오:
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
만약 더 오래된 버전의 파일에 잘못된 또는 해결되지 않은 Beak 주소가 저장되어 있다면, --reuse-values는 그 값을 그대로 유지합니다. 고정된 차트로의 첫 번째 업그레이드 때도 --set-string config.BEAK_WS_URL="${BEAK_WS_URL}"를 전달하여 그 값을 수정해야 합니다. 이후의 업그레이드에서는 계속해서 해당 값을 재사용할 수 있습니다.
Helm 설치를 제거하십시오:
helm uninstall은 차트가 생성한 PVC를 삭제하며, kubectl delete namespace는 해당 네임스페이스의 PVC도 삭제합니다. 기저 PV 데이터가 보존되는지 여부는 StorageClass 회수 정책에 따라 다릅니다. 복원하거나 이어갈 작업이 없음을 확인한 후에만 이 명령을 실행하십시오.
사용 가능한 환경 변수 보기¶
모든 설치 방법에는 AGENT_ID와 AGENT_API_KEY이 필요합니다. Docker와 Kubernetes, YAML도 BEAK_WS_URL이 필요합니다. 브랜드 Helm 차트는 기본 주소를 제공하므로, 커스텀된 엔드포인트나 구형 차트의 경우에만 기본 값을 변경해야 합니다. 아래의 나머지 변수들은 문제 해결이나 기본 값의 변경을 위한 것입니다.
| 환경 변수 | 수동 설정이 필요합니다. | 설명 |
|---|---|---|
BEAK_WS_URL |
Docker/YAML: 예; 브랜드 Helm: 없음 | Beak 설정 API 주소입니다. 예: https://agent-api.guance.com. 브랜드별 Helm Charts는 기본값을 포함하며 config.BEAK_WS_URL로 재정의할 수 있습니다. |
AGENT_ID |
네 | Agent 인스턴스 ID입니다. 각 실행 중인 인스턴스는 고유해야 합니다. |
AGENT_API_KEY |
네 | Agent가 Beak 설정 API와 WebSocket에 접근할 때 사용하는 자격 증명입니다. |
BEAK_ENDPOINT |
아니오 | 컨테이너 진입점이 Beak 설정 API를 읽을 때 사용하는 대체 주소입니다. 설정하지 않으면 BEAK_WS_URL을 사용합니다. |
HTTP_PROXY / http_proxy |
아니오 | HTTP은 HTTP 및 WS 요청을 위한 전달 프록시입니다. 대문자와 소문자 변수는 모두 설정된 경우 일치해야 합니다. |
HTTPS_PROXY / https_proxy |
아니오 | HTTPS 및 WSS 요청을 위한 프록시 서버입니다. 프록시 엔드포인트는 여전히 http://를 사용합니다. |
NO_PROXY / no_proxy |
아니오 | 프록시를 우회하는 호스트, 도메인, IP 주소, 또는 CIDR 값들입니다. 최소한 localhost,127.0.0.1,::1를 포함해야 합니다. |
SSL_CERT_FILE / SSL_CERT_DIR |
아니오 | 프록시가 TLS 인증서를 다시 서명할 때 사용되는 Enterprise CA 파일 또는 디렉터리입니다. |
AGENT_NAME |
아니오 | Agent 표시 이름입니다. 수동으로 설정하지 않으면 Beak 설정 API가 제공합니다. |
AGENT_WORKDIR |
아니오 | Agent 작업 디렉터리입니다. 컨테이너의 기본값은 /app입니다. |
AGENT_PROFILE_CACHE_DIR |
아니오 | Profile 캐시 디렉터리. 컨테이너의 기본값은 /var/lib/obs-agent/profile-cache입니다. |
AGENT_BROWSER_ENABLED |
아니오 | 설정하지 않거나 비어 있으면 기본값은 true입니다. 시작 전에 Browser 프로그램을 설치하거나 재사용하고 상태 검사에 성공한 후 도구를 제공합니다. 명시적인 false는 다운로드와 Browser를 비활성화합니다. 변경 후 컨테이너를 다시 생성하거나 워크로드를 업데이트하세요. |
AGENT_LOCAL_TIMEZONE |
아니오 | Agent 현지 시간대. 컨테이너의 기본 시간대는 Asia/Shanghai입니다. |
AGENT_HTTP_ALLOWED_DOMAINS |
아니오 | HTTP 도구가 접근할 수 있는 도메인을 쉼표로 구분하여 제한합니다. |
AGENT_UPDATE_ENABLED |
아니오 | 컨테이너화된 배포 방식에서는 자동 업데이트 기능이 비활성화됩니다. 이미지나 매니펫을 교체하여 업그레이드해야 합니다. |
AGENT_UPDATE_HELPER_PATH |
아니오 | 자동 업데이트 도우미 경로입니다. 일반적으로 컨테이너화된 배포 환경에서는 사용되지 않습니다. |
AGENT_UPDATE_BASE_URL |
아니오 | 자동 업데이트를 위한 릴리스 주소입니다. 일반적으로 컨테이너화된 배포 환경에서는 사용되지 않습니다. |
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과 호환되는 모델 엔드포인트입니다. 이 엔드포인트은 Beak 외부의 배포 시스템을 통해 설치될 수 있습니다. |
LLM_API_KEY |
아니오 | 모델 API 키입니다. 이 키는 LLM_BASE_URL에게만 전송됩니다. |
LLM_MODEL |
아니오 | 모델 이름. 커스텀 모델의 경우 명시적으로 설정해야 합니다. |
LLM_TEMPERATURE |
아니오 | LLM 온도. 기본값은 0.2입니다. |
LLM_MAX_TOKENS |
아니오 | 최대 LLM 출력 토큰입니다. 기본값인 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 |
아니오 | 버그 보고서에서 사용되는 제한된 로테이션 로그 복사본입니다. 컨테이너는 영구 프로필-캐시 볼륨에서 기본적으로 /var/lib/obs-agent/profile-cache/diagnostics/agent.log로 설정되며, 경로가 쓰기 가능하지 않다면 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 설정 API가 제공하며, 트레이스 내보내기가 필요하면 수동으로 재정의할 수 있습니다. |
OTEL_EXPORTER_OTLP_HEADERS |
아니오 | OTEL 요청 헤더입니다. Beak 설정 API가 제공하며, 트레이스 내보내기가 필요하면 수동으로 재정의할 수 있습니다. |
OTEL_LOGS_ENABLED |
아니오 | 현재 Agent가 무시하는 이전 변수입니다. Beak의 런타임 설정 API가 메트릭, 로그 및 트레이스를 함께 제어합니다. |
AGENT_MAX_RUN_DURATION |
아니오 | 각 실행의 소프트 시간 한도입니다. 기본값은 2h입니다. 진행 중인 모델 요청이나 도구를 완료한 후 새 작업을 중단하고 요약을 한 번 시도합니다. 승인 대기 시간도 포함되며 0s로 비활성화합니다. |
AGENT_MAX_LLM_MESSAGES |
아니오 | 단일 모델 요청에 대한 선택적 메시지 수 안전 한도입니다. 기본값은 0입니다(비활성 상태). |
AGENT_MAX_LLM_MESSAGE_CHARS |
아니오 | LLM 메시지당 최대 문자 수입니다. 기본값은 512000입니다. |
AGENT_MAX_SYSTEM_PROMPT_CHARS |
아니오 | 최대 시스템 알림 문자 수입니다. 기본값은 512000입니다. |
AGENT_QUERY_SESSION_CHAT_HISTORY_LIMIT |
아니오 | 세션 기록에 대한 쿼리 제한. 기본값은 20입니다. |
AGENT_CONTEXT_BUDGET_TOKENS |
아니오 | 컨텐츠 토큰 예산. 기본값은 262144입니다. |
AGENT_CONTEXT_BUDGET_CHARS |
아니오 | 컨텍스트 캐릭터 예산. 기본값은 262144입니다. |
AGENT_REASONING_DISPLAY_MODE |
아니오 | 추론 표시 모드입니다. hidden 또는 raw를 지원합니다. 기본 설정은 hidden입니다. |
AGENT_PROFILE_SYNC_DISABLE |
아니오 | 시작 시, 주기적인 확인 과 push 알림 과정에서 원격 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 |
아니오 | Agents이 복잡한 작업을 수행하기 전에 사용 가능한 도구, 증거, 그리고 실행 경로를 확인해야 합니다. 기본값은 true입니다. 이 기능을 비활성화하려면 false로 설정해야 합니다. 이 설정은 주 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 키 ID. |
AGENT_MESSAGE_HPKE_PRIVATE_KEY |
아니오 | HPKE 개인 키 내용입니다. |
AGENT_MESSAGE_HPKE_KEY_PATH |
아니오 | HPKE 개인 키 파일의 경로입니다. |
AGENT_MESSAGE_HPKE_ROTATION_INTERVAL |
아니오 | HPKE 키의 교체 주기입니다. 기본값인 0는 자동 교체가 불가능함을 의미합니다. |
OWL_BASE_URL |
아니오 | Owl 의존성 다운로드 주소입니다. 일반적으로 이미지에 포함되거나 Beak 설정 API가 제공합니다. |
OWL_INSTALL_URL |
아니오 | Owl 설치 스크립트 주소입니다. 일반적으로 Beak 설정 API가 제공합니다. |
OWL_REGISTRY_ENDPOINT |
아니오 | Owl 레지스트리 주소입니다. 일반적으로 Beak 설정 API가 제공합니다. 정상적인 Agent 시작 과정에서 $OWL_DIR/config.yaml에 기록됩니다. |
OWL_TOKEN |
아니오 | Owl 레지스트리 접근 토큰입니다. 일반적으로 Beak 설정 API가 제공합니다. 시작 시 Owl 설정의 auth.api-key에 기록하며 도구 환경의 허용 목록에는 추가하지 않습니다. |
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 디렉터리를 마운트합니다; 별도로 마운트된 읽기 전용 설정 파일은 이 모드를 지원하지 않습니다. - 컨테이너 시작 과정은
registry.endpoint와auth.api-key를 포함한 루트config.yaml전체를 관리합니다. 재시작하면 파일 전체를 교체하므로 사용자 정의 필드는 보존되지 않지만 캐시와 데이터는 유지됩니다. 업그레이드 전에 기존 설정을 백업하세요. 두 시작 입력이 모두 비어 있으면 파일을 쓰지 않으며 하나만 제공하면 시작을 중단합니다. 비어 있지 않은 로컬 재정의가 계속 우선하고 사용자 정의 레지스트리에는 로컬 토큰이 필요합니다. 호스트 초기화는 기존 값 우선순위를 유지합니다. - 만약 영구 볼륨이
state.yaml라는 명명된 프로필을 선택하거나,OWL_PROFILE의 값이default와 다르게 설정된 경우, Agent는 오류를 보고하고 설정을 그대로 유지합니다. 유지 관리 환경에서는 컨테이너를 시작하기 전에 동일한OWL_DIR로owl switch default를 실행하고OWL_PROFILE을 삭제해야 합니다. Agent은 명명된 프로필을 자동으로 변경하지 않습니다. 유효하지 않은state.yaml또는 쓰기 또는 교체 작업 중 발생하는 오류도 시작을 중단시키고 원래 설정을 유지합니다. - Docker와 Helm은 동일한
AGENT_ID를 동시에 온라인에서 사용할 수 없습니다. 실행 중인 각 인스턴스에는 독립적인 에이전트가 필요합니다. - 이미지만 교체하여 업그레이드한 이전 배포의 경우, Owl 볼륨이
/var/lib/obs-agent/work/.owl에 마운트된 상태로 남아 있으면OWL_DIR이 설정되지 않았을 때 진입점이 이를 감지하고 계속 사용합니다. 새 Compose, Kubernetes, Helm 템플릿은/app/.owl을 사용합니다. 마이그레이션 중에 두 Owl 볼륨을 모두 마운트하지 마십시오. obs-agent.yml은 전용 ServiceAccount를 생성하고 Kubernetes 서비스 계정 토큰 자동 마운트를 비활성화합니다.- 컨테이너는 호스트 설치 스크립트를 실행하지 않으며 systemd에 의존하지 않습니다.
- 컨테이너화된 배포는 로컬 자체 업데이트를 활성화하지 않습니다. 이미지 태그 또는 다이제스트를 교체하여 업그레이드하십시오.
- 프로덕션에서는 이미지 다이제스트를 사용하여 버전을 고정하십시오.