@zlogic.run 文档

@zlogic.run 是一个本地优先的 AI 工程助手。你可以在终端里用 TUI 操作，也可以在跨平台桌面端中可视化地管理项目、会话和配置。

快速导航

新用户 → #安装 → #快速上手
日常使用 → #CLI 与桌面端选择
配置 → #Provider 与模型、#密钥管理、#配置参考
安全 → #安全与审批、#数据流与隐私
即将到来 → #Roadmap

安装

一行命令安装 CLI（推荐）

bash / zsh

curl -fsSL https://install.zlogic.run | sh

PowerShell

irm https://install.zlogic.run | iex

npm

npm install -g @zlogic/cli

安装脚本会自动检测操作系统和架构，下载对应二进制到 /usr/local/bin/zlogic（Linux/macOS）或 %LOCALAPPDATA%\zlogic\bin（Windows）。

桌面端

从 zlogic.run/#download 下载对应平台的安装包：

平台	格式	下载
Windows 10/11 x64	NSIS 安装包 (.exe)	下载
macOS 12+ Intel & Apple Silicon	DMG (Universal)	下载
Linux x86_64	AppImage	下载

桌面端基于 Tauri 2，各平台的系统依赖：

Windows：需要 WebView2 运行时（Windows 10+ 自带）
macOS：首次启动需右键 → 打开（因未公证）
Linux：需要 WebKitGTK 4.1 和 libsoup3

快速上手

1. 添加你的第一个 Provider

@zlogic.run 本身不提供模型，你需要配置一个模型提供商。密钥来自环境变量（默认开启）或系统钥匙串，详见 #密钥管理。

最快的开始方式 —— 导出 key 并编辑 ~/.zlogic/models.yaml：

export DEEPSEEK_API_KEY=sk-...

# ~/.zlogic/models.yaml
providers:
  my-provider:
    sdk: openai_chat
    base_url: https://api.openai.com/v1
    models:
      - id: gpt-4o

key 不进配置文件 —— 上面 export 的变量按 provider 自动匹配，或用系统钥匙串（见 #密钥管理）。

DeepSeek 与 OpenAI 经过完整测试；其余内置 SDK（Anthropic、Gemini、GLM、DashScope、Qwen、OpenRouter、Fireworks、Bedrock、自定义端点）为 beta 状态。详见 #Provider 与模型。

2. 启动 CLI

zlogic

首次启动会进入会话选择界面。按 Enter 创建一个新会话，输入消息即可开始对话。

常用快捷键：

操作	快捷键
发送消息	`Enter`
换行	`Shift+Enter`
打开历史 / 取消	`Esc`
文件引用	`@`
斜杠命令	`/`

3. 试试桌面端

安装后打开桌面应用，创建或打开一个 Workspace（任意文件夹），然后在 Chat 视图中开始对话。桌面端提供文件浏览、用量统计、可视化配置、插件/技能市场、本地历史（checkpoints）等更多功能。

下一步

了解 CLI 与桌面端的区别选择合适的客户端
配置更多 Provider 与模型
查看安全与审批机制

CLI 与桌面端选择

两个客户端共享同一个本地 Agent runtime，区别在于交互方式：

场景	CLI	桌面端
已在终端中工作	★ 首选	可用
键盘驱动、低打扰	★ TUI 快捷键	GUI 操作
管理多个项目/会话	可用	★ 可视化侧栏
文件浏览与编辑	命令行工具	★ 内置文件面板 + 编辑器
模型/Key 配置	YAML 编辑	★ 配置表单
用量与成本统计	命令行查询	★ 图表展示
审批工作流	★ 终端内审批	窗口内审批

何时用 CLI

你已经在终端里编码、查日志、跑构建
希望长回复停留在你正在使用的终端里
偏好键盘操作、不想离开 shell

何时用桌面端

需要直观地管理多个 Workspace 和 Session
想通过 GUI 配置 Provider、模型和密钥
需要用量趋势、成本统计、本地历史与插件/技能市场

两者不互斥：可以在终端里快速提问，再用桌面端查看项目全景。

CLI

CLI 适合已经在终端里工作的开发者。它运行在你现有的终端里，保留真实终端体验。

核心能力

审批工作流：写文件、运行命令、访问外部资源等敏感动作会先请求授权。
授权范围：支持仅本次、当前 Session、当前 Project；project 授权会按工作目录持久化，session 授权只在当前会话内生效。
轮次历史：查看某轮改动了哪些文件（changes）并撤销（undo），由本地 checkpoints 支撑。
记忆：持久化事实（memory）按作用域（global / workspace）跨会话保留。
MCP 工具：在终端里管理 MCP 服务器（mcp）。
IME 友好输入：硬件光标锚定，CJK 输入和组合窗口不会漂移。
主题与快捷操作：支持主题切换、会话切换、文件引用、粘贴文本/图片、模型选择和 provider/key 管理。

适合场景

在现有 shell 里完成代码阅读、修改、测试和提交前检查
直接在终端里处理长输出、命令结果和 agent 过程
偏好键盘驱动、低打扰审批和终端原生交互

快捷键

操作	快捷键
发送消息	`Enter`
换行	`Shift+Enter`
取消/打开历史	`Esc`
文件引用	`@`
斜杠命令	`/`
主题切换	`/theme`
会话切换	`/session`

桌面端

桌面端基于 Tauri 2，将 Agent runtime 包装为跨平台原生应用，提供可视化工作空间。

主要视图

Dashboard：创建或打开 Workspace，或使用 Global Workspace 进行临时对话。
Chat：流式回复、reasoning 块、tool/diff/todo 活动面板、权限/确认/输入提示；支持附件、粘贴文本/文件/图片、@ 文件引用、斜杠面板、实时 steering、停止、复制、编辑、删除、回滚和 diff undo。
Workspace & Conversations：任意文件夹都可以成为 Workspace；每个 Workspace 可包含多个 Conversations（对话）；可创建、重命名、删除和追踪在线对话。
文件：项目树、延迟加载目录、CodeMirror 编辑器、脏状态提示、刷新和保存；写入带 mtime 检查，避免覆盖外部修改。
本地历史（checkpoints）：每次改文件的工具调用前后都会打快照 —— "这一轮改了什么"、回滚和 diff 撤销都依赖它。快照存在本地存储，绝不触碰你的 git。
任务：后台任务的状态与通知。
市场：安装并管理插件与技能（基于 MCP 的扩展），每个扩展的能力需要单独批准。
连接：一次配置数据库、对象存储和云账号，再分配给具体 Workspace。
用量：调用次数、tokens、费用和预估调用数；可按日期、Provider、模型、Workspace 或 Conversation 筛选。
设置与 Provider：主题、语言、更新、默认模型、上下文压缩阈值、God Mode、日志级别/路径；可编辑 Provider SDK、Base URL、API key、模型层级、上下文窗口、定价、模型角色与记忆。

适合场景

管理多个项目、会话和模型
查看成本趋势和近期调用（按项目或会话）
通过 GUI 检查密钥存储、模型定价、Provider 端点和本地设置

Provider 与模型

@zlogic.run 只连接你配置的模型提供商。不存在 @zlogic.run 云端 —— 请求直接发送到你声明的端点。

⚠️ Beta 声明

目前只有 DeepSeek 与 OpenAI 经过了完整测试。其余 SDK（anthropic、gemini、glm、dashscope、qwen_local、openrouter、fireworks、bedrock、openai_generic）均为 beta 状态 —— 应该能用，但可能有边角问题。遇到问题请提交 issue：https://github.com/zlogic-labs/zlogic/issues。

内置 Provider

程序内置了一份 provider 目录（端点、上下文窗口、定价与 thinking 档位）。内置 provider 在探测到 key 后自动出现，不需要写配置文件：

Provider	SDK	Key 来源（自动探测）
OpenAI	`openai_chat` / `openai_responses`	`OPENAI_API_KEY` 或系统钥匙串
Anthropic	`anthropic`	`ANTHROPIC_API_KEY` 或钥匙串
Gemini	`gemini`	`GEMINI_API_KEY` / `GOOGLE_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY` 或钥匙串
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY` 或钥匙串
GLM（智谱）	`glm`	`ZHIPUAI_API_KEY` / `GLM_API_KEY` 或钥匙串
DashScope（通义千问）	`dashscope`	`DASHSCOPE_API_KEY` 或钥匙串
OpenRouter	`openrouter`	`OPENROUTER_API_KEY` 或钥匙串
Fireworks	`fireworks`	从环境探测
Bedrock	`bedrock`	从环境探测

密钥如何解析见 #密钥管理。

自建与自定义端点

SDK	用途
`qwen_local`	自建 Qwen（vLLM / SGLang 开启 reasoning）
`openai_generic`	其他任意 OpenAI 兼容端点 —— 企业网关、自建 vLLM/SGLang；支持声明式方言配置 reasoning 字段

在 `models.yaml` 中添加 Provider

# ~/.zlogic/models.yaml
auto_detect_env: true        # 默认 true —— 从环境变量读取 key

providers:
  my-provider:
    sdk: openai_chat         # SDK 协议（见上表）
    base_url: https://api.openai.com/v1
    models:
      gpt-4o: {}
      gpt-4o-mini: {}

Provider 级字段：sdk、base_url、wiring（请求头 / 查询参数 / 额外头 —— 例如 Azure 风格的鉴权）、default_params、models，以及用 enabled: false 关闭某个 provider。guide_url 只是展示用。

API key 不写在配置里 —— 只从环境变量（默认开启）或系统钥匙串读取，见 #密钥管理。

从环境变量读取 key

环境变量密钥默认开启（auto_detect_env: true）。导出变量即可被识别，无需 key add：

export DEEPSEEK_API_KEY=sk-...

通用形式是 <PROVIDER>_API_KEY（provider id 大写）；内置 provider 也识别各自的官方变量名（见上表）。在 models.yaml 中设置 auto_detect_env: false 可完全关闭环境变量密钥 —— 之后只从系统钥匙串取。

模型设置

每个模型可以携带以下字段：

providers:
  my-provider:
    models:
      gpt-4o:
        wire_model: gpt-4o-2024-11-20   # 实际发给 API 的模型名（默认 = map 的 key）
        display_name: GPT-4o             # 界面显示名
        tier: main                       # light / main / thinking
        context_window: 128000           # 上下文窗口（token），用于压缩决策
        max_output_tokens: 16384
        vision: true                     # 能力标记
        thinking:                        # thinking 能力（逐模型）
          supported: true
          can_disable: false
          efforts: [low, medium, high]   # 模型支持的 effort 档位
        pricing:                         # 每百万 token 定价（展示与成本统计）
          input_per_m: 2.5
          output_per_m: 10.0
          cached_input_per_m: 0.5
          currency: USD
        default_params:                  # 合并进请求体
          temperature: 0.6
        no_think_params:                 # 关闭 thinking 时合入请求体的参数
          reasoning_effort: minimal

default_params 支持的标准参数：temperature、top_p、top_k、max_tokens、frequency_penalty，以及各厂商的扩展字段。未配置 context_window 时使用各 SDK 的保守内置下限（偏小是安全的 —— 只会让压缩早一点触发）。当同一个 provider 下混用不同协议时，模型级 sdk 可以覆盖 provider 级设置。

路由

default_model（写在 config.yaml 中）决定默认模型，格式为 provider:model（如 deepseek:deepseek-chat）。
模型层级（light / main / thinking）让路由器按任务选模型：标题与审批用便宜快的，常规轮次用主力，深度审查用 thinking。
角色模型链（llm_roles）按角色声明候选链，失败时沿链回退：

llm_roles:
  session:                  # 主对话
    models: [gpt-4o]
  compaction:               # 上下文摘要
    models: [gpt-4o, claude-sonnet-4-6]
  title:                    # 会话标题 —— 便宜即可
    models: [gpt-4o-mini]
    params:
      temperature: 0.2
    thinking: off

未配置的角色使用内置链：标题/审批/工具类优先 light，摘要与深度审批优先 main，所有链最终都回退到当前会话模型 —— 完全不配层级时，一切行为退化为"全用一个模型"。

内置角色名：session、title、compaction、approval、approval_deep、utility、agent:<name>。

密钥管理

API key 绝不会写入配置文件。密钥只有两种来源：

来源	原理	适用场景
环境变量	运行时从环境变量读取。默认开启（`auto_detect_env: true`）。	本地开发、CI/CD —— 直接 `export` 即可
系统钥匙串	通过 `zlogic key add` 加密保存在操作系统凭据库（macOS Keychain / Windows 凭据管理器 / Linux Secret Service）。	本机持久化密钥

每个 provider 的解析优先级：先环境变量，后钥匙串。取不到 key 的 provider 直接不可用 —— 绝不会裸发请求。

环境变量（默认）

直接导出环境变量即可，无需 key add：

export DEEPSEEK_API_KEY=sk-...

内置 provider 识别各自的官方变量名（OPENAI_API_KEY、ANTHROPIC_API_KEY、DEEPSEEK_API_KEY、GEMINI_API_KEY、GOOGLE_API_KEY、GOOGLE_GENERATIVE_AI_API_KEY、DASHSCOPE_API_KEY、ZHIPUAI_API_KEY、GLM_API_KEY、OPENROUTER_API_KEY）。
通用形式是 <PROVIDER>_API_KEY（provider id 大写）。
想完全关闭环境变量密钥，在 models.yaml 中设置 auto_detect_env: false —— 之后只从钥匙串取。

系统钥匙串（持久化）

# 为某个 provider 添加密钥（会提示输入 secret）
zlogic key add openai

# 列出哪些 provider 有钥匙串条目（只显示掩码，绝不显示明文）
zlogic key list

# 验证凭据对 provider 是否可用
zlogic key verify openai
zlogic key verify openai gpt-4o

# 删除钥匙串条目
zlogic key remove openai --yes

钥匙串条目按 provider id 引用（keyring:openai）。桌面端 Settings 界面添加密钥的方式相同 —— 选择 Provider 并选择凭据来源。

密钥不进配置文件

API key 不会以任何形式写进 models.yaml / config.yaml —— 没有 api_key 字段，也不支持明文配置。密钥只从两种来源解析（先环境变量，后钥匙串）：

环境变量：按 provider 自动识别（<PROVIDER>_API_KEY 或官方变量名），无需在配置里引用。
系统钥匙串：zlogic key add <provider> 存入，运行时透明解密，同样无需在配置里引用。

env.yaml —— 把密钥放进一个文件

不想每次 export、又不想用系统钥匙串时，可以在 config 根目录放一个 env.yaml，系统启动时会把它加载为环境变量（真实环境变量优先，env.yaml 只补缺）：

# ~/.zlogic/env.yaml
DEEPSEEK_API_KEY: sk-...
OPENAI_API_KEY: sk-...

只支持键值对（键名大写，值就是密钥明文 —— 文件本身要小心保管，权限建议仅本人可读）。
键值不会覆盖进程里已存在的同名环境变量。
与 export 完全等价：auto_detect_env 开关同样生效。
不推荐把它提交进仓库；.gitignore 加一行 env.yaml 即可。

安全建议

个人开发机：用 zlogic key add <provider> 添加一次，之后由系统钥匙串透明解密。
CI/CD 与共享环境：使用 secrets 管理工具注入环境变量。
绝不把 API key 以明文写在任何配置文件或仓库中。

配置参考

数据目录

数据按四个根目录划分，语义各不相同（所有平台统一使用 XDG 风格）：

根	存放	删掉会怎样
`config`	你手写的配置文件	回到默认设置
`data`	对象库、附件、每个 workspace 的历史、已安装的运行时与技能	⚠️ 不要删 —— 删掉等于丢掉全部数据（会话内容、历史、附件、已装软件）
`state`	`state.db`（会话、entries、usage）、锁、日志	⚠️ 不要删 —— 删掉 `state.db` 等于清空整个会话库，历史与用量记录全部丢失、无法恢复
`cache`	可重新生成的东西	什么都不会发生 —— 可随时清空

data 与 state 是本机数据的唯二存放处，删除不可恢复，建议永远不要手动清理（对象库与 state.db 之间还有引用关系：state.db 没了，对象库里的内容也变成孤儿）。只有 cache 可以放心清空。

默认位置（所有平台一致，XDG 风格）：

~/.config/zlogic/           # config
├── config.yaml             # 全局行为：默认模型、上下文、工具、角色链 ...
├── models.yaml             # 你的 provider/模型 + auto_detect_env
├── env.yaml                # 可选：密钥键值对 —— 启动时加载为环境变量（见密钥管理）
└── policy.yaml             # 全局安全策略 + 成本预算

~/.local/share/zlogic/      # data
├── objects/                # 对象库（大工具结果、附件）
├── workspaces/             # 每个 workspace 的私有数据
├── extensions/runtimes/    # 从市场安装的运行时
└── skills/                 # 已安装的技能

~/.local/state/zlogic/      # state
├── state.db                # SQLite —— 会话、entries、usage
└── logs/

~/.cache/zlogic/            # cache —— 随时可删

项目内：工作区私有目录 .zlogic/（项目根下）可存放项目级 policy.yaml；工作区的 MCP server 在项目根 .mcp.json 中声明。

环境变量

优先级：ZLOGIC_HOME（全部折叠到一个根）> XDG_*_HOME（分别控制各根）> 上面的平台默认值。

变量	作用
`ZLOGIC_HOME`	把全部数据放到这一个根下（便携安装、容器）
`XDG_CONFIG_HOME`	config 根（默认 `~/.config`）→ zlogic 配置在 `~/.config/zlogic`
`XDG_DATA_HOME`	data 根（默认 `~/.local/share`）→ `~/.local/share/zlogic`
`XDG_STATE_HOME`	state 根（默认 `~/.local/state`）→ `~/.local/state/zlogic`
`XDG_CACHE_HOME`	cache 根（默认 `~/.cache`）→ `~/.cache/zlogic`

config.yaml

全局行为配置：

default_model: deepseek:deepseek-chat   # 默认模型，格式 provider:model

providers:                 # 可选：覆盖单个 provider 的字段
  deepseek:                # （叠加在 models.yaml / 内置目录之上）
    models:
      deepseek-chat:
        context_window: 64000

llm_roles:                 # 角色模型链 —— 见 Provider 与模型
  title:
    models: [gpt-4o-mini]
    thinking: off

session:
  god_mode: false          # 完全授权模式：跳过所有权限确认（默认关）
  auto_title:              # 会话标题生成
    enabled: true
    max_chars: 30
    source_chars: 600

context:
  compact_ratio: 0.8       # 上一轮 input 占窗口比例达到该值即压缩
  tail_turns: 4            # 压缩时保留最近 N 轮为结构化消息
  overflow_retries: 1      # 上下文溢出后的重试次数，再超就报错

tools:
  default_shell: auto      # shell 工具的后端（auto / git_bash / pwsh / cmd / bash）
  max_result_chars: 30000  # 超长的工具结果落入对象库
  timeout_secs: 0          # 工具执行超时（秒），0 = 不限
  web_search:
    provider: exa          # exa / parallel —— 哪边有 key 用哪边
    timeout_secs: 25

checkpoint:                # 本地历史 —— 见下文「本地历史」小节
  enabled: true
  max_file_size_mb: 20
  budget_gb: 2
  exclude: []
  exclude_dirs: []
  build_dirs: []
  max_build_dir_files: 2000
  retention_days: 30

worktree:
  dir: "../{workspace}-worktrees"   # 子 agent 工作树检出的位置

cost:                      # 账目用哪种货币
  display_currency: USD
  rates: []                # 例如 {from: USD, to: CNY, rate: 7.2}

limits:                    # 防卡死的兜底，不是预算
  max_rounds: 150          # 单个 turn 最多多少轮 LLM
  max_depth: 2             # 子 agent 最大嵌套深度

log:
  level: info              # error / warn / info / debug / trace
  to_file: true            # 写入 state/logs/（终端 UI 会吞掉 stderr）

marketplace:               # 可选：下载镜像（GitHub 连不上时）
  github_release_mirror: null
  node_dist_mirror: null

models.yaml

你的 provider 与模型 —— 完整结构见 #Provider 与模型：

auto_detect_env: true      # 默认 true —— 从环境变量读取 API key

providers:
  my-provider:
    sdk: openai_chat       # openai_chat / openai_responses / deepseek / glm / dashscope /
                           # qwen_local / openrouter / fireworks / anthropic / gemini /
                           # bedrock / openai_generic
    base_url: https://api.openai.com/v1
    models:
      gpt-4o: {}

models.yaml 只接受 provider/模型相关设置 —— deny_unknown_fields 会拒绝写错分区的键（如 context:、session:）。这些要放在 config.yaml 中。API key 不写在这里（也没有 api_key 字段）—— 只从环境变量或系统钥匙串读取，见 #密钥管理。

policy.yaml —— 审批与预算

安全策略与成本预算都在 policy.yaml 中（全局在 config 根目录，项目级在项目根 .zlogic/policy.yaml）。项目策略只会收紧全局策略，不会放宽。

policy:                    # 审批规则 —— 见「安全与审批」
  version: 1
  default: ask             # ask / allow / deny —— 默认 fail-closed
  commands: []             # 简单命令规则（POSIX）
  exec: []                 # exec 规则
  paths: []                # 路径规则（敏感路径）
  scripts: []              # 脚本规则
  protected_delete: []     # 任何删除操作都必须保留的路径
  protected_write: []      # 写入永远不能自动批准的路径

budget:                    # 需求侧成本上限
  per_turn: 0.5            # 单个 turn 的上限（含派生的子 agent）
  per_session: 5           # 单次对话累计上限
  per_task: 1              # 单个后台任务上限（默认回落到 per_turn）
  window:                  # 滚动时间窗总额
    hours: 24
    amount: 10
  action: ask              # 达到上限时的行为（ask / stop）

写坏的 budget: 分区只会让预算失效（并给出可见警告）；policy: 一半单独解析，仍然生效。

.mcp.json（工作区级）

工作区的 MCP server 声明在项目根：

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": { "MY_VAR": "value" }
    }
  }
}

从市场安装的插件与技能（基于 MCP 的扩展）在桌面端管理；已安装的技能落在 data 根下的 skills/。

本地历史（checkpoints）

每次改文件的工具调用前后都会打快照。"这一轮改了什么"、回滚和 diff 撤销都依赖它。

快照存放在本地数据目录下的影子对象库 —— 绝不触碰你的 git 历史或 .gitignore。
打开工作区时的全量快照有大小预算：超出预算时本地历史保持未启用，并报告大目录候选，而不是替你决定排除什么。
node_modules、.venv 等工具缓存无条件排除；产物目录只有文件数超过 max_build_dir_files 才跳过。
关闭本地历史意味着一个字节都不写：没有快照，撤销与回滚都不可用。

记忆（Memory）

agent 可以跨会话持久化耐久事实（偏好、目标、纠正、参考）。项目指令永远优先于记忆。

作用域：global（所有工作区）与 workspace（当前项目）。
在桌面端设置 → 记忆中管理，或用 CLI：zlogic memory（列表）、zlogic memory remove <id>、zlogic memory undo [global|workspace]。

扩展（市场）

插件与技能是基于 MCP 的扩展，从桌面端市场安装：

每个扩展声明自己的能力，安装时需要你显式接受。
扩展可随时启用 / 禁用 / 卸载；扩展贡献的 MCP 服务器拥有独立的 token 凭据（CLI 中用 zlogic mcp 管理）。

连接（Connections）

数据库、对象存储和云账号可以一次配置，再分配给具体 Workspace：

每个连接声明受支持的 Provider 及其能力（读 / 写 / 执行）。
凭据保存在系统钥匙串，或引用环境变量 —— 绝不写入工作区配置。
每个连接列出其授权的 Workspace；agent 只在授权的 Workspace 中看到该连接。

安全与审批

@zlogic.run 的默认安全边界是：模型可以建议动作，但敏感动作必须经过本地客户端审批后才执行。

审批层级

每次工具调用之前，权限门（Permission Gate）都会进行检查：

层级	行为	示例
Layer 0 — 确定性规则	硬编码规则立即决定放行/询问，无需调用模型	非敏感路径的只读操作、工作区内的写入文件
Layer 1 — 模型审查	轻量级 LLM 根据规则手册审查请求并返回判断	Layer 0 无法决定的请求
Layer 2 — 深度审查	Layer 1 不确定时，使用更强模型按同一规则重新审查。需要配置双模型层级才可用	复杂 shell 管道、不常见的写入路径
用户确认	所有自动审批层都说"询问用户"时，客户端弹出确认对话框供用户选择授权范围	危险操作、敏感文件

⚠️ 自动审批的局限性

自动审批系统（Layer 0–2）通过确定性规则和 LLM 审查来提高效率，但无法保证 100% 的准确率。LLM 可能误判请求的意图，规则可能无法覆盖所有边缘场景。用户确认环节是安全模型中的最后一环也是最重要的一环——在每个敏感操作执行之前，你都有机会审查并决定是否放行。请勿在 untrusted 环境下启用 God Mode，也不要完全依赖自动审批规则来防范恶意行为。

授权范围

审批或拒绝时，可以指定授权范围：

once：仅本次通过，下次再问
session：当前会话内不再提示
project：当前工作目录下不再提示（持久化到磁盘）

已有授权可通过授权列表 UI 或 CLI 中的 /grants 命令管理。

自动审批规则手册 (Layer 0)

确定性规则分为两类：

危险规则 — 始终询问用户：

规则	描述
D1	不可逆地销毁数据 — 工作区外的递归/强制删除、覆盖不相关文件
D2	读取、写入或传输机密 — .env 文件、私钥、凭据
D3	提权或更改系统状态 — sudo、系统服务、/etc
D4	发布或部署 — 包发布、强制推送、创建 release
D5	数据外泄 — 将本地文件内容或仓库数据发送到用户未指定的远程主机
D6	安装持久化 — 修改 shell rc/profile、git hooks、登录项
D7	与用户请求没有明显关联或相矛盾

分类规则 (C1–C6)：

C1 read_file / list_dir：非敏感路径预批准；敏感目标触发 D2
C2 write_file 在工作区内：预批准，除非匹配 D2/D6
C3 write_file 在工作区外：按目录判断（临时目录允许，系统目录询问）
C4 exec：构建/测试/格式化允许；D 规则和 git push 需要用户确认
C5 网络：公开 GET 允许；变更操作和私有主机询问用户
C6 其他工具（MCP/插件）：对操作应用 D 规则

敏感路径模式

当 agent 读取或写入匹配以下任一模式的文件时，Layer 0 会直接升级为询问用户（D2）：

目标	示例路径
环境变量文件	`.env`、`.env.production`、`.env.local`
SSH 密钥	`~/.ssh/id_rsa`、`~/.ssh/id_ed25519`、`~/.ssh/authorized_keys`
AWS 凭据	`~/.aws/config`、`~/.aws/credentials`
GitHub CLI 认证	`~/.config/gh/`
GnuPG	`~/.gnupg/`
Docker 配置	`~/.docker/config.json`
kubectl 配置	`~/.kube/config`
私钥文件	任何以 `.pem` 或 `.key` 结尾的文件
私钥名称	`id_rsa`、`id_dsa`、`id_ed25519`（任意位置）
凭据点文件	`.npmrc`、`.pypirc`、`.netrc`

额外的敏感路径可通过 policy.yaml 中的 paths 规则自定义（全局或项目级）。

God Mode

启用 God Mode 会绕过大部分安全限制，仅建议在本地开发环境中使用。在桌面端 Settings 或 CLI 中通过 /god 切换。

数据流与隐私

@zlogic.run 没有自己的云端 API、控制平面或中转服务。一次普通对话的数据流是：

数据流

你的消息 → 本地 Agent runtime → 你配置的 Provider → 响应流式返回 → 本地存储

所有过程都在本地完成：消息组装、上下文构建、工具执行、文件读写、会话持久化。

收集什么

@zlogic.run 不收集：

不上传会话、代码、prompt、key 或用量数据
不发送匿名遥测、分析或崩溃报告
没有第三方 CDN、Google Fonts、GitHub API 或分析脚本
站点纯静态，不依赖外部服务

本地存储什么

对话历史：state 根目录下的 SQLite 数据库（默认 ~/.local/state/zlogic/state.db）
配置：config 根目录（默认 ~/.config/zlogic/）下的 config.yaml、models.yaml、policy.yaml
密钥：系统钥匙串（macOS Keychain / Windows 凭据管理器 / Linux Secret Service）或环境变量 —— 绝不落盘为文件
用量记录：调用次数、tokens 和费用估算
授权记录：project 级别的授权持久化
检查点：本地历史快照存放在影子对象库 —— 不触碰你的 git
记忆：你（或经你批准的 agent）选择持久化的耐久事实

删除对话会删除本地对话记录；不存在云端副本。

许可证

@zlogic.run 目前是专有软件 —— 源码暂不对外公开，未来部分组件可能会开源。产品所依赖的第三方开源组件保留各自的许可证（见致谢页面）。

常见问题

终端兼容

Q: 支持 Windows 自带的 cmd 吗？

A: Windows 旧版控制台 (conhost.exe) 不支持 DEC 2026，CJK 宽度也不稳定，且 process.stdin 无法处理 IME 组合事件。请使用 Windows Terminal、WezTerm、Alacritty 或 VS Code 终端。

模型与 Provider

Q: @zlogic.run 会用自己的 API 吗？

A: 不会。@zlogic.run 本身不提供模型，也没有云端 API 或控制平面。所有请求都直接发送到你配置的 Provider 端点。

Q: 支持本地模型吗？

A: 支持。通过 Ollama 或 vLLM 等提供 OpenAI 兼容端点的本地推理服务，可以配置为 sdk: openai-compatible 连接。

隐私

Q: @zlogic.run 会上报使用数据吗？

A: 不会。无遥测、无埋点、无 cookie 跟踪。

Q: API key 存在哪里？

A: 存在系统钥匙串（macOS Keychain / Windows 凭据管理器 / Linux Secret Service）中，或运行时从环境变量读取。详见 #密钥管理。

Q: Reasoning 内容会泄露给下一个 Provider 吗？

A: 不会。Reasoning 内容仅作为思考通道展示，不会回灌到下一轮 LLM 上下文。

其他

Q: @zlogic.run 开源吗？

A: 暂时不开源。@zlogic.run 目前是专有软件，源码不对外公开；未来部分组件可能会开源。产品所依赖的开源库保留各自的许可证。

本地历史

Q: 本地历史（checkpoints）会碰我的 git 吗？

A: 不会。快照存放在本地数据目录下的影子对象库。你的提交、工作区和 .gitignore 都不会被修改。

Q: 为什么撤销 / 回滚不可用？

A: 本地历史可能已在设置中被关闭（或首次快照超出了大小预算）。在设置 → 本地历史中开启；"这一轮改了什么"和回滚都需要它处于启用状态。

Roadmap

接下来要做的内容。不承诺时间表 —— 准备好了就会发布。

移动端 App

规划中的 @zlogic.run 移动端伴侣：在手机上聊天、语音通话与远程审批，连接运行在你机器上的 agent runtime。

通过一次性密钥（二维码）配对设备 —— 无账号、无云端中转。
随时查看会话、任务与搜索；远程审批敏感操作。

daemon 与远程访问

把本地 agent runtime 以 HTTP 形式暴露出来，供移动端连接：

zlogic daemon 启动 daemon；--pair 打印一次性配对密钥与二维码（5 分钟有效）。
已配对设备持有独立的带 scope 凭据；配对尝试与设备请求都有速率限制。
在局域网之外暴露时，只应放在自有 TLS 反向代理之后。

@zlogic.run Docs

@zlogic.run is a local-first AI engineering assistant. Use the terminal TUI for a keyboard-driven workflow, or the cross-platform desktop app to manage projects, conversations and configuration visually.

Quick navigation

New users → #Installation → #Quick Start
Daily use → #Choosing CLI vs Desktop
Configuration → #Providers & Models、#Key Management、#Configuration Reference
Security → #Security & Approvals、#Data Flow & Privacy
Coming next → #Roadmap

Installation

One-line CLI install (recommended)

bash / zsh

curl -fsSL https://install.zlogic.run | sh

PowerShell

irm https://install.zlogic.run | iex

npm

npm install -g @zlogic/cli

The installer detects your OS and architecture, downloads the matching binary to /usr/local/bin/zlogic (Linux/macOS) or %LOCALAPPDATA%\zlogic\bin (Windows).

Desktop app

Download from zlogic.run/#download:

Platform	Format	Download
Windows 10/11 x64	NSIS installer (.exe)	download
macOS 12+ Intel & Apple Silicon	DMG (Universal)	download
Linux x86_64	AppImage	download

Desktop is built on Tauri 2. System requirements:

Windows: WebView2 runtime (included in Windows 10+)
macOS: right-click → Open on first launch (unsigned)
Linux: WebKitGTK 4.1 + libsoup3

Quick Start

1. Add your first Provider

@zlogic.run does not provide models — you need to configure a provider. Keys come from environment variables (on by default) or the system keyring; see #Key Management.

The quickest start — export a key and edit ~/.zlogic/models.yaml:

export DEEPSEEK_API_KEY=sk-...

# ~/.zlogic/models.yaml
providers:
  my-provider:
    sdk: openai_chat
    base_url: https://api.openai.com/v1
    models:
      - id: gpt-4o

Keys never go into the configuration file — the variable exported above is matched to the provider automatically, or use the OS keyring (see #Key Management).

DeepSeek and OpenAI are fully tested; the other built-in SDKs (Anthropic, Gemini, GLM, DashScope, Qwen, OpenRouter, Fireworks, Bedrock, custom endpoints) are in beta. See #Providers & Models for details.

2. Launch the CLI

zlogic

Press Enter to create a new session and start chatting.

Common shortcuts:

Action	Key
Send message	`Enter`
New line	`Shift+Enter`
Cancel / history	`Esc`
File reference	`@`
Slash command	`/`

3. Try the desktop app

Open the desktop app, create or open a Workspace (any folder), then start a conversation in the Chat view. The desktop adds file browsing, usage stats, visual configuration, a plugin/skill marketplace, local history (checkpoints) and more.

Next steps

Learn CLI vs Desktop to pick the right client
Configure more Providers & Models
Review Security & Approvals

Choosing CLI vs Desktop

Both clients share the same local Agent runtime — the difference is the interaction model:

Scenario	CLI	Desktop
Already in the terminal	★ Best	OK
Keyboard-driven, low-distraction	★ TUI shortcuts	GUI
Managing multiple projects/conversations	OK	★ Visual sidebar
File browsing & editing	Command-line tools	★ Built-in file panel + editor
Model/key configuration	YAML editing	★ Configuration forms
Usage & cost tracking	CLI queries	★ Charts
Approval workflow	★ In-terminal	In-window

Use CLI when

You already live in the terminal — coding, logs, builds
You want long replies to stay in the terminal you are already using
You prefer a keyboard-driven workflow

Use Desktop when

You need to manage multiple Workspaces and Conversations visually
You want GUI-based Provider, model and key configuration
You need usage trends, cost charts, local history and a plugin/skill marketplace

They work together: quick questions in the terminal, full project overview in the desktop app.

CLI

The CLI runs inside your existing terminal and keeps the real terminal experience.

Core capabilities

Approval workflow: sensitive actions (write files, run commands, access external resources) request authorization first.
Grant scopes: allow once, allow for this session, or allow for this project. Project grants persist per working directory.
Turn history: review what a turn changed (changes) and undo it (undo), backed by local checkpoints.
Memory: durable facts (memory) persist across conversations, per scope (global / workspace).
MCP tooling: manage MCP servers (mcp) from the terminal.
IME-friendly input: hardware cursor anchoring keeps CJK composition windows stable.
Themes & quick actions: theme switching, session switching, file references, paste support, model selection and provider/key management.

Best for

Code reading, editing, testing and pre-commit checks inside the terminal
Working with long output, command results and agent activity directly in the terminal
Keyboard-driven, low-distraction workflows

Shortcuts

Action	Key
Send message	`Enter`
New line	`Shift+Enter`
Cancel / open history	`Esc`
File reference	`@`
Slash command	`/`
Switch theme	`/theme`
Switch session	`/session`

Desktop

The desktop app (Tauri 2) wraps the Agent runtime as a native cross-platform application with a visual workspace.

Main views

Dashboard: create or open a Workspace, or use the Global Workspace for ad-hoc chats.
Chat: streaming replies, reasoning blocks, tool / todo / diff activity panel, permission / confirmation / input prompts; supports attachments, pasted text / files / images, @ file references, slash panels, in-flight steering, stop, copy, edit, delete, rollback and diff undo.
Workspaces & Conversations: any folder can be a Workspace; each Workspace can hold multiple Conversations; create, rename, delete and track live conversations.
Files: project tree, lazy-loaded directories, CodeMirror editor, dirty-state hints, refresh and save; writes carry an mtime check to avoid silently overwriting external edits.
Local history (checkpoints): snapshots are taken around every file-changing tool call — "what did this turn change", rollback and diff undo all rely on them. Snapshots live in local storage and never touch your git.
Tasks: background tasks with status and notifications.
Marketplace: install and manage plugins & skills (MCP-based extensions), with per-extension capability approval.
Connections: manage databases, object storage and cloud accounts once, then assign them to specific workspaces.
Usage: calls, tokens, cost and estimated-call count; filter by date, provider, model, workspace or conversation.
Settings & Providers: theme, language, updates, default model, context compaction threshold, God Mode, log level/path; edit provider, SDK, base URL, API key, model tier, context window, pricing, model roles and memory.

Best for

Managing several projects, conversations and models
Reviewing cost trends and recent calls by project or conversation
Inspecting key storage, model pricing, provider endpoints and local settings through a GUI

Providers & Models

@zlogic.run only talks to providers you configure. There is no @zlogic.run cloud — requests go directly to the endpoints you declare.

⚠️ Beta disclaimer

Only DeepSeek and OpenAI are currently fully tested. Every other SDK (anthropic, gemini, glm, dashscope, qwen_local, openrouter, fireworks, bedrock, openai_generic) is in beta status — it should work, but expect rough edges. If something breaks, please file an issue: https://github.com/zlogic-labs/zlogic/issues.

Built-in providers

A built-in provider directory ships with the program (endpoints, context windows, pricing and thinking tiers). Built-ins appear automatically once a key is found — no config file entry needed:

Provider	SDK	Key source (auto-detected)
OpenAI	`openai_chat` / `openai_responses`	`OPENAI_API_KEY` or system keyring
Anthropic	`anthropic`	`ANTHROPIC_API_KEY` or keyring
Gemini	`gemini`	`GEMINI_API_KEY` / `GOOGLE_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY` or keyring
DeepSeek	`deepseek`	`DEEPSEEK_API_KEY` or keyring
GLM (智谱)	`glm`	`ZHIPUAI_API_KEY` / `GLM_API_KEY` or keyring
DashScope (Qwen)	`dashscope`	`DASHSCOPE_API_KEY` or keyring
OpenRouter	`openrouter`	`OPENROUTER_API_KEY` or keyring
Fireworks	`fireworks`	detected from the environment
Bedrock	`bedrock`	detected from the environment

See #Key Management for how keys are resolved.

Self-hosted & custom endpoints

SDK	Use for
`qwen_local`	self-hosted Qwen (vLLM / SGLang with reasoning enabled)
`openai_generic`	any other OpenAI-compatible endpoint — enterprise gateways, self-hosted vLLM/SGLang; supports a declarative dialect for reasoning fields

Adding a provider in `models.yaml`

# ~/.zlogic/models.yaml
auto_detect_env: true        # default true — read keys from environment variables

providers:
  my-provider:
    sdk: openai_chat         # SDK protocol (see table above)
    base_url: https://api.openai.com/v1
    models:
      gpt-4o: {}
      gpt-4o-mini: {}

Provider-level fields: sdk, base_url, wiring (headers / query params / extra headers — e.g. Azure-style auth), default_params, models, enabled: false to switch a provider off. guide_url is display-only.

API keys are never written into configuration — they come from the environment (on by default) or the OS keyring, see #Key Management.

Keys from environment variables

Environment-based keys are on by default (auto_detect_env: true). Export the variable and the provider is picked up — no key add needed:

export DEEPSEEK_API_KEY=sk-...

The generic pattern is <PROVIDER>_API_KEY (provider id uppercased); built-ins also recognize their official variable names (see the table above). Set auto_detect_env: false in models.yaml to disable environment keys entirely — then only the system keyring is consulted.

Model settings

Each model under a provider can carry:

providers:
  my-provider:
    models:
      gpt-4o:
        wire_model: gpt-4o-2024-11-20   # model name actually sent to the API (default: the key)
        display_name: GPT-4o             # shown in the UI
        tier: main                       # light / main / thinking
        context_window: 128000           # tokens; used for compaction decisions
        max_output_tokens: 16384
        vision: true                     # capability flag
        thinking:                        # thinking capability (per-model)
          supported: true
          can_disable: false
          efforts: [low, medium, high]   # effort levels the model accepts
        pricing:                         # per-million-token pricing (display + cost)
          input_per_m: 2.5
          output_per_m: 10.0
          cached_input_per_m: 0.5
          currency: USD
        default_params:                  # merged into the request body
          temperature: 0.6
        no_think_params:                 # used when thinking is turned off
          reasoning_effort: minimal

Supported standard params in default_params: temperature, top_p, top_k, max_tokens, frequency_penalty, plus vendor-specific extensions. If a context_window is missing, a conservative built-in floor is used per SDK (smaller values are safe — they only trigger compaction a little earlier). A model can also override the provider-level sdk when one provider mixes protocols.

Routing

default_model in config.yaml picks the default model, written as provider:model (e.g. deepseek:deepseek-chat).
Model tiers (light / main / thinking) let the router pick the right model per job: cheap/fast for titles and approvals, main for regular turns, thinking for deep review.
Role chains (llm_roles) declare per-role candidate chains that fall through on failure:

llm_roles:
  session:                  # main conversation
    models: [gpt-4o]
  compaction:               # context summarization
    models: [gpt-4o, claude-sonnet-4-6]
  title:                    # session titles — cheap is fine
    models: [gpt-4o-mini]
    params:
      temperature: 0.2
    thinking: off

Roles without a configured chain use built-ins: titles/approvals/utility prefer light, compaction and deep approval prefer main, and every chain falls back to the current conversation model — with no tiers configured, everything simply uses one model.

Built-in role names: session, title, compaction, approval, approval_deep, utility, agent:<name>.

Key Management

API keys are never written into configuration files. There are exactly two sources:

Source	How it works	When to use
Environment variable	Read at runtime from an env var. On by default (`auto_detect_env: true`).	Local dev, CI/CD — just `export` the variable
System keyring	Stored encrypted in the OS credential store (macOS Keychain / Windows Credential Manager / Linux Secret Service) via `zlogic key add`.	Persistent keys on your machine

Resolution priority per provider: environment variable first, then the keyring. Keys that cannot be resolved simply make that provider unavailable — nothing is ever sent unauthenticated.

Environment variables (default)

Just export the variable — no key add step needed:

export DEEPSEEK_API_KEY=sk-...

Built-in providers recognize their official variable names (OPENAI_API_KEY, ANTHROPIC_API_KEY, DEEPSEEK_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, DASHSCOPE_API_KEY, ZHIPUAI_API_KEY, GLM_API_KEY, OPENROUTER_API_KEY).
The generic pattern is <PROVIDER>_API_KEY (provider id uppercased).
To turn environment keys off entirely, set auto_detect_env: false in models.yaml — after that only the keyring is consulted.

System keyring (persistent)

# Add a key for a provider (prompts for the secret)
zlogic key add openai

# List which providers have keyring entries (masked, never the plaintext)
zlogic key list

# Verify a credential actually works against the provider
zlogic key verify openai
zlogic key verify openai gpt-4o

# Remove a keyring entry
zlogic key remove openai --yes

Keyring entries are referenced by provider id (keyring:openai). The desktop Settings UI adds keys the same way — choose the provider and pick a credential source.

Keys never go into configuration files

API keys are never written into models.yaml / config.yaml in any form — there is no api_key field and no plaintext support. Keys come from exactly two sources, resolved in order (environment first, keyring second):

Environment variables: matched to providers automatically (<PROVIDER>_API_KEY or the official variable name) — no reference in configuration needed.
OS keyring: stored with zlogic key add <provider> and decrypted transparently at runtime — again, no reference in configuration needed.

env.yaml — keys in a single file

If you would rather not export every time and do not want to use the keyring, drop an env.yaml into the config root. The system loads it as environment variables at startup (a real environment variable always wins; env.yaml only fills in what is missing):

# ~/.zlogic/env.yaml
DEEPSEEK_API_KEY: sk-...
OPENAI_API_KEY: sk-...

Plain KEY: value pairs (uppercase key names; the values are the plaintext secrets — keep the file private, e.g. readable by you only).
Values never override an existing process environment variable of the same name.
Exactly equivalent to export: the auto_detect_env switch applies the same way.
Do not commit it; add env.yaml to .gitignore.

Security recommendations

Personal machines: zlogic key add <provider> once — the OS keyring decrypts transparently afterwards.
CI/CD and shared environments: use environment variables injected by your secrets manager.
Never write API keys as plaintext in any configuration file or repository.

Configuration Reference

Data directory

Data is split across four roots with different semantics (XDG-style on all platforms):

Root	Holds	Deleting it
`config`	your hand-written config files	resets to defaults
`data`	object store, attachments, per-workspace history, installed runtimes and skills	⚠️ do not delete — wipes all local data (conversation content, history, attachments, installed software)
`state`	`state.db` (sessions, entries, usage), locks, logs	⚠️ do not delete — removing `state.db` empties the entire session store; history and usage records are lost with no recovery
`cache`	regenerable data	nothing happens — safe to wipe

data and state are the only places your local data lives; deleting them is unrecoverable, so never clean them by hand (the object store and state.db also reference each other — losing state.db orphans the objects). Only cache is safe to clear.

Defaults (all platforms use the same XDG-style layout):

~/.config/zlogic/           # config
├── config.yaml             # global behavior: default model, context, tools, roles, ...
├── models.yaml             # your providers/models + auto_detect_env
├── env.yaml                # optional: KEY: value secrets — loaded as environment variables at startup (see Key Management)
└── policy.yaml             # global security policy + cost budget

~/.local/share/zlogic/      # data
├── objects/                # object store (large tool results, attachments)
├── workspaces/             # per-workspace private data
├── extensions/runtimes/    # runtimes installed from the marketplace
└── skills/                 # installed skills

~/.local/state/zlogic/      # state
├── state.db                # SQLite — sessions, entries, usage
└── logs/

~/.cache/zlogic/            # cache — safe to delete at any time

Per project, the workspace-private directory .zlogic/ inside the project root may hold a project-level policy.yaml; MCP servers for a workspace are declared in the project's .mcp.json.

Environment variables

Priority: ZLOGIC_HOME (collapse everything under one root) > XDG_*_HOME (fine-grained per root) > platform defaults above.

Variable	Effect
`ZLOGIC_HOME`	Put everything under this one root (portable installs, containers)
`XDG_CONFIG_HOME`	config root (default `~/.config`) → zlogic config in `~/.config/zlogic`
`XDG_DATA_HOME`	data root (default `~/.local/share`) → `~/.local/share/zlogic`
`XDG_STATE_HOME`	state root (default `~/.local/state`) → `~/.local/state/zlogic`
`XDG_CACHE_HOME`	cache root (default `~/.cache`) → `~/.cache/zlogic`

config.yaml

Global behavior settings:

default_model: deepseek:deepseek-chat   # default model, written as provider:model

providers:                 # optional: override individual provider fields
  deepseek:                # (merged over models.yaml / built-ins)
    models:
      deepseek-chat:
        context_window: 64000

llm_roles:                 # role-based model chains — see Providers & Models
  title:
    models: [gpt-4o-mini]
    thinking: off

session:
  god_mode: false          # full authorization mode: skips all approval prompts (default false)
  auto_title:              # session title generation
    enabled: true
    max_chars: 30
    source_chars: 600

context:
  compact_ratio: 0.8       # compact when last round used this share of the window
  tail_turns: 4            # keep the last N turns structured through compaction
  overflow_retries: 1      # retries after a context overflow before failing

tools:
  default_shell: auto      # shell backend for the shell tool (auto / git_bash / pwsh / cmd / bash)
  max_result_chars: 30000  # oversized tool results go to the object store
  timeout_secs: 0          # tool execution timeout, 0 = unlimited
  web_search:
    provider: exa          # exa / parallel — whichever has a key
    timeout_secs: 25

checkpoint:                # local history — see the Local history section
  enabled: true
  max_file_size_mb: 20
  budget_gb: 2
  exclude: []
  exclude_dirs: []
  build_dirs: []
  max_build_dir_files: 2000
  retention_days: 30

worktree:
  dir: "../{workspace}-worktrees"   # where sub-agent worktrees are checked out

cost:                      # which currency the books are kept in
  display_currency: USD
  rates: []                # e.g. {from: USD, to: CNY, rate: 7.2}

limits:                    # anti-hang guardrails, not a budget
  max_rounds: 150          # max LLM rounds per turn
  max_depth: 2             # max sub-agent nesting depth

log:
  level: info              # error / warn / info / debug / trace
  to_file: true            # write to state/logs/ (the terminal UI swallows stderr)

marketplace:               # optional download mirrors (when GitHub is unreachable)
  github_release_mirror: null
  node_dist_mirror: null

models.yaml

Your providers and models — the full shape is in #Providers & Models:

auto_detect_env: true      # default true — read API keys from environment variables

providers:
  my-provider:
    sdk: openai_chat       # openai_chat / openai_responses / deepseek / glm / dashscope /
                           # qwen_local / openrouter / fireworks / anthropic / gemini /
                           # bedrock / openai_generic
    base_url: https://api.openai.com/v1
    models:
      gpt-4o: {}

models.yaml only accepts provider/model settings — deny_unknown_fields rejects misplaced keys like context: or session: there. Put those in config.yaml. API keys are not written here (there is no api_key field) — they come from the environment or the OS keyring, see #Key Management.

policy.yaml — approvals & budget

Both the security policy and the cost budget live in policy.yaml (global at the config root, project-level at .zlogic/policy.yaml in the project root). Project policy tightens the global one, never loosens it.

policy:                    # approval rules — see Security & Approvals
  version: 1
  default: ask             # ask / allow / deny — fail-closed
  commands: []             # simple-command rules (POSIX)
  exec: []                 # exec rules
  paths: []                # path rules (sensitive paths)
  scripts: []              # script rules
  protected_delete: []     # paths that must survive any deletion
  protected_write: []      # paths whose writes can never be auto-approved

budget:                    # demand-side cost limits
  per_turn: 0.5            # max spend per turn (includes sub-agents)
  per_session: 5           # max spend per conversation
  per_task: 1              # max spend per background task (defaults to per_turn)
  window:                  # rolling time window total
    hours: 24
    amount: 10
  action: ask              # what happens when a limit is hit (ask / stop)

A broken budget: section only disables the budget (with a visible warning); the policy: half is parsed separately and still applies.

.mcp.json (per workspace)

MCP servers for a workspace are declared in the project root:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": { "MY_VAR": "value" }
    }
  }
}

Plugins and skills installed from the Marketplace (MCP-based extensions) are managed in the desktop UI; installed skills land under the data root (skills/).

Local history (checkpoints)

Snapshots are taken around every file-changing tool call. "What did this turn change", rollback and diff undo all rely on them.

Snapshots live in a shadow object store under the local data directory — they never touch your git history or .gitignore.
The workspace opening snapshot has a size budget: if it would exceed the budget, local history stays disabled and reports the large directories instead of deciding what to exclude for you.
node_modules, .venv and similar tool caches are always excluded; build-output directories are skipped only once they hold more than max_build_dir_files files.
Turning local history off means not a single byte is written: no snapshots, and undo / rollback are unavailable.

Memory

The agent can persist durable facts across conversations (Preferences, Goals, Corrections, References). Project instructions always take precedence over memory.

Scopes: global (all workspaces) and workspace (current project).
Manage entries in desktop Settings → Memory, or from the CLI: zlogic memory (list), zlogic memory remove <id>, zlogic memory undo [global|workspace].

Extensions (Marketplace)

Plugins & skills are MCP-based extensions installed from the desktop Marketplace:

Each extension declares its capabilities; installing requires your explicit acceptance.
Extensions can be enabled / disabled / removed at any time; MCP servers contributed by extensions get their own token credentials (zlogic mcp manages them from the CLI).

Connections

Databases, object storage and cloud accounts can be configured once and assigned to specific workspaces:

Supported providers and their capabilities (read / write / exec) are declared per connection.
Credentials are stored in your OS keyring, or referenced from environment variables — never written into workspace config.
Each connection lists the workspaces it is authorized for; the agent only sees a connection in workspaces you assigned.

Security & Approvals

@zlogic.run's default security boundary: the model may propose actions, but sensitive actions require local client approval before execution.

Approval layers

The permission gate checks every tool call before it runs:

Layer	What happens	Examples
Layer 0 — Deterministic rules	Hard-coded rules decide Allow / Ask User instantly. No model call needed.	Safe read-only operations (read_file on non-sensitive paths, safe exec heads), write_file inside workspace
Layer 1 — Model review	A light-tier LLM reviews the request against the rulebook and returns a verdict.	Everything that Layer 0 couldn't decide
Layer 2 — Deep model review	If Layer 1 is uncertain, a stronger model re-reviews with the same rulebook. Available when two model tiers are configured.	Complex shell pipelines, unusual write paths
User prompt	If all auto-approval layers say "ask user", the client shows a confirmation dialog with scope options.	Dangerous operations, sensitive files

⚠️ Limitations of auto-approval

The auto-approval system (Layers 0–2) uses deterministic rules and LLM review to improve efficiency, but it cannot guarantee 100% accuracy. The LLM may misjudge a request's intent, and rules may not cover every edge case. User confirmation is the last and most important layer of the security model — before every sensitive action executes, you have the opportunity to review and decide. Do not enable God Mode in untrusted environments, and do not rely solely on auto-approval rules to defend against malicious behavior.

Grant scopes

When approving or declining, you can specify a scope:

once: allow this one time only
session: don't prompt again in this session
project: persist per working directory (stored to disk)

Existing grants can be managed via the grant list UI or the /grants command in the CLI.

Auto-approval rulebook (Layer 0)

The deterministic rules fall into two categories:

Danger rules — always ask the user:

Rule	Description
D1	Destroys data irreversibly — recursive/forced deletion outside workspace, overwriting unrelated files
D2	Reads, writes, or transmits secrets — .env files, private keys, credentials
D3	Escalates privilege or alters system state — sudo, system services, /etc
D4	Publishes or deploys — package publish, force push, release creation
D5	Exfiltrates — sends local file contents or repo data to a remote host the user didn't name
D6	Installs persistence — shell rc/profile, git hooks, login items
D7	No plausible connection to the user's request, or contradicts it

Category rules (C1–C6):

C1 read_file / list_dir: non-sensitive paths pre-approved; sensitive target triggers D2
C2 write_file inside workspace: pre-approved unless D2/D6 matches
C3 write_file outside workspace: judge by directory (temp dirs allowed, system dirs ask)
C4 exec: builds/tests/linters/formatters allowed; D-rules and git push require user confirmation
C5 network: public GET allowed; mutations and private hosts ask user
C6 other tools (MCP/plugins): apply D-rules to the action

Sensitive path patterns

When the agent reads or writes files matching any of the following patterns, Layer 0 immediately escalates to ask user (D2):

Target	Example paths
Environment files	`.env`, `.env.production`, `.env.local`
SSH keys	`~/.ssh/id_rsa`, `~/.ssh/id_ed25519`, `~/.ssh/authorized_keys`
AWS credentials	`~/.aws/config`, `~/.aws/credentials`
GitHub CLI auth	`~/.config/gh/`
GnuPG	`~/.gnupg/`
Docker config	`~/.docker/config.json`
kubectl config	`~/.kube/config`
Private key files	any file ending in `.pem` or `.key`
Private key names	`id_rsa`, `id_dsa`, `id_ed25519` (any location)
Credential dotfiles	`.npmrc`, `.pypirc`, `.netrc`

Additional patterns can be configured through paths rules in policy.yaml (global or per-project).

God Mode

God Mode bypasses most safety limits — use only in local development. Toggle in desktop Settings or via /god in the CLI.

Data Flow & Privacy

@zlogic.run has no project-owned cloud API, control plane or proxy service. A normal turn flows like this:

Data flow

Your message → Local Agent runtime → Your configured Provider → Streaming response → Local storage

Everything happens locally: message assembly, context construction, tool execution, file I/O, conversation persistence.

What we collect

@zlogic.run does NOT:

Upload conversations, code, prompts, keys or usage
Send anonymous telemetry, analytics or crash reports
Use third-party CDNs, Google Fonts, GitHub API or analytics scripts
The site is fully static — no external services

What's stored locally

Conversation history: SQLite database in the state root (~/.local/state/zlogic/state.db by default)
Configuration: config.yaml, models.yaml and policy.yaml under the config root (~/.config/zlogic/)
Keys: in your OS keyring (macOS Keychain / Windows Credential Manager / Linux Secret Service) or environment variables — never in files
Usage records: call counts, tokens and cost estimates
Grants: project-level authorizations persisted to disk
Checkpoints: local history snapshots in a shadow object store — your git is untouched
Memory: durable facts you (or the agent, with your approval) chose to persist

Deleting a conversation removes the local record. There is no cloud copy.

License

@zlogic.run is currently proprietary software — its source code is not publicly available. Parts of it may be open-sourced in the future. Third-party open-source components that the product builds on keep their own licenses (see the credits page).

Troubleshooting & FAQ

Terminal compatibility

Q: Does it work in Windows cmd.exe?

A: Windows legacy console (conhost.exe) does not support DEC 2026, has flaky CJK widths, and process.stdin doesn't surface IME composition events. Use Windows Terminal, WezTerm, Alacritty or VS Code terminal instead.

Models & Providers

Q: Does @zlogic.run use its own API?

A: No. @zlogic.run does not provide models and has no cloud API or control plane. All requests go directly to the provider endpoint you configure.

Q: Can I use local models?

A: Yes. Run Ollama, vLLM or any OpenAI-compatible local inference server, then configure it as sdk: openai-compatible.

Privacy

Q: Does @zlogic.run collect usage data?

A: No. No telemetry, no analytics, no cookies.

Q: Where are API keys stored?

A: In your OS keyring (macOS Keychain / Windows Credential Manager / Linux Secret Service), or read from environment variables at runtime. See #Key Management.

Q: Can reasoning content leak to the next provider?

A: No. Reasoning is rendered as a local thinking block and is never zlogiced into the next LLM context.

Other

Q: Is @zlogic.run open source?

A: Not yet. @zlogic.run is currently proprietary software and its source is not publicly available. Some components may be open-sourced in the future. The open-source libraries it builds on keep their own licenses.

Local history

Q: Does local history (checkpoints) touch my git?

A: No. Snapshots are stored in a shadow object store under the local data directory. Your commits, working tree and .gitignore are never modified.

Q: Why is undo / rollback unavailable?

A: Local history was probably disabled in Settings (or the initial snapshot exceeded the size budget). Turn it on in Settings → Local history; it must be enabled for "what did this turn change" and rollback to work.

Roadmap

What is being worked on next. No dates are promised — these land when they are ready.

Mobile app

A mobile companion for @zlogic.run is planned: chat, voice calls and remote approval from your phone, connecting to the agent runtime running on your own machine.

Device pairing through a one-time secret (QR code) — no accounts, no cloud relay.
Sessions, tasks and search on the go; approve sensitive actions remotely.

Daemon & remote access

The local agent runtime exposed over HTTP, which the mobile app connects to:

zlogic daemon starts the daemon; --pair prints a one-time pairing key and QR (valid 5 minutes).
Paired devices get their own scoped credentials; pairing attempts and per-device requests are rate-limited.
Expose it beyond your LAN only behind your own TLS reverse proxy.

Guide

Guide

@zlogic.run 文档

安装

一行命令安装 CLI（推荐）

桌面端

快速上手

1. 添加你的第一个 Provider

2. 启动 CLI

3. 试试桌面端

下一步

CLI 与桌面端选择

CLI

核心能力

适合场景

快捷键

桌面端

主要视图

适合场景

Provider 与模型

内置 Provider

自建与自定义端点

在 models.yaml 中添加 Provider

从环境变量读取 key

模型设置

路由

密钥管理

环境变量（默认）

系统钥匙串（持久化）

密钥不进配置文件

env.yaml —— 把密钥放进一个文件

安全建议

配置参考

数据目录

环境变量

config.yaml

models.yaml

policy.yaml —— 审批与预算

.mcp.json（工作区级）

本地历史（checkpoints）

记忆（Memory）

扩展（市场）

连接（Connections）

安全与审批

审批层级

授权范围

自动审批规则手册 (Layer 0)

敏感路径模式

God Mode

数据流与隐私

数据流

收集什么

本地存储什么

许可证

常见问题

终端兼容

模型与 Provider

隐私

其他

本地历史

Roadmap

移动端 App

daemon 与远程访问

@zlogic.run Docs

Installation

One-line CLI install (recommended)

Desktop app

Quick Start

1. Add your first Provider

2. Launch the CLI

3. Try the desktop app

Next steps

Choosing CLI vs Desktop

CLI

Core capabilities

Best for

Shortcuts

Desktop

Main views

Best for

在 `models.yaml` 中添加 Provider

Adding a provider in `models.yaml`