文档中心

ArkClaw 企业版

CLI参考

身份认证与凭证

本文介绍 ArkClaw CLI 的登录与凭证管理机制，涵盖默认浏览器 SSO 登录链路、Token 刷新、凭证保存位置、A2A 端点登录、静态凭证兜底模式及退出登录的完整操作说明与安全注意事项。

默认登录链路

默认的 ArkClaw 登录和调用链路如下：

CLI 通过 OAuth 2.0 Authorization Code + PKCE 发起浏览器登录；

说明

PKCE 登录是命令行 / 网页 / 手机端安全免密钥登录方案，本地生成一对一次性密码，登录时传加密指纹，拿接口凭证时出示原始密码校验，防止授权码被盗用，是 ArkClaw CLI 浏览器 SSO 登录底层机制。

身份提供方把回调发送到本机 127.0.0.1 的临时端口；

CLI 获得代表当前用户的短期 OIDC token；

CLI 使用该 token 通过 STS 换取临时凭证；

每次连接 Claw 时，再换取短期的 ChatToken、TerminalToken 或文件服务凭证。

PKCE 使用 public client，不需要 client secret。正常的 SSO 身份穿透路径不要求最终用户配置永久 AK/SK。

Claw ID 只是资源标识，不是授权凭据。服务端仍会根据登录身份、Claw 所有权和共享 Claw 角色执行访问控制；知道某个 Claw ID 不等于获得访问权限。

浏览器登录与非浏览器登录

默认登录：

arkclaw login <用户端登录地址>

不自动打开浏览器：

arkclaw login <用户端登录地址> --no-browser

--no-browser 只是不自动启动浏览器。CLI 仍会输出授权链接，用户仍需复制链接后在浏览器完成登录，而且回调必须能够访问发起登录的本机 127.0.0.1。默认等待时间为 300 秒，因此它不是无人值守的首次认证方式。

在 --json 模式下，CLI 也不会自动打开浏览器。

如果代理拦截本机回调，可尝试把 127.0.0.1 加入 NO_PROXY，或切换网络后重试。

Token 刷新

PKCE 登录获得 refresh token 时，CLI 会在 id token 到期前约 5 分钟尝试静默刷新。refresh token 已过期、被撤销或不可用时，需要重新运行：

arkclaw login

当用户端尚未提供可用的 CLI OAuth 配置时，当前版本可能临时复用本机 Chrome 中该用户端的网页登录态。该兜底会复制并扫描 Chrome 用户数据目录中的 Local Storage，从中提取该用户端的 id token；读取过程在本机完成，提取出的 token 随后进入正常认证链路。该路径没有 refresh token，浏览器缓存过旧时需要先在 Chrome 中重新登录用户端，再重试 CLI。用户端发布 CLI public client 后，CLI 会优先使用 PKCE。

如果登录时没有解析出默认 Claw，CLI 还可能读取本机 Chrome History 的副本，查找该用户端最近访问的 Claw；无论 token 来自 PKCE 还是 Chrome 兜底，都可能触发该查询。合规敏感环境应在使用前评估这些本地浏览器数据读取行为，也可以通过显式传入 --clawid 避免历史记录推断。

凭证保存位置

macOS：Keychain。

Linux：可用的 Secret Service/keyring 后端。

如果钥匙串不可用或写入失败，CLI 会降级到 ~/.arkclaw/tokens.json。该文件权限为 0600，但内容是明文 JSON，不是加密文件。如果文件对组用户或其他用户可读，CLI 会拒绝信任该文件，并按未登录处理。

文件服务使用的短期 Silk token、IDS 临时 AK/SK 和 session token 可能缓存在 ~/.arkclaw/credcache.json。该文件同样为 0600，缓存项在接近过期时不再使用。

在共享主机或受管终端上使用前，应确认本机账号、主目录权限和钥匙串策略符合组织要求。0600 只限制其他本地账号读取，不能提供进程隔离，也不能阻止当前账号下的恶意进程读取。

A2A 登录

连接 A2A Agent 端点：

arkclaw login <用户端登录地址> \​
  --transport a2a \​
  --endpoint https://<可信A2A端点>​
​
arkclaw agents​
arkclaw chat -m "你好"​

A2A 模式会把当前用户的 Bearer token 直接发送到目标 Agent 网关，不经过 ArkClaw 的 ChatToken 链路。登录时获取 Agent Card 的探测请求也会携带该 token，因此登录建立连接时凭证就会发往目标端点；后续再次查询 Agent Card 时同样会发送。只应连接组织认可的 HTTPS 端点；目标端点属于凭证信任边界。

静态凭证模式

login --static-creds 是管理员和测试场景的逃生路径，不是最终用户的推荐登录方式。它直接使用环境中的火山引擎 AK/SK，跳过浏览器 PKCE 和 STS 身份穿透。命令必须最终解析出区域和 Claw ID；这些值可以来自显式参数、环境变量、在线发现。管理员脚本中建议显式指定，避免误用旧配置中的目标。

静态凭证可使用 ARKCLAW_AK/ARKCLAW_SK，或 VOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY；临时凭证对应的可选 session token 分别为 ARKCLAW_SESSION_TOKEN 和 VOLCENGINE_SESSION_TOKEN。应成对使用同一组变量，不要把两套命名混合配置。

该模式使用的是账号级身份，不能表达“当前企业 SSO 用户是谁”，也可能拥有远高于普通用户的权限。不得把管理员 AK/SK 分发给终端用户，也不得用该模式替代正常的权限模型。

退出登录与凭证撤销

当前版本没有 arkclaw logout 命令。重新认证可直接运行 arkclaw login。

如果需要彻底撤销登录，应先按组织流程在身份提供方或管理员侧撤销会话，再清理操作系统钥匙串中服务名为 arkclaw-webchat-cli 的对应条目。文件兜底环境还需按组织安全流程清理 ~/.arkclaw/tokens.json 和短期凭证缓存。删除前应先确认目标账号和文件，避免影响其他用户端的登录态。

最近更新时间：2026.07.23 11:19:35

这个页面对您有帮助吗？

有用

无用