Claude Agent SDK：1M 上下文和沙箱

把 Claude Code 嵌进自己的产品，用的是 Claude Agent SDK：同一套工具循环、同一套权限和会话，Python / TypeScript 都能调。上下文只有 200K 时，长会话很快就要 compact，细节被摘要吃掉；Bash 不隔离时，你又不敢把权限放开。1M 窗口和沙箱就是冲着这两件事来的。

本文按 2026 年 8 月的官方文档和 SDK 类型来写。站内已经有过 Agent SDK 总览和给编码代理一个 Docker 沙箱，这里只谈 SDK 自己的 1M 上下文和 Bash 沙箱，不重复那两篇。

先分清三套「沙箱」

名字容易混，别装错：

Agent SDK / Claude Code 的 Bash 沙箱：在本机用 Linux bubblewrap 或 macOS seatbelt 隔离命令，不另起容器。本文讲这个。
Managed Agents 的环境沙箱：Anthropic 托管的 Linux 容器，会话结束就扔。那是另一套产品。
Docker sbx：给代理单独一台 microVM。站内那篇讲的是它。

文件系统和网络限制也不写在 sandbox 对象里。读用 Read 的 deny 规则，写用 Edit 的 allow/deny，出网用 WebFetch 的 allow/deny。sandbox 只管「Bash 要不要进隔离、进不去怎么办」。

1M 上下文现在怎么开

2026 年 3 月 13 日，Opus 4.6 和 Sonnet 4.6 的 1M 窗口转正：全窗口按标准价计费，没有长上下文溢价，也不再需要 context-1m-2025-08-07 这个 beta 头。请求超过 200K 会自动走 1M。后面的 Opus 4.7 / 4.8 / 5、Sonnet 5 也是默认 1M。

旧的 Sonnet 4 / 4.5 曾经靠那个 beta 头扩到 1M。这个 beta 已经退役：头发了也没用，超 200K 直接报错。还停在 4 / 4.5 上的，迁到 4.6 及以上。

Agent SDK 这边有一点别扭。平台文档说 4.6 不用 beta 头，但不少 SDK 版本不带 [1m] 后缀时，modelUsage.contextWindow 仍报 200000，长会话会在大约 175K 到 180K 处撞 Prompt is too long。社区里能稳定打开的写法是模型名加后缀，或显式传 betas。

Python：

python

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    model="claude-opus-4-6[1m]",
    system_prompt={"type": "preset", "preset": "claude_code"},
)

async for message in query(prompt="把仓库里的 API 约定和最近的失败日志对上", options=options):
    print(message)

TypeScript：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "把仓库里的 API 约定和最近的失败日志对上",
  options: {
    model: "claude-opus-4-6[1m]",
    systemPrompt: { type: "preset", preset: "claude_code" },
  },
})) {
  console.log(message);
}

[1m] 是 CLI / SDK 用来打开 1M 窗口的约定，不是模型正式 ID。换模型时后缀跟着写，比如 claude-sonnet-4-6[1m]。旧版本也可以传 betas: ["context-1m-2025-08-07"]。

Max / Team / Enterprise 在 Claude Code 里用 Opus 4.6，会话会默认走 1M，compact 会少很多。SDK 没有「登录套餐自动扩窗」这一说，还是要自己把模型名或 betas 写对。

怎么确认真的开了

只看 /context 不够。早期 CLI 开了 1M 仍显示 200000，维护者确认过这是显示 bug，以初始化消息里的 betas 为准。

更稳的是读 SDK 自己报的窗口。会话开始后调用 get_context_usage()，看 rawMaxTokens、maxTokens 和 model。一轮结束的 ResultMessage 里，model_usage 对应模型那一项也有 contextWindow。

rawMaxTokens 应接近 1000000。如果仍是 200000，先检查模型名有没有 [1m]，再看用的是不是已经退役 1M beta 的旧 Sonnet。

1M 的意义很具体：一次请求能装下整仓、长工具轨迹、几百页 PDF。Claude Code 搜日志和源码时动辄烧掉 10 万 token，200K 窗口很快就要摘要，修 bug 会在摘要里打转。窗口拉到 1M 之后，少 compact、少丢跨文件依赖，是最直接的收益。

媒体上限也跟着放开：一次请求最多 600 张图或 PDF 页（以前 100）。走 Claude Platform、Vertex AI、Microsoft Foundry 都可以。

沙箱怎么开

Bash 沙箱默认关。打开之后，命令在隔离里跑，当前工作目录可读写，目录外的修改被挡住；出网走沙箱外的代理，按域名放行。Anthropic 自己用下来，权限弹窗少了大约 84%。实现是 OS 原语，子进程也出不去。

Python 里给 ClaudeAgentOptions 传 sandbox 字典即可：enabled 设为 True，并把出网域名写进 network.allowedDomains。TypeScript 字段名一样。

几个容易踩的开关：

enabled：只在 macOS / Linux 生效。
autoAllowBashIfSandboxed：默认 true。进了沙箱的 Bash 不再逐条问你，越界才会弹。
excludedCommands：这些命令在沙箱外跑。git 常要写在这里。
allowUnsandboxedCommands：默认 true。生产里建议设成 false。
failIfUnavailable：enabled 为 true 时 SDK 默认 fail closed，依赖没装好就直接失败。
enableWeakerNestedSandbox：嵌套环境才用，默认关。

出网白名单要自己列。装依赖就写上对应的包仓库域名。

开源运行时：https://github.com/anthropic-experimental/sandbox-runtime

一份能跑的最小组合

两件事一起开：窗口够长，命令被关住。模型用 claude-opus-4-6[1m]，system_prompt 用 claude_code 预设，sandbox.enabled 打开，allowUnsandboxedCommands 关掉，max_turns 先设 30。cwd 指到你的仓库。

先用一个小仓库试：看 get_context_usage() 的 rawMaxTokens 是不是百万级，再确认工作目录以外的访问被挡住。这两步过了，再把 max_turns 和出网名单放开。

常见坑

SDK 版本和模型版本要对上。 Python 包 claude-agent-sdk、TS 包 @anthropic-ai/claude-agent-sdk 都捆绑一份 Claude Code CLI。旧 CLI 不认 [1m]，也不认现在的 sandbox 字段。先把包升到当前主线，再查对应 CLI 的 changelog。

1M 不是无限。 输出上限仍是模型自己的 max_tokens（新模型一般到 128K）。任务预算用 task_budget，美元预算用 max_budget_usd。窗口大了，一次请求更贵，也更容易把缓存前缀打穿。能缓存的系统提示就固定下来，动态的工作目录、git 状态用 exclude_dynamic_sections 挪到第一条用户消息。

沙箱挡不住已经进上下文的内容。 它挡的是进程能碰哪些路径、能连哪些主机。敏感材料不要写进会被读进上下文的文件。

权限回调和沙箱是两层。 can_use_tool 只处理规则判定为 ask 的调用。allowed_tools 里的整工具名、bypassPermissions 会绕过回调。要拦每一次工具调用，用 PreToolUse hook。

字节笔记本