Claude Code 深度学习手册

主题

Claude Code on the Web ​

在 Anthropic 托管云端 VM 里跑 Claude Code 任务的网页版，会话持久、可移动端监控，能与本地终端用 --remote / --teleport 双向接力。

你的真实情况 ​

从你的命令历史看不到网页版痕迹（没用过 /web-setup、--remote、/teleport 等），即你目前在本地 CLI 干活，没用 Claude Code on the web。

什么时候它对你有用（要用才看）：

  • 长任务挂云端：你那些 /qa、ralph-loop、大审计想"丢了去忙别的、回头收 PR"——web 在 Anthropic 云 VM 跑，关机也继续。
  • 手机上看进度/续接：配 Remote Control 从手机接本地会话，或直接用云会话。
  • 前提：要连 GitHub 仓库。你这个工作项目根目前不是 git 仓库（会话启动时检测为 not a git repository），web 走 GitHub clone，用它前得先把代码放到 GitHub。

注意：开了 Zero Data Retention 的组织用不了 web；你单人订阅不受此限，但"需要本地配置/工具"与"仓库要在 GitHub"是它对你的短板。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

Claude Code on the web 在 Anthropic 托管的云端基础设施上运行任务，入口是 claude.ai/code。每个会话跑在一台全新的 Anthropic-managed VM 里，并已 clone 你的仓库。会话即使关闭浏览器也会持续运行，可从 Claude mobile app 监控。它目前处于 research preview 阶段，仅对 Pro、Max、Team 用户，以及拥有 premium seats 或 Chat + Claude Code seats 的 Enterprise 用户开放。它与本地 CLI 可双向接力：用 --remote 从终端发起云会话，用 --teleport 把云会话拉回终端继续。

怎么工作 ​

  • 每个会话在一台隔离的 Anthropic-managed VM 中启动，从 GitHub 上 clone 仓库（不是从你的机器拷贝）。仓库里 commit 进去的东西（CLAUDE.md、.claude/settings.json hooks、.mcp.json、.claude/rules/、.claude/skills|agents|commands/、settings.json 里声明的 plugins）才可用；只在本机配置的（~/.claude/CLAUDE.md、claude mcp add 加的 server、user-scoped enabledPlugins、静态密钥、AWS SSO 等交互式 auth）不可用。
  • GitHub 接入两种方式：(1) 授权 Claude GitHub App（onboarding 走浏览器，且 Auto-fix 必须用它接收 PR webhook）；(2) 在终端跑 /web-setup，把本地 gh CLI token 同步到 Claude 账号。无论哪种，云会话能访问该 GitHub 账号可见的任意仓库——App 安装与否不是会话级访问控制，要限制得在 GitHub 侧限制成员/仓库访问。
  • 所有 git 操作走专用 GitHub proxy：sandbox 内的 git client 用一个 scoped credential，由 proxy 校验并翻译成你真实的 GitHub token，token 永不进入容器；git push 被限制只能推当前工作分支。
  • 所有出站流量走一个 HTTP/HTTPS security proxy（防滥用、限流、内容过滤）。网络访问分级 None / Trusted（默认，仅放行 allowlist 域名）/ Full / Custom。MCP connector 流量经 Anthropic 服务器中转，不需要把其 host 加进 Allowed domains。
  • setup script 在新会话启动、Claude Code 启动之前以 root 跑（Ubuntu 24.04）。首次跑完后 Anthropic 对文件系统做 snapshot 缓存，后续会话直接用快照、跳过 setup script。改 setup script、改 allowed hosts、或缓存到期（约 7 天）会重跑；resume 已有会话永不重跑。缓存只存文件不存运行中的进程。
  • --remote 在 claude.ai 新建云会话，clone 当前目录的 GitHub remote 的当前分支（有本地 commit 要先 push）。非 GitHub 仓库会自动 bundle 上传（含全分支历史 + 已跟踪文件的未提交改动）。--teleport 把云会话及其分支拉回本地终端，校验仓库一致、fetch 并 checkout 分支、载入完整对话历史。
  • Auto-fix：Claude 订阅 PR 的 GitHub 事件，CI 失败或有 review comment 时自行调查；明确的修复直接改并 push，含糊或架构级的会先问你，重复/无需动作的记录后跳过。需安装 Claude GitHub App。

怎么配置 / 用法 ​

入口：claude.ai/code；管理后台开关 claude.ai/admin-settings/claude-code（Team/Enterprise admin 可关 /web-setup 的 Quick web setup toggle）。

环境变量用 .env 格式，一行一个 KEY=value，不要加引号（引号会被存进值里）： NODE_ENV=development LOG_LEVEL=debug DATABASE_URL=postgres://localhost:5432/myapp

setup script（环境设置对话框 Setup script 字段，root/Ubuntu 24.04）： #!/bin/bash apt update && apt install -y gh

只在云端装依赖（repo 的 .claude/settings.json 加 SessionStart hook，靠 CLAUDE_CODE_REMOTE 判断）： { "hooks": { "SessionStart": [ { "matcher": "startup|resume", "hooks": [ { "type": "command", "command": ""$CLAUDE_PROJECT_DIR"/scripts/install_pkgs.sh" } ] } ] } } 脚本里：if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then exit 0; fi

终端命令：claude --remote "..."（新建云会话）；claude --teleport [session-id]（拉回，含 picker）；CLI 内 /teleport 或 /tp；/tasks 里按 t teleport；/web-setup 同步 gh token；/remote-env 设 --remote 默认环境；/autofix-pr 在 PR 分支上开 auto-fix；/compact、/context 可用。

打印本会话 transcript URL： echo "https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID/#cse_/session_}"

强制 bundle 上传：CCR_FORCE_BUNDLE=1 claude --remote "..." 提前压缩：CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70；开 agent teams：CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

什么时候用 ​

  • 适合：autonomous 长任务、并行多任务（每条 --remote 独立云会话同时跑）、关掉笔记本也要继续的任务、想用移动端监控。
  • 适合 plan locally / execute remotely：本地 claude --permission-mode plan 定方案、commit+push 后 claude --remote "Execute the migration plan in docs/migration-plan.md"。
  • 适合让 Claude 盯 PR 自动修 CI/评论（Auto-fix），或定时/事件触发（/schedule、Routines）。
  • 别用：需要超过 4 vCPU / 16GB RAM / 30GB disk 的大型 build 或内存密集测试——改用 Remote Control 在自有硬件上跑。
  • 别用：开了 Zero Data Retention 的组织（无法用 /web-setup 及云会话功能）；开了组织级 IP allowlist 且未豁免 Anthropic 服务的（每个云会话会认证失败）。
  • 别指望把已有终端会话推到 web——CLI 侧 handoff 是单向的（只能 --teleport 拉回；推到 web 需用 Desktop app 的 Continue in 菜单或 --remote 新建）。

限制 / 坑 ​

  • research preview：仅 Pro/Max/Team 及有 premium seats 或 Chat + Claude Code seats 的 Enterprise。
  • 资源上限（近似，可能变化）：4 vCPUs、16 GB RAM、30 GB disk；超限任务可能失败或被终止。
  • Rate limits 与账号下所有 Claude/Claude Code 用量共享，并行越多消耗越快；云 VM 没有单独的算力计费。
  • 没有专用 secrets store；环境变量和 setup script 都存在环境配置里，凡能编辑该环境的人都看得到——放密钥要考虑这点。
  • setup script 退出非 0 会导致会话启动失败（非关键命令追加 || true）；总运行时间要控制在约 5 分钟内否则缓存建不起来；超 5 分钟的单个下载要挪到后台跑的 SessionStart hook。
  • gh CLI 未预装；需要时在 setup script 里 apt install -y gh 并配 GH_TOKEN 环境变量。
  • Bun 已装但与 proxy 有已知的包拉取兼容性问题；部分包管理器对 security proxy 不兼容。
  • SessionStart hook 不能只在云端跑（本地也会触发，要靠 CLAUDE_CODE_REMOTE 判断）；每次启动/resume 都跑、不享受环境缓存，会增加启动延迟。
  • 不支持换自己的 base Docker image；只能在提供的 image 上用 setup script 加东西，或 docker compose 起容器。
  • 云会话里 /model、/config 等会开交互式 picker 的命令不可用；/clear 不可用（去 sidebar 新建会话）。
  • 平台限制：clone 仓库和创建 PR 需要 GitHub；GitLab/Bitbucket/非 GitHub 仓库可作为 local bundle 送上去但无法 push 回 remote；GitHub Enterprise Server 仅 Team/Enterprise 支持。
  • bundle 上传限制：必须是至少有一个 commit 的 git 仓库；需 < 100 MB（超了先退化为只 bundle 当前分支、再退化为单个 squashed 工作树快照，仍太大才失败）；未跟踪文件不含（需 git add）；从 bundle 建的会话除非另配 GitHub auth 否则不能 push。
  • teleport 前置：git 工作区干净（否则提示 stash）、同一仓库（非 fork）的 checkout、分支已 push 到 remote、同一 claude.ai 账号；用 API key/Bedrock/Vertex AI/Microsoft Foundry 认证时 --teleport 不可用，需 /login 切回 claude.ai 账号。
  • 网络关到 None 时 setup script 和装包的 SessionStart hook 都会失败；即便网络 disabled，Claude Code 仍能与 Anthropic API 通信，数据可能借此离开 VM。
  • Auto-fix 的回复用你的 GitHub 账号发（标注来自 Claude Code），可能触发 issue_comment 事件驱动的自动化（如 Atlantis、Terraform Cloud），有部署/特权操作风险的仓库应慎用。
  • 会话闲置一段时间后停止、底层环境被回收（本地报 Could not resume session ... its environment has expired，web 标记 expired）；重开会恢复对话历史并新建环境。

硬事实速查（33 条） ​

  • 入口 URL：claude.ai/code（即 https://claude.ai/code）。
  • 可用对象：Pro、Max、Team 用户；Enterprise 需 premium seats 或 Chat + Claude Code seats。
  • 会话 VM 操作系统：Ubuntu 24.04；setup script 以 root 运行。
  • 资源上限：4 vCPUs / 16 GB RAM / 30 GB disk（近似）。
  • 环境缓存约 7 天到期；setup script 总时长建议 < 约 5 分钟。
  • GitHub 接入：Claude GitHub App（https://github.com/apps/claude）或终端 /web-setup（同步 gh token）。
  • Auto-fix 必须装 Claude GitHub App（用于接收 PR webhook）。
  • Admin 开关：claude.ai/admin-settings/claude-code 的 Quick web setup toggle 可禁用 /web-setup。
  • 预装语言/工具：Python 3.x（pip/poetry/uv/black/mypy/pytest/ruff）；Node.js 20、21、22 via nvm（npm/yarn/pnpm/bun/eslint/prettier/chromedriver）；Ruby 3.1/3.2/3.3（gem/bundler/rbenv）；PHP 8.4 + Composer；Java OpenJDK 21 + Maven/Gradle；Go latest stable；Rust rustc/cargo；C/C++ GCC/Clang/cmake/ninja/conan；Docker（docker/dockerd/docker compose）。
  • 预装数据库：PostgreSQL 16、Redis 7.0（默认不运行，需 service postgresql start / service redis-server start）。
  • 预装工具：git、jq、yq、ripgrep、tmux、vim、nano。
  • 查精确版本：在云会话里跑 check-tools（该命令只存在于云会话）。
  • gh CLI 未预装；自装需 apt install -y gh + GH_TOKEN 环境变量（gh 自动读 GH_TOKEN，无需 gh auth login）。
  • 会话 ID 环境变量：CLAUDE_CODE_REMOTE_SESSION_ID，值带 cse_ 前缀；transcript URL 路径用 session_ 前缀（需替换前缀）。
  • 云会话标记环境变量：CLAUDE_CODE_REMOTE=true。
  • 环境变量文件（SessionStart hook 持久化变量）：写入 $CLAUDE_ENV_FILE；hook command 用 $CLAUDE_PROJECT_DIR。
  • --remote：新建云会话，clone 当前目录 GitHub remote 的当前分支，一次只作用于单仓库。
  • CCR_FORCE_BUNDLE=1：即使连了 GitHub 也强制 bundle 上传本地仓库。
  • bundle 上限 100 MB；超限退化顺序：当前分支 → 单个 squashed 工作树快照 → 失败。
  • --teleport / /teleport / /tp：把云会话拉回终端；/tasks 里按 t；web 界面 Open in CLI。
  • --teleport ≠ --resume（后者只读本机本地历史，不列云会话）。
  • --remote ≠ --remote-control（后者是把本地 CLI 会话暴露给 web 监控，见 Remote Control）。
  • 网络访问级别：None / Trusted（默认）/ Full / Custom；Custom 用 *. 通配子域，可勾选 Also include default list of common package managers。
  • Trusted 默认放行 Anthropic：api.anthropic.com、statsig.anthropic.com、docs.claude.com、platform.claude.com、code.claude.com、claude.ai；含 github.com、api.github.com、gitlab.com、bitbucket.org、Docker Hub、各大包注册中心（npm/PyPI/RubyGems/crates.io 等）。
  • GitHub proxy 独立于网络访问级别；限制 git push 只能推当前工作分支。
  • 上下文：/compact 与 /context 可用（/compact 支持焦点指令如 /compact keep the test output）；/clear 不可用。
  • CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 默认约 95% 触发，可设 70；另有 CLAUDE_CODE_AUTO_COMPACT_WINDOW；agent teams 默认关，CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 开启。
  • 共享可见性：Enterprise/Team 为 Private/Team（默认开仓库访问校验，Claude in Slack 会话自动 Team 可见）；Max/Pro 为 Private/Public（默认不开仓库访问校验），设置在 Settings > Claude Code > Sharing settings。
  • diff 指示器形如 +42 -18，可在 diff 视图留 inline 评论随下条消息发给 Claude。
  • Auto-fix 是 per-PR toggle；终端 /autofix-pr 在 PR 分支上一步开启（用 gh 检测 open PR、spawn web 会话）。
  • 故障排查：Session creation failed 查 status.claude.com；Remote Control session expired / Access denied 跑 /login 刷新；环境过期重开会话恢复历史。
  • Zero Data Retention 组织不能用 /web-setup 及云会话功能；开了 IP allowlist 的组织云会话会认证失败（Code Review、Routines 同理），需联系 Anthropic support 豁免。
  • Desktop app 的 Continue in 菜单可把本地会话送到 web；CLI 侧 handoff 单向（只能拉回）。

官方出处：https://code.claude.com/docs/en/claude-code-on-the-web