kimi-cli Web 配置接口详解UpdateConfigTomlResponse 响应模型与 config.toml 在线更新机制【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-clikimi-cli 内置的 Web 服务提供了一套以config.toml为核心的配置管理 REST API。UpdateConfigTomlResponse是该 API 中更新 config.toml接口PUT /api/config/toml的响应模型本文以 UpdateConfigTomlResponse.md 为骨架结合请求模型、同组接口与后端源码完整讲解如何通过 Web 面板在线读写 kimi-cli 的config.toml以及前端 TypeScript 调用方如何处理其返回结果。响应模型概览UpdateConfigTomlResponseUpdateConfigTomlResponse是 kimi-cli Web 后端在收到config.toml更新请求后返回给前端的数据结构定义在 web/src/lib/api/docs/UpdateConfigTomlResponse.md 中其语义为更新 config.toml 之后的响应Response after updating config.toml。字段说明名称类型含义successboolean更新是否成功errorstring失败时的错误信息该模型只有两个字段success用于标记整体更新结果error用于在失败时携带可读的错误消息。从后端实现看src/kimi_cli/web/api/config.pyerror是一个可选字段仅在失败时填充成功时响应体形如{success: true}class UpdateConfigTomlResponse(BaseModel): Response after updating config.toml. success: bool Field(descriptionWhether the update was successful) error: str | None Field(defaultNone, descriptionError message if failed)响应示例TypeScriptUpdateConfigTomlResponse.md给出了一个 TypeScript 调用示例骨架展示了如何用类型声明、序列化与反序列化来消费该模型import type { UpdateConfigTomlResponse } from // TODO: Update the object below with actual values const example { success: null, error: null, } satisfies UpdateConfigTomlResponse console.log(example) // Convert the instance to a JSON string const exampleJSON: string JSON.stringify(example) console.log(exampleJSON) // Parse the JSON string back to an object const exampleParsed JSON.parse(exampleJSON) as UpdateConfigTomlResponse console.log(exampleParsed)实践中前端可直接用satisfies做静态类型校验真实调用时success应为布尔值error应为字符串或null。请求模型UpdateConfigTomlRequest与响应模型配套的请求模型是 UpdateConfigTomlRequest.md其字段仅有一个名称类型含义contentstring新的完整 TOML 内容即前端通过PUT /api/config/toml提交整份config.toml文本而非增量补丁。后端对应实现src/kimi_cli/web/api/config.pyclass UpdateConfigTomlRequest(BaseModel): Request to update config.toml. content: str Field(descriptionNew TOML content)该设计意味着任何保存操作都必须先在客户端取得当前完整内容通过GET /api/config/toml修改后整体回传。接口调用链ConfigApi 中的 PUT /api/config/tomlUpdateConfigTomlResponse是 ConfigApi.md 中updateConfigTomlApiConfigTomlPut方法的返回类型。ConfigApi 是前端生成的 OpenAPI 客户端包含四个与配置相关的端点方法HTTP 请求描述getConfigTomlApiConfigTomlGetGET/api/config/toml获取 kimi-cli config.tomlgetGlobalConfigApiConfigGetGET/api/config/获取全局kimi-cli配置快照updateConfigTomlApiConfigTomlPutPUT/api/config/toml更新 kimi-cli config.tomlupdateGlobalConfigApiConfigPatchPATCH/api/config/更新全局默认模型/思考模式前端调用示例TypeScriptimport { Configuration, ConfigApi, } from ; import type { UpdateConfigTomlApiConfigTomlPutRequest } from ; async function example() { console.log( Testing SDK...); const api new ConfigApi(); const body { // UpdateConfigTomlRequest updateConfigTomlRequest: { content: # kimi-cli config default_model kimi-k2 default_thinking true , }, } satisfies UpdateConfigTomlApiConfigTomlPutRequest; try { const data await api.updateConfigTomlApiConfigTomlPut(body); console.log(data); // { success: true } 或 { success: false, error: ... } } catch (error) { console.error(error); } } // Run the test example().catch(console.error);生成的客户端实现位于 web/src/lib/api/apis/ConfigApi.ts其调用链为updateConfigTomlApiConfigTomlPut→updateConfigTomlApiConfigTomlPutRaw先校验updateConfigTomlRequest参数非空再通过UpdateConfigTomlRequestToJSON将请求体序列化为 JSON最后发出PUT请求并反序列化响应为UpdateConfigTomlResponse。接口契约要点Content-Type:application/jsonAccept:application/json授权: 无需鉴权No authorization required成功状态码:200Successful Response失败状态码:422Validation Error请求体不符合模型校验时返回返回类型: UpdateConfigTomlResponse需要注意422表示 HTTP 层请求体校验失败与success: false的业务失败是两回事——后者发生在200响应体内。后端实现原理校验-落盘-结果返回UpdateConfigTomlResponse的生成逻辑在 src/kimi_cli/web/api/config.py 的update_config_toml路由中核心流程分三步router.put(/toml, summaryUpdate kimi-cli config.toml) async def update_config_toml( request: UpdateConfigTomlRequest, http_request: Request, ) - UpdateConfigTomlResponse: Update kimi-cli config.toml. from kimi_cli.config import load_config_from_string _ensure_sensitive_apis_allowed(http_request) try: # Validate the config first load_config_from_string(request.content) # Write to file config_file get_config_file() config_file.parent.mkdir(parentsTrue, exist_okTrue) config_file.write_text(request.content, encodingutf-8) return UpdateConfigTomlResponse(successTrue) except Exception as e: logger.warning(fFailed to update config.toml: {e}) return UpdateConfigTomlResponse(successFalse, errorstr(e))权限闸门_ensure_sensitive_apis_allowed检查 Web 服务是否处于restrict_sensitive_apis受限模式src/kimi_cli/web/api/config.py。若受限则直接抛出403 Forbidden不允许通过 Web 修改配置。先校验后落盘先调用load_config_from_string(request.content)解析并验证 TOML 内容是否合法校验通过后才写入get_config_file()指向的配置文件不存在时自动创建父目录。这种先验证、再写入的顺序避免了把非法 TOML 写进磁盘导致 CLI 启动失败。结果返回写入成功返回UpdateConfigTomlResponse(successTrue)任何解析或写盘异常都会被捕获返回UpdateConfigTomlResponse(successFalse, errorstr(e))同时以logger.warning记录告警日志。读取侧GET /api/config/toml 与 ConfigToml更新前通常需要先读取当前配置GET /api/config/toml返回 ConfigToml.md 模型名称类型含义contentstring原始 TOML 内容pathstring配置文件路径后端实现src/kimi_cli/web/api/config.py在配置文件不存在时返回空content与目标路径方便前端在首次配置时初始化内容。典型的前端读-改-写闭环即GET /api/config/toml→ 编辑器修改content→PUT /api/config/toml整体回传。与 GlobalConfig 的协作关系与UpdateConfigTomlResponse同组的PATCH /api/config/返回 UpdateGlobalConfigResponse.md提供了结构化修改入口可只更新default_model/default_thinking并支持restart_running_sessions、force_restart_busy_sessions选项来决定是否重启运行中的会话以生效src/kimi_cli/web/api/config.py。两者定位互补UpdateConfigTomlResponse 场景适合 Web 前端提供config.toml 原文编辑器文本级、全量覆盖例如高级用户手写 TOML 配置UpdateGlobalConfigResponse 场景适合提供表单化的默认模型/思考模式快速设置字段级、结构化更新并联动会话重启。前端调用方可根据success字段决定 UI 反馈成功时提示保存完成失败时将error消息直接展示给用户帮助其定位 TOML 语法错误或路径权限问题。小结UpdateConfigTomlResponse虽然只有success与error两个字段却完整承载了 kimi-cli Web 端更新 config.toml这一能力的结果语义。理解它需要串联三层前端 OpenAPI 客户端web/src/lib/api/apis/ConfigApi.ts、请求/响应模型UpdateConfigTomlRequest.md 与 UpdateConfigTomlResponse.md、以及后端路由实现src/kimi_cli/web/api/config.py。在 Web 面板中集成配置编辑功能时按读取 ConfigToml → 编辑 content → PUT 回传 → 依据 success/error 反馈结果的流程即可安全完成 kimi-cli 的在线配置管理。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考