它到底是什么

claude setup-token 是一个 CLI 子命令，用来为 CI 和脚本生成长期有效的 OAuth token。官方 CLI reference 的描述是："Generate a long-lived OAuth token for CI and scripts. Prints the token to the terminal without saving it. Requires a Claude subscription."

认证文档补充了几点：

• 运行时打开与 /login 相同的浏览器授权流程，授权后 token 打印到终端。
• token 有效期为一年。
• 命令不会保存 token。你需要自己复制它，再设置成 CLAUDE_CODE_OAUTH_TOKEN 环境变量。
• token 走的是 Claude 订阅认证，需要 Pro、Max、Team 或 Enterprise 计划。

用法 / 语法

claude setup-token

官方文档只给出这一种形式，没有列出任何 flag。

拿到 token 后，在需要认证的环境里设置环境变量：

export CLAUDE_CODE_OAUTH_TOKEN=your-token

退出码 / 输出格式

官方文档没有说明退出码，也没有 --output-format 之类的结构化输出。已知的输出行为只有：token 在浏览器授权完成后打印到终端（stdout/stderr 的具体归属文档未说明）。

Shell 集成 / 自动化

GitHub Actions：官方文档的做法是在本地运行 claude setup-token，把结果存为仓库 secret CLAUDE_CODE_OAUTH_TOKEN，然后在 workflow 里通过 claude_code_oauth_token 输入传给 anthropics/claude-code-action:

- uses: anthropics/claude-code-action@v1
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

官方文档说明，如果 workflow 示例里写的是 anthropic_api_key 那一行，使用订阅认证时把它替换成 claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} 即可。

认证优先级：CLAUDE_CODE_OAUTH_TOKEN 在认证优先级列表中排第 5，低于云厂商凭据、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 和 apiKeyHelper，高于 /login 保存的订阅 OAuth 凭据。同一环境里设了 ANTHROPIC_API_KEY 时，后者会先被使用（交互模式下需先经你批准，-p 非交互模式只要存在就使用）。

与会话内同名命令的差异

与之相关的是 /login，二者的差异：

如果在 CLAUDE_CODE_OAUTH_TOKEN 已设置时运行 /login，当前会话会切换到新登录，但每个新会话仍会重新读取该环境变量，直到你把它从 shell profile 或 settings 的 env 块中移除。

运行约束 / 限制

经典使用场景

• GitHub Actions：把 token 存为 CLAUDE_CODE_OAUTH_TOKEN secret，让 claude-code-action 使用订阅额度而非 API 计费（GitHub Actions 文档："If you authenticate with an OAuth token, runs use your Claude subscription instead of API billing"）。
• 其他无浏览器环境的脚本 / CI 流水线：在 shell 环境中导出 CLAUDE_CODE_OAUTH_TOKEN 后运行 claude。

常见坑

• 忘记复制 token：命令不保存 token，需要自行复制。
• 环境里残留 ANTHROPIC_API_KEY：优先级更高，会盖过 OAuth token（交互模式下需先经你批准才会使用，-p 非交互模式只要存在就使用）；若该 key 属于已禁用或过期的组织，可能导致认证失败。
• token 无法用于 --bare：脚本传了 --bare 时，CLAUDE_CODE_OAUTH_TOKEN 不会被读取。
• 误以为可用于 Remote Control 或 claude.ai connectors：该 token 只能发模型请求，这两项功能不可用。
• /login 后新会话仍读旧 token：环境变量没移除时，每个新会话都会再次读取它。
• 提交进仓库：官方文档警告，不要把 API key 或 OAuth token 直接提交到仓库，应存为 GitHub Secrets。

来源

• CLI reference - Claude Code Docs
• Authentication - Claude Code Docs
• Claude Code GitHub Actions - Claude Code Docs