OpenSpace/docs/codex-mcp-deployment.md

Codex MCP Deployment

This guide bootstraps OpenSpace MCP in a fresh Codex environment after cloning this repository. It is intended for the customized Codex setup where OpenSpace is available as global MCP servers and optional sidecar evolution.

Target Setup

After deployment:

• openspace MCP is available from Codex through a global wrapper.
• openspace_evolution MCP is available for sidecar skill capture.
• Wrappers resolve the active workspace to the Git repository root when possible.
• Shared daemon mode is used by default.
• If Codex Desktop starts without a usable workspace (PWD=/), wrappers fall back to direct mode instead of creating daemon state for /.
• The MCP guard can inspect and clean stale OpenSpace or Computer Use MCP child processes.

1. Clone And Install

Use the repository and branch that contain this document.

git clone https://github.com/CCLCK/OpenSpace-1.git ~/PycharmProjects/openspace
cd ~/PycharmProjects/openspace

python3 -m venv .venv
./.venv/bin/python -m pip install -U pip
./.venv/bin/pip install -e .

For development and test tooling, install the dev extra instead:

./.venv/bin/pip install -e ".[dev]"

Quick install check:

./.venv/bin/python - <<'PY'
from importlib.metadata import version
print("openspace", version("openspace"))
PY

test -x .venv/bin/openspace-mcp
test -x .venv/bin/openspace-evolution-mcp

2. Configure Provider Environment

Create openspace/.env from the example:

cp openspace/.env.example openspace/.env

Recommended OpenAI-compatible setup:

OPENSPACE_MODEL=gpt-5.4
OPENSPACE_LLM_API_KEY=sk-xxx
OPENSPACE_LLM_API_BASE=http://127.0.0.1:8080/v1
OPENSPACE_LLM_OPENAI_STREAM_COMPAT=true

OPENSPACE_SKILL_EMBEDDING_BACKEND=local
OPENSPACE_SKILL_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5

Notes:

• OPENSPACE_LLM_* is the canonical provider surface for OpenSpace.
• Keep skill embeddings local unless you intentionally have a remote /v1/embeddings endpoint.
• If you change these values later, restart Codex Desktop and any existing MCP daemon processes so they do not keep old environment variables.

3. Install Global Codex MCP Wrappers

Run the installer from the repository root:

./scripts/install-global-codex-openspace

It creates:

~/.codex/bin/openspace-global-mcp
~/.codex/bin/openspace-evolution-global-mcp

Rerun this installer whenever you move the repository or change wrapper behavior. The generated wrapper scripts contain absolute paths to this checkout.

The installer does not edit ~/.codex/config.toml or ~/.codex/AGENTS.md.

4. Wire Codex Config

Edit ~/.codex/config.toml and point Codex at the generated wrappers. Use literal absolute paths; TOML will not expand $HOME.

[mcp_servers.openspace]
command = "/Users/YOUR_USER/.codex/bin/openspace-global-mcp"
args = []

[mcp_servers.openspace.env]
OPENSPACE_MCP_PROXY_MODE = "daemon"
OPENSPACE_MCP_IDLE_TIMEOUT_SECONDS = "900"
OPENSPACE_MCP_PROXY_IDLE_TIMEOUT_SECONDS = "180"
OPENSPACE_MCP_MAX_DAEMONS_PER_KIND = "8"

[mcp_servers.openspace_evolution]
command = "/Users/YOUR_USER/.codex/bin/openspace-evolution-global-mcp"
args = []

[mcp_servers.openspace_evolution.env]
OPENSPACE_MCP_PROXY_MODE = "daemon"
OPENSPACE_MCP_IDLE_TIMEOUT_SECONDS = "900"
OPENSPACE_EVOLUTION_MCP_IDLE_TIMEOUT_SECONDS = "1800"
OPENSPACE_MCP_PROXY_IDLE_TIMEOUT_SECONDS = "180"
OPENSPACE_MCP_MAX_DAEMONS_PER_KIND = "8"

Optional but recommended: keep global Codex instructions in ~/.codex/AGENTS.md aligned with this repository's AGENTS.md, especially the rules for:

• project-scoped skill routing through ~/.codex/tools/route_codex_skills_via_openspace.py
• sidecar evolution through openspace_evolution.evolve_from_context
• treating missing Git repositories as bootstrap issues for project work

Restart Codex Desktop after editing config.toml.

5. Verify Deployment

Run static config and wrapper checks:

cd ~/PycharmProjects/openspace
./.venv/bin/python scripts/check_openspace_mcp_preflight.py \
  --cwd "$PWD" \
  --codex-home ~/.codex \
  --json

Run a real Codex MCP session probe:

./.venv/bin/python scripts/check_openspace_mcp_preflight.py \
  --cwd "$PWD" \
  --codex-home ~/.codex \
  --probe-session \
  --json

If the probe passes, open Codex from a project repository and confirm the openspace and openspace_evolution MCP servers are available.

6. Optional Launch Modes

Normal Global Mode

Use this for day-to-day Codex Desktop. The global wrappers in ~/.codex/bin are used for any trusted project opened by Codex.

This is the recommended default.

Desktop Sidecar Evolution Profile

Use this when the main Codex Desktop login should stay unchanged, but openspace_evolution should be injected through an isolated overlay profile:

cd ~/PycharmProjects/openspace
./scripts/codex-desktop-evolution app

Then ask Codex to capture a sidecar skill after meaningful work, for example:

sidecar 自进化一下

or the longer explicit form:

对当前这轮工作做一次 sidecar 自进化。不要改代码，不要接管任务。请调用 openspace_evolution.evolve_from_context，基于当前对话、git diff 和关键改动，自动提炼 task/summary，最多生成 1 个高复用 skill，并告诉我 skill 名称、路径、为什么值得保留。

This profile keeps provider token spend isolated to the evolution sidecar.

Provider-Backed OpenSpace Codex Profile

Use this when you want an isolated Codex profile where Codex itself is launched with the OpenSpace provider settings:

cd ~/PycharmProjects/openspace
./scripts/codex-openspace app

This launcher reads openspace/.env, writes an isolated profile under ~/.codex-openspace, and enables both openspace and openspace_evolution MCP servers in daemon mode.

7. Operational Guard

The guard is available through both repository launchers:

./scripts/codex-desktop-evolution guard status
./scripts/codex-desktop-evolution guard check
./scripts/codex-desktop-evolution guard clean --dry-run
./scripts/codex-desktop-evolution guard tail
./scripts/codex-desktop-evolution guard daemon

Equivalent:

./scripts/codex-openspace guard <subcommand>

Use status first. Use clean --dry-run before any real cleanup.

The guard diagnoses:

• openspace.mcp_proxy residue
• SkyComputerUseClient mcp residue
• stale child processes under the current Codex Desktop app-server

It does not target the main codex app-server.

Troubleshooting

Codex Starts Wrappers With PWD=/

If Codex Desktop does not provide a usable workspace, the wrappers intentionally fall back to direct mode and print a warning. This prevents daemon records keyed to /.

Fix by opening Codex from a trusted project repository, or by using a launcher that passes an explicit workspace.

Raw Provider Works But MCP Fails

Treat this as configuration drift until proven otherwise:

1. Confirm openspace/.env has the expected OPENSPACE_LLM_* values.
2. Confirm ~/.codex/config.toml points to the new wrapper paths.
3. Restart Codex Desktop.
4. Re-run scripts/check_openspace_mcp_preflight.py --probe-session.
5. If needed, inspect daemon state under ~/.codex/state/openspace.

Too Many MCP Child Processes

Check before cleaning:

./scripts/codex-desktop-evolution guard status
./scripts/codex-desktop-evolution guard check
./scripts/codex-desktop-evolution guard clean --dry-run

Only run non-dry cleanup after the dry-run output matches the stale processes you intended to remove.

Deployment Checklist

• Repository cloned and virtualenv installed.
• openspace/.env contains the intended provider and embedding settings.
• ./scripts/install-global-codex-openspace completed successfully.
• ~/.codex/config.toml points to the generated wrapper scripts.
• Codex Desktop was restarted.
• Preflight static check passes.
• Preflight --probe-session passes.
• guard status reports expected process counts.