用途：在修改应用代码前，先用 Prefactor CLI 为智能体开通凭证与运行时配置，属于初始化步骤。核心原则是“先开通，后埋点”。适用触发场景包括：为某个智能体设置 Prefactor、注册 Prefactor 智能体并获取环境变量、用 CLI 引导 Prefactor、在埋点前准备 ID 与环境变量。
前置条件：Prefactor CLI 已安装（prefactor 在 PATH 中，或通过 npx @prefactor/cli）；人类已在真实终端运行过 prefactor login；当前处于应接收环境变量值的项目根目录。不要运行 prefactor login、prefactor profiles add，也不要凭空编造 API token；若因未登录导致失败，应停止并要求用户自行登录。
CLI 工作流：使用单条 setup 命令，建议加 --json 以便解析。已有智能体：prefactor setup <agent_id> --json；新建智能体：prefactor setup --create --name "<short-agent-name>" --description "<short description>" --json。setup 会按需创建部署、签发部署级运行时 token、通过 ping 校验该 token，并输出 api_url、api_token、agent_id、agent_identifier。该输出是 Prefactor 配置的唯一事实来源，不要在中列出账户、创建环境、手动创建 API token 或注册智能体实例。
写入环境变量：按项目现有环境变量模式写入，字段映射为 PREFACTOR_API_URL、PREFACTOR_API_TOKEN、PREFACTOR_AGENT_ID、PREFACTOR_AGENT_IDENTIFIER。不要自创密钥结构，不要提交 prefactor.json（可能含 profile token）。
包选择：根据项目选择适配器，LangChain 用 @prefactor/langchain，AI SDK 用 @prefactor/ai，OpenClaw 用 @prefactor/openclaw，Claude SDK 用 @prefactor/claude；自定义或不支持的提供方改用 create-provider-package-with-core 技能。用项目现有包管理器安装，并由同一适配器包导入辅助函数。
验证与常见错误：确认 setup 成功、环境变量与输出一致、包与提供方匹配、prefactor.json 未进入暂存。常见错误包括：先埋点后 setup、在 setup 之外运行登录或创建 token、忽略 setup JSON 自造键名或包名、将适配器初始化与 @prefactor/core 的 withSpan/shutdown 混用（除非显式传入 tracer）、提交 prefactor.json。具体支持范围与限制以官方资料为准，资料未提供更多细节。