mirror of
https://github.com/HKUDS/OpenSpace.git
synced 2026-10-09 03:17:51 +00:00
Document Codex MCP deployment
This commit is contained in:
CCLCK
parent
4f16fd3c3b
commit
b31ea82637
3 changed files with 291 additions and 0 deletions
|
|
@ -157,6 +157,11 @@ pip install -e .
|
|||
openspace-mcp --help # verify installation
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> **Codex MCP deployment:** If you want this repository to provide global
|
||||
> `openspace` and `openspace_evolution` MCP servers for a fresh Codex setup,
|
||||
> follow [`docs/codex-mcp-deployment.md`](docs/codex-mcp-deployment.md).
|
||||
|
||||
> [!TIP]
|
||||
> **Recommended split routing for OpenAI-compatible gateways**
|
||||
>
|
||||
|
|
|
|||
282
docs/codex-mcp-deployment.md
Normal file
282
docs/codex-mcp-deployment.md
Normal file
|
|
@ -0,0 +1,282 @@
|
|||
# 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.
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
./.venv/bin/pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
Quick install check:
|
||||
|
||||
```bash
|
||||
./.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:
|
||||
|
||||
```bash
|
||||
cp openspace/.env.example openspace/.env
|
||||
```
|
||||
|
||||
Recommended OpenAI-compatible setup:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
./scripts/install-global-codex-openspace
|
||||
```
|
||||
|
||||
It creates:
|
||||
|
||||
```text
|
||||
~/.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`.
|
||||
|
||||
```toml
|
||||
[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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
./.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:
|
||||
|
||||
```bash
|
||||
cd ~/PycharmProjects/openspace
|
||||
./scripts/codex-desktop-evolution app
|
||||
```
|
||||
|
||||
Then ask Codex to capture a sidecar skill after meaningful work, for example:
|
||||
|
||||
```text
|
||||
sidecar 自进化一下
|
||||
```
|
||||
|
||||
or the longer explicit form:
|
||||
|
||||
```text
|
||||
对当前这轮工作做一次 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
./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:
|
||||
|
||||
```bash
|
||||
./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:
|
||||
|
||||
```bash
|
||||
./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.
|
||||
|
|
@ -124,6 +124,9 @@ This makes it possible to tell the difference between:
|
|||
|
||||
## Reinstalling the Global Wrappers
|
||||
|
||||
For a full fresh-machine setup, start with
|
||||
[`docs/codex-mcp-deployment.md`](codex-mcp-deployment.md).
|
||||
|
||||
Use:
|
||||
|
||||
```bash
|
||||
|
|
@ -178,6 +181,7 @@ Scope:
|
|||
|
||||
## Related Docs
|
||||
|
||||
- `docs/codex-mcp-deployment.md`
|
||||
- `docs/current-routing-flow.md`
|
||||
- `docs/release-note-local-customization.md`
|
||||
- `docs/codex-desktop-sidecar-evolution.md`
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue