自建 runner 要改用 system-prompt 文件
Claude Code 2.1.281 让自建 runner 用私有文件把系统提示交给进程,不再放在命令行。仍在 command 钩子里追加 --system-prompt 或 --append-system-prompt 的包装脚本,要改成对应的 file 参数。

Claude Code 2.1.281 改了自建 runner 传递系统提示的方式。发行说明写:系统提示改为私有文件交给 Claude Code,不再作为命令行文本,这样很长的提示不会把启动撑失败。包装脚本或 command 钩子如果还在追加 --system-prompt 或 --append-system-prompt,必须改成 --system-prompt-file 或 --append-system-prompt-file。claude code system-prompt-file 是这次迁移的参数名。
谁需要改
主语是 self-hosted runners,以及会往启动命令上追加系统提示的包装或钩子。普通终端里手打 claude、不包一层脚本的人,发行说明没有要求改命令。云端会话和 Claude Desktop 也不在这句里。
失败形态写的是 large prompts no longer fail the launch。升级之后,仍把长提示塞进命令行参数的包装,会走旧路径,说明预期它们要换参数,而不是自动兼容。文件内容是否还会出现在进程列表里,说明只说了「私有文件」和「不再是命令行文本」,没有写文件权限位。落地时把该文件的权限收在运行用户可读,不要提交进仓库。
和网关、桌面策略不是同一份配置
2.1.281 同时给 Claude apps gateway 加了 Bedrock 的 assume_role 和 guardrail,以及桌面策略里的 blockReadsOutsideWorkingDirectories、disableBypassPermissionsMode。那些是网关或桌面策略键。--system-prompt-file 是 runner 启动参数。三套名字不要写进同一个「升级清单」然后只改其中一处。
同一段还写:网关在 managedMcpServers 的 envHelper 路径以 \??\ 或 /??/ 开头时拒绝启动,因为当前 Claude Desktop 拒绝执行这种路径形式。这是网关启动检查。它解释不了系统提示参数为什么失效。
升到 2.1.281 之后,先在测试 runner 上把钩子改成 file 参数,用一份短提示确认会话能起来,再换上生产用的长提示。命令行里还留着 --system-prompt 时,不要假设新参数会覆盖它。说明要求的是 switch,也就是换过去。