fix(sandbox): macOS 沙盒 deny lark-cli 认证/配置路径，agent 在沙盒内无法读 auth/whoami/doctor（Full Disk Access 无法覆盖 Seatbelt）

[alexander2618]

问题

开启文件沙盒（sandbox: true / BOTMUX_SANDBOX=1 / 主机 device enroll 强制凭据隔离）后，在 macOS 上 agent 在沙盒内跑 lark-cli（以及类似把认证/配置写到用户目录下的 CLI）时，认证与配置信息读不到：

lark-cli doctor   → config_file: operation not permitted
lark-cli whoami   → not configured
lark-cli auth status → not configured
node 直接 stat/读取 lark-cli 配置文件 → EPERM

关键现象：在系统设置里给 node、codex「Full Disk Access / 全磁盘访问权限」也不起作用。

根因

macOS 有两套互相独立的强制访问控制层：

1. TCC / Full Disk Access（系统设置 → 隐私与安全性）——管隐私弹窗层。
2. Seatbelt（sandbox-exec / sandbox_init）——内核级 MAC，botmux 用 sandbox-exec -f <profile.sb> 包住 CLI 进程强制施加。

botmux 在 src/worker.ts:7740-7751 把 spawn 改成 sandbox-exec -f <profile> <cliBin> ...，profile 由 src/adapters/cli/fs-policy.ts:500 的 compileToSeatbelt() 生成，起手 (deny default)（line 503）后逐路径 emit (deny file-read* (subpath "..."))。这些 deny 在 vnode 层由内核拦，和 TCC 完全无关——所以给 node/codex 全磁盘访问对 seatbelt 的 deny 规则没有任何作用，读被拒路径照样返回 EPERM。这正解释了「给全磁盘访问也不行」。

涉及的 deny 规则

src/adapters/cli/fs-policy.ts baseline 里直接 deny 的 lark-cli 路径：

行	规则	路径
300	deny	~/.lark-cli
330	deny	~/Library/Application Support/lark-cli
326	deny	~/Library/Keychains

macOS 上 lark-cli 的用户登录态 / whoami / auth token / config_file 就落在这两个被 deny 的目录下。沙盒只开了两个极窄的只读 carve-out（fs-policy.ts:434-437）：

~/Library/Application Support/lark-cli/master.key.file
~/Library/Application Support/lark-cli/appsecret_<appId>.enc

外加可写目录 ~/.lark-cli-bots/<appId>（line 383，per-bot 身份配置）。

为什么 doctor / whoami / auth status 失败

这条 carve-out 的注释（fs-policy.ts:423-433）写得很清楚：它只验证过 lark-cli auth scopes（botmux 自己的 send 链路用），设计意图是「bot 自己的 send 走 BOT_HOME 里的 send-cred.json，不读这个 key store」。即 carve-out 是按 botmux send 链路的最小需求设计的，没有覆盖 agent 直接跑 lark-cli doctor / whoami / auth status 的需求：

• whoami → 要读用户身份 token（在 deny 的 ~/.lark-cli / ~/Library/Application Support/lark-cli）→ EPERM → "not configured"
• auth status → 要读登录/授权状态（同上被 deny）→ "not configured"
• doctor config_file → 要读 lark-cli 配置文件（在 deny 区）→ "operation not permitted"

对「botmux send 链路」符合设计；对「agent 在沙盒内裸跑 lark-cli 自省/操作身份」是覆盖缺口。

影响面

• 平台：仅 macOS（Linux 走 bwrap，lark-cli 密钥放 per-bot ~/.lark-cli-bots/<self>，已 readWrite，不受影响——见 fs-policy.ts:432 注释）
• 会话类型：所有开启沙盒的 bot 会话（sandbox: true、readIsolation、device enroll 强制隔离）
• CLI：lark-cli 及任何把认证/配置写到 ~/Library/Application Support/<app> 或 ~/.<app> 下、且未被 carve-out 显式放行的 CLI

建议的解法方向（待讨论）

1. 关沙盒：受影响 bot 的 bots.json 设 "sandbox": false，并确保无 BOTMUX_SANDBOX=1 全局强制、主机未 device enroll——最直接，但失去跨 bot 隔离。
2. sandboxPaths 开洞：在 bot 配置里把所需路径加进 sandboxPaths.readOnly（user 源 rank=3 > baseline rank=0，能覆盖 line 300/330 的 deny）。但整目录开 ~/Library/Application Support/lark-cli 会把所有 bot 的 appsecret 密文 + master key 暴露给当前 bot 的 agent，等于回到重构前的跨 bot 泄漏面（line 327-330 注释专门提到的那条），是安全回退。
3. 扩 carve-out（推荐）：先查清 lark-cli 在 macOS 上 whoami / auth status / doctor 实际读哪几个文件，把本 bot 自己需要的文件以本 bot 限定方式补成只读 carve-out（同 appsecret_<appId>.enc 做法），不破坏跨 bot 隔离。

环境

• 平台：macOS
• 沙盒：开启
• 相关代码：
  • src/adapters/cli/fs-policy.ts:300,326,330（deny）
  • src/adapters/cli/fs-policy.ts:434-437（lark-cli carve-out）
  • src/adapters/cli/fs-policy.ts:500-560（compileToSeatbelt）
  • src/worker.ts:7740-7751（sandbox-exec -f 包 spawn）
  • src/adapters/backend/sandbox.ts:232（sandboxEnabled）

[xu4wang]

lark-cli 多机器人应用隔离配置指南

目标：让每个 botmux 机器人在调用 lark-cli 操作飞书时，使用它自己的飞书应用，从而按机器人粒度独立管理数据访问权限——而不是所有机器人共用同一个应用、共享同一套权限。

一、背景与问题

同一台机器上跑多个 botmux 机器人时，它们调用 lark-cli 默认会读取同一份全局配置（~/.lark-cli/config.json），因此无论哪个机器人发起操作，访问飞书用的都是同一个应用身份。

这带来两个问题：

• 权限无法隔离：无法做到"A 机器人能读文档、B 机器人只能发消息"这类按机器人的权限管控。

• 身份混淆：机器人创建的文档、发出的操作，作者都是那个共享应用，而非机器人自己。

关键前提：每个 botmux 机器人在 ~/.botmux/bots.json 里其实已各自绑定了一个独立的飞书应用（larkAppId / larkAppSecret）。我们要做的，就是让 lark-cli 在每个机器人的会话里改用它对应的那个应用。

二、实现原理

方案依赖两个现成的"钩子"，把它们串起来即可，无需改动 botmux 本身：

钩子	说明
BOTMUX_LARK_APP_ID	botmux 启动每个机器人会话时，已自动注入这个环境变量，值=该机器人的飞书 App ID。
LARKSUITE_CLI_CONFIG_DIR	lark-cli 支持用这个环境变量覆盖配置目录。指向哪个目录，就用那个目录里的应用配置。

解析链路（机器人会话内每次调用 lark-cli 时自动发生）：

机器人会话
  └─ 环境变量 BOTMUX_LARK_APP_ID = cli_xxx   （botmux 注入）
       └─ ~/.zshenv 据此设置
            LARKSUITE_CLI_CONFIG_DIR = ~/.lark-cli-bots/cli_xxx
                 └─ lark-cli 读取该目录配置
                      └─ 使用 cli_xxx 这个应用（bot-only 身份）

为什么是 .zshenv 而不是 .zshrc？ Agent 执行命令用的是非交互 shell，只加载 ~/.zshenv，不加载 ~/.zshrc。放错文件会导致配置不生效（这是实际踩过的坑）。

三、配置步骤

步骤 1：在 ~/.zshenv 加入跟随逻辑

追加以下内容。机器人会话内 BOTMUX_LARK_APP_ID 存在 → 指向专属配置目录；普通终端里该变量为空 → 自动回退到默认 ~/.lark-cli，手动使用不受影响。

if [ -n "$BOTMUX_LARK_APP_ID" ]; then
  export LARKSUITE_CLI_CONFIG_DIR="$HOME/.lark-cli-bots/$BOTMUX_LARK_APP_ID"
fi

步骤 2：为每个机器人建独立配置（用它自己的应用）

对每个机器人，建一个以 App ID 命名的配置目录，并用该机器人在 bots.json 里的 larkAppId / larkAppSecret 初始化，身份设为 bot-only（不登录用户、不冒充个人）。

DIR="$HOME/.lark-cli-bots/$APPID"
mkdir -p "$DIR"
printf '%s' "$SECRET" | LARKSUITE_CLI_CONFIG_DIR="$DIR" \
  lark-cli config init --app-id "$APPID" --app-secret-stdin --brand feishu --force-init
LARKSUITE_CLI_CONFIG_DIR="$DIR" lark-cli config default-as bot

bot-only 身份的含义：机器人只能访问显式分享给它那个应用的文档/表格，碰不到任何人的私人云空间、日历、邮箱。这正是按机器人隔离权限的基础。

步骤 3：在开放平台给每个应用开通 scope（数据权限总开关）

scope 决定"这个机器人能做哪类飞书操作"，是按机器人管控数据权限的核心。到开发者后台逐个应用开通，开完创建版本并发布才生效。

后台权限页地址格式：https://open.feishu.cn/app/<appId>/auth

按需勾选对应能力的 scope，例如：

能力	代表性 scope
云文档 Docx	docx:document:readonly、docs:document.content:read
电子表格	sheets:spreadsheet:read
云盘 Drive	drive:file:download、drive:drive.metadata:readonly
IM 消息	im:message、im:message:readonly
群组信息	im:chat:read、im:chat.members:read
妙记 Minutes	minutes:minutes:readonly、minutes:minutes.transcript:export 等

四、验证

在某个机器人的会话里执行，确认 lark-cli 已用上该机器人自己的应用：

# 看当前 lark-cli 用的是哪个应用
lark-cli config show        # appId 应为该机器人的 App ID
                            # 配置路径应为 ~/.lark-cli-bots/<appId>/config.json

# 实测 bot 身份能力（列出机器人所在的群）
lark-cli im +chat-list --as bot

进一步可让机器人以 bot 身份创建一篇文档，确认作者显示为该机器人本身；如需把文档归属转给某人，用：

lark-cli drive permission.members transfer_owner \
  --params '{"token":"<docToken>","type":"docx"}' \
  --data '{"member_type":"openid","member_id":"<userOpenId>"}' --yes

五、边界与注意事项

• scope ≠ 具体文件访问权。开了 scope 只是有了"能力"；要让机器人真能读某份文档，那份文件还得分享给对应应用（或放进机器人所在的群 / 知识库）。

• 换应用后旧文档会读不到。之前分享给共享应用的文档，机器人换成自己的应用后需要重新分享给新应用。这是隔离生效的正常表现。

• bot 不是所有者就删不掉。机器人把文档 owner 转给他人后，自身降为协作者，无权删除该文档——符合权限预期。

• 妙记多为个人资源。即便开了 scope，bot 通常只能访问"分享给该应用 / 由应用创建"的妙记，纯私人妙记可能仍受限。

六、新增机器人时怎么扩展

非常简单，只需重复步骤 2 + 步骤 3：

1. 用新机器人的 App ID / Secret 跑一次步骤 2，建好它的专属配置目录。

2. 在开放平台给新应用开通所需 scope 并发布。

步骤 1 的 ~/.zshenv 逻辑是通用的，无需改动——只要 botmux 注入了 BOTMUX_LARK_APP_ID，新机器人会自动走对它的配置目录。

一句话总结：.zshenv 一段跟随逻辑（一次性）＋ 每个机器人一个独立配置目录（绑自己的应用）＋ 后台按应用开 scope（控数据权限）＝ 干净的按机器人隔离。

[xu4wang]

@alexander2618 MacOS下的sandbox基线是基于把lark-cli配置拆分，按照bot分割的方案配置的。 抱歉文档中没有写清楚。具体筛分方法见上面，让每个bot用自己的appID使用lark-cli。 在sandbox下没问题。

[xu4wang]

@alexander2618 顺手把这条前置条件补成正式文档了：#701（纯文档，3 files +143，零代码改动）。

新增 docs/lark-cli-per-bot.md，并在 docs/file-sandbox.md 的「启用」段、docs/isolated-bot-deploy.md 的部署步骤 + 排错表里加了交叉链接。内容按 白名单怎么切的 → 原理链路（BOTMUX_LARK_APP_ID → LARKSUITE_CLI_CONFIG_DIR）→ 配置步骤 → 验证 → 边界 → 排错表 组织。

基于你 issue 里那份指南，另外补了几条读码/实测核出来的边界，都是踩过才知道的：

• 沙盒下只有 bot 身份可用：用户登录态 <appId>_<openId>.enc 不在 carve-out 里，--as user 读不到。
• 不要用 sandboxPaths.readOnly 整目录开洞。user rank 3 > baseline 0，确实能覆盖 deny，但那等于把所有 bot 的密文 + master key 一起交给当前 agent。
• no-transport turn（apiOnly bot / HTTP 虚拟会话）下整个飞书授权面被冻结，per-bot 目录和 keystore carve-out 都不发放，lark-cli 一律不可用。
• lark-cli 1.0.56 没有 whoami 子命令（issue 标题里提到的那个），身份自查用 auth status / config show。
• 「给 node/codex 开完全磁盘访问权限为什么没用」——TCC 和 Seatbelt 是两套独立机制，FDA 不覆盖 sandbox profile。这条单独进了排错表，是本 issue 里最费时间的一个误判，值得让人一眼看到。

另外两件刻意没做、留给后续单独提的代码改动，PR 正文里也列了：

1. worker spawn 时注入 LARKSUITE_CLI_CONFIG_DIR=$HOME/.lark-cli-bots/<appId>（仅当目录存在）。现方案依赖用户手改 ~/.zshenv，在不经登录 shell 的 spawn 路径、非 zsh 机器上会静默失效。
2. 沙盒已开启但 ~/.lark-cli-bots/<appId>/config.json 缺失时，spawn 前 warn 一下。

文档有说不清或跟你实际配置对不上的地方，直接在 PR 上提。