Claude Code SDK #38：Claude Code on the web 全解——Cloud VM × GitHub × --teleport，把任务丢到云端继续跑 (2026)

如果你把 Claude Code on the web 当成「网页版 CLI」，第一步就会用错。

它更像一台临时云端开发机：从 GitHub 拉一份干净仓库，按你配置的环境启动，自己跑测试、改代码、推分支。浏览器只是控制台，不是执行现场。官方 quickstart 的任务流也是这样写的：克隆仓库、准备环境、按环境配置网络、执行任务，最后推分支供你审查。1

01. 先分清三种「远程」

Claude Code 现在有三种容易混在一起的入口：本地 CLI、Remote Control、Claude Code on the web。

入口	代码实际跑在哪里	适合什么任务
本地 CLI	你的机器	依赖本地数据库、内部网络、私有脚本、复杂调试的任务。
Remote Control	仍然是你的机器，只是从网页或手机操控	任务已经在本机跑着，你想换设备继续看、继续发指令。Remote Control 文档明确说，执行和文件访问都留在本地。2
Claude Code on the web	Anthropic 管理的云端 VM	不想占用本机、想并行跑多个任务、或要处理一个本地还没 clone 的 GitHub 仓库。官方 quickstart 把它描述为在 Anthropic 管理的云基础设施上运行，并把结果推到 GitHub 分支。1

这个边界很关键。Remote Control 是「远程看本机」，web 是「另开一台云端工作副本」。前者吃你的本地环境，后者吃仓库和云环境配置。

02. GitHub 接入不是一个按钮那么简单

Web session 需要能 clone 仓库和 push 分支。官方给了两条接入方式：浏览器里授权 Claude GitHub App，或者在终端里用 /web-setup 同步本地 gh CLI token。3

这里有个容易误解的点：安装 GitHub App 主要启用 onboarding 和 PR webhook，例如 Auto-fix；它不是 session 级别的仓库访问边界。文档明确说，云端 session 可以访问连接的 GitHub 账号可见的仓库，而不只限于安装了 App 的仓库。真正要收窄访问范围，应在 GitHub 里控制账号、团队和仓库权限。3

所以团队落地时不要只问「App 装了吗」。更应该问三件事：这个连接账号能看哪些 repo？哪些 repo 允许 Auto-fix webhook？哪些环境变量会暴露给能编辑环境的人？

03. 云端只继承「进仓库的东西」

Cloud session 从一次 fresh clone 开始。仓库里的 CLAUDE.md、.claude/settings.json hooks、.mcp.json、.claude/rules/、.claude/skills/、.claude/agents/、.claude/commands/ 会随仓库进入云端；你电脑上的 ~/.claude/CLAUDE.md、用户级 skills、用户级 agents、用户级 commands、只在本机添加的 MCP server 不会自动过去。3

这会直接改变工程习惯。很多人本地 Claude Code 跑得顺，是因为本机藏了大量「个人外挂」：shell alias、本地 MCP、用户级 instructions、全局 commands。到了 web，这些都不算数。你要么把稳定规则提交到 repo 的 .claude/ 目录，要么把它们当成本地专属能力，不要指望云端 session 自动复现。

环境变量也要谨慎。官方文档说，目前没有专用 secrets store；环境变量和 setup script 都存在环境配置里，能编辑这个环境的人可以看到它们。3 这意味着云端环境适合放 scoped token，不适合塞一个权限过大的长期密钥。

04. Setup script 管「云机器」，SessionStart hook 管「项目启动」

Web session 有两层启动逻辑。

第一层是环境里的 setup script。它在 Claude Code 启动前执行，跑在 Ubuntu 24.04 上，可以用来安装云 VM 没有的系统工具，比如 gh。脚本第一次成功后会被缓存，后续新 session 直接复用快照；缓存保存文件，不保存正在运行的服务。官方也提醒，setup script 最好控制在约五分钟内，否则可能拖慢或阻塞环境构建。3

第二层是 repo 里的 SessionStart hook。它属于项目配置，cloud 和 local 都会执行。官方示例用 CLAUDE_CODE_REMOTE 区分云端，只在 cloud session 里安装依赖。3

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/install_pkgs.sh"
          }
        ]
      }
    ]
  }
}

一个实用分工是：setup script 装系统级工具和大依赖，SessionStart hook 做项目级准备。比如 apt install gh 放 setup；npm install 或 pip install -r requirements.txt 放 hook，并在脚本里判断 CLAUDE_CODE_REMOTE。这样本地不会被云端逻辑打扰，云端也能在每次启动时补齐项目依赖。

05. 网络访问是一道工程边界，不是开关装饰

每个 cloud environment 都有一个 network access level：None、Trusted、Full 或 Custom。Trusted 是默认值，只允许包管理器、GitHub、云 SDK、容器 registry 等白名单域名；Custom 可以自己列域名，还能选择是否同时包含默认列表。3

这会影响依赖安装、Docker 镜像拉取、外部 API 调用，也会影响你写 prompt 的方式。让 Claude 「顺手查一下线上接口」之前，先确认环境允许访问那个域名。否则它不是不会写代码，而是 VM 根本出不去。

GitHub 又是单独一条链路。文档说 GitHub 操作走专门的 proxy，sandbox 里用 scoped credential，proxy 再映射到真实 GitHub token，并把 git push 限制在当前工作分支。3 这也是为什么 web 适合「开分支做任务」，不适合让它拿着一个万能 token 到处写。

06. `--cloud` 是发新任务，`--teleport` 是接回任务

终端里可以直接发云端任务：

claude --cloud "Fix the authentication bug in src/auth/login.ts"

--cloud 会基于当前目录的 GitHub remote 和当前分支创建新的 cloud session。VM 是从 GitHub clone，不是从你的硬盘复制，所以有本地 commit 就先 push。官方还说明，老的 --remote 拼法仍可用，但已经是 --cloud 的 deprecated alias。3

如果当前 repo 没有 GitHub 连接，Claude Code 会把本地 git 仓库打包上传到 cloud session。这个 fallback 包含完整 git 历史和 tracked 文件里的未提交改动，但不包含 untracked 文件；bundle 需要小于 100 MB，超过后会逐级降级到当前分支或工作树快照。没有 GitHub 认证时，这类 session 也不能把结果 push 回 remote。3

--teleport 则是反方向：把一个 cloud session 拉回本地 terminal。它会检查你是否在同一个 repo、工作区是否干净、云端分支是否已经 push、账号是否一致，然后把分支和完整对话历史接进本地 CLI。官方也强调，--teleport 不等于 --resume：前者拉云端 session，后者只恢复本机历史。3

07. Auto-fix 很强，但要先看仓库里的自动化

Web session 可以打开 Auto-fix。开启后，Claude 会订阅 PR 上的 GitHub 活动；遇到 CI 失败或 review comment，它会调查并在有清晰修复路径时推新改动。Auto-fix 需要 Claude GitHub App 安装在对应仓库。3

这里不要太激进。官方文档写得很直：如果仓库里有依赖 issue_comment 触发的自动化，比如 Atlantis、Terraform Cloud 或自定义 GitHub Actions，Claude 替你回复 comment 可能会触发这些 workflow。3

我的建议是先把 Auto-fix 用在普通应用代码 PR 上：测试失败、lint 失败、reviewer 要求改一个函数名，这些都适合。基础设施仓库、部署 comment 能触发动作的仓库，先关掉，或者把触发词和权限规则收紧后再开。

08. 它适合什么，不适合什么

适合 web 的任务有四类：并行小改动、可从 GitHub 完整复现的 bug、文档和测试维护、代码阅读和定位。官方 quickstart 也把 parallel tasks、没有本地 checkout 的 repo、低频 steering 任务和代码探索列为典型场景。1

不适合 web 的任务也很明确：依赖本地私有配置、要连公司内网、需要你机器上的交互式认证、或者超过云端资源上限的任务。官方 reference 给出的近似资源上限是 4 vCPU、16 GB RAM、30 GB disk；更重的构建和测试，应该回到 Remote Control，在自己的硬件上跑。3

还有一个组织层面的坑：如果公司开了 IP allowlist，cloud session 从 Anthropic 管理的基础设施访问 API，不会来自你的公司网络。官方限制说明里说，这种情况下 cloud session 会认证失败，Code Review 和 Routines 也同样受影响。3

今天可以直接落地的配置清单

把团队稳定规则放进仓库：CLAUDE.md、.claude/settings.json、.mcp.json、.claude/skills/，不要依赖个人 ~/.claude/。
给 web 单独建一个环境，默认用 Trusted 网络访问；只有任务需要时，再用 Custom 加具体域名。
setup script 只装云 VM 缺的系统工具，控制在约五分钟内；项目依赖交给 SessionStart hook，并用 CLAUDE_CODE_REMOTE 避免影响本地。
用 --cloud 跑低耦合任务前，先 push 本地 commit；需要接回本地继续调试时，再用 --teleport。
Auto-fix 先在普通应用仓库试水；凡是 PR comment 能触发部署、基础设施变更或高权限 automation 的仓库，先别开。

如果一句话概括：Claude Code on the web 不是把你的本地 Claude 搬进浏览器，而是给每个任务开一台可丢弃、可审查、能推分支的云端开发机。用得好，它负责并行执行；用错了，它会暴露你本地环境从来没有被工程化过。

Claude Code SDK #38：Claude Code on the web 全解——Cloud VM × GitHub × --teleport，把任务丢到云端继续跑