跳到主要内容

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 slackSlack 辅助工具(目前:生成包含所有命令作为原生 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 portalKOPI 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 clawOpenClaw 迁移辅助工具。
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 与 /model —— 了解区别

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 模型怎么办?

如果你只配置了 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。

WSL 用户

请使用 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 保留或输入新值。没有菜单。

也可以直接进入某一节,而不运行完整向导:

节描述
modelProvider 和模型设置。
terminal终端后端和沙箱设置。
gateway消息平台设置。
tools按平台启用/禁用工具。
agentAgent 行为设置。

选项:

选项描述
--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 会提示重新安装。

FlagDefaultPurpose
--write [PATH]stdout写入文件而非 stdout。单独的 --write 会写入 $KOPI_HOME/slack-manifest.json。
--name NAMEKopi AgentSlack 中的机器人显示名称。
--description DESCdefault blurb在 Slack app 目录中显示的机器人描述。
--slashes-onlyoff仅输出 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。

OptionDescription
-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)子命令:

SubcommandDescription
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 跳过)。

SubcommandDescription
xai扫描 config.yaml 中对计划于 2026 年 5 月 15 日退役的 xAI 模型的引用,并(使用 --apply)按照 xAI 迁移指南就地重写为官方替代项。默认为 dry-run。

迁移子命令的通用 flag:

FlagDescription
--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。

SubcommandDescription
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 标志:

标志默认值描述
--jsonoff输出机器可读的 JSON,而非人类可读的文本。
--fail-on <level>critical当任何发现的严重程度达到该级别时以非零状态退出(low、moderate、high、critical)。
--skip-venvoff跳过扫描 Kopi Agent Python venv。
--skip-pluginsoff跳过扫描插件 requirements 文件。
--skip-mcpoff跳过扫描 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。

包含哪些内容​

部分详情
HeaderKopi 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网关状态、已配置的消息平台
WorkloadCron 任务数量、已安装的 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 与之等效。
liststatus 的别名。
prune强制执行清理扫描 —— 删除孤立和过期项目、对存储执行 GC、强制执行大小上限。忽略 24 小时幂等标记。
clear删除整个 checkpoint 基础。不可逆;除非使用 -f,否则会要求确认。
clear-legacy仅删除由 v1→v2 迁移产生的 legacy-<timestamp>/ 归档。

选项​

选项子命令说明
--limit Nstatus, list最多列出的项目数(默认 20)。
--retention-days Nprune删除 last_touch 早于 N 天的项目(默认 7)。
--max-size-mb Nprune在孤立/过期项目清理之后,逐个项目删除最旧的 commit,直到总存储大小 ≤ N MB(默认 500)。
--keep-orphansprune跳过删除工作目录已不存在的项目。
-f, --forceclear, 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 及以上级别)
errorserrors.log仅警告和错误 —— agent.log 的过滤子集
gatewaygateway.log消息网关活动 —— 平台连接、消息分发、webhook 事件
guigui.logDashboard / TUI 网关 / PTY 桥接 / websocket 事件
desktopdesktop.logElectron 桌面应用 —— 启动、后端进程输出以及最近的 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)://…/*.md URL 会直接安装单文件 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移除所有回退条目

参见 Fallback Providers。

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(仅使用内置记忆)。
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_1059CODE_1060运行 web 服务器的端口
CODE_1061CODE_1062绑定地址
CODE_1063—不自动打开浏览器
CODE_1064off已弃用 / 无效操作。 此前用于在非 loopback 绑定时绕过认证。自 2026 年 6 月的安全加固起,公开绑定始终需要 auth provider(密码或 OAuth)。请绑定 CODE_1065 并通过隧道访问,以保持本地化。
CODE_1066off跳过 web UI 构建步骤,直接提供现有的 CODE_1067。适用于没有 npm 的非交互式环境(Windows 计划任务、CI)。请用 CODE_1068 预先构建。
CODE_1069off从命名 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_1079dashboard 的人类可读标签(默认:自动生成)。
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 跳过提示。

另请参阅​