loki-mode

Loki Mode

你的 Agent 说任务完成了。Loki 会证明这一点：它是一款自主编码 Agent，可将任务或问题转化为经过验证的拉取请求，并附上可自行核验的签名回执。

网站 | 快速入门 | 安装指南 | 用户指南 | CLI 参考 | 与 opencode 对比 | 更新日志

上方的 npm 徽章显示当前版本；发行说明请参阅 CHANGELOG.md。

CLI 参考：docs/CLI-REFERENCE.md（根据命令注册表生成）。

安装

npm install -g loki-mode

npm 包会将引擎所需的 Bun 运行时作为可选依赖项安装。其他安装方式：bun install -g loki-mode、brew tap asklokesh/tap && brew install loki-mode，或 docker pull asklokesh/loki-mode:latest（Docker 指南）。使用 loki self-update 升级。

想在安装或花费之前先看看效果？

npx loki-mode start   # no git repo: a real receipt, no key, no spend
npx loki-mode tour    # the same receipt when you are already inside a repo

npx 首次运行时会下载软件包，因此这一步需要联网。回执本身可离线重放和核验，无需服务提供方，也无需密钥。

npx loki-mode wow     # a provider is ready: one tiny real task in a temp repo, its own receipt

首次运行

Loki 需要一个模型。Claude Code（claude）是默认服务提供方：请安装并登录。主流程也可以使用捆绑的 Agent SDK 和 ANTHROPIC_API_KEY，替代 CLI。其他编码 CLI 均为可选项。请参阅要求。

cd your-repo
loki setup                                   # first-run wizard (or: loki doctor --fix)
loki start "add rate limiting to /api/login" # the primary path: build, verify, seal a receipt, open a PR
loki start prd.md                            # same, from a PRD file
loki start owner/repo#123                    # same, from a GitHub, GitLab or Jira issue
loki edit "rename fooBar to foo_bar"         # one small change, no loop
loki chat                                    # interactive alternative: Plan and Build modes

loki start、loki "<task>"、loki owner/repo#N 和 loki quick "<task>" 默认均使用 Loki 10 引擎运行，不受标志顺序或输入形式影响。添加 --no-pr 可构建并验证，但不创建拉取请求；添加 --max-cost <usd> 可限制支出；添加 --provider <name> 可选择其他编码 CLI。如果设置了 ANTHROPIC_API_KEY 或 OPENAI_API_KEY，支出上限默认为 $100；如果使用订阅登录，则不设美元上限；loki.yaml 中的 budgets.per_run 也可设置上限。无需运行即可检查路由：loki route start prd.md 或 --explain-route。刚开始使用？请阅读5 分钟快速入门。

你将获得什么

每次运行都会根据你的任务生成交付契约，仅依据任务编写检查，然后才会修改代码、进行验证，并以且仅以以下一种结果结束：VERIFIED、ALREADY_SATISFIED、FAILED、BUDGET_STOP、BLOCKED 或 STALLED（退出代码）。如果无法按原文满足契约，运行就会停止并提出一个问题，而不是猜测。

• 一个拉取请求，便于快速审查：说明问题要求了什么、改动了什么、如何测试，以及哪些内容尚未得到证明。只有 VERIFIED 的运行才会推送分支并创建 PR；其他结果都会将分支保留在本地，并打印其位置。
• 一份签名收据，位于 .loki/runs/<run-id>/receipt.json，使用首次运行时创建的本地 Ed25519 密钥签名。
• 一次专家审查，在审查委员会运行时进行：通过比对变更文件和差异与各审查者的关键词，从专家池（agents/types.json，由 run.sh:FOCUS_KEYWORDS 评分）中选出审查者。

loki verify              # newest run; or: loki verify <run-id>

loki verify 会重新计算收据的哈希值、检查其签名，并将其与运行事件日志核对。它会打印判定结果并以以下代码退出：0（VERIFIED）、1（TAMPERED）、2（UNCHECKED）、3（UNSIGNED，除非使用 --allow-unsigned，否则会拒绝）或 4（运行结果未验证）；66 表示没有运行记录。[ $rc -eq 0 ] 是检查“已验证”是否成立的唯一安全方式。对于已声明的行为变更，loki start 还要求通过 fail-to-pass 检查：Wall 测试必须在旧代码上失败、在修改后通过，否则判定结果会保持为 PARTIAL（可通过 LOKI_MUTATION_STRICT=0 选择不启用此项）。完整表格：docs/exit-codes.md。在另一台机器上，使用 loki keys export 导出公钥，并通过 loki verify --pubkey <file> 传入。收据只声明其所运行的检查所能证明的内容，并会列出未检查的内容；签名能证明是谁生成了收据，但不能证明代码没有缺陷。详情：docs/SIGNED-RECEIPTS.md。

对于多仓库变更集，loki start --workspace <name> "<brief>" 会基于每份子收据生成一份签名的 composite.json，而 loki verify <run-dir>/composite.json 会离线重新验证（docs/WORKSPACES.md）。综合判定结果绝不会高于最弱的子项。

两套词汇，不是一套。收据判定结果（封存，共 5 种）：VERIFIED、PARTIAL、ALREADY_SATISFIED、SPEC_CONFLICT、FAILED。运行结果（打印，共 8 种）：VERIFIED、ALREADY_SATISFIED、PARTIAL、FAILED、BUDGET_STOP、BLOCKED、STALLED、CANCELLED。BUDGET_STOP、BLOCKED、STALLED 和 CANCELLED 是运行结果，不是收据判定结果。

运行结果	收据判定结果	loki start 退出代码
VERIFIED、ALREADY_SATISFIED	相同	0
FAILED、PARTIAL	相同	1
BUDGET_STOP	无（因达到上限而停止）	3
BLOCKED	SPEC_CONFLICT	4
STALLED	无	5
CANCELLED	无	130

综合判定：所有子项均为 VERIFIED 或 ALREADY_SATISFIED 时，结果为 VERIFIED（若全部为 ALREADY_SATISFIED，则仍为 ALREADY_SATISFIED；任何 SPEC_CONFLICT 子项都会使结果保持为 SPEC_CONFLICT）；有一个 PARTIAL 子项，结果上限就是 PARTIAL；有一个 FAILED 子项，综合判定就会失败。对综合结果运行 loki verify，退出代码为 0（VERIFIED）、1（TAMPERED）、2（UNCHECKED）或 3（UNSIGNED）。

自主权限与部署：.loki/policies.json 中的 autonomy: propose|execute|operate 决定 loki start 可以执行哪些操作（propose 不会创建任何内容，execute 会创建 PR，operate 还允许部署）；若没有该文件，则沿用当前行为。loki trust 会根据你的收据打印建议性的权限升级建议，但绝不会写入策略。Loki 仅在满足以下条件时部署：使用 loki deploy --execute（或 loki start --deploy）、提供一份 VERIFIED 且锚定于 HEAD 的收据，并且策略允许部署；--health-url 和 --auto-rollback 会添加部署后的探测，以及有文档说明的提供商回滚机制。Sentry 告警 webhook 可以将修复 PR 加入队列，前提是通过收据验证（docs/sentry-intake.md）。

运行结束时会打印简短摘要（两种引擎的每次运行最后都会输出统一的 Result、Files、Cost、Elapsed、Receipt 和 next: 区块；--quiet 只打印该区块，--json 则会添加一个 summary 对象）：

Outcome:    VERIFIED
PR:         https://github.com/owner/repo/pull/1
Receipt:    sha256:2f9a41c7e0b3...
NOT PROVEN: full suite, app boot, council, security scan
Cost:       $0.42 (claude, 212k tokens)
Time:       4m12s (intake 11s, plan 20s, implement 3m10s, verify 31s)

核心命令

命令	功能
loki start "<task>"	要运行的命令：使用与原始会话相同的提供方模型，然后由执行框架重新运行检查并封存凭证（可用 --no-pr、--provider、--max-cost、--haiku，让首次实现使用 haiku）。loki "<task>" 和 loki owner/repo#N 是简写。不提供任务且不在 git 仓库中时，会显示凭证且不产生任何费用
loki edit "<change>"	一次性完成一项有针对性的更改，不创建 PR、计划或评审委员会（可用 --verify、--receipt、--commit、--dry-run）
loki quick "<task>"	完成一项小任务并运行验证循环，不创建 PR
loki chat	交互式替代方式：提供 Plan 和 Build 模式及斜杠命令；/run 会启动一次 loki start 运行，--attach 会加入已有运行
loki route start <args>	显示引擎、提供方、模型和原因，但不运行（也可使用 --explain-route）
loki setup	首次运行向导：工具、Claude 登录、提供方、模型路由、支出上限
loki config list|get|set|path	读取和写入设置
loki models [--local]	列出模型路由（OpenRouter、Ollama、LM Studio、llama.cpp、vLLM、自定义）；发现本地模型
loki agents list|new|show|export --claude	在 .loki/agents/*.md 中管理自定义子 Agent
loki status [run-id]	查看最近一次运行的状态，或指定运行的状态
loki verify [run-id]	检查凭证的哈希、签名和事件日志
loki answer [run-id]	使用你的回答，从 BLOCKED 状态的运行启动后续运行（可用 --text "..."）
loki doctor [--fix] [--json]	检查先决条件、提供方和登录状态；--fix 会应用安全修复
loki control serve	启动 Control Plane（见下文）
loki dashboard	打开 Control Plane UI；如有需要会先启动它
loki tour	离线显示示例凭证。在 git 仓库之外且未提供任务时，loki start 会执行此操作
loki wow	在临时仓库中执行与普通 start 相同的实时小任务。没有可用提供方时显示离线示例
loki factory "<task>"	与 loki start 相同。start 会打印策略行
loki --help	查看其他所有内容；使用 loki help <command> 查看单个命令

核心动词：docs/CLI-CORE-VERBS.md。所有命令（自动生成）：docs/CLI-REFERENCE.md。引擎指南、提供方表、模型路由、自定义 Agent 和 chat：docs/v10/GUIDE.md。与 opencode 的客观比较：docs/COMPARE-OPENCODE.md。

模型、提供方和本地模型

Claude Code 是默认的 Tier-1 提供方。使用 --provider codex|cline|aider|opencode（或 LOKI_PROVIDER）可选择其他提供方；对于所有这些提供方，Loki 10 引擎都会强制执行墙钟时间限制和迭代后的防护扫描，并衡量 codex、cline 和 aider 的费用（从 CLI 输出中解析或估算，并标记为 estimated），因此 --max-cost 会生效。对于 OpenRouter 或本地模型，请在运行 loki start 前设置 LOKI_MODEL_ROUTE=<kind>/<id>（类型：openrouter、ollama、lmstudio、llamacpp、vllm、custom）；loki models --local 会查找本地运行时，并输出可直接粘贴使用的值。

LOKI_MODEL_ROUTE=ollama/qwen3-coder loki start prd.md

Control Plane

用于管理所有运行的本地 UI 和 API：运行结果、凭证、费用，以及 BLOCKED 运行的回答框。默认开启（设置 LOKI_CONTROL=0 可将其关闭），且仅监听 127.0.0.1。

loki control serve       # http://127.0.0.1:47821 (--port N, --db PATH)
loki control backfill .  # load existing ./.loki/runs
loki control status      # reachable? how many runs?

运行期间，这台计算机上的运行会自动发送到该服务。指南：container、Helm 和 ECS、从旧版 dashboard 迁移。

要求

loki doctor 会检查以下列表。

必需：

• Claude Code（claude），已安装并登录：默认提供方，也是唯一支持所有功能的提供方。内置 Agent SDK 配合 ANTHROPIC_API_KEY 可用于 loki start 主流程，但 loki edit 和 loki chat 会调用 claude CLI。
• Python 3.8+（python3）
• Node.js 20+（node；CI 目标为 22 LTS）
• jq
• Git 2.x（git）
• curl

可选：

• 其他编码 CLI：Codex、Cline、Aider、opencode（--provider）。模型路由可使用 Ollama 或 OpenRouter 密钥。
• PATH 中的 Bun 1.3+（bun）（npm 包也会捆绑它）。
• Docker，用于运行已发布的镜像。

支持 macOS 和 Linux。

更多信息

• 安装、环境变量、退出代码、已知问题、隐私与遥测
• Agent Change Receipt 格式：docs/AGENT-CHANGE-RECEIPT.md
• 从 GitHub Actions 将问题转为 PR，无需托管服务：docs/examples/loki-issue-to-pr.yml.example
• Jira 和 Linear 接入：docs/trackers.md。双向 Slack：docs/slack.md。多仓库运行和组合回执：docs/WORKSPACES.md。部署：docs/DEPLOY-PLAN.md
• MCP：内置服务通过 stdio（loki mcp）公开 48 个工具，包括启动运行、读取状态和验证回执。一键安装：Cursor、VS Code。也可运行 loki mcp install --client claude|cursor|vscode|windsurf。
• Claude Code 插件：先运行 claude plugin marketplace add asklokesh/loki-mode，再运行 claude plugin install loki-mode@loki-mode。同一插件市场还提供 loki-seal，这是一个 Stop hook，当测试新近失败或被弱化时，会拒绝将任务标记为“完成”。
• 架构：docs/ARCHITECTURE.md。升级：UPGRADING.md

贡献

git clone https://github.com/asklokesh/loki-mode.git && cd loki-mode
npm install && npm test

请参阅 CONTRIBUTING.md、TESTING.md 和行为准则。

许可证

Business Source License 1.1。可免费用于个人、内部、学术和非商业用途；该许可证将于 2030 年 3 月 19 日转为 Apache 2.0。其他安排请联系 [email protected]。

Loki Mode 由 Autonomi 构建。