CLI 命令参考
本页介绍你从 shell 中运行的终端命令。
关于聊天内的斜杠命令,请参阅斜杠命令参考。
全局入口
kopi [global-options] <command> [subcommand/options]
全局选项
| 选项 | 说明 |
|---|---|
--version, -V | 显示版本号并退出。 |
--profile <name>, -p <name> | 选择本次调用要使用的 Kopi Agent 配置文件(profile)。会覆盖由 kopi profile use 设置的粘性默认值。 |
--resume <session>, -r <session> | 通过 ID 或标题恢复之前的会话。 |
--continue [name], -c [name] | 恢复最近一次会话,或恢复标题匹配的最近一次会话。 |
--worktree, -w | 在隔离的 git worktree 中启动,用于并行 agent 工作流。 |
--yolo | 跳过危险命令的批准提示。 |
--pass-session-id | 在 agent 的系统提示中包含会话 ID。 |
--ignore-user-config | 忽略 ~/.kopi/config.yaml,回退到内置默认值。.env 中的凭据仍会被加载。 |
--ignore-rules | 跳过 AGENTS.md、SOUL.md、.cursorrules、记忆以及预加载 skill 的自动注入。 |
--tui | 启动 TUI 而非经典 CLI。等同于 KOPI_TUI=1。优先级始终高于 display.interface。 |
--cli | 强制使用经典的 prompt_toolkit REPL。用于在单次调用中覆盖 display.interface: tui。 |
--dev | 配合 --tui:通过 tsx 直接运行 TypeScript 源码,而不使用预构建的 bundle(适用于 TUI 贡献者)。 |
顶级命令
| 命令 | 用途 |
|---|---|
kopi chat | 与 agent 进行交互式或单次对话。 |
kopi model | 交互式选择默认 provider 和 model。 |
kopi moa | 配置可从模型选择器中选用的命名 Mixture of Agents 预设。 |
kopi fallback | 管理当主模型出错时尝试的回退 provider。 |
kopi gateway | 运行或管理消息网关服务。 |
kopi proxy | 本地 OpenAI 兼容代理,可附加 OAuth provider 凭据。参见订阅代理。 |
kopi lsp | 管理 Language Server Protocol 集成(用于 write_file/patch 的语义诊断)。 |
kopi setup | 针对全部或部分配置的交互式设置向导。 |
kopi whatsapp | 配置并配对 WhatsApp 桥接。 |
kopi whatsapp-cloud | 配置官方 Meta WhatsApp Business Cloud API 适配器(需要商业账户和公开 webhook)。与 kopi whatsapp(Baileys 个人账户桥接)不同。 |
kopi slack | Slack 辅助工具(目前:生成包含所有命令作为原生 slash 命令的应用 manifest)。 |
kopi auth | 管理凭据 —— 添加、列出、移除、重置、状态、登出。处理 Codex/Nous/Anthropic 的 OAuth 流程。 |
kopi login / logout | 已弃用 —— 请改用 kopi auth。 |
kopi send | 向已配置的消息平台(Telegram、Discord、Slack、Signal、SMS 等)发送单次消息。适用于 shell 脚本、cron 任务、CI 钩子和监控守护进程 —— 无 agent 循环,无 LLM。 |
kopi secrets | 管理外部密钥来源(目前为 Bitwarden Secrets Manager),用于在进程启动时拉取 API key,而非从 ~/.kopi/.env 获取。 |
kopi migrate | 诊断并(可选地)重写 config.yaml,以替换对已下线模型或已弃用设置的引用(例如 migrate xai)。 |
kopi status | 显示 agent、认证和平台状态。 |
kopi cron | 检查并推进 cron 调度器。 |
kopi kanban | 多 profile 协作看板(任务、链接、调度器)。 |
kopi project | 管理命名的多文件夹工作区(项目)。锚定桌面会话分组,并且在绑定到看板时,为任务提供确定性的 worktree + 分支约定。状态按 profile 隔离。 |
kopi webhook | 管理用于事件驱动激活的动态 webhook 订阅。 |
kopi hooks | 检查、批准或移除在 config.yaml 中声明的 shell 脚本钩子。 |
kopi doctor | 诊断 config 和依赖问题。 |
kopi security audit | 按需供应链审计(OSV.dev),覆盖 venv、plugin 依赖和锁定版本的 MCP server。 |
kopi dump | 可直接复制粘贴的设置摘要,用于支持/调试。 |
kopi prompt-size | 显示系统提示词 + 工具 schema 的字节构成明细(skills 索引、记忆、profile)。离线运行。 |
kopi debug | 调试工具 —— 上传日志和系统信息以获取支持。 |
kopi backup | 将 Kopi Agent 主目录备份为 zip 文件。 |
kopi checkpoints | 检查 / 清理 / 清除 ~/.kopi/checkpoints/(/rollback 使用的影子存储)。不带参数运行可查看状态概览。 |
kopi import | 从 zip 文件恢复 Kopi Agent 备份。 |
kopi logs | 查看、实时跟踪和筛选 agent/gateway/error 日志文件。 |
kopi config | 显示、编辑、迁移和查询配置文件。 |
kopi pairing | 批准或撤销消息配对码。 |
kopi skills | 浏览、安装、发布、审计和配置 skill。 |
kopi bundles | 将多个 skill 归组到单个 /<name> slash 命令下。参见 Skill Bundles。 |
kopi curator | 后台 skill 维护 —— 状态、运行、暂停、固定。参见 Curator。 |
kopi memory | 配置外部记忆 provider。插件专属的子命令(例如 kopi honcho)会在其 provider 激活时自动注册。 |
kopi acp | 将 Kopi Agent 作为 ACP server 运行,用于编辑器集成。 |
kopi mcp | 管理 MCP server 配置,并将 Kopi Agent 作为 MCP server 运行。 |
kopi plugins | 管理 KOPI AI AGENT plugin(安装、启用、禁用、移除)。 |
kopi portal | KOPI Proxy 状态、订阅链接和 Tool Gateway 路由。参见 Tool Gateway。 |
kopi tools | 按平台配置启用的工具。 |
kopi computer-use | 安装或检查 cua-driver 后端(macOS Computer Use)。 |
kopi pets | 浏览、安装并选择在 CLI、TUI 和桌面应用中展示的 petdex 动态宠物。子命令:list、install、select、show、off、scale、remove、doctor。 |
kopi sessions | 浏览、导出、清理、重命名和删除会话。 |
kopi insights | 显示 token/成本/活动分析。 |
kopi claw | OpenClaw 迁移辅助工具。 |
kopi dashboard | 打开 Web 仪表板以管理配置、API key 和会话。 |
kopi desktop(别名 gui) | 构建并启动原生 Electron 桌面应用。 |
kopi profile | 管理 profile —— 多个相互隔离的 Kopi Agent 实例。 |
kopi completion | 打印 shell 补全脚本(bash/zsh/fish)。 |
kopi version | 显示版本信息。 |
kopi update | 拉取最新代码并重新安装依赖。--check 可预览而不安装;--backup 会创建拉取前的 KOPI_HOME 快照。 |
kopi uninstall | 从系统中移除 Kopi Agent。 |
kopi chat
kopi chat [options]
常用选项:
| 选项 | 说明 |
|---|---|
-q, --query "..." | 一次性、非交互式提示。 |
-m, --model <model> | 为本次运行覆盖所用模型。 |
-t, --toolsets <csv> | 启用一组以逗号分隔的 toolsets。 |
--provider <provider> | 强制指定 provider:auto, openrouter, nous, openai-codex, copilot-acp, copilot, anthropic, gemini, huggingface, novita(别名 novita-ai, novitaai),openai-api, zai, kimi-coding, kimi-coding-cn, minimax, minimax-cn, minimax-oauth, kilocode, xiaomi, arcee, gmi, alibaba, alibaba-coding-plan(别名 alibaba_coding),deepseek, nvidia, ollama-cloud, xai(别名 grok),xai-oauth(别名 grok-oauth),qwen-oauth, bedrock, opencode-zen, opencode-go, azure-foundry, lmstudio, stepfun, tencent-tokenhub(别名 tencent, tokenhub)。 |
-s, --skills <name> | 为会话预加载一个或多个 skill(可重复使用或用逗号分隔)。 |
-v, --verbose | 详细输出。 |
-Q, --quiet | 程序化模式:不显示横幅/加载动画/工具预览。 |
--image <path> | 为单次查询附加一张本地图片。 |
--resume <session> / --continue [name] | 直接从 chat 恢复会话。 |
--worktree | 为本次运行创建一个隔离的 git worktree。 |
--checkpoints | 在执行破坏性文件更改前启用文件系统检查点。 |
--yolo | 跳过批准提示。 |
--pass-session-id | 将会话 ID 传入系统提示。 |
--ignore-user-config | 忽略 ~/.kopi/config.yaml 并使用内置默认值。.env 中的凭据仍会被加载。适用于隔离的 CI 运行、可复现的错误报告以及第三方集成。 |
--ignore-rules | 跳过自动注入 AGENTS.md、SOUL.md、.cursorrules、持久化 memory 以及预加载的 skill。与 --ignore-user-config 结合使用可实现完全隔离的运行。 |
--safe-mode | 故障排查模式:禁用所有自定义项 —— 用户配置、规则/memory 注入、plugin、shell 钩子和 MCP 服务器(隐含 --ignore-user-config 和 --ignore-rules)。用于判断问题源自你的设置还是 Kopi Agent 本身。 |
--source <tag> | 用于筛选的会话来源标签(默认:cli)。对不应出现在用户会话列表中的第三方集成,请使用 tool。 |
--max-turns <N> | 每个对话轮次的最大工具调用迭代次数(默认:90,或配置中的 agent.max_turns)。 |
示例:
kopi-agent
kopi chat -q "Summarize the latest PRs"
kopi chat --provider openrouter --model anthropic/claude-sonnet-4.6
kopi chat --toolsets web,terminal,skills
kopi chat --quiet -q "Return only JSON"
kopi chat --worktree -q "Review this repo and open a PR"
kopi chat --ignore-user-config --ignore-rules -q "Repro without my personal setup"
kopi chat --safe-mode -q "Is this bug mine or Kopi Agent'?"
kopi -z <prompt> —— 脚本化的一次性调用
对于程序化调用方(shell 脚本、CI、cron、通过管道传入提示的父进程),kopi -z 是最纯粹的一次性入口:传入单条提示,输出最终回复文本,stdout 或 stderr 上没有任何其他内容。 没有横幅、没有加载动画、没有工具预览、没有 Session: 行 —— 只有 agent 的最终回复,以纯文本形式输出。
kopi -z "What's the capital of France?"
# → Paris.
# Parent scripts can cleanly capture the response:
answer=$(kopi -z "summarize this" < /path/to/file.txt)
单次运行覆盖项(不会修改 ~/.kopi/config.yaml):
| 标志 | 对应的环境变量 | 用途 |
|---|---|---|
-m / --model <model> | KOPI_INFERENCE_MODEL | 为本次运行覆盖所用模型 |
--provider <provider> | (无) | 为本次运行覆盖所用 provider |
kopi -z "…" --provider openrouter --model openai/gpt-5.5
# or:
KOPI_INFERENCE_MODEL=anthropic/claude-sonnet-4.6 kopi -z "…"
相同的 agent、相同的工具、相同的 skill —— 只是去掉了所有交互式/装饰性输出层。如果你还需要在记录中包含工具输出,请改用 kopi chat -q;-z 明确用于"我只想要最终答案"的场景。
kopi model
交互式的 provider + 模型选择器。这是添加新 provider、配置 API key 以及运行 OAuth 流程的命令。 请从终端运行它 —— 而不是在活跃的 Kopi Agent 聊天会话内部运行。
kopi model
当你想要执行以下操作时使用它:
- 添加新的 provider(OpenRouter、Anthropic、Copilot、DeepSeek、自定义等)
- 登录基于 OAuth 的 provider(Anthropic、Copilot、Codex、KOPI Proxy)
- 输入或更新 API key
- 从特定于 provider 的模型列表中进行选择
- 配置自定义/自托管端点
- 将新的默认值保存到 config
kopi model(从终端运行,在任何 Kopi Agent 会话之外)是完整的 provider 设置向导。它可以添加新的 provider、运行 OAuth 流程、提示输入 API key,并配置端点。
/model(在活跃的 Kopi Agent 聊天会话中输入)只能在你已设置好的 provider 和模型之间切换。它无法添加新的 provider、运行 OAuth 或提示输入 API key。
如果你需要添加新的 provider: 请先退出你的 Kopi Agent 会话(Ctrl+C 或 /quit),然后在终端提示符下运行 kopi model。
/model 斜杠命令(会话中)
无需离开会话即可在已配置的模型之间切换:
/model # Show current model and available options
/model claude-sonnet-4 # Switch model (auto-detects provider)
/model zai:glm-5 # Switch provider and model
/model custom:qwen-2.5 # Use model on your custom endpoint
/model custom # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5 # Use a named custom provider
/model openrouter:anthropic/claude-sonnet-4 # Switch back to cloud
默认情况下,/model 的更改仅应用于当前会话。添加 --global 可将更改持久化到 config.yaml:
/model claude-sonnet-4 --global # Switch and save as new default
如果你只配置了 OpenRouter,/model 将只显示 OpenRouter 的模型。要添加另一个 provider(Anthropic、DeepSeek、Copilot 等),请退出会话并在终端运行 kopi model。
Provider 和 base URL 的更改会自动持久化到 config.yaml。当从自定义端点切换走时,会清除过期的 base URL,以防止其泄漏到其他 provider。
kopi gateway
kopi gateway <subcommand>
子命令:
| 子命令 | 描述 |
|---|---|
run | 在前台运行 gateway。推荐用于 WSL、Docker 和 Termux。 |
start | 启动已安装的 systemd/launchd 后台服务。 |
stop | 停止该服务(或前台进程)。 |
restart | 重启该服务。 |
status | 显示服务状态。 |
list | 列出所有 profile 及每个 profile 的 gateway 当前是否正在运行(如有则显示 PID)。当你并行运行多个 profile 并希望一目了然地总览时非常方便。 |
install | 安装为 systemd(Linux)或 launchd(macOS)后台服务。 |
uninstall | 移除已安装的服务。 |
setup | 交互式消息平台设置。 |
migrate-legacy | 移除重命名前安装遗留的旧版 kopi-agent.service 单元。profile 单元(kopi-gateway-<profile>.service)以及无关服务绝不会被改动。Flags:--dry-run、-y/--yes。 |
enroll | 实验性功能:将此 gateway 注册到 relay connector,并为 connector 支持的平台保存 relay 凭据。 |
选项:
| 选项 | 描述 |
|---|---|
--all | 在 start / restart / stop 上:对每个 profile 的 gateway 执行操作,而不仅仅是当前活动的 KOPI_HOME。当你并行运行多个 profile 并希望在 kopi update 后全部重启时非常有用。 |
--no-supervise | 在 run 上:在 s6-overlay Docker 镜像中,退出自动监管并使用 s6 之前的前台语义 —— gateway 作为容器的主进程运行,不会自动重启。在 s6 镜像之外无操作。等同于设置 KOPI_GATEWAY_NO_SUPERVISE=1。 |
kopi gateway enroll 接受 --token、--connector-url、--gateway-id 和 --wake-url。它会用注册 token 与 connector 交换,并将生成的 GATEWAY_RELAY_ID、GATEWAY_RELAY_SECRET、GATEWAY_RELAY_DELIVERY_KEY、可选的 GATEWAY_RELAY_URL 以及(在指定 --wake-url 时)GATEWAY_RELAY_WAKE_URL 的值写入当前活动 profile 的 .env。
请使用 kopi gateway run 而不是 kopi gateway start —— WSL 的 systemd 支持不可靠。可以用 tmux 包裹以保持持久运行:tmux new -s kopi 'kopi gateway run'。详情请参阅 WSL FAQ。
kopi lsp
kopi lsp <subcommand>
管理 Language Server Protocol 集成。LSP 在后台运行真实的语言服务器(pyright、gopls、rust-analyzer 等),并将其诊断信息提供给 write_file 和 patch 所使用的写入后检查。以 git 工作区检测为前提 —— 只有当 cwd 或被编辑的文件位于某个 git worktree 内时,LSP 才会运行。
子命令:
| 子命令 | 描述 |
|---|---|
status | 显示服务状态、已配置的服务器、安装状态。 |
list | 打印受支持服务器的 registry。传入 --installed-only 可跳过缺失的项。 |
install <id> | 提前安装某个服务器的二进制文件。 |
install-all | 安装所有已知自动安装方案的服务器。 |
restart | 拆除正在运行的客户端,以便下次编辑时重新启动。 |
which <id> | 打印某个服务器解析出的二进制文件路径。 |
完整指南、支持的语言以及配置项,请参阅 LSP — Semantic Diagnostics。
kopi setup
kopi setup [model|tts|terminal|gateway|tools|agent] [--non-interactive] [--reset] [--quick] [--reconfigure] [--portal]
最简单的路径: kopi setup --portal —— 一步完成 OAuth 登录 KOPI Proxy 并选择加入 Tool Gateway。
首次运行: 启动首次设置向导。
回归用户(已完成配置): 直接进入完整的重新配置向导 —— 每个提示都会把你的当前值作为默认值显示,按 Enter 保留或输入新值。没有菜单。
也可以直接进入某一节,而不运行完整向导:
| 节 | 描述 |
|---|---|
model | Provider 和模型设置。 |
terminal | 终端后端和沙箱设置。 |
gateway | 消息平台设置。 |
tools | 按平台启用/禁用工具。 |
agent | Agent 行为设置。 |
选项:
| 选项 | 描述 |
|---|---|
--quick | 在回归用户运行时:仅提示缺失或未设置的项。跳过你已配置的项。 |
--non-interactive | 使用默认值/环境变量值,不进行提示。 |
--reset | 在设置前将配置重置为默认值。 |
--reconfigure | 向后兼容别名 —— 在已有安装上直接运行 kopi setup 现在默认执行此操作。 |
--portal | 一步完成 KOPI Proxy 设置:通过 OAuth 登录、将 Nous 设为推理 provider,并选择加入 Tool Gateway。跳过向导的其余部分。 |
kopi portal
kopi portal [status|open|tools]
检查 KOPI Proxy 认证、Tool Gateway 路由,并访问订阅页面。不带子命令的调用会运行 status。
| 子命令 | 描述 |
|---|---|
status(默认) | KOPI Proxy 认证状态 + 按工具汇总的 Tool Gateway 路由。不指定子命令时同样会显示。 |
open | 在你的默认浏览器中打开 portal.kopiaiagent.com/manage-subscription。 |
tools | 列出每个 Tool Gateway 合作伙伴(Firecrawl、FAL、OpenAI TTS、Browser Use、Modal),以及哪些通过 Nous 路由。 |
关于 gateway 本身的配置,请参阅 Tool Gateway。关于一步完成的设置路径,请参阅上文的 kopi setup --portal。
kopi whatsapp
kopi whatsapp
运行 WhatsApp 配对/设置流程,包括模式选择和二维码配对。
kopi slack
kopi slack manifest # print manifest to stdout
kopi slack manifest --write # write to ~/.kopi/slack-manifest.json
kopi slack manifest --slashes-only # just the features.slash_commands array
生成一个 Slack app manifest,将 COMMAND_REGISTRY(/btw、/stop、/model 等)中的每个 gateway 命令注册为一等的 Slack 斜杠命令——与 Discord 和 Telegram 保持一致。将输出粘贴到 https://api.slack.com/apps → your app →
Features → App Manifest → Edit 中的 Slack app 配置里,然后点击 Save。如果 scopes 或斜杠命令发生变更,Slack 会提示重新安装。
| Flag | Default | Purpose |
|---|---|---|
--write [PATH] | stdout | 写入文件而非 stdout。单独的 --write 会写入 $KOPI_HOME/slack-manifest.json。 |
--name NAME | Kopi Agent | Slack 中的机器人显示名称。 |
--description DESC | default blurb | 在 Slack app 目录中显示的机器人描述。 |
--slashes-only | off | 仅输出 features.slash_commands,用于合并到手动维护的 manifest 中。 |
在 kopi update 之后重新运行 kopi slack manifest --write,即可获取所有新增命令。
kopi send
kopi send --to <target> "message text"
kopi send --to <target> --file <path>
echo "message" | kopi send --to <target>
kopi send --list [platform]
向已配置的消息平台发送一次性消息,无需启动 agent 或 gateway 循环。复用 gateway 中已配置的凭据(~/.kopi/.env + ~/.kopi/config.yaml),因此运维脚本、cron 任务、CI 钩子和监控守护进程都可以发布状态更新,而无需重新实现每个平台的 REST client。
对于使用 bot-token 的平台(Telegram、Discord、Slack、Signal、SMS、WhatsApp-CloudAPI),无需运行中的 gateway —— kopi send 直接与平台的 REST endpoint 通信。需要持久化 adapter 的插件平台仍然需要一个运行中的 gateway。
| Option | Description |
|---|---|
-t, --to <TARGET> | 投递目标。格式:platform(使用 home channel)、platform:chat_id、platform:chat_id:thread_id 或 platform:#channel-name。示例:telegram、telegram:-1001234567890、discord:#ops、slack:C0123ABCD、signal:+15551234567。 |
-f, --file <PATH> | 从 PATH 读取消息正文(仅限文本文件——日志、报告、markdown)。传递 - 以强制从 stdin 读取。要发送图片或其他二进制文件,请使用 MEDIA:<path>(见下文)。 |
-s, --subject <LINE> | 在消息正文前添加主题/标题行。 |
-l, --list [platform] | 列出所有平台上已配置的目标(或仅列出给定平台的目标)。 |
-q, --quiet | 成功时抑制 stdout 输出——在脚本中很有用(仅依赖退出码)。 |
--json | 输出原始 JSON 结果,而非人类可读的输出。 |
如果既未提供位置参数 message,也未提供 --file,则当 stdin 不是 TTY 时,kopi send 会从 stdin 读取。退出码:成功为 0,投递/后端失败为 1,用法错误为 2。
发送图片和其他媒体
--file 仅适用于文本正文。要将图片、文档、视频或音频文件作为原生平台附件投递,请在消息文本中使用 MEDIA:<local_path> 指令引用它:
kopi send --to telegram "MEDIA:/tmp/screenshot.png"
kopi send --to telegram "Build chart for today MEDIA:/tmp/chart.png" # with caption
kopi send --to discord:#ops "MEDIA:/tmp/report.pdf"
默认情况下,图片文件作为照片发送(Telegram 等平台会重新压缩这些图片)。在消息中添加 [[as_document]] 可改为以未压缩的文件附件形式投递:
kopi send --to telegram "[[as_document]] MEDIA:/tmp/screenshot.png"
示例:
kopi send --to telegram "deploy finished"
echo "RAM 92%" | kopi send --to telegram:-1001234567890
kopi send --to discord:#ops --file /tmp/report.md
kopi send --to slack:#eng --subject "[CI]" --file build.log
kopi send --list # all platforms
kopi send --list telegram # filter by platform
kopi secrets
kopi secrets bitwarden <subcommand>
kopi secrets bw <subcommand> # short alias
在进程启动时从外部 secret manager(机密管理器)中提取 API 密钥,而不是将其存储在 ~/.kopi/.env 中。目前支持 Bitwarden Secrets Manager。完整指南请参阅:Bitwarden integration。
bitwarden(别名 bw)子命令:
| Subcommand | Description |
|---|---|
setup | 交互式向导:安装固定版本的 bws 二进制文件、存储 access token 并选择项目。支持 --project-id、--access-token 和 --server-url,用于非交互式使用。 |
status | 显示当前 config、二进制文件路径/版本以及最近一次获取信息。 |
sync | 立即获取 secrets 并报告发生了哪些变更。添加 --apply 以实际将 secrets 导出到当前 shell 的环境中(默认为 dry-run)。 |
install | 下载并验证固定版本的 bws 二进制文件。即使已存在托管副本,--force 也会重新下载。 |
disable | 关闭 Bitwarden 集成。 |
kopi migrate
kopi migrate <type>
诊断并(可选地)重写当前生效的 config.yaml,以替换对已退役模型或已弃用设置的引用。在任何重写之前,会对原始 config.yaml 创建带时间戳的备份(使用 --no-backup 跳过)。
| Subcommand | Description |
|---|---|
xai | 扫描 config.yaml 中对计划于 2026 年 5 月 15 日退役的 xAI 模型的引用,并(使用 --apply)按照 xAI 迁移指南就地重写为官方替代项。默认为 dry-run。 |
迁移子命令的通用 flag:
| Flag | Description |
|---|---|
--apply | 就地重写 config.yaml(默认:dry-run,不写入)。 |
--no-backup | 在应用时跳过 config.yaml 的带时间戳备份。 |
注意不要与
kopi claw migrate(将 OpenClaw 配置一次性导入 Kopi Agent)混淆——kopi migrate是顶层的配置重写命令。
kopi proxy
kopi proxy <subcommand>
运行一个本地的 OpenAI 兼容 HTTP server,将请求转发到经过 OAuth 认证的上游 provider(例如 KOPI Proxy、xAI)。外部应用可以使用任意 bearer token 指向该 proxy;proxy 会在出站时附加你的真实 OAuth 凭据。完整指南请参阅 Subscription Proxy。
| Subcommand | Description |
|---|---|
start | 在前台运行 proxy。Flags:--provider <nous|xai>(默认 nous)、--host <addr>(默认 127.0.0.1;使用 0.0.0.0 可暴露到局域网)、--port <int>(默认 8645)。 |
status | 显示哪些 proxy 上游已就绪(凭据存在、OAuth 有效)。 |
providers | 列出可用的 proxy 上游 provider。 |
kopi security
kopi security <subcommand>
针对 OSV.dev 的按需漏洞扫描。覆盖 Kopi Agent venv(已安装的 PyPI 发行版)、~/.kopi/plugins/ 下插件声明的 Python 依赖,以及 config.yaml 中固定的 npx/uvx MCP 服务器。不会扫描全局安装的软件包或编辑器/浏览器扩展。
| 子命令 | 描述 |
|---|---|
audit | 运行一次性供应链审计。 |
audit 标志:
| 标志 | 默认值 | 描述 |
|---|---|---|
--json | off | 输出机器可读的 JSON,而非人类可读的文本。 |
--fail-on <level> | critical | 当任何发现的严重程度达到该级别时以非零状态退出(low、moderate、high、critical)。 |
--skip-venv | off | 跳过扫描 Kopi Agent Python venv。 |
--skip-plugins | off | 跳过扫描插件 requirements 文件。 |
--skip-mcp | off | 跳过扫描 config.yaml 中固定的 MCP 服务器。 |
kopi login / kopi logout (已弃用)
kopi login 已被移除。请使用 kopi auth 管理 OAuth 凭据、kopi model 选择 provider(服务提供商),或使用 kopi setup 进行完整的交互式设置。
kopi auth
管理同一 provider 的凭据池以实现密钥轮换。完整文档请参阅凭据池。
kopi auth # Interactive wizard
kopi auth list # Show all pools
kopi auth list openrouter # Show specific provider
kopi auth add openrouter --api-key sk-or-v1-xxx # Add API key
kopi auth add anthropic --type oauth # Add OAuth credential
kopi auth remove openrouter 2 # Remove by index
kopi auth reset openrouter # Clear cooldowns
kopi auth status anthropic # Show auth status for a provider
kopi auth logout anthropic # Log out and clear stored auth state
kopi auth spotify # Authenticate Kopi Agent with Spotify via PKCE
子命令:add、list、remove、reset、status、logout、spotify。不带子命令调用时,将启动交互式管理向导。
kopi status
kopi status [--all] [--deep]
| 选项 | 描述 |
|---|---|
--all | 以可分享的脱敏格式显示所有详情。 |
--deep | 运行可能耗时更长的深度检查。 |
kopi cron
kopi cron <list|create|edit|pause|resume|run|remove|status|tick>
| 子命令 | 描述 |
|---|---|
list | 显示已调度的作业。 |
create / add | 根据提示创建调度作业,可通过重复使用 --skill 选择性地附加一个或多个 skill。 |
edit | 更新作业的调度、提示、名称、投递方式、重复次数或附加的 skill。支持 --clear-skills、--add-skill 和 --remove-skill。 |
pause | 暂停作业而不删除它。 |
resume | 恢复已暂停的作业并计算其下一次未来运行时间。 |
run | 在下一个调度器节拍触发作业。 |
remove | 删除调度作业。 |
status | 检查 cron 调度器是否正在运行。 |
tick | 运行一次到期的作业然后退出。 |
cron 触发器可通过 cron.provider config 键进行插拔。留空(默认值)时使用内置的进程内节拍器。可将其设置为 chronos(用于可缩容至零的托管网关的 NAS 托管 provider)——通过 cron.chronos.* 键(portal_url、callback_url、expected_audience、nas_jwks_url)进行配置——或在 plugins/cron/<name>/ 或 $KOPI_HOME/plugins/<name>/ 下指定自定义 provider。未知或不可用的 provider 会回退到内置触发器,因此 cron 永远不会没有触发器。请参阅 cron 内部机制文档。
kopi kanban
kopi kanban [--board <slug>] <action> [options]
多 profile、多项目的协作看板。每次安装可承载多个看板(每个项目、仓库或领域一个);每个看板都是一条独立的队列,拥有自己的 SQLite 数据库和 dispatcher 作用域。新安装会以一个名为 default 的看板开始,其数据库为 ~/.kopi/kanban.db(为保持向后兼容);后续新增的看板位于 ~/.kopi/kanban/boards/<slug>/kanban.db。内嵌于 gateway 的 dispatcher 每个 tick 会扫描所有看板。
全局 flag(适用于以下每个操作):
| Flag | 用途 |
|---|---|
--board <slug> | 操作指定的看板。默认使用当前看板(通过 kopi kanban boards switch、KOPI_KANBAN_BOARD 环境变量或 default 设置)。 |
这是面向人 / 脚本的接口。 由 dispatcher 生成的 agent worker 通过专用的 kanban_* toolset(kanban_show、kanban_complete、kanban_block、kanban_create、kanban_link、kanban_comment、kanban_heartbeat;orchestrator profile 还额外获得 kanban_list 和 kanban_unblock)来驱动看板,而不是通过 shell 调用 kopi kanban。Worker 的环境变量中固定写入了 KOPI_KANBAN_BOARD,因此它们在物理上无法看到其他看板。
| 操作 | 用途 |
|---|---|
init | 若 kanban.db 不存在则创建。幂等操作。 |
boards list / boards ls | 列出所有看板及其任务数量。--json、--all(包含已归档)。 |
boards create <slug> | 创建新看板。flag:--name、--description、--icon、--color、--switch(设为活跃)。Slug 为 kebab-case 格式,自动转为小写。 |
boards switch <slug> / boards use | 将 <slug> 持久化为活跃看板(写入 ~/.kopi/kanban/current)。 |
boards show / boards current | 打印当前活跃看板的名称、数据库路径和任务数量。 |
boards rename <slug> "<name>" | 修改看板的显示名称。Slug 不可更改。 |
boards rm <slug> | 归档(默认)或硬删除看板。--delete 跳过归档步骤。已归档的看板会移至 boards/_archived/<slug>-<ts>/。对 default 会拒绝执行。 |
create "<title>" | 在活跃看板上创建新任务。flag:--body、--assignee、--parent(可重复)、--workspace scratch|worktree|dir:<path>、--tenant、--priority、--triage、--idempotency-key、--max-runtime、--max-retries、--skill(可重复)。 |
list / ls | 列出活跃看板上的任务。可使用 --mine、--assignee、--status、--tenant、--archived、--json 进行过滤。 |
show <id> | 显示任务及其评论和事件。--json 用于机器可读输出。 |
assign <id> <profile> | 分配或重新分配。使用 none 取消分配。任务运行中时会拒绝执行。 |
link <parent> <child> | 添加依赖关系。会进行环检测。两个任务必须位于同一看板。 |
unlink <parent> <child> | 移除依赖关系。 |
claim <id> | 原子地认领一个就绪任务。打印解析后的 workspace 路径。 |
comment <id> "<text>" | 追加评论。下一个认领该任务的 worker 会将其作为 kanban_show() 响应的一部分读取。 |
complete <id> | 将任务标记为完成。flag:--result、--summary、--metadata。 |
block <id> "<reason>" | 将任务标记为需要人工输入的阻塞状态。同时会将原因作为评论追加。 |
schedule <id> "<reason>" | 将延时 / 后续工作暂存在 scheduled 中,使其不会显示为人工阻塞。 |
unblock <id> | 将阻塞或已计划的任务恢复为就绪状态(若依赖仍未解决则为 todo)。 |
archive <id> | 在默认列表中隐藏。gc 会删除临时 workspace。 |
tail <id> | 跟踪任务的事件流。 |
dispatch | 在活跃看板上执行一次 dispatcher 扫描。flag:--dry-run、--max N、--failure-limit N、--json。 |
context <id> | 打印 worker 将看到的完整上下文(标题 + 正文 + 父任务结果 + 评论)。 |
specify <id> / specify --all | 通过辅助 LLM 将 triage 列中的任务细化为具体规格(标题 + 包含目标、方法、验收标准的正文),然后将其提升到 todo。flag:--tenant(将 --all 限定到单个租户)、--author、--json。在 config.yaml 中的 auxiliary.triage_specifier 下配置模型。 |
decompose <id> / decompose --all | 将 triage 列中的任务展开为一个子任务图,按描述路由到专门的 profile。当 LLM 判定该任务不适合展开时,回退为 specify 风格的单任务提升。flag 与 specify 相同。在 config.yaml 中的 auxiliary.kanban_decomposer 下配置分解模型;kanban.orchestrator_profile 仅控制展开后由谁拥有根 / 编排任务。当 kanban.auto_decompose: true(默认值)时,也会在每个 dispatcher tick 自动运行。参见自动 vs 手动编排。 |
gc | 删除已归档任务的临时 workspace。 |
示例:
# Create a second board and put a task on it without switching away.
kopi kanban boards create atm10-server --name "ATM10 Server" --icon 🎮
kopi kanban --board atm10-server create "Restart server" --assignee ops
# Switch the active board for subsequent calls.
kopi kanban boards switch atm10-server
kopi kanban list # shows atm10-server tasks
# Archive a board (recoverable) or hard-delete it.
kopi kanban boards rm atm10-server
kopi kanban boards rm atm10-server --delete
看板解析顺序(优先级从高到低):--board <slug> flag → KOPI_KANBAN_BOARD 环境变量 → ~/.kopi/kanban/current 文件 → default。
所有操作也可作为 gateway(/kanban …)中的斜杠命令使用,参数接口完全相同——包括 boards 子命令和 --board flag。
完整设计文档——包括与 Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise 的对比、八种协作模式、四个用户故事、并发正确性证明——请参见仓库中的 docs/kopi-kanban-v1-spec.pdf,或 Kanban 用户指南。
kopi project
kopi project <create|list|show|add-folder|remove-folder|rename|set-primary|use|archive|restore|bind-board>
Projects(项目)是人为命名的工作区,可以跨多个文件夹 / 仓库。它们锚定桌面端会话分组,并且在绑定到看板时,会为任务提供确定性的 worktree + branch 约定。状态按 profile(配置文件)独立存储。
| 子命令 | 描述 |
|---|---|
create | 创建新项目。 |
list(别名 ls) | 列出项目。 |
show | 显示项目详情。 |
add-folder | 向项目添加文件夹 / 仓库。 |
remove-folder | 从项目中移除文件夹。 |
rename | 重命名项目。 |
set-primary | 设置主文件夹。 |
use | 设置当前活动项目。 |
archive | 归档项目(可恢复)。 |
restore | 恢复已归档的项目。 |
bind-board | 将看板绑定到此项目。 |
kopi webhook
kopi webhook <subscribe|list|remove|test>
管理用于事件驱动 agent(智能体)激活的动态 webhook(网络钩子)订阅。需要在 config 中启用 webhook 平台 — 如果未配置,会打印设置说明。
| 子命令 | 描述 |
|---|---|
subscribe / add | 创建 webhook 路由。返回需要在你的服务上配置的 URL 和 HMAC secret。 |
list / ls | 显示所有由 agent 创建的订阅。 |
remove / rm | 删除动态订阅。config.yaml 中的静态路由不受影响。 |
test | 发送测试 POST 以验证订阅是否正常工作。 |
kopi webhook subscribe
kopi webhook subscribe <name> [options]
| 选项 | 描述 |
|---|---|
--prompt | 包含 {dot.notation} 负载引用的提示模板。 |
--events | 要接受的事件类型,以逗号分隔(例如 issues,pull_request)。留空 = 接受全部。 |
--description | 人类可读的描述。 |
--skills | 要为 agent 运行加载的 skill(技能)名称,以逗号分隔。 |
--deliver | 送达目标:log(默认)、telegram、discord、slack、github_comment。 |
--deliver-chat-id | 跨平台送达的目标聊天/频道 ID。 |
--secret | 自定义 HMAC secret。如果省略则自动生成。 |
--deliver-only | 跳过 agent — 将渲染后的 --prompt 作为原始消息送达。零 LLM 开销,秒级送达。要求 --deliver 是真实目标(而非 log)。 |
--script | 位于 ~/.kopi/scripts/ 下的过滤/转换脚本。webhook 负载以 JSON 形式通过 stdin 传入;JSON stdout 会替换该负载,而空 stdout、[SILENT] 或非零退出码会忽略该 webhook。参见脚本过滤与转换。 |
订阅会持久化到 ~/.kopi/webhook_subscriptions.json,并由 webhook 适配器热重载,无需重启网关。
kopi doctor
kopi doctor [--fix]
| 选项 | 描述 |
|---|---|
--fix | 在可能的情况下尝试自动修复。 |
kopi dump
kopi dump [--show-keys]
输出整个 Kopi Agent 设置的紧凑纯文本摘要。设计用于在寻求支持时复制粘贴到 Discord、GitHub issue 或 Telegram 中 — 没有 ANSI 颜色,没有特殊格式,只有数据。
| 选项 | 描述 |
|---|---|
--show-keys | 显示脱敏后的 API key 前缀(首尾各 4 个字符),而不是仅显示 set/not set。 |
包含哪些内容
| 部分 | 详情 |
|---|---|
| Header | Kopi Agent 版本、发布日期、git commit hash |
| Environment | 操作系统、Python 版本、OpenAI SDK 版本 |
| Identity | 当前活动 profile 名称、KOPI_HOME 路径 |
| Model | 已配置的默认模型和 provider |
| Terminal | 后端类型(local、docker、ssh 等) |
| API keys | 全部 22 个 provider/工具 API key 的存在性检查 |
| Features | 已启用的 toolset、MCP server 数量、memory provider |
| Services | 网关状态、已配置的消息平台 |
| Workload | Cron 任务数量、已安装的 skill 数量 |
| Config overrides | 与默认值不同的所有 config 配置值 |
示例输出
--- kopi dump ---
version: 0.8.0 (2026.4.8) [af4abd2f]
os: Linux 6.14.0-37-generic x86_64
python: 3.11.14
openai_sdk: 2.24.0
profile: default
kopi_home: ~/.kopi
model: anthropic/claude-opus-4.6
provider: openrouter
terminal: local
api_keys:
openrouter set
openai not set
anthropic set
nous not set
firecrawl set
...
features:
toolsets: all
mcp_servers: 0
memory_provider: built-in
gateway: running (systemd)
platforms: telegram, discord
cron_jobs: 3 active / 5 total
skills: 42
config_overrides:
agent.max_turns: 250
compression.threshold: 0.85
display.streaming: True
--- end dump ---
何时使用
- 在 GitHub 上报告 bug — 将 dump 粘贴到你的 issue 中
- 在 Discord 上寻求帮助 — 以代码块形式分享
- 将你的设置与其他人的进行比较
- 当某些功能无法正常工作时进行快速健全性检查
kopi dump 专为分享而设计。要进行交互式诊断,请使用 kopi doctor。要查看可视化概览,请使用 kopi status。
kopi debug
kopi debug share [options]
将调试报告(系统信息 + 近期日志)上传到粘贴服务,并获取一个可分享的 URL。适用于快速支持请求 — 包含协助者诊断你的问题所需的一切信息。
| 选项 | 描述 |
|---|---|
--lines <N> | 每个日志文件包含的日志行数(默认:200)。 |
--expire <days> | 粘贴内容的过期天数(默认:7)。 |
--nous | 上传到 Nous 内部诊断存储,而非公开粘贴服务。当 Nous 支持团队要求提供私有诊断包时使用此选项。 |
--local | 在本地打印报告而不上传。 |
--no-redact | 禁用上传时的 secret 脱敏。默认情况下,上传内容会被脱敏。 |
报告包含系统信息(操作系统、Python 版本、Kopi Agent 版本)、近期的 agent、网关、GUI/仪表盘和桌面日志(每个文件 512 KB 上限),以及脱敏后的 API key 状态。默认情况下,上传内容会被脱敏,因此不会包含 secret。
默认上传会按顺序依次尝试公开粘贴服务:paste.rs、dpaste.com。--nous 则会将相同的调试包上传到私有的 Nous 诊断存储;返回的查看链接面向 Nous 团队,14 天后自动删除。
示例
kopi debug share # Upload debug report, print URL
kopi debug share --lines 500 # Include more log lines
kopi debug share --expire 30 # Keep paste for 30 days
kopi debug share --nous # Upload a private diagnostics bundle for Nous support
kopi debug share --local # Print report to terminal (no upload)
kopi backup
kopi backup [options]
为你的 Kopi Agent 配置、skill、会话和数据创建一个 zip 归档。备份不包含 kopi-ai-agent 代码库本身。
| 选项 | 说明 |
|---|---|
-o, --output <path> | zip 文件的输出路径(默认:~/kopi-backup-<timestamp>.zip)。 |
-q, --quick | 快速快照:仅包含关键状态文件(config.yaml、state.db、.env、auth、cron 任务)。比完整备份快得多。 |
-l, --label <name> | 快照的标签(仅与 --quick 一起使用)。 |
备份使用 SQLite 的 backup() API 进行安全复制,因此即使 Kopi Agent 正在运行也能正常工作(WAL 模式安全)。
zip 中排除的内容:
*.db-wal、*.db-shm、*.db-journal— SQLite 的 WAL / 共享内存 / 日志边车文件。*.db文件已经通过sqlite3.backup()获得了一致的快照;将活跃的边车文件一并打包会让恢复时看到一个半提交的状态。checkpoints/— 每个会话的轨迹缓存。以哈希为键,并在每个会话中重新生成;无论如何也无法干净地迁移到另一个安装环境。kopi-ai-agent代码本身(这是用户数据备份,而不是仓库快照)。
示例
kopi backup # Full backup to ~/kopi-backup-*.zip
kopi backup -o /tmp/kopi.zip # Full backup to specific path
kopi backup --quick # Quick state-only snapshot
kopi backup --quick --label "pre-upgrade" # Quick snapshot with label
kopi checkpoints
kopi checkpoints [COMMAND]
检查并管理位于 ~/.kopi/checkpoints/ 的影子 git 存储 —— 即会话内 /rollback 命令背后的存储层。任何时候运行都是安全的;不要求 agent 正在运行。
| 子命令 | 说明 |
|---|---|
status(默认) | 显示总大小、项目数量以及按项目的细分。单独的 kopi checkpoints 与之等效。 |
list | status 的别名。 |
prune | 强制执行清理扫描 —— 删除孤立和过期项目、对存储执行 GC、强制执行大小上限。忽略 24 小时幂等标记。 |
clear | 删除整个 checkpoint 基础。不可逆;除非使用 -f,否则会要求确认。 |
clear-legacy | 仅删除由 v1→v2 迁移产生的 legacy-<timestamp>/ 归档。 |
选项
| 选项 | 子命令 | 说明 |
|---|---|---|
--limit N | status, list | 最多列出的项目数(默认 20)。 |
--retention-days N | prune | 删除 last_touch 早于 N 天的项目(默认 7)。 |
--max-size-mb N | prune | 在孤立/过期项目清理之后,逐个项目删除最旧的 commit,直到总存储大小 ≤ N MB(默认 500)。 |
--keep-orphans | prune | 跳过删除工作目录已不存在的项目。 |
-f, --force | clear, clear-legacy | 跳过确认提示。 |
示例
kopi checkpoints # status overview
kopi checkpoints prune --retention-days 3 # aggressive cleanup
kopi checkpoints prune --max-size-mb 200 # tighten size cap once
kopi checkpoints clear-legacy -f # drop v1 archive dirs
kopi checkpoints clear -f # wipe everything
完整架构及会话内命令请参阅Checkpoints 和 /rollback。
kopi import
kopi import <zipfile> [options]
将先前创建的 Kopi Agent 备份恢复到你的 Kopi Agent 主目录中。归档中的所有文件都会覆盖 Kopi Agent 主目录中的现有文件;--force 仅跳过当目标位置已存在 Kopi Agent 安装时弹出的确认提示。
| 选项 | 说明 |
|---|---|
-f, --force | 跳过已有安装的确认提示。 |
导入前请先停止网关,以避免与正在运行的进程发生冲突。
示例
kopi import ~/kopi-backup-20260423.zip # Prompts before overwriting existing config
kopi import ~/kopi-backup-20260423.zip --force # Overwrite without prompting
kopi logs
kopi logs [log_name] [options]
查看、跟踪和过滤 Kopi Agent 日志文件。所有日志都存储在 ~/.kopi/logs/(对于非默认 profile 则是 <profile>/logs/)。
日志文件
| 名称 | 文件 | 记录内容 |
|---|---|---|
agent(默认) | agent.log | 所有 agent 活动 —— API 调用、工具分发、会话生命周期(INFO 及以上级别) |
errors | errors.log | 仅警告和错误 —— agent.log 的过滤子集 |
gateway | gateway.log | 消息网关活动 —— 平台连接、消息分发、webhook 事件 |
gui | gui.log | Dashboard / TUI 网关 / PTY 桥接 / websocket 事件 |
desktop | desktop.log | Electron 桌面应用 —— 启动、后端进程输出以及最近的 Python 回溯 |
选项
| 选项 | 说明 |
|---|---|
log_name | 要查看的日志:agent(默认)、errors、gateway,或使用 list 显示可用文件及其大小。 |
-n, --lines <N> | 要显示的行数(默认:50)。 |
-f, --follow | 实时跟踪日志,类似 tail -f。按 Ctrl+C 停止。 |
--level <LEVEL> | 要显示的最低日志级别:DEBUG、INFO、WARNING、ERROR、CRITICAL。 |
--session <ID> | 过滤包含某会话 ID 子串的行。 |
--since <TIME> | 显示相对时间之前的行:30m、1h、2d 等。支持 s(秒)、m(分钟)、h(小时)、d(天)。 |
--component <NAME> | 按组件过滤:gateway、agent、tools、cli、cron。 |
示例
# View the last 50 lines of agent.log (default)
kopi logs
# Follow agent.log in real time
kopi logs -f
# View the last 100 lines of gateway.log
kopi logs gateway -n 100
# Show only warnings and errors from the last hour
kopi logs --level WARNING --since 1h
# Filter by a specific session
kopi logs --session abc123
# Follow errors.log, starting from 30 minutes ago
kopi logs errors --since 30m -f
# List all log files with their sizes
kopi logs list
过滤
过滤条件可以组合使用。当多个过滤条件同时生效时,日志行必须通过所有条件才会显示:
# WARNING+ lines from the last 2 hours containing session "tg-12345"
kopi logs --level WARNING --since 2h --session tg-12345
当 --since 处于激活状态时,不带可解析时间戳的行也会被包含(它们可能是多行日志条目中的续行)。当 --level 处于激活状态时,不带可识别级别的行也会被包含。
日志轮转
Kopi Agent 使用 Python 的 RotatingFileHandler。旧日志会自动轮转 —— 查找 agent.log.1、agent.log.2 等文件。kopi logs list 子命令会显示所有日志文件,包括已轮转的文件。
kopi prompt-size
kopi prompt-size [--platform <name>] [--json]
报告全新会话的固定 prompt 预算——即在任何对话内容之前,每次 API 调用都会发送的内容。当下游 adapter 或 proxy 的 prompt 预算比模型的上下文窗口更紧张时,或者当你想查看哪个区块(skills 索引、memory、profile)占用了最多空间时,这个命令非常有用。
它会构建与 agent 相同的 system prompt,然后进行拆分:
- System prompt 总量 —— 完整组装后的 prompt(身份、指引、skills 索引、context 文件、memory、profile、时间戳)。
- Skills 索引 ——
<available_skills>区块。当安装了大量 skill 时,这通常是最大的单个区块。 - Memory 与 user profile —— 你的
MEMORY.md/USER.md快照。 - Prompt 层级 —— stable / context / volatile,与 Kopi Agent 为提高缓存友好度而分层组织 prompt 的方式一致。
- Tool schemas —— 所有已启用 tool 的 JSON(固定单次调用负载的另一半)。
完全离线运行——不发起 API 调用,无需配置任何凭据即可使用。
# Human-readable breakdown for the CLI platform (default)
kopi prompt-size
# Simulate a messaging platform's prompt (different platform hint)
kopi prompt-size --platform telegram
# Machine-readable output for scripts
kopi prompt-size --json
Skills 索引和 tool schemas 的大小会随你启用的 skill 与 tool 数量增长。要缩小 prompt,可以禁用不需要的 toolset(kopi tools),或卸载不需要的 skill(kopi skills)。当前目录中的 context 文件(AGENTS.md、.cursorrules)也会计入总量。
kopi config
kopi config <subcommand>
子命令:
| 子命令 | 描述 |
|---|---|
show | 显示当前 config 值。 |
edit | 在编辑器中打开 config.yaml。 |
set <key> <value> | 设置一个 config 值。 |
path | 打印 config 文件路径。 |
env-path | 打印 .env 文件路径。 |
check | 检查 config 是否缺失或过期。 |
migrate | 以交互方式添加新引入的选项。 |
kopi pairing
kopi pairing <list|approve|revoke|clear-pending>
| 子命令 | 描述 |
|---|---|
list | 显示待批准和已批准的用户。 |
approve <platform> <code> | 批准一个配对码。 |
revoke <platform> <user-id> | 撤销某个用户的访问权限。 |
clear-pending | 清除待处理的配对码。 |
kopi skills
kopi skills <subcommand>
子命令:
| 子命令 | 描述 |
|---|---|
browse | 浏览 skill registry 的分页浏览器。 |
search | 搜索 skill registry。 |
install | 安装一个 skill。 |
inspect | 预览某个 skill,而不实际安装它。 |
list | 列出已安装的 skill。 |
check | 检查已安装的 hub skill 是否有上游更新。 |
update | 在有上游变更时重新安装 hub skill。 |
audit | 重新扫描已安装的 hub skill。 |
uninstall | 移除一个通过 hub 安装的 skill。 |
reset | 通过清除其 manifest 条目,解除被标记为 user_modified 的内置 skill 的锁定状态。使用 --restore 时,还会用内置版本替换用户副本。 |
opt-out | 阻止内置 skill 被写入当前活动的 profile。会写入一个 .no-bundled-skills 标记,使安装器、kopi update 以及任何 sync 都跳过内置 skill 的写入。默认是安全的——不会改动磁盘上的任何内容。使用 --remove 时,还会删除已存在且未被修改的内置 skill(用户编辑过的、通过 hub 安装的以及手写的 skill 永远不会被删除;会先预览并确认,使用 --yes 可跳过确认)。 |
opt-in | 撤销 opt-out,移除 .no-bundled-skills 标记,使内置 skill 在下一次 kopi update 时重新写入。使用 --sync 时,立即重新写入。 |
publish | 将 skill 发布到某个 registry。 |
snapshot | 导出/导入 skill 配置。 |
tap | 管理自定义 skill 来源。 |
config | 按平台对 skill 进行交互式的启用/禁用配置。 |
常见示例:
kopi skills browse
kopi skills browse --source official
kopi skills search react --source skills-sh
kopi skills search https://mintlify.com/docs --source well-known
kopi skills inspect official/security/1password
kopi skills inspect skills-sh/vercel-labs/json-render/json-render-react
kopi skills install official/migration/openclaw-migration
kopi skills install skills-sh/anthropics/skills/pdf --force
kopi skills install https://sharethis.chat/SKILL.md # Direct URL (single-file SKILL.md)
kopi skills install https://example.com/SKILL.md --name my-skill # Override name when frontmatter has none
kopi skills check
kopi skills update
kopi skills config
kopi skills reset google-workspace
kopi skills reset google-workspace --restore --yes
kopi skills opt-out # stop future bundled-skill seeding (nothing deleted)
kopi skills opt-out --remove --yes # also delete UNMODIFIED bundled skills
kopi skills opt-in --sync # undo: remove marker and re-seed now
说明:
--force可以为第三方/社区 skill 覆写非危险的 policy 区块。--force不会覆写dangerous的扫描判定结果。--source skills-sh会搜索公开的skills.sh目录。--source well-known可让 Kopi Agent 指向一个暴露/.well-known/skills/index.json的站点。--source browse-sh会搜索 browse.sh 的目录,其中包含 200 多个针对特定站点的浏览器自动化 skill。标识符的形式类似browse-sh/airbnb.com/search-listings-ddgioa。- 传入一个
http(s)://…/*.mdURL 会直接安装单文件 SKILL.md。当 frontmatter 中没有name:且 URL slug 不是有效的标识符时,交互式终端会提示输入名称;非交互式界面(TUI 内的/skills install、gateway 平台)则需要改用--name <x>。
kopi bundles
kopi bundles <subcommand>
Skill bundle 将多个 skill 归入一个 /<bundle-name> slash 命令。调用该 bundle 会将所有引用的 skill 加载到一条合并后的 user message 中。存储位置:~/.kopi/skill-bundles/<slug>.yaml。YAML schema 和行为请参阅 Skill Bundles。
子命令:
| 子命令 | 描述 |
|---|---|
list | 列出已安装的 bundle(未指定子命令时的默认行为) |
show <name> | 显示某个 bundle 的名称、描述、skills 及文件路径 |
create <name> | 创建一个新的 bundle。可传入 --skill <id>(可重复),或省略以交互方式输入。提供 --description、--instruction、--force。 |
delete <name> | 移除一个 bundle 文件 |
reload | 重新扫描 ~/.kopi/skill-bundles/ 并报告新增/移除的 bundle |
示例:
kopi bundles create backend-dev \
--skill github-code-review \
--skill test-driven-development \
--skill github-pr-workflow \
-d "Backend feature work"
kopi bundles list
kopi bundles show backend-dev
kopi bundles delete backend-dev
在聊天会话中,/bundles 会列出已安装的 bundle,/<bundle-name> 会加载其中一个。
kopi curator
kopi curator <subcommand>
curator(整理器)是一个基于辅助模型的后台任务,会定期检查由 agent 创建的 skill,清除过时的 skill,合并重叠的 skill,并归档废弃的 skill。内置(Bundled)和从 hub 安装的 skill 永远不会被改动。归档是可恢复的;绝不会发生自动删除。
| 子命令 | 描述 |
|---|---|
status | 显示 curator 状态和 skill 统计信息 |
run | 立即触发一次 curator 检查(阻塞直到 LLM 处理完成) |
run --background | 在后台线程中启动 LLM 处理并立即返回 |
run --dry-run | 仅预览——生成检查报告,不做任何改动 |
backup | 对 ~/.kopi/skills/ 手动创建 tar.gz 快照(curator 在每次实际运行前也会自动快照) |
rollback | 从快照恢复 ~/.kopi/skills/(默认恢复最新的快照) |
rollback --list | 列出可用快照 |
rollback --id <ts> | 按 id 恢复指定快照 |
rollback -y | 跳过确认提示 |
pause | 暂停 curator,直到恢复为止 |
resume | 恢复已暂停的 curator |
pin <skill> | 固定(pin)某个 skill,使 curator 永远不会自动更改其状态 |
unpin <skill> | 取消固定某个 skill |
restore <skill> | 恢复一个已归档的 skill |
archive <skill> | 手动归档一个 skill |
prune | 手动清理 curator 通常会清除的 skill |
list-archived | 列出已归档的 skill(可通过 restore 恢复) |
在全新安装时,首次计划检查会推迟一个完整的 interval_hours(默认为 7 天)——网关不会在 kopi update 之后的首个周期就立即进行整理。请在那之前使用 kopi curator run --dry-run 进行预览。
行为和配置详情请参阅 Curator。
kopi moa
配置命名的 Mixture of Agents 预设。预设会以可选模型的形式出现在每个模型选择器的 Mixture of Agents provider 下;/moa <prompt> 会使用默认预设运行一次提示。
kopi moa list
kopi moa configure [name]
kopi moa delete <name>
kopi moa configure 会为每个参考模型和聚合器复用 Kopi Agent 的 provider → model 选择器。预设是一种执行模式配置,而不是主模型或 provider。
kopi fallback
kopi fallback <subcommand>
管理 fallback provider(回退服务提供商)链。当主模型因速率限制、过载或连接错误而失败时,会按顺序尝试 fallback provider。
| 子命令 | 描述 |
|---|---|
list(别名:ls) | 显示当前的回退链(未指定子命令时的默认行为) |
add | 选择一个 provider + model(与 kopi model 相同的选择器)并追加到链中 |
remove(别名:rm) | 选择链中的一个条目进行删除 |
clear | 移除所有回退条目 |
kopi hooks
kopi hooks <subcommand>
检查在 ~/.kopi/config.yaml 中声明的 shell 脚本 hook,使用合成负载测试它们,并管理位于 ~/.kopi/shell-hooks-allowlist.json 的首次使用同意(consent)允许列表。
| 子命令 | 描述 |
|---|---|
list(别名:ls) | 列出已配置的 hook,包括 matcher、超时时间和同意状态 |
test <event> | 针对合成负载触发每个匹配 <event> 的 hook |
revoke(别名:remove、rm) | 移除某个命令的允许列表条目(下次重启后生效) |
doctor | 检查每个已配置的 hook:执行权限位、允许列表、mtime 漂移、JSON 有效性以及合成运行耗时 |
事件签名和负载结构请参见 Hooks。
kopi memory
kopi memory <subcommand>
设置并管理外部 memory provider(记忆服务提供商)plugin。可用的 provider 有:honcho、openviking、mem0、hindsight、holographic、retaindb、byterover、supermemory。同一时间只能激活一个外部 provider。内置记忆(MEMORY.md/USER.md)始终处于激活状态。
子命令:
| 子命令 | 描述 |
|---|---|
setup | 交互式选择并配置 provider。 |
status | 显示当前的 memory provider 配置。 |
off | 禁用外部 provider(仅使用内置记忆)。 |
当外部 memory provider 处于激活状态时,它可能会注册自己的顶层 kopi <provider> 命令用于 provider 专属管理(例如 Honcho 激活时的 kopi honcho)。未激活的 provider 不会暴露其子命令。运行 kopi --help 可查看当前接入了哪些内容。
kopi acp
kopi acp
将 Kopi Agent 作为 ACP(Agent Client Protocol)stdio 服务器启动,用于编辑器集成。
相关入口:
kopi-acp
python -m acp_adapter
请先安装支持:
cd ~/.kopi/kopi-ai-agent && uv pip install -e '.[acp]'
参见 ACP Editor Integration 和 ACP Internals。
kopi mcp
kopi mcp <subcommand>
管理 MCP(Model Context Protocol)服务器配置,并将 Kopi Agent 作为 MCP 服务器运行。
| 子命令 | 描述 |
|---|---|
(无) 或 picker | 交互式目录选择器——浏览 Nous 认可的 MCP 并进行安装/启用/禁用。 |
catalog | 列出 Nous 认可的 MCP(纯文本,便于脚本处理)。 |
install <name> | 安装目录中的条目(例如 kopi mcp install n8n)。 |
serve [-v|--verbose] | 将 Kopi Agent 作为 MCP 服务器运行——把对话暴露给其他 agent。 |
add <name> [--url URL] [--command CMD] [--auth oauth|header] [--args ...] | 添加一个自定义 MCP server,并自动发现工具。--args 会把剩余的 argv 传递给 stdio 命令,因此请把它放在最后。 |
remove <name>(别名:rm) | 从配置中移除某个 MCP server。 |
list(别名:ls) | 列出已配置的 MCP server。 |
test <name> | 测试与某个 MCP server 的连接。 |
configure <name>(别名:config) | 切换某个 server 的工具选择。 |
login <name> | 强制对基于 OAuth 的 MCP server 重新进行身份验证。 |
参见 MCP Config Reference、Use MCP with Kopi Agent 和 MCP Server Mode。
kopi plugins
kopi plugins [subcommand]
统一的插件管理 —— 将常规插件、memory provider 与 context engine 集中在一处。不带子命令运行 kopi plugins 会打开一个包含两个部分的复合交互界面:
- General Plugins —— 通过多选复选框启用/禁用已安装的插件
- Provider Plugins —— 针对 Memory Provider 和 Context Engine 的单选配置。在某个类别上按 ENTER 可打开单选选择器。
| 子命令 | 描述 |
|---|---|
| (无) | 复合交互界面 —— 常规插件开关 + provider 插件配置。 |
install <identifier> [--force] | 通过 Git URL 或 owner/repo 安装插件。 |
update <name> | 拉取已安装插件的最新变更。 |
remove <name>(别名:rm、uninstall) | 移除已安装的插件。 |
enable <name> | 启用已禁用的插件。 |
disable <name> | 禁用插件但不移除它。 |
list(别名:ls) | 列出已安装的插件及其启用/禁用状态。 |
provider 插件的选择会保存到 config.yaml:
memory.provider—— 当前活动的 memory provider(为空 = 仅内置)context.engine—— 当前活动的 context engine("compressor"= 内置默认值)
常规插件的禁用列表保存在 config.yaml 的 plugins.disabled 下。
参见 Plugins 和 Build a Kopi Agent Plugin。
kopi tools
kopi tools [--summary]
| 选项 | 描述 |
|---|---|
--summary | 打印当前已启用工具的摘要并退出。 |
不指定 --summary 时,会启动按平台逐项配置工具的交互式 UI。
kopi computer-use
kopi computer-use <subcommand>
子命令:
| 子命令 | 描述 |
|---|---|
install | 运行上游 cua-driver 安装程序(macOS、Windows 和 Linux)。 |
install --upgrade | 即使 cua-driver 已在 PATH 中,也重新运行安装程序。上游脚本始终拉取最新版本,因此这会执行就地升级。 |
status | 打印 cua-driver 是否位于 $PATH 上以及已安装的版本。 |
kopi computer-use install 是安装 computer_use 工具集所使用的
cua-driver 二进制文件的稳定入口。它运行的上游安装程序与
kopi tools 在你首次启用 Computer Use 时调用的相同,因此如果你的工具集开关
没有触发安装(例如在回归用户的配置场景下),可以安全地用它重新执行安装。
如果 cua-driver 位于 PATH 中,kopi update 会在更新结束时自动重新运行
上游安装程序,因此大多数用户无需手动调用 --upgrade。当你希望立即获得
上游发布的修复,而不必等待下一次 Kopi Agent 更新时,可以使用它。
kopi pets
kopi pets <list|install|select|show|off|scale|remove|doctor>
Petdex 是一个面向编码 agent 的动画精灵宠物公共画廊。安装一个后,Kopi Agent 会在 CLI、TUI 和桌面应用中展示它对 agent 活动的反应。
| 子命令 | 描述 |
|---|---|
list | 浏览 petdex 画廊。 |
install | 从画廊安装宠物。 |
select | 设置活动宠物(写入 display.pet.*)。 |
show | 让活动宠物在终端中播放动画。 |
off | 禁用宠物显示。 |
scale | 调整宠物在所有位置的大小(display.pet.scale)。 |
remove | 删除已安装的宠物。 |
doctor | 检查宠物设置 + 终端图形支持情况。 |
你还可以使用 /hatch 斜杠命令根据文本描述生成全新的宠物。参见 Pets。
kopi sessions
kopi sessions <subcommand>
子命令:
| 子命令 | 描述 |
|---|---|
list | 列出最近的会话。 |
browse | 交互式会话选择器,支持搜索和恢复。 |
export <output> [--session-id ID] | 将会话导出为 JSONL。 |
delete <session-id> | 删除单个会话。 |
prune | 删除与过滤条件匹配的会话:时间范围 --older-than/--newer-than/--before/--after(时长形式如 5h/2d、纯天数或 ISO 时间戳);属性 --source、--title、--model、--provider、--branch、--end-reason、--user、--chat-id、--chat-type、--cwd;数值范围 --min/--max-messages、--min/--max-tokens、--min/--max-cost、--min/--max-tool-calls;以及 --include-archived、--dry-run、CODE_1000。默认:90 天前的会话。 |
| CODE_1001 | 批量归档(软隐藏,不删除)与 CODE_1002 相同过滤条件匹配的会话。至少需要指定一个过滤条件。 |
| CODE_1003 | 显示会话存储的统计信息。 |
| CODE_1004 | 设置或修改会话标题。 |
CODE_1005
kopi insights [--days N] [--source platform]
| 选项 | 描述 |
|---|---|
| CODE_1006 | 分析最近 CODE_1007 天的数据(默认:30)。 |
| CODE_1008 | 按来源过滤,例如 CODE_1009、CODE_1010 或 CODE_1011。 |
CODE_1012
kopi claw migrate [options]
将你的 OpenClaw 配置迁移到 Kopi Agent。从 CODE_1013(或自定义路径)读取,并写入 CODE_1014。自动检测旧版目录名(CODE_1015、CODE_1016)和配置文件名(CODE_1017、CODE_1018)。
| 选项 | 描述 |
|---|---|
| CODE_1019 | 预览将要迁移的内容,不写入任何文件。 |
| CODE_1020 | 迁移预设:CODE_1021(所有兼容设置)或 CODE_1022(排除基础设施配置)。两个预设都不会导入 secrets —— 请显式传入 CODE_1023。 |
| CODE_1024 | 在冲突时覆盖已有的 Kopi Agent 文件(默认:当计划存在冲突时拒绝应用)。 |
| CODE_1025 | 在迁移中包含 API 密钥。即使在 CODE_1026 下也需要此项。 |
| CODE_1027 | 跳过 CODE_1028 的迁移前 zip 快照(默认情况下,应用前会将单个还原点归档写入 CODE_1029;可用 CODE_1030 还原)。 |
| CODE_1031 | 自定义 OpenClaw 目录(默认:CODE_1032)。 |
| CODE_1033 | 工作区指令(AGENTS.md)的目标目录。 |
| CODE_1034 | 处理 skill 名称冲突:CODE_1035(默认)、CODE_1036 或 CODE_1037。 |
| CODE_1038 | 跳过确认提示。 |
迁移内容
迁移涵盖 30 多个类别,涉及 persona、memory、skills、模型 providers、消息平台、agent 行为、会话策略、MCP servers、TTS 等。各条目要么直接导入为 Kopi Agent 的对应项,要么归档以供手动审阅。
直接导入: SOUL.md、MEMORY.md、USER.md、AGENTS.md、skills(4 个源目录)、默认模型、自定义 providers、MCP servers、消息平台 tokens 和允许列表(Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost)、agent 默认设置(reasoning effort、compression、human delay、timezone、sandbox)、会话重置策略、审批规则、TTS 配置、浏览器设置、工具设置、exec 超时、命令允许列表、gateway 配置,以及来自 3 个来源的 API 密钥。
归档以供手动审阅: Cron 任务、plugins、hooks/webhooks、memory 后端(QMD)、skills 注册表配置、UI/身份、日志记录、多 agent 设置、渠道绑定、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。
API 密钥解析按优先级顺序检查三个来源:config 值 → CODE_1039 → CODE_1040。所有 token 字段都支持纯字符串、env 模板(CODE_1041)和 SecretRef 对象。
完整的 config key 映射、SecretRef 处理详情以及迁移后检查清单,请参阅**完整迁移指南**。
示例
# Preview what would be migrated
kopi claw migrate --dry-run
# Full migration (all compatible settings, no secrets)
kopi claw migrate --preset full
# Full migration including API keys
kopi claw migrate --preset full --migrate-secrets
# Migrate user data only (no secrets), overwrite conflicts
kopi claw migrate --preset user-data --overwrite
# Migrate from a custom OpenClaw path
kopi claw migrate --source /home/user/old-openclaw
CODE_1042
kopi serve [options]
启动 Kopi Agent 后端服务器 —— 即 desktop app 和远程客户端连接的 JSON-RPC/WebSocket gateway。它与 CODE_1043 运行的是同一个服务器,但以无头模式运行:永远不会打开浏览器 UI。desktop app 会启动自己的 CODE_1044 后端;当你需要在远程主机上运行无头后端时,请直接使用此命令。接受与下方 CODE_1051 相同的 CODE_1045 / CODE_1046 / CODE_1047 / CODE_1048 / CODE_1049 / CODE_1050 选项(绑定到非 loopback 地址会触发相同的认证闸门)。需要 CODE_1052 extra;内嵌 Chat socket 还需要在 POSIX 主机上安装 CODE_1053。
CODE_1054
kopi dashboard [options]
启动 web dashboard —— 一个基于浏览器的 UI,用于管理配置、API 密钥和监控会话。(如果需要没有浏览器 UI 的无头后端 —— 例如 desktop app 所启动的 —— 请使用上方的 CODE_1055。)需要 CODE_1056(FastAPI + Uvicorn)。内嵌的浏览器 Chat 标签页始终可用,并且额外需要 CODE_1057 extra(CODE_1058)以及 POSIX PTY 环境,例如 Linux、macOS 或 WSL2。完整文档请参阅 Web Dashboard。
| 选项 | 默认值 | 描述 |
|---|---|---|
| CODE_1059 | CODE_1060 | 运行 web 服务器的端口 |
| CODE_1061 | CODE_1062 | 绑定地址 |
| CODE_1063 | — | 不自动打开浏览器 |
| CODE_1064 | off | 已弃用 / 无效操作。 此前用于在非 loopback 绑定时绕过认证。自 2026 年 6 月的安全加固起,公开绑定始终需要 auth provider(密码或 OAuth)。请绑定 CODE_1065 并通过隧道访问,以保持本地化。 |
| CODE_1066 | off | 跳过 web UI 构建步骤,直接提供现有的 CODE_1067。适用于没有 npm 的非交互式环境(Windows 计划任务、CI)。请用 CODE_1068 预先构建。 |
| CODE_1069 | off | 从命名 profile(CODE_1070)启动时,运行该 profile 专属的独立服务器,而不是路由到机器 dashboard。 |
| CODE_1071 | — | 停止运行中的 CODE_1072 进程并退出。 |
| CODE_1073 | — | 列出运行中的 CODE_1074 进程并退出。 |
CODE_1075
将此安装注册为你的 KOPI Proxy 账户下的自托管 dashboard。创建 OAuth client,将 CODE_1076 写入 CODE_1077,并打印如何启用登录闸门的说明。需要已登录(CODE_1078)。
| 选项 | 描述 |
|---|---|
| CODE_1079 | dashboard 的人类可读标签(默认:自动生成)。 |
| CODE_1080 | 公网 HTTPS OAuth 重定向 URI(例如 CODE_1081)。若仅用于 localhost,可省略。 |
| CODE_1082 | 覆盖注册所用的 KOPI Proxy 基础 URL(默认:你登录的 portal)。也可通过 CODE_1083 设置。 |
# Default — opens browser to http://127.0.0.1:9119
kopi dashboard
# Custom port, no browser
kopi dashboard --port 8080 --no-open
# From a profile alias — routes to the machine dashboard with the
# profile preselected in the sidebar switcher (attach if running)
worker dashboard
CODE_1084
kopi profile <subcommand>
管理 profile — 多个相互隔离的 Kopi Agent 实例,每个实例拥有各自的 config、sessions、skills 和 home 目录。
| 子命令 | 说明 |
|---|---|
| CODE_1085 | 列出所有 profile。 |
| CODE_1086 | 设置一个持久的默认 profile。 |
| CODE_1087 | 创建新的 profile。CODE_1088 会从活动 profile 复制 config、CODE_1089、CODE_1090 和 skills。CODE_1091 会复制全部状态。CODE_1092 指定源 profile,默认隐含 config 克隆,除非与 CODE_1093 搭配使用。 |
| CODE_1094 | 删除 profile。 |
| CODE_1095 | 显示 profile 详情(home 目录、config 等)。 |
| CODE_1096 | 管理用于快速访问 profile 的 wrapper 脚本。 |
| CODE_1097 | 重命名 profile。 |
| CODE_1098 | 将 profile 导出为 CODE_1099 归档(本地备份)。 |
| CODE_1100 | 从 CODE_1101 归档导入 profile(本地恢复)。 |
| CODE_1102 | 从 git URL 或本地目录安装 profile 发行版。 |
| CODE_1103 | 重新拉取发行版;保留用户数据(memories、sessions、auth)。 |
| CODE_1104 | 显示 profile 的发行版 manifest(版本、依赖要求、来源)。 |
示例:
kopi profile list
kopi profile create work --clone
kopi profile use work
kopi profile alias work --name h-work
kopi profile export work -o work-backup.tar.gz
kopi profile import work-backup.tar.gz --name restored
kopi profile install github.com/user/my-distro --alias
kopi profile update work
kopi -p work chat -q "Hello from work profile"
CODE_1105
kopi completion [bash|zsh|fish]
将 shell 补全脚本打印到 stdout。将输出内容 source 到你的 shell profile 中,即可为 Kopi Agent 的命令、子命令和 profile 名称启用 Tab 补全。
示例:
# Bash
kopi completion bash >> ~/.bashrc
# Zsh
kopi completion zsh >> ~/.zshrc
# Fish
kopi completion fish > ~/.config/fish/completions/kopi.fish
CODE_1106
kopi update [--gateway] [--check] [--no-backup] [--backup] [--yes]
拉取最新的 CODE_1107 代码并在托管 venv 中重新安装依赖,然后重新运行安装后钩子(MCP servers、skills 同步、补全安装)。可在活跃安装上安全运行。使用 CODE_1108 可在不安装的情况下查看你的检出版本是否落后于 CODE_1109。
CODE_1110 会拉取配置的更新分支(默认:CODE_1111)。如果你的检出位于其他分支,Kopi Agent 可能会先检出更新分支再拉取。若想让分支上的工作不受更新自动 stash 流程影响,请在更新前提交相关改动。
| 选项 | 说明 |
|---|---|
| CODE_1112 | 消息 CODE_1113 命令使用的内部模式。通过基于文件的 IPC 处理提示和进度流式传输,而不是从终端 stdin 读取。这不是 gateway 重启标志。 |
| CODE_1114 | 仅检查是否有可用更新,不执行拉取、安装依赖或重启任何组件。 |
| CODE_1115 | 本次运行跳过更新前备份,即使 CODE_1117 中启用了 CODE_1116。 |
| CODE_1118 | 在拉取前为 CODE_1119(config、auth、sessions、skills、pairing 数据)创建带标签的更新前快照。默认为 关闭 — 之前的始终备份行为会让大型 home 目录上的每次更新都多花数分钟。可通过 CODE_1121 中的 CODE_1120 永久开启。 |
| CODE_1122、CODE_1123 | 对 config 迁移和 stash 恢复等交互式提示自动回答 yes。API key 输入会被跳过;如需填写,请单独运行 CODE_1124。 |
其他行为:
- Gateway 重启。 更新成功后,Kopi Agent 会尝试自动重启所有正在运行的 gateway profile,使其加载新代码。若只想重启 gateway 而不应用更新,请使用 CODE_1125。
- 本地源码改动。 对于 git 安装,检出分支或拉取前会自动 stash 有改动的已跟踪文件和未跟踪文件(CODE_1126)。交互式终端更新会在恢复 stash 前先行询问。非交互式更新默认会恢复;仅在托管安装上、且本地源码改动应在成功拉取后丢弃时才设置 CODE_1127。如果 stash 恢复发生冲突或拉取失败,stash 会保留下来供手动恢复。
- npm lockfile 变动。 在 stash 或切换分支之前,Kopi Agent 会尽力清理 npm install/build 步骤产生的已跟踪 CODE_1128 差异。如需保留有意的 lockfile 改动,请在运行 CODE_1129 前提交或手动 stash。
- Pairing 数据快照。 即使 CODE_1130 关闭,CODE_1131 仍会在 CODE_1133 前对 CODE_1132 和飞书评论规则创建轻量快照。如果拉取重写了你正在编辑的文件,可用 CODE_1134 回滚。
- 旧版 CODE_1135 警告。 如果 Kopi Agent 检测到重命名前的 CODE_1136 systemd 单元(而非当前的 CODE_1137),会打印一次性迁移提示,以避免 flap-loop 问题。
- 退出码。 成功时返回 CODE_1138,拉取/安装/安装后错误时返回 CODE_1139,出现阻塞 CODE_1141 的意外工作树改动时返回 CODE_1140。
维护命令
| 命令 | 说明 |
|---|---|
| CODE_1142 | 打印版本信息。 |
| CODE_1143 | 拉取最新改动并重新安装依赖。 |
| CODE_1144 | 内部引导命令。在安装脚本配置好 Kopi Agent 后(或在 CODE_1145 之后)运行一次,用于安装 pip 无法提供的非 Python 依赖 — Node.js 运行时、headless 浏览器、ripgrep、ffmpeg — 并在 profile 尚未配置时触发 CODE_1146。可幂等地重复运行。 |
| CODE_1147 | 移除 Kopi Agent,可选择性删除所有 config/数据。CODE_1148 仅移除桌面 Chat GUI,保留 agent 本体;CODE_1149 同时删除 config/数据;CODE_1150 跳过提示。 |