Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(plugin/codex): allow empty api_key (unauthenticated local OV) (#2023)

t0sakic73a32f270c8
diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.md
index 2d7c0cb75..a5ccbc642 100644
--- a/docs/en/agent-integrations/04-codex.md
+++ b/docs/en/agent-integrations/04-codex.md
@@ -35,11 +35,12 @@ codex features list | grep codex_hooks
Three steps the installer does for you, that you can do manually:
-1. **Shell function wrapper** in `~/.zshrc` / `~/.bashrc` that promotes ovcli.conf into env vars before exec'ing codex (uses `node` rather than `jq` to avoid a silent fallback to OAuth when `jq` is missing — Codex already requires Node 22+):
+1. **Shell function wrapper** in `~/.zshrc` / `~/.bashrc`. The installer-emitted version (see `setup-helper/install.sh`) additionally re-renders the cached `.mcp.json` bearer field on each launch, which is required if you swap `OPENVIKING_CLI_CONFIG_FILE` between configs with and without `api_key`. A simpler fixed-config equivalent:
```bash
codex() {
local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"
+ local _ov_url _ov_key _ov_account _ov_user
if [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; then
local _ov_env
_ov_env=$(node -e '
@@ -55,16 +56,21 @@ Three steps the installer does for you, that you can do manually:
} catch {}
' "$_ov_conf" 2>/dev/null)
eval "$_ov_env"
- OPENVIKING_URL="${OPENVIKING_URL:-${OV_URL:-}}" \
- OPENVIKING_API_KEY="${OPENVIKING_API_KEY:-${OV_KEY:-}}" \
- OPENVIKING_ACCOUNT="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}" \
- OPENVIKING_USER="${OPENVIKING_USER:-${OV_USER:-}}" \
- OPENVIKING_AGENT_ID="${OPENVIKING_AGENT_ID:-codex}" \
- command codex "$@"
- unset OV_URL OV_KEY OV_ACCOUNT OV_USER
- else
- command codex "$@"
fi
+ _ov_url="${OPENVIKING_URL:-${OV_URL:-}}"
+ _ov_key="${OPENVIKING_API_KEY:-${OV_KEY:-}}"
+ _ov_account="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}"
+ _ov_user="${OPENVIKING_USER:-${OV_USER:-}}"
+ unset OV_URL OV_KEY OV_ACCOUNT OV_USER
+ # Empty values are NOT exported — Codex hard-fails on empty
+ # bearer_token_env_var targets.
+ local -a _env_args=()
+ [ -n "$_ov_url" ] && _env_args+=("OPENVIKING_URL=$_ov_url")
+ [ -n "$_ov_key" ] && _env_args+=("OPENVIKING_API_KEY=$_ov_key")
+ [ -n "$_ov_account" ] && _env_args+=("OPENVIKING_ACCOUNT=$_ov_account")
+ [ -n "$_ov_user" ] && _env_args+=("OPENVIKING_USER=$_ov_user")
+ _env_args+=("OPENVIKING_AGENT_ID=${OPENVIKING_AGENT_ID:-codex}")
+ env "${_env_args[@]}" codex "$@"
}
```
@@ -85,6 +91,8 @@ Hooks resolve this chain on every fire (changes to ovcli.conf take effect on the
Auth is sent as `Authorization: Bearer <api_key>` to both the REST API (used by hooks) and the `/mcp` endpoint (used by the model).
+For **unauthenticated local OV** (`ovcli.conf` without `api_key`, or no ovcli.conf at all), `.mcp.json` is rendered *without* `bearer_token_env_var`. Codex 0.130 hard-fails MCP startup with `Environment variable ... is empty` when `bearer_token_env_var` points at an empty/unset env var. The `codex()` shell-function wrapper re-renders this field on every codex launch based on whichever ovcli.conf `OPENVIKING_CLI_CONFIG_FILE` is currently pointing at, so swapping configs (e.g. for benchmark isolation) doesn't require a re-install. Identity headers still flow through `env_http_headers`.
+
### Key environment variables
| Variable | Default | Notes |
diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.md
index eff714fa6..9e357d11a 100644
--- a/docs/zh/agent-integrations/04-codex.md
+++ b/docs/zh/agent-integrations/04-codex.md
@@ -35,11 +35,12 @@ codex features list | grep codex_hooks
installer 替你做的三件事,你也可以自己手动做:
-1. **shell 函数包装**追加到 `~/.zshrc` / `~/.bashrc`,把 ovcli.conf 提升成环境变量后再 exec codex(用 `node` 而不是 `jq` 解析 conf —— 这样在没装 `jq` 的机器上也能跑,Codex 本身已经强依赖 Node 22+):
+1. **shell 函数包装**追加到 `~/.zshrc` / `~/.bashrc`。installer 实际生成的版本(见 `setup-helper/install.sh`)还会在每次 codex 启动时**重新渲染缓存里的 `.mcp.json` bearer 字段** —— 这是切 `OPENVIKING_CLI_CONFIG_FILE`(有 / 无 key 来回换)所必需的。下面是固定 conf 场景的简化版:
```bash
codex() {
local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"
+ local _ov_url _ov_key _ov_account _ov_user
if [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; then
local _ov_env
_ov_env=$(node -e '
@@ -55,16 +56,20 @@ installer 替你做的三件事,你也可以自己手动做:
} catch {}
' "$_ov_conf" 2>/dev/null)
eval "$_ov_env"
- OPENVIKING_URL="${OPENVIKING_URL:-${OV_URL:-}}" \
- OPENVIKING_API_KEY="${OPENVIKING_API_KEY:-${OV_KEY:-}}" \
- OPENVIKING_ACCOUNT="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}" \
- OPENVIKING_USER="${OPENVIKING_USER:-${OV_USER:-}}" \
- OPENVIKING_AGENT_ID="${OPENVIKING_AGENT_ID:-codex}" \
- command codex "$@"
- unset OV_URL OV_KEY OV_ACCOUNT OV_USER
- else
- command codex "$@"
fi
+ _ov_url="${OPENVIKING_URL:-${OV_URL:-}}"
+ _ov_key="${OPENVIKING_API_KEY:-${OV_KEY:-}}"
+ _ov_account="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}"
+ _ov_user="${OPENVIKING_USER:-${OV_USER:-}}"
+ unset OV_URL OV_KEY OV_ACCOUNT OV_USER
+ # 空值不导出 —— Codex 看到 bearer_token_env_var 指向空 env var 会硬错。
+ local -a _env_args=()
+ [ -n "$_ov_url" ] && _env_args+=("OPENVIKING_URL=$_ov_url")
+ [ -n "$_ov_key" ] && _env_args+=("OPENVIKING_API_KEY=$_ov_key")
+ [ -n "$_ov_account" ] && _env_args+=("OPENVIKING_ACCOUNT=$_ov_account")
+ [ -n "$_ov_user" ] && _env_args+=("OPENVIKING_USER=$_ov_user")
+ _env_args+=("OPENVIKING_AGENT_ID=${OPENVIKING_AGENT_ID:-codex}")
+ env "${_env_args[@]}" codex "$@"
}
```
@@ -85,6 +90,8 @@ Hook 每次触发都重新解析这条优先级链——改完 ovcli.conf 下一
鉴权头同时发给 REST API(hook 用)和 `/mcp` endpoint(模型用):`Authorization: Bearer <api_key>`。
+对于**无鉴权的本地 OV**(`ovcli.conf` 没有 `api_key`,或者根本没 ovcli.conf),`.mcp.json` 渲染时**不会**写入 `bearer_token_env_var`。Codex 0.130 一旦看到 `bearer_token_env_var` 指向空/未设置的 env var,会直接 `Environment variable ... is empty` 硬错。`codex()` shell 函数包装会在**每次 codex 启动时**根据当前 `OPENVIKING_CLI_CONFIG_FILE` 指向的 ovcli.conf 重新渲染这个字段,所以切换 conf(比如 benchmark 隔离)**不用重跑 installer**。多租户身份头通过 `env_http_headers` 始终传。
+
### 关键环境变量
| 环境变量 | 默认值 | 说明 |
diff --git a/examples/codex-memory-plugin/README.md b/examples/codex-memory-plugin/README.md
index f408bb606..faff3b6a4 100644
--- a/examples/codex-memory-plugin/README.md
+++ b/examples/codex-memory-plugin/README.md
@@ -39,11 +39,12 @@ codex # first run: review /hooks once
If you don't want the installer touching your rc, do these three things yourself:
-1. **Wire a `codex()` shell function** that injects OpenViking creds at invocation time. Add to `~/.zshrc` / `~/.bashrc` (uses `node` rather than `jq` so it works on any machine that already has Codex — Codex requires Node 22+):
+1. **Wire a `codex()` shell function** that injects OpenViking creds at invocation time. The installer-emitted version (see `setup-helper/install.sh`) additionally re-renders the cached `.mcp.json` bearer field on each launch — required if you swap `OPENVIKING_CLI_CONFIG_FILE` between configs with and without `api_key`. A simpler equivalent for a fixed config:
```bash
codex() {
local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"
+ local _ov_url _ov_key _ov_account _ov_user
if [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; then
local _ov_env
_ov_env=$(node -e '
@@ -59,16 +60,21 @@ If you don't want the installer touching your rc, do these three things yourself
} catch {}
' "$_ov_conf" 2>/dev/null)
eval "$_ov_env"
- OPENVIKING_URL="${OPENVIKING_URL:-${OV_URL:-}}" \
- OPENVIKING_API_KEY="${OPENVIKING_API_KEY:-${OV_KEY:-}}" \
- OPENVIKING_ACCOUNT="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}" \
- OPENVIKING_USER="${OPENVIKING_USER:-${OV_USER:-}}" \
- OPENVIKING_AGENT_ID="${OPENVIKING_AGENT_ID:-codex}" \
- command codex "$@"
- unset OV_URL OV_KEY OV_ACCOUNT OV_USER
- else
- command codex "$@"
fi
+ _ov_url="${OPENVIKING_URL:-${OV_URL:-}}"
+ _ov_key="${OPENVIKING_API_KEY:-${OV_KEY:-}}"
+ _ov_account="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}"
+ _ov_user="${OPENVIKING_USER:-${OV_USER:-}}"
+ unset OV_URL OV_KEY OV_ACCOUNT OV_USER
+ # Build env-prefix dynamically so empty values are NOT passed as empty
+ # strings — Codex hard-fails on empty bearer_token_env_var targets.
+ local -a _env_args=()
+ [ -n "$_ov_url" ] && _env_args+=("OPENVIKING_URL=$_ov_url")
+ [ -n "$_ov_key" ] && _env_args+=("OPENVIKING_API_KEY=$_ov_key")
+ [ -n "$_ov_account" ] && _env_args+=("OPENVIKING_ACCOUNT=$_ov_account")
+ [ -n "$_ov_user" ] && _env_args+=("OPENVIKING_USER=$_ov_user")
+ _env_args+=("OPENVIKING_AGENT_ID=${OPENVIKING_AGENT_ID:-codex}")
+ env "${_env_args[@]}" codex "$@"
}
```
@@ -89,6 +95,10 @@ The shell function wrapper handles step 1 for you by promoting ovcli.conf fields
Auth is sent as `Authorization: Bearer <api_key>` to both the REST API (used by hooks) and the `/mcp` endpoint (used by the model).
+For **unauthenticated local OV** (`ovcli.conf` without `api_key`, or no ovcli.conf at all), `.mcp.json` is rendered *without* `bearer_token_env_var`. Codex 0.130 hard-fails MCP startup with `Environment variable ... is empty` if `bearer_token_env_var` points at an empty/unset env var, so it must be omitted entirely when there's no key.
+
+The `codex()` shell-function wrapper **re-renders this field on every codex launch** based on the currently-active `ovcli.conf` (the one `OPENVIKING_CLI_CONFIG_FILE` points at, falling back to `~/.openviking/ovcli.conf`). That means you can switch between authenticated and unauthenticated OV — e.g. to isolate a benchmark run from production memory — by just changing `OPENVIKING_CLI_CONFIG_FILE` before invoking `codex`, with no re-install needed. The wrapper also omits empty env-var assignments entirely (so `OPENVIKING_API_KEY=` is never passed to codex), keeping `env_http_headers` for identity (`X-OpenViking-Account` / `User` / `Agent`) intact.
+
Optional Codex-specific tuning lives under `codex` in `ovcli.conf`:
```jsonc
diff --git a/examples/codex-memory-plugin/setup-helper/install.sh b/examples/codex-memory-plugin/setup-helper/install.sh
index bff51523b..eb33fe33a 100755
--- a/examples/codex-memory-plugin/setup-helper/install.sh
+++ b/examples/codex-memory-plugin/setup-helper/install.sh
@@ -195,13 +195,46 @@ if [ -f "$HOOKS_JSON" ]; then
rm -f "${HOOKS_JSON}.bak"
fi
-# Render the OpenViking /mcp URL into the cached .mcp.json. The repo's
-# checked-in .mcp.json keeps the __OPENVIKING_MCP_URL__ placeholder.
+# Detect whether the user has an OpenViking API key configured anywhere.
+# When they don't (typical for a local unauth OV), we render .mcp.json
+# WITHOUT bearer_token_env_var, so Codex doesn't see an empty
+# OPENVIKING_API_KEY at MCP launch and trigger its OAuth fallback for
+# what should be an unauthenticated server.
+detect_api_key() {
+ if [ -n "${OPENVIKING_API_KEY:-}" ] || [ -n "${OPENVIKING_BEARER_TOKEN:-}" ]; then
+ echo "1"
+ return
+ fi
+ if [ -f "$OVCLI_CONF" ]; then
+ node -e '
+ try {
+ const c = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"));
+ process.stdout.write(c.api_key ? "1" : "0");
+ } catch { process.stdout.write("0"); }
+ ' "$OVCLI_CONF" 2>/dev/null || echo "0"
+ return
+ fi
+ echo "0"
+}
+HAS_API_KEY="$(detect_api_key)"
+
+# Render the OpenViking /mcp URL into the cached .mcp.json (and drop the
+# bearer_token_env_var line in no-auth mode). The repo's checked-in
+# .mcp.json keeps the placeholder + always-present bearer field; the cache
+# copy is what Codex actually loads.
MCP_JSON="$CACHE_DIR/.mcp.json"
if [ -f "$MCP_JSON" ]; then
- MCP_URL_ESC="$(printf '%s' "$MCP_URL" | sed -e 's/[\\/&]/\\&/g')"
- sed -i.bak -e "s|__OPENVIKING_MCP_URL__|$MCP_URL_ESC|g" "$MCP_JSON"
- rm -f "${MCP_JSON}.bak"
+ node - "$MCP_JSON" "$MCP_URL" "$HAS_API_KEY" <<'NODE'
+const fs = require("node:fs");
+const [, , file, url, hasKey] = process.argv;
+const j = JSON.parse(fs.readFileSync(file, "utf8"));
+const s = j.mcpServers["openviking-memory"];
+s.url = url;
+if (hasKey !== "1") {
+ delete s.bearer_token_env_var;
+}
+fs.writeFileSync(file, JSON.stringify(j, null, 2) + "\n");
+NODE
fi
# ----- Shell rc wrapper -----
@@ -221,15 +254,32 @@ case "${SHELL:-}" in
;;
esac
-# The wrapper uses `node` (already a hard requirement of this installer) to
-# parse ovcli.conf instead of `jq`. This avoids a silent-auth-loss failure
-# mode where `jq` is missing on the user's machine, the wrapper's
-# `command -v jq` check fails, and codex starts with no Bearer token →
-# OpenViking returns 401 → Codex falls back to OAuth.
+# The wrapper uses `node` (already a hard requirement of this installer)
+# instead of `jq` so a missing-jq machine doesn't silently lose auth.
+#
+# It also re-renders the cached .mcp.json's bearer_token_env_var field on
+# every codex launch, based on whichever ovcli.conf the user pointed
+# OPENVIKING_CLI_CONFIG_FILE at this time. That lets a single install
+# handle both authenticated and unauthenticated configs without forcing
+# a re-install when the user swaps configs (e.g. to isolate a benchmark
+# run from production memory).
+#
+# Codex 0.130 hard-fails MCP startup when bearer_token_env_var points at
+# an EMPTY env var ("Environment variable ... is empty"), and also when
+# bearer_token_env_var is present but the env var is unset. So when the
+# resolved api_key is empty, we both drop the field from .mcp.json AND
+# omit OPENVIKING_API_KEY from the env passed to codex.
read -r -d '' WRAPPER_BODY <<'WRAPPER' || true
codex() {
local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"
- if [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; then
+ if ! command -v node >/dev/null 2>&1; then
+ command codex "$@"
+ return
+ fi
+
+ # Resolve OV connection settings: existing env > ovcli.conf > nothing.
+ local _ov_url _ov_key _ov_account _ov_user
+ if [ -f "$_ov_conf" ]; then
local _ov_env
_ov_env=$(node -e '
try {
@@ -244,16 +294,74 @@ codex() {
} catch {}
' "$_ov_conf" 2>/dev/null)
eval "$_ov_env"
- OPENVIKING_URL="${OPENVIKING_URL:-${OV_URL:-}}" \
- OPENVIKING_API_KEY="${OPENVIKING_API_KEY:-${OV_KEY:-}}" \
- OPENVIKING_ACCOUNT="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}" \
- OPENVIKING_USER="${OPENVIKING_USER:-${OV_USER:-}}" \
- OPENVIKING_AGENT_ID="${OPENVIKING_AGENT_ID:-codex}" \
- command codex "$@"
- unset OV_URL OV_KEY OV_ACCOUNT OV_USER
+ fi
+ _ov_url="${OPENVIKING_URL:-${OV_URL:-}}"
+ _ov_key="${OPENVIKING_API_KEY:-${OV_KEY:-}}"
+ _ov_account="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}"
+ _ov_user="${OPENVIKING_USER:-${OV_USER:-}}"
+ unset OV_URL OV_KEY OV_ACCOUNT OV_USER
+
+ # Sync cache .mcp.json to current OV connection state: rewrite both the
+ # URL (so OPENVIKING_CLI_CONFIG_FILE swaps actually change the target)
+ # and the bearer_token_env_var field (Codex 0.130 hard-fails on empty
+ # bearer env vars, so the field must be absent in no-auth mode). The
+ # node script writes only when something actually changes — idempotent
+ # fast-path so we don't bump file mtime on every codex launch.
+ local _has_key _mcp_url_from_conf
+ if [ -n "$_ov_key" ]; then _has_key=1; else _has_key=0; fi
+ if [ -n "$_ov_url" ]; then
+ # Strip trailing slashes then append /mcp (matching the install-time
+ # resolve_mcp_url logic). OPENVIKING_MCP_URL env can fully override.
+ if [ -n "${OPENVIKING_MCP_URL:-}" ]; then
+ _mcp_url_from_conf="$OPENVIKING_MCP_URL"
+ else
+ _mcp_url_from_conf="${_ov_url%/}/mcp"
+ fi
else
- command codex "$@"
+ _mcp_url_from_conf=""
fi
+ local _cache_mcp
+ for _cache_mcp in "$HOME"/.codex/plugins/cache/openviking-plugins-local/openviking-memory/*/.mcp.json; do
+ [ -f "$_cache_mcp" ] || continue
+ node -e '
+ const fs = require("node:fs");
+ // node -e: argv is [node, file, hasKey, url] — no [eval] placeholder.
+ const file = process.argv[1];
+ const hasKey = process.argv[2];
+ const url = process.argv[3] || "";
+ const j = JSON.parse(fs.readFileSync(file, "utf8"));
+ const s = j.mcpServers && j.mcpServers["openviking-memory"];
+ if (s) {
+ let changed = false;
+ if (url && s.url !== url) {
+ s.url = url;
+ changed = true;
+ }
+ const cur = s.bearer_token_env_var || "";
+ if (hasKey === "1" && cur !== "OPENVIKING_API_KEY") {
+ s.bearer_token_env_var = "OPENVIKING_API_KEY";
+ changed = true;
+ } else if (hasKey !== "1" && cur) {
+ delete s.bearer_token_env_var;
+ changed = true;
+ }
+ if (changed) {
+ fs.writeFileSync(file, JSON.stringify(j, null, 2) + "\n");
+ }
+ }
+ ' "$_cache_mcp" "$_has_key" "$_mcp_url_from_conf" 2>/dev/null || true
+ done
+
+ # Build env-prefix dynamically so empty values are NOT exported as empty
+ # strings — Codex hard-fails on empty bearer_token_env_var targets.
+ local -a _env_args=()
+ [ -n "$_ov_url" ] && _env_args+=("OPENVIKING_URL=$_ov_url")
+ [ -n "$_ov_key" ] && _env_args+=("OPENVIKING_API_KEY=$_ov_key")
+ [ -n "$_ov_account" ] && _env_args+=("OPENVIKING_ACCOUNT=$_ov_account")
+ [ -n "$_ov_user" ] && _env_args+=("OPENVIKING_USER=$_ov_user")
+ _env_args+=("OPENVIKING_AGENT_ID=${OPENVIKING_AGENT_ID:-codex}")
+
+ env "${_env_args[@]}" codex "$@"
}
WRAPPER
@@ -298,13 +406,14 @@ EOF
printf '\n%s\n' "$WRAPPER_BLOCK" >> "$RC"
fi
-if [ ! -f "$OVCLI_CONF" ]; then
+if [ ! -f "$OVCLI_CONF" ] && [ "$HAS_API_KEY" != "1" ]; then
cat >&2 <<EOF
-Note: $OVCLI_CONF was not found.
-The plugin will hit $MCP_URL with no Bearer token.
-Either create ovcli.conf (see https://docs.openviking.ai/zh/guides/03-deployment#cli)
-or export OPENVIKING_URL / OPENVIKING_API_KEY before running codex.
+Note: $OVCLI_CONF was not found and no OPENVIKING_API_KEY in env.
+The plugin is installed in unauthenticated mode targeting $MCP_URL.
+To enable Bearer auth later, create ovcli.conf with an api_key (see
+https://docs.openviking.ai/zh/guides/03-deployment#cli) and re-run this
+installer — the bearer_token_env_var field will be re-added to .mcp.json.
EOF
fi
@@ -314,6 +423,7 @@ Installed $PLUGIN_ID (version $PLUGIN_VERSION).
Marketplace: $MARKETPLACE_ROOT
Plugin cache: $CACHE_DIR
MCP endpoint: $MCP_URL
+MCP auth: $([ "$HAS_API_KEY" = "1" ] && echo "Bearer (OPENVIKING_API_KEY)" || echo "none (unauthenticated)")
Next:
EOF