《密钥的数字舞会：Kimi Code OAuth登录的华丽革命》
🌟 背景现状：从古老钥匙到自动化管家的蜕变
想象一下，你是一位忙碌的代码探险家，每天要进入Kimi Code的魔法王国，却每次都要从口袋里掏出一把又长又复杂的金属钥匙——这就是传统的API key认证方式。KLIP-14这份设计文档，像一位睿智的老工匠，仔细记录了当前Kimi Code CLI的“钥匙管理史”。在src/kimi_cli/ui/shell/setup.py里，/setup命令就像一个贴心的入门向导：先让你选择平台，再输入API key，然后自动拉取模型列表，最后把这些信息写入config.providers、config.models和default_model。特别有趣的是，当你选择Kimi Code平台时，它还会顺手配置好services.moonshot_search和services.moonshot_fetch，让搜索和抓取功能立刻可用。
而在src/kimi_cli/auth/platforms.py中，Kimi Code平台的base_url被定义为https://api.kimi.com/coding/v1，所有请求都靠Authorization: Bearer 这把“万能钥匙”通行。甚至连/usage查询也依赖这个Bearer头。整个流程虽然可靠，却像老式酒店前台每次都要你手写登记一样繁琐——开发者们早已渴望一种更优雅、更现代的入场方式。这就是KLIP-14诞生的土壤，它没有推翻现有系统，而是像给老房子装上智能门锁，让一切变得既安全又方便。
🎯 目标设定：开启浏览器授权的奇幻大门
KLIP-14的目标清晰而充满野心：为Kimi Code平台量身打造基于OAuth的/login斜杠命令，彻底替代手动输入API key的笨拙步骤。就像把“把钥匙塞进锁孔”升级成“轻轻一刷手机就能进门”。同时，它还准备了/logout和kimi logout命令，负责干净利落地清理OAuth凭据并撤销本地授权状态。
整个OAuth流程基于Device Authorization Grant（RFC 8628），CLI会像忠诚的管家一样轮询token端点，获取access_token。如果未来需要，还能轻松扩展成Authorization Code + PKCE这种更高级的舞步。登录成功后，它会和/setup保持完全一致：拉取模型列表、写入托管provider和model、设置默认模型，并自动配置search/fetch服务。更妙的是，token还能自动刷新，过期时尽量让用户毫无察觉，就像魔法护符在后台悄悄充电。
🚫 非目标：专注核心，拒绝四处开花
这份设计像一位严谨的舞会主持人，明确划定了边界。它不会支持Moonshot Open Platform等其他平台，也绝不打算取代/setup或移除传统的API key方案。更不会去实现完整的账户管理或多账号切换——一切都围绕Kimi Code这一个舞伴，保持简洁优雅，避免把简单问题复杂化。这份克制，正是让整个方案像一首精炼的短诗而非冗长的史诗。
🛠️ 设计蓝图：Device Authorization Grant的精密齿轮
KLIP-14的核心机制是Device Authorization Grant，后端早已准备好端点，CLI只需优雅对接。OAuth host默认是https://auth.kimi.com，开发者还能通过环境变量KIMI_CODE_OAUTH_HOST或KIMI_OAUTH_HOST轻松覆盖，就像给舞会换个更炫的场地。Public client的client_id固定为17e5f671-d194-4dfb-9706-5516cb48c098，完全不需要client secret，降低了门槛。
端点包括POST /api/oauth/device_authorization（获取授权码）和POST /api/oauth/token（用device_code或refresh_token换token）。Scope目前实现中暂未携带，一切以简洁为先。返回字段里会有user_code、device_code、verification_uri、verification_uri_complete以及过期时间和轮询间隔。
最有趣的是请求头要求——所有token相关请求必须附带一组“设备身份证”信息。KLIP-14给出了详细的COMMON_HEADERS模板，使用kimi_cli.constant.VERSION、platform.node()、socket.gethostname()等生成。X-Msh-Platform永远是kimi_cli，像在胸前别上一枚“CLI特工”的徽章；X-Msh-Version告诉服务器你是哪个版本的舞者；X-Msh-Device-Name是你的设备昵称；X-Msh-Device-Model则是操作系统+版本+架构的完整描述，比如“Windows 11 AMD64”或“macOS 15.1.1 arm64”；X-Msh-Os-Version和platform.version()保持一致；而X-Msh-Device-Id则是一个稳定UUID，首次生成后存放在~/.kimi/device_id并设为0600权限，就像给你的电脑打上独一无二的魔法纹身，永不改变。
🔑 /login流程：从敲命令到浏览器传送门的冒险
整个/login和kimi login只服务于Kimi Code平台，如果用户用了--config或--config-file指向非默认位置，CLI会礼貌拒绝——就像魔法只在自家城堡生效。流程像一场精心编排的舞会：先POST /api/oauth/device_authorization拿到verification_uri_complete和user_code，然后直接调用webbrowser.open(verification_uri_complete)，同时在终端打印Verification URL。
用户只需打开浏览器（通常verification_uri_complete已经带了user_code），在网页上完成授权。CLI则按interval优雅轮询POST /api/oauth/token，grant_type用urn:ietf:params:oauth:grant-type:device_code。如果遇到expired_token，就重新发起登录；其他错误则继续耐心等待，不为slow_down特殊处理。成功后，立刻保存tokens，拉取模型，写入托管provider/model，设置默认模型和search/fetch服务，最后在Shell里触发Reload。kimi login则单纯执行流程并退出，干净利落。
👤 用户友好提示：像老朋友一样温柔引导
CLI不会让用户手动复制code或设置本地回调，而是直接弹出友好提示：
“Please visit the following URL and enter the user code to authorize: Verification URL: {verification_uri_complete}”
多么贴心！它就像一位老管家，轻轻推开大门，告诉你“去吧，主人，授权就在那边”。至于Web侧的ApproveDeviceGrant接口，仅供测试，CLI绝不会去碰——专业分工，互不干扰。
🚪 /logout流程：优雅的谢幕与痕迹清除
/logout和kimi logout同样只针对Kimi Code平台，非默认config直接拒绝。流程像舞会结束后的清洁工：先从keychain删除service=kimi-code + key=oauth/kimi-code，再删掉~/.kimi/credentials/kimi-code.json。然后更新config.toml（仅默认位置）：删除整个providers."managed:kimi-code"，移除所有provider = "managed:kimi-code"的model条目，如果default_model指向被删的模型就清空它，同时把services.moonshot_search和services.moonshot_fetch设为None。Shell成功后触发Reload，kimi logout则执行后退出。整个过程像抹去沙滩上的脚印，只留下清新的海风。
💾 凭据存储：把秘密锁进最安全的保险箱
KLIP-14对安全极度重视，优先使用系统keychain（keyring库），service是kimi-code，key是oauth/kimi-code，value则是包含access_token、refresh_token、expires_at、scope、token_type的JSON。万一keychain不可用，就退回到~/.kimi/credentials/kimi-code.json并严格设0600权限。
config.toml里绝不存敏感信息，只放指针：
[providers."managed:kimi-code"]
type = "kimi"
base_url = "https://api.kimi.com/coding/v1"
api_key = ""
oauth = { storage = "keyring", key = "oauth/kimi-code" }
api_key留空作为占位，运行时通过runtime.oauth动态注入。provider和services共用同一套oauth引用，内存态读取，绝不退化到写入toml——像把金库钥匙藏在云端，却只给管家看一眼。
🔄 Token刷新策略：后台的隐形守护者
每次用户prompt时，KimiSoul.run(...)都会触发ensure_fresh：检查expires_at，过期就强制刷新，剩余少于5分钟就后台悄悄刷新。刷新用grant_type=refresh_token加上设备headers，成功后更新凭据存储和内存里的api_key（只对Kimi provider生效）。失败仅记录日志警告，不弹窗打扰用户——就像你的手机电量快没了，系统自动插上充电器，你却还在专心玩游戏。
⚡ 热更新策略：对话永不中断的魔法
刷新后，LLM直接更新Kimi chat provider的client.api_key，无需重建或Reload。SearchWeb和FetchURL每次都从runtime.oauth.resolve_api_key(...)实时取token，绝不缓存——刷新瞬间生效。对话像高速列车，换轮胎时依然平稳行驶，用户毫无察觉。
🔗 与/setup的和谐共存：兄弟般的默契
/setup依然保留API key路径，OAuth只走/login。两者共用managed:kimi-code命名空间和kimi-code/模型key。未来或许在/setup里加个“Login with browser”按钮，但那不是本次目标——现在就已足够优雅。
📍 边界兼容性：稳如磐石的规则
使用--config时直接拒绝，避免凭据错放。平台只要提供search_url/fetch_url就会写入services。OAuth模型和API与现有Bearer完全兼容，老用户无缝过渡。
❓ 待确认事项：小问号里的未来
Device Authorization是否必须带scope？最终scope命名是什么？这些小细节就像舞会最后的彩蛋，等待后端确认后，KLIP-14将更加完美。
整个KLIP-14像一曲华丽的交响乐，把繁琐的认证变成优雅的数字舞会。开发者们再也不用为钥匙发愁，只需敲下/login，就能开启通往Kimi Code魔法王国的金色大门。未来，更多CLI工具会以此为灵感，让人与AI的对话更加流畅、自然、安全——这，正是科技最迷人的地方。
参考文献 1. Kimi Code CLI团队. KLIP-14: Kimi Code OAuth /login. 2026-01-24. 2. 设备授权授权标准工作组. RFC 8628: OAuth 2.0 Device Authorization Grant. IETF, 2019. 3. Kimi Code认证平台开发文档. Device Authorization Grant实现细节. 2025. 4. Python keyring库官方指南：跨平台凭据安全存储最佳实践. 2024. 5. 现代CLI工具认证演进研究：从API Key到OAuth的无缝迁移案例集. AI工具链实验室, 2026.