使用多个 Profile¶
Profile 是一份有别名的完整 OWL 配置，包含 Endpoint、API Key 和可选的工作空间信息。例如，可以用 customer-a-prod、customer-a-test 保存同一客户的两个空间，也可以保存不同账号或站点的配置。
顶层 owl profile 管理这些独立配置。owl workspace profile 管理的是所选配置中的 workspaces 条目；workspace use 或 workspace profile use 替换所选配置的工作空间身份，不改变 owl switch 保存的默认 Profile。
新增和切换¶
# 交互输入 Endpoint、API Key，以及可选的空间 UUID 和名称
owl profile add customer-a
# 复制已有配置；后续修改不会影响源文件
owl profile add customer-b --from ./customer-b.yaml
owl profile list
owl switch customer-a
owl profile current
owl exec owl.metric.list --mode source
终端输入 API Key 时隐藏字符。新增 Profile 只保存配置，不切换当前选择；同名 Profile 会报错。别名区分大小写，长度为 1–80 个字符，允许字母（含中文）、数字、短横线和下划线，首字符必须是字母或数字。
尚未指定 --profile / OWL_PROFILE，也未执行 owl switch 时，继续使用旧配置模式。即使已新增 Profile，只要没有选择它，旧的配置文件、身份环境变量优先级和 cache/data 路径仍保持原样；init、login、config set、workspace use 仍写回原配置。
新增和切换只做本地校验，不请求云端验证授权。profile list 列出的是本机保存的配置，不是云端当前有效的账号授权清单。实际请求发生认证、权限或网络错误时会报错，不会改用其他 Profile。
命令行补全¶
启用 Bash 或 PowerShell 补全后，可用 Tab 提示本地 Profile 别名：
owl switch customer-<Tab>
owl profile rename customer-<Tab>
owl profile remove customer-<Tab>
owl --profile customer-<Tab>
owl exec --profile=customer-<Tab>
补全只读本地配置，不切换 Profile、不联网。profile add 的新别名和 profile rename 的新名称需要自行输入；保留名称 default 不会出现在重命名或删除的候选中。选择 Profile 后，工具名与参数候选来自该 Profile 的缓存。
临时选择和脚本¶
owl --profile customer-b exec owl.metric.list --mode source
OWL_PROFILE=customer-b owl exec owl.metric.list --mode source
owl profile list -f json
owl --profile customer-b profile current -f json
选择顺序为：--profile > OWL_PROFILE > owl switch 保存的默认 Profile。临时选择不会修改持久化默认；多个任务可以分别指定自己的 Profile。
对 exec、tool exec、tools exec、validate 和 tool validate，把 --profile / --conf 放在命令前面。工具名称之后的参数属于工具本身，不用于选择 OWL 配置。
Profile 生效后，Endpoint 和 Key 整套来自其配置文件。残留的 OWL_REGISTRY_ENDPOINT、OWL_API_KEY、OWL_TOKEN 及等效认证配置环境变量不会覆盖它。其他受支持的非身份环境设置继续遵循已有规则。
如果设置了 OWL_PROFILE，必须先取消它才能执行 owl switch；switch 也不接受 --profile 或 --conf。这样不会出现切换默认后，当前终端仍由临时选择指向其他 Profile 的情况。
管理命令的 -f json 输出可直接解析，交互提示写到 stderr。profile current 返回 profile、source、defaultProfile、configFile、endpoint、空间信息、脱敏 Key 及实际 cache/data 路径。authorizationChecked 为 false，表示未进行在线验证。
独立文件与旧配置¶
默认存储在 ~/.owl，设置 OWL_DIR 时跟随该目录：
~/.owl/
├── config.yaml
├── state.yaml
└── profiles/
└── profile-<id>/
├── config.yaml
├── cache/
├── data/
└── logs/
state.yaml 记录别名、稳定的目录标识及当前默认，不包含 Key。目录标识不随别名变化，因此重命名不会破坏已有查询文件的路径。使用 profile current 查看配置文件的实际位置。
每份 Profile 配置完整独立，未配置的字段使用程序默认值，不继承根 config.yaml。导入时会复制 token_file 中的凭据，并将 cache/data/log 路径调整到新 Profile 目录。命名 Profile 的这些目录由 OWL 管理，不能通过环境变量或 config set 覆盖；根配置 default 保留自定义目录及 token_file 引用。
缓存按所选身份进一步分隔；修改 Endpoint 或 Key 后会使用新的缓存分区，避免误用旧身份的工具目录。查询文件留在所属 Profile 的 data 目录中。配置文件在支持 POSIX 权限的平台上以 0600 写入，Profile 目录以 0700 创建；Windows 文件继承当前用户目录的访问控制。
旧的根 config.yaml 直接作为保留名称 default，不复制、不搬迁。尚未使用 Profile 选择功能时，旧配置和环境变量优先级保持兼容。显式选择 default 或执行 owl switch default 后，根配置也遵循整套身份规则。其 cache/data 基础目录沿用原配置。
从已弃用的 --conf 迁移¶
CLI 的 --conf 已弃用，从帮助中隐藏；兼容期保留原行为，使用时向 stderr 输出一次迁移提示，不影响 JSON stdout。建议将配置导入后使用别名：
--conf 与 --profile 同时传入会报错。单独使用 --conf 会忽略 OWL_PROFILE 和持久化选择，保持原来的环境变量优先级，并将修改写回指定文件。--conf 不选择另一套 Profile 目录，不用于 profile add/list/rename/remove。
导入后，配置、凭据与 cache/data/log 独立于源文件；身份环境变量不再覆盖所选 Profile。依赖原文件写回、外部密钥文件轮换或自定义路径的脚本，可在兼容期继续使用 --conf，完成迁移后再改为 Profile。此次弃用只针对 OWL CLI，Registry 服务的 --config 不变。
修改、重命名与删除¶
owl --profile customer-a login
owl --profile customer-a config set registry.request_timeout 180000
owl --profile customer-a workspace use wksp_example
owl profile rename customer-a customer-a-prod
owl profile remove customer-b
# 仅在需要同时删除该 Profile 的缓存和查询文件时使用
owl profile remove obsolete-profile --purge
login、config set、workspace use 修改所选 Profile，不改变持久化选择。workspace use 会替换该配置的空间 Key 和空间信息；别名只是标签，不保证永久绑定某个空间。
重命名当前默认时，OWL 同步更新选择记录。删除当前默认前必须先切换；由 OWL_PROFILE 选中的 Profile 也需要先取消临时选择。default 不允许重命名或删除。
默认删除行为只移除配置和凭据，并显示保留 cache/data 的目录路径；可以按该路径归档或清理遗留文件。--purge 则一并删除仍在管理中的 Profile 目录。重新创建同名 Profile 会生成新目录，不接入旧产物。
--purge 清理产物失败时，保留配置和凭据并恢复别名，修正目录权限后可重试。清理过程中已删除的缓存或查询文件不会恢复；需要保留产物时，请先备份或使用不带 --purge 的删除命令。