Claude Code 小课 · 2026年8月8日

说明:本文为 2026-10-13 回溯补生成,内容基于当时(D 前后)的公开报道检索。 📅 2026-08-08 · 版本窗口:2026-08-07(v2.1.224 / v2.1.225)至 08-08(v2.1.226,仅 bug 修复) 场景还原:团队想把内部插件打成 zip 放在制品库里分发,又怕被人中途替换;CI 里的 claude -p 跑着跑着突然 401;沙箱里的 DATABASE_URL 一掩码就连不上库;安全部门要求代码检出不能离开公司网络。这两天的版本正好各补了一块。前置:第 9 课(权限与沙箱)、第 12 课(无头模式与 CI)、第 17 课(插件与 Marketplace)。跨会话 SendMessage(同属 v2.1.224)已在第 13 课讲过,本课不再重复。来源:v2.1.224 Release · v2.1.225 Release · Havoptic 8 月版本表注意:配置写法取自 code.claude.com 当前(2026-10)文档,部分细节可能是 08-08 之后补充的(例如 self-hosted-runner setup 引导);用前先 claude --version 确认 ≥ 2.1.224。

技巧 1(基础):用 `archive` 插件源分发 zip,并用 SHA-256 锁死

解决的问题:插件不在 git / npm 上,只是一个放在内部制品库的 zip;既想不装 git 就能安装,又要防止 zip 被悄悄替换。

v2.1.224 起,marketplace.json 的插件条目可以用 archive 源:只认 https://,不能指向回环 / 链路本地 / 云元数据地址;插件根目录可以在 zip 顶层或下一层。设置 sha256 后,下载内容不匹配就拒绝安装。

# 1) 算出 zip 的摘要(macOS 用 shasum,Linux 也可用 sha256sum)
shasum -a 256 formatter-2.0.0.zip

{
  "name": "formatter",
  "source": {
    "source": "archive",
    "url": "https://artifacts.example.com/formatter-2.0.0.zip",
    "sha256": "6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1"
  }
}

# 2) 每次改完 marketplace.json 先校验,再本地装一遍
claude plugin validate ./my-marketplace
claude plugin install formatter@my-marketplace

要点:每发一个新 zip 就要同步更新 sha256,否则用户装不上——这正是"锁死"的意义。私有制品库需要鉴权时,可用条目级 headers / headersHelper(文档注明需 v2.1.238+,不在本窗口内)。 📖 官方:Marketplace reference · archive · v2.1.224

技巧 2(进阶):无头 token 不再被"顶掉" + Gateway 花费上限看得见

解决的问题:CI 里用长期 CLAUDE_CODE_OAUTH_TOKEN 跑 claude -p,一次偶发 401 后会被本机存的短期登录 token 替换,之后一直失败直到重启;团队网关设了花费上限,但触顶时只看到一句模糊报错。

v2.1.225 修复了前者;后者现在会在用量警告里写明上限值、重置时间和管理员留言(需要网关同样升级到 2.1.225)。另外 claude agents 在未信任目录里也会像 claude 一样先弹工作区信任提示。

# CI 推荐做法:生成长期 token,放进 CI 的 secret,而不是依赖某台机器上的登录态
claude setup-token
export CLAUDE_CODE_OAUTH_TOKEN="<粘贴 secret>"
claude -p "跑一遍单测并总结失败原因" --output-format json

# 确认版本已包含修复
claude --version   # 应 ≥ 2.1.225

要点:如果你的流水线以前靠"出错就重启容器"来绕过 401,升级后可以去掉这个补丁,但建议保留一次重试。 📖 v2.1.225 · 官方:Headless / CI

技巧 3(进阶):沙箱凭据掩码进阶——AWS 成对掩码、结构化值只掩密钥部分

解决的问题:第 7 课讲过 mask 模式(真实密钥不进沙箱,出站时由代理替换)。但 AWS 请求带 SigV4 签名、DATABASE_URL 这类连接串有结构,整串替换后工具就解析不了。

先回顾必需条件:掩码需要 network.tlsTerminate(代理要看见请求内容才能替换),且只在用户设置、托管设置或 --settings 中生效,写在仓库的 .claude/settings.json 里会被忽略。

// ~/.claude/settings.json
{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "*.amazonaws.com"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "AWS_ACCESS_KEY_ID", "mode": "mask" },
        { "name": "AWS_SECRET_ACCESS_KEY", "mode": "mask" }
      ]
    }
  }
}

v2.1.224 新增的几个字段(写法以 settings 参考文档为准): - AWS:把 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 一起掩码,代理会用真实值重签 SigV4;只掩 secret 会导致请求在 AWS 端失败。变量名不是标准名时用 credentials.awsPairs 把它们组成一对;流式上传、预签名 URL、SigV4A 这类代理无法重算签名的请求,用 credentials.sigv4 选择"直接失败"还是"原样转发"。 - 结构化值:环境变量也支持 extract(正则指出哪一段是密钥)和 onExtractNoMatch;JWT 可用 decode: "jwt" + maskClaims 只掩部分 claim。文件掩码的 extract 官方示例:"extract": "oauth_token:\\s*(\\S+)"。

验证方法:让 Claude 在沙箱里 echo $GH_TOKEN,Linux/WSL2 上应只看到哨兵值;再跑一次 gh api user,能正常返回说明出站替换成功。claude doctor 若提示 TLS termination is unavailable,说明掩码没生效。 📖 官方:Sandboxing · Mask credentials · Re-sign AWS requests · v2.1.224

技巧 4(高阶):`claude self-hosted-runner`——让云端会话跑在你自己的机器上

解决的问题:想用 claude.ai/code、手机端、定时任务发起"云端会话",但代码检出、构建产物、内网服务访问都必须留在公司网络里。

自托管环境(Team / Enterprise,公测,默认关闭)由三部分组成:环境(在 claude.ai 管理后台创建)、runner(你部署的进程,类似自托管 CI runner)、会话。runner 只做出站 HTTPS 轮询,Anthropic 不会连进你的网络;但对话内容(提示、回复、工具结果)仍会发往 api.anthropic.com。

# 0) 确认版本(< 2.1.224 不认识这个子命令)
claude self-hosted-runner --help

# 1) 在 claude.ai → Admin settings → Cloud environments → Self-hosted 新建环境,复制"environment key"(只显示一次)
mkdir -p /etc/claude
(umask 077 && cat > /etc/claude/environment-secret)   # 粘贴 → 回车 → Ctrl-D

# 2) 启动 runner
claude self-hosted-runner \
  --environment-secret-file '/etc/claude/environment-secret' \
  --base-dir '/srv/claude-runner'

然后在 claude.ai/code 发起会话时从环境选择器里选你的环境,runner 日志会出现 Picked up session <id>。

要点:① runner 首次接单后会锁定到该会话的所有者,只为这个人服务,所以机器数 ≥ 同时活跃的人数;② 默认会话结束就退出,生产环境要放在 Kubernetes 等会自动重启的编排器下;③ 开启 ZDR 或 HIPAA 配置的组织不可用;④ v2.1.225 修复了 --base-dir 不可写时"先注册再全部失败"的问题,现在会在启动时直接报错退出。 📖 官方:Self-hosted environments · Quickstart · v2.1.224

顺带一提:v2.1.224 移除了"每会话最多 200 个子 agent"的上限(并发与深度限制仍在),长时间运行的会话不会再拒绝新 agent。

今日实操(15 分钟)

找一个你自己的插件目录,打成 zip,放到任意 HTTPS 可访问的位置(内部制品库或私有对象存储)。
在本地 marketplace 里加一个 archive 条目,sha256 填你算出的值,claude plugin validate 后安装。
把 sha256 的最后一位故意改错,再执行一次安装。
验收:第 2 步安装成功、claude plugin list 显示 enabled;第 3 步安装被拒绝(摘要不匹配)。改回正确值后恢复正常。
加分项(Linux/WSL2):按技巧 3 给 GH_TOKEN 开 mask,验收标准是沙箱里 echo $GH_TOKEN 看不到真实值,但 gh api user 仍能返回你的用户名。

技巧 1(基础):用 archive 插件源分发 zip,并用 SHA-256 锁死

技巧 2(进阶):无头 token 不再被"顶掉" + Gateway 花费上限看得见

技巧 3(进阶):沙箱凭据掩码进阶——AWS 成对掩码、结构化值只掩密钥部分

技巧 4(高阶):claude self-hosted-runner——让云端会话跑在你自己的机器上

今日实操(15 分钟)

技巧 1(基础):用 `archive` 插件源分发 zip,并用 SHA-256 锁死

技巧 4(高阶):`claude self-hosted-runner`——让云端会话跑在你自己的机器上