TLS Observer Codex Installer

安装带内置 Stop hook 的 Codex 插件、TLS 配置和失败 trace 重试任务。

安装

npm exec -y \
  --package=@volcengine/tls-observer-codex-install -- \
  tls-observer-codex-install

旧命令 storage-tls-codex-install 仍可作为兼容 alias 使用。

API Key 非交互示例：

npm exec -y \
  --package=@volcengine/tls-observer-codex-install -- \
  tls-observer-codex-install \
  --non-interactive \
  --force \
  --region <region> \
  --tls-endpoint tls-<region>.volces.com \
  --trace-topic-id <trace-topic-id> \
  --api-key <api-key>

AK/SK 非交互示例：

npm exec -y \
  --package=@volcengine/tls-observer-codex-install -- \
  tls-observer-codex-install \
  --non-interactive \
  --force \
  --region <region> \
  --project-name codex_observability \
  --app-name <log-app-name> \
  --ak <ak> \
  --sk <sk>

安装内容

• ~/.codex/plugins/marketplaces/storage-tls-codex：本地插件来源。
• ~/.codex/plugins/cache/storage-tls-codex/storage-tls/<version>：插件和 Stop hook。
• ~/.codex/config.toml：marketplace 和插件启用配置。
• ~/.codex/storage-tls-codex.env：TLS 配置，权限为 0600。
• ~/.codex/storage-tls-codex：retry runner。
• ~/Library/LaunchAgents/com.volcengine.storage-tls-codex.retry.plist：macOS 失败重试任务。
• Codex 提供的 PLUGIN_DATA：state、send-log、失败缓存和 artifacts。

安装器会清理其管理的旧 marketplace、plugin cache、旧 Stop hook 和旧更新任务，但单项历史清理失败不会阻断新安装。

TLS Region 默认是 cn-beijing，Producer endpoint 默认按 Region 自动生成为 tls-<region>.volces.com。通常无需传入 --tls-endpoint；该参数只用于覆盖自定义 TLS Producer/OpenAPI endpoint。旧 --otel-endpoint 和 CODEX_TLS_OTEL_ENDPOINT 仅作为迁移兼容输入，不再写入新配置。

自定义 span attributes 可通过 --span-attributes 'session.name:${AIPAAS_SESSION_ID},tenant.id:${TENANT_ID}' 写入 env，并由运行时展开本地环境变量。

上报容量和超时可通过安装参数配置：

• --trace-otlp-attribute-value-max-chars <n>：单 attribute 字符上限，默认 5 MiB。
• --max-batch-size <bytes>：TLS Producer batch 上限，默认 6 MiB，最大 8 MiB。
• --export-timeout-ms <ms>：单次 TLS 发送超时，默认 55 秒。

本地构建

该目录是生成型发布目录，权威源码在 packages/codex：

emo run build:installer --filter @volcengine/tls-observer-codex --skip-cache
emo run test:installer-package --filter @volcengine/tls-observer-codex --skip-cache
node packages/codex-install/bin/tls-observer-codex-install.mjs --help

不要直接维护 src/installer/*.mjs 或 bin；下次构建会覆盖它们。

发布

emo run publish:installer --filter @volcengine/tls-observer-codex

发布助手负责构建、版本和 manifest 同步、pack dry-run 与 publish；变更日志由 Changesets 管理。