日志系统
AgentKit CLI 内置了灵活的日志系统，帮助你了解命令执行过程、调试问题和追踪运行状态。
默认行为
AgentKit 默认配置如下：
- ✅ 控制台输出：关闭（不显示日志）
- ✅ 文件日志：关闭（不记录日志）
- 💡 按需开启：根据需要通过环境变量开启日志功能
bash
# 默认情况下，命令运行时无任何日志输出
agentkit status
# 如需日志，请通过环境变量开启（见下文）日志示例：
[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 | 是否在控制台显示日志 | false | true / false |
AGENTKIT_FILE_ENABLED | 是否保存日志到文件 | false | true / false |
AGENTKIT_LOG_LEVEL | 日志级别（控制台和文件） | INFO | DEBUG / INFO / WARNING / ERROR |
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/ 文件夹中：
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配置优先级
当多种配置方式同时存在时，优先级如下（从高到低）：
- 专用环境变量 -
AGENTKIT_CONSOLE_LOG_LEVEL - 通用环境变量 -
AGENTKIT_LOG_LEVEL - 默认值 -
INFO
示例：
bash
# 设置通用级别为 INFO
export AGENTKIT_LOG_LEVEL=INFO
# 设置控制台专用级别为 WARNING（优先级更高）
export AGENTKIT_CONSOLE_LOG_LEVEL=WARNING
# 结果：控制台显示 WARNING，文件记录 INFO
agentkit status故障排查
日志文件没有创建
可能原因：
- 文件日志被禁用了
- 目录权限不足
解决方法：
bash
# 1. 检查是否禁用了文件日志
echo $AGENTKIT_FILE_ENABLED # 应该是 true 或为空
# 2. 检查目录权限
ls -la .agentkit/logs/
# 3. 手动创建目录
mkdir -p .agentkit/logs
# 4. 确保环境变量正确
unset AGENTKIT_FILE_ENABLED # 重置为默认值控制台没有日志输出
可能原因：
- 控制台日志默认是关闭的
- 日志级别设置过高
解决方法：
bash
# 1. 开启控制台日志
export AGENTKIT_LOG_CONSOLE=true
# 2. 设置合适的日志级别
export AGENTKIT_CONSOLE_LOG_LEVEL=INFO
# 3. 运行命令
agentkit status日志太多或太少
调整日志级别：
bash
# 日志太多 - 只看重要信息
export AGENTKIT_LOG_LEVEL=WARNING
# 日志太少 - 查看详细信息
export AGENTKIT_LOG_LEVEL=DEBUG最佳实践
开发环境推荐配置
在你的 .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 文件：
bash
# AgentKit 日志配置示例
# 根据需要复制到 .env 并修改
# === 开发环境建议配置 ===
# 开启控制台日志（便于实时查看）
AGENTKIT_LOG_CONSOLE=true
# 开启文件日志（便于问题追溯，可选）
# AGENTKIT_FILE_ENABLED=true
# 设置日志级别
AGENTKIT_LOG_LEVEL=INFO
# 自定义日志路径（可选）
# AGENTKIT_LOG_FILE=./logs/my-agent.log提醒：
- 团队成员根据需求自行调整
.env文件应该在.gitignore中，避免提交个人配置- 默认不开启文件日志，保护信息安全
生产部署建议
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如有问题，请参考 故障排查 章节或联系技术支持。