コンテンツにスキップ

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 は進行中のセッションやタスクの JSONL 履歴と関連データを保存し、他の 2 ディレクトリは Profile と 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 ユーザーで動作し、すべてのケイパビリティを削除して権限昇格を禁止します。--privileged と SYS_ADMIN は不要です。この制限はツールにも適用され、Full Access でも root 権限やホスト権限は付与されません。sudo が必要な処理は、必要な OS 権限と権限昇格が既に許可されている環境でのみ動作します。標準コンテナ設定はこれらを許可しません。

アプリケーションの承認はツール呼び出しの実行を制御し、OS の認可はファイルアクセスや sudo を制御します。汎用の Bash、Python、exec、Owl、ローカル stdio MCP はプロセスのサンドボックスを提供しません。十分な OS 権限を持つプログラムは設定を読み書きできるため、設定ツールのフィールドやロールの検査は汎用シェルが回避できない隔離境界にはなりません。

Skill の依存関係とオンライン更新

v0.15.0 と v0.15.1 のコンテナイメージには Skill 依存関係の準備ツールが含まれていません。git-rg コマンドがあっても、依存関係を宣言する Skill は利用できない場合があります。v0.15.2 以降のイメージに更新してください。

修正版イメージには Skill 依存関係チェッカーが含まれ、AGENT_SKILL_DEP_INSTALLER で既定の準備ツールとして設定されます。Agent が Skill 更新通知を受信した場合や定期同期で新しい Skill を検出した場合、必要なコマンド、Debian パッケージ、Python パッケージとバージョンをイメージ内で検査してから Skill を有効にします。依存関係を満たせばコンテナの再起動は不要です。依存関係の宣言がない Skill はそのまま公開されます。

このチェッカーは稼働中のコンテナで apt、pip、sudo によるインストールを行いません。依存関係の不足やバージョン不一致がある Skill は利用不可となり、旧版には戻りません。他の準備済み Skill は利用できます。ログに不足項目とイメージ更新の必要性が表示されます。依存関係をイメージに追加し、既存の 3 つの永続ボリュームで再デプロイしてください。ホストインストールは専用の依存関係インストーラーを維持し、既存の OS 権限の範囲で新しい依存関係を準備できます。

Agent は接続した後に Skill を 1 つずつ準備します。依存関係の検査中もチャットを利用できます。通常の同期は既定で約 10 分ごとです。準備や状態報告に失敗すると 30 秒後に再試行し、成功すると通常間隔に戻ります。設定間隔が 30 秒より短い場合は再試行にもその間隔を使用します。状態報告の失敗でローカルの準備済み Skill が削除されたり、報告の再試行時に再インストールされたりすることはありません。

旧コンテナに AGENT_SKILL_DEP_INSTALLER を設定しても、欠けているチェッカーは追加されません。チェッカーを含むイメージでコンテナを再作成するか、ワークロードを更新してください。

接続情報の準備

Beak コンソールまたはインストールページから以下の値をコピーします。Docker と Kubernetes YAML では 3 つすべてを使用します。ブランド別 Helm Chart には既定の 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'

イメージのアドレスを準備します。

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

Docker でのインストール

以下の 3 つの名前付きボリュームを作成し、再起動やアップグレード後も同じ名前でマウントしてください。コンテナ内の一時ディレクトリで置き換えないでください。コンテナとは独立して管理するバインドマウントも利用できます。

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 を使う場合も 3 サービスの既定値をそれぞれ明示してください。Beak が返すエンドポイントが欠落または不正な場合、Agent 起動前にコンテナが停止します。ローカルのツールエンドポイントは必須のサーバー設定を代替しません。ツールを無効にするには、エンドポイントを省略せず AGENT_WEB_SEARCH_ENABLED=false または AGENT_SEND_EMAIL_ENABLED=false を設定します。

空でないコンテナ環境変数は Beak の既定値より優先されます。リモートの install-config は固定の許可リストに従うリテラルデータとして解析し、source や実行はしません。未知のフィールドは重複分も含めて黙って無視され、環境変数には出力されません。識別情報の競合、既知フィールドの重複、不正な応答、エンドポイントや認証情報の不足がある場合は、秘密情報を表示せず 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}"

状態を確認します。

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 はセッションやタスクの履歴と関連データを完全に削除します。復元・継続が必要なタスクがないことを確認してから実行してください。

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

同じイメージと既存の 3 つの永続ボリュームでコンテナを再作成します。docker restart だけでは変更した env ファイルは読み込まれません。Kubernetes YAML には同じ環境変数を追加するか、Helm values に設定します。

config:
  AGENT_BROWSER_ENABLED: "false"

初回起動には、イメージの Agent ダウンロード先と、Chrome for Testing(AMD64)または Debian Chromium パッケージ配布先(ARM64、旧パッケージは Debian Snapshot の場合もあります)への接続が必要です。entrypoint は固定バージョンの agent-browser とブラウザーを検証し、非 root ユーザーでインストールします。ダウンロードには時間がかかる場合があります。プログラムは /var/lib/obs-agent/profile-cache/browser-runtime に保存されます。再起動・再作成・ロールバックでは、イメージに一致する検証済みの完全なキャッシュを再利用します。完全なキャッシュはオフラインでも使えますが、初回インストールやキャッシュ破損時はネットワークが必要です。既存の profile-cache ボリュームを保持してください。

ダウンロードやヘルスチェックに失敗すると Browser 利用不可の診断が出ますが、通常の Agent は起動できます。サンドボックス検査が自動的に無効になることはありません。ノードが Chromium のユーザー名前空間を制限している場合は、コンテナへ直接特権を付与せず、管理者がノードポリシーを確認してください。

AGENT_BROWSER_ENABLED=false を明示すると、キャッシュがあってもダウンロードと Browser ツールは無効になります。既存環境の明示的な false は維持されます。再度有効にするには true に変更し、コンテナの再作成またはワークロード更新を行います。キャッシュにはプログラムのみを保存し、サイトの Cookie、ログイン状態、セッションの承認は保存しません。この起動設定は Browser のセッション承認規則を変更しません。ネイティブインストールの動作も変わりません。

Kubernetes YAML でのインストール

Helm を使わない場合は、OSS に公開された基本マニフェストを直接利用できます。

基本マニフェストは 3 つの PVC(20 GiB、5 GiB、5 GiB)を作成してマウントします。インストール前に、動的プロビジョニング用の既定の StorageClass、または PVC がバインドできる作成済み PV を用意してください。PVC が未バインドの間、Pod は Pending になります。emptyDir で置き換えると、Pod の再作成やアップグレードで進行中のセッションやタスクの JSONL 履歴と関連データが失われます。

マニフェストをダウンロードします。

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

特定バージョンのマニフェストをダウンロードします。

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

名前空間を作成します。

kubectl create namespace obs-agent

マニフェストは Beak のアドレスと Agent 認証情報を環境変数に保存します。envsubst をインストールし、以下の 3 変数だけを展開してください。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 の回収ポリシーによります。復元・継続が必要なタスクがないことを確認してから実行してください。

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

Kubernetes Helm でのインストール

Helm Chart は既定で 3 つの 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 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 のマウントもこのトークンに依存しません。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 から直接 Chart をインストールする場合に限り、--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

旧版の values に不正または未解決の Beak アドレスが保存されていると、--reuse-values はその値を保持します。修正版 Chart への初回更新では --set-string config.BEAK_WS_URL="${BEAK_WS_URL}" も指定して修正します。その後は values の再利用を続けられます。

Helm インストールを削除します。

helm uninstall は Chart が作成した PVC を削除し、kubectl delete 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 設定 API のアドレス。例:https://agent-api.guance.com。ブランド別 Helm Chart には既定値があり、config.BEAK_WS_URL で上書きできます。
AGENT_ID 必須 Agent インスタンス ID。稼働中のインスタンスごとに一意である必要があります。
AGENT_API_KEY 必須 Agent が Beak 設定 API と WebSocket に接続するための認証情報。
BEAK_ENDPOINT 不要 entrypoint が Beak 設定 API を読む際の代替アドレス。未設定なら BEAK_WS_URL を使用します。
HTTP_PROXY / http_proxy 不要 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 証明書に再署名する場合の企業 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 の temperature。既定値は 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 不要 不具合報告用のサイズ制限付きローテーションログ。既定では永続 profile-cache 上の /var/lib/obs-agent/profile-cache/diagnostics/agent.log に保存し、書き込み不可の場合はメモリー内の末尾 4 MiB を保持します。
LOG_RELATIVE_PATH 不要 ログパスを作業ディレクトリ基準で解決するかどうか。既定値は true。
LOG_MAX_SIZE_MB 不要 ログファイル 1 個の最大サイズ。既定値は 32。
LOG_MAX_BACKUPS 不要 ログバックアップ数。既定値は 5。
OTEL_EXPORTER_OTLP_PROTOCOL 不要 OTEL エクスポートプロトコル。コンテナの既定値は http/protobuf。
OTEL_EXPORTER_OTLP_ENDPOINT 不要 OTEL Collector のエンドポイント。Beak 設定 API から取得するか、トレースの出力が必要な場合に手動で上書きします。
OTEL_EXPORTER_OTLP_HEADERS 不要 OTEL 要求ヘッダー。Beak 設定 API から取得するか、トレースの出力が必要な場合に手動で上書きします。
OTEL_LOGS_ENABLED 不要 現行 Agent が無視する旧変数。Beak の runtime-config API がメトリクス、ログ、トレースをまとめて制御します。
AGENT_MAX_RUN_DURATION 不要 1 回の実行のソフト時間制限。既定値は 2h。進行中のモデル要求やツールを完了後、新規処理を停止して要約を 1 回試みます。承認待ちも含まれ、0s は無効を意味します。
AGENT_MAX_LLM_MESSAGES 不要 モデル要求 1 回あたりの任意のメッセージ数上限。既定値は 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 不要 起動時・定期確認・プッシュ通知によるリモート Profile 同期を無効化します。true ではローカルキャッシュを使用します。既定値は false。
AGENT_PROFILE_SYNC_INTERVAL 不要 Profile 全体の定期同期間隔。既定値は 10m。失敗時は 30 秒後、または設定間隔のほうが短ければその間隔で再試行します。この Agent の Profile、Skill、MCP バインドを保存すると対象を絞った同期も即座に実行されます。
AGENT_DEFAULT_APPROVAL_TTL_SECONDS 不要 非推奨。旧設定との互換性のため受け付けますが、起動時に 1 回警告して無視します。
AGENT_WEB_SEARCH_ENABLED 不要 Web Search ツールを有効にするかどうか。既定値は true。
AGENT_PRE_SEARCH_ENABLED 不要 複雑なタスクの前に利用可能なツール・証拠・実行経路を確認するかどうか。既定値は 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 不要 検索結果 1 件の最大文字数。既定値は 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 が提供し、通常起動時に $OWL_DIR/config.yaml へ書き込みます。
OWL_TOKEN 不要 Owl レジストリのアクセストークン。通常は Beak 設定 API が提供し、起動時に Owl 設定の auth.api-key へ書き込みます。ツール環境変数の許可リストには追加しません。
OWL_DIR 不要 Owl 作業ディレクトリ。既定値は ${AGENT_WORKDIR}/.owl、通常は /app/.owl。read_file と list_dir に共有の読み取り専用ルートとして公開されます。旧環境の明示的なパスも利用できます。
AGENT_IMAGE_PRINT_VERSIONS 不要 コンテナ起動時に obs-agent と owl のバージョンを表示するかどうか。既定値は false。

注意事項

  • 通常のコンテナ起動では、ツールサービスを起動する前に有効な 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 で名前付き Profile を選択している場合、または OWL_PROFILE が default 以外の場合、Agent はエラーを報告して設定を変更しません。メンテナンス環境で同じ OWL_DIR を使って owl switch default を実行し、OWL_PROFILE を解除してから起動してください。Agent は名前付き Profile を自動変更しません。state.yaml が不正な場合や書き込み・置換が失敗した場合も起動を停止し、元の設定を保持します。
  • Docker と Helm で同じ AGENT_ID を同時にオンラインにできません。稼働インスタンスごとに独立した Agent が必要です。
  • イメージだけを交換する旧環境で Owl ボリュームが /var/lib/obs-agent/work/.owl にある場合、OWL_DIR が未設定なら entrypoint が検出して継続使用します。新しい Compose、Kubernetes、Helm テンプレートは /app/.owl を使います。移行中に両方の Owl ボリュームをマウントしないでください。
  • obs-agent.yml は専用 ServiceAccount を作成し、Kubernetes サービスアカウントトークンの自動マウントを無効にします。
  • コンテナはホスト用インストールスクリプトを実行せず、systemd に依存しません。
  • コンテナではローカルの自己更新を有効にしません。イメージのタグまたは digest を交換して更新します。
  • 本番環境ではイメージの digest でバージョンを固定してください。

フィードバック

このページは役に立ちましたか?