Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.mdindex 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_hooksThree 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:```bashcodex() {local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"+ local _ov_url _ov_key _ov_account _ov_userif [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; thenlocal _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 theAuth 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.mdindex 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_hooksinstaller 替你做的三件事,你也可以自己手动做:-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 场景的简化版:```bashcodex() {local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"+ local _ov_url _ov_key _ov_account _ov_userif [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; thenlocal _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.mdindex 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 onceIf 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:```bashcodex() {local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"+ local _ov_url _ov_key _ov_account _ov_userif [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; thenlocal _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 fieldsAuth 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`:```jsoncdiff --git a/examples/codex-memory-plugin/setup-helper/install.sh b/examples/codex-memory-plugin/setup-helper/install.shindex 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" ]; thenrm -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");+NODEfi# ----- 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' || truecodex() {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" ]; thenlocal _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"+ fielse- 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 @@ EOFprintf '\n%s\n' "$WRAPPER_BLOCK" >> "$RC"fi-if [ ! -f "$OVCLI_CONF" ]; then+if [ ! -f "$OVCLI_CONF" ] && [ "$HAS_API_KEY" != "1" ]; thencat >&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.EOFfi@@ -314,6 +423,7 @@ Installed $PLUGIN_ID (version $PLUGIN_VERSION).Marketplace: $MARKETPLACE_ROOTPlugin cache: $CACHE_DIRMCP endpoint: $MCP_URL+MCP auth: $([ "$HAS_API_KEY" = "1" ] && echo "Bearer (OPENVIKING_API_KEY)" || echo "none (unauthenticated)")Next:EOF