### Install and Run Web Console Locally

Source: https://github.com/gan-xing/codexbridge/blob/main/apps/web/README.md

Install dependencies and start the development server for the web console from the repository root.

```bash
pnpm --dir apps/web install
pnpm --dir apps/web dev
```

--------------------------------

### Install Public Daemon

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-native-api/README.md

Installs and starts the background daemon for public access on a specific port, requiring an authentication token.

```bash
npx codex-native-api daemon install --port 4242 --public --auth-token your-token
```

--------------------------------

### Install Local Daemon

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-native-api/README.md

Installs and starts the background daemon for local-only use on a specific port.

```bash
npx codex-native-api daemon install --port 4242
```

--------------------------------

### Runtime Initialization Example

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-provider-relay/docs/OPENAI_TOOL_PARITY_AND_PACKAGE_HARDENING_HANDOFF.md

Example of initializing the CodexProviderRelayRuntime with API keys, model details, and hosted tool configurations.

```typescript
import {
  CodexProviderRelayRuntime,
  createCodexProviderRelayFileSearchExecutor,
  createCodexProviderRelayLocalVectorFileSearchSource,
  createCodexProviderRelayEmbeddingsApiProvider,
  createCodexProviderRelayWebSearchExecutor,
} from "@codexbridge/codex-provider-relay";

const runtime = new CodexProviderRelayRuntime({
  apiKey: process.env.OPENROUTER_API_KEY!,
  upstreamBaseUrl: "https://openrouter.ai/api/v1",
  defaultModel: "deepseek/deepseek-chat",
  providerLabel: "openrouter",
  profileMode: "mixed",
  toolStrategy: "relay-emulated",
  hostedTools: [
    { name: "web_search", mode: "relay-emulated" },
    { name: "file_search", mode: "relay-emulated" },
  ],
  hostedToolExecutors: {
    web_search: createCodexProviderRelayWebSearchExecutor(...),
    file_search: createCodexProviderRelayFileSearchExecutor(...),
  },
});

const state = await runtime.start();
// state.codexCliArgs can launch Codex app-server.
```

--------------------------------

### Example: Route Existing Record - Complete Action

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/command-skills/assistant-record.md

Example of routing an existing record, specifically marking a 'todo' as complete with a reason and confidence score.

```json
{
  "schemaVersion": "codexbridge.assistant-record-command-skill.v1",
  "operation": "route_existing_record",
  "action": "complete",
  "targetRecordId": "record-id-from-input",
  "targetIndex": 1,
  "type": "todo",
  "reason": "用户明确表示给王总回电话这件事已经完成。",
  "confidence": 0.94
}
```

--------------------------------

### Daily Schedule Example

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/command-skills/auto.md

An example of a daily schedule for an automation job, set to run at 08:00 UTC.

```json
{
  "kind": "daily",
  "hour": 8,
  "minute": 0,
  "timeZone": "UTC",
  "label": "daily 08:00 UTC"
}
```

--------------------------------

### Start local API server (explicit form)

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-native-api/README.md

Start the codex-native-api server using the explicit 'serve' command with a specified port. This is an alternative to the shorthand command.

```bash
npx codex-native-api serve --port 4242
```

--------------------------------

### Install codex-native-api

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-native-api/README.md

Install the codex-native-api package using npm.

```bash
npm install codex-native-api
```

--------------------------------

### Start WeChat Serve Process

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

Starts the WeChat serve process. This command is used after logging in and is necessary for receiving replies. Ensure the process remains running.

```bash
npm run weixin:serve -- --cwd /absolute/path/to/workspace
```

--------------------------------

### Example: Route Existing Record - Create Action

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/command-skills/assistant-record.md

Example of routing a request to create a new 'reminder', indicating no existing record was uniquely matched.

```json
{
  "schemaVersion": "codexbridge.assistant-record-command-skill.v1",
  "operation": "route_existing_record",
  "action": "create",
  "targetRecordId": null,
  "targetIndex": null,
  "type": "reminder",
  "reason": "用户要求新增一个提醒，没有唯一指向已有记录。",
  "confidence": 0.9
}
```

--------------------------------

### Interval Schedule Example

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/command-skills/auto.md

An example of an interval schedule for an automation job, set to run every 30 minutes.

```json
{
  "kind": "interval",
  "everySeconds": 1800,
  "label": "every 30m"
}
```

--------------------------------

### Start Foreground Server

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-native-api/README.md

Starts the Codex Native API as a foreground server. Use options to configure port, host, authentication, and working directory.

```bash
npx codex-native-api [serve] [options]
```

--------------------------------

### Clarify Action Example

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/command-skills/auto.md

Example JSON output for the 'clarify' action, used when user intent is ambiguous. It includes a question to resolve ambiguity and candidate options.

```json
{
  "schemaVersion": "codexbridge.auto-command-skill.v1",
  "ok": false,
  "action": "clarify",
  "confidence": 0.42,
  "requiresConfirmation": false,
  "question": "你想把待办自动任务改成什么时间或什么内容？",
  "candidates": [
    {
      "index": 1,
      "title": "每日待办检查",
      "schedule": "daily 08:00 UTC"
    }
  ]
}
```

--------------------------------

### Start WeChat Serve Process on Windows

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

Starts the WeChat serve process on Windows. This command is used after logging in and is necessary for receiving replies. Ensure the process remains running.

```powershell
npm run weixin:serve -- --cwd C:\absolute\path\to\workspace
```

--------------------------------

### Example Rewrite Record Operation

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/command-skills/assistant-record.md

An example of a completed `rewrite_record` operation, demonstrating how a reminder record is updated with new content, time, and tags.

```json
{
  "schemaVersion": "codexbridge.assistant-record-command-skill.v1",
  "operation": "rewrite_record",
  "action": "update",
  "type": "reminder",
  "title": "提醒给李总回电话",
  "content": "2026-05-01 11:00 UTC 提醒给李总回电话。",
  "status": "pending",
  "priority": "normal",
  "dueAt": null,
  "remindAt": "2026-05-01T11:00:00.000Z",
  "recurrence": null,
  "project": null,
  "tags": ["客户", "重要客户"],
  "changeSummary": "把王总改为李总，将提醒时间改为 11:00，并补充重要客户标签。",
  "confidence": 0.95
}
```

--------------------------------

### Display Help for a Specific Command (Alternative)

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/usage/weixin-slash-commands.md

Use the /help command followed by a command name to get detailed help for a specific slash command.

```text
/help open
```

--------------------------------

### CodexBridge Runtime Provider Configuration Examples

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

Examples of environment variables for configuring various OpenAI-compatible runtime providers like DeepSeek, MiniMax, Kimi, and Gemini. These settings allow CodexBridge to connect to and utilize different AI models.

```bash
DEEPSEEK_API_KEY=...
DEEPSEEK_DEFAULT_MODEL=deepseek-v4-flash

MINIMAX_API_KEY=...
MINIMAX_BASE_URL=https://api.minimaxi.com/v1
MINIMAX_MODEL=MiniMax-M2.7
MINIMAX_REQUEST_RETRY=2
MINIMAX_RETRY_STATUSES=429,503

KIMI_API_KEY=...
KIMI_BASE_URL=https://api.kimi.com/coding
KIMI_MODEL=kimi-k2

GEMINI_API_KEY=...
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
GEMINI_MODEL=gemini-2.5-pro

IFLOW_API_KEY=...
IFLOW_BASE_URL=https://apis.iflow.cn/v1
IFLOW_MODEL=qwen3-coder-plus

CODEX_COMPAT_PROVIDER_ID=custom
CODEX_COMPAT_API_KEY=...
CODEX_COMPAT_BASE_URL=https://provider.example/v1
CODEX_COMPAT_DEFAULT_MODEL=example-model
CODEX_COMPAT_CAPABILITIES=default # or deepseek/minimax/qwen/kimi/gemini/iflow/openrouter
CODEX_COMPAT_REQUEST_RETRY=2
```

--------------------------------

### Help Command Variations

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/usage/weixin-slash-commands.md

Demonstrates equivalent forms for accessing help information for various commands. Use these to get detailed usage instructions for specific commands.

```text
/threads -h
/open --help
/rename -helps
/th -h
/perm --help
```

```text
/helps threads
/helps open
/helps rename
```

--------------------------------

### Start WeChat Serve with Embedded API

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/architecture/codex-native-api.md

Command to start the WeChat serve, which enables the embedded Codex Native API service by default.

```bash
pnpm exec tsx src/cli.ts weixin serve
```

--------------------------------

### Start Localhost Service via CLI

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/todo/codex-native-api.md

The src/cli.ts codex native-api-serve command starts the localhost service without requiring WeChat/Telegram runtime startup, while preserving the main bridge chat path.

```typescript
src/cli.ts
```

--------------------------------

### Start WeChat Login

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

Run this command to initiate the WeChat login process. It will typically generate a QR code for scanning.

```bash
npm run weixin:login
```

--------------------------------

### Start or Refresh Host Codex Login

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/usage/weixin-slash-commands.md

Use the /login command to start or refresh a pending device login flow for the host Codex account pool.

```text
/login
```

--------------------------------

### Set Required Authentication Environment Variables

Source: https://github.com/gan-xing/codexbridge/blob/main/apps/web/README.md

Set these environment variables before starting the web console to configure authentication credentials.

```bash
export CODEXBRIDGE_WEB_USERNAME=admin
export CODEXBRIDGE_WEB_PASSWORD='replace-with-a-strong-password'
```

--------------------------------

### Recommended PR 7: Package Independence

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-provider-relay/docs/OPENAI_TOOL_PARITY_AND_PACKAGE_HARDENING_HANDOFF.md

Seventh PR recommendation focusing on package independence hardening, including examples and documentation.

```text
package independence hardening + examples + docs
```

--------------------------------

### Display Help for a Specific Command

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/usage/weixin-slash-commands.md

Use the /helps command followed by a command name to get detailed help for a specific slash command.

```text
/helps threads
```

--------------------------------

### API Key Compatible Mode Profile Configuration (TOML)

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-provider-relay/docs/TARGET.md

Example TOML configuration for the 'pure-api' mode, which uses an OpenAI-compatible fallback and requires an API key.

```toml
requires_openai_auth = false
env_key = "OPENAI_API_KEY"
```

--------------------------------

### Mixed Mode Profile Configuration (TOML)

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-provider-relay/docs/TARGET.md

Example TOML configuration for the 'mixed' mode, which supports Codex++-style provider configuration and requires a local Responses adapter.

```toml
model_provider = "custom"
model = "gpt-5.4"

[model_providers.custom]
name = "custom"
wire_api = "responses"
requires_openai_auth = true
base_url = "http://127.0.0.1:57321/v1"
experimental_bearer_token = "sk-..."
supports_websockets = false
```

--------------------------------

### Windows First-Time Bring-Up Steps

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

Installs dependencies, runs type checks, tests, live agent tests, verifies Codex CLI, checks Codex command location, logs in to WeChat, and serves the application on Windows.

```powershell
npm install
npm run typecheck
npm test
npm run test:live-agent
codex --version
where codex
npm run weixin:login
npm run weixin:serve -- --cwd C:\absolute\path\to\workspace
```

--------------------------------

### Install macOS launchd User Service

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

Installs and starts the CodeXBridge WeChat service as a launch agent on macOS. This ensures the service runs in the background.

```bash
bash ./scripts/service/install-launchd-user.sh
```

--------------------------------

### Linux Deployment Steps

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

Installs dependencies, runs type checks, tests, live agent tests, verifies Codex CLI, logs in to WeChat, and serves the application on Linux.

```bash
npm install
npm run typecheck
npm test
npm run test:live-agent
codex --version
npm run weixin:login
npm run weixin:serve -- --cwd /absolute/path/to/workspace
```

--------------------------------

### Install Windows Scheduled Task

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

Installs and starts a hidden per-user scheduled task for the CodeXBridge WeChat service on Windows. Use -AtStartup flag for machine startup.

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\service\install-windows-task.ps1
```

--------------------------------

### Install Linux systemd User Service

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

Installs and starts the CodeXBridge WeChat service as a systemd user service on Linux. This enables unattended use and automatic restarts.

```bash
bash ./scripts/service/install-systemd-user.sh
```

--------------------------------

### Recommended Bin Configuration in package.json

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-provider-relay/docs/CODEX_PROVIDER_RENAME_AND_EXTRACTION_HANDOFF.md

JSON configuration for the 'bin' field in package.json, mapping server commands to the CLI entry point.

```json
"bin": {
  "codex-provider-server": "./dist/cli.js",
  "codex-provider-relay-server": "./dist/cli.js",
  "codex-gateway-server": "./dist/cli.js"
}
```

--------------------------------

### Run codex-native-api without project install

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-native-api/README.md

Execute the codex-native-api package directly using npx without a project installation. This command starts the API server on the default port.

```bash
npx codex-native-api --port 4242
```

--------------------------------

### Manage Background Daemon

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-native-api/README.md

Manages the Codex Native API as a background daemon. Subcommands include install, start, stop, restart, status, logs, and uninstall.

```bash
npx codex-native-api daemon <subcommand> [options]
```

--------------------------------

### CodexBridge Help Command Examples

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

All slash commands support command-scoped help flags. Use '-h', '--help', or '-helps' to get specific usage information for a command.

```text
/threads -h
/open --help
/permissions -helps
```

--------------------------------

### Install Codex CLI Globally

Source: https://github.com/gan-xing/codexbridge/blob/main/README.md

Installs the latest version of the Codex CLI globally. Use this if the Codex CLI is not already installed.

```bash
npm install -g @openai/codex@latest --include=optional
codex --version
```

--------------------------------

### AI Execution Instructions - Initial Steps

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-provider-relay/docs/OPENAI_TOOL_PARITY_AND_PACKAGE_HARDENING_HANDOFF.md

Instructions for AI to follow before modifying code, including saving the document and reading specified files.

```text
packages/codex-provider-relay/docs/OPENAI_TOOL_PARITY_AND_PACKAGE_HARDENING_HANDOFF.md
packages/codex-provider-relay/README.md
packages/codex-provider-relay/package.json
packages/codex-provider-relay/src/index.ts
packages/codex-provider-relay/src/hosted_tools.ts
packages/codex-provider-relay/src/hosted_tool_executors.ts
packages/codex-provider-relay/src/converters/responses_adapter.ts
packages/codex-provider-relay/src/server/responses_adapter_server.ts
packages/codex-provider-relay/src/file_search_executor.ts
packages/codex-provider-relay/src/file-search/types.ts
packages/codex-provider-relay/src/file-search/executor.ts
packages/codex-provider-relay/src/file-search/local-vector-index.ts
packages/codex-provider-relay/src/file-search/stores.ts
packages/codex-provider-relay/src/file-search/shared.ts
packages/codex-provider-relay/src/file-search/sources/local-vector.ts
packages/codex-provider-relay/src/web_search_executor.ts
packages/codex-provider-relay/test/file_search_executor.test.ts
packages/codex-provider-relay/test/server.test.ts
packages/codex-provider-relay/test/public_surface.test.ts
```

--------------------------------

### List and Switch Provider Profiles

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/usage/weixin-slash-commands.md

Use `/provider` or `/pd` to list available provider profiles or switch the current scope to a different one. Examples include switching to 'openai-default', 'DeepSeek', or 'minimax'.

```text
/provider
/pd
/provider openai-default
/pd openai-default
/provider DeepSeek
/pd deepseek
/provider minimax
/pd minimax
```

--------------------------------

### Enable Protocol Tracing via Environment Variable

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-gateway/README.md

Run the internal Responses adapter server with protocol tracing enabled by setting an environment variable.

```bash
CODEX_GATEWAY_TRACE=1 \
node packages/codex-gateway/dist/cli.js
```

--------------------------------

### Cron Schedule Example

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/command-skills/auto.md

An example of a cron schedule for an automation job, set to run at 18:00 UTC on weekdays.

```json
{
  "kind": "cron",
  "expression": "0 18 * * 1-5",
  "timeZone": "UTC",
  "label": "cron 0 18 * * 1-5 UTC"
}
```

--------------------------------

### Load Dotenv File for Server Configuration

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-gateway/README.md

Run the internal Responses adapter server and load a dotenv-style configuration file.

```bash
node packages/codex-gateway/dist/cli.js --env-file /path/to/codex-gateway.env
```

--------------------------------

### Run Prompt-Driven Focused Code Review

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/usage/weixin-slash-commands.md

Use the /review custom <instructions> command to run a prompt-driven focused code review.

```text
/review custom 只审查测试目录里的改动
```

--------------------------------

### Recommended PR 1: Registry and Compatibility

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-provider-relay/docs/OPENAI_TOOL_PARITY_AND_PACKAGE_HARDENING_HANDOFF.md

First PR recommendation focusing on the builtin-tools registry, compatibility documentation, and hosted tool alias normalization.

```text
builtin-tools registry + compatibility docs + hosted tool alias normalization
```

--------------------------------

### Start Codex Native API Service

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/architecture/codex-native-api.md

Command to start the Codex Native API service using tsx and the CLI.

```bash
pnpm exec tsx src/cli.ts codex native-api-serve
```

--------------------------------

### Example: Classify New Reminder Record

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/command-skills/assistant-record.md

An example of classifying a new record as a 'reminder' with a specific title, content, and reminder time.

```json
{
  "schemaVersion": "codexbridge.assistant-record-command-skill.v1",
  "operation": "classify_new_record",
  "type": "reminder",
  "title": "提醒给王总回电话",
  "content": "2026-05-01 10:00 UTC 提醒给王总回电话。",
  "priority": "normal",
  "dueAt": null,
  "remindAt": "2026-05-01T10:00:00.000Z",
  "recurrence": null,
  "project": null,
  "tags": [],
  "confidence": 0.96
}
```

--------------------------------

### Run Internal Responses Adapter Server with Node

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-gateway/README.md

Build the package and run the internal Responses adapter server directly using Node.js.

```bash
node packages/codex-gateway/dist/cli.js
```

--------------------------------

### Example: Classify New Todo Record

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/command-skills/assistant-record.md

An example of classifying a new record as a 'todo' with a specific title, content, priority, and due date.

```json
{
  "schemaVersion": "codexbridge.assistant-record-command-skill.v1",
  "operation": "classify_new_record",
  "type": "todo",
  "title": "停机坪成本和报价测算",
  "content": "2026-04-30 UTC 必须完成停机坪的成本和报价测算。",
  "priority": "high",
  "dueAt": "2026-04-30T23:59:00.000Z",
  "remindAt": null,
  "recurrence": null,
  "project": null,
  "tags": [],
  "confidence": 0.95
}
```

--------------------------------

### Attachment Workflow with /up

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/usage/weixin-slash-commands.md

Initiate an attachment workflow by staging files with /up, then record them as an attachment to a specific record type using /as, /log, /todo, /remind, or /note.

```text
/up
```

```text
发送一个或多个文件、图片、语音、视频
```

```text
/as 把这些资料记录为合同附件 #合同
```

--------------------------------

### Dry Run Daemon Install

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-native-api/README.md

Installs the background daemon with a dry run, printing generated service files without making changes to the machine.

```bash
npx codex-native-api daemon install --port 4242 --dry-run
```

--------------------------------

### Run Internal Responses Adapter Server

Source: https://github.com/gan-xing/codexbridge/blob/main/packages/codex-gateway/README.md

Build the package and run the internal Responses adapter server using pnpm.

```bash
pnpm --dir packages/codex-gateway run serve
```

--------------------------------

### Local-Only Action Example

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/command-skills/review.md

Use 'local_only' when the request is asking for a command that Bridge handles directly. This example shows a JSON response marking the action as local_only.

```json
{
  "schemaVersion": "codexbridge.review-command-skill.v1",
  "ok": true,
  "action": "local_only",
  "confidence": 1,
  "requiresConfirmation": false,
  "reason": "This request should be handled by Bridge locally."
}
```

--------------------------------

### Display All Slash Commands

Source: https://github.com/gan-xing/codexbridge/blob/main/docs/usage/weixin-slash-commands.md

Use the /helps command to display a full catalog of available slash commands.

```text
/helps
```