# claude-env **Repository Path**: Arcment/claude-env ## Basic Information - **Project Name**: claude-env - **Description**: A focused workspace for Claude Code on Linux and macOS. - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-05 - **Last Updated**: 2026-11-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Claude Env [English](README.md) | 简体中文 为 Linux 和 macOS 上的 Claude Code 提供专用工作环境。 Claude Env 在独立的文件、进程和网络环境中启动官方 Claude Code CLI。你选择一个项目目录作为 workspace,再选择一个 profile 保存登录与偏好;启动器将它们挂载到环境中,并通过你提供的 HTTP CONNECT 代理访问外网。 如果你希望让 Claude Code 访问指定项目、将它的用户数据与宿主日常账户分开,或在多个项目中复用同一份登录和技能,可以从这里开始。在 Linux 上,还可以打开一个运行于沙箱内的独立 VS Code 窗口,使用官方 Claude Code 插件。 Linux 使用 Bubblewrap 和原生命名空间;macOS 在此基础上增加专用的 Lima/VZ Linux 虚拟机,因此其中的命令运行于 Linux。这个项目提供环境启动器,使用 Claude 仍需你自己的账号和相应服务。 - [支持的平台](#支持的平台) - [开始使用](#开始使用) - [日常命令](#日常命令) - [在 Linux 上清理本地聊天](#在-linux-上清理本地聊天) - [在 Linux 上恢复多个聊天](#在-linux-上恢复多个聊天) - [同步网页端的整理操作](#同步网页端的整理操作) - [理解 profile、workspace 与可见路径](#理解-profileworkspace-与可见路径) - [在 Linux 上使用 VS Code](#在-linux-上使用-vs-code) - [代理、时区和语言](#代理时区和语言) - [管理 macOS 虚拟机](#管理-macos-虚拟机) - [隔离如何工作](#隔离如何工作) - [检查与排障](#检查与排障) - [运行时版本与更新](#运行时版本与更新) ## 支持的平台 | 宿主平台 | 工作环境 | 本仓库已有的验证记录 | |---|---|---| | Linux x86_64 | 原生 Bubblewrap 沙箱 | 已在实体宿主测试 | | macOS Apple Silicon | 专用 VZ 虚拟机,运行 Linux ARM64 | 已在 MacBook 测试 | | Linux ARM64 | 相同 Linux 后端,使用 ARM64 二进制 | 已在 Mac 的 Debian ARM64 guest 中测试 | | macOS Intel | 已提供 x86_64 Lima、镜像与 CLI 配置 | 尚未进行实体宿主验证 | | Windows | 尚无宿主适配器 | 暂不支持直接运行 | 可选的 VS Code 集成需要 **Linux Wayland 会话**。macOS 适配器目前提供 CLI 和 shell 工作方式。 ## 开始使用 ### 1. 准备宿主环境 Linux 需要支持 `memfd` 的系统 Python 3.9+、Bubblewrap、util-linux、iproute2、curl、libseccomp、locale 源文件、`localedef` 和 tzdata,并且允许非特权 user namespace、提供 `/dev/net/tun`。 Debian/Ubuntu 通常可通过以下软件包准备依赖: ```bash sudo apt-get update sudo apt-get install python3 bubblewrap util-linux iproute2 curl libseccomp2 locales tzdata ca-certificates ``` macOS 需要 macOS 13.5+、硬件虚拟化、位于 `/usr/bin/python3` 的 Python 3.9+、curl 和 SSH。安装器会下载私有 Lima 运行时和 Debian 镜像,无需 Homebrew 或 Docker Desktop。准备 guest 依赖时只在专用 VM 内使用 `sudo`,不需要宿主 `sudo`。已有实体宿主验证使用 macOS 26.7.2 / Apple Silicon。 ### 2. 下载并安装 克隆仓库,并设置本机可用的 HTTP CONNECT 代理。将示例端口替换为你的代理端口: ```bash git clone https://gitee.com/Arcment/claude-env.git cd claude-env export https_proxy=http://127.0.0.1:2080 export CLAUDE_ENV_PROXY="$https_proxy" /usr/bin/python3 setup.py ``` `https_proxy` 供 Linux 安装器下载时使用,`CLAUDE_ENV_PROXY` 明确选择启动器的上游代理。在 macOS 上,也可以使用已启用的系统 HTTP/HTTPS 代理,不设置上述变量。 安装器将固定版本的运行时下载并校验到 `.runtime/`,不会替换系统程序。macOS 第一次启动还会创建 VM 并安装 guest 依赖,可能需要几分钟。 ### 3. 打开第一个 workspace 可以先在仓库内创建一个小型工作区,熟悉环境: ```bash mkdir -p workspace ./claude-env run --workspace "$PWD/workspace" ``` 开始实际工作时,将路径替换为已有的项目目录: ```bash ./claude-env run --workspace /absolute/path/to/your-project ``` 项目目录以可读写方式挂载,环境内编辑会直接改变宿主文件。建议选择能完成任务的最小项目目录;它的所有子目录也会开放。启动器会拒绝自身仓库根目录、私有运行时目录和若干范围过大的路径。 默认 profile 为 `default`。首次使用请在环境内登录;启动器不会导入宿主的 Claude 登录、API Key 或 SSH 密钥。如果无法自动打开浏览器,将授权链接复制到宿主浏览器,再按 Claude Code 的提示完成登录。 如果 Linux 提示 user namespace 权限错误,请查看 [AppArmor 与 SSH 启动](#apparmor-与-ssh-启动)。 ## 日常命令 以下命令在仓库目录中执行。也可以在其他目录使用启动器的绝对路径。 | 任务 | 命令 | |---|---| | 启动 Claude Code | `./claude-env run --workspace /path/to/project` | | 继续该项目的会话 | `./claude-env run --workspace /path/to/project -- --continue` | | 进入交互终端 | `./claude-env shell --workspace /path/to/project` | | 在环境内执行命令 | `./claude-env exec --workspace /path/to/project -- /usr/bin/python3 --version` | | 使用独立登录与偏好 | `./claude-env run --workspace /path/to/project --profile work` | | 检查工作环境 | `./claude-env check --workspace /path/to/project` | `--` 后的参数传给 Claude Code;在 `exec` 模式中则是要运行的程序及其参数。进入交互终端后,可运行 `claude`,使用 `exit` 离开。退出后项目修改和 profile 数据都会保留。 终端中的 `#` 表示 user namespace 内的 UID 0。它在 Linux 上映射到宿主普通用户,在 macOS 上映射到 VM 普通用户;Linux capabilities 已被移除。 ## 在 Linux 上清理本地聊天 只想挑选要保留的聊天时,无需启动 Claude 或连接账号。运行下列命令查看标题、UUID 和 fork 的父会话;进入 `trash` 后可以输入一个或多个列表编号,直接回车取消。 ```bash ./claude-env sessions my-project list ./claude-env sessions my-project trash ./claude-env sessions my-project bin ./claude-env sessions my-project undo ``` 也可以先用 `list --find 关键词` 搜索,再用 `trash UUID前缀 --dry-run` 预览。去掉 `--dry-run` 才执行。支持多个完整 UUID、至少 8 位的唯一 UUID 前缀或精确标题;重名时请用 UUID。支持 `--profile`、`--json` 和 workspace 绝对路径。 - **workspace 离线:** 将选中会话的主 `.jsonl` 和同名 UUID 目录(若有,含该会话的子代理记录等)移入本地回收站。独立 fork、项目文件、memory、原生 job 登记和远端列表均保留。 - **workspace 正在使用:** 标为 `pending`,托管会话从后续恢复中排除,当前进程继续运行。workspace 空闲后可运行 `./claude-env sessions my-project apply`,也可等下一次 `start_cc` 启动时自动处理。无需专门停止环境。 - **撤销:** `bin` 查看回收站;`undo` 取消待清理项或原位还原文件。若原位置已出现新文件会拒绝覆盖。还原不会启动会话,已排除的聊天仍保持排除;需要继续时用 `./start_cc my-project --session 完整UUID` 单独启动。 回收站位于 `.runtime/profiles//session-trash//`,在沙箱外,不会自动清空。它保留文件,因此不会释放这些文件占用的磁盘空间。 ## 在 Linux 上恢复多个聊天 当项目里有多个持续使用的聊天或 fork 时,可以使用 `start`:它保持一个 workspace 沙箱常驻,在内部恢复各个会话。命令会返回宿主终端,关闭这个终端不会停止托管环境;此模式无需额外的 `screen` 或 keep-awake watcher。 建议先查看将要恢复的记录: ```bash ./claude-env start --workspace /path/to/project --list ./claude-env start --workspace /path/to/project --all --dry-run ./claude-env start --workspace /path/to/project --all ``` 之后省略 `--all`,即可恢复保存的会话集合。仍在运行的会话会直接复用。对于本仓库 `workspace/` 下的项目,可以使用短名称: ```bash ./start_cc my-project --all --dry-run ./start_cc my-project --all ./start_cc my-project ``` 启动时实时显示每个聊天的标题、UUID、批次进度,以及启动或复用状态。同一 workspace 内,相邻两次 CLI 启动采用每次重新随机取值的 **1~2 秒间隔**,进度中会显示剩余等待时间;已运行的会话直接复用。整批启动后,继续报告连接状态变化,最多等待 `--wait` 指定的秒数(默认 30 秒)。`--wait 0` 跳过最后的连接检查,仍保留启动间隔;`--json` 隐藏进度,只输出一份 JSON 结果,方便程序读取。 需要同时查看进程、Remote Control、网页同步基线、回收站及自动恢复状态时,可以打开终端状态视图: ```bash ./start_cc my-project --status # 查看一次 ./start_cc my-project --status --watch # 每 2 秒刷新 ./start_cc my-project --status --watch 5 # 自定义刷新间隔:1~60 秒 ./start_cc my-project --status --json # 导出结构化快照,包含完整 UUID ``` 视图完全只读,可以直接查看已经运行的管理器,无需重启,不请求远端接口。`Ctrl+C` 只退出视图,会话继续运行。每个 fork 独立显示;缺少远端绑定记录、或当前远端 ID 尚未建立同步基线时,会明确提示尚不具备删除同步依据。已保存基线不代表连接仍在线;同步文件更新时间也不等于远端检查成功。实时刷新需要交互终端,JSON 模式只输出一次快照。 终端使用中文状态标签;JSON 快照使用固定的英文字段和状态值: | 状态标签 | 含义与处理方式 | |---|---| | `基线已保存` | 已在匹配的账号下成功读取当前远端 ID,具备后续删除核验依据。 | | `缺少绑定` / `尚无基线` | 这条聊天尚未建立删除同步依据;运行中的 fork 也可能如此,需要逐条查看。 | | `待确认删除 N/3` | 正在核验远端记录是否已移除,单次检查失败不会触发回收。 | | `待搬文件` | 已加入回收队列;workspace 运行期间,文件仍保留原位。 | | `待补写标题` | 已观察到网页改名,等待 workspace 离线后保存。 | `start_cc` 也接受项目的绝对或相对路径,代理设置与 `run` 相同。如果之前定义过同名 shell 函数,在终端重新定义一次,或加入 shell 配置;请将路径替换为自己的仓库绝对路径: ```bash start_cc() { /absolute/path/to/claude-env/start_cc "$@"; } ``` | 选项 | 行为 | |---|---| | 不指定选择选项 | 恢复上次保存的集合;首次使用导入已登记的后台聊天,没有这类记录时选择最近一次聊天。项目完全没有历史时创建一个新聊天。 | | `--all` | 恢复该 workspace 内所有未排除、有聊天内容的会话,包括父会话和 fork。跳过空初始化文件和 subagent 记录。 | | `--session UUID` | 按完整本地会话 UUID 选择,可重复指定;显式选择也会取消该会话的排除标记。 | | `--new` | 额外创建一个新聊天。 | | `--list` / `--json` | 查看记录和管理器状态;包含连接状态、当前网页链接、进程状态及退出码。 | | `--status` / `--status --watch [秒数]` | 查看一次终端状态视图,或持续刷新;`--status --json` 导出结构化快照。 | | `--wait 秒数` | 等待整批会话的启动状态,默认 30 秒,范围 0–60;超时不会重启进程。 | | `--dry-run` | 预览复用、恢复、记录缺失或新建行为,不启动环境。 | | `--attach UUID` | 打开会话终端,处理登录、信任和权限对话框;按 `Ctrl+]` 分离。 | | `--logs UUID` | 查看当前管理器保留的最近终端输出,包括启动错误。 | | `--exclude UUID` | 从之后的默认及 `--all` 恢复中排除;不停止进程、不删除记录。 | | `--stop` | 停止这个托管 workspace 及其进程,保留聊天记录。 | 会话按完整 UUID 区分,同名、继承相同提示词的 fork 仍分别保留。托管会话产生的 fork 会自动加入集合,其本地后台任务会被 Pin。排除父会话不会连带排除已经纳入管理的子会话。`--all` 也会恢复旧的已完成聊天,历史较多时先看预览。记录缺失时会明确报告,不会改为新建或重放原始提示词。恢复不额外发送“继续”,但仍遵循 Claude 自身对中断轮次的处理。 每次冷启动都通过 `--resume <原 UUID>` 加载聊天,包括已经退出的 fork。程序会先核对旧远端连接的账号归属、备份原始聊天文件,然后追加原生格式的连接重置记录,让 Claude 建立带原标题的新 Remote Control 入口并补传可恢复的历史。原消息、标题和 fork 关系不会被删除;本地 UUID 不变,网页链接会变化。运行中的会话直接复用,不改写记录、不重启。旧的后台任务登记不会被当成仍在运行的进程。 启动时只会自动接受已核实的首次 **“Resume this conversation?”** 提示,选择继续原聊天;不会发送实验提示词、接受权限请求或完成登录。手动 `--attach` 后由你接管该终端。 输出中的 `connected` 表示原生 CLI 已登记远端连接,并会给出该会话的网页链接;它不代表浏览器已经渲染完全部消息。`starting` / `resuming` 表示仍在启动,`needs-input` 表示需要 `--attach UUID` 处理登录或其他对话框,`remote-error` 表示连接失败,`history-withheld` 表示原生 CLI 仍禁止历史补传。后两种状态不会冒充恢复成功。账号归属不符、明确的历史抑制记录或文件异常会显示 `recovery-blocked` 并保留原文件。可用 `--list` 复查,用 `--logs UUID` 查看原因。 恢复前的逐字节备份位于 `.runtime/profiles//workspaces//history-backups//`,不会自动清空。重新执行 `start_cc` 可在系统重启后恢复聊天,但不恢复任意训练进程或内存状态,也不会安装开机启动服务。 ### 同步网页端的整理操作 托管启动会在恢复前检查已保存的远端会话信息。workspace 运行期间,宿主监视器约每分钟检查一次,使用同一代理和 profile 登录。它只读取远端元数据,不发送提示词、不刷新凭据、不停止 CLI 进程。已经运行的旧启动器会在下一次正常重启后启用监视器。 - **网页改名:** 连接正常时由原生 CLI 保存到本地。列表读取最新聊天标题及原生标题文件,下次恢复也沿用新名字。监视器还能发现两次检查之间、断连期间发生的改名,等 workspace 离线后补写;与本地同时改名时保留本地修改。首次读取远端标题只建立基线,避免旧的 `sandbox-*` 回退标题覆盖有意义的本地标题。 - **网页删除:** 必须曾成功读取当前远端 ID,核实账号和组织一致,并连续三次收到指向该 ID 的 `404 not_found_error`,才进入本地回收站。workspace 仍在使用时标为 `pending` 并排除后续恢复;等安全退出、下次启动,或离线执行 `sessions … apply` 时搬文件。独立 fork 和 memory 保留。仍可用 `sessions … bin` / `undo` 查看和撤销;撤销后不会因同一份删除证据立即再次回收。 - **断连、归档或鉴权失败:** 均不触发回收。超时、普通 404、账号切换,以及已不再对应当前本地会话的旧网页条目删除,也不会触发回收。从未成功观察到的远端 ID,不能仅凭“不存在”自动回收。 **当前 fork 限制:** 部分原生后台 fork 只在运行登记或 job 状态中保存远端 ID,没有在聊天文件中写入带账号归属的绑定记录。这些聊天可以运行、接收原生标题更新,但本版本不会在网页删除后自动回收它们。状态视图显示为 `缺少绑定`;父会话已覆盖,不代表它的 fork 也已覆盖。仍可使用本地 `sessions … trash` 清理。 监视器使用针对固定 CLI 版本核验的元数据接口;远端记录不存在并不能识别是谁移除了它。接口返回无法识别时保留本地文件。同步基线保存在沙箱外的 `.runtime/profiles//session-sync/.json`,只记录 ID、标题等信息,不保存凭据。`--list`、`--dry-run` 和本地回收站查看仍不联网。 **已有 `run`、VS Code 或 screen 启动器不会被自动停止或接管。** 如果它们占用该 workspace 的锁,`start` 会报错并保留原进程。现在即可使用 `--list` 和 `--dry-run` 查看记录,等原实例在合适的时间退出后再切换。旧 `run` 和编辑器模式保留原来的目录布局。 托管模式新增以下路径安排: - profile HOME 仍是 `/home/sandbox`。`CLAUDE_CONFIG_DIR` 为 `/home/sandbox/.claude-workspaces/`,各 workspace 的 daemon、job 和 PID 登记独立保存。 - 凭据仍保存在 `/home/sandbox/.claude`,通过固定版本 CLI 的独立凭据目录设置复用,不复制凭据。CLI 包装脚本通过 `--settings` 读取 profile 的 `settings.json`,workspace 内的 CLI 状态与本地设置另存。共享偏好请编辑 profile 设置文件,其中显式设置的值优先于本地值。 - `projects`(包括聊天和 memory)、skills、commands、agents、plugins、user-memory、output-styles、file-history、plans 通过目录挂载沿用原 profile 数据,已有记录保持原位。启动时已有的 profile `CLAUDE.md` 会只读挂载进独立配置目录。 - 恢复集合、锁和启动日志保存在 `.runtime/profiles//workspaces//`。其中该 workspace 的控制目录挂载到 `/run/claude-env`,用于本地管理 socket;接口只接受会话管理操作,不接受任意 shell 命令。 目前支持 **Linux + Claude Code 2.1.311**,使用原生进程登记和 Pin 格式前会校验版本。不保证远端服务始终可用,也不能防止严重内存不足造成的终止。独立运行状态避免不同 PID 命名空间中的 supervisor 共用一份登记;同 profile 的完整 HOME 仍共享,workspace 之间不是用户数据安全边界。 测试使用独立的临时 profile 和 workspace: ```bash /usr/bin/python3 -B -m unittest discover -s tests -p 'test_*.py' -v /usr/bin/python3 -B tests/session_lifecycle.py ``` 生命周期测试运行真实沙箱和官方 CLI,使用不可用的测试代理且不登录账号,覆盖启动、复用、隔离、停止和重启。回归测试另用模拟原生进程验证旧连接重置、历史和标题传递、首次 Resume 确认及状态报告;这些测试不验证已登录账号的网页或手机渲染。 远端同步测试使用模拟认证响应,覆盖删除确认、断连和鉴权错误、远端 ID 变化、延后回收与撤销,以及原生和离线改名;不删除真实云端聊天。 ## 理解 profile、workspace 与可见路径 **workspace** 是通过 `--workspace` 选择的宿主项目目录。**profile** 是通过 `--profile` 选择的持久用户环境。项目没有另外的 profile 绑定表:每次启动选择这一组合,不指定 profile 时使用 `default`。 | 环境组成 | 作用范围 | |---|---| | Claude 登录、全局设置、skills、plugins | 同一 profile 的所有 workspace 共享 | | HOME 与用户安装的文件 | 在 profile 内共享 | | 项目文件 | 选定 workspace 及其全部子目录 | | 会话与自动记忆分组 | Claude Code 按沙箱内项目路径区分 | | Linux VS Code 用户数据目录 | 在 profile 内按 workspace 分开保存 | | 进程、网络、`/tmp`、`/run` | 每个外层启动器实例独立 | Linux 的 `.runtime/profiles//home` 挂载为 `/home/sandbox`。macOS 的持久宿主目录为 `.runtime/mac-profiles//home`,内层沙箱的 HOME 同样为 `/home/sandbox`。两种平台分别保存登录数据,迁移代码不会复制凭据。 **同一 profile 的 workspace 共享完整 HOME。** 虽然项目历史分别归组,进程仍可主动读取这份 HOME 中其他项目的历史或记忆。登录、退出登录、全局设置和共享技能的变更会影响同 profile 的其他 workspace。需要分开用户数据时,请选择不同 profile。若选择的项目目录相互包含,重叠的项目文件也会可见。 ### Linux 中的文件视图 | 沙箱内路径 | 来源 | 权限 | |---|---|---| | `/workspaces//` | 选定宿主项目 | 持久、可读写 | | `/workspace` | 显式登记的旧 workspace | 持久、可读写 | | `/home/sandbox` | 所选 profile 的完整 HOME | 持久、可读写 | | `/usr`,含 `/usr/local` | 宿主系统软件 | 只读 | | `/bin`、`/sbin`、`/lib`、`/lib64` | 指向 `/usr` 对应目录的链接 | 只读 | | `/opt/claude`、`/opt/bin/claude` | 私有 Claude CLI | 只读 | | `/opt/locales/` | 已生成的 locale | 只读 | | `/etc` | 生成的账号、DNS、时区、证书与托管设置 | 只读 | | `/tmp`、`/run` | 每次启动的临时文件系统 | 临时可写 | | `/proc`、`/dev` | 沙箱进程视图及基础设备 | 受沙箱限制 | 宿主完整 HOME、其他项目目录、SSH agent、Docker socket 和桌面会话默认不挂载。VS Code 模式会增加[对应章节](#在-linux-上使用-vs-code)说明的挂载。 环境会清空继承的变量,并设置: ```text HOME=/home/sandbox PATH=/opt/bin:/usr/local/bin:/usr/bin:/bin ``` 宿主已激活的 Conda/venv 和 shell 启动脚本不会被继承,安装在宿主 HOME 下的 Conda 也不会自动可见。Claude Env 不会为每个 workspace 创建或激活虚拟环境。项目内的 `.venv` 随项目可见,但解释器、软链接和绝对路径也必须能在沙箱内工作。安装到 profile HOME 的文件由该 profile 的 workspace 共享;用户可执行目录不会自动加入上述 PATH。 ### 在 Linux 上并行运行多个 workspace 在不同终端启动不同项目: ```bash ./claude-env run --profile default --workspace /path/to/project-a ./claude-env run --profile default --workspace /path/to/project-b ``` Linux 按 **profile + workspace 真实路径** 加锁。同 profile 的不同 workspace 可同时运行;相同组合只允许一个外层启动器。符号链接别名视为同一 workspace。已有 VS Code 窗口内可以打开多个 Claude 会话。 workspace key 是宿主真实路径的 SHA-256 前 32 位十六进制字符。项目位置不变时,沙箱路径保持稳定;移动项目会改变 key,也可能改变 Claude Code 选取的项目历史。 ### 保留已有的 `/workspace` 历史 旧 Linux profile 可在 `.runtime/profiles//workspace-layout.json` 中登记原项目: ```json { "version": 1, "legacy_workspace": "/absolute/path/to/the-original-project" } ``` 只有该项目保留 `/workspace`,新项目使用各自的唯一路径。已有历史保留原位,无需重写。如果检测到旧 `/workspace` 会话而没有登记,启动器会要求先明确其项目归属,不会分配给下一个打开的项目。仍在运行的旧版启动器只会阻止登记的旧 workspace 再次启动。 ### 在 Linux 上保持后台 fork 唤醒 即使外层启动器由 `screen` 保持运行,Claude Code 仍可能回收空闲的后台 fork。网页或手机端的 Pin 不一定会更新本地 supervisor 的 Pin 清单。对于固定 CLI 版本 2.1.311,可以直接在宿主管理这份清单,无需再启动一个沙箱: ```bash ./claude-env keep-awake --workspace /path/to/project --profile default --all --dry-run ./claude-env keep-awake --workspace /path/to/project --profile default --all ``` 如果还希望新 fork 自动置顶,在宿主另外一个 `screen` 会话中运行监控: ```bash screen -S project-keep-awake ./claude-env keep-awake \ --workspace /path/to/project --profile default --all --watch ``` 依次按 `Ctrl+A`、`D` 分离。可用重复的 `--session <短ID或完整ID>` 代替 `--all`,只选择特定会话。监控每 15 秒检查一次,持续为匹配的任务添加 Pin,包括已经完成的任务;它不会唤醒已停止的任务、发送提示词或重启 Claude。已 asleep 的会话需先通过回复或 attach 唤醒一次。需要在本地 Agent View 取消 Pin 时,先用 `Ctrl+C` 停止监控;停止监控不会删除已有 Pin。 命令使用 Claude 的文件锁合并 Pin 并原子写入,保留其他 workspace 的 Pin。该机制依赖版本特定的内部文件格式,遇到未经验证的已安装运行时版本会拒绝操作。它防止普通本地空闲回收,不保证避免严重内存不足、关机或远程连接失效,也不会解决共享 profile 下跨 workspace 的 supervisor 状态冲突。 ## 在 Linux 上使用 VS Code CLI 环境可用后,可以继续使用专用编辑器窗口。需要已安装的官方 VS Code `/usr/share/code/code` 和标准本地 Wayland 会话。已有集成验证使用 VS Code 1.138.0 与官方 Claude Code 插件 2.1.318。 ```bash ./claude-env vscode --workspace /absolute/path/to/your-project --profile default ``` 通过宿主文件夹选择器选择项目: ```bash ./claude-env-vscode --pick-workspace ``` 打开官方 Claude Code 面板,通过 **Open in New Tab** 增加会话。它们共享所选 profile 的登录、设置、skills、plugins 和历史。并发受机器与账号资源限制,启动器没有固定四会话上限。 编辑器主进程、扩展宿主、Claude 后端和集成终端都在同一个外层沙箱内,看到相同的项目路径。窗口使用私有编辑器数据,不覆盖普通宿主 VS Code 的偏好。每个新 workspace 首次启动时,会在存在的情况下继承旧私有编辑器的 `settings.json` 和 `keybindings.json`,之后分别保存编辑器状态。 官方插件私有安装到 `.runtime/vscode/extensions`,只读挂载为 `/opt/vscode-extensions`。启动检查器只读挂载到 `/opt/claude-env/vscode-process-wrapper`。后端启动记录写入 profile 的 `.local/state/claude-env/vscode/launches.jsonl`,不记录提示词、凭据或参数值。 图形模式额外共享 **一个 Wayland 显示 socket**,位于 `/run/user/0/wayland-0`。不会共享宿主整个运行时目录、D-Bus、X11、SSH agent、GPU 或宿主网络。缺少 Wayland 时拒绝启动。Electron 使用 `--no-sandbox`,因为当前限制下无法运行其嵌套 Chromium 沙箱;外层 Bubblewrap、seccomp、文件、进程与网络限制仍启用。 内置文件选择器只能看到已挂载路径。当前不提供原生桌面控制或宿主浏览器联动,登录时可能需要复制链接到宿主浏览器。普通宿主 VS Code 窗口不会自动获得这些隔离限制。 可选的桌面启动默认值从 `.runtime/vscode/launcher.json` 读取,包括 workspace、profile 和不含认证信息的上游代理 URL。启动器不会自动保存代理密码。这个私有窗口中的编辑器及扩展自动更新均已关闭。 ## 代理、时区和语言 启动器按以下顺序读取宿主代理配置: 1. `CLAUDE_ENV_PROXY` 2. `https_proxy` 3. `HTTPS_PROXY` 4. `http_proxy` 5. `HTTP_PROXY` 使用带明确端口的 HTTP CONNECT 代理 URL。Linux 接受 `http://` 或 `https://` 上游;macOS 适配器目前要求 `http://`,访问 HTTPS 目标时也通过 HTTP CONNECT。macOS 未设置上述变量时会读取已启用的系统 HTTP/HTTPS 代理。代理变量与凭据不传入沙箱。缺少代理或网络初始化失败时拒绝启动;上游连接失败不会回退直连。 每次启动通过代理查询 `ipwho.is`,失败时尝试 `ipinfo.io`,根据返回结果选择时区与地区默认语言。这些服务会看到代理出口 IP,查询不包含项目文件或 Claude 凭据。地区默认语言可能与你的偏好不同。地理查询失败时,可同时明确指定两项: ```bash ./claude-env shell --workspace /path/to/project \ --timezone America/New_York --locale en_US.UTF-8 ``` 启动器设置 `TZ`、`LANG`、`LC_ALL`、`LANGUAGE`、生成的 UTF-8 locale,以及沙箱内 `/etc/localtime` 和 `/etc/timezone`。Claude 的只读托管设置包含 `language` 和 `timeZone`,但不保证所有界面文字都翻译。进程仍能修改自己的环境变量。 时区在下次启动时重新选择,不会在运行中热切换。上游代理若按域名选择不同出口,地理查询出口可能与 Anthropic 流量的出口不同。Claude Env 不控制这种分流,也不承诺代理不可识别。 ## 管理 macOS 虚拟机 每组 **项目绝对路径 + profile** 对应一个专用 VZ/Linux VM,默认 2 CPU、4 GiB 内存与 16 GiB 按需占用空间的虚拟磁盘。只从 Mac 挂载选定项目和 profile HOME,不转发 SSH agent,也不自动转发 guest 服务端口。 ```bash ./claude-env vm-status --workspace /path/to/project --profile default ./claude-env vm-init --workspace /path/to/project --profile default ./claude-env vm-stop --workspace /path/to/project --profile default ``` 退出 CLI 或 shell 后,VM 保持可复用状态。通过 `vm-stop` 释放内存,它也会停止该 VM 内的会话。若升级改变了 VM 隔离配置,先停止 VM,再重新启动以更新配置。 **macOS 当前每个 profile 只允许一个活动启动器**,即使项目位于不同 VM。Linux 的同 profile 多 workspace 并发暂不适用于这里。项目在内层沙箱中的路径以启动日志为准。 Claude 运行的是 Linux 软件,不能直接使用 Xcode、宿主 Keychain 或宿主桌面程序。外层 SSH 隧道只绑定 VM 回环地址;宿主和 guest 监控进程会在所属启动器或隧道消失时终止内层进程。 ## 隔离如何工作 Linux 后端组合使用以下机制: 1. 在 user/network namespace 内创建 TUN 虚拟网卡与隔离 DNS 监听器。 2. 通过文件描述符连接到执行沙箱外的可信网关。TCP 经 tun2socks 和选定 HTTP CONNECT 代理转发;DNS 经同一代理使用 Cloudflare DoH,失败时尝试 Google DoH。 3. Bubblewrap 创建 mount、PID、IPC、UTS 和 cgroup namespace,清空环境、移除 capabilities,并禁止继续创建 user namespace。 4. seccomp 限制命名空间切换、挂载、ptrace 和内核管理,同时允许普通进程与线程。 常见私网、链路本地与保留 IPv4 网段通过黑洞路由阻断。没有 IPv6 默认路由,不提供普通 UDP/QUIC 转发。Claude 启动的工具继承相同限制。交互启动使用独立 PTY,退出时清理沙箱与网关。 macOS 的专用 VM 提供额外边界,内层 Linux 沙箱与 guest 共享内核。VM 依赖准备和 Linux AppArmor 安装是明确的设置步骤;普通启动不会修改宿主时区、locale、防火墙或路由。 使用时需要了解以下实际边界: - 项目挂载是可写宿主文件,不会自动回滚。需要可恢复编辑时,请使用 Git 或副本。 - 进程可以使用所选 profile 的凭据,并通过允许的公网连接发送可读取的数据。共享 profile 不提供 workspace 间的数据保密隔离。 - 默认环境无法使用宿主 Docker、SSH agent、宿主端口和桌面自动化;需要这些接口的集成应另行设计。 - Linux 共享宿主内核,图形模式还需与宿主 Wayland 合成器通信。未知内核、沙箱、合成器或虚拟化漏洞仍可能存在。 - 隔离不会隐藏所有网络或设备特征,不会锁定应用自身的语言选择,也不承诺减少账号限制。 ## 检查与排障 ### 检查环境 在仓库根目录中,使用可用代理,并确保所选 workspace 空闲: ```bash ./claude-env check --workspace /path/to/project ``` 该检查验证权限、时区、locale、CLI 启动和真实 HTTPS 出口,不需要 Claude 登录,也不发送模型请求。代理出口轮换或不同地理服务的数据差异可能导致时区检查失败。 Linux 编辑器检查: ```bash ./claude-env vscode-check --workspace /path/to/project ``` 检查覆盖插件加载、多会话、编辑器文件访问、集成终端和继承的隔离限制,使用单独的测试编辑器数据,并将 `claude-env-vscode-validation.json` 写入项目。加 `--model-smoke-test` 会发送一条最小模型请求,计入账号用量。所选 workspace 需空闲,同 profile 的其他 Linux workspace 可以继续运行。 开发者单元测试不需要真实登录或模型请求: ```bash /usr/bin/python3 -m unittest discover -s tests -p 'test_*.py' -v ``` 完成运行时准备后,可运行 Linux 集成测试: ```bash /usr/bin/python3 tests/workspace_lifecycle.py /usr/bin/python3 tests/workspace_editor_lifecycle.py /usr/bin/python3 tests/lifecycle.py ``` 编辑器生命周期测试会打开两个临时窗口,需要 Wayland。`tests/lifecycle.py` 使用 `workspace/` 和测试 profile,运行前请确保目录存在;它验证上游故障与启动器终止。已准备好的 Mac 使用 `/usr/bin/python3 tests/mac_lifecycle.py`,该测试会占用 `workspace/` 和 `default` profile,请先退出该 profile 的其他实例。集成测试可能创建本地验证报告并执行网络检查,但不会发送模型请求。 ### AppArmor 与 SSH 启动 Ubuntu 中,新 SSH 登录可能没有已有桌面应用的 user namespace 权限。若启动报告 `unshare: write failed /proc/self/uid_map: Operation not permitted`,请在宿主安装本项目专用的 AppArmor 授权: ```bash sudo /usr/bin/python3 install_apparmor.py ``` 它只向私有 `.runtime/bin/claude-env-unshare` 路径授予 user namespace 权限,并将配置持久保存到 `/etc/apparmor.d/claude-env-userns-`。不会关闭全局限制、修改系统 Python/unshare 权限或添加 setuid/file capabilities。util-linux 升级后可重新运行以更新私有副本。仅准备并检查配置、不加载时,使用 `/usr/bin/python3 install_apparmor.py --prepare`。 ### 其他常见问题 - **提示 workspace 已运行:** 复用已有 VS Code 窗口,关闭该 profile/workspace 组合的启动器,或选择其他 workspace。macOS 仍对整个 profile 加锁。 - **找不到宿主工具或 Conda 环境:** 查看[可见路径](#linux-中的文件视图)。宿主 HOME 下安装的软件及已激活环境不会自动开放。 - **编辑器无法打开:** 检查 `/usr/share/code/code`、本地 Wayland 会话和代理。桌面辅助启动器的日志位于 `.runtime/vscode/editor.log`。 - **检测不到文件变化:** 检查宿主工具是否耗尽 inotify 实例或监听上限。调整上限属于单独的宿主管理操作,启动器不会自动执行。 - **首次引导按 Ctrl+C 后滞留:** 固定版本 CLI 中曾观察到该现象。在沙箱 shell 中可用 Ctrl+反斜杠终止 CLI 并返回 shell,也可关闭启动器退出环境。 - **强制停止后残留临时目录:** Linux 的 SIGKILL 可能遗留 `.runtime/session-*`,其中启动器文件不含上游代理凭据。macOS 的启动前步骤若中断,可能在内层沙箱外残留 guest 私有的 0600 权限配置。 已有安装检查覆盖 CLI 启动和隔离。认证后的模型行为仍取决于你的登录与账号,安装检查本身不代表已验证模型调用。 ## 运行时版本与更新 | 组件 | 固定版本 | 配置来源 | |---|---|---| | Claude Code CLI | 2.1.311 | `artifacts.py` | | tun2socks | 2.7.0 | `artifacts.py` | | Lima | 2.2.1 | `artifacts.py` | | VS Code Claude Code 插件 | 2.1.318 | `vscode_backend.py` | `artifacts.py` 中的 SHA-256/SHA-512 用于校验运行时下载。Claude 来自 Anthropic 官方分发,tun2socks 与 Lima 来自各自官方 GitHub release,Debian 镜像来自 Debian Cloud。校验可以发现损坏或意外变更,不能替代对发布者的信任。 重新安装固定版本私有运行时可执行 `/usr/bin/python3 setup.py`。升级时更新版本与摘要、重新安装,并运行相应检查;CLI 和私有编辑器的自动更新均已关闭。 请将 `.runtime/` 保持私有,不纳入版本控制。其中可能包含登录凭据、日志、启动器配置、VM 磁盘和私有 SSH 密钥。仓库 `.gitignore` 已排除该目录、本地 workspace 与验证报告。 延伸阅读:[Claude Code 网络配置](https://code.claude.com/docs/en/network-config)、[设置](https://code.claude.com/docs/en/settings-reference)、[VS Code 集成](https://code.claude.com/docs/en/vs-code#extension-settings)、[VS Code 扩展测试](https://code.visualstudio.com/api/working-with-extensions/testing-extension)、[Bubblewrap](https://github.com/containers/bubblewrap)、[tun2socks](https://github.com/xjasonlyu/tun2socks)。