AB
AB
AiBoss

すべてのカテゴリ

チュートリアル

Jan

チュートリアル

用 Jan Agent 命令行运行自主编码任务

Jan Agent 是一个独立的命令行编码代理，它本身不带本地推理引擎，需要连接云服务商或兼容 OpenAI 的端点。本文从安装、配置服务商、启动安全模式控制台讲起，逐步演示如何让代理读取项目、修改代码、设置完成目标，并整理会话续接、计划模式与常见报错的处理方式。

Jan Agent 是一个独立的命令行编码代理，与 Jan Desktop 桌面应用分开分发。它接收一条自然语言任务，然后在当前项目目录里自行读取文件、执行命令、修改代码，直到任务完成或你叫停。它适合已经习惯在终端里工作、希望把「读代码、改代码、跑测试」这类多步操作交给代理执行的开发者。需要注意，Jan Agent 本身不带本地推理引擎，它必须调用云服务商或一个兼容 OpenAI 的 HTTP 端点，因此你需要准备 API 密钥或可用的端点。如果你更想先了解桌面端的使用方式，可以参考 Jan 的桌面应用文档；本文只讲命令行代理这一条路径。

准备工作

在动手之前，先确认下面几件事，否则后面很容易卡在环境问题上。

  • 终端环境：macOS、Linux 或 Windows 均可。Windows 下使用 PowerShell 执行安装脚本。
  • 模型访问方式：一个云服务商的 API 密钥（例如 Anthropic），或者一个兼容 OpenAI / Anthropic 的 HTTP 端点，或者使用 Tokamak 登录方式（无需自备密钥）。
  • 一个待处理的项目目录：代理会在你启动它的目录里工作，所以最好先进入目标项目再启动。
  • PATH 可用：安装目录需要能被 shell 找到，否则会出现 jan: command not found。

另外要清楚一个前提：Jan Agent 处于预览阶段，安装脚本拉取的是 agent-nightly 通道的构建，属于 nightly 质量。不要把它当成稳定版工具用在关键生产流程上。

操作步骤

第一步：安装 Jan Agent

macOS 与 Linux 使用同一条安装命令：

curl -fsSL https://delta.jan.ai/jan-cli/install-jan-agent.sh | bash

默认安装到 ~/.local/bin。如果想换目录，用 JAN_INSTALL_DIR 覆盖，例如装到 /usr/local/bin：

JAN_INSTALL_DIR=/usr/local/bin curl -fsSL https://delta.jan.ai/jan-cli/install-jan-agent.sh | bash

无论装到哪里，都要确保该目录在 PATH 中。

Windows 使用 PowerShell：

irm https://delta.jan.ai/jan-cli/install-jan-agent.ps1 | iex

这条命令会装到 %USERPROFILE%\.local\bin，而这个目录默认不在 PATH 里。若想一步完成安装并写入用户 PATH，改用下面这条，然后新开一个终端：

& ([scriptblock]::Create((irm https://delta.jan.ai/jan-cli/install-jan-agent.ps1))) -AddToPath

安装完成后验证：

jan --version

如果你已经把 Jan 仓库克隆到本地，也可以用源码构建，避免下载：

scripts/install-jan-agent.sh --source

源码构建不会自动更新，因为更新通道是在 CI 里写入构建产物的。

第二步：配置模型服务商

Jan Agent 没有本地推理引擎，必须先指向一个可用的模型来源。最直接的方式是设置服务商与密钥：

jan config set --provider anthropic --api-key sk-ant-...

如果不想自备密钥，可以登录 Tokamak：

jan login

配置完成后检查当前状态，密钥在输出中会被脱敏：

jan config list

如果你已经在用 Jan Desktop，并且 Desktop 里有一个已启用、端点可用、凭据齐全的 HTTP 服务商，Jan Agent 可以继承它，从而跳过上面的配置步骤。但要注意：仅靠 Desktop 里的本地 llama.cpp 或 MLX 模型是不够的。你需要先在 Desktop 中启动 Local API Server，再把 Jan Agent 指向那个端点。Jan Agent 不会替你启动 Desktop 的推理引擎。

第三步：在安全模式下打开控制台

先进入你要处理的项目目录，然后启动：

jan --safe

这会打开一个交互式控制台：输入消息、回车发送。代理在你启动它的目录中工作。

直接运行 jan 会自动批准所有工具调用。本文的流程使用 --safe，这样文件写入、shell 命令、MCP 工具调用都会先征求你的同意。需要说明的是，--safe 本身并不提供沙箱：shell 默认不受限制，以你的账户权限运行。若想同时启用审批与沙箱，使用：

jan --safe --sandbox

第四步：先给一个可验证的小任务

不要一上来就丢一个大需求。先让它做只读的探查：

Read the README and tell me how to run the tests

项目内的文件读取不需要审批；读取项目之外的文件可能会弹出请求。如果代理在调查过程中请求执行 shell 命令或做修改，先看清楚再批准。

第五步：请求一次代码修改

确认它能正确理解项目之后，再提出改动：

Add a --version flag to the CLI and update the README to document it

在 --safe 下，文件写入会弹出审批，除非已有策略允许规则或此前授予过权限。专门的记忆工具与技能工具不会弹审批，包括写入操作。

审批时你会看到：文件写入请求会显示路径与 diff；shell 请求会显示具体命令。用方向键选择 Allow once 或 Deny，回车确认；也可以直接按 y 允许一次、按 n 拒绝。部分请求还会提供线程级授权，用 a 选择。选择前请读清楚它的标签——对 shell 命令来说，它可能只允许其中列出的命令，或者只允许这一条确切命令，而不是此后所有 shell 调用。走完整套流程时建议一律选 Allow once，避免把授权扩散到后续调用。

第六步：观察执行过程

代理运行期间，每次工具调用都会实时显示，回合结束时给出一行回执，例如：

Worked for 12s • 14:02 • ↑ 43K ↓ 1.1K • 45.6/s

这行信息依次表示：本回合耗时、结束时间、发送的上下文量、生成的 token 数、吞吐速度。任何时候按 Esc 可以取消当前回合，按 Ctrl + D 退出。

第七步：续接上一次会话

会话按项目保存。要接着最近一次继续：

jan --safe -c

也可以在控制台内用 /resume 从列表中选择。

一个完整示例

下面把上面的步骤串成一条可跑通的路径。假设你有一个 Node 项目位于 ~/work/my-cli，其中 tests/auth 下有一个失败的测试。

1. 安装并验证

curl -fsSL https://delta.jan.ai/jan-cli/install-jan-agent.sh | bash
jan --version

2. 配置服务商

jan config set --provider anthropic --api-key sk-ant-...
jan config list

3. 进入项目，以计划模式启动

cd ~/work/my-cli
jan --safe --plan

计划模式下代理只做研究、不改动任何东西，它会分析项目并给出一个方案。等你准备好让它动手，在控制台输入：

/plan exit

注意：退出计划模式后安全模式仍然生效，写入、shell 命令、MCP 调用依旧遵循审批规则。

4. 设定完成标准

与其一轮一轮盯着，不如直接告诉它什么算「做完」：

/goal all tests in tests/auth pass

代理会持续工作并反复检查，直到这个条件成立。

5. 或者从 shell 直接带任务启动

如果你不想先进入控制台再输入，可以把初始任务作为参数传入：

jan --safe --task "fix the failing test in tests/auth"

6. 中途审批与收尾

当它请求写入文件时，检查路径与 diff，按 y 允许一次；请求执行 shell 命令时，检查命令内容再决定。回合结束后看回执里的耗时与 token 用量。按 Ctrl + D 退出。下次回到这个项目，用 jan --safe -c 继续。

注意事项

安全模式不等于沙箱

--safe 只负责在工具调用前征求你的同意，它不会限制命令能做什么。shell 默认不受约束，以你的账户权限运行。要同时获得隔离，需要加上 --sandbox，即 jan --safe --sandbox。

审批授权的范围要看清

线程级授权（按 a 选择）的标签决定了它的实际范围。对 shell 命令而言，它可能只覆盖标签中列出的命令，或者只覆盖那一条确切命令，而不是此后所有 shell 调用。不确定时选 Allow once。

哪些操作不弹审批

项目内的文件读取不需要审批；项目外的读取可能弹出请求。专门的记忆工具与技能工具不弹审批，包括其中的写入操作。文件写入在 --safe 下会弹审批，除非已有策略允许规则或既有授权覆盖。

预览版与更新通道

Jan Agent 是预览产品，安装脚本从 agent-nightly 通道拉取构建，质量按 nightly 预期。源码构建（--source）不会自更新，因为更新通道由 CI 写入。

常见报错

  • jan: command not found：安装目录不在 PATH。安装脚本检测到这种情况时会打印提示。把 ~/.local/bin 加入 shell 配置；Windows 下用 -AddToPath 重跑安装脚本并新开终端。如果安装脚本警告 PATH 上有另一个 jan 排在前面，删除它指出的那个条目。
  • no providers configured：执行 jan config set --provider <id> --api-key <key>，或用 jan login 走 Tokamak。jan config path 会打印它读取的配置文件位置。
  • 代理什么都不改：你可能还在计划模式，输入 /plan exit。
  • 模型报错或用了意料之外的模型：在控制台内用 /model 列出可用模型并当场切换；jan config list 可以查看哪些服务商已接好。

其他细节

取消当前回合用 Esc，退出控制台用 Ctrl + D。会话按项目保存，换目录启动不会看到另一个项目的会话。功能、配额与可用性以官网当前信息为准。

戻る