Jan 0.8.7 常用 CLI 命令与工具详解

目标：完整覆盖 Jan 终端代理 Jan Agent 的命令行工具 jan（0.8.7-66）：安装、TUI 交互模式与无头（headless）模式、agent/models/mcp/threads 四大子命令组，以及 config/login/auth/usage/plugin/update 辅助命令。全部命令与输出均在 Ubuntu 22.04（x86_64）实测采集。

一、环境信息

操作系统：Ubuntu 22.04（x86_64，jammy）
软件版本：Jan Agent 0.8.7-66（agent-nightly 通道，官方最新构建，查询日期 2026-10-22）
二进制形态：单个约 20MB 的 jan 可执行文件，安装到 ~/.local/bin/
与桌面版的关系：Jan Desktop 0.8.5 起不再捆绑 jan 命令，终端代理是独立安装的 Jan Agent；两者共享同一数据区 ~/.local/share/Jan/data（如 MCP 配置）
定位说明：jan 本身不内置本地推理引擎，模型由远程 Provider（OpenAI/Anthropic/Groq 等）提供，或复用桌面应用已配置的 Provider

二、工具概览

不带参数运行 jan 进入交互式代理控制台（TUI）；带 cli 子命令则以无头方式运行代理任务、管理模型与线程。实测 jan --help 给出的命令结构：

命令	作用
`jan`（无参数）	交互式 TUI 控制台，与可执行工具的模型对话
`jan cli`	无头模式：运行代理任务、管理模型/线程/MCP
`jan login`	登录 Tokamak，密钥存入 `~/.jan/config.toml`
`jan auth`	查看或管理 Tokamak 登录态（status/logout）
`jan usage`	读取 Provider 用量与消费记录
`jan config`	管理 `~/.jan/config.toml` 中的 Provider 凭据
`jan plugin`	管理项目级插件与技能
`jan mcp`	把 Jan 内置工具以 MCP 服务暴露给其他代理
`jan update`	更新到所在通道的最新构建

三、前置条件与安装

前提：可访问外网（或已配置代理），用户对 ~/.local/bin 有写权限。官方一键安装脚本实测：

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

实测输出（节选）：

resolving the latest agent-nightly build
downloading 0.8.7-66 from https://delta.jan.ai/agent-nightly/jan-agent-linux-x86_64-0.8.7-66.tar.gz
sha256 verified
installed /root/.local/bin/jan (agent-nightly 0.8.7-66)
note: /root/.local/bin is not on your PATH; add it to your shell profile

要点：脚本自动完成"解析最新构建 → 下载 tar.gz → sha256 校验 → 安装到 ~/.local/bin/jan"。若 ~/.local/bin 不在 PATH 中会给出提示，将其加入 shell 配置：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

确认版本：

jan --version

实测输出：

jan 0.8.7-66

⚠️ 注意：安装通道为 agent-nightly（每日构建），版本号形如 0.8.7-66（主版本-构建号），与桌面版的 0.8.7 各自独立演进。

四、顶层命令与 TUI 启动参数

jan 不带子命令即进入 TUI。启动参数全集（实测 jan --help）：

参数	作用
`--project <PROJECT>`	指定项目根目录（其 `agent.toml` 位于 `~/.jan/projects/<slug>/`），默认 `.`
`--task <TASK>`	首条消息，直接以其开始对话
`--model <MODEL>`	覆盖 `agent.toml` 的 `[agent].model`
`--image <IMAGES>`	附带图片文件，可重复
`--provider <PROVIDER>`	指定单一 Provider（如 `anthropic`）
`--api-key <API_KEY>`	对应 Provider 的密钥（否则读 `JAN_API_KEY`/`<PROVIDER>_API_KEY`）
`--base-url <URL>`	自定义端点（如网关），否则读 `JAN_BASE_URL`
`--safe`	写文件、执行命令、调用 MCP 工具前先请求确认
`--resume [<ID>]` / `-c`	恢复最近会话或按 ID 前缀恢复指定会话
`--fork-session`	将恢复的会话分支为新线程，原会话保留可恢复
`--plan`	以只读规划模式启动（等同 `/plan`）
`--sandbox` / `--no-sandbox`	是否在 OS 沙箱（bubblewrap/Seatbelt/AppContainer）中执行 shell 命令
`--allow-escalation`	允许沙箱内命令申请越出沙箱执行
`--worktree` / `--no-worktree`	是否在专用 git worktree 中工作

常用组合（来自实测帮助页示例）：

jan                                  # 交互式控制台
jan --safe                           # 写操作前询问
jan --task "fix the failing test"    # 带首条消息启动
jan -c                               # 恢复最近会话
jan --worktree                       # 在独立 worktree 中工作

五、jan cli agent：代理任务执行

jan cli agent 包含 6 个子命令（实测 jan cli agent --help）：

子命令	作用
`run`	运行代理循环直至完成或达到 `--max-turns` 上限
`step`	单轮执行（调试用）
`status`	以 JSON 输出解析后的项目配置与可用 Provider
`schema`	输出协议 JSON Schema
`rpc`	在 stdin/stdout 上以 JSON-RPC 提供可寻址会话
`rpc-schema`	输出 RPC 请求与事件 Schema

5.1 jan cli agent run（无头执行任务）

最常用的一等命令。未配置任何模型凭据时的真实表现：

jan cli agent run "列出当前目录文件" --max-turns 2

实测输出：

Error: no model specified: run `jan login` to sign in to Tokamak, or pass --model, set [agent].model in agent.toml, set default_model in ~/.jan/config.toml, or select a model in the desktop app

该报错给出模型解析的全部路径（按优先级）：命令行 --model > 项目 agent.toml 的 [agent].model > 全局 config.toml 的 default_model > 桌面应用所选模型 > jan login 登录 Tokamak。配置任一来源后重跑即可正常执行。

5.2 jan cli agent status（查看解析后的配置）

jan cli agent status --project /root/demo

实测输出为完整 JSON（节选关键字段）：

{
  "project": "/root/demo",
  "data_folder": "/root/.local/share/Jan/data",
  "model": null,
  "max_session_tokens": 128000,
  "max_session_tokens_source": "default",
  "tools": { "default": "read-only", "allow": [], "deny": [] },
  "sandbox": { "enabled": false, "backend": "none" },
  "hooks": [],
  "providers": [
    { "provider": "anthropic", "base_url": "https://api.anthropic.com/v1", "has_api_key": false, "models": 8 },
    { "provider": "openai", "base_url": "https://api.openai.com/v1", "has_api_key": false, "models": 8 },
    { "provider": "groq", "base_url": "https://api.groq.com/openai/v1", "has_api_key": false, "models": 8 }
  ]
}

用途：排障时确认项目目录、生效模型、工具权限基线（默认 read-only）、沙箱状态，以及各 Provider 的密钥有无（has_api_key）。providers[].models 是该 Provider 内置模型清单条数，完整清单见第六章。

六、jan cli models：模型清单管理

jan cli models list

以 JSON 输出全部已配置 Provider 的模型（密钥脱敏）。实测输出节选（每个条目含 id/provider/base_url/api_type/has_api_key）：

[
  {
    "id": "claude-sonnet-4-5",
    "provider": "anthropic",
    "base_url": "https://api.anthropic.com/v1",
    "api_type": "anthropic",
    "has_api_key": false
  },
  {
    "id": "llama-3.3-70b-versatile",
    "provider": "groq",
    "base_url": "https://api.groq.com/openai/v1",
    "api_type": null,
    "has_api_key": false
  }
]

未配置任何 Provider 凭据时执行刷新：

jan cli models refresh

实测输出：

no providers to refresh

refresh 的作用是重新读取每个 Provider 的 /models 端点并替换本地存储的模型清单；至少配置一个带密钥的 Provider 后才有实际效果。

七、jan cli mcp：MCP 服务器管理

管理 mcp_config.json（与桌面应用共用）中的 MCP 服务器，子命令全集（实测 jan cli mcp --help）：list/get/add/remove/enable/disable。

查看现有服务器（实测 jan cli mcp list，输出 JSON 数组，每项含 name/active/type/command/args/url/env/headers，内置 browsermcp、fetch、filesystem、sequential-thinking、serper 等，均默认 active: false；桌面专属的浏览器桥接不在列表中）。

新增一个文件系统 MCP 服务器：

jan cli mcp add demo-fs --command npx --arg -y --arg @modelcontextprotocol/server-filesystem --arg /root/demo

实测输出：

saved server 'demo-fs' to mcp_config.json

查询单个：

jan cli mcp get demo-fs

实测输出：

{
  "name": "demo-fs",
  "active": false,
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/root/demo"],
  "url": null,
  "env": {},
  "headers": {}
}

启用/停用/删除（实测输出逐条）：

jan cli mcp disable demo-fs   →  disabled server 'demo-fs'
jan cli mcp enable demo-fs    →  enabled server 'demo-fs'
jan cli mcp remove demo-fs    →  removed server 'demo-fs' from mcp_config.json

💡 说明：add 对同名服务器执行覆盖（官方帮助原文：add 或 replace an existing one with the same name），可作为修改手段；新加服务器默认 active: false，需 enable 后下一会话才会连接。

八、jan cli threads：会话线程管理

检查桌面应用与 CLI 保存的会话（输出 JSON，可配合 jq 过滤）。子命令（实测 jan cli threads --help）：list/get <ID>/messages <THREAD_ID>/delete <ID>。

jan cli threads list

实测输出（全新环境无任何会话）：

[]

产生会话后（TUI 对话或 agent run），list 返回线程元数据数组，get/messages 按 ID 查详情，delete 永久删除线程及其全部消息。

九、凭据与辅助命令

9.1 jan config：Provider 凭据管理

jan config set --provider openai --api-key sk-demo-q1w2e3r4

实测输出：

Updated provider 'openai' in /root/.jan/config.toml

写入后的 ~/.jan/config.toml：

[providers.openai]
api_key = "sk-demo-q1w2e3r4"

set 完整参数：--provider（必填）、--api-key、--base-url（自建网关）、--model（可重复，替换模型列表）、--api-type（openai/anthropic）。删除凭据 jan config unset --provider openai；核对用：

jan config path   # 输出 /root/.jan/config.toml
jan config list   # JSON：config_path 与 providers[]（has_api_key 布尔，不回显明文）

jan login 交互式登录 Tokamak 并把密钥写入 ~/.jan/config.toml。jan auth 有 status（当前账号、端点、密钥 ID 与有效期，并在线校验）与 logout（服务端吊销并清除本地）两个子命令（实测 jan auth --help）。

9.3 jan usage：用量与消费

读取 Provider 用量 API 的记录，子命令（实测 jan usage --help）：account（跨凭据汇总）、daily（按日合计）、requests（最近请求）、limits（限额状态）、generation（按执行 ID 追踪单次）、correlate（按客户端请求 ID 关联）。全局选项 --json 原样输出响应体。

9.4 jan plugin 与 jan mcp serve

jan plugin（实测 --help）：list/install（git URL 或市场插件）/remove/search，管理项目级插件；市场地址在 agent.toml 的 [plugins] 段配置。jan mcp serve 把 Jan 内置工具以 MCP 服务暴露给其他代理消费。

9.5 jan update：自更新

jan update --check

实测输出：

Already on the latest agent-nightly build (0.8.7-66)

去掉 --check 即执行更新（下载所在通道最新构建并替换二进制）。

十、注意事项

密钥安全：~/.jan/config.toml 中的 API Key 为明文 TOML，应保证文件权限仅当前用户可读（chmod 600），不要把该文件提交进代码仓库或在输出中回显；
遥测与更新检查：jan 每 24 小时发送一次匿名使用 ping（版本、OS/架构、随机安装 ID），与更新检查同一端点；离线或合规环境设置 JAN_CLI_NO_UPDATE_CHECK 同时关闭两者；
keyring 降级告警：无桌面钥匙串的环境执行模型相关命令会出现 WARN app_lib::core::server::provider_secrets Keyring unavailable ... using encrypted file fallback，属预期行为，密钥自动改用加密文件存储；
与桌面版共享状态：mcp_config.json、数据区目录与桌面应用共用，CLI 侧 jan cli mcp 的增删会直接反映到桌面端设置；
版本通道：Agent 为 agent-nightly 每日构建，生产环境锁定具体版本号（如 0.8.7-66）并在变更前阅读官方 changelog。

十一、常见问题

Q1：jan: command not found？

安装脚本已提示 ~/.local/bin is not on your PATH。将 export PATH="$HOME/.local/bin:$PATH" 写入 ~/.bashrc 后 source ~/.bashrc，或直接用全路径 ~/.local/bin/jan。

Q2：安装脚本开头打印 BASH_SOURCE[0]: unbound variable 但仍安装成功？

实测该提示出现在脚本以 curl | bash 方式执行时（脚本内部引用 BASH_SOURCE[0] 触发），不影响下载、校验与安装流程，忽略即可。

Q3：jan cli agent run 报 no model specified？

模型解析链为空。最少两步解决：jan config set --provider <ID> --api-key <KEY> 配凭据，再用 --model <ID> 或在 agent.toml/config.toml 指定默认模型；用 jan cli agent status 确认 "model" 字段与 has_api_key。

Q4：jan cli models refresh 提示 no providers to refresh？

~/.jan/config.toml 中没有任何已配置凭据的 Provider。先 jan config set 至少一个 Provider，再刷新。

Q5：CLI 能用本地模型吗？

jan 本体不捆绑推理引擎。本地推理由 Jan Desktop 的 llama.cpp 引擎承担并暴露 OpenAI 兼容端点（默认 127.0.0.1:1337/v1）；CLI 侧把该端点配置为自定义 Provider（jan config set --provider <ID> --api-key <KEY> --base-url http://127.0.0.1:1337/v1）即可让终端代理调用本地模型。桌面应用的安装与引擎配置见本专栏安装篇与配置参数篇。

十二、参考链接

官方 Agent 文档 - CLI 参考（含安装脚本与全部子命令）：https://docs.jan.ai/agent/cli （查询日期 2026-10-22）
官方 Agent 文档 - Quickstart：https://docs.jan.ai/agent/quickstart （查询日期 2026-10-22）
官方 Agent 文档 - Project Configuration（agent.toml）：https://docs.jan.ai/agent/project-config （查询日期 2026-10-22）
官方 Agent 文档 - MCP（jan mcp serve 与 cli mcp）：https://docs.jan.ai/agent/mcp （查询日期 2026-10-22）
Jan Agent 安装脚本（本篇实测所用）：https://delta.jan.ai/jan-cli/install-jan-agent.sh （查询日期 2026-10-22）
GitHub 仓库 janhq/jan（源码与 Releases）：https://github.com/janhq/jan （查询日期 2026-10-22）

Jan 0.8.7 常用 CLI 命令与工具详解

Jan 0.8.7 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件与安装

四、顶层命令与 TUI 启动参数

五、jan cli agent：代理任务执行

5.1 jan cli agent run（无头执行任务）

5.2 jan cli agent status（查看解析后的配置）

六、jan cli models：模型清单管理

七、jan cli mcp：MCP 服务器管理

八、jan cli threads：会话线程管理

九、凭据与辅助命令

9.1 jan config：Provider 凭据管理

9.2 jan login / jan auth：Tokamak 登录态

9.3 jan usage：用量与消费

9.4 jan plugin 与 jan mcp serve

9.5 jan update：自更新

十、注意事项

十一、常见问题

十二、参考链接