配置

Scopwis 把部署配置、Server 拥有的产品配置和客户端偏好分开。客户端在调用受保护业务 API 前，会先通过公开 Bootstrap 契约确认当前 Server 到底支持哪些产品能力。

Server 基础设置

SCOPWIS_HOST=127.0.0.1
SCOPWIS_PORT=3000
SCOPWIS_DATA_ROOT=/path/to/data
SCOPWIS_LOAD_PUBLIC_DATA=true

只有明确需要网络访问并已经配置认证/来源策略时，才把 host 改成 0.0.0.0。

模型配置

使用 设置 → 模型 或 SCOPWIS_MODEL_* 环境变量。只要持久化 Settings 配置存在，它就优先于启动 fallback。

Jev 是模型设置下独立的可选 Decision Plane assist。它必须 fail-soft：Jev 不可用不能替代确定性完成门禁，也不能让主推理链路启动失败。

认证

SCOPWIS_AUTH_REQUIRED=false 保持 Guest 工作区可用。要求认证时，需要配置 OAuth/OIDC provider，并确保公开 Base URL 与 callback 完全一致。

客户端只拿到 Scopwis session；provider OAuth access token 和 client secret 始终保留在 Server。

在设置中配置 GitHub 登录

在 GitHub 创建 OAuth App，保存它的 Client ID 和 Client Secret。
打开 设置 → 账户 → GitHub SSO。启用 GitHub，填写 Client ID、Secret，以及当前 Scopwis Server 的公开来源地址，例如 https://scopwis.example.com。
复制页面显示的回调地址 https://scopwis.example.com/api/v1/auth/github/callback，填入 OAuth App 的 Authorization callback URL。
首次保存需要服务器初始化令牌。部署管理员在 Server 环境中设置 SCOPWIS_SSO_SETUP_TOKEN，然后在页面输入该值。它用于初次配置和恢复管理权限，与 GitHub 凭据无关。
保存后点击 通过 GitHub 登录。已登录的管理员使用初始化令牌保存一次，即成为此配置的所有者，之后可以直接更新。

GitHub 凭据在 Server 加密保存。页面只显示是否已有 Secret，不会返回原值；Secret 留空会保留已有凭据。更新采用修订检查，保存后立即用于新的登录流程；已开始的授权流程继续使用其原配置。远端来源地址必须使用 HTTPS，本地开发可使用 loopback HTTP 地址。

环境变量部署仍可使用 SCOPWIS_GITHUB_CLIENT_ID、SCOPWIS_GITHUB_CLIENT_SECRET 与 SCOPWIS_PUBLIC_BASE_URL。持久化的 GitHub 设置优先于环境变量。启用 SCOPWIS_AUTH_REQUIRED=true 时，不能关闭最后一个可用登录方式。

GitHub 登录使用 Authorization Code 与 S256 PKCE，参见 GitHub OAuth App 授权指南。

Web Origin

跨域浏览器部署使用明确 HTTPS allowlist，例如：

SCOPWIS_ALLOWED_ORIGINS=https://app.example.com

Wildcard、带凭据 URL、远端纯 HTTP、带 path/query 的 origin 都会失败关闭。

持久化数据

runtime artifact、ownership、conversation、加密配置和 source state 都位于 SCOPWIS_DATA_ROOT。大 query payload 与不可变 artifact envelope 分开存储，并可能按照 query artifact TTL 过期。

不要手工编辑加密状态文件。涉及破坏性迁移前，先备份 data root。

客户端能力协商

客户端会先调用 GET /api/v1/bootstrap。稳定 capability 包括 Agent task/runtime、analysis methods、artifact、report、data source、model configuration、external capability 和 semantics。已知 capability 缺失时，对应 UI 应直接禁用，而不是先请求 endpoint 再等 404。