<div align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7237/193b3f67135a6e0f90c36ec914e8c5fd73a4d6181ea56b6ba75e042e6335dc72.png" alt="clawk" width="400">
*给编码代理一个它自己的、一次性的 Linux 机器，而不是你的。*
[](https://github.com/clawkwork/clawk/actions/workflows/ci.yml)
[](LICENSE)
[](go.mod)
-lightgrey)
**[安装](#install)** · **[快速上手](#quickstart)** ·
**[为什么用虚拟机？](#why-a-vm)** · **[工作原理](#how-it-works)** ·
**[对比](#compared-to)** · **[常见问题](#faq)** · **[文档](https://github.com/clawkwork/clawk/blob/main/docs)**
</div>
编码代理只有在你真正让它*动手*做事时才有用：安装包、运行它写的代码、启动服务器、使用网络。在你自己机器上，这只会留下两个糟糕的选择。要么你批准每一条命令（然后每隔几秒就盯着一个提示符），要么你运行 `--dangerously-skip-permissions`，然后祈祷没有什么是离一个 `rm -rf` 或一个泄露的令牌那么近。
clawk 是第三个选择。`cd` 进一个仓库，输入 `clawk`，Claude Code（或 Codex、pi、或一个 shell）就在一个一次性的 Linux 虚拟机里工作（你的代码挂载进去，来宾系统里是 root，没有权限提示），而你的文件、你的钥匙串、以及你机器的其余部分都够不着。**代理得到的是它自己的机器，而不是你的。**
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7237/56b97e90b5af190abc2e1de5cc7b8ad4e835a05dd6e7a1e2f3416d78021a6a8b.gif" alt="clawk 演示：clawk 启动一个虚拟机并挂载 claude；一个向未知服务器发送数据的被阻止的尝试出现在 clawk 网络拒绝中；clawk attach 稍后恢复沙箱" width="760">
<br>
<sub><i>一条命令就得到一个能工作的代理；一次向未知服务器发送数据的尝试，被网络允许列表阻止；<code>clawk attach</code> 稍后恢复会话。</i></sub>
</p>
边界不是提示词里一条可能被代理说服绕过的规则。它是一台独立的机器，唯一的开口就是你挂载的那些。从沙箱内的一个 shell 里：```console
$ curl https://tracker.evil.example # not on the allow-list: blocked
curl: (7) Failed to connect to tracker.evil.example port 443 after 2 ms: Connection refused
$ cat ~/.ssh/id_rsa # your keys never entered the VM
cat: /home/agent/.ssh/id_rsa: No such file or directory
$ git push # ...yet this works: ssh-agent is forwarded
Enumerating objects: 5, done.
```
老实说，在限制方面，允许列表阻止的是与*未知*服务器的连接，而不是与你已允许的服务器：github.com 是预先允许的，转发的 ssh-agent 可以推送，所以请把 agent 能读取的任何内容都视为它可能发布的内容。[安全模型](#security-model-and-its-limits)对此有详细说明。
如果 agent 弄坏了 VM，运行 `clawk destroy && clawk`：一个全新的 VM、同一个仓库，`--resume` 会恢复对话。
> [!IMPORTANT]
> **1.0 之前且快速迭代中。** 版本之间预计会有破坏性变更和偶尔的粗糙之处；事情可能而且一定会出问题。请提交 issue；这些反馈正在塑造 1.0。
## 亮点
- **让 agent 做任何事。** 它运行在一个网络受限的一次性 VM 中，所以 `rm -rf`、软件包安装和不受信任的代码都无法触及你的主机、你的文件，或任何你未明确共享的内容。
- **一条命令即可工作。** `cd` 进入仓库并运行 `clawk`。无需 Dockerfile、devcontainer 或配置文件。首次启动会从你的镜像构建 rootfs；之后的每次启动只需几秒。
- **弄坏它也不会丢失任何东西。** 随意销毁和重建；你的代码和 agent 的对话都保存在主机上。只有一次性 VM 磁盘会丢失。
- **一个真正的 Linux 机器，你的工具链。** 任何 OCI 镜像都是 rootfs：一个完整的操作系统，恰好包含你的项目所需的工具。无需 Docker 守护进程。
- **机密留在你的机器上。** 出站流量被允许列表限制，你的 ssh-agent 被转发，因此 `git push` 无需密钥进入 VM 即可工作。
- **每个项目或工单一个沙箱。** 可同时运行多个；多仓库工单会为每个仓库创建一个 git worktree，并协调 PR。空闲 VM 会自动释放内存并挂起到磁盘，因此被遗忘的沙箱几乎不花费任何成本。
## 为什么用 VM？
clawk 是一个面向自主编码 agent 的通用本地环境。VM 是关键：它是一个 agent 可以完全拥有的整台机器，而不是包裹在你正在使用的机器上的策略里的一个进程。
- **独立的内核。** 客户机运行自己的 Linux 内核，因此主机文件系统不是靠拒绝规则隐藏的；它从未被挂载过。
- **常规的 Linux 环境。** 标准内核、标准用户空间、符合 `/dev/kvm` 预期的行为，因此工具的行为与其文档一致，不会出现系统调用过滤的意外。
- **客户机中的 root 权限。** 安装系统软件包、编辑 `/etc`、加载模块、绑定特权端口。这是 agent 可以重新配置的机器。
- **一次性生命周期。** 弄坏成本低，重建速度快；一台损坏的 VM 只需 `clawk destroy && clawk` 即可恢复，你的仓库和对话在主机上不受影响。
- **与主机更强的隔离。** 隔离依赖于虚拟机监控程序边界，而不是依赖把进程沙箱策略做到完全正确。
这种组合可以运行受限进程沙箱往往难以支持的工作负载：
- 安装软件包和原生依赖；
- 运行后台服务（数据库、队列、开发服务器）；
- 以全速执行不受信任的构建和测试；
- 使用期望真实机器的系统级 Linux 工具；
- 并且，在受支持的硬件上配合启用 KVM 的客户机内核，可以在沙箱*内部*运行容器和 Kubernetes 开发工作流，例如 Docker 或 Kind。这是可选的且受硬件限制；具体要求请参阅[镜像](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override)。
这些都不是*产品本身*；clawk 是用于一般性本地 agent 工作的。Docker 和 Kubernetes 只是“需要真实机器，而不是沙箱进程”的最典型例子。
## 安装
需要 macOS 14+ 且为 Apple silicon。（Linux 通过 firecracker 支持，目前处于实验阶段——请从 **[docs/linux-quickstart.md](https://github.com/clawkwork/clawk/blob/main/docs/linux-quickstart.md)** 开始，其中涵盖了设置、工作流程和差距。本 README 以 macOS 为主。）```sh
brew install clawkwork/tap/clawk
```
**从源码构建**（贡献者，或如果你不使用 Homebrew），需要 Go 1.26+：```sh
git clone https://github.com/clawkwork/clawk && cd clawk
make install
```
无论哪种方式，都不需要额外的主机工具：不需要 Docker、不需要 qemu、不需要 sudo。
虚拟机监控程序是 Apple 的 Virtualization.framework，已链接到二进制文件中，并且发布二进制文件已预构建了客户机内代理——因此只有在从源码构建时才需要 Go 工具链，而那时你本来就有。首次运行会检测缺失项并提供修复。
**卸载：** `clawk destroy` 销毁你的沙箱，`rm -rf ~/.clawk`，然后通过 `brew uninstall clawk` 移除二进制文件（如果是源码安装，则从 `$GOBIN` 中删除）。没有安装其他任何东西：没有 launchd 任务；每个沙箱的守护进程都是普通进程，会随其虚拟机一起退出。
## 快速开始
日常使用场景，为当前所在目录创建一个沙箱：```sh
cd ~/code/my-project
clawk # boot a sandbox for this dir + attach claude
clawk run shell # drop into a shell in the same sandbox
clawk run codex # or another agent: codex, pi, opencode, shell
clawk down # stop the VM (repo + agent state persist)
clawk attach # come back later — boots if stopped, reattaches claude
clawk destroy # remove the VM (conversation history is kept)
```
通用选项：```sh
clawk run claude -- --resume # pass args through to the agent
clawk forward add my-project 3000 # expose a guest dev server on localhost:3000
clawk network allow my-project api.example.com
```
处理一个跨多个仓库的工单？一条命令即可为每个仓库在全新分支上创建带 git worktree 的沙箱，之后 `clawk pr` 会为所有变更内容打开相互关联的 PR：```sh
cd ~/code/my-workspace # contains a clawk.mod listing the repos
clawk work INFRA-123 # one sandbox, a worktree per repo, claude attached
clawk pr INFRA-123 # push branches + open one PR per repo
```
完整的工单生命周期（状态、合并或变基后的后续分支）详见 **[docs/ticket-mode.md](https://github.com/clawkwork/clawk/blob/main/docs/ticket-mode.md)**。
> **提示：** 使用 Claude Code？运行一次 `claude setup-token`，然后运行
> `clawk auth set-token`，之后每个沙箱启动时都会自动登录，
> 无需 `/login`，并行沙箱之间也不会出现登录冲突。详见
> **[docs/claude-auth.md](https://github.com/clawkwork/clawk/blob/main/docs/claude-auth.md)**。
## 什么能保留，什么不能
一条规则决定持久性：*虚拟机是一次性的；你不想丢失的一切都保存在宿主机上。*
| | `clawk down` | `clawk destroy` |
| --- | :---: | :---: |
| 你的仓库（挂载的工作树；提交、分支） | ✅ | ✅ |
| 代理状态（Claude/Codex/pi/opencode 对话、记忆） | ✅ | ✅ |
| 虚拟机磁盘（apt 安装、缓存、`$HOME`） | ❌（每次启动时全新重建*） | ❌（这正是它的目的） |
\* 两个例外：恢复 `clawk snapshot` 会按挂起时的状态精确还原磁盘和
内存；Linux/firecracker 提供程序会保留其磁盘直到执行 destroy。每次启动
都需要的工具应放入镜像（`vm ( image … )`）；每次启动时的设置应放入
`on up` 钩子中。
代理状态按沙箱挂载在宿主机上：每个运行器的家目录——
claude 的 `~/.claude/`、codex 的 `~/.codex/`、pi 的 `~/.pi/`、opencode 的两个 XDG
目录——位于宿主机上的
`~/.clawk/namespaces/default/state/<name>/` 下，因此重建的
沙箱可以通过 `--resume` 恢复其旧对话。正是这个挂载让承诺成真：虚拟机磁盘本身
在每次启动时都会从镜像重新克隆，因此运行器在这些目录之外写入的任何内容
都会在下次 `clawk up` 时消失。
## 默认完全自主（以及 `--safe` 退出选项）
运行器以其“外部沙箱”模式启动：claude 使用
`--dangerously-skip-permissions`，codex 使用
`--dangerously-bypass-approvals-and-sandbox`，pi 使用 `--approve`（它没有
审批提示可绕过——它根本不附带沙箱——但它确实会将项目本地的 `.pi/` 设置和
扩展置于信任提示之后），而
opencode 使用 `--auto`。在你自己的机器上，这些标志
会是鲁莽之举；但在这里它们正是关键：虚拟机边界和网络
允许列表提供了隔离，因此代理可以全速工作，无需逐操作提示。
代理只能影响你挂载和允许列表中的内容，仅此而已（见 [SECURITY.md](https://github.com/clawkwork/clawk/blob/main/SECURITY.md)）。
还是更喜欢确认提示？在任何附加操作中添加 `--safe`
（`clawk --safe`、`clawk run claude --safe`），该会话中运行器将
不带其绕过标志启动。
## 网络
默认拒绝出站流量；每个沙箱都有自己的允许列表。
DNS 可解析所有内容；对未列入列表的主机的 TCP、UDP（包括 QUIC）和 ICMP 回显
均被拒绝。常见注册表（npm、PyPI、crates.io、GitHub、
Anthropic 等）已预先允许，并且过滤器是 DNS 感知的，因此允许
`example.com` 后，即使其 IP 轮换也能持续生效。```sh
clawk network allow my-project api.stripe.com '*.internal.mycorp.com' 10.0.0.5
clawk network denials my-project # what the agent tried that got blocked
clawk forward add my-project 3000 # localhost:3000 → the guest's dev server
clawk forward add-reverse my-project 63342 # and the other way: a service on YOUR
# localhost, reachable inside the guest
```
拒绝记录按*客户机解析出的主机名*进行，因此 `clawk network denials` 可读作代理尝试访问目标的日志。可复用的命名策略（包括订阅 oisd 等外部黑名单）以及将它们分层叠加的 `use` 链，详见
**[docs/networking.md](https://github.com/clawkwork/clawk/blob/main/docs/networking.md)**。
## 配置：`clawk.mod`
无需配置文件；默认设置已足够合理。当项目需要更多配置时，可使用 `clawk.mod` 文件以 go.mod 风格的语法进行描述：```text
sandbox my-project (
vm (
cpu 4
memory 8GiB
image golang:1.25 # any OCI image is the rootfs
)
network ( allow api.example.com )
forwards ( 3000 )
env ( DATABASE_URL ) # forward a host var; values come from your shell
# also: GH=${OTHER_NAME}, LOG=${LOG:-info} defaults, API=${API:?required}
mcp ( # MCP servers, ready on first boot
linear https://mcp.linear.app/mcp header "Authorization: Bearer ${LINEAR_TOKEN}"
)
on create ( "go mod download" )
agent (
instructions "Ask before running destructive commands."
)
)
```
该块是一个*模板*：在沙箱创建时被快照，因此运行中的沙箱永远不会意外变化。完整参考（共享、机密文件、技能、代理内存种子、多仓库工作区根目录）见 **[docs/configuration.md](https://github.com/clawkwork/clawk/blob/main/docs/configuration.md)**；MCP 服务器及其凭据如何不落盘见 **[docs/mcp.md](https://github.com/clawkwork/clawk/blob/main/docs/mcp.md)**；将 Mac 上的 USB 串口板放入沙箱以进行微控制器工作见 **[docs/serial.md](https://github.com/clawkwork/clawk/blob/main/docs/serial.md)**；镜像和自定义客户机内核（包括用于嵌套虚拟化的 KVM 启用内核）见 **[docs/images.md](https://github.com/clawkwork/clawk/blob/main/docs/images.md)**。
## 生命周期```sh
clawk list # all sandboxes
clawk status [<name>] # state, forwards, blocked hosts; --json for scripts
clawk up / down # boot / stop
clawk pause / resume # suspend / resume the running VM in memory
clawk snapshot # save to disk: RAM freed, guest intact; resume restores it
clawk destroy # remove the VM; host-side state persists
```
`clawk snapshot` 是沙箱的休眠机制：客户机的内存会与其磁盘一起保存，下次启动时会将客户机精确恢复到之前的状态。后台进程和开发服务器会像什么都没发生一样继续运行，而 `clawk attach` 会让你重新回到代理面前。完整的命令面、运行器调度以及空闲管理机制（内存回收、准入控制、自动停止）都记录在 **[docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md)** 中。
## 工作原理```text
you ──▶ clawk CLI ──▶ per-sandbox daemon (detached; owns the VM)
├─ gvproxy: in-process userspace TCP/IP stack —
│ the DNS-aware outbound filter the guest can't reconfigure
├─ vsock bridge to the in-guest pty-agent (no sshd)
├─ ssh-agent proxy, macOS (signing stays on the host)
└─ VM: Virtualization.framework (macOS) / firecracker (Linux)
├─ clawk-init, PID 1 (no systemd, no cloud-init)
├─ your repo, live-mounted over virtio-fs
└─ claude / codex / pi / shell on a PTY
```
几个刻意的选择，简述如下：
- **rootfs 是一个普通的 OCI 镜像。** clawk 拉取它（无需 Docker 守护进程），
展平各层，并直接写入一个 ext4 磁盘，无需 root 权限，也无需 loop 设备。
来自同一镜像的每个沙箱都是写时复制克隆（APFS `clonefile` / `FICLONE`），
因此每个沙箱的磁盘成本就是客户机实际写入的量。
- **网络在客户机之下被过滤。** VM 的整个 L3 层（网关、DHCP、DNS、NAT）
是守护进程内部的一个用户态协议栈。每个出站连接和 DNS 应答都会在那里
查询允许列表，即使客户机内的 root 也无法更改它。无需主机 iptables，无需 sudo。
- **单一入口。** 没有 sshd，没有 cloud-init：一个单一的 vsock 代理是进入
客户机的唯一控制路径，每次附加都是 container-exec 风格：一个全新的进程，
断开连接即被销毁。
完整图景（客户机栈、两个提供程序、帧级网络）见 **[ARCHITECTURE.md](https://github.com/clawkwork/clawk/blob/main/ARCHITECTURE.md)**，
每个决策背后的理由见 **[DESIGN.md](https://github.com/clawkwork/clawk/blob/main/DESIGN.md)**。
## 对比
- **容器与 devcontainer。** 它们共享你的内核，并能在减去拒绝规则的情况下看到你的
文件系统；一个内核 bug 或一次错误的挂载就可能暴露主机。Devcontainer 设置通常
会绑定挂载主机 Docker 套接字来构建镜像，从而让容器控制主机守护进程；clawk 则
将 Docker 保留在 VM *内部*。而且无需编写 `Dockerfile`/`devcontainer.json`：
任何 OCI 镜像都可以作为 rootfs。
- **操作系统级代理沙箱。** 像 Anthropic 的 sandbox-runtime 这类工具会在你的真实
机器上应用进程级护栏：适合轻量级规则，但一次策略失误就会暴露一切（包括钥匙串），
而且安装、后台服务或嵌套虚拟机管理程序都难以安全地放行。clawk 将整个工作负载
移到了另一台机器上。
- **通用 VM 管理器（例如 Lima）。** Lima 给你一个 Linux VM；clawk 是在其之上
的一个*工作流*：每个项目一个 VM，挂载仓库，附加并认证代理，默认允许列表出站
并记录拒绝，代理对话在销毁后仍保留，以及一个管理 worktree 和 PR 的票据模式。
（底层两者都使用 Virtualization.framework。）
- **云沙箱。** 本地优先：你的代码永远不会离开机器，没有按小时计费，代理编辑的
worktree 就是编辑器中的那个，在 macOS 上实时挂载（Linux 提供程序目前会在创建时
将其烘焙进去；见 [Roadmap](#roadmap)）。云沙箱适合集群；clawk 是为你桌面上的
机器而设计的。
## 安全模型（及其局限）
两个边界在起作用：VM（主机文件系统除了你挂载的内容外不可见）和出站允许列表
（在客户机之下的用户态强制执行，适用于所有可以离开它的协议）。clawk **不**防护
以下情况：
- **你挂载或允许的内容都会暴露。** Worktree 是可写的，因此代理可以提交糟糕的
代码，或推送到你的转发 ssh-agent 能到达的任何仓库。像审查陌生人的 PR 一样
审查沙箱产出的内容。
- **你推入的机密是可见的。** `files ( … )` 和 `shares ( … )` 的内容、转发的
环境变量以及 Claude 令牌，代理都可以读取（并且，如果某个目的地被允许列表
放行，还可以发送到那里）。分享最少的内容。
- **虚拟机管理程序逃逸。** clawk 依赖 Virtualization.framework/KVM 隔离；
它不会在这些之外增加防御。
如果你找到突破边界的方法（客户机到主机逃逸、网络过滤绕过、凭据泄露），请通过
[SECURITY.md](https://github.com/clawkwork/clawk/blob/main/SECURITY.md) 私下报告。
## 常见问题
**开销如何？**
从镜像首次启动会支付一次性的 rootfs 构建成本（拉取 → 展平 → ext4）。之后，
磁盘是写时复制克隆，内核直接启动，无需固件，也无需安装程序。空闲 VM 会将内存
释放到约 1 GiB，空闲 30 分钟后自动停止，并且可以快照到磁盘，因此只占用存储。
**支持 Intel Mac 吗？Windows 呢？**
不支持。macOS 需要 Apple silicon（macOS 14+）。在 Linux 上，firecracker
提供程序可用但处于实验阶段（见 [docs/commands.md](https://github.com/clawkwork/clawk/blob/main/docs/commands.md#vm-providers)）。
不支持 Windows。
**需要安装 Docker 吗？**
不需要。clawk 自己拉取 OCI 镜像并构建可启动磁盘。Docker *镜像*是输入格式；
Docker 引擎不参与。（在沙箱*内部*运行 Docker 守护进程是一个单独的、可选的功能；
硬件和内核要求见 [Images](https://github.com/clawkwork/clawk/blob/main/docs/images.md#guest-kernel-override)。）
**为什么叫 "clawk"？**
标志是一个爪子；*clawkwork* 是对 *发条橙*（A Clockwork Orange）的戏仿。一个
你可以上紧发条、放出去、随时重置的 VM。
## 路线图
下一步：运行比你的 RAM 能同时容纳的更多的沙箱。
- **带快照的空闲停止。** 手动挂起到磁盘已作为 `clawk snapshot` / `clawk resume`
提供；接下来，*自动*空闲停止也会使用它，这样开发服务器能在停止后存活，
挂起的沙箱只占用磁盘。
- **运行中 VM 的上限。** 当 RAM 已全部提交时，不再拒绝新 VM，而是将最近最少
使用的沙箱挂起到磁盘，然后启动新的。
- **Firecracker 对等。** Linux 上的实时 worktree 传播和主机文件推送。
## 状态
Pre-1.0 且处于积极开发中，演进迅速：预期版本之间会有破坏性变更。CLI 表面变化
最少，内部变化最多，但在 1.0 之前没有任何东西是冻结的。
## 贡献
欢迎提交 Issue 和 PR。构建和测试见 [CONTRIBUTING.md](https://github.com/clawkwork/clawk/blob/main/CONTRIBUTING.md)，
构建方式见 [ARCHITECTURE.md](https://github.com/clawkwork/clawk/blob/main/ARCHITECTURE.md)，未来方向见
[DESIGN.md](https://github.com/clawkwork/clawk/blob/main/DESIGN.md)。
## 许可证
[Apache License 2.0](https://github.com/clawkwork/clawk/blob/main/LICENSE)。clawk 附带两个第三方组件，它们使用各自的许可证
（gvisor-tap-vsock，Apache-2.0；一个 hcsshim ext4 写入器，MIT）；
见 [NOTICE](https://github.com/clawkwork/clawk/blob/main/NOTICE)。
