Operations

运维与排障

正常启动

1. 启动 CCProxy-Agent-v0.4.92.exe。
2. 代理读取 EXE 同目录配置。
3. 选择监听端口并发现上游。
4. HTTP Server 监听成功后接管 Claude Code/Desktop。
5. GUI 显示代理地址、上游来源、Patch 和 Vision 状态。

正常关闭

从 GUI 停止代理或关闭窗口。程序会停止漂移监控、恢复 Claude 配置、关闭连接后退出。不要把任务管理器强杀作为日常关闭方式。

常见问题

启动一直加载

• 查看 GUI Notice 和日志中的首个错误。
• 检查首选端口是否被旧进程占用。
• 检查 config.json 是否为有效 JSON。
• 检查 CC Switch 是否已经启动。

请求返回 context length 400

• 确认日志是否出现 tool result clearing 或 context retry。
• 如果已经重试一次仍失败，先在 Claude 执行 /compact 或开启新会话。
• 检查最近是否有单条异常巨大的工具输出。

Claude 重复 Read/Bash

• 查看 Hook Observer 中 repeated calls 和 truncated results。
• 确认使用 v0.4.92，旧版本可能完全清除最新工具结果。
• 缩小工具查询范围，例如按文件或行段读取。

Desktop 切换配置后不走代理

• 等待一个 watcher 间隔。
• 查看是否记录 appliedId changed 或 gateway drift。
• 手动 Restart Proxy 会重新执行 Patch。

日志与记录

• 主日志：logs/ccproxy-agent.log。
• 最近归档：logs/ccproxy-agent.log.1。
• 请求保护记录：runtime/sessions/<requestId>.json。
• 日志内存环形缓冲：最近 1000 条。

请求记录保存预算、恢复标记和 Vision 使用情况，不保存完整请求正文。当前 session 文件没有自动保留天数限制，长期运行应定期清理；自动 retention 属于生产级路线图。

健康状态说明

v0.4.92 的 GUI Health 更接近运行摘要，不是严格 readiness probe。显示 Upstream OK 不代表刚刚完成了真实模型调用；严格状态机见 Production-Roadmap。