Kimi Code CLI 常见问题排查指南从登录鉴权到更新升级的完整实战手册【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli导读本文基于 Kimi Code CLI 官方 FAQ 文档系统梳理了这款 CLI Agent 工具从安装登录、日常交互、ACP/MCP 集成到版本更新升级过程中最常遇到的故障场景与解决方案。你将掌握/login空模型列表、API Key 失效、shell 模式下cd不生效、图片粘贴失败、MCP 服务器连接与 OAuth 授权、--print无输出等高频问题的根因分析与修复步骤并学会通过kimi mcp list/test/auth/reset-auth、kimi --work-dir、KIMI_CLI_NO_AUTO_UPDATE等命令与环境变量从根源上规避问题。安装与认证问题/login时模型列表为空执行/login或/setup命令时如果看到 No models available for the selected platform 错误通常源于以下两类原因API Key 无效或已过期请先确认你的 Key 是否正确且仍然有效。可以在平台控制台重新生成一个 Key 再试。网络连接异常确认本机可以访问 Kimi 的 API 服务地址例如api.kimi.com或api.moonshot.cn。如果你处于代理或防火墙环境需要确保这些域名已被放行。从源码结构看Kimi Code CLI 在登录时通过 auth/platforms.py 拉取平台模型列表其中supports_image_in等能力字段会被转换成模型 capabilities如image_in再据此构建可用的模型候选集。因此当请求失败或返回为空时界面就会提示没有可用模型。API Key 无效API Key 报Invalid无效可能有以下几种情况输入错误检查 Key 中是否混入了多余空格或漏掉了字符。Key 已过期或被吊销到平台控制台确认该 Key 的状态。环境变量覆盖检查KIMI_API_KEY或OPENAI_API_KEY环境变量是否覆盖了配置文件中的 Key。可运行以下命令确认echo $KIMI_API_KEY关于环境变量覆盖配置文件的详细机制可参考 环境变量文档 与 配置覆盖文档。例如KIMI_API_KEY用于覆盖 provider 配置中的api_key字段常用于 CI/CD 场景中免改配置注入密钥。会员过期或配额耗尽如果你使用的是 Kimi Code 平台可以通过/usage命令查看当前配额与会员状态。从 usage.py 的实现可以看到/usage别名/status会拉取 API 使用量与配额信息并以面板形式展示已用量、上限和重置提示当模型配置不属于 Kimi Code 平台时会提示 Usage is available on Kimi Code platform only.。若配额耗尽或会员过期需要在 Kimi Code 平台续费或升级。交互问题shell 模式下cd命令不生效在 shell 模式中执行cd不会改变 Kimi Code CLI 的工作目录。原因是每条 shell 命令都在独立的子进程中执行目录切换只对当前进程生效。如需切换工作目录有三种方式退出后重新启动在目标目录下重新运行kimi。使用--work-dir参数启动时指定工作目录如kimi --work-dir /path/to/project。从 cli/init.py 可以看到该参数的定义与解析逻辑最终会通过KaosPath创建会话工作目录。在命令中使用绝对路径直接执行带绝对路径的命令如ls /path/to/dir。另外shell 工具文档 建议在单次调用中需要用串联多个相关命令例如cd /path ls -la因为每次工具调用也是独立子进程这进一步印证了上述设计。图片粘贴失败使用Ctrl-V粘贴图片时如果出现 Current model does not support image input说明当前模型不支持图片输入。解决方案切换到支持图片的模型换用具备image_in能力的模型。从 soul/message.py 可以看到消息组装时会根据内容自动检测所需能力并加入image_in模型能力在 llm.py 中定义为image_in、video_in、thinking、always_thinking等字面量。检查剪贴板内容确保剪贴板中确实是图片数据而不是图片的文件路径。工作目录被删除或移除如果会话期间工作目录变得不可访问例如外部硬盘被拔出、目录被删除或文件系统被卸载Kimi Code CLI 会检测到该情况显示包含会话 ID 和工作目录路径的崩溃报告然后干净退出。你可以在正确的目录下用kimi -r session-id恢复该会话。ACP 问题IDE 无法连接 Kimi Code CLI如果 IDE如 Zed、JetBrains 系列无法连接到 Kimi Code CLI请依次检查确认 Kimi Code CLI 已安装运行kimi --version验证。检查配置路径确认 IDE 配置中 Kimi Code CLI 的路径正确通常可使用kimi acp作为命令。检查 uv 路径若通过 uv 安装请确保~/.local/bin在 PATH 中也可使用绝对路径如/Users/yourname/.local/bin/kimi acp。查看日志检查~/.kimi/logs/kimi.log中的错误信息。ACP 相关协议细节可参考 ACP 文档 与 ACP 集成说明。MCP 问题MCP 服务器启动失败添加 MCP 服务器后工具未加载或出现报错可能的原因命令不存在对于 stdio 类型的服务器确保命令如npx在 PATH 中可配置为绝对路径。配置格式错误检查~/.kimi/mcp.json是否为合法 JSON。运行kimi mcp list查看当前配置。调试步骤# 查看已配置的服务器 kimi mcp list # 测试服务器是否可用 kimi mcp test server-name从 cli/mcp.py 的实现看kimi mcp test会通过 fastmcp 客户端建立连接并列出可用工具含工具名称与描述连接失败时会打印异常类型与错误信息方便定位问题。OAuth 授权失败对于需要 OAuth 授权的 MCP 服务器如 Linear若授权失败检查网络连接确保可以访问授权服务器。重新授权运行kimi mcp auth server-name重新授权。源码中该命令会打开浏览器进行授权成功后回显可用的工具数量见 cli/mcp.py。重置授权若授权信息损坏运行kimi mcp reset-auth server-name清除缓存的 token 后重试。该命令通过create_mcp_oauth_token_storage(server[url])定位并清空对应服务器的 OAuth token 存储见 cli/mcp.py。需要说明的是只有以--auth oauth方式添加的远程服务器才支持这些操作未启用 OAuth 的服务器执行mcp auth会直接报错提示 does not use OAuth。Header 格式错误添加 HTTP 类型 MCP 服务器时header 格式应为KEY: VALUE冒号后带一个空格。例如# 正确写法 kimi mcp add --transport http context7 https://mcp.context7.com/mcp --header CONTEXT7_API_KEY: your-key # 错误写法缺少空格或使用等号 kimi mcp add --transport http context7 https://mcp.context7.com/mcp --header CONTEXT7_API_KEYyour-keyPrint/Wire 模式问题JSONL 输入格式无效使用--input-format stream-json时输入必须是合法的 JSONL每行一个 JSON 对象。常见问题JSON 格式错误确保每行都是完整的 JSON 对象且无语法错误。编码问题确保输入使用 UTF-8 编码。换行符问题Windows 用户需确认换行符为\n而非\r\n。正确的输入格式示例{role: user, content: Hello}从 cli/init.py 可以看到输入/输出格式被定义为text与stream-json两种字面量stream-json模式下输入支持多轮对话。Print 模式无输出--print模式没有输出的可能原因未提供输入需要通过--prompt或--command或 stdin 提供输入例如kimi --print --prompt Hello。输出被缓冲尝试使用--output-format stream-json获取流式输出。配置不完整确保已通过/login完成 API Key 与模型的配置。更新与升级macOS 首次启动缓慢macOS 的 Gatekeeper 安全机制会在首次运行时检查新程序导致启动缓慢。解决方案耐心等待检查完成首次运行后后续启动会恢复正常。加入开发者工具在系统设置 → 隐私与安全性 → 开发者工具中添加你的终端应用。如何升级 Kimi Code CLI使用 uv 升级到最新版本uv tool upgrade kimi-cli --no-cache添加--no-cache确保获取到最新版本。从 ui/shell/update.py 的实现看CLI 内置了独立的自动更新逻辑通过_get_latest_version拉取最新版本号下载对应平台x86_64/aarch64与apple-darwin/unknown-linux-gnu的 tar.gz 压缩包解压后安装到~/.local/bin/kimi。默认升级命令常量UPGRADE_COMMAND即为uv tool upgrade kimi-cli。启动时的更新提示后台检查检测到新版本时Kimi Code CLI 会在 shell 加载前显示阻塞式更新提示展示当前版本与最新版本信息。你可以用以下按键选择操作Enter立即升级到最新版本q暂时跳过下次启动时会再次提醒s跳过该版本并抑制后续提醒直到有更新的版本发布从 update.py 的check_update_gate实现可以看出该提示仅在交互式终端stdin/stdout 均为 TTY且本地缓存了更新的版本号时触发按s会把版本号写入skipped_version.txt位于 share 目录从而屏蔽同版本的重复提醒。如何禁用更新提醒如果不想让 Kimi Code CLI 检查更新或在启动时显示更新提示可设置环境变量export KIMI_CLI_NO_AUTO_UPDATE1这会在后台检查更新、启动时的阻塞式更新提示以及欢迎面板中的版本提示全部禁用。建议将该行加入 shell 配置文件如~/.zshrc或~/.bashrc。根据 环境变量文档当该变量设为1、true、t、yes或y不区分大小写时即生效如果通过 Nix 等包管理器安装该变量通常会由包管理器自动设置因为更新交由包管理器处理。check_update_gate中正是通过get_env_bool(KIMI_CLI_NO_AUTO_UPDATE)来短路整个更新门控逻辑。小结Kimi Code CLI 的绝大多数常见问题都可以归纳为四类根因配置/凭据错误API Key、环境变量覆盖、模型能力不匹配、环境差异PATH 不完整、子进程隔离、网络受限、集成协议问题ACP/MCP 的传输、header 与 OAuth 配置以及版本管理更新门控、环境变量抑制。本文涉及的每个问题都对应了可复现的排查路径与源码依据更多细节可继续查阅 FAQ 英文原文档、环境变量文档、配置覆盖文档、ACP 文档 以及 MCP 文档按图索骥即可快速定位并解决实际使用中遇到的故障。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考