一个网关搞定所有AI编程助手:Context Gateway多Agent接入实战(Claude Code/Cursor/Codex/OpenClaw)

原创2026-11-07 15:57:461,857 阅读

一个网关搞定所有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/),只需回答几个问题:

  1. 选择 Agent:claude_code / cursor / codex / openclaw / opencode / 自定义;
  2. 配置 Summarizer 模型与 API Key(压缩用的摘要模型,默认走订阅认证即可);
  3. 设置触发阈值:上下文占用达到约 85% 时开始后台摘要(可在向导调整);
  4. 可选开启 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)。

登录后查看全文
Context-Gateway