AgentKit CLI内置了灵活的日志系统，帮助您了解命令执行过程、调试问题和追踪运行状态。 ## 默认行为 AgentKit默认配置如下： * ✅ **控制台输出**：关闭（不显示日志） * ✅ **文件日志**：关闭（不记录日志） * 💡 **按需开启**：根据需要通过环境变量开启日志功能 ```Bash # 默认情况下，命令运行时无任何日志输出 agentkit status # 如需日志，请通过环境变量开启（见下文） ``` **日志示例**： ```Bash [2025-11-20 14:56:09] [INFO] [agentkit.toolkit.executors] Loading configuration... [2025-11-20 14:56:09] [INFO] [agentkit.toolkit.executors] Using launch_type: cloud [2025-11-20 14:56:09] [INFO] [agentkit.toolkit.executors] Querying status with cloud strategy... [2025-11-20 14:56:09] [INFO] [agentkit.toolkit.executors] Status query completed: running ``` ## 快速开始 ### 开启文件日志如果需要将日志保存到文件： ```Bash # 开启文件日志（默认 INFO 级别） export AGENTKIT_FILE_ENABLED=true # 运行命令 agentkit deploy # 查看生成的日志文件 cat .agentkit/logs/agentkit-$(date +%Y%m%d).log ``` ### 开启控制台日志如果您想在控制台实时查看日志： ```Bash # 开启控制台日志 export AGENTKIT_LOG_CONSOLE=true # 运行命令，现在可以在控制台看到日志了 agentkit status ``` ### 同时开启控制台和文件日志 ```Bash # 同时开启控制台和文件日志 export AGENTKIT_LOG_CONSOLE=true export AGENTKIT_FILE_ENABLED=true # 运行命令 agentkit build ``` ### 调试模式遇到问题需要详细日志时： ```Bash # 开启 DEBUG 级别日志（自动开启控制台和文件输出） export AGENTKIT_LOG_LEVEL=DEBUG export AGENTKIT_LOG_CONSOLE=true export AGENTKIT_FILE_ENABLED=true # 运行命令，查看详细的调试信息 agentkit build ``` ## 环境变量配置通过环境变量，您可以完全自定义日志行为。 ### 基础配置 |**环境变量** |**说明** |**示例** | |---|---|---| |AGENTKIT_LOG_CONSOLE |是否在控制台显示日志。

取值：

* true

* false（默认值） |true | |AGENTKIT_FILE_ENABLED |是否保存日志到文件。

取值：

* true

* false（默认值） |false | |AGENTKIT_LOG_LEVEL |日志级别（控制台和文件）。

取值：

* DEBUG

* INFO（默认值）

* WARNING

* ERROR |INFO | |AGENTKIT_LOG_FILE |日志文件路径（开启文件日志时生效）

默认路径：`.agentkit/logs/agentkit-YYYYMMDD.log` |/tmp/my\-agent.log | ### 高级配置分别控制控制台和文件的日志级别： |**环境变量** |**说明** |**默认值** | |---|---|---| |AGENTKIT_CONSOLE_LOG_LEVEL |控制台日志级别 |INFO | |AGENTKIT_FILE_LOG_LEVEL |文件日志级别 |INFO | **使用示例**： ```Bash # 控制台只看重要的错误，文件记录所有信息 export AGENTKIT_LOG_CONSOLE=true export AGENTKIT_CONSOLE_LOG_LEVEL=ERROR export AGENTKIT_FILE_LOG_LEVEL=DEBUG agentkit launch ``` ## 日志级别说明 AgentKit 支持 5 种日志级别，级别越高，信息越少： |**级别** |**说明** |**适用场景** | |---|---|---| |DEBUG |详细的调试信息 |问题排查、开发调试 | |INFO |常规操作信息（默认） |了解命令执行过程 | |WARNING |警告信息 |关注潜在问题 | |ERROR |错误信息 |只看失败的操作 | |CRITICAL |严重错误 |只看致命错误 | ## 常用场景 ### 场景 1：正常使用（默认配置）适合日常使用，无日志输出，保护信息安全。 ```Bash # 无需任何配置，直接使用 agentkit status agentkit deploy ``` **效果**： * ✅ 控制台：干净整洁，无日志输出 * ✅ 文件：无日志文件生成，保护信息安全 --- ### 场景 1.1：需要保存日志记录开启文件日志，便于追溯操作历史： ```Bash # 开启文件日志 export AGENTKIT_FILE_ENABLED=true # 运行命令 agentkit deploy ``` **效果**： * ✅ 控制台：干净整洁 * ✅ 日志：自动保存到 .agentkit/logs/，默认 INFO 级别 ### 场景 2：调试问题遇到错误或异常行为时，开启详细日志： ```Bash # 开启控制台和文件的 DEBUG 日志 export AGENTKIT_LOG_CONSOLE=true export AGENTKIT_FILE_ENABLED=true export AGENTKIT_LOG_LEVEL=DEBUG # 运行命令 agentkit build ``` **效果**： * ✅ 控制台：显示详细的执行过程 * ✅ 日志文件：保存完整 DEBUG 信息，便于事后分析 --- ### 场景 3：CI/CD 环境在持续集成环境中，需要在控制台看到日志，同时保存完整记录： ```Bash # 在 CI 配置文件中设置 export AGENTKIT_LOG_CONSOLE=true export AGENTKIT_FILE_ENABLED=true export AGENTKIT_CONSOLE_LOG_LEVEL=INFO export AGENTKIT_FILE_LOG_LEVEL=DEBUG export AGENTKIT_LOG_FILE=/var/log/agentkit/build-${BUILD_ID}.log # 运行构建 agentkit launch ``` **效果**： * ✅ 控制台：显示关键信息，便于查看 CI 日志 * ✅ 日志文件：保存详细信息，便于事后分析 ### 场景 4：生产环境生产环境只记录警告和错误到文件： ```Bash export AGENTKIT_FILE_ENABLED=true export AGENTKIT_FILE_LOG_LEVEL=WARNING export AGENTKIT_LOG_FILE=/var/log/agentkit/production.log # 运行命令 agentkit deploy ``` **效果**： * ✅ 控制台：无输出，保持清爽 * ✅ 日志文件：只记录警告和错误，聚焦问题 ### 场景 5：完全静默不需要任何日志时（默认行为）： ```Bash # 默认配置即为完全静默，无需设置环境变量 agentkit status # 或者显式设置（确保之前的环境变量不影响） unset AGENTKIT_LOG_CONSOLE unset AGENTKIT_FILE_ENABLED ``` **效果**： * ✅ 控制台：无日志输出 * ✅ 文件：无日志文件生成 ## 日志文件管理 ### 日志文件位置当开启文件日志后（AGENTKIT_FILE_ENABLED=true），日志保存在项目根目录的 .agentkit/logs/ 文件夹中： ```Bash your-project/ ├── .agentkit/ │ └── logs/ │ ├── agentkit-20251120.log # 今天的日志 │ ├── agentkit-20251119.log # 昨天的日志 │ └── agentkit-20251118.log # 前天的日志 ├── agentkit.yaml └── my_agent.py ``` ### 自动清理旧日志日志文件会随时间增多，建议定期清理： ```Bash # 删除 7 天前的日志 find .agentkit/logs -name "agentkit-*.log" -mtime +7 -delete # 或者手动删除 rm .agentkit/logs/agentkit-20251101.log ``` ### 自定义日志路径 ```Bash # 保存到指定位置 export AGENTKIT_LOG_FILE=/tmp/my-custom-agent.log # 或保存到用户目录 export AGENTKIT_LOG_FILE=$HOME/.agentkit-logs/agent.log agentkit deploy ``` ## 配置优先级当多种配置方式同时存在时，优先级如下（从高到低）： 1. **专用环境变量：** `AGENTKIT_CONSOLE_LOG_LEVEL` 2. **通用环境变量** ：`AGENTKIT_LOG_LEVEL` 3. **默认值：** `INFO` **示例**： ```Bash # 设置通用级别为 INFO export AGENTKIT_LOG_LEVEL=INFO # 设置控制台专用级别为 WARNING（优先级更高） export AGENTKIT_CONSOLE_LOG_LEVEL=WARNING # 结果：控制台显示 WARNING，文件记录 INFO agentkit status ``` ## 最佳实践 ### 开发环境推荐配置在` .bashrc `或` .zshrc `中添加（可选）： ```Bash # AgentKit 开发环境配置（根据需要选择） # 选项1：只开启控制台日志 export AGENTKIT_LOG_CONSOLE=true # 选项2：同时开启控制台和文件日志 export AGENTKIT_LOG_CONSOLE=true export AGENTKIT_FILE_ENABLED=true export AGENTKIT_CONSOLE_LOG_LEVEL=INFO export AGENTKIT_FILE_LOG_LEVEL=DEBUG ``` **推荐**： * 默认不配置，保持干净 * 需要调试时临时开启 * 避免敏感信息意外记录 ### 团队协作在项目根目录创建 .env.example 文件：

注意

团队成员根据需求自行调整

.env 文件应该在 .gitignore 中，避免提交个人配置

默认不开启文件日志，保护信息安全

```Bash # AgentKit 日志配置示例 # 根据需要复制到 .env 并修改 # === 开发环境建议配置 === # 开启控制台日志（便于实时查看） AGENTKIT_LOG_CONSOLE=true # 开启文件日志（便于问题追溯，可选） # AGENTKIT_FILE_ENABLED=true # 设置日志级别 AGENTKIT_LOG_LEVEL=INFO # 自定义日志路径（可选） # AGENTKIT_LOG_FILE=./logs/my-agent.log ``` ### 生产部署建议 ```Bash # 生产环境配置 export AGENTKIT_LOG_CONSOLE=false # 关闭控制台 export AGENTKIT_FILE_ENABLED=true # 开启文件日志 export AGENTKIT_FILE_LOG_LEVEL=WARNING # 只记录警告和错误 export AGENTKIT_LOG_FILE=/var/log/agentkit/prod.log # 统一路径 ``` **优点**： * 减少不必要的输出 * 聚焦重要问题 * 便于日志管理和监控 ## 总结 AgentKit 的日志系统设计原则： * 🔒 **安全优先** \- 默认不输出日志，避免信息泄露 * 🎯 **按需启用** \- 通过环境变量灵活开启 * 🔧 **灵活配置** \- 控制台和文件可独立控制 * 📊 **分级控制** \- 不同场景使用不同日志级别 * 📁 **自动管理** \- 开启后按日期分割，便于查找 **快速参考**： ```Bash # 1. 开启文件日志 export AGENTKIT_FILE_ENABLED=true # 2. 开启控制台调试 export AGENTKIT_LOG_CONSOLE=true export AGENTKIT_FILE_ENABLED=true export AGENTKIT_LOG_LEVEL=DEBUG # 3. 查看日志文件（需要先开启文件日志） cat .agentkit/logs/agentkit-$(date +%Y%m%d).log # 4. 控制台和文件使用不同级别 export AGENTKIT_LOG_CONSOLE=true export AGENTKIT_FILE_ENABLED=true export AGENTKIT_CONSOLE_LOG_LEVEL=ERROR export AGENTKIT_FILE_LOG_LEVEL=DEBUG ``` 如有问题，请参考[故障排查](https://www.volcengine.com/docs/86681/2153325#M56NQihT)章节或联系技术支持。