Atuin AI Proxy 评测 2026：保留终端里的 ? 助手，把后端换成自己的

Atuin 大概是那种用过就回不去的工具：它把 shell 的 Ctrl+R 换成一个飞快、可搜索、端到端加密并且能跨机器同步的历史记录。从 v18.13 起它还带了 AI 助手——在空提示符下按 ?，用自然语言说你想干什么，它给回一条命令，回车执行、Tab 编辑。

这个助手好用，恰恰是因为它”看得多”：它能把你的 shell 历史、退出码、当前目录、甚至命令输出一起当作排错上下文。而这也正是一部分人压根不敢开它的原因——Atuin AI 在设计上要求登录 Atuin Hub 账号，上述这些上下文必须离开本机才能发挥作用。Atuin 官方文档确实写了”你可以自建 AI 后端”，但并没有顺手给你一个能跑的服务端。

Atuin AI Proxy 就是第三方来补这块的。说白了，它是一份写得挺讲究的周末量级 Python 代码：假装自己就是 Atuin 的 Hub AI 接口，然后把请求转发到你指定的任何地方。

它到底做了什么

Atuin 客户端对 [ai].endpoint 那一端有很具体的要求：必须有一个 POST /api/cli/chat 路由，返回 text/event-stream，并且带上 x-atuin-ai-session-id 响应头。这个代理实现了这套约定，然后在 Atuin 的事件词汇和上游服务商真正说的协议之间做翻译。

翻译层才是真功夫所在。上游的 response.output_text.delta 事件、以及 Chat Completions 的 choices[].delta.content 分片，都会被统一成 Atuin 的 text 事件；完成态的 function_call 和 Chat Completions 的 tool_calls 都变成 tool_call；response.completed 或 Chat Completions 的 [DONE] 变成 done；上游报错变成 error。客户端工具只在 Atuin 主动声明支持时才暴露给模型，但 suggest_command 例外——它永远开着，因为整件事的目的就是让模型能把命令递回来。

Atuin 侧的配置就三行：

[ai]
enabled = true
endpoint = "http://localhost:8000"
api_token = "change-me"

把 api_token 设成和代理的 ATUIN_PROXY_TOKEN 一致就有了 bearer 鉴权。如果 ATUIN_PROXY_TOKEN 不设，代理会放行本地请求、不做鉴权——自己笔记本上图省事可以，但凡机器有你控制不了的网络接口，就别这么干。

什么场景值得用

不想让 shell 上下文出本机。 这是最主要的理由。如果你在客户的服务器上干活、身处合规要求较严的环境，或者单纯就是对”命令历史往哪儿跑”有明确态度，这个代理能让你保留 Atuin 的顺手，同时把 AI 链路收在自己的边界内。

复用手上已有的 Codex 订阅。 codex-token 和 codex-oauth 这两个后端是整个项目最有意思的部分。如果你本来就买了 Codex，就不必再开一份按 token 计费的 API 关系。设备码登录一条命令：docker compose run --rm atuin-ai-proxy atuin-ai-proxy auth login --device-code；也可以直接把现成的 Codex CLI auth.json 挂到 /data/codex/auth.json。

自己定模型。 托管版用什么模型是 Atuin 说了算。走代理，MODEL 由你设，可以指向本地 Ollama 那类端点、更便宜的托管模型，或者顶配模型——只要它说 OpenAI 协议。

排查助手为什么不对劲。 所有流量都过一个你自己的进程，就可以把日志开大、真真切切看到 Atuin 发了什么、上游回了什么。对着一个托管黑盒是做不到这件事的。

关键特性

三种后端，一个入口

BACKEND=openai 对接任何 OpenAI 兼容 API；BACKEND=codex-token 用 Codex access token 或个人访问令牌加 account ID；BACKEND=codex-oauth 读 Codex 的 OAuth auth.json。OPENAI_API 开关接受 auto、responses、chat_completions，默认 auto 会先试 Chat Completions，被判为不支持时自动退回 Responses。两个 Codex 后端只支持 Responses API——万一你配错成 OPENAI_API=chat_completions，代理会在启动时打一条告警，然后悄悄按正确的走，而不是直接崩给你看。

运行时零第三方依赖

README 讲得很直白：运行时只用 Python 标准库。对于一个横在你 shell 历史链路上、还要对外监听的服务来说，这是实打实的安全和维护优势——没有依赖树需要审计、锁版本，也不会某天早上被一个传递依赖的 CVE 叫醒。测试用 python3 -m unittest discover -s tests 就能跑。

内置可追溯，而且提醒得很老实

每一个 HTTP 响应和流式错误都带 request id。当 Atuin 甩给你一句含糊的 SSE request failed (...)，你从 JSON body 里把 request_id 抠出来，去代理日志里 grep 就行。日志级别从 INFO、WARNING、DEBUG 一直到 TRACE，最高级会输出经过脱敏、按 TRACE_PAYLOAD_BYTES 截断的请求 / 后端 / SSE 片段。README 明确写了：TRACE 输出仍可能包含 shell 历史、提示词、路径和命令输出，只在排查问题时开。这种主动交代风险的态度，比不少体量大得多的项目要靠谱。

错误码对照表

不用你猜，README 直接把错误映射到原因：400 missing_model 是没设 MODEL；401 unauthorized 是 api_token 和 ATUIN_PROXY_TOKEN 不一致；502 auth_error 是后端凭据缺失或无效；502 upstream_http_error 会附带脱敏后的上游片段；504 upstream_timeout 是后端超过了 REQUEST_TIMEOUT_SECONDS。

价格

代理本身免费，不用注册账号，没有分层，也没有埋点。

但有个不太好回避的账要算清楚：目前的经济性其实是不划算的。Atuin AI 在测试期间是免费的，所以你现在做的事，本质是拿一个免费的托管服务，换成一份要花钱的 API 关系，外加自己那点搭建时间。Atuin 收费的 Personal Pro 大约 2 美元/月或 20 美元/年，而那是买历史同步，不是买助手。

所以现阶段它卖的是隐私和模型选择权，不是省钱。等 Atuin AI 结束测试、开始收费，这笔账就立刻翻过来——那时候把它指向一份你本来就有的订阅，就是直接更便宜。

还有一个比价格更要紧的坑：仓库里没有 LICENSE 文件。源码看得见，不等于你被授权使用；默认情况下这叫保留所有权利。个人折腾没人会追究，但如果你所在公司有开源合规要求，在作者补上许可证之前，这一条就是硬门槛。

常见问题

用它就能不要 Atuin 账号了吗？ AI 这条链路上是的——代理自己就是后端，这个流程里不会调 Hub。但历史同步是另一个功能，有自己的账号要求，而自建同步服务器是官方支持的。

Atuin 更新了会不会挂？ 有可能。POST /api/cli/chat 是内部约定，不是公开稳定 API。代理靠观察来对齐，上游一改就可能无声破功。再叠加上”自 2026-07-10 起没有新提交”这一点，这个风险要当真。

能上生产吗？ 一个人的笔记本上没问题——它小、有测试、无依赖。团队就别想了：没有多用户、没有配额核算、没有按人分发的密钥，也没有许可证。要做团队共享的基础设施，LiteLLM 这类通用网关是更合适的底座，只不过 Atuin 那套约定得你自己去桥接。

总结

Atuin AI Proxy 是一个把很窄的问题解决得挺漂亮的小软件。只用标准库的运行时、成体系的错误码表、request id 追踪，以及关于 TRACE 会泄漏什么的坦白提醒，这几点加起来能看出作者是真运维过软件的人，而不是丢个 demo 就跑。Codex 订阅那两个后端更是个聪明的加分项——体量大些的项目大概根本懒得做。

但它毕竟是个 3 星、0 fork、7 月之后就没再提交、只有一位维护者、还没有 LICENSE 的仓库。倒不是说它哪里坏了，而是万一作者不玩了、或者 Atuin 改了接口，几乎没有社区缓冲垫。

建议用：你已经在用 Atuin，明确希望按 ? 时 shell 上下文不出本机，或者想把它接到已经付费的 Codex 计划上。搭起来大概十分钟。

建议跳过：你对开箱即用的 Atuin AI 已经满意——它现在免费，装这层只是多了活动部件，换来的好处你未必需要。另外，如果公司要求明确的开源许可，在仓库补上许可证之前也先别用。

一个有教养的小工具，适配特定人群。只是要清楚：你接手的是一个周末项目，不是一款产品。