认证与访问凭证

日常使用 Clowld Space 时，你主要会接触两种凭据：浏览器登录会话和个人访问凭证。浏览器会话用于 Web 与 Desktop；个人访问凭证用于 CLI、守护进程、脚本和 API。

浏览器登录会话

通过邮箱验证码或 Google 登录后，Clowld Space 会把 JWT 保存到名为 clowld_auth 的 HttpOnly cookie 中。浏览器自动携带它，JavaScript 无法直接读取。

会话默认有效 30 天，但这不是从登录起算的倒计时：持续使用的会话会在到期前自动续期，所以不需要每隔一段时间重新登录一次。续期只在剩余有效期过半之后才发生，因此闲置的会话可能在最后一次使用后不到 30 天就失效。自托管管理员可以通过 AUTH_TOKEN_TTL 调整有效期，见登录与注册。退出登录会清除当前浏览器的认证与 CSRF cookie。

浏览器 cookie 不适合复制到脚本或 CLI；从终端访问 Clowld Space 使用个人访问凭证。

个人访问凭证

个人访问凭证（PAT）以 mul_ 开头，代表你的账号。它可以访问你有权访问的全部工作区和 API，需要像密码一样保管。

在 设置 → 访问凭证 中创建凭证时，需要填写名称，并选择 30 天、90 天、1 年或永不过期，默认选中 90 天。完整凭证只显示一次；关闭窗口后，Clowld Space 只保留：

• 凭证的哈希值；
• 用于辨认它的开头几位；
• 名称、创建时间、过期时间和最近使用时间。

完整值无法找回，丢失时吊销旧凭证并创建新的。

CLI 与 PAT

运行 clowld login 时，CLI 会通过浏览器完成登录，再创建一个有效期为 90 天的 PAT，保存到当前 profile 的配置文件：

~/.clowld-space/cli/config.json
~/.clowld-space/cli/profiles/<name>/config.json

守护进程使用同一个 PAT 连接 Clowld Space。带过期时间的 mul_ PAT 在剩余有效期不足 7 天时自动续期，延长到当时起 90 天后。续期失败不会改变凭证本身；凭证已经过期或被吊销时，需要重新运行 clowld login。

无浏览器环境可以先在 Web 中创建 PAT，再让 CLI 安全地提示输入：

clowld login --token

在 API 请求中使用 PAT

把 PAT 放进 Authorization header：

export CLOWLD_TOKEN='mul_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

curl https://api.clowld.com/api/me \
 -H "Authorization: Bearer $CLOWLD_TOKEN"

调用工作区级 API 时，还需要按接口要求提供工作区：

curl https://api.clowld.com/api/issues \
 -H "Authorization: Bearer $CLOWLD_TOKEN" \
 -H "X-Workspace-ID: $CLOWLD_WORKSPACE_ID"

脚本中的访问凭证应取自 secret manager 或受保护的环境变量，不要硬编码。自托管实例把域名替换为自己的公开 API 地址。

退出登录与吊销

clowld auth logout 只删除当前 CLI profile 中保存的 PAT；Web 退出登录只删除当前浏览器的 cookie。它们不会吊销服务器上的个人访问凭证。

如果访问凭证可能泄露，到 设置 → 访问凭证 中立即吊销。吊销后，这个 PAT 无法再次使用，已经保存它的其他电脑和脚本也会失去访问权限。

智能体执行的临时访问凭证

守护进程领取执行后，服务器会为这次执行创建一个以 mat_ 开头的临时访问凭证。它绑定当前用户、工作区、智能体和本次执行，最长有效 24 小时，并在执行结束时清理。

守护进程把这个临时访问凭证注入 AI 编程工具，而不是把用户 PAT 交给智能体。因此，智能体发出的请求会记录为智能体行为，也不能借此调用只允许用户或 owner执行的敏感操作。

这类访问凭证由服务器自动创建，用户不需要保存或管理。

其他机器凭据

服务端还识别两种内部或托管场景中的凭据：

普通 Cloud、自托管和 Desktop 安装都不需要手动创建它们。用户侧的 CLI 与守护进程始终使用 mul_ PAT；不要自行构造其他前缀的访问凭证。

接下来

• 使用 CLI — login、auth status 和 profile 配置。
• 守护进程与运行时 — PAT 续期发生的位置。
• 登录与注册 — 会话有效期与注册限制的服务端配置。