feat: support Hermes-managed Codex OAuth

.gitignore

@@ -23,6 +23,7 @@ Thumbs.db
 # Environment
 .env
 *.env.local
+.venv/
 
 # uv
 uv.lock

README.md

@@ -212,7 +212,7 @@ The setup wizard prompts for the provider, model, local skills directory, PRM se
 For a minimal first run:
 
 - choose `none` for the CLI agent if you do not want SkillClaw to auto-configure an external agent yet
-- local skills at `~/.skillclaw/skills` for the generic setup path; if you choose Hermes, Codex, or Claude Code, the default local library becomes `~/.hermes/skills`, `~/.codex/skills`, or `~/.claude/skills`
+- local skills at `~/.skillclaw/skills` for the generic setup path; if you choose Hermes, Codex, or Claude Code, the default local library becomes `$HERMES_HOME/skills` (or `~/.hermes/skills` when unset), `~/.codex/skills`, or `~/.claude/skills`
 - disable shared storage if you only want to use the local proxy first
 - enable local shared storage only if you want to add the evolve server later on the same machine, and use a dedicated root such as `~/.skillclaw/local-share`
 - disable PRM if you want the cheapest first pass
@@ -239,8 +239,8 @@ If you already use Hermes, the client-side path is:
 1. Install Hermes first.
 2. Run `skillclaw setup` and choose `hermes` for `CLI agent to configure`.
 3. Keep `Proxy model name exposed to agents` as `skillclaw-model` unless you have a specific reason to change it.
-4. Start SkillClaw. On startup, SkillClaw rewrites `~/.hermes/config.yaml` to point Hermes at the local proxy.
-5. Hermes uses `~/.hermes/skills` as the default local skill library. SkillClaw prepares that directory automatically and copies in any missing legacy skills from `~/.skillclaw/skills`.
+4. Start SkillClaw. On startup, SkillClaw rewrites `$HERMES_HOME/config.yaml` (or `~/.hermes/config.yaml` when unset) to point Hermes at the local proxy.
+5. Hermes uses `$HERMES_HOME/skills` (or `~/.hermes/skills` when unset) as the default local skill library. SkillClaw prepares that directory automatically and copies in any missing legacy skills from `~/.skillclaw/skills`.
 6. If you want to inspect or undo the integration, use `skillclaw doctor hermes` and `skillclaw restore hermes`.
 
 Minimal verification:
@@ -259,6 +259,12 @@ skillclaw restore hermes
 
 `skillclaw doctor hermes` reports whether Hermes is pointed at the local proxy, whether the Hermes skills directory exists, whether legacy skills are still present, and that session boundaries still fall back to proxy-side heuristics unless Hermes sends explicit session headers.
 
+#### Hermes-managed ChatGPT / Codex OAuth
+
+Choose `hermes-openai-codex` as the upstream provider in `skillclaw setup` when Hermes already owns a ChatGPT/Codex OAuth login. SkillClaw resolves a fresh bearer through Hermes for each upstream request; it never stores the OAuth access or refresh token in `~/.skillclaw/config.yaml`.
+
+This route registers a named loopback provider with Hermes's native `codex_responses` wire mode, while SkillClaw owns the separate upstream `openai-codex` OAuth hop. Setup generates a local proxy key, forces `127.0.0.1`, and validates the Hermes OAuth login without storing OAuth access or refresh tokens. Start with `skillclaw start --daemon`, then verify the complete route with `skillclaw doctor hermes` and a `hermes chat` exact-reply query.
+
 ### Path B: Join an existing shared group
 
 Install the same client as in Path A, then point your local client at the group's shared storage. The easiest beginner route is to rerun `skillclaw setup`, enable shared storage, and fill in the values your server operator gives you.

assets/README_ZH.md

@@ -211,7 +211,7 @@ skillclaw setup
 第一次最小化验证时，推荐这样选：
 
 - `CLI agent` 选 `none`，先不要自动改外部 agent 配置
-- `skills` 目录保持默认值 `~/.skillclaw/skills`；如果你选了 Hermes、Codex 或 Claude Code，默认技能库会变成 `~/.hermes/skills`、`~/.codex/skills` 或 `~/.claude/skills`
+- `skills` 目录保持默认值 `~/.skillclaw/skills`；如果你选了 Hermes、Codex 或 Claude Code，默认技能库会变成 `$HERMES_HOME/skills`（未设置时为 `~/.hermes/skills`）、`~/.codex/skills` 或 `~/.claude/skills`
 - 如果你只是想先验证代理能不能正常用，可以先关闭 shared storage
 - 如果你后面想在同一台机器上继续跑本地 evolver 闭环，就把 shared storage 打开并选 `local` backend，例如 `~/.skillclaw/local-share`
 - 如果你想先把成本压到最低，可以先关闭 PRM
@@ -238,8 +238,8 @@ curl "http://127.0.0.1:${PROXY_PORT}/healthz"
 1. 先安装 Hermes。
 2. 运行 `skillclaw setup`，在 `CLI agent to configure` 里选择 `hermes`。
 3. `Proxy model name exposed to agents` 保持 `skillclaw-model`，除非你明确知道自己为什么要改它。
-4. 启动 SkillClaw。启动时，SkillClaw 会自动改写 `~/.hermes/config.yaml`，把 Hermes 指到本地代理。
-5. Hermes 默认使用 `~/.hermes/skills` 作为本地技能库。SkillClaw 会自动准备好该目录，并把 `~/.skillclaw/skills` 中遗留的旧技能复制过来。
+4. 启动 SkillClaw。启动时，SkillClaw 会自动改写 `$HERMES_HOME/config.yaml`（未设置时为 `~/.hermes/config.yaml`），把 Hermes 指到本地代理。
+5. Hermes 默认使用 `$HERMES_HOME/skills`（未设置时为 `~/.hermes/skills`）作为本地技能库。SkillClaw 会自动准备好该目录，并把 `~/.skillclaw/skills` 中遗留的旧技能复制过来。
 6. 如果你想检查或撤销集成，使用 `skillclaw doctor hermes` 和 `skillclaw restore hermes`。
 
 最小验证命令：
@@ -258,6 +258,12 @@ skillclaw restore hermes
 
 `skillclaw doctor hermes` 会检查 Hermes 是否指向了本地代理、Hermes skills 目录是否存在、旧技能是否还在、以及会话边界是否仍回退到代理侧的启发式策略（除非 Hermes 发送了显式的 session header）。
 
+#### 使用 Hermes 管理的 ChatGPT / Codex OAuth
+
+如果 Hermes 已经持有 ChatGPT/Codex OAuth 登录，可在 `skillclaw setup` 中选择 `hermes-openai-codex`。SkillClaw 每次请求都通过 Hermes 临时解析访问令牌，不会把 OAuth access token 或 refresh token 写入 `~/.skillclaw/config.yaml`。
+
+该模式仅绑定本机回环地址，使用独立的本地代理密钥，并通过 Hermes 原生 `codex_responses` 传输。启动后使用 `skillclaw doctor hermes` 和一次 `hermes chat` 精确回复测试验证完整链路。
+
 ### 路径 B：加入一个已有的共享群组
 
 加入群组时，用户侧安装方式和路径 A 完全一样。区别只是把本地 Client 指向群组的共享存储。

pyproject.toml

@@ -38,6 +38,11 @@ server = [
     "oss2",
     "python-dotenv",
 ]
+# Test suite
+test = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+]
 # Everything
 all = [
     "skillclaw[embedding,evolve,sharing,server]",