企业官网建设流程全解析

Jan Agent 如何用 Safe 模式与 Shell 沙箱限制写入和命令权限？

【免费下载链接】janJan is an open source alternative to ChatGPT that runs 100% offline on your computer.项目地址: https://gitcode.com/GitHub_Trending/ja/jan

Jan Agent 的janCLI 默认行为比较宽松：写入和 shell 命令自动批准，且不启用沙箱——你批准过的命令会直接以你自己的权限运行。如果项目目录里保存着无法重建的工作，就需要用Safe 模式让 Agent 在每次写入和执行命令前停下来征求批准，再用Shell 沙箱（--sandbox）把命令限制在项目目录内。本文基于 Run Modes 和 Tool Permissions 两份文档，给出开启、配置与验证这两道防线的完整路径。

适用对象是janCLI 和交互控制台（console）。桌面版聊天 Agent 的沙箱是始终开启且不可关闭的，不属于本文的配置范围。

准备条件：装好 jan 并接入一个 provider

按 QuickStart 安装并验证：

# macOS / Linux curl -fsSL https://delta.jan.ai/jan-cli/install-jan-agent.sh | bash # 验证安装 jan --version

默认安装到~/.local/bin，如提示jan: command not found说明该目录不在PATH中。然后接入一个模型 provider（Jan Agent 不自带推理引擎，必须调用远端 provider）：

jan config set --provider anthropic --api-key sk-ant-... # 换成你自己的 key # 或 jan login # 登录 Tokamak，不需要自己的 key jan config list # 确认配置，key 会被打码

如果已经在用 Jan Desktop，Agent 会直接继承那里的 provider 配置，可以跳过这一步。

用 Safe 模式让每次写入和命令先征求批准

在项目根目录启动会话时加上--safe：

jan --safe

Agent 读取文件不受限，但任何会改变机器的操作都会停下来询问：

write src/cli.rs y yes, once a yes, and don't ask again this session n no

三个选项的含义：

• y：只批准这一次；
• a：批准并在此会话内不再询问同类型调用；
• n：拒绝。

批准前你能看到具体内容：write和edit会先展示 diff，bash会展示将要执行的完整命令。注意a的授权按能力（capability）而非单个工具生效——对一条 shell 命令选了a，之后所有 shell 命令都免询问，这正是文档建议只在确实需要连续放行时用a、其余情况用y的原因。授权不会写盘，新会话重新开始时又是谨慎的默认状态。

两点限制需要记住：

1. --safe在启动时决定，无法在会话中途开关。谨慎启动的会话会一直保持谨慎。
2. 无头环境（CI、stdin 没有 TTY）不要传--safe：提示无法被回答，所有写入提示都会被拒绝，运行会卡死在第一次写入上。

无脚本场景下，jan cli agent run也支持同样的旗标，例如jan cli agent run --safe "run the migration"表示逐步批准。

开启 Shell 沙箱：把命令限制在项目目录内

Safe 模式解决的是"要不要问你"，沙箱解决的是"命令能碰到多大范围"。文档明确警告：沙箱关闭时，你批准的 shell 命令就运行在完全属于你自己的权限之下，没有任何东西把它限制在项目内。

Jan 用操作系统级的隔离机制实现沙箱：Linux 上 bubblewrap、macOS 上 Seatbelt、Windows 上 AppContainer。沙箱开启后，命令只能写入项目目录及其 scratch 目录；读取稍宽松——CLI 默认保持$HOME可读，以便git和ssh的 credential helper 正常工作。

沙箱有三个配置层级，从最具体到最宽泛：

# 1. 仅当前会话 jan --sandbox # 仅当前会话关闭，可覆盖下面的持久设置 jan --no-sandbox

# 2. .jan/agent/agent.toml —— 对该项目的所有检出者生效 [tools] sandbox = true

# 3. ~/.jan/config.toml —— 对你工作过的所有项目生效 sandbox = true

优先级是：命令行旗标 > 项目文件 > 全局配置 > 默认值（CLI 上默认关闭）。--no-sandbox的存在就是为了让持久开启沙箱后仍能临时运行某一条不受限的命令。

写入限制之外，还可以收紧读取和网络：

# .jan/agent/agent.toml [tools] sandbox = true # 关闭 $HOME 读取（默认开着，供 git/ssh 凭证助手使用） allow_home_read = false # 让 CLI Agent 的 shell 命令离线。注意：沙箱开启时网络默认是放开的 allow_network = false

网络访问是沙箱的属性，只在沙箱开启时才生效；沙箱关闭时命令拥有你本机的全部网络权限。CLI 代码屏 Agent 的网络默认开启（文档理由是编码 Agent 需要curl、git fetch、安装依赖），桌面聊天 Agent 默认关闭，两者默认值不同。

如果系统无法建立任何沙箱后端，行为是拒绝运行而不是降级：bash工具直接不可用，Agent 不会在不受限状态下执行命令。

验证沙箱实际生效状态

用jan cli agent status打印解析后的项目配置（JSON），其中包含沙箱状态：

jan cli agent status jan cli agent status --project ~/code/app

输出中的沙箱字段形如（文档示例）：

"sandbox": { "enabled": false, "backend": "bubblewrap" }

• enabled：本次运行是否会启用沙箱；
• backend：将使用的隔离后端。出现none表示这台机器上没有任何可用后端，此时若enabled为true，组合效果就是bash被整体扣留。

检查顺序：先确认enabled是否符合预期，再看backend是否为none。同时jan cli agent status --project .还可以用来在首次使用前脚手架出.jan/agent/目录。

边界与仍然存在的风险

即使同时开启 Safe 模式和沙箱，以下事实来自文档，写操作前值得确认：

• bash没有路径参数，在项目根目录执行。受路径检查约束的是带路径的工具（写入项目外的路径会被拒绝，指向项目外的符号链接也会被拒绝），但你批准过的命令在沙箱关闭时仍可触达项目之外——文档因此把 plan 模式（jan --plan，所有写入和命令被硬阻断）称为硬边界。沙箱开启后这一风险被 OS 级隔离覆盖。
• 无论什么模式都有不可解除的拒绝项：.jan/agent/内部（Agent 无法改写自己的权限配置）、agent.toml中[tools] deny列出的工具，以及 plan 模式期间的一切写入和命令。
• 项目策略文件也能收紧工具面：.jan/agent/agent.toml的[tools]支持default = "read-only" | "deny" | "allow"，以及allow/deny/allow_write列表；deny永远优先于allow，同一个工具出现在两个列表里会被拒绝。
• 子 Agent 的工具集只能收窄、不能放大，委派不能用来绕过上述策略。
• 无头运行：CI 场景依赖的是默认自动批准（没有人回答提示），文档明确不要在 CI 里传--safe；此时若希望保留 OS 级隔离，应使用--sandbox或项目级sandbox = true。

下一步

文档给出的延伸方向：

• 用 project-config.mdx 中介绍的agent.toml/AGENT.md固定项目级工具策略，提交进版本库让整个团队得到同一套约束（threads/则建议加入.gitignore）；
• 需要只读调研时使用 run-modes.mdx 中的 plan 模式：jan --plan启动，会话内用/plan切换、/plan exit退出；
• 完整参数与无头运行（含--output-format json、CI 用法）见 CLI Reference，权限模型细节见 Tool Permissions。

【免费下载链接】janJan is an open source alternative to ChatGPT that runs 100% offline on your computer.项目地址: https://gitcode.com/GitHub_Trending/ja/jan