跳到主要内容

配置

所有设置都存储在 ~/.kopi/ 目录中,方便访问。

最快配置可用 config.yaml 的方法

运行 kopi setup --portal —— 一次 OAuth 即可获得 model provider(模型服务提供商)和全部四个 Tool Gateway 工具,无需手动编辑 YAML。KOPI Proxy 订阅用户还可享受按 token 计费的 provider(服务提供商)九折优惠。参见 KOPI Proxy。

目录结构​

~/.kopi/
├── config.yaml # Settings (model, terminal, TTS, compression, etc.)
├── .env # API keys and secrets
├── auth.json # OAuth provider credentials (KOPI Proxy, etc.)
├── SOUL.md # Primary agent identity (slot #1 in system prompt)
├── memories/ # Persistent memory (MEMORY.md, USER.md)
├── skills/ # Agent-created skills (managed via skill_manage tool)
├── cron/ # Scheduled jobs
├── sessions/ # Gateway sessions
└── logs/ # Logs (errors.log, gateway.log — secrets auto-redacted)

管理配置​

kopi config              # View current configuration
kopi config edit # Open config.yaml in your editor
kopi config set KEY VAL # Set a specific value
kopi config check # Check for missing options (after updates)
kopi config migrate # Interactively add missing options

# Examples:
kopi config set model anthropic/claude-opus-4
kopi config set terminal.backend docker
kopi config set OPENROUTER_API_KEY sk-or-... # Saves to .env
提示

kopi config set 命令会自动将值路由到正确的文件 —— API keys 会保存到 .env,其他内容保存到 config.yaml。

配置优先级​

设置按以下顺序解析(优先级从高到低):

  1. CLI arguments(命令行参数) —— 例如 kopi chat --model anthropic/claude-sonnet-4(每次调用时的覆盖)
  2. ~/.kopi/config.yaml —— 所有非敏感设置的主配置文件
  3. ~/.kopi/.env —— env vars 的备选来源;敏感信息(API keys、tokens、密码)必须放在此处
  4. 内置默认值 —— 当未设置任何内容时使用的硬编码安全默认值
经验法则

敏感信息(API keys、bot tokens、密码)放在 .env 中。其他内容(model、terminal backend、压缩设置、内存限制、toolsets)放在 config.yaml 中。当两者都设置了时,非敏感设置以 config.yaml 为准。

组织部署

管理员可以通过系统级托管目录,固定特定的 config 和 secret 值,使普通用户无法覆盖。参见 Managed Scope。

环境变量替换​

你可以在 config.yaml 中使用 ${VAR_NAME} 语法引用环境变量:

auxiliary:
vision:
api_key: ${GOOGLE_API_KEY}
base_url: ${CUSTOM_VISION_URL}

delegation:
api_key: ${DELEGATION_KEY}

在单个值中进行多次引用是可行的:url: "${HOST}:${PORT}"。如果引用的变量未设置,占位符将原样保留(${UNDEFINED_VAR} 保持不变)。仅支持 ${VAR} 语法 —— 单独的 $VAR 不会被展开。

关于 AI provider(服务提供商)的设置(OpenRouter、Anthropic、Copilot、自定义端点、自托管 LLMs、fallback models 等),参见 AI Providers。

Provider 超时​

你可以设置 providers.<id>.request_timeout_seconds 来指定 provider(服务提供商)级别的请求超时,也可以设置 providers.<id>.models.<model>.timeout_seconds 进行针对特定 model 的覆盖。适用于所有传输方式(OpenAI-wire、原生 Anthropic、Anthropic-compatible)上的主要轮次客户端、fallback 链、凭据轮换后的重建,以及(对于 OpenAI-wire)每次请求的 timeout kwarg —— 因此配置的值优先于旧的 KOPI_API_TIMEOUT env var。

你还可以设置 providers.<id>.stale_timeout_seconds 用于非流式的陈旧调用检测器,以及 providers.<id>.models.<model>.stale_timeout_seconds 进行针对特定 model 的覆盖。这优先于旧的 KOPI_API_CALL_STALE_TIMEOUT env var。

保持这些项未设置时,将沿用旧的默认值(KOPI_API_TIMEOUT=1800s、KOPI_API_CALL_STALE_TIMEOUT=90s、原生 Anthropic 900 秒)。非流式陈旧检测器在未显式设置时会对本地端点自动禁用,并可在超大上下文场景下向上调整。目前尚未接入 AWS Bedrock(bedrock_converse 和 AnthropicBedrock SDK 路径均使用 boto3,由其自行管理 timeout 配置)。参见 cli-config.yaml.example 中带注释的示例。

更新行为​

kopi update 设置位于 config.yaml 中的 updates 下:

updates:
pre_update_backup: false # Create a full KOPI_HOME zip before every update
backup_keep: 5 # Keep this many pre-update backup zips
non_interactive_local_changes: stash # stash | discard

对于 git 安装,Kopi Agent 在检出更新分支或拉取之前,会自动 stash(暂存)有改动的已跟踪文件和未跟踪文件。交互式终端更新会在恢复该 stash 前进行提示。非交互式更新(desktop/chat app、gateway 或 --yes)使用 updates.non_interactive_local_changes:stash 会在成功拉取后恢复本地源码修改,而 discard 会在成功拉取后丢弃更新过程中创建的 stash。仅在托管安装(本地源码修改本就不应保留)中使用 discard。

在执行该 stash 步骤之前,Kopi Agent 还会恢复 npm install/build 变动留下的已跟踪 package-lock.json diff。请在更新前提交或手动 stash 有意为之的 lockfile 修改。

终端后端配置​

Kopi Agent 支持六种终端后端。每种后端决定了 agent 的 shell 命令实际在哪里执行——你的本地机器、一个 Docker 容器、通过 SSH 连接的远程服务器、一个 Modal 云沙箱(直接连接或经由 Nous 托管的网关)、一个 Daytona workspace,或一个 Singularity/Apptainer 容器。

terminal:
backend: local # local | docker | ssh | modal | daytona | singularity
cwd: "." # Gateway/cron working directory (CLI always uses launch dir)
timeout: 180 # Per-command timeout in seconds
home_mode: auto # auto | real | profile — subprocess HOME policy
env_passthrough: [] # Env var names to forward to sandboxed execution (terminal + execute_code)
singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20" # Container image for Singularity backend
modal_image: "nikolaik/python-nodejs:python3.11-nodejs20" # Container image for Modal backend
daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20" # Container image for Daytona backend

对于 Modal 和 Daytona 等云沙箱,container_persistent: true 表示 Kopi Agent 会尝试在沙箱重建后保留文件系统状态。它并不保证同一个运行中的沙箱、PID 空间或后台进程在稍后仍然存在。

后端概览​

后端命令运行位置隔离性适用场景
local直接在你的机器上无开发、个人使用
docker单个持久化 Docker 容器(在 session、/new、subagents 之间共享)完整(namespaces、cap-drop)安全沙箱、CI/CD
ssh通过 SSH 连接的远程服务器网络边界远程开发、高性能硬件
modalModal 云沙箱完整(云 VM)临时性云计算、评估
daytonaDaytona workspace完整(云容器)托管式云开发环境
singularitySingularity/Apptainer 容器namespaces(--containall)HPC 集群、共享机器

Local 后端​

默认后端。命令直接在你的机器上运行,没有隔离。无需特殊配置。

terminal:
backend: local

默认情况下,本地工具子进程会保留你真实的操作系统用户 HOME。这样, git、ssh、gh、az、npm、Claude Code 和 Codex 等外部 CLI 就能找到它们在你正常 shell 中已经在使用的凭据和配置。Kopi Agent 的 state 仍然通过 KOPI_HOME 按 profile 划分作用域;HOME 并不是 profile 选择 config、memory、session 或 skill 的方式。

Kopi Agent 不会更改你的系统级 HOME、shell 启动文件或操作系统的账户 home。这个设置只控制传给 Kopi Agent 通过 terminal 等工具启动的子进程的环境, 这些子进程包括后台终端进程、execute_code 以及 ACP 辅助进程。

terminal.home_mode​

模式宿主机安装容器权衡
auto保留真实的操作系统用户 HOME使用 {KOPI_HOME}/home推荐默认值。宿主机 CLI 继续正常工作;容器状态得以保留。
real强制使用真实的操作系统用户 HOME如果可见,则强制使用真实的操作系统用户 HOME当父进程意外地以 HOME 指向 profile home 的方式启动时很有用。
profile存在时使用 {KOPI_HOME}/home存在时使用 {KOPI_HOME}/home严格的按 profile 划分的 CLI config 隔离,但普通的 ~/.ssh、~/.gitconfig、~/.azure、~/.config/gh、Claude/Codex 认证、npm 状态等将不可见,除非你在该 profile home 内初始化或链接它们。

默认值的缺点是,各宿主 profile 会共享 ~ 下相同的普通 用户级 CLI 凭据/配置。如果你需要一个拥有独立 git 身份、SSH 密钥、GitHub CLI 登录、npm config 或云 CLI 登录的 profile,请使用 home_mode: profile,并有意地在该 profile home 内初始化这些工具。

如果你确实想要严格的按 profile 划分的工具配置隔离,请设置:

terminal:
home_mode: profile

在该模式下,工具子进程使用 {KOPI_HOME}/home 作为 HOME。Kopi Agent 还会 设置 KOPI_REAL_HOME,以便脚本在需要时仍能找到实际的用户 home。 容器后端在 auto 模式下继续使用 {KOPI_HOME}/home,因为该目录位于持久化的 Kopi Agent 数据卷上。

需要区分 profile 状态和真实用户 home 的脚本应当优先使用 KOPI_HOME 来获取 Kopi Agent 数据,使用 KOPI_REAL_HOME 来获取账户 home:

from pathlib import Path
import os

kopi_home = Path(os.environ["KOPI_HOME"])
real_home = Path(os.environ.get("KOPI_REAL_HOME", os.environ["HOME"]))
注意

agent 拥有与你的用户账户相同的文件系统访问权限。请使用 kopi tools 禁用你不想要的工具,或改用 Docker 来获得沙箱隔离。

Docker 后端​

在 Docker 容器内运行命令,并带有安全加固(丢弃所有 capabilities、禁止权限提升、PID 数量限制)。

单个持久化容器,在 Kopi Agent 进程之间共享。 Kopi Agent 在首次使用时启动 ONE 个长期运行的容器,并把每个终端、文件和 execute_code 调用都通过 docker exec 路由到同一个容器中——跨 session、/new、/reset 和 delegate_task subagent 都是如此。工作目录的变更、已安装的软件包、/workspace 中的文件,以及后台进程都会从一次工具调用延续到下一次工具调用,并从一个 Kopi Agent 进程延续到下一个。当你关闭一个 TUI session、运行 /quit 或启动一个新的 kopi 调用时,容器会继续运行,下一个 Kopi Agent 进程会通过标签查找复用它。确切的拆除规则请参见下文的容器生命周期。

terminal:
backend: docker
docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
docker_mount_cwd_to_workspace: false # Mount launch dir into /workspace
docker_run_as_host_user: false # See "Running container as host user" below
docker_forward_env: # Host env vars to forward into container
- "GITHUB_TOKEN"
docker_env: # Literal env vars to inject (KEY=value)
DEBUG: "1"
PYTHONUNBUFFERED: "1"
docker_volumes: # Host directory mounts
- "/home/user/projects:/workspace/projects"
- "/home/user/data:/data:ro" # :ro for read-only
docker_extra_args: # Extra flags appended verbatim to `docker run`
- "--gpus=all"
- "--network=host"
docker_network: true # false = air-gap the container (--network=none)

# Resource limits
container_cpu: 1 # CPU cores (0 = unlimited)
container_memory: 5120 # MB (0 = unlimited)
container_disk: 51200 # MB (requires overlay2 on XFS+pquota)
container_persistent: true # Persist /workspace and /root bind-mount dirs

# Cross-process container reuse (defaults match the "one long-lived
# container shared across sessions" contract — see Container lifecycle).
docker_persist_across_processes: true # Reuse container across Kopi Agent restarts
docker_orphan_reaper: true # Sweep abandoned Exited containers at startup

# Cross-backend lifecycle settings (apply to docker as well)
timeout: 180 # Per-command timeout in seconds
lifetime_seconds: 300 # Idle-reaper window; also feeds 2× orphan-reaper threshold

docker_env 与 docker_forward_env:前者注入你在 config 中指定的字面 KEY=value 键值对(这些值存放在你的 config.yaml 中,或通过 TERMINAL_DOCKER_ENV='{"DEBUG":"1"}' 以 JSON dict 的形式传入)。后者转发来自你 shell 或 ~/.kopi/.env 的值,因此实际的 secret 绝不会出现在 config 文件中。token 请使用 docker_forward_env,容器所需的静态开关请使用 docker_env。

terminal.docker_extra_args(也可以通过 TERMINAL_DOCKER_EXTRA_ARGS='["--gpus=all"]' 覆盖)允许你传入任意 docker run 标志,这些标志没有被 Kopi Agent 作为一等 config 键暴露出来——--gpus、--network、--add-host、替代的 --security-opt 覆盖等等。每个条目必须是字符串;该列表会最后追加到组装好的 docker run 调用中,因此如有需要可以覆盖 Kopi Agent 的默认值。请谨慎使用——与沙箱加固冲突的标志(capability 丢弃、--user、workspace 绑定挂载)会悄悄削弱隔离性。

terminal.docker_network(默认 true;env:TERMINAL_DOCKER_NETWORK)——设置为 false 时会以 --network=none 运行沙箱容器,切断该容器的所有网络出站连接 自 agent 命令。这适用于 terminal、execute_code 和文件工具所使用的执行容器。由于容器在 Kopi Agent 进程之间持续存在,如果在已存在较旧的联网容器时将该项切换为 false,则会移除该容器并启动一个全新的、与网络隔离(air-gapped)的容器(会记录一条警告);其中运行的后台进程会丢失。优先使用该键,而非通过 docker_extra_args 传递 --network=none。

要求: 已安装并运行 Docker Desktop 或 Docker Engine。Kopi Agent 会探测 $PATH 以及常见的 macOS 安装位置(/usr/local/bin/docker、/opt/homebrew/bin/docker、Docker Desktop 应用包)。Podman 开箱即用:当两者都已安装时,设置 KOPI_DOCKER_BINARY=podman(或完整路径)以强制使用它。

容器生命周期​

每个由 Kopi Agent 管理的容器都带有三个 label 标签,以便后续进程(以及孤儿回收器)能够识别它:

  • kopi-ai-agent=1 — 将其标记为由 Kopi Agent 管理
  • kopi-task-id=<sanitized task_id> — 作为按任务复用探测的键
  • kopi-profile=<sanitized profile name> — 将复用和回收范围限定在当前激活的 Kopi Agent profile

启动时,Kopi Agent 运行 docker ps --filter label=kopi-task-id=<id> --filter label=kopi-profile=<profile>,并在找到已有容器时连接(attach)到该容器。如果容器处于 exited 状态(例如在 Docker daemon 重启之后),它会被 docker start 并复用 —— 文件系统状态和已安装的包会保留,但容器内的后台进程不会。

当 Kopi Agent 进程退出时 —— /quit、关闭 TUI 会话、gateway 关闭,甚至 SIGKILL —— 清理路径对默认模式下的容器而言是空操作(no-op)。容器会继续运行。下一个 Kopi Agent 进程会在几毫秒内通过 label 探测连接到它。这正是“跨会话共享的单个长生命周期容器”这一约定所要求的行为:这也是后台进程(npm watchers、开发服务器、长时间运行的 pytest)能够在跨会话后存活的唯一方式。

仅在以下情况下容器才会被拆除(停止并 docker rm -f):

触发条件触发时机
docker_persist_across_processes: false显式的按进程隔离。每个 cleanup() 都会执行 stop + rm -f。与 issue #20561 之前的行为一致。
空闲回收器(lifetime_seconds,默认 300 秒)仅当 env 为 persist_across_processes=false 时触发。persist 模式的 env 会被跳过(no-op);容器在空闲清理中存活。
下次启动时的孤儿回收器清理带有 kopi label 的、处于 Exited 状态且超过 2 × lifetime_seconds 的容器(默认 600 秒 = 10 分钟),范围限定为当前 profile。运行中的容器绝不会被触碰 —— 这是为了保证兄弟进程的安全。设置 docker_orphan_reaper: false 可禁用。
用户的直接操作docker rm -f、docker system prune、重启 Docker Desktop。我们不设置 --restart=always,因此宿主机重启会让容器处于 Exited 状态(其 CoW 层会保留并在下次启动时被复用,但后台进程会丢失)。

值得了解的边界情况:

  • 容器内 PID 1 遭到 OOM kill 会使容器转入 Exited。下次复用时会将其 docker start;文件系统状态保留,后台进程不保留。
  • 切换 profile 会使容器之间相互隔离 —— 带有 kopi-profile=work 标签的容器对运行在 kopi-profile=research 下的 Kopi Agent 进程不可见。孤儿回收器同样按 profile 划分范围,因此跨 profile 的容器不会被意外回收,但在你再次于其原 profile 下启动 Kopi Agent 之前,它们也不会被自动清理。

通过 delegate_task(tasks=[...]) 生成的并行 subagent 共享同一个容器 —— 并发的 cd、env 变更以及对同一路径的写入会发生冲突。如果某个 subagent 需要隔离的 sandbox,它必须通过 register_task_env_overrides() 注册按任务的镜像覆盖,RL 与基准测试环境(TerminalBench2、HermesSweEnv 等)会为其按任务的 Docker 镜像自动完成这一操作。

安全加固:

  • --cap-drop ALL,仅重新添加 DAC_OVERRIDE、CHOWN、FOWNER
  • --security-opt no-new-privileges
  • --pids-limit 256
  • 为 /tmp(512MB)、/var/tmp(256MB)、/run(64MB)设置大小受限的 tmpfs

凭据转发: docker_forward_env 中列出的环境变量会先从你的 shell 环境中解析,然后是 ~/.kopi/.env。Skill 还可以声明 required_environment_variables,它们会被自动合并。

环境变量覆盖​

terminal: 下的每个键都具有 TERMINAL_<KEY_UPPERCASE> 形式的环境变量覆盖。对 Docker 后端最有用的几个:

环境变量映射到说明
TERMINAL_DOCKER_IMAGEdocker_image基础镜像
TERMINAL_DOCKER_FORWARD_ENVdocker_forward_envJSON 数组:'["GITHUB_TOKEN","OPENAI_API_KEY"]'
TERMINAL_DOCKER_ENVdocker_envJSON 字典:'{"DEBUG":"1"}'
TERMINAL_DOCKER_VOLUMESdocker_volumes由 "host:container[:ro]" 字符串组成的 JSON 数组
TERMINAL_DOCKER_EXTRA_ARGSdocker_extra_argsJSON 数组
TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACEdocker_mount_cwd_to_workspacetrue / false
TERMINAL_DOCKER_RUN_AS_HOST_USERdocker_run_as_host_usertrue / false
TERMINAL_DOCKER_NETWORKdocker_networktrue / false — 默认 true;false = --network=none
TERMINAL_DOCKER_PERSIST_ACROSS_PROCESSESdocker_persist_across_processestrue / false — 默认 true
TERMINAL_DOCKER_ORPHAN_REAPERdocker_orphan_reapertrue / false — 默认 true
TERMINAL_CONTAINER_CPUcontainer_cpuCPU 核心数
TERMINAL_CONTAINER_MEMORYcontainer_memoryMB
TERMINAL_CONTAINER_DISKcontainer_diskMB
TERMINAL_CONTAINER_PERSISTENTcontainer_persistenttrue / false — 控制 bind-mount 的工作区目录,与 docker_persist_across_processes 不同
TERMINAL_LIFETIME_SECONDSlifetime_seconds空闲回收器时间窗口
TERMINAL_TIMEOUTtimeout每条命令的超时时间
KOPI_DOCKER_BINARY无强制指定 docker/podman 可执行文件路径

SSH 后端​

通过 SSH 在远程服务器上运行命令。使用 ControlMaster 进行连接复用(空闲保活 5 分钟)。默认启用持久 shell —— 状态(cwd、环境变量)在多条命令之间保持。

terminal:
backend: ssh
persistent_shell: true # Keep a long-lived bash session (default: true)

必需的环境变量:

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

可选:

变量默认值说明
TERMINAL_SSH_PORT22SSH 端口
TERMINAL_SSH_KEY(系统默认)SSH 私钥路径
TERMINAL_SSH_PERSISTENTtrue启用持久 shell

工作原理: 在初始化时通过 BatchMode=yes 和 StrictHostKeyChecking=accept-new 建立连接。持久化 shell 会在远程主机上保持单个 bash -l 进程存活,通过临时文件进行通信。需要 stdin_data 或 sudo 的命令会自动回退到一次性模式。

在 Modal 云沙箱中运行命令。每个任务都会获得一个隔离的 VM,其 CPU、内存和磁盘均可配置。文件系统可在多个会话之间快照/恢复。

terminal:
backend: modal
container_cpu: 1 # CPU cores
container_memory: 5120 # MB (5GB)
container_disk: 51200 # MB (50GB)
container_persistent: true # Snapshot/restore filesystem

**必需项:**要么提供 MODAL_TOKEN_ID + MODAL_TOKEN_SECRET 环境变量,要么提供 ~/.modal.toml config 文件。

**持久化:**启用后,沙箱文件系统会在清理时快照,并在下次会话时恢复。快照记录在 ~/.kopi/modal_snapshots.json 中。这仅保留文件系统状态,不会保留活跃进程、PID 空间或后台任务。

**凭据文件:**自动从 ~/.kopi/ 挂载(OAuth token 等),并在每条命令执行前同步。

Daytona Backend​

在 Daytona 托管工作区中运行命令。支持通过停止/恢复实现持久化。

terminal:
backend: daytona
container_cpu: 1 # CPU cores
container_memory: 5120 # MB → converted to GiB
container_disk: 10240 # MB → converted to GiB (max 10 GiB)
container_persistent: true # Stop/resume instead of delete

必需项:DAYTONA_API_KEY 环境变量。

**持久化:**启用后,沙箱在清理时会被停止(而非删除),并在下次会话时恢复。沙箱名称遵循 kopi-{task_id} 模式。

**磁盘上限:**Daytona 强制最大 10 GiB。超过该限制的请求会被截断并给出警告。

Singularity/Apptainer Backend​

在 Singularity/Apptainer 容器中运行命令。专为无法使用 Docker 的 HPC 集群和共享机器设计。

terminal:
backend: singularity
singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
container_cpu: 1 # CPU cores
container_memory: 5120 # MB
container_persistent: true # Writable overlay persists across sessions

依赖项:$PATH 中的 apptainer 或 singularity 可执行文件。

**镜像处理:**Docker URL(docker://...)会自动转换为 SIF 文件并缓存。已有的 .sif 文件会直接使用。

**临时目录:**按以下顺序解析:TERMINAL_SCRATCH_DIR → TERMINAL_SANDBOX_DIR/singularity → /scratch/$USER/kopi-ai-agent(HPC 约定)→ ~/.kopi/sandboxes/singularity。

**隔离性:**使用 --containall --no-home 实现完整的命名空间隔离,且不挂载宿主机的 home 目录。

常见终端后端问题​

如果终端命令立即失败,或终端工具被报告为已禁用:

  • Local — 无特殊要求。入门时最安全的默认选项。
  • Docker — 运行 docker version 验证 Docker 是否正常。若失败,请修复 Docker 或 kopi config set terminal.backend local。
  • SSH — TERMINAL_SSH_HOST 和 TERMINAL_SSH_USER 都必须设置。如果缺少其中任意一项,Kopi Agent 会记录清晰的错误信息。
  • Modal — 需要 MODAL_TOKEN_ID 环境变量或 ~/.modal.toml。运行 kopi doctor 进行检查。
  • Daytona — 需要 DAYTONA_API_KEY。Daytona SDK 负责处理服务器 URL 配置。
  • Singularity — 需要 $PATH 中的 apptainer 或 singularity。在 HPC 集群中很常见。

如有疑问,将 terminal.backend 设置回 local,并先验证命令能在该模式下正常运行。

远程到宿主机的文件同步(Teardown 阶段)​

对于 SSH、Modal 和 Daytona 后端(即 agent 的工作树位于运行 Kopi Agent 的宿主机之外的机器上时),Kopi Agent 会跟踪 agent 在远程沙箱中修改过的文件,并在会话拆除/沙箱清理时,将修改过的文件同步回宿主机的 ~/.kopi/cache/remote-syncs/<session-id>/ 下。

  • 触发时机:会话关闭、/new、/reset、网关消息超时、使用远程后端的 delegate_task 子 agent 完成时。
  • 覆盖 agent 修改过的整个目录树,而不仅仅是它显式打开的文件。新增、编辑和删除都会被捕获。
  • 当你去查找文件时,远程沙箱可能已经被拆除;本地的 ~/.kopi/cache/remote-syncs/… 副本才是 agent 所做更改的权威记录。
  • 大型二进制产物(模型检查点、原始数据集)受大小上限约束 — 同步会跳过超过 file_sync_max_mb 的文件(默认 100)。如果你预期会有更大的产物返回,请调高该值。
terminal:
file_sync_max_mb: 100 # default — sync files up to 100 MB each
file_sync_enabled: true # default — set false to skip the sync entirely

这就是如何从会话结束后即被销毁的一次性云沙箱中恢复结果的方式,无需让 agent 显式地 scp 或 modal volume put 每一个产物。

Docker 卷挂载​

使用 Docker 后端时,docker_volumes 允许你与容器共享宿主机目录。每个条目使用标准的 Docker -v 语法:host_path:container_path[:options]。

terminal:
backend: docker
docker_volumes:
- "/home/user/projects:/workspace/projects" # Read-write (default)
- "/home/user/datasets:/data:ro" # Read-only
- "/home/user/.kopi/cache/documents:/output" # Gateway-visible exports

这在以下场景中非常有用:

  • 向 agent 提供文件(数据集、配置、参考代码)
  • 从 agent 接收文件(生成的代码、报告、导出结果)
  • 共享工作区,你和 agent 访问相同的文件

如果你使用消息网关,并希望 agent 通过 MEDIA:/... 发送生成的文件,建议使用专用的宿主机可见导出挂载点,例如 /home/user/.kopi/cache/documents:/output。

  • 在 Docker 内将文件写入 /output/...
  • 在 MEDIA: 中输出宿主机路径,例如: MEDIA:/home/user/.kopi/cache/documents/report.txt
  • 不要输出 /workspace/... 或 /output/...,除非该路径在宿主机上也 对网关进程同样存在
注意

YAML 中的重复键会静默覆盖之前的值。如果你已经有 docker_volumes: 块,请将新的挂载项合并到同一个列表中,而不要在文件后面 再添加另一个 docker_volumes: 键。

也可以通过环境变量设置:TERMINAL_DOCKER_VOLUMES='["/host:/container"]'(JSON 数组)。

Docker 凭据转发​

默认情况下,Docker 终端会话不会继承宿主机的任意凭据。如果你需要在容器内使用某个特定的 token,请将其添加到 terminal.docker_forward_env。

terminal:
backend: docker
docker_forward_env:
- "GITHUB_TOKEN"
- "NPM_TOKEN"

Kopi Agent 首先从你当前的 shell 中解析每个列出的变量,如果该变量曾通过 kopi config set 保存过,则回退到 ~/.kopi/.env。

注意

docker_forward_env 中列出的所有内容对容器内运行的命令均可见。只转发你愿意暴露给终端会话的凭据。

以宿主机用户身份运行容器​

默认情况下,Docker 容器以 root(UID 0)身份运行。在 /workspace 或其他绑定挂载中创建的文件在宿主机上归 root 所有,因此会话结束后你必须先 sudo chown 它们,才能从宿主机编辑器中编辑。terminal.docker_run_as_host_user 标志可以解决这个问题:

terminal:
backend: docker
docker_run_as_host_user: true # default: false

启用后,Kopi Agent 会将 --user $(id -u):$(id -g) 追加到 docker run 命令,使写入绑定挂载目录(/workspace、/root 以及 docker_volumes 中的任何目录)的文件归你的宿主机用户所有,而非 root。代价是:容器将无法再 apt install 或写入 /root/.npm 这类 root 所有的路径 — 如果你需要两者兼得,请使用 HOME 归非 root 用户所有的基础镜像(或在构建镜像时添加所需的工具链)。

保持此项 false(默认值)以获得向后兼容的行为。当你的工作流主要是"编辑挂载的宿主机文件",并且厌倦了 sudo chown -R 时,再将其开启。

可选:将启动目录挂载到 /workspace​

Docker 沙箱默认保持隔离。除非你显式选择启用,否则 Kopopi Agent 不会将你当前的宿主机工作目录传入容器。

在 config.yaml 中启用:

terminal:
backend: docker
docker_mount_cwd_to_workspace: true

启用后:

  • 如果你从 ~/projects/my-app 启动 Kopi Agent,该宿主机目录会被绑定挂载到 /workspace
  • Docker 后端会从 /workspace 启动
  • 文件工具和终端命令都能看到同一个已挂载的项目

禁用时,/workspace 仍归沙箱所有,除非你通过 docker_volumes 显式挂载内容。

安全性权衡:

  • false 保持沙箱边界
  • true 让沙箱直接访问你启动 Kopi Agent 所在的目录

仅在你确实希望容器处理活跃的宿主机文件时,才使用这个 opt-in 选项。

持久化 Shell​

默认情况下,每条终端命令都在各自的子进程中运行 —— 工作目录、环境变量和 shell 变量会在命令之间重置。启用持久化 shell 后,一个长期存活的 bash 进程会在多次 execute() 调用之间保持活跃,从而使状态在命令之间得以保留。

这对 SSH 后端最为有用,它同时还能消除每条命令的连接开销。持久化 shell 对 SSH 默认启用,对 local 后端默认禁用。

terminal:
persistent_shell: true # default — enables persistent shell for SSH

要禁用:

kopi config set terminal.persistent_shell false

跨命令保留的内容:

  • 工作目录(cd /tmp 会延续到下一条命令)
  • 导出的环境变量(export FOO=bar)
  • Shell 变量(MY_VAR=hello)

优先级:

层级变量默认值
Configterminal.persistent_shelltrue
SSH overrideTERMINAL_SSH_PERSISTENT遵循 config
Local overrideTERMINAL_LOCAL_PERSISTENTfalse

每个后端对应的环境变量优先级最高。如果你也希望在 local 后端启用持久化 shell:

export TERMINAL_LOCAL_PERSISTENT=true
备注

需要 stdin_data 或 sudo 的命令会自动回退到一次性模式,因为持久化 shell 的 stdin 已被 IPC 协议占用。

详情请参阅代码执行和 README 的终端章节中关于各后端的说明。

Skill 设置​

Skill 可以通过其 SKILL.md 的 frontmatter 声明自己的配置设置。这些是非机密值(路径、偏好、领域设置),存储在 config.yaml 中的 skills.config 命名空间下。

skills:
config:
myplugin:
path: ~/myplugin-data # Example — each skill defines its own keys

Skill 设置的工作原理:

  • kopi config migrate 会扫描所有已启用的 skill,找出未配置的设置,并提示你进行配置
  • kopi config show 会在 "Skill Settings" 下显示所有 skill 设置及其所属的 skill
  • 当 skill 加载时,其解析后的配置值会自动注入到 skill 上下文中

手动设置取值:

kopi config set skills.config.myplugin.path ~/myplugin-data

有关在你自己的 skill 中声明 config 设置的详情,请参阅 Creating Skills — Config Settings。

对 agent 创建的 skill 写入进行防护​

当 agent 使用 skill_manage 创建、编辑、修补或删除 skill 时,Kopi Agent 可以选择性地扫描新的/更新后的内容,查找危险的关键词模式(凭据收集、明显的 prompt injection、数据外泄指令)。该扫描器默认关闭 —— 真实的 agent 工作流中合法地涉及 ~/.ssh/ 或提及 $OPENAI_API_KEY 的情况太频繁地误触了该启发式规则。如果你希望扫描器在 agent 的 skill 写入落盘前提示你,请重新开启它:

skills:
guard_agent_created: true # default: false

开启后,任何被标记的 skill_manage 写入都会作为审批提示浮现,并附带扫描器给出的理由。接受的写入会落盘;被拒绝的写入会向 agent 返回带有解释说明的错误。

Skill 写入的写入审批​

与上述内容扫描器相互独立,skills.write_approval 会将每一次 agent skill 写入(创建 / 编辑 / 修补 / 删除 / 支持文件)置于你的显式审批之后 —— 与危险命令采用相同的批准/拒绝机制:

skills:
write_approval: false # false = write freely (default) | true = stage every write for review

开启后,skill 写入会被暂存到 ~/.kopi/pending/skills/ 下,并通过 /skills pending、/skills diff <id>、/skills approve <id>、/skills reject <id> 进行审查 —— 可在 CLI 或任意消息平台上进行。可通过 /skills approval on|off 在运行时切换。Memory 也有同样的门控(memory.write_approval,见下文)。完整演练:Gating agent skill writes。

Memory 配置​

memory:
memory_enabled: true
user_profile_enabled: true
memory_char_limit: 2200 # ~800 tokens
user_char_limit: 1375 # ~500 tokens
write_approval: false # true = require approval before any memory write

启用 memory.write_approval: true 后,memory 写入需要经过你的批准才会落盘:交互式 CLI 会内联提示;消息会话以及后台的自我改进审查会将写入暂存,等待 /memory pending → /memory approve <id> / /memory reject <id> 审查。可通过 /memory approval on|off 在运行时切换。参见 Controlling memory writes。

上下文文件截断​

控制 Kopi Agent 在对每个自动上下文文件应用头/尾截断前,会从中加载多少内容。这适用于注入到 system prompt 的文件,例如 SOUL.md、.kopi.md、AGENTS.md、CLAUDE.md 以及 .cursorrules。它不会影响 read_file 工具。

context_file_max_chars: 20000  # default

当你有意保留较大的身份或项目上下文文件,并使用具有足够 context window 的模型来承载它们时,可以调高该值:

context_file_max_chars: 25000

文件读取安全​

控制单次 read_file 调用能返回多少内容。超出限制的读取会被拒绝,并返回一个错误,告知 agent 使用 offset 和 limit 来获取更小范围的内容。这可以防止单次读取压缩后的 JS bundle 或大型数据文件时淹没 context window。

file_read_max_chars: 100000  # default — ~25-35K tokens

如果你使用的模型具有较大的 context window,并且经常读取大文件,可以调高该值。对于 context 较小的模型,可调低该值以保持读取的高效:

# Large context model (200K+)
file_read_max_chars: 200000

# Small local model (16K context)
file_read_max_chars: 30000

agent 还会自动对文件读取进行去重 —— 如果同一文件区域被读取两次且文件未发生变化,则会返回一个轻量级存根,而不会重新发送内容。这会在上下文压缩时重置,因此 agent 可以在文件内容被摘要掉之后重新读取这些文件。

工具输出截断限制​

有三个相互关联的上限,用于控制工具在 Kopi Agent 截断之前能返回多少原始输出:

tool_output:
max_bytes: 50000 # terminal output cap (chars)
max_lines: 2000 # read_file pagination cap
max_line_length: 2000 # per-line cap in read_file's line-numbered view
  • max_bytes —— 当 terminal 命令产生的 stdout/stderr 合计字符数超过此值时,Kopi Agent 会保留前 40% 和后 60%,并在两者之间插入一条 [OUTPUT TRUNCATED] 通知。默认值 50000(在典型 tokenizer 中约 12-15K tokens)。
  • max_lines —— 单次 read_file 调用中 limit 参数的上限。超过此值的请求会被钳制,从而避免单次读取淹没 context window。默认值 2000。
  • max_line_length —— 当 read_file 输出带行号的视图时应用的每行上限。超过此长度的行会被截断为这么多字符,后面跟上 ... [truncated]。默认值 2000。

对于能够承受每次调用更多原始输出的大 context window 模型,请调高这些限制。对于 context 较小的模型,请调低它们以保持工具结果紧凑:

# Large context model (200K+)
tool_output:
max_bytes: 150000
max_lines: 5000

# Small local model (16K context)
tool_output:
max_bytes: 20000
max_lines: 500

全局工具集禁用​

要在一处屏蔽特定工具集,使其在 CLI 和所有 gateway 平台中都不启用,可将其名称列在 agent.disabled_toolsets 下:

agent:
disabled_toolsets:
- memory # hide memory tools + MEMORY_GUIDANCE injection
- web # no web_search / web_extract anywhere

这在按平台的工具配置(由 kopi tools 写入的 platform_toolsets)之后应用,因此列在此处的工具集总是会被移除 —— 即使某个平台已保存的配置中仍然列有它也是如此。当你想要一个统一的开关来"在所有地方关闭 X",而不是在 kopi tools UI 中编辑 15+ 行平台记录时,可使用此功能。

将列表留空,或省略该键,均不会产生任何效果。

Git Worktree 隔离​

为在同一仓库中并行运行多个 agent 启用隔离的 git worktree:

worktree: true    # Always create a worktree (same as kopi -w)
# worktree: false # Default — only when -w flag is passed

启用后,每个 CLI 会话都会在 .worktrees/ 下创建一个全新的 worktree,并带有自己的分支。Agent 可以编辑文件、提交、推送和创建 PR,而互不干扰。干净的 worktree 会在退出时被删除;有未提交更改的则会保留,以便手动恢复。

默认情况下,新的 worktree 分支基于新拉取的远程最新提交(当前分支的上游分支,否则为远程的默认分支),因此它从项目的最新状态开始,而不是从本地克隆中可能已过时的 HEAD 开始。这样 PR 的 diff 范围仅限于实际更改,而不会继承本地克隆落后的那些提交。设置 worktree_sync: false 可改为从本地 HEAD 分支 —— 这在离线时很有用,或者当你刻意希望以克隆的确切当前状态作为基准时也很有用。如果无法连接远程,它会自动回退到本地 HEAD。

worktree_sync: true    # Default — branch from the fetched remote tip
# worktree_sync: false # Branch from local HEAD (offline / pinned base)

你还可以通过仓库根目录中的 .worktreeinclude 列出要复制到 worktree 中的被 gitignore 忽略的文件:

# .worktreeinclude
.env
.venv/
node_modules/

上下文压缩​

Kopi Agent 会自动压缩较长的对话,使其保持在模型的上下文窗口范围内。压缩摘要器是一次独立的 LLM 调用 —— 你可以将其指向任意 provider 或端点。

所有压缩设置都位于 config.yaml 中(没有环境变量)。

完整参考​

compression:
enabled: true # Toggle compression on/off
threshold: 0.50 # Compress at this % of context limit
target_ratio: 0.20 # Fraction of threshold to preserve as recent tail
protect_last_n: 20 # Min recent messages to keep uncompressed
protect_first_n: 3 # Non-system head messages pinned across compactions (0 = pin nothing)
hygiene_hard_message_limit: 5000 # Gateway safety valve — see below

# The summarization model/provider is configured under auxiliary:
auxiliary:
compression:
model: "" # Empty = use main chat model. Override with e.g. "google/gemini-3-flash-preview" for cheaper/faster compression.
provider: "auto" # Provider: "auto", "openrouter", "nous", "codex", "main", etc.
base_url: null # Custom OpenAI-compatible endpoint (overrides provider)
旧版配置迁移

较早的配置中包含 compression.summary_model、compression.summary_provider 和 compression.summary_base_url,这些配置会在首次加载时自动迁移到 auxiliary.compression.*(config version 17)。无需手动操作。

hygiene_hard_message_limit 是仅适用于 gateway 的压缩前安全阀。它的存在是为了打破死循环:当 API 调用因会话过大而持续断开时,gateway 永远收不到 token 用量数据,基于 token 的阈值因此无法触发,转录内容持续增长,断开情况愈发严重。这个基于消息数量的下限仅根据消息数量触发(无论 API 是否失败,消息数量始终是已知的),以强制压缩并恢复会话。默认 5000 —— 远高于任何正常会话,包括使用大上下文(1M+)模型进行数千次短对话的会话,这些会话早在达到此阈值前就已通过 token 阈值完成压缩。对于特殊平台可将其调高,若想强制更激进的压缩则可调低。在运行中的 gateway 上编辑此值会在下一条消息时生效(见下文)。

protect_first_n 控制在每次压缩中固定的非系统头部消息数量。默认 3 —— 开头的用户/助手对话会在每次摘要器处理中保留下来,从而使原始目标始终可见。在长时间运行的滚动压缩会话中,如果开头的轮次已不再相关,可设置 protect_first_n: 0 使其不固定任何内容,只保留系统提示 + 摘要 + 尾部消息。无论此设置如何,系统提示本身始终会被保留。

压缩与上下文长度的 gateway 热重载

从近期版本开始,在运行中的 gateway 上编辑 model.context_length 或 config.yaml 中的任何 compression.* 键会在下一条消息时生效 —— 无需重启 gateway、无需 /reset、无需轮换会话。缓存的 agent 签名包含这些键,因此 gateway 在检测到变更时会透明地重建 agent。API key 以及工具/skill 配置仍需通过常规重载路径处理。

常见配置​

默认(自动检测)—— 无需配置:

compression:
enabled: true
threshold: 0.50

使用你的主 provider 和主模型。可按任务覆盖(例如 auxiliary.compression.provider: openrouter + model: google/gemini-2.5-flash),如果你希望压缩使用比主聊天模型更便宜的模型。

强制指定特定 provider(基于 OAuth 或 API key):

auxiliary:
compression:
provider: nous
model: gemini-3-flash

适用于任何 provider:nous、openrouter、codex、anthropic、main 等。

自定义端点(自托管、Ollama、zai、DeepSeek 等):

auxiliary:
compression:
model: glm-4.7
base_url: https://api.z.ai/api/coding/paas/v4

指向一个自定义的 OpenAI 兼容端点。使用 OPENAI_API_KEY 进行身份验证。

三个配置项如何协同工作​

auxiliary.compression.providerauxiliary.compression.base_url结果
auto(默认)未设置自动检测最佳可用 provider
nous / openrouter 等未设置强制使用该 provider,并使用其身份验证
任意已设置直接使用自定义端点(忽略 provider)
摘要模型的上下文长度要求

摘要模型的上下文窗口必须至少与主 agent 模型的一样大。压缩器会将对话的完整中间部分发送给摘要模型 —— 如果该模型的上下文窗口小于主模型的,摘要调用会因上下文长度错误而失败。此时,中间轮次会被丢弃且不生成摘要,从而静默丢失对话上下文。如果你覆盖了模型,请验证其上下文长度达到或超过主模型的。

上下文引擎​

上下文引擎控制在接近模型 token 上限时如何管理对话。内置的 compressor 引擎使用有损摘要(参见上下文压缩)。Plugin 引擎可以用替代策略替换它。

context:
engine: "compressor" # default — built-in lossy summarization

要使用 plugin 引擎(例如用于无损上下文管理的 LCM):

context:
engine: "lcm" # must match the plugin's name

Plugin 引擎永远不会自动激活 —— 你必须显式地将 context.engine 设置为 plugin 名称。可通过 kopi plugins → Provider Plugins → Context Engine 浏览并选择可用的引擎。

有关 memory plugin 的类似单选系统,请参阅 Memory Providers。

迭代预算​

当 agent 处理包含大量工具调用的复杂任务时,可能会耗尽其迭代预算(默认:90 个回合)。Kopi Agent 不会在任务中途注入压力警告 —— 早期版本会在预算用到 70%/90% 时警告模型,这会导致模型过早放弃复杂任务,该机制已于 2026 年 4 月移除。

相反,当预算真正耗尽时(90/90),Kopi Agent 会注入一条消息,要求模型收尾,并允许一次 宽限调用(grace call),以便它能给出最终响应。如果该宽限调用仍未产出文本,则会要求 agent 总结它已完成的工作。

agent:
max_turns: 90 # Max iterations per conversation turn (default: 90)
api_max_retries: 3 # Retries per provider before fallback engages (default: 3)

当迭代预算完全耗尽时,CLI 会向用户显示一条通知:⚠ Iteration budget reached (90/90) — response may be incomplete。

agent.api_max_retries 控制 Kopi Agent 在遇到临时错误(速率限制、连接中断、5xx)时重试 provider(服务提供商)API 调用的次数,在启用 fallback provider 切换之前。默认值是 3 —— 总共四次尝试。如果你配置了 fallback provider 并希望更快地进行故障转移,可以将其调低为 0,这样主 provider 上出现第一次临时错误时就会立即移交给 fallback,而不是针对不稳定的端点反复重试。

常设目标(/goal)​

当某个常设目标处于激活状态时,Kopi Agent 会判断每条助手响应是否满足该目标。如果不满足,它会将一条续写提示反馈到同一会话中,并持续工作,直到目标完成、回合预算耗尽,或用户暂停/清除该目标。回合预算才是真正的兜底机制 —— 判定失败时会按 放行(继续)处理,因此不稳定的判定器永远不会卡住进度。

goals:
max_turns: 20 # Max continuation turns before Kopi Agent auto-pauses the goal (default: 20)

max_turns 限制一个目标能驱动的续写回合数上限,超过后 Kopi Agent 会自动暂停该目标,并要求用户 /goal resume。它可以防止判定器误判(目标实际已完成但判定器说继续)以及在模糊或无法达成的目标上无限制地消耗模型额度。完整功能说明请参阅目标。

API 超时​

Kopi Agent 为流式传输设置了独立的超时层,并为非流式调用设置了停滞检测器。这些停滞检测器仅在你保持其隐式默认值不变时,才会针对本地 provider 自动调整。

超时项默认值本地 provider配置 / 环境变量
Socket 读取超时120s自动提升至 1800sKOPI_STREAM_READ_TIMEOUT
流停滞检测180s自动禁用KOPI_STREAM_STALE_TIMEOUT
非流停滞检测300s保持隐式时自动禁用providers.<id>.stale_timeout_seconds 或 KOPI_API_CALL_STALE_TIMEOUT
API 调用(非流式)1800s不变providers.<id>.request_timeout_seconds / timeout_seconds 或 KOPI_API_TIMEOUT

socket 读取超时 控制 httpx 等待来自 provider 的下一个数据块的时长。本地 LLM 在大型上下文上进行预填充时可能需要数分钟才会产出第一个 token,因此 Kopi Agent 在检测到本地端点时会将其提升至 30 分钟。如果你显式设置了 KOPI_STREAM_READ_TIMEOUT,则无论端点检测结果如何,始终使用该值。

流停滞检测 会终止那些只收到 SSE keep-alive 心跳而没有实际内容的连接。对于本地 provider,此功能会完全禁用,因为它们在预填充期间不会发送 keep-alive 心跳。

非流停滞检测 会终止那些长时间没有产生任何响应的非流式调用。默认情况下,Kopi Agent 会在本地端点上禁用此功能,以避免长时间预填充期间的误判。如果你显式设置了 providers.<id>.stale_timeout_seconds、providers.<id>.models.<model>.stale_timeout_seconds 或 KOPI_API_CALL_STALE_TIMEOUT,即使在本地端点上也会采用该显式值。

上下文压力警告​

与迭代预算压力不同,上下文压力跟踪的是对话距离 压缩阈值 有多接近 —— 达到该阈值时会触发上下文压缩来总结较早的消息。这有助于你和 agent 了解对话何时变得过长。

进度级别发生的情况
距阈值 ≥ 60%信息CLI 显示青色进度条;gateway 发送一条信息性通知
距阈值 ≥ 85%警告CLI 显示加粗的黄色进度条;gateway 警告即将进行压缩

在 CLI 中,上下文压力会以工具输出流中的进度条形式呈现:

  ◐ context ████████████░░░░░░░░ 62% to compaction  48k threshold (50%) · approaching compaction

在消息平台上,会发送一条纯文本通知:

◐ Context: ████████████░░░░░░░░ 62% to compaction (threshold: 50% of window).

如果自动压缩已禁用,该警告会告知你上下文可能会被截断。

上下文压力是自动的 —— 无需任何配置。它纯粹作为面向用户的通知触发,不会修改消息流,也不会向模型的上下文中注入任何内容。

凭据池策略​

当你为同一个 provider 拥有多个 API key 或 OAuth token 时,可以配置轮换策略:

credential_pool_strategies:
openrouter: round_robin # cycle through keys evenly
anthropic: least_used # always pick the least-used key

可选项:fill_first(默认)、round_robin、least_used、random。完整文档请参阅凭据池。

提示缓存​

当活跃的 provider(服务提供商)支持跨会话提示缓存时,Kopi Agent 会自动启用该功能——无需用户配置。

对于 native Anthropic、OpenRouter 和 KOPI Proxy 上的 Claude,Kopi Agent 会在系统提示词和 skill 块上附加 cache_control 断点,TTL 为 1 小时(ttl: "1h")。在新开启的一个小时内首次发送需按完整输入费率计费;此后同一小时内任何会话中的后续发送都以折扣后的缓存读取费率从缓存中获取。这意味着系统提示词、已加载的 skill 内容以及任何长上下文包含内容的前段部分,都能在 kopi 会话之间以及派生的子 agent 之间跨第一个小时复用。

Qwen Cloud(Alibaba DashScope)上游将缓存 TTL 上限设为 5 分钟,因此 Kopi Agent 在该处改用 5 分钟的断点 TTL。其他经由第三方的 Claude 路径(AWS Bedrock、Azure Foundry)则回退到 provider 自身的缓存默认设置。xAI Grok 使用单独的、绑定会话的 conversation-id 机制——参见 xAI 提示缓存。

没有任何开关可以禁用此功能——缓存始终开启,即使是单轮对话也能节省费用,因为仅系统提示词一项就占输入 token 数的可观比例。

唯一的显式配置项是 Kopi Agent 在 Anthropic 风格断点上请求的缓存 TTL 层级:

prompt_caching:
cache_ttl: "5m" # "5m" or "1h" (Anthropic-supported tiers); other values are ignored

cache_ttl 用于选择 Kopi Agent 通过 native Anthropic API、OpenRouter 和 KOPI Proxy 为 Claude 附加断点时所用的 TTL。仅 Anthropic 支持的两个层级("5m"、"1h")会被采纳——其他任何值都会被忽略。具有自身上限的 provider(例如上限为 5 分钟的 Qwen Cloud)仍会以允许的上游值为准进行收敛。

辅助模型​

Kopi Agent 使用"辅助"模型来处理旁路任务,例如图像分析、网页摘要、浏览器截图分析、会话标题生成和上下文压缩。默认情况下(auxiliary.*.provider: "auto"),Kopi Agent 会把每个辅助任务都路由到你的主聊天模型——也就是你在 kopi model 中选择的同一个 provider/model。开始使用时你无需进行任何配置,但请注意,在昂贵的推理模型(Opus、MiniMax M2.7 等)上,辅助任务会带来可观的成本。如果你希望无论主模型是什么,旁路任务都能又便宜又快,请显式设置 auxiliary.<task>.provider 和 auxiliary.<task>.model(例如,在 OpenRouter 上使用 Gemini Flash 来处理视觉和网页提取)。

为什么 "auto" 使用你的主模型

早期构建会把聚合器用户(OpenRouter、KOPI Proxy)分流到便宜的 provider 端默认模型。这很令人意外——付费购买聚合器订阅的用户会看到另一个模型处理他们的辅助流量。auto 现在对所有用户都使用主模型,而 config.yaml 中的按任务覆盖设置仍然优先生效(参见下文的完整辅助配置参考)。

交互式配置辅助模型​

无需手动编辑 YAML,只需运行 kopi model 并从菜单中选择 "Configure auxiliary models"。你会得到一个按任务选择的交互式选择器:

$ kopi model
→ Configure auxiliary models

[ ] vision currently: auto / main model
[ ] web_extract currently: auto / main model
[ ] title_generation currently: openrouter / google/gemini-3-flash-preview
[ ] tts_audio_tags currently: auto / main model
[ ] compression currently: auto / main model
[ ] approval currently: auto / main model
[ ] triage_specifier currently: auto / main model
[ ] kanban_decomposer currently: auto / main model
[ ] profile_describer currently: auto / main model

选择一个任务,选择一个 provider(OAuth 流程会打开浏览器;API-key provider 会进行提示),然后选择一个模型。更改会持久化保存到 config.yaml 中的 auxiliary.<task>.*。与主模型选择器使用的是同一套机制——无需学习额外语法。

视频教程​

通用配置模式​

Kopi Agent 中的每个模型槽位——辅助任务、压缩、回退——都使用相同的三个配置项:

配置项作用默认值
provider使用哪个 provider 进行鉴权和路由"auto"
model要请求哪个模型provider 的默认值
base_url自定义 OpenAI 兼容端点(覆盖 provider)未设置

当设置了 base_url 时,Kopi Agent 会忽略 provider,直接调用该端点(使用 api_key 或 OPENAI_API_KEY 进行鉴权)。当只设置了 provider 时,Kopi Agent 会使用该 provider 内置的鉴权方式和 base URL。

辅助任务可用的 provider:auto、main,以及 provider registry 中的任何 provider——openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、gemini、qwen-oauth、zai、kimi-coding、kimi-coding-cn、minimax、minimax-cn、minimax-oauth、deepseek、nvidia、xai、xai-oauth、ollama-cloud、alibaba、bedrock、huggingface、arcee、xiaomi、kilocode、opencode-zen、opencode-go、azure-foundry——或 custom_providers 列表中任意命名的自定义 provider(例如 provider: "beans")。

MiniMax OAuth

minimax-oauth 通过浏览器 OAuth 登录(无需 API key)。运行 kopi model 并选择 MiniMax (OAuth) 即可完成认证。辅助任务会自动使用 MiniMax-M2.7-highspeed。参见 MiniMax OAuth 指南。

xAI Grok OAuth

xai-oauth 为 SuperGrok 和 X Premium+ 订阅用户提供浏览器 OAuth 登录(无需 API key)。运行 kopi model 并选择 xAI Grok OAuth (SuperGrok / Premium+) 即可完成认证。同一个 OAuth token 会被所有直接面向 xAI 的功能复用(聊天、辅助任务、TTS、图像生成、视频生成、转录)。参见 xAI Grok OAuth 指南;如果 Kopi Agent 运行在远程主机上,请参见 OAuth over SSH / 远程主机。

"main" 仅用于辅助任务

"main" 这个 provider 选项的含义是"使用我的主 agent 所用的 provider"——它只在 auxiliary:、compression: 以及主回退条目(fallback_providers: 或旧版的 fallback_model:)内部有效。它不是顶层 model.provider 设置的有效值。如果你使用自定义的 OpenAI 兼容端点,请在你的 model: 部分中设置 provider: custom。所有主模型 provider 选项参见 AI Providers。

完整辅助配置参考​

auxiliary:
# Image analysis (vision_analyze tool + browser screenshots)
vision:
provider: "auto" # "auto", "openrouter", "nous", "codex", "main", etc.
model: "" # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
base_url: "" # Custom OpenAI-compatible endpoint (overrides provider)
api_key: "" # API key for base_url (falls back to OPENAI_API_KEY)
timeout: 120 # seconds — LLM API call timeout; vision payloads need generous timeout
download_timeout: 30 # seconds — image HTTP download; increase for slow connections
max_concurrency: 8 # max concurrent image encode/resize bursts across the process
# (default: host CPU core count, no ceiling) — bounds only the
# CPU-bound encode step so a video-frame fan-out can't saturate
# every core and starve the event loop; LLM calls stay fully
# concurrent. Minimum 1; values < 1 are ignored.

# Web page summarization + browser page text extraction
web_extract:
provider: "auto"
model: "" # e.g. "google/gemini-2.5-flash"
base_url: ""
api_key: ""
timeout: 360 # seconds (6min) — per-attempt LLM summarization

# Dangerous command approval classifier
approval:
provider: "auto"
model: ""
base_url: ""
api_key: ""
timeout: 30 # seconds

# Gemini 3.1 TTS hidden audio-tag insertion
tts_audio_tags:
provider: "auto"
model: "" # empty = main chat model
base_url: ""
api_key: ""
timeout: 30

# Context compression timeout (separate from compression.* config)
compression:
timeout: 120 # seconds — compression summarizes long conversations, needs more time
# fallback_chain: # Optional — providers to try on rate-limit / connectivity failure
# - provider: nous
# model: deepseek/deepseek-chat
# - provider: openrouter
# model: google/gemini-2.5-flash
# base_url: ""
# api_key: ""

# Auto-generated session titles. Empty language follows the conversation;
# set e.g. "English" or "Japanese" to pin titles to one language.
title_generation:
provider: "auto"
model: ""
base_url: ""
api_key: ""
timeout: 30
language: ""

# Skills hub — skill matching and search
skills_hub:
provider: "auto"
model: ""
base_url: ""
api_key: ""
timeout: 30

# MCP tool dispatch
mcp:
provider: "auto"
model: ""
base_url: ""
api_key: ""
timeout: 30

# Kanban triage specifier — `kopi kanban specify <id>` (or the
# dashboard's ✨ Specify button on Triage-column cards) uses this
# slot to expand a one-liner into a concrete spec and promote the
# task to `todo`. Cheap fast models work well here; spec expansion
# is short and doesn't need reasoning depth.
triage_specifier:
provider: "auto"
model: ""
base_url: ""
api_key: ""
timeout: 120
提示

每个辅助任务都有可配置的 timeout(以秒为单位)。默认值:vision 120 秒、web_extract 360 秒、approval 30 秒、compression 120 秒。如果辅助任务使用较慢的本地模型,请调大这些值。Vision 还有一个单独的 download_timeout(默认 30 秒),用于 HTTP 图像下载——网络较慢或使用自托管图像服务器时请调大该值。

信息

上下文压缩有自己的 compression: 块用于阈值设置,以及一个 auxiliary.compression: 块用于 model/provider 设置——参见上文的上下文压缩。主回退链使用顶层的 fallback_providers: 列表——参见 Fallback Providers。三者都遵循相同的 provider/model/base_url 模式。

辅助任务的按任务回退链​

每个辅助任务都可以选择性地定义一个 fallback_chain——一组 provider/model 条目的列表,当主辅助 provider 因限流、连接问题或支付限制而失败时,Kopi Agent 会依次尝试这些条目:

auxiliary:
compression:
provider: openrouter
model: openai/gpt-4o-mini
fallback_chain:
- provider: nous
model: deepseek/deepseek-chat
- provider: openrouter
model: google/gemini-2.5-flash

当主辅助 provider(openrouter / openai/gpt-4o-mini)返回限流、连接超时或需要付费的错误时,Kopi Agent 会按顺序遍历 fallback_chain。它会跳过 provider 与已失败 provider 相同的条目,并依次尝试每个剩余条目,直到某个条目成功或 回退链会被耗尽。如果所有回退都失败,Kopi Agent 最终会回退到主 agent 模型,作为最后的安全网。

每个条目都支持与任意辅助任务配置相同的三个配置项:

键描述
providerProvider(服务提供商)名称(nous、openrouter、anthropic、gemini、main 等)
model该 provider 的模型名称
base_url(可选)自定义的 OpenAI 兼容 endpoint

fallback_chain 可用于任何辅助任务 —— compression、vision、web_extract、approval、skills_hub、mcp 等。

辅助任务的 OpenRouter 路由与 Pareto Code​

当辅助任务解析到 OpenRouter(无论是显式指定,还是在主 agent 使用 OpenRouter 时通过 provider: "main" 解析),主 agent 的 provider_routing 和 openrouter.min_coding_score 设置不会传播 —— 这是有意为之的,每个辅助任务都是独立的。要为特定辅助任务设置 OpenRouter provider 偏好或使用 Pareto Code 路由器,请通过 extra_body 按任务进行设置:

auxiliary:
compression:
provider: openrouter
model: openrouter/pareto-code # use the Pareto Code router for this task
extra_body:
provider: # OpenRouter provider routing prefs
order: [anthropic, google] # try these providers in order
sort: throughput # or "price" | "latency"
# only: [anthropic] # restrict to a specific provider
# ignore: [deepinfra] # exclude specific providers
plugins: # OpenRouter Pareto Code router knob
- id: pareto-router
min_coding_score: 0.5 # 0.0–1.0; higher = stronger coders

其结构与 OpenRouter 在 chat completions 请求体中接受的内容一致。Kopi Agent 会原样转发整个 extra_body,因此 openrouter.ai/docs 中记录的任何其他 OpenRouter 请求体字段都同样适用。

更改视觉模型​

要在图像分析中使用 GPT-4o 而不是 Gemini Flash:

auxiliary:
vision:
model: "openai/gpt-4o"

或者通过环境变量(在 ~/.kopi/.env 中):

AUXILIARY_VISION_MODEL=openai/gpt-4o

Provider 选项​

这些选项适用于辅助任务配置(auxiliary:、compression:)以及主回退条目(fallback_providers: 或旧版 fallback_model:),不适用于你的主 model.provider 设置。

Provider描述要求
"auto"使用最佳可用项(默认)。视觉任务会依次尝试 OpenRouter → Nous → Codex。—
"openrouter"强制使用 OpenRouter —— 可路由到任意模型(Gemini、GPT-4o、Claude 等)OPENROUTER_API_KEY
"nous"强制使用 KOPI Proxykopi auth
"codex"强制使用 Codex OAuth(ChatGPT 账户)。支持视觉(gpt-5.3-codex)。kopi model → Codex
"minimax-oauth"强制使用 MiniMax OAuth(浏览器登录,无需 API key)。辅助任务使用 MiniMax-M2.7-highspeed。kopi model → MiniMax (OAuth)
"xai-oauth"强制使用 xAI Grok OAuth(面向 SuperGrok 或 X Premium+ 订阅者的浏览器登录,无需 API key)。同一个 OAuth token 覆盖 chat、TTS、图像、视频和转写。kopi model → xAI Grok OAuth (SuperGrok / Premium+)
"main"使用你当前激活的自定义/主 endpoint。它可能来自 OPENAI_BASE_URL + OPENAI_API_KEY,也可能来自通过 kopi model / config.yaml 保存的自定义 endpoint。适用于 OpenAI、本地模型或任何 OpenAI 兼容 API。仅限辅助任务 —— 对 model.provider 无效。自定义 endpoint 凭据 + base URL

当你希望辅助任务绕过默认路由器时,主 provider 目录中的直接 API key provider 在这里同样可用。gmi 在配置了 GMI_API_KEY 后即为有效:

auxiliary:
compression:
provider: "gmi"
model: "anthropic/claude-opus-4.6"

对于 GMI 辅助路由,请使用 GMI 的 /v1/models endpoint 返回的精确模型 ID。

常见配置​

使用直接自定义 endpoint(对于本地/自托管 API,比 provider: "main" 更清晰明了):

auxiliary:
vision:
base_url: "http://localhost:1234/v1"
api_key: "local-key"
model: "qwen2.5-vl"

base_url 优先于 provider,因此这是将辅助任务路由到特定 endpoint 的最明确方式。对于直接的 endpoint 覆盖,Kopi Agent 会使用已配置的 api_key,或回退到 OPENAI_API_KEY;不会为该自定义 endpoint 复用 OPENROUTER_API_KEY。

为视觉任务使用 OpenAI API key:

# In ~/.kopi/.env:
# OPENAI_BASE_URL=https://api.openai.com/v1
# OPENAI_API_KEY=sk-...

auxiliary:
vision:
provider: "main"
model: "gpt-4o" # or "gpt-4o-mini" for cheaper

为视觉任务使用 OpenRouter(可路由到任意模型):

auxiliary:
vision:
provider: "openrouter"
model: "openai/gpt-4o" # or "google/gemini-2.5-flash", etc.

使用 Codex OAuth(ChatGPT Pro/Plus 账户 —— 无需 API key):

auxiliary:
vision:
provider: "codex" # uses your ChatGPT OAuth token
# model defaults to gpt-5.3-codex (supports vision)

使用 MiniMax OAuth(浏览器登录,无需 API key):

model:
default: MiniMax-M2.7
provider: minimax-oauth
base_url: https://api.minimax.io/anthropic

运行 kopi model 并选择 MiniMax (OAuth) 进行登录并自动完成此设置。对于中国区域,base URL 将是 https://api.minimaxi.com/anthropic。完整操作步骤请参阅 MiniMax OAuth 指南。

使用本地/自托管模型:

auxiliary:
vision:
provider: "main" # uses your active custom endpoint
model: "my-local-model"

provider: "main" 使用 Kopi Agent 进行普通对话时所用的 provider —— 无论是命名的自定义 provider(例如 beans)、openrouter 这样的内置 provider,还是旧版 OPENAI_BASE_URL endpoint。

提示

如果你使用 Codex OAuth 作为主模型 provider,视觉功能会自动工作 —— 无需额外配置。Codex 已包含在视觉的自动检测链中。

注意

视觉功能需要多模态模型。 如果你设置了 provider: "main",请确保你的 endpoint 支持多模态/视觉 —— 否则图像分析将会失败。

环境变量(旧版)​

辅助模型也可以通过环境变量配置。不过,config.yaml 是首选方法 —— 它更易于管理,并支持所有选项,包括 base_url 和 api_key。

设置环境变量
视觉 providerAUXILIARY_VISION_PROVIDER
视觉模型AUXILIARY_VISION_MODEL
视觉 endpointAUXILIARY_VISION_BASE_URL
视觉 API keyAUXILIARY_VISION_API_KEY
网页提取 providerAUXILIARY_WEB_EXTRACT_PROVIDER
网页提取模型AUXILIARY_WEB_EXTRACT_MODEL
网页提取 endpointAUXILIARY_WEB_EXTRACT_BASE_URL
网页提取 API keyAUXILIARY_WEB_EXTRACT_API_KEY

压缩和回退模型设置仅限在 config.yaml 中配置。

提示

运行 kopi config 可查看当前的辅助模型设置。覆盖项只有在与默认值不同时才会显示。

推理强度​

控制模型在响应前进行多少"思考":

agent:
reasoning_effort: "" # empty = medium (default). Options: none, minimal, low, medium, high, xhigh (max)

未设置时(默认),推理强度为"medium" —— 这是一个均衡的级别,适用于大多数任务。设置某个值会覆盖该默认值 —— 更高的推理强度在复杂任务上能带来更好的结果,但代价是消耗更多 token 并增加延迟。

在 OpenRouter 上使用自适应思考模型(Claude 4.6+、Fable/Mythos 级别)

这些模型采用自适应思考,不接受常规的 reasoning.effort 字段 —— OpenRouter 会忽略它们的该字段。Kopi Agent 会透明地将你的 reasoning_effort 路由到 OpenRouter 的 verbosity 参数(该参数映射到 Anthropic 的 output_config.effort),因此同一个 low/medium/high/xhigh 旋钮仍可继续使用 —— 无需额外配置。none(或不设置)会让模型 保持其自身的自适应默认值。(max 在传输层会被接受,但它不是 可选择的 reasoning_effort 值;xhigh 才是可配置的上限。) 原生 Anthropic provider 已直接控制强度,不受影响。

你也可以在运行时使用 /reasoning 命令更改推理强度:

/reasoning           # Show current effort level and display state
/reasoning high # Set reasoning effort to high
/reasoning none # Disable reasoning
/reasoning show # Show model thinking above each response
/reasoning hide # Hide model thinking

工具调用强制执行​

有些模型偶尔会以文本形式描述其打算执行的操作,而不是发起工具调用(例如"我会运行测试……",而不是实际调用终端)。工具调用强制执行会注入系统提示词引导,促使模型转而真正调用工具。

agent:
tool_use_enforcement: "auto" # "auto" | true | false | ["model-substring", ...]
值行为
"auto"(默认)对匹配以下模式的模型启用:gpt、codex、gemini、gemma、grok。对其他所有模型(Claude、DeepSeek、Qwen 等)禁用。
true始终启用,无论模型如何。如果你发现当前模型只是描述操作而非执行操作,这会很有用。
false始终禁用,无论模型如何。
["gpt", "codex", "qwen", "llama"]仅当模型名称包含所列子串之一(不区分大小写)时启用。

注入了什么​

启用后,系统提示词中可能会添加三层引导:

  1. 通用工具调用强制执行(所有匹配的模型) —— 指示模型立即发起工具调用,而不是描述意图;持续工作直到任务完成;绝不以承诺将来会执行某个操作来结束回合。

  2. OpenAI 执行纪律(仅 GPT 和 Codex 模型) —— 针对 GPT 特有失败模式的额外引导:在拿到部分结果后就放弃工作、跳过必要的前置查询、不使用工具而是产生幻觉、以及未经验证就宣布"完成"。

  3. Google 操作指引(仅 Gemini 和 Gemma 模型) —— 简洁性、绝对路径、并行工具调用,以及"先验证再编辑"的模式。

这些内容对用户是透明的,只会影响系统提示词。已经可靠使用工具的模型(如 Claude)不需要这类引导,这也是 "auto" 将它们排除在外的原因。

何时开启​

如果你使用的模型不在默认自动列表中,并且发现它频繁描述它将会做什么而不是实际去做,请设置 tool_use_enforcement: true,或将该模型的子串添加到列表中:

agent:
tool_use_enforcement: ["gpt", "codex", "gemini", "grok", "my-custom-model"]

工具循环防护​

Kopi Agent 会检测 agent 是否陷入无效的工具调用循环 —— 同一个工具调用反复失败、同一个工具一遍遍失败,或者某个幂等调用返回相同结果而没有任何进展。默认情况下,它会在工具结果中注入一条警告,让模型自行纠正;它不会强制停止,因为正在关注 CLI/TUI 的人可以介入。

对于无人值守的网关 / 服务器部署,请启用强制停止,使卡住的 agent 被熔断,而不是白白消耗迭代预算:

tool_loop_guardrails:
warnings_enabled: true # inject warnings into tool results (default: true)
hard_stop_enabled: false # also BLOCK the call past the hard-stop threshold (default: false)
warn_after:
exact_failure: 2 # identical failing call repeated N times
same_tool_failure: 3 # same tool failing N times (different args)
idempotent_no_progress: 2 # same result, no progress, N times
hard_stop_after:
exact_failure: 5
same_tool_failure: 8
idempotent_no_progress: 5

hard_stop_enabled 默认为 false,因为交互式会话有人参与其中。在无人值守的部署(网关、cron、看板 worker)中,请将其设为 true,这样重复失败会被阻断,而不只是发出警告。另请参阅 Docker / 无人值守部署。

TTS 配置​

tts:
provider: "edge" # "edge" | "elevenlabs" | "openai" | "minimax" | "mistral" | "gemini" | "xai" | "neutts"
speed: 1.0 # Global speed multiplier (fallback for all providers)
edge:
voice: "en-US-AriaNeural" # 322 voices, 74 languages
speed: 1.0 # Speed multiplier (converted to rate percentage, e.g. 1.5 → +50%)
elevenlabs:
voice_id: "pNInz6obpgDQGcFmaJgB"
model_id: "eleven_multilingual_v2"
openai:
model: "gpt-4o-mini-tts"
voice: "alloy" # alloy, echo, fable, onyx, nova, shimmer
speed: 1.0 # Speed multiplier (clamped to 0.25–4.0 by the API)
base_url: "https://api.openai.com/v1" # Override for OpenAI-compatible TTS endpoints
minimax:
speed: 1.0 # Speech speed multiplier
# base_url: "" # Optional: override for OpenAI-compatible TTS endpoints
mistral:
model: "voxtral-mini-tts-2603"
voice_id: "c69964a6-ab8b-4f8a-9465-ec0925096ec8" # Paul - Neutral (default)
gemini:
model: "gemini-2.5-flash-preview-tts" # or gemini-3.1-flash-tts-preview
voice: "Kore" # 30 prebuilt voices: Zephyr, Puck, Kore, Enceladus, etc.
audio_tags: false # Hidden Gemini 3.1 TTS audio-tag insertion
persona_prompt_file: "" # Optional Markdown/text file with Gemini voice direction
xai:
voice_id: "eve" # xAI TTS voice
language: "en" # ISO 639-1
sample_rate: 24000
bit_rate: 128000 # MP3 bitrate
# base_url: "https://api.x.ai/v1"
neutts:
ref_audio: ''
ref_text: ''
model: neuphonic/neutts-air-q4-gguf
device: cpu

这同时控制 text_to_speech 工具和语音模式下的口头回复(在 CLI 或消息网关中为 /voice tts)。

速度回退层级: provider 特定速度(例如 tts.edge.speed)→ 全局 tts.speed → 1.0 默认值。设置全局 tts.speed 可让所有 provider 使用统一速度,或者按 provider 进行覆盖以实现精细控制。

显示设置​

display:
tool_progress: all # off | new | all | verbose
tool_progress_command: false # Enable /verbose slash command in messaging gateway
platforms: {} # Per-platform display overrides (see below)
tool_progress_overrides: {} # DEPRECATED — use display.platforms instead
interim_assistant_messages: true # Gateway: send natural mid-turn assistant updates as separate messages
skin: default # Built-in or custom CLI skin (see user-guide/features/skins)
personality: "kawaii" # Legacy cosmetic field still surfaced in some summaries
compact: false # Compact output mode (less whitespace)
resume_display: full # full (show previous messages on resume) | minimal (one-liner only)
bell_on_complete: false # Play terminal bell when agent finishes (great for long tasks)
show_reasoning: false # Show model reasoning/thinking above each response (toggle with /reasoning show|hide)
streaming: false # Stream tokens to terminal as they arrive (real-time output)
show_cost: false # Show estimated $ cost in the CLI status bar
timestamps: false # When true, prefixes user and assistant labels with [HH:MM] timestamps in the CLI / TUI transcript
tool_preview_length: 0 # Max chars for tool call previews (0 = no limit, show full paths/commands)
runtime_footer: # Gateway: append a runtime-context footer to final replies
enabled: false
fields: ["model", "context_pct", "cwd"]
file_mutation_verifier: true # Append an advisory footer when write_file/patch calls failed this turn
credits_notices: true # Nous credits status-bar notices (usage bands, grant-spent, depleted). false = silence them; /usage still works
language: en # UI language for static messages (approval prompts, some gateway replies). en | zh | zh-hant | ja | de | es | fr | tr | uk | af | ko | it | ga | pt | ru | hu

文件修改校验器​

当 display.file_mutation_verifier 为 true(默认值)时,如果本轮对话中 write_file 或 patch 调用失败,且之后没有对同一路径的成功写入操作使其失效,Kopi Agent 会在助手的最终回复末尾附加一行提示信息。这样可以捕获"一批并行补丁中有一半静默失败,模型却总结为成功"这类过度声明的问题,而无需你在每次编辑后手动运行 git status。

示例尾注:

⚠️ File-mutation verifier: 3 file(s) were NOT modified this turn despite any wording above that may suggest otherwise. Run `git status` or `read_file` to confirm.
• concepts/automatic-organization.md — [patch] Could not find match for old_string
• concepts/lora.md — [patch] Could not find match for old_string
• concepts/rag-pipeline.md — [patch] Could not find match for old_string

将 file_mutation_verifier: false(或 KOPI_FILE_MUTATION_VERIFIER=0)设置为指定值即可隐藏该尾注。校验器只会在对话结束时仍存在真实失败的情况下触发 —— 如果模型在同一次对话内重试失败的补丁并成功,就不会针对该文件触发校验器。

静态消息的界面语言​

display.language 设置用于翻译一小组面向用户的静态消息 —— 包括 CLI 审批提示、少量 gateway 斜杠命令回复(例如重启排空通知、"审批已过期"、"目标已清除")。它不会翻译 agent 的回复、日志行、工具输出、错误堆栈或斜杠命令描述 —— 这些内容仍保持英文。如果你希望 agent 本身以其他语言回复,直接在提示词或系统消息中告诉它即可。

支持的取值:en(默认)、zh(简体中文)、zh-hant(繁体中文)、ja(日语)、de(德语)、es(西班牙语)、fr(法语)、tr(土耳其语)、uk(乌克兰语)、af(南非荷兰语)、ko(韩语)、it(意大利语)、ga(爱尔兰语)、pt(葡萄牙语)、ru(俄语)、hu(匈牙利语)。未知取值会回退为英文。

你也可以通过 KOPI_LANGUAGE 环境变量按会话设置此项,该变量会覆盖 config 中的取值。

display:
language: zh # CLI approval prompts appear in Chinese
模式你会看到什么
off静默 —— 只显示最终回复
new仅在工具发生变化时显示工具指示器
all显示每次工具调用并附带简短预览(默认)
verbose显示完整的参数、结果和调试日志

在 CLI 中,使用 /verbose 循环切换这些模式。要在消息平台(Telegram、Discord、Slack 等)中使用 /verbose,请在上面的 display 部分设置 tool_progress_command: true。此后该命令会切换模式并保存到 config。

工具进度显示需要一个能够安全显示进度更新的 gateway adapter。不支持消息编辑的平台(包括 Signal)会隐藏工具进度气泡,即使 /verbose 保存了非 off 的模式。

运行时元数据尾注(仅限 gateway)​

启用 display.runtime_footer.enabled: true 后,Kopi Agent 会在每个 gateway 回合的最后一条消息中附加一个小的运行时上下文尾注。当前尾注可以显示模型、上下文窗口百分比和当前工作目录。默认关闭;如果你的团队希望每条回复都包含这些溯源信息,可以按 gateway 单独开启。

display:
runtime_footer:
enabled: true
fields: ["model", "context_pct", "cwd"] # supported fields: model, context_pct, cwd

/footer 斜杠命令可以在任意会话中随时切换此设置。

附加到 Telegram/Discord/Slack 回复的示例尾注:

— claude-opus-4.7 · 12 tool calls · 2m 14s · $0.042

只有回合的最后一条消息会附加尾注;中间的更新内容保持干净。

按平台的进度显示覆盖设置​

不同平台对详细程度的需求各不相同。使用 display.platforms 设置按平台的模式:

display:
tool_progress: all # global default
platforms:
signal:
tool_progress: 'off' # Signal cannot currently display tool-progress bubbles
telegram:
tool_progress: verbose # detailed progress on Telegram
slack:
tool_progress: 'off' # quiet in shared Slack workspace

没有覆盖设置的平台会回退到全局的 tool_progress 取值。有效的平台键:telegram、discord、slack、signal、whatsapp、matrix、mattermost、email、sms、homeassistant、dingtalk、feishu、wecom、weixin、bluebubbles、qqbot。旧版的 display.tool_progress_overrides 键仍会加载以保持向后兼容,但已弃用,并会在首次加载时迁移至 display.platforms。

Signal 被列为有效平台键,是因为该设置可以按平台保存,但当前的 Signal adapter 无法编辑已发送的消息,也不会渲染工具进度气泡。请将 Signal 的 tool_progress 保持为 off;如果你需要实时查看每次工具调用,请使用 CLI 或支持消息编辑的消息平台。

interim_assistant_messages 仅限 gateway。启用后,Kopi Agent 会将回合中途完成的助手更新作为单独的聊天消息发送。此项独立于 tool_progress,且不需要 gateway 流式传输。

隐私​

privacy:
redact_pii: false # Strip PII from LLM context (gateway only)

当 redact_pii 为 true 时,gateway 会在受支持的平台上将系统提示词中的个人身份信息脱敏后再发送给 LLM:

字段处理方式
电话号码(WhatsApp/Signal 上的用户 ID)哈希为 user_<12-char-sha256>
用户 ID哈希为 user_<12-char-sha256>
聊天 ID数字部分哈希处理,保留平台前缀(telegram:<hash>)
主频道 ID数字部分哈希处理
用户名 / 账号名不受影响(用户自选、公开可见)

平台支持: 脱敏适用于 WhatsApp、Signal 和 Telegram。Discord 和 Slack 不在范围内,因为它们的提及系统(<@user_id>)需要在 LLM 上下文中包含真实的 ID。

哈希是确定性的 —— 同一个用户始终映射到同一个哈希,因此模型仍然可以在群聊中区分不同用户。路由和消息投递在内部使用原始值。

语音转文字(STT)​

stt:
enabled: true # Auto-transcribe inbound voice messages (default: true)
echo_transcripts: true # Post raw transcripts back to the chat as 🎙️ "..." (default: true)
provider: "local" # "local" | "groq" | "openai" | "mistral"
local:
model: "base" # tiny, base, small, medium, large-v3
openai:
model: "whisper-1" # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe
# model: "whisper-1" # Legacy fallback key still respected

当 gateway 需要为 agent 转录语音消息、但不能将原始转录文本回发到聊天中时(例如面向客户的 WhatsApp 机器人),请设置 stt.echo_transcripts: false。

各 provider(服务提供商)的行为:

  • local 使用在你机器上运行的 faster-whisper。请使用 pip install faster-whisper 单独安装。
  • groq 使用 Groq 的 Whisper 兼容端点,并读取 GROQ_API_KEY。
  • openai 使用 OpenAI 语音 API,并读取 VOICE_TOOLS_OPENAI_KEY。

如果请求的 provider 不可用,Kopi Agent 会按以下顺序自动回退:local → groq → openai。

Groq 和 OpenAI 的模型覆盖通过环境变量驱动:

STT_GROQ_MODEL=whisper-large-v3-turbo
STT_OPENAI_MODEL=whisper-1
GROQ_BASE_URL=https://api.groq.com/openai/v1
STT_OPENAI_BASE_URL=https://api.openai.com/v1

语音模式(CLI)​

voice:
record_key: "ctrl+b" # Push-to-talk key inside the CLI
max_recording_seconds: 120 # Hard stop for long recordings
auto_tts: false # Enable spoken replies automatically when /voice on
beep_enabled: true # Play record start/stop beeps in CLI voice mode
silence_threshold: 200 # RMS threshold for speech detection
silence_duration: 3.0 # Seconds of silence before auto-stop

在 CLI 中使用 /voice on 启用麦克风模式,record_key 开始/停止录音,/voice tts 切换语音回复。有关完整的端到端设置和特定平台的行为,请参阅语音模式。

流式传输​

在 token 到达时将其流式传输到终端或消息平台,而不是等待完整响应。

CLI 流式传输​

display:
streaming: true # Stream tokens to terminal in real-time
show_reasoning: true # Also stream reasoning/thinking tokens (optional)

启用后,响应会在流式传输框中逐个 token 显示。工具调用仍会被静默捕获。如果 provider(服务提供商)不支持流式传输,会自动回退到普通显示方式。

Gateway 流式传输(Telegram、Discord、Slack)​

streaming:
enabled: true # Enable progressive message editing
transport: edit # "edit" (progressive message editing) or "off"
edit_interval: 0.3 # Seconds between message edits
buffer_threshold: 40 # Characters before forcing an edit flush
cursor: " ▉" # Cursor shown during streaming
fresh_final_after_seconds: 0 # Opt in to fresh final (Telegram) when preview is this old

启用后,机器人会在收到第一个 token 时发送消息,随后随着更多 token 到达逐步编辑该消息。不支持消息编辑的平台(Signal、Email、Home Assistant)会在首次尝试时被自动检测——该会话的流式传输会被优雅地禁用,而不会刷屏。

如果需要在不进行逐 token 渐进编辑的情况下,在对话过程中单独发送自然的助手更新,请设置 display.interim_assistant_messages: true。

溢出处理: 如果流式传输的文本超出平台的消息长度限制(约 4096 个字符),当前消息会被最终确定,并自动开始一条新消息。

全新最终消息(Telegram): Telegram 的 editMessageText 会保留原始消息时间戳,因此一条长时间运行的流式回复即使在完成后也会保留第一个 token 的时间戳。设置 fresh_final_after_seconds > 0 可选择将旧的预览消息作为全新的最终消息发送,并尽力删除预览消息。默认值为 0,它始终就地最终确定流式回复,避免在会同时显示两种操作的客户端上出现短暂的重复消息/删除序列。

各平台的流式传输默认值

主开关 streaming.enabled 默认为 false——在你打开之前不会有任何内容被流式传输。启用后,流式传输按各平台分别决定:Telegram 默认为 display.platforms.telegram.streaming: true(流式传输),Discord 默认为 display.platforms.discord.streaming: false(不流式传输)。因此启用流式传输后,Telegram 开箱即用地进行流式传输,而 Discord 仍保持整条消息回复,直到你更改它的开关。你可以从仪表板的Channels开关或直接在 ~/.kopi/config.yaml 中调整这些各平台开关。

群聊会话隔离​

限制在 CLI、TUI/仪表板和消息网关之间可以同时活跃打开的聊天会话数量:

max_concurrent_sessions: null  # null/0 = unlimited; positive integer = active session cap

当达到上限时,Kopi Agent 会为新会话返回一条直接的限制消息。 现有的活跃会话保持其正常行为。

规范键是顶层的 max_concurrent_sessions。Kopi Agent 也接受 gateway.max_concurrent_sessions 作为回退,但当两者同时设置时, 顶层键优先。

该上限通过本地运行时租约文件强制执行,且为尽力而为:如果注册表无法读取或加锁,Kopi Agent 会失败开放(fail open),以免用户被卡住。 它适用于单个主机/配置文件运行时,而不是跨多台机器挂载的共享 $KOPI_HOME。

控制共享聊天是每个房间保留一个对话,还是每个参与者一个对话:

group_sessions_per_user: true  # true = per-user isolation in groups/channels, false = one shared session per chat
  • true 是默认且推荐的设置。在 Discord 频道、Telegram 群组、Slack 频道以及类似的共享上下文中,当平台提供用户 ID 时,每个发送者都会获得自己的会话。
  • false 回退到旧的共享房间行为。如果你明确希望 Kopi Agent 将某个频道视为一个协作式对话,这会很有用,但这也意味着用户会共享上下文、token 成本和中断状态。
  • 私信不受影响。Kopi Agent 仍会像往常一样按聊天/私信 ID 为私信建立键。
  • 无论哪种方式,话题(thread)都与其父频道保持隔离;使用 true 时,每个参与者在话题内也会获得自己的会话。

有关行为详情和示例,请参阅会话和 Discord 指南。

未授权私信行为​

控制当未知用户发送私信时 Kopi Agent 的行为:

unauthorized_dm_behavior: pair

whatsapp:
unauthorized_dm_behavior: ignore
  • pair 是聊天式私信平台的默认值。Kopi Agent 会拒绝访问,但在私信中回复一次性配对码。
  • ignore 静默丢弃未授权的私信。
  • 除非设置了 platforms.email.unauthorized_dm_behavior: pair,否则 Email 默认为 ignore,因为收件箱中可能包含不相关的未读邮件。
  • 各平台部分会覆盖全局默认值,因此你可以广泛保持配对启用,同时让某个平台更安静。

快捷命令​

定义自定义命令,这些命令可以运行 shell 命令而不调用 LLM,或者将一个斜杠命令别名到另一个斜杠命令。Exec 快捷命令是零 token 的,在消息平台(Telegram、Discord 等)中非常适合快速服务器检查或实用脚本。

quick_commands:
status:
type: exec
command: systemctl status kopi-ai-agent
disk:
type: exec
command: df -h /
update:
type: exec
command: cd ~/.kopi/kopi-ai-agent && git pull && pip install -e .
gpu:
type: exec
command: nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total --format=csv,noheader
restart:
type: alias
target: /gateway restart

用法:在 CLI 或任何消息平台中输入 /status、/disk、/update、/gpu 或 /restart。exec 命令在主机上本地运行并直接返回输出——不调用 LLM,不消耗 token。alias 命令会改写为配置的斜杠命令目标。

  • 30 秒超时 — 长时间运行的命令会被终止并显示错误消息
  • 优先级 — 快捷命令会在 skill 命令之前检查,因此你可以覆盖 skill 名称
  • 自动补全 — 快捷命令在派发时解析,不会显示在内置斜杠命令自动补全表中
  • 类型 — 支持的类型为 exec 和 alias;其他类型会显示错误
  • 随处可用 — CLI、Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant

仅含字符串的提示快捷方式不是有效的快捷命令。对于可复用的提示工作流,请创建一个 skill 或别名到现有的斜杠命令。

人类延迟​

在消息平台中模拟类人的响应节奏:

human_delay:
mode: "off" # off | natural | custom
min_ms: 800 # Minimum delay (custom mode)
max_ms: 2500 # Maximum delay (custom mode)

代码执行​

配置 execute_code 工具:

code_execution:
mode: project # project (default) | strict
timeout: 300 # Max execution time in seconds
max_tool_calls: 50 # Max tool calls within code execution

mode 控制脚本的工作目录和 Python 解释器:

  • project(默认)——脚本在会话的工作目录中运行,使用当前激活的 virtualenv/conda 环境的 python。项目依赖(pandas、torch、项目包)和相对路径(.env、./data.csv)都能自然解析,与 terminal() 看到的一致。
  • strict——脚本在临时暂存目录中运行,使用 sys.executable(Kopi Agent 自带的 python)。可复现性最高,但项目依赖和相对路径无法解析。

环境变量清理(剥离 *_API_KEY、*_TOKEN、*_SECRET、*_PASSWORD、*_CREDENTIAL、*_PASSWD、*_AUTH)和工具白名单在两种模式下完全相同——切换模式不会改变安全态势。

网络搜索后端​

web_search 和 web_extract 工具支持五种后端 provider。可在 config.yaml 中配置后端,或通过 kopi tools 配置:

web:
backend: firecrawl # firecrawl | searxng | parallel | tavily | exa

# Or use per-capability keys to mix providers (e.g. free search + paid extract):
search_backend: "searxng"
extract_backend: "firecrawl"
后端环境变量搜索提取
Firecrawl(默认)FIRECRAWL_API_KEY✔✔
SearXNGSEARXNG_URL✔—
ParallelPARALLEL_API_KEY✔✔
TavilyTAVILY_API_KEY✔✔
ExaEXA_API_KEY✔✔

后端选择: 如果未设置 web.backend,则根据可用的 API key 自动检测后端。如果仅设置了 SEARXNG_URL,则使用 SearXNG。如果仅设置了 EXA_API_KEY,则使用 Exa。如果仅设置了 TAVILY_API_KEY,则使用 Tavily。如果仅设置了 PARALLEL_API_KEY,则使用 Parallel。否则默认使用 Firecrawl。

SearXNG 是一个免费、自托管、注重隐私的元搜索引擎,可查询 70 多个搜索引擎。无需 API key——只需将 SEARXNG_URL 设置为你的实例(例如 http://localhost:8080)。SearXNG 仅支持搜索;web_extract 需要单独的提取 provider(请设置 web.extract_backend)。Docker 设置说明请参阅网络搜索设置指南。

自托管 Firecrawl: 将 FIRECRAWL_API_URL 设置为指向你自己的实例。当设置了自定义 URL 时,API key 变为可选(在服务器上设置 `USE_DB_AUTHENTICATION=*** 可禁用认证)。

Parallel 搜索模式: 设置 PARALLEL_SEARCH_MODE 来控制搜索行为——fast、one-shot 或 agentic(默认:agentic)。

Exa: 在 ~/.kopi/.env 中设置 EXA_API_KEY。支持 category 过滤(company、research paper、news、people、personal site、pdf)以及域名/日期过滤。

浏览器​

配置浏览器自动化行为:

browser:
inactivity_timeout: 120 # Seconds before auto-closing idle sessions
command_timeout: 30 # Timeout in seconds for browser commands (screenshot, navigate, etc.)
record_sessions: false # Auto-record browser sessions as WebM videos to ~/.kopi/browser_recordings/
# Optional CDP override — when set, Kopi Agent attaches directly to your own
# Chromium-family browser (via /browser connect) rather than starting a headless browser.
cdp_url: ""
# Dialog supervisor — controls how native JS dialogs (alert / confirm / prompt)
# are handled when a CDP backend is attached (Browserbase, local Chromium-family
# browser via /browser connect). Ignored on Camofox and default local agent-browser mode.
dialog_policy: must_respond # must_respond | auto_dismiss | auto_accept
dialog_timeout_s: 300 # Safety auto-dismiss under must_respond (seconds)
camofox:
managed_persistence: false # When true, Camofox sessions persist cookies/logins across restarts
user_id: "" # Optional externally managed Camofox userId
session_key: "" # Optional session key sent when Kopi Agent creates a tab
adopt_existing_tab: false # Reuse an existing tab for this identity before creating one

对话框策略:

  • must_respond(默认)——捕获对话框,在 browser_snapshot.pending_dialogs 中呈现,并等待 agent 调用 browser_dialog(action=...)。在 dialog_timeout_s 秒内没有响应后,对话框会被自动关闭,以防止页面的 JS 线程永久阻塞。
  • auto_dismiss——捕获后立即关闭。agent 仍可在事后通过 browser_snapshot.recent_dialogs 中带有 closed_by="auto_policy" 的记录查看该对话框。
  • auto_accept——捕获后立即接受。适用于带有强制性 beforeunload 提示的页面。

完整的对话框工作流程请参阅浏览器功能页面。

浏览器工具集支持多种 provider。关于 Browserbase、Browser Use 和本地 Chromium 系 CDP 设置的详情,请参阅浏览器功能页面。

时区​

使用 IANA 时区字符串覆盖服务器本地时区。影响日志中的时间戳、cron 调度以及系统提示中的时间注入。

timezone: "America/New_York"   # IANA timezone (default: "" = server-local time)

支持的值:任意 IANA 时区标识符(例如 America/New_York、Europe/London、Asia/Kolkata、UTC)。留空或省略则使用服务器本地时间。

Discord​

为消息网关配置 Discord 特定行为:

discord:
require_mention: true # Require @mention to respond in server channels
free_response_channels: "" # Comma-separated channel IDs where bot responds without @mention
auto_thread: true # Auto-create threads on @mention in channels
  • require_mention——当为 true(默认)时,机器人在服务器频道中仅在通过 @BotName 提及时才响应。私信始终无需提及即可响应。
  • free_response_channels——以逗号分隔的频道 ID 列表,机器人会在这些频道中响应每条消息,无需提及。
  • auto_thread——当为 true(默认)时,频道中的提及会自动为该对话创建一个 thread,使频道保持整洁(类似 Slack 的线程功能)。

安全​

执行前的安全扫描和密钥脱敏:

security:
redact_secrets: true # Redact API key patterns in tool output and logs (on by default)
tirith_enabled: true # Enable Tirith security scanning for terminal commands
tirith_path: "tirith" # Path to tirith binary (default: "tirith" in $PATH)
tirith_timeout: 5 # Seconds to wait for tirith scan before timing out
tirith_fail_open: true # Allow command execution if tirith is unavailable
website_blocklist: # See Website Blocklist section below
enabled: false
domains: []
shared_files: []
  • redact_secrets——当为 true 时,在工具输出进入对话上下文和日志之前,自动检测并脱敏其中类似 API key、token 和密码的模式。默认开启。仅在调试或脱敏器开发需要原始的类凭据字符串时,才显式设置为 false。
  • tirith_enabled——当为 true 时,终端命令在执行前会由 Tirith 扫描,以检测潜在的危险操作。
  • tirith_path——tirith 二进制文件的路径。如果 tirith 安装在非标准位置,请设置此项。
  • tirith_timeout——等待 tirith 扫描的最长秒数。如果扫描超时,命令将继续执行。
  • tirith_fail_open——当为 true(默认)时,如果 tirith 不可用或执行失败,命令仍被允许执行。设置为 false 可在 tirith 无法验证命令时阻止执行。

网站屏蔽列表​

阻止 agent 的网络和浏览器工具访问特定域名:

security:
website_blocklist:
enabled: false # Enable URL blocking (default: false)
domains: # List of blocked domain patterns
- "*.internal.company.com"
- "admin.example.com"
- "*.local"
shared_files: # Load additional rules from external files
- "/etc/kopi/blocked-sites.txt"

启用后,任何匹配被屏蔽域名模式的 URL 都会在网络或浏览器工具执行前被拒绝。这适用于 web_search、web_extract、browser_navigate 以及任何访问 URL 的工具。

域名规则支持:

  • 精确域名:admin.example.com
  • 通配符子域名:*.internal.company.com(屏蔽所有子域名)
  • 顶级域名通配符:*.local

共享文件每行包含一条域名规则(空行和 # 注释会被忽略)。缺失或不可读的文件会记录警告,但不会禁用其他网络工具。

策略缓存 30 秒,因此配置更改无需重启即可快速生效。

智能审批​

控制 Kopi Agent 如何处理潜在危险命令:

approvals:
mode: manual # manual | smart | off
模式行为
manual(默认)在执行任何被标记的命令前提示用户确认。在 CLI 中,会显示交互式审批对话框。在消息渠道中,会将待处理的审批请求加入队列。
smart使用辅助 LLM 来评估被标记的命令是否确实危险。低风险命令会自动批准,并在会话级别内保持有效。确实存在风险的命令会被上报给用户。
off跳过所有审批检查。等同于 KOPI_YOLO_MODE=true。请谨慎使用。

智能模式在减少审批疲劳方面尤其有用 —— 它让 agent 能够在安全操作上更自主地工作,同时仍然能拦截真正具有破坏性的命令。

注意

设置 approvals.mode: off 会禁用终端命令的所有安全检查。请仅在可信的沙箱环境中使用。

拒绝规则​

approvals.deny 是一组 glob 模式列表,会无条件屏蔽匹配的终端命令 —— 即使在 --yolo、/yolo 或 mode: off 下也不例外。它是内置硬性屏蔽列表的用户可编辑对应项:

approvals:
deny:
- "git push --force*"
- "*curl*|*sh*"

这些模式是不区分大小写的 fnmatch glob,并且必须在 YAML 中加引号(以裸写 * 开头会导致解析错误)。详情请参阅安全 —— 用户自定义拒绝规则。

检查点​

在执行破坏性文件操作前自动创建文件系统快照。详情请参阅检查点与回滚。

checkpoints:
enabled: false # Enable automatic checkpoints (also: kopi chat --checkpoints). Default: false (opt-in).
max_snapshots: 20 # Max checkpoints to keep per directory (default: 20)

委托​

为 delegate 工具配置 subagent(子代理)行为:

delegation:
# model: "google/gemini-3-flash-preview" # Override model (empty = inherit parent)
# provider: "openrouter" # Override provider (empty = inherit parent)
# base_url: "http://localhost:1234/v1" # Direct OpenAI-compatible endpoint (takes precedence over provider)
# api_key: "local-key" # API key for base_url (falls back to OPENAI_API_KEY)
# api_mode: "" # Wire protocol for base_url: "chat_completions", "codex_responses", or "anthropic_messages". Empty = auto-detect from URL (e.g. /anthropic suffix → anthropic_messages). Set explicitly for non-standard endpoints the heuristic can't detect.
max_concurrent_children: 3 # Parallel children per batch (floor 1, no ceiling). Also via DELEGATION_MAX_CONCURRENT_CHILDREN env var.
max_spawn_depth: 1 # Delegation tree depth cap (1-3, clamped). 1 = flat (default): parent spawns leaves that cannot delegate. 2 = orchestrator children can spawn leaf grandchildren. 3 = three levels.
orchestrator_enabled: true # Global kill switch. When false, role="orchestrator" is ignored and every child is forced to leaf regardless of max_spawn_depth.

**Subagent 的 provider:model 覆盖:**默认情况下,subagent 会继承父 agent 的 provider 和 model。设置 delegation.provider 和 delegation.model 可将 subagent 路由到不同的 provider:model 组合 —— 例如,为范围明确的子任务使用便宜/快速的模型,而主 agent 则运行昂贵的推理模型。

**直接端点覆盖:**如果你想要直接的自定义端点路径,可设置 delegation.base_url、delegation.api_key 和 delegation.model。这会将 subagent 直接发送到该 OpenAI 兼容端点,并且优先于 delegation.provider。如果省略 delegation.api_key,Kopi Agent 会回退到仅使用 OPENAI_API_KEY。

**传输协议(api_mode):**Kopi Agent 会根据 delegation.base_url 自动检测传输协议(例如以 /anthropic 结尾的路径 → anthropic_messages;Codex / 原生 Anthropic / Kimi-coding 主机名会保留其现有检测结果)。对于启发式方法无法归类的端点 —— 例如 Azure AI Foundry、MiniMax、智谱 GLM,或前置 Anthropic 形态后端的 LiteLLM 代理 —— 请将 delegation.api_mode 显式设置为 chat_completions、codex_responses 或 anthropic_messages 之一。将其留空(默认值)则保持自动检测。

委托 provider 使用与 CLI/网关启动时相同的凭据解析机制。支持所有已配置的 provider:openrouter、nous、copilot、zai、kimi-coding、minimax、minimax-cn。设置 provider 后,系统会自动解析正确的 base URL、API key 和 API mode —— 无需手动配置凭据。

**优先级:**config 中的 delegation.base_url → config 中的 delegation.provider → 父 provider(继承)。config 中的 delegation.model → 父 model(继承)。只设置 model 而不设置 provider 时,只会更改模型名称,同时保留父级的凭据(适用于在同一 provider 内切换模型,例如 OpenRouter)。

宽度与深度:max_concurrent_children 限制每批并行运行的 subagent 数量(默认 3,下限为 1,无上限)。也可通过 DELEGATION_MAX_CONCURRENT_CHILDREN 环境变量设置。当模型提交的 tasks 数组长度超过上限时,delegate_task 会返回一个说明该限制的工具错误,而不是静默截断。max_spawn_depth 控制委托树的深度(限制在 1-3 之间)。在默认的 1 下,委托是扁平的:子级不能生成孙级,并且传入 role="orchestrator" 会静默降级为 leaf。提高到 2 后,编排型子级可以生成叶子孙级;3 则支持三层树。agent 通过 role="orchestrator" 在每次调用时选择启用编排;orchestrator_enabled: false 则无论如何都会强制每个子级回到叶子模式。成本按乘法增长 —— 在 max_spawn_depth: 3 与 max_concurrent_children: 3 下,树最多可达 3×3×3 = 27 个并发叶子 agent。用法示例请参阅Subagent 委托 → 深度限制与嵌套编排。

澄清​

配置澄清提示行为:

clarify:
timeout: 120 # Seconds to wait for user clarification response

上下文文件(SOUL.md、AGENTS.md)​

Kopi Agent 使用两种不同的上下文作用域:

文件用途作用域
SOUL.md主要 agent 身份 — 定义 agent 是谁(system prompt 中的槽位 #1)~/.kopi/SOUL.md 或 $KOPI_HOME/SOUL.md
.kopi.md / HERMES.md项目特定指令(优先级最高)向上遍历至 git 根目录
AGENTS.md项目特定指令、编码规范递归目录遍历
CLAUDE.mdClaude Code 上下文文件(同样会被检测)仅工作目录
.cursorrulesCursor IDE 规则(同样会被检测)仅工作目录
.cursor/rules/*.mdcCursor 规则文件(同样会被检测)仅工作目录
  • SOUL.md 是 agent 的主要身份。它占据 system prompt 中的槽位 #1,会完全替换内置的默认身份。编辑它可以彻底自定义 agent 是谁。
  • 如果 SOUL.md 缺失、为空或无法加载,Kopi Agent 会回退到内置默认身份。
  • 项目上下文文件使用优先级系统 — 只会加载一种类型(首次匹配生效):.kopi.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始终独立加载。
  • AGENTS.md 是分层的:如果子目录中也有 AGENTS.md,它们会被合并。
  • 如果默认的 SOUL.md 尚不存在,Kopi Agent 会自动创建一个。
  • 所有加载的上下文文件都被限制在 context_file_max_chars 个字符内(默认 20,000),并进行智能截断。

另请参阅:

工作目录​

上下文默认值
CLI (kopi)运行命令时所在的当前目录
消息网关来自 ~/.kopi/config.yaml 的 terminal.cwd;如果未设置,则为 home 目录 ~
Docker / Singularity / Modal / SSH容器或远程机器中的用户 home 目录

覆盖工作目录:

# In ~/.kopi/config.yaml:
terminal:
cwd: /home/myuser/projects

MESSAGING_CWD 以及 ~/.kopi/.env 中的直接 TERMINAL_CWD 条目属于遗留兼容性回退项。新的配置应使用 terminal.cwd。

网络​

出站 HTTP 的连通性变通方案:

network:
force_ipv4: false # Force IPv4 for outbound connections (default: false)

force_ipv4 — 在 IPv6 损坏或不可达的服务器上,Python 会优先解析 AAAA 记录,并可能在回退到 IPv4 之前挂起整个 TCP 超时时长。将其设置为 true 可完全跳过 IPv6,直接通过 IPv4 连接。

引导流程​

首次接触的引导提示和结构化的 profile 构建提议:

onboarding:
profile_build: "ask" # "ask" (default) | "off"
seen: {} # internal latch — leave empty
  • profile_build — 控制在有史以来第一条网关消息中提供的 profile 构建路径。"ask"(默认)会提供构建用户 profile 的选项;该选项是选择加入并受同意控制的 — agent 会在任何查询前先询问,并且绝不会静默读取已连接的账户。"off" 仅显示简要介绍。该提议最多只触发一次。
  • seen — 内部状态。Kopi Agent 会在此记录每个已显示的提示,确保其不再触发;profile 构建提议在显示一次后也会记录在此。请勿手动编辑 — 如果想重新看到所有提示,请清除整个 onboarding 部分。

仪表盘​

Web 仪表盘的配置 — 视觉主题、公开 URL 以及认证 provider(服务提供商)。认证 provider(OAuth、基础密码、drain)在 web-dashboard 页面中有详细文档;这里是 config.yaml 的形式。

dashboard:
theme: "default" # "default" | "midnight" | "ember" | "mono" | "cyberpunk" | "rose"
show_token_analytics: false # Re-enable the (local-estimate-only) token/cost analytics surfaces
public_url: "" # Full public authority for OAuth redirect_uri (env: KOPI_DASHBOARD_PUBLIC_URL)
oauth: # KOPI Proxy OAuth gate (engaged with --host and not --insecure)
client_id: "" # agent:{instance_id} — KOPI Proxy provisions this
portal_url: "" # blank → plugin default (production KOPI Proxy)
basic_auth: # Self-hosted username/password gate (dashboard_auth/basic plugin)
username: "" # blank → plugin no-op
password_hash: "" # scrypt$... (preferred — no plaintext at rest)
password: "" # plaintext fallback (hashed in-memory at load)
secret: "" # token-signing key; blank → random per-process
session_ttl_seconds: 0 # 0 → plugin default (12h)
drain_auth: # Drain-control service-credential gate (dashboard_auth/drain plugin)
scope: "drain" # capability label on the verified principal
min_secret_chars: 43 # entropy bar (url-safe-b64 chars; 43 ≈ 256 bits)
  • theme — 仪表盘视觉主题。
  • show_token_analytics — 默认关闭。分析页面以及 token/成本数字是本地的下限估算(它们不包括辅助调用、重试、回退和缓存写入),因此可能远低于 provider 的账单金额。仅在你理解这些数字并非账单时才设置 true。
  • public_url — 设置后,这就是构建 OAuth redirect_uri 所依据的完整权威地址(scheme + host + 可选路径前缀)。如果部署位于不能可靠转发 X-Forwarded-* 头的反向代理之后,请设置此项。留空则使用代理头重建。
  • oauth / basic_auth / drain_auth — 由内置 dashboard-auth 插件读取的认证 provider 配置。drain secret 本身不是在这里设置的;它通过 KOPI_DASHBOARD_DRAIN_SECRET 环境变量来配置。完整的认证设置请参阅 Web 仪表盘。