grix-codex

grix-codex is a plugin that lets Grix dispatch Codex.

Grix is an AI orchestrator. It supports native protocol integrations with OpenClaw, Claude, Codex, Hermes, and other AI agents, plus group chat orchestration and private chat training.

What this plugin is for

Install grix-codex when you want to connect your local Codex to Grix and let Grix send project work to it directly.

It is useful when you want to:

• Use Codex as a dispatchable agent inside Grix
• Keep Codex working in a specific project directory
• Coordinate Codex with other agents in group chats
• Work with Codex one-on-one in private chats

Start in a few commands

Install it globally:

npm install -g @dhf-codex/grix

This package still installs the grix-codex command.

Start the local service:

grix-codex start

Connect it to your Grix agent:

grix-codex agent \
  --agent-id <your agent id> \
  --endpoint <your Grix endpoint> \
  --api-key <your key>

After that, you can start dispatching Codex from Grix.

What you can do with it

Once connected, you can:

• Send Codex into a chosen project and start work
• Check the current status at any time
• Stop the current session when needed

Common commands:

grix-codex status
grix-codex stop

If the code on disk has been rebuilt after the daemon started, grix-codex status --json will report restartRequired: true, and grix-codex start will replace the old daemon with the current build.

升级发布注意（Codex 工具栏能力）

每次升级代码后，必须执行 build + restart，不能只拉代码不重启：

npm run build
grix-codex restart --profile dev
grix-codex restart --profile prod

升级后验收分两步：

1. 校验最近一条 auth 报文能力声明

rg '"cmd":"auth"' ~/.grix-codex/dev/logs/agentapi-packets.jsonl | tail -n 1
rg '"cmd":"auth"' ~/.grix-codex/prod/logs/agentapi-packets.jsonl | tail -n 1

payload.local_actions 必须包含 get_context、set_model、set_mode。

2. 校验后端 runtime 能力快照

docker exec aibot-redis redis-cli --raw get im:agent_api:runtime:<agent_id>

返回 JSON 的 local_actions 必须包含 set_model、set_mode，否则 Codex 模型/模式按钮会保持禁用。

也可以直接用仓库脚本一键验收：

scripts/check_runtime_capabilities.sh dev <agent_id>
scripts/check_runtime_capabilities.sh prod <agent_id>

Runtime files

By default, the service stores its local state under ~/.grix-codex:

• service.json
• bindings.json
• service/daemon-service.out.log
• service/daemon-service.err.log
• logs/agentapi-packets.jsonl
• logs/bridges/<bridgeId>.jsonl
• logs/sessions/<sessionId>/conversation.jsonl

bindings.json keeps the session-to-workspace and session-to-thread binding so the service can reopen the same workspace and continue the same Codex session after a restart.

logs/agentapi-packets.jsonl keeps the raw Agent API transport packets that grix-codex agent sends and receives. It also records whether an outbound packet was sent immediately, buffered, or dropped before it could leave the local process.

logs/bridges/<bridgeId>.jsonl keeps the full raw Codex bridge traffic in time order:

• Messages sent to Codex
• Messages returned by Codex
• Child process stderr output
• Bridge lifecycle events

This bridge log is for diagnosis and replay, not a separate business protocol.

logs/sessions/<sessionId>/conversation.jsonl keeps only the session-facing conversation layer:

• Inbound chat content from Grix
• Outbound text replies sent back to Grix
• Final event_result status for each event