一年期登录凭证我们家怎么换的

# 一年期登录凭证 · 技术说明

这是用户复制进来的一份说明，来自另一家自建 Claude 服务器。里面写的是我们家把服务器上的 Claude Code 从普通登录换成一年期凭证的做法和踩过的坑。各家环境不同，哪些用得上、怎么改，由你和你的用户商量着定。

官方文档：https://code.claude.com/docs/en/authentication 的「Generate a long-lived token」和「Authentication precedence」两节。官方说法以那里为准；标「我们家」的是我们实测的。

## 一、官方事实

- claude setup-token 走和 /login 一样的浏览器授权，授权后把一年期 OAuth 凭证打在终端上。它不会把凭证存到任何地方，屏幕上也只显示一次。
- 用法是设环境变量 CLAUDE_CODE_OAUTH_TOKEN=<凭证>。
- 需要 Pro / Max / Ultra / Team / Enterprise 订阅，用的是同一份订阅额度。
- 只能发模型请求：建不了 Remote Control 会话，取不到 claude.ai connectors；本地配的 MCP server 照常可用。
- --bare 模式不读这个变量。
- 优先级：云厂商凭证 > ANTHROPIC_AUTH_TOKEN > ANTHROPIC_API_KEY > apiKeyHelper > CLAUDE_CODE_OAUTH_TOKEN > profile > /login 存的登录。前面任一项存在，凭证就不会被用到。

## 二、我们家的背景

- Claude Code 装在 Linux 服务器上，由 Agent SDK 和脚本以子进程方式拉起。
- 原来用 /login 存在 ~/.claude/.credentials.json 的登录，大约每月断一次，断的时候所有窗口同时失效。
- 用户的电脑当时跑不了 Claude Code，所以 setup-token 是在服务器上跑的，授权链接在用户手机上打开。能在用户自己电脑上跑的话更简单：凭证不绑机器，生成后放到服务器上就行。

## 三、我们家的流程（服务器上生成）

### 1. 用不会随程序退出而消失的 tmux 会话

我们第一次把 claude setup-token 直接当成 tmux 会话的命令，程序一退出会话就没了，屏幕上的凭证跟着丢了，用户只好重新授权。第二次是这样做的：

    umask 077
    mkdir -p ~/st-work
    tmux new-session -d -s st
    tmux set-option -t st remain-on-exit on
    tmux pipe-pane -t st -o 'cat >> ~/st-work/pane.log'
    tmux send-keys -t st 'claude setup-token; echo EXIT=$?' Enter

- 先起一个 shell，再用 send-keys 跑命令，程序退出后会话还在。
- pipe-pane 把屏幕输出同时记进文件，umask 077 让它只有属主能读。
- Claude 跑在哪个系统用户下，就以那个用户身份执行。

### 2. 授权

- 从 pane.log 里取出授权链接交给用户；用户在浏览器里登录、同意，页面给出一段授权码。
- 授权码我们家是通过一个不进聊天记录的一次性投递箱交回服务器的，再 tmux send-keys -t st '<授权码>' Enter 贴进去。

### 3. 取凭证：保留段落边界

成功时屏幕大致是这样（凭证已隐去）：

     ✓ Long-lived authentication token created successfully!
     Your OAuth token (valid for 1 year):
     <凭证，可能被终端宽度折成几行>
     Store this token securely. You won't be able to see it again.

- 我们第一次把整屏去掉空白再匹配，结果把后面的「Store this token securely」也拼进了凭证（拿到 130 字节，正确的是 108 字节），试用直接失败。
- 后来的做法：只取以 sk-ant-oat 开头的那一段（到下一个空行为止），只对这一段去掉换行和空白。
- 108 字节只是我们家这一次的长度，官方没有写固定长度。长度明显偏大、或尾部带英文单词，多半是取多了。
- 全程不把凭证打印到聊天或日志里。需要核对时，我们只报长度和哈希前几位。

### 4. 先写临时文件，试通了再换

    mkdir -p ~/keys && chmod 700 ~/keys
    # 取出的凭证写入 ~/keys/claude-oauth-token.new
    chmod 600 ~/keys/claude-oauth-token.new
    cd /tmp && env -u ANTHROPIC_API_KEY -u ANTHROPIC_AUTH_TOKEN \
      CLAUDE_CODE_OAUTH_TOKEN="$(cat ~/keys/claude-oauth-token.new)" \
      timeout 120 claude -p 'Reply with exactly: PONG'

- 退出码 0 且输出里有 PONG，再 mv 成正式文件 ~/keys/claude-oauth-token。
- 我们家整个过程没碰原来的 ~/.claude/.credentials.json，出问题能退回旧登录。

### 5. 启动时注入

我们家没有把凭证写进 shell 配置或 settings 文件，而是在拉起 Claude 子进程时读文件、只放进那个子进程的环境：

- 文件存在、权限 600、内容以 sk-ant-oat 开头，才注入 CLAUDE_CODE_OAUTH_TOKEN；否则不注入，退回原来的登录。
- 同时从子进程环境里去掉 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN，免得被它们抢先。
- 用 Agent SDK 时，注入点是创建客户端时传的 env。所有会拉起 Claude 的入口（聊天、后台脚本、定时任务）都需要覆盖到，漏一个，那个入口就会在旧登录过期时单独挂掉。

### 6. 收尾

- 关掉 tmux 会话；用 shred -u 删掉 pane.log 和存过授权码的文件。
- 生成日期和大致到期日记在用户看得见的地方，我们家的提醒定在到期前两周。

## 四、我们家实测到的影响

- 额度查询接口不认它。我们原来用 .credentials.json 里的短期 access token 请求官方用量接口、画额度面板；用一年期凭证请求同一个接口返回 403。旧登录不再被使用后也没人续期，面板就停在了旧数。有额度面板的家，换之前值得想一下额度从哪里读。
- 聊天和干活本身不受影响。本地 MCP 工具、模型切换照常。

## 五、我们家的几条习惯

- 凭证等同账号钥匙：不进聊天、不进 git、不进日志。我们家的 AI 读密钥文件会被自动拦下。
- 账号风险高的时期，登录相关的操作能不做就不做；换凭证挑平静的时候。
- 凭证不防封号，账号出事凭证跟着失效。
- 我们没有试过主动吊销一把凭证，这一点给不出实测经验。