一个网关搞定所有AI编程助手:Context Gateway多Agent接入实战(Claude Code/Cursor/Codex/OpenClaw)
一个网关搞定所有AI编程助手:Context Gateway多Agent接入实战(Claude Code/Cursor/Codex/OpenClaw)
Context Gateway 是 Compresr 出品的开源 AI Agent 代理网关(agentic proxy),在 AI 编程助手与 LLM API 之间做一层透明转发,提供后台历史压缩(History Compaction)与上下文优化工具。一个网关即可同时接入 Claude Code、Cursor、Codex、OpenClaw 等主流 Agent,长对话不再等待压缩、上下文成本显著下降。
💡 为什么需要 Context Gateway?
AI 编程助手都有"上下文焦虑":
- 对话越长,上下文占用越高,费用跟着水涨船高;
- 触发 compaction(压缩)时,Agent 卡住等待,体验断档;
- 工具输出(读文件、执行命令的结果)动辄几万 token,白白吃占上下文。
Context Gateway 的做法是把 Agent 的请求指向本地网关(默认端口 18081),由它拦截并完成三件事:
| 核心能力 | 作用 | 说明文档 |
|---|---|---|
| ⚡ Preemptive Summarization | 后台预先计算历史摘要,触发压缩时秒级生效,用户无感等待 | internal/preemptive/ |
| 📦 Tool Output Compression | 大体积工具输出先压缩再进上下文,节省约 50% token | internal/pipes/tool_output/ |
| 🔍 Tool Discovery | 按相关性过滤无关工具定义,减小固定开销 | internal/pipes/tool_discovery/ |
不同 Agent 使用的 API 协议不同(Anthropic Messages / OpenAI Chat / Responses 等),网关内置了多协议适配层,统一处理。适配器源码见 internal/adapters/,每个目录对应一种供应商(anthropic.go、openai.go、bedrock.go、ollama.go 等)。
🚀 3 分钟安装 Context Gateway
方式一:源码构建(推荐,本仓库 Go 1.23 编写)
git clone https://gitcode.com/gh_mirrors/co/Context-Gateway
cd Context-Gateway
make build # 产物为 bin/context-gateway,Dashboard 前端自动打包内嵌
构建细节见 Makefile;官方也提供一键安装脚本(curl | sh,脚本源码在 distribution/install.sh),安装后二进制位于 ~/.local/bin。
方式二:Docker
仓库提供 Docker 与 docker-compose 测试编排,端到端联调可运行 make docker-test-e2e,架构说明见 docker/README.md。
🧙 5 分钟接入你的第一个 Agent(TUI 向导)
安装完成后,直接运行:
context-gateway
会进入交互式 TUI 向导(源码 cmd/wizard_core.go、internal/tui/),只需回答几个问题:
- 选择 Agent:
claude_code/cursor/codex/openclaw/opencode/ 自定义; - 配置 Summarizer 模型与 API Key(压缩用的摘要模型,默认走订阅认证即可);
- 设置触发阈值:上下文占用达到约 85% 时开始后台摘要(可在向导调整);
- 可选开启 Slack 通知(脚本示例 cmd/hooks/slack-notify.sh)。
向导会基于推荐的 cmd/configs/fast_setup.yaml 生成配置——该配置默认全量开启三类优化(摘要 / 工具输出压缩 / 工具发现),是官方推荐的新手起点。
🔌 四大 Agent 接入方式一览
每个 Agent 都有独立的 YAML 定义,位于 cmd/agents/,核心思路都是:把 Agent 的 API 基址指到本地网关,其余一切不变。
Claude Code(cmd/agents/claude_code.yaml)
- 运行
context-gateway -a claude_code,网关自动设置环境变量ANTHROPIC_BASE_URL=http://localhost:${GATEWAY_PORT},再启动claude命令; - 无需 API Key:网关配置中
skip_api_key_setup: true,认证沿用 Claude Code 自带的/login订阅流程; - 运行模式为
interactive——网关与 Agent 同生命周期,Agent 退出后网关自动清理。
Cursor(cmd/agents/cursor.yaml)
Cursor 同时使用 OpenAI 与 Anthropic 两套协议,网关会双路注入:
environment:
- name: "OPENAI_BASE_URL" # → http://localhost:${GATEWAY_PORT}/v1
- name: "OPENAI_API_KEY"
- name: "ANTHROPIC_BASE_URL" # → http://localhost:${GATEWAY_PORT}
- name: "ANTHROPIC_API_KEY"
即 Cursor 走 OpenAI 兼容端点的流量和 Anthropic 端点的流量全部经过网关压缩。
Codex CLI(cmd/agents/codex.yaml)
- 注入
OPENAI_BASE_URL=http://localhost:${GATEWAY_PORT}; - 认证自动识别:
sk-开头的 API Key 路由到 OpenAI API;ChatGPT 订阅 token 则自动路由到 ChatGPT 后端,无需手动区分; - 向导对 Codex 默认预设 OpenAI 供应商 + 订阅模式(见 cmd/wizard_core.go 第 59-74 行)。
OpenClaw(cmd/agents/openclaw.yaml)
OpenClaw 采用后台守护模式,与前三个不同:
context-gateway -a openclaw # 网关以后台 daemon 运行
openclaw tui # 在另一个终端正常启动 OpenClaw
网关通过自带插件(internal/plugins/openclaw/,TypeScript 插件源码)改写 ~/.openclaw/openclaw.json 中的 provider baseUrl,把流量导入网关,全程无需环境变量。首次使用 OpenClaw 需先运行 openclaw onboard 完成模型认证。
🎁 OpenCode 也已支持(cmd/agents/opencode.yaml):同时注入 Anthropic 与 OpenAI 两路 Base URL。
⌨️ 常用命令速查
入口逻辑在 cmd/main.go,帮助信息可用 context-gateway --help 查看:
context-gateway -l # 列出所有可用 Agent
context-gateway -a claude_code # 指定 Agent 启动(跳过选择菜单)
context-gateway -a codex -p 19081 # 手动指定端口(默认 18081 或自动探测)
context-gateway serve # 只启动网关服务器,不启动 Agent
context-gateway --config list # 列出可用配置
context-gateway -a openclaw --daemon # 后台模式
context-gateway --stop # 停止网关
context-gateway -a claude_code -- -p # -- 之后的参数透传给 Agent
多 Agent 并行:自 v0.5.0 起网关是真正的多 Agent 平台(见 ChangeLog.md),支持多端口并行——开多个终端各跑一个 Agent,网关会为每个会话自动分配独立端口(GATEWAY_PORT 由 cmd/agent.go 探测后注入配置),互不干扰。
📊 验证效果:Dashboard 与压缩日志
Dashboard:网关启动后会自动用浏览器打开 http://localhost:18080/dashboard/(默认端口常量见 internal/config/defaults.go 第 75 行),可查看:
- 💰 压缩节省量(token 与费用统计)
- 📈 使用量与实时会话信息
- 🗂 提示词历史(前端源码 web/dashboard/src/)
日志文件(每次调用独立的会话目录 logs/):
| 日志 | 内容 |
|---|---|
logs/history_compaction.jsonl |
后台历史压缩事件,随时查看"发生了什么" |
logs/tool_output_compression.jsonl |
工具输出压缩明细 |
logs/telemetry.jsonl |
遥测数据 |
logs/session_stats.json |
会话统计 |
日志路径均可在 cmd/configs/fast_setup.yaml 的 monitoring 段自定义。
🧩 进阶:自定义 Agent 与关键配置
接入你自己的 Agent:复制模板 cmd/agents/template_example.yaml,填三个部分即可——
agent:
name: "my_agent" # 唯一标识
environment: # 把 API 基址指向网关
- name: "OPENAI_BASE_URL"
value: "http://localhost:${GATEWAY_PORT}"
command:
check_cmd: ["which", "my_agent"]
run: "my_agent"
${GATEWAY_PORT} 与 ${OPENAI_API_KEY} 等变量会自动从 .env 展开。
调优压缩强度:在 fast_setup.yaml 的 pipes.tool_output 段调整 target_compression_ratio(0.5 ≈ 移除 50% token),在 preemptive.trigger_threshold 调整触发阈值;成本上限可启用 cost_control 做会话/全局封顶。
跑测试:仓库测试覆盖非常完整,make test 跑单元测试(tests/ 下按供应商分目录,含单元 / 集成 / 性能 / 压测),make test-race 带竞态检测。
❓ 常见问题 FAQ
Q:端口 18081 被占用了怎么办?
默认自动探测可用端口,也可 -p/--port 手动指定。
Q:一定要用 API Key 吗? 不需要。Claude Code、Codex 均支持订阅认证透传(OAuth/ChatGPT Plus),网关只转发流量、不碰凭证(认证相关逻辑在 internal/auth/)。
Q:网关挂了会影响正常开发吗?
网关是独立进程,context-gateway --stop 或杀掉进程后,把 Agent 的 *_BASE_URL 环境变量移除即可直连官方 API,配置零残留。
总结
| 需求 | Context Gateway 方案 |
|---|---|
| 多 Agent 统一接入 | 一个二进制 + YAML 定义,-a 切换 Claude Code / Cursor / Codex / OpenClaw / OpenCode |
| 压缩等待 | 后台 Preemptive Summarization,触发即秒级生效 |
| 成本可见 | Dashboard 实时统计节省量,cost_control 设上限 |
| 扩展性 | 自定义 Agent 模板 + 多端口并行 + Docker 部署 |
一句话:装一个 context-gateway,所有 AI 编程助手都获得后台压缩与上下文优化能力。上手路径很短——克隆构建(或一键脚本)→ 运行 context-gateway 走完 TUI 向导 → context-gateway -a <agent> 开工。
项目完整说明见 README.md,版本演进见 ChangeLog.md,欢迎参与贡献(约定见 CONTRIBUTING.md)。