> ## Documentation Index
> Fetch the complete documentation index at: https://cac.nextmind.space/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# cac env

> 环境管理——创建、激活和检查隔离会话。

每个环境是完全隔离的上下文：独立的 `.claude` 配置、设备身份、Claude Code 版本和可选代理。

## create

创建新环境。

```bash theme={null}
cac env create <name> [-p <proxy>] [-c <version>] [--clone [source]] [--no-link] [--telemetry <mode>] [--persona <preset>]
```

| 参数                   | 说明                                                                                                                            |
| :------------------- | :---------------------------------------------------------------------------------------------------------------------------- |
| `-p, --proxy`        | 代理地址。可选。                                                                                                                      |
| `-c, --claude`       | 锁定的 Claude Code 版本。未安装时自动下载。`latest` 会自动解析为最新版本。                                                                              |
| `--clone [source]`   | 从 `~/.claude/`（默认）或其他 cac 环境继承配置。默认通过符号链接共享。                                                                                  |
| `--no-link`          | 与 `--clone` 配合使用。复制文件而非符号链接，用于独立定制。                                                                                           |
| `--telemetry <mode>` | 遥测屏蔽模式：`transparent`（不屏蔽）/ `stealth`（默认，屏蔽 1p\_events）/ `paranoid`（最大屏蔽）。向后兼容：旧名称 `off` / `conservative` / `aggressive` 自动映射。 |
| `--persona <preset>` | 容器/服务器的终端环境预设：`macos-vscode` / `macos-cursor` / `macos-iterm` / `linux-desktop`。注入桌面终端环境变量并隐藏 Docker 信号。仅在 Docker/服务器中运行时需要。  |

创建成功后会**自动激活**该环境，无需额外执行 `activate`。

**示例：**

```bash theme={null}
# 仅身份隔离（无代理，使用系统 Claude）
cac env create personal

# 带代理
cac env create work -p 1.2.3.4:1080:user:pass

# 带代理 + 锁定版本
cac env create work -p socks5://proxy:1080 -c 2.1.81

# 自动安装并锁定最新版 Claude Code
cac env create dev -c latest

# 从 ~/.claude/ 克隆配置（符号链接）
cac env create work --clone

# 从其他环境克隆
cac env create work2 --clone work

# 克隆配置（独立复制）
cac env create work --clone --no-link

# stealth 模式（默认）：屏蔽 1p_events 但允许 Feature flags
cac env create stealth-env --telemetry stealth

# paranoid 模式：最大遥测屏蔽
cac env create paranoid --telemetry paranoid

# Docker/服务器中运行：使用 macOS VSCode 人设
cac env create docker-work --persona macos-vscode

# 组合：Docker + 强遥测屏蔽
cac env create secure-docker --persona macos-cursor --telemetry paranoid
```

**代理格式：**

```
host:port:user:pass       # 自动检测协议（依次尝试 http → socks5 → https）
host:port                 # 无认证
socks5://user:pass@host:port
http://host:port
```

<Info>
  环境名称必须是字母数字、连字符或下划线。如 `my-work` 和 `prod_us1` 是有效的；`my/work` 无效。
</Info>

## ls

列出所有环境，以表格形式展示环境名称、代理、Claude 版本等信息。

```bash theme={null}
cac env ls
cac ls        # 快捷方式
```

```
  ▶ work
      proxy: socks5://u:p@1.2.3.4:1080  claude: 2.1.81
    personal
      claude: system
```

`▶` 标记显示当前活跃环境。

## activate

激活环境。这是**全局**的——影响所有终端。

```bash theme={null}
cac env activate work
cac work              # 快捷方式
```

激活时：

1. 将 `~/.cac/current` 设置为环境名称
2. 更新隔离 `.claude` 配置中的 statsig 和用户 ID 文件
3. 如果检测到 TUN 且配置了代理，重启中继

## set

修改已有环境的配置。

```bash theme={null}
cac env set [name] <key> <value>
```

不指定 `name` 时，默认修改当前活跃环境。

| 用法                                              | 说明                                              |
| :---------------------------------------------- | :---------------------------------------------- |
| `cac env set [name] proxy <url>`                | 设置或更换代理                                         |
| `cac env set [name] proxy --remove`             | 移除代理                                            |
| `cac env set [name] version <ver\|latest>`      | 更换 Claude Code 版本，`latest` 自动解析                 |
| `cac env set [name] telemetry <mode>`           | 修改遥测屏蔽模式：`transparent` / `stealth` / `paranoid` |
| `cac env set [name] persona <preset\|--remove>` | 修改或移除终端人设                                       |

**快捷方式：**

```bash theme={null}
cac env <name> proxy <url>    # 等同于 cac env set <name> proxy <url>
cac env proxy <url>           # 修改当前环境代理
```

**示例：**

```bash theme={null}
cac env set work proxy socks5://user:pass@1.2.3.4:1080
cac env set work proxy --remove
cac env set work version 2.1.81
cac env set work version latest

# 遥测模式
cac env set work telemetry stealth    # 屏蔽 1p_events，Feature flags 正常
cac env set work telemetry paranoid   # 最大屏蔽
cac env set work telemetry transparent  # 不屏蔽

# 终端人设
cac env set work persona macos-vscode
cac env set work persona --remove

# 快捷方式
cac env work proxy 1.2.3.4:1080:user:pass
cac env proxy --remove        # 移除当前环境代理
```

## check

对当前活跃环境运行诊断检查。输出简洁的通过/失败结论摘要。

```bash theme={null}
cac env check          # 简洁摘要（✓/✗）
cac env check -d       # 详细输出
```

| 参数              | 说明              |
| :-------------- | :-------------- |
| `-d, --details` | 显示详细诊断输出，而非仅摘要。 |

检查项目：

* 环境信息（代理、UUID、版本、时区）
* 代理连通性和出口 IP（如果配置了代理）
* TUN 冲突检测（如果配置了代理）
* 安全防护（DNS 守卫、遥测环境变量、mTLS）
* 包装器 PATH 检测

## rm

移除环境。不能移除当前活跃的环境。

```bash theme={null}
cac env rm staging
```

<Warning>
  此操作会永久删除环境目录，包括其 `.claude` 配置、身份文件和 mTLS 证书。
</Warning>